OS-9 Level 2 Development System

OS-9 Level 2 Development System
08-9 Level Two
Development System
OS-9 Level Two Software:
© 1987 Microware Systems Corporation.
Licensed to Tandy Corporation. All rights Reserved.
OS-9 Level Two Development System Software:
© 1987 Tandy Corporation.
All righ15 Reserved.
OS-9 Level Two Development System Documentation:
Interactive Debugger, Screen Editor, Relocating Macro Assembler, Utilities, Commands
© 1987 Tandy Corporation.
All righ Is Reserved.
Reproduction or use of any portion of this manual without eJ<press wrillen permission
from Tandy Corporation is prohibited. While reasonable efforts have been taken in the
preparation of this manuals to assure its accuracy, Tandy Corporation assumes no
liability resulting from any errors in or omissions from this manuals, or from the use of
the information contained herein,
Tandy and the Tandy logo are registered trademarks of Tandy Corporation.
Motorola is a registered trademark of Motorola Inc.
10 9 8 7 6 5 4 3 2
Contents
This manual contains documents for:
•
Interactive Debugger
A program to aid in diagnosing system programs, testing machine
language programs and to gain access to your computer's
memory.
•
Screen Editor
A screen-oriented text editor for preparing letters, documents, and
for writing OS-9 programs.
•
Relocating Macro Assembler
A full-featured macro assembler and linkage editor.
•
Utilities
Three utility programs: Make, to help maintain current version
software; Touch, to update files; and VDD, a Virtual Disk
DriverfRAM Disk Driver to create a high-speed storage in your
systems RAM.
•
Commands
Twelve additional OS-9 commands to expand your system's
capabilities.
Each document contains its own table of contents.
TERMS AND CONDITIONS OF SALE AND ",CENSE OF TANDY COMPUTER EQUIPMENT ANO
SOFTWARE PURCHASED FROM RADIO SHACK COMPANY·OWNEO COMPUTER CENTERS, RETAIL
STORES AND RADIO SHACK FRANCHISEES OR DEALERS ATTHEIR AUTHORIZED LOCATIONS
USA LIMITED WARRANTY
I.
CUSTOMER OBliGATIONS
A CUSTOMER assumes full responSibility that Ih,s oomputer l\ardware purchased (the Equipment 'j, and any
copies of software inCluded whh the Equipment or licensed separately Ithe "Software") meets the speCifications.
capaCity, capabilities, versatility. and other reqUirements of CUSTOMER.
CUSTOMER assumes full rllsponslb,lily tor tho condition and .Hoc!lYllness of th. operating en'lronmenl In which
the Equipment and Software are to function, and for Its Installation.
LIMITED WARRANTIES AND CONDITIONS OF SALE
A. For a pellod 01 ninety (90) calendar days from the date of Ihe RadiO Shack sales documenl received upon
purchase of the EqUipment RADI D SHACK warranls 10 Ihe ollglnal CUSTOMER Ihal Ihe Equipmenl and the
medIUm upon which the Sonware IS stored IS freo lrom manufacturing defects Thl$ .emnly II only eppllcable
to purchases of Ta"" Equipment by lbe .,Iglnal curtDmar from Radl. Shack company·o_d compuler
clntars, retail aI.rn, and Radio Shack trln.hlllel and dialers at lhelr luthorlzed lo.atlcns. The warran1jl IS
VOid d the EqUl~ment or Software has been subjected to Improper or abnormal use U a manuiactunng d&il:'C1 is
discoyered dUllng Ihe slaled warranty penod the do1eC!lye EqUlpmenl musl be refumed to a RadiO Shack
Computer Center. a RadiO Shack retail store. a partlapa1ln9 RadiO Shack franchISee or a participating Radio Shack
dealer fOr repair, alon~ With a copy of lhe sales documem or lease agreement. Tho original CUSTOM ER S sole and
exclUSive remedy in the event nf a deiect Is limited to the correction o1lhe defecl by rep'If. replacement, or
retund 01 the purchase Pllce, at RADIO SHACK'S election and soie expense. RADIO SHACK has no obligation to
replace or repaH expendabl!! Items.
B. RADIO SHACK makes no warranty as 10 the deSign, capaOlllty. cap,acltv. or sUltaOllitY for use 01 the Schware.
except as prOVided In this ,paragraph Software IS Ifcensed on an 'AS II;" basis, without warra.nty The onginal
CUSTOMER'S exclusNe remedy. In lhe eyent of a Sohware manufactullng defect, is Its repair or replacement
Within Ihlrty (3D) calendar days of the date of the RadiO ShaCK sales document recelvnd upon I,eonse of the
Soltware The det,cliv, Software shall be return,d 10 a RadiO Shack CompUl,r Center. a RadiO Shack relall S10re.
a par!lcipaling RadiO Shack tranchlsee or RadIO Shack dealer alcng wilh the sales document.
C. Except as provided herein no employee, agent, franch,sea, dealer Or other person IS authollzed to giV€ any
warranties of any natu re on behalf of RADIO SHACK
D EXCEPT AS PROVIDED HEREIN. RADIO SH~C. MAKES NO EXPRESS WARRANTIES, AND ANY IMPliED
WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE IS LIMITED IN ITS DURATION
TO THE DURATION OF THE WRlnEN LIMITED WARRANTIES SET FORTH HEREIN.
Some states do not allow Ilmllations o~ how long an Implied warranty lasts. so Ihl! aMve Ilmltat,On!s) may not
apply 10 CUSTOMER
III. LIMITATION OF LIABILITY
A EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY TO GUSTOMER
OR ANY OTHER PERSON DR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS DR DAMADE CAUSED DR
AlLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY "EOUIPMENT" OR "SOFTWARE" SOLO, LEASED,
LICENSED OR FURNISHED BY RADIO SHACK, INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF
SERVICE, LOSS DF BUSINESS OR ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM
THE USE OR OPERATION OF THE "EQUIPMENT" DR "SOFTWARE." IN NO EVENT SHALL RADIO SHACK BE
LIABLE FOR ~S OF PROFITS, OR ANY INDIRECT, SPECIAL, OR CONSEDUENTIAL DAMAGES ARISING OUT OF
ANY BREACH OF THIS WARRANTY DR IN ANY MANNER ARISING OUT OF OR CONNECTED WITH THE SALE,
LfASE, LICENSE, USE OR ANTICIMTED USE OF THE "EQUIPMENT" OR "SOnw~RE. "
NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK'S LIABILITY HEREUNDER FOR
DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEeD THE AMOUNT PAID BY CUSTOMER RlR
THE PARnCULAR "EOUIPMENT" DR "SDnwARE" INVOLVED.
RAOIQ SHACK shall nol be liable for any damages caused by delay .n deliv8nng or furnishing Equipment andlOr
Software
No aCllon arlsmg oul of any clalrned breach of thiS Warranty or transactions undel Ihls Warranty may be Oroug~t
more lhan two (2) years atler the cause ot action has accrued or more than tour (4) years after t~e ~ale of the
RadiO Shack sales document for the Equipmenl or Software, whicheyar first occurs.
Some Slates do not allow the I,mltal,on or exclusion of inCidental or conseQuential damages. so the above
limllationls} Dr .xclusion(s) may no1 apply to CUSTOMER
IV SDFlWARE LICENSE
RADIO SHACK grams to CUSTOMER a non-exclusive. pald-uo lICense to use lhe TANDY Software Dn one cornpuler.
subl'ct 10 the followln~ provisions
A. Except as ottlerwlse proVlded In thIS Software License. applICable copyllghllaws shall apply to the Sohwsre
B TItle 10 the medIUm on which Ihe Software 15 recorded Icassene and!or dlsKeNel or .'ored (ROM) 15 translerred 10
CUSTOMER. bUI not title to the Software
C. CUSTOMER may use Software on a multi" ,er or networ< system only If .,ther Ihe Software IS ""press y labeled
te be for use on a multiuser or network system. or one copy of th,s software s purchased tor each node or
o
o
terminal on which Software
IS
to be used sim lJltaneolJs'Y
CUSTOMER shall not use make manufacture, or reproduce copies 01 Software excepl for use on on8 computer
In thiS Sottwaf6 LJc~n5e Customer IS ex.~res5Iy prohlblted from dlsaSsembl!ng the
Software
CUSTOMER is permitted to make addlllonal copies of the Software only lor back,p or arcooval purposes or it
and as 15 speCifically proVided
addi1i(lnal copies are reQUired In the operation of DIUI computer wnh the Software, bUl only to the extent the
Software allows a beckup copy 10 be made. However. for TRSDOS Saftware. CUSTOMER IS p"mlll.d to maKe a
limited numO~r af additional OOPIeS tor CUSTOMER'S own use
CUSTOMER may resell er distribute unmodified OOPieS 01 the Software prOVided CUSTOMER has purooased one
copy of the Software tor each ene sold or dIstrtb"ted ne provisions oj this Software ucense shal also be
applicable to Ihlrd parties rec.,vlOg COPieS af the Software from CUSTOMER.
All copyrtght rloIic.s shall be relained DO all COpieS 01 the Software.
APPLICABILITY Of WARRANTY
A The terms aM condrtmns of thiS Warranty are eppllcaOle as between RADIO SHACK an~ CUSTOMER to either a
sale 01 the EQuipment and'or Software License 10 CUSTOMER or 10 a lransact,on whereby Radio Shack sells or
COnyeys such EQui~menlto a third party for lease to CUSTOMER
The limitations of 118bJlil)' and Warranty proVISions ht!reln sha,1 Jnur~ to the benetlt 01 RADIO SHACK, the author
owner and or licensor of the Software and any manufaG1urer of the Equipment sold by Radio Shack
VI. STATE LAW RIGHTS
The warran!les granted herein 9'.8 Ih, original CUSTOMER speCifIC leg,1 lights. and the ~'lgln.1 CUSTOMER m.y
haw other rights which vary tram slate to stale
4187
Interactive Debugger
Contents
------------------------
Chapter 1/ Introduction
,
Calling Debug
Basic Concepts
Chapter 2 / Expressions
Constants
Special Names
Register Names
Operators
Forming Expressions
Indirect Addressing
Chapter 3/ Debug Commands
Calculator Commands .,
Dot and Memory Examine/Change Commands
Incrementing Dot
Decrementing Dot
Changing Dot
Changing Dot's Contents
Register Examine/Change Command
Breakpoint Commands
Setting Breakpoints
Removing Breakpoints
Program Setup and Run Commands
Goto Command
Link Command
1-1
1-1
1-1
2-1
2-1
2-2
2-3
2-3
2-4
2-4
3-1
3-1
3-2
3-3
3-3
3-3
3-4
3-5
3-7
3-8
3-8
3-9
3-10
3-10
Interactive Debugger
Utility Commands
Clearing Memory
Displaying Memory
Searching Memory
Shell Command
Quitting Debug
Contents
3-11
3-11
3-12
3-12
3-12
3-13
Chapter 4 / Using Debug
Sample Program
U sing Debug
Patching Programs
Patching OS-9 Component Modules
4-1
4-1
4-4
4-7
4-8
Chapter 5 I Debug Command Summary
and Error Codes
Debug Command Summary
Dot Commands
Register Commands
Program Setup and Run Commands
Breakpoint Commands
Utility Commands
Debug Error Codes
5-1
5-1
5-1
5-2
5-2
5-2
5-3
5-3
Chapter 1
Introduction
Debug is an interactive debugger that aids in diagnosing system
programs and testing machine-language programs for the 6809 microprocessor. You can also use it to gain direct access to the computer's
memory. Debug's calculator mode can simplify address computation,
radix conversion, and other mathematical problems.
Calling Debug
To run Debug, type the following command at the OS-9
prompt:
sy~tem
DEBUG [ENTER]
Basic Concepts
Debug responds to I-line commands entered from the keyboard. The
screen shows the DB: prompt when Debug expects a command.
Terminate each line by pressing [ENTER]. Correct a typing error by
using the backspace (... ) key, or delete the entire line by pressing X
while pressing [CLEAR].
1-1
Interactive Debugger
Introduction /1
Each command starts with a single character, which you can follow
with text or one or two arithmetic expressions, depending on the
command. You can use upper- or lowercase letters or a mixture.
When you use the spacebar to insert a space before a specific
expression, the screen shows the results in hexadecimal and decimal
notation. For example, in the calculator mode, to obtain the
hexadecimal and decimal notation for the hexadecimal expression
A+2, type:
(SPACEBAR][A][+][2]
Debug displays:
DB: A+2
$OOOC #00012
1·2
Chapter 2
Expressions
Debug's integral expression interpreter lets you type simple or
complex expressions wherever a command calls for an input value.
Debug expressions are slmilar to those used with high-level languages
such as BASIC, except that some extra operators and operands are
unique to Debug.
Numbers in expressions are 16-bit unsigned integers--the 6809'5
native arithmetic representation. The allowable range of numbers is 0
to 65535. Debug performs two's complement addition and subtraction
correctly. but displays all results as positive numbers in decimal form.
Some commands require byte values. The screen shows an error
message if the result of an expression is too large to be stored in a
byte; that is, if the result is greater than 255. Some operands, such as
individual memory locations and some registers, are only one byte
long, and Debug automatically converts them to 16-bit words without
sign extension.
Spaces, other than a space at the beginning of a command, do not
affect evaluation of the expression. Use them as necessary between
operators and operands to improve readability.
Constants
Constants can be in base 2 (binary), base 10 (decimal), or base 16
(hexadecimal). Binary constants require the prefix %. Decimal
constants require the prefix #. Debug assumes all other numbers to be
hexadecimal. They can have the optional prefix $. The following table
shows examples of each type of constant:
2-1
Interactive Debugger
Expressions 12
Hexadecimal
Binary
#100
64
#255
#6000
FF
1770
#65535
FFFF
%1100100
%11111111
%1011101110000
%1111111111111111
Decimal
You can use character constants. Use a single quotation mark (') for 1character constants and a double quotation mark (") for 2-character
constants. Quotation marks produce the numerical value of the ASCII
codes for the character(s) that follow. For example:
'A
'0
"AB
"99
$0041
$0030
$4142
$3939
Special Names
Dot (.) refers to Debug's current working address in memory. You can
examine it, change it, update it, use it in expressions, and recall it. Dot
eliminates a tremendous amount of memory address typing.
Dot-Dot C.. ) is the value of Dot before the last time it was changed. Use
Dot-Dot to restore Dot from an incorrect value, or use it as a second
memory address.
2-2
Interactive Debugger
Expressions / 2
Register Names
Specify the MPU registers with a colon (:) followed by the mnemonic
name of the register, as follows:
:A
:B
:D
:X
:Y
:U
:DP
:SP
:PC
;;;,
:CC
Accumulator A
Accumulator B
Accumulator D
X Register
Y Register
U Register
Direct Page Register
Stack Pointer
Program Counter
Condition Codes Register
The values returned are the test program's registers, which are stacked
when Debug is active. Debug increases I-byte registers to a word
when used in expressions.
Note: When a break point interrupts a program, the SP
register points at the bottom of the MPU register stack.
Operators
Operators specify arithmetic or logical operations to be performed
within an expression. Debug executes operators in the following
order:
& and!
* and I
+ and-
(negative numbers)
(logical AND and OR)
(multiplication and division)
(addition and subtraction)
Operators that are in a single expression and that have equal
precedence (for example, + and -) are evaluated left to right. You can
use parentheses, however, to override precedence.
2-3
Interactive Debugger
Expressions I 2
Forming Expressions
An expression is composed of any combination of constants, regi!\ter
names, special names, and operators. The following are valid
expressions;
#1024+#128
:X-:Y-2
.+20
:y*(:X+:A)
:U & FFFE
Indirect Addressing
Indirect addressing returns the data at the memory address, using a
value (expression, constant, special name, and so on) as the memory
address. The two Debug indirect addressing modes are:
<expression>
returns the value of a memory byte using
expression as an address
[expression]
returns the value of a 16-bit word using
expression as an address.
For example:
<200:>
returns the value of the byte at Address 200
[:X]
returns the value of the word pointed to by
Register X
[.+10]
returns the word value at Address Dot plus 10
2-4
Chapter 3
Debug Commands
This chapter describes Debug's available commands. Following the
description for each command, there is an example. The left side of
the example shows what you type, and the Tight side shows what the
screen displays. Be sure to execute these examples in the order they
appear so you obtain the screen display shown. Many of the examples'
results depend on examples previously executed. Also, remember to
press [ENTER) after each command.
Calculator Commands
The [SPACEBAR] expression command evaluates the specified
expression and displays the result in both hexadecimal and decimal.
For example:
You Type:
The Screen Shows:
[SPACEBAR]5000+200[ENTER)
$5200 #20992
[SPACEBA R]6BOO/2[ENTE R]
$4400 #17408
[SPACEBAR]#1 OO+#12[ENTE R]
$0070 #00112
You can also use this command to convert values from one
representation to another. For example:
You Type:
The Screen Shows:
[SPACEBAR]%11110000[ENTER]
$OOFO #00240
[SPACEBAAI'A[ENTERI
$0041 #00065
[SPACEBAR]#100[ENTER]
$0064 #00100
[SPACEBA R].[E NTER]
$0000 #00000
- - - - - -
3-1
._-------
-----
Interactive Debugger
Debug Commands / 3
The examples show: (1) a conversion from binary to both hexadecimal
and decimal, (2) a character constant conversion to hexadecimal and
decimal ASCII, and (3) a decimal to hexadecimal conversion. The last
example used indirect addressing to examine memory without
changing Dot's value.
In addition, you can use indirect addressing to simulate 6809 indexed
or indexed indirect instructions. The following example is the same as
the assembly-language syntax [C,Y]:
You Type:
The Screen Shows:
(SPACE BAR][: D.:Y][ENTER]
$0110
·00272
Dot and Memory
Examine/Change Commands
You can display the current value of Dot (the current memory
address), using the DOT command. For example:
You Type:
The Screen Shows:
2201
eo
This shows that the present value of Dot is 2201. That memory address
contains the value BO.
Incrementing Dot
You can use [ENTER] to increment the value of Dot and display its new
value and contents:
You Type:
The Screen Shows:
[ENTER]
220205
[ENTER]
2203 C2
[ENTER]
220482
3-2
Debug Commands /3
Interactive Debugger
Decrementing Dot
Use the minus (-) key to decrement the value of Dot. As when you use
the [ENTER] key, Debug displays both the new value and the contents
of that address:
You Type:
The Screen Shows:
.[ENTER]
220482
-[ENTER]
2203 C2
-[ENTER]
220205
Changing Dot
You can enter an expression after the DOT command to change the
value of Dot:
Debug evaluates the expression, and sets Dot to that value. For
example:
You Type:
The Screen Shows:
. 500[ENTER]
050012
Debug displays the new value of Dot and its contents.
The DOT-DOT command (.•) command restores Dot to its previous
value:
You Type:
The Screen Shows:
.[ENTER]
050012
• 2000[ENTER]
2000 9C
..[ENTERI
050012
3·3
Interactive Debugger
Debug Commands /3
----------------------------
Changing Dot's Contents
You can change the contents of Dot with the EQUAL (=) command:
= expression
Debug evaluates expression, and stores the result at Dot. Debug then
increments Dot and displays the next address and its contents.
The EQUAL command also checks Dot, after the new value is stored,
to see that it changed to the correct value. If it did not, the screen
shows an error message. This happens when you attempt to alter nonRAM memory. In particular, the registers of many 6800-family
interface devices (such as PIAs and AelAs) do not read the same as
when written to.
For example:
You Type:
The Screen Shows:
.[ENTER]
2203 C2
=FF[ENTER]
220401
-{ENTER]
2203 FF
Note: The EQUAL command can change any memory
location. Be careful when changing addresses so that you do
not accidentally alter the Debug program, the program being
tested, or 05-9.
----. - - - - - - - -
3-4
Interactive Debugger
Debug Commands f 3
Register Examine/Change Command
You can use any of several fonns of the colon (:) REGISTER
command to examine one or all registers or to change a specific
register's contents.
The registers affected by these commands are actually images of the
register values of the program under test. These values are stored on a
stack when the program is not running, Although a dummy stack is
established automatically when you start Debug, use the E command
to give the register images valid data before using the G command to
run the program. The registers are valid after breakpoints are
encountered and are passed back to the program upon the next G
command. (See the "Program Setup" and "GOTO Command" sections
later in this chapter for information on the E and G commands.)
Note: If you change the SP register, you move your stack and
change register contents. In addition, Bit 7 of Register CC
(the E flag) must always be set for the G command to work. If
it is not set. Debug does not return to the program correctly.
This form of the REGISTER command displays the contents of a
specific register:
: register
Omitting register causes Debug to displays all register contents:
You Type:
The Screen Shows:
:PC[ENTER]
C499
:B[ENTER]
007E
:SP[ENTER]
42FD
:[ENTER]
PC=B265 A=Ol 8=OB CC"BO
DP=OC
SP=OCF4 X=FFOD Y=OOQB
U=OOAE
3-5
Debug Commands / 3
Interactive Debugger
Use the following form of the REGISTER command to assign a new
value to a register
:register expression
Debug evaluates the expression, and stores the result in the specified
register. If you specify 8-bit registers, the expression value must fit in
one byte. Otherwise, Debug displays an error message and does not
change the value of the register. Here is an example of this command:
You Type:
The Screen Shows:
:X #4096
:X #4096
Breakpoint Commands
The breakpoint capabilities of Debug let you specify addresses at
which you want to suspend execution of the program under test and
reenter Debug. When you encounter a breakpoint, the screen shows
the values of the :MPU registers and the DB: prompt. After the program
reaches a breakpoint, you can examine or change registers, alter
memory, and resume program execution. You can insert breakpoints
at as many as 12 addresses.
The inserted breakpoints use the 6809 SWI instruction, which
interrupts the program and saves its complete state on the stack.
Debug automatically inserts and removes SWI instructions at the right
times; so you do not see them in memory.
3·6
Interactive Debugger
Debug Commands /3
Because SWIs operate by temporarily replacing an instruction OP
code, there are three restrictions on their use:
•
You cannot use breakpoints in programs in ROM.
•
You must position breakpoints at the first byte (OP code) of the
instruction.
•
You cannot use the SWI instruction in user programs for other
purposes. (You can use SWI2 and SWI3.)
When you encounter the breakpoint during execution of the program
under test, reenter Debug by typing: register [ENTER], where register
is a mnemonic as discussed in Chapter 2. The screen shows the
program's register contents.
Setting Breakpoints
Use the BREAKPOINT (B) command to insert breakpoints:
B expression
Debug evaluates the expression, and sets the breakpoint at that address. If you omit expression, Debug displays all present breakpoint
addresses. Note in the following examples that the B . command sets a
breakpoint at the address of Dot.
You Type:
The Screen Shows:
B 1COO[ENTER)
B lCOO
B 4FD3[ENTER]
B 4FD3
.[ENTER]
127739
B .[ENTER]
B.
B[ENTER]
1COO 4FD3 1277
3·7
Interactive Debugger
Debug Commands /3
Removing Breakpoints
Use the KILL (K) command to remove breakpoints:
K expression
Debug evaluates expression for the address at which to remove the
breakpoint. Omitting expression causes Debug to remove all breakpoints. For example:
You Type:
The Screen Shows:
8[ENTER)
1COO 4FD3 1277
K 4FD3[ENTER]
B[ENTER)
1COO 1277
K[ENTER)
B[ENTER]
Program Setup and Run Commands
The ESTABLISH (E) command prepares Debug for testing a specific
program module:
E module-name
This command's function is similar to that of the 05-9 Shell in starting
a program. The E command does not, however, redirect I/O or override
(#) memory size. The E command sets up a stack, parameters, registers, and data memory area in preparation for executing the program
to be tested. The G command starts the program.
Note: The E command allocates program and data area
memory as appropriate. The new program uses Debug's
current standard 110 paths, but can open other paths as
necessary. In effect, Debug and the program become coroutines.
3-8
Interactive Debugger
Debug Commands! 3
The E command is acknowledged by a register dump showing the
program's initial register values. The G command begins program
execution. The E command sets up the MPU registers as if you had
just performed an F$CHAIN service request as shown in the following
table:
DP,U
low
direct page
data area
parameter area
x,s
D
=
high
parameter area size
module entry point absolute address
CC = (F=O) , (1=0)
interrupts disabled
PC
=
For example:
You Type:
E myprog
The Screen Shows:
SP CC A
X
Y
B OP
PC
OCF3 C800 01 OC
OCFF 0000 9214
GOTO Command
To start (or resume) program execution, use the G command. The G
command goes to (resumes) program execution after a breakpoint. If a
breakpoint exists at the present program counter address, Debug does
not insert that breakpoint. If you wish to suspend execution during
each pass in a loop, you must insert two breakpoints in that loop.
3·9
Debug Commands J 3
Interactive Debugger
Note: Usually you use the E command before the first G
command to set up the program to be tested. Debug initially
sets up a default stack, so you can use G expression to start a
program, using the results of the expression as a starting
address.
Examples:
DB: G 4COO[ENTER]
DB: G :PC+l00[ENTER]
DB: G [.][ENTER]
LINK Command
The LINK (L) command sets a link to the specified module:
L module-name
If successful, LINK sets Dot to the address of the first byte of the
program and displays it.
You can use L to find the starting address of an OS-9 memory module.
For example:
You Type:
The Screen Shows:
L FPMATH [ENTER]
COCOS7
You can also use the LINK command to reset Dot to the first byte of a
module:
You Type:
The Screen Shows;
L FPMATH [ENTER]
. .+A10 [ENTER]
L FPMATH [ENTER]
COCO 87
CA10 FF
COOO 87
3·10
Interactive Debugger
Debug Commands I 3
Utility Commands
Clearing Memory
The CLEAR MEMORY (C) command perfonns a walking bit memory
test and clears all memory between the two evaluated expressions:
C expression 1 expression2
Expression] specifies the starting address and expression2 specifies
the ending address, which must be higher. If any byte fails the test, the
C command displays its address. You can test and clear random access
memory only.
Note: Use this command carefully. Be sure of the memory
address you are clearing.
Some examples of this command are:
You Type:
The Screen Shows:
C ..+FF[ENTERI
C 15FF 2000[ENTERI
17E4
17E7
The first example clears all memory between the last value of Dot and
Dot plus FF. Because Debug displayed a blank line (nothing), all
memory tested good.
The second example indicates that there is bad memory at addresses
17£4 and 17E7.
3-11
Interactive Debugger
Debug Commands /3
Displaying Memory
The MEMORY command produces a screen-sized tabular display of
the contents of memory in both hexadecimal and ASCII form:
M expression 1 expression2
Expression] specifies the starting address. Expression2 specifies the
ending address, which must be higher.
Each line's starting address displays on the left, followed by the
contents of the subsequent memory locations. On the far right, Debug
displays the ASCII representation of the same memory locations.
Debug substitutes periods (.) for nondisplayable characters.
Searching Memory
The SEARCH command searches an area of memory for a 1- or 2-byte
pattern, beginning at Dot.
S expression1 expression2
Expression] specifies the ending address. Expression2 is the data for
which to search. If expression2 is less than 256. Debug uses a I-byte
comparison. If it is greater than 256, Debug uses a 2-byte comparison.
If Debug finds a match, it sets Dot to the address at which the match
occurred. If Debug does not find a match, it displays the DB; prompt.
Shell Command
To call the 05-9 shell from within Debug, use the $ command:
$ shell-command
This command executes the specified shell-command and returns to
Debug. If you omit the shell-command, Debug calls the OS-9 Shell,
which responds with prompts for one or more command lines.
3-12
Debug Comnumds I 3
Interactive Debugger
You can also use the $ command to call the system utility programs
and the assembler from within Debug. For example:
$DIR[ENTER]
displays the current directory.
Quitting Debug
The QUIT command lets you exit Debug and return to the OS-9 Shell.
To exit Debug, type:
Q [ENTER]
The system returns you to 08-9.
Note: Any modules you load using $load
any modules you link using L module-name,
memory. See the UNLINK command in the
Operating System manual for information
modules from memory.
3-13
module-lUlme,or
remain linked in
05-9 Level Two
about unlinking
Chapter 4
Using Debug
You use Debug primarily to test system memory and I/O devices. to
patch the operating system or other programs, and to test handwritten or compiler-generated programs.
Sampie Program
The simple assembly-language program shown here illustrates the use
of Debug commands. This program prints HELLO WORLD and then
waits for a line of input.
NAM EXAMPLE
• Useful Numbers
PRGRM equ $10
OBJeT equ $01
STK
equ 200
• Data Section
csect
LIN LEN RMB 2 LINE LENGTH
INPBUF RMB 80 LINE INPUT BUFFER
endsect
4-1
Interactive Debugger
Using Debug / 4
• Program Section
pseet example,PRGRM+OBJCT,$81 ,O,STK,ENTRY
ENTRY EOU· MODULE ENTRY POINT
LEAX OUTSTR,PCR OUTPUT STRING ADDRESS
LDY #STRLEN GET STRING LENGTH
LDA #1 STANDARD OUTPUT PATH
059 I$WritLn WRITE THE LINE
BCS ERROR BRA IF ANY ERRORS
LEAX INPBUF,U ADDRESS OF INPUT BUFFER
LOY #80 MAX OF 80 CHARACTERS
LDA #0 STANDARD INPUT PATH
os9 I$ReadLn READ THE LINE
BCS ERROR BRA IF ANY 110 ERRORS
STY L1NLEN SAVE THE LINE LENGTH
LOB #0 RETURN WITH NO ERRORS
ERROR os9 F$Exit TERMINATE THE PROCESS
OUTSTR FCC IHELLO WORLDI OUTPUT STRING
FCB $00 END OF LINE CHARACTER
STRLEN EaU ·~OUTSTR STRING LENGTH
endsect End of PSect
Following is the listing (RMA output) for the Example program:
Microware OS-9 RMA - V1.1 87/03/16 17:33 example.a
EXAMPLE -
Page
00001
NAM EXAMPLE
00002
00003· Useful Numbers
000040010
PRGRM equ $10
000050001
00006 00c8
00007
00008 • Data Section
OBJeT
STK
000090000
000100000
csect
UNLEN RMB 2
INPBUF RMB 80
00011 0002
000120052
equ
equ
$01
200
line length
line input buffer
endsect
00013
00014· Program Section
00015
00016
psect example,PRGRM+OBJCT,$81 ,O,STK,ENTRY
4·2
Interactive Debugger
00017 0000
Using Debug 14
EQU
LEAX
LOY
LOA
ENTRY
000180000308d0020
000190004108eOOOc
0002000088601
00021 000a=103100
00022 OOOd 2512
00023 oOof 3042
00024 0011 108e0050
0002500158600
000260017=103fOO
00027 001 a 2505
00028001 c 109100
000290011 c600
o00300021=103fOO
ERROR
00031
000320024 48454c4c OUTSTR
00033 o02f ad
00034000C
STRLEN
00035
000360030
059
BCS
LEAX
LOY
LOA
os9
BCS
STY
LOB
os9
•
module entry point
OUTSTR,PCR output string address
get siring length
#STRLEN
standard output path
#1
write the line
I$WritLn
BRA if any errors
ERROR
INPBUF,U
address of input butler
max 01 80 characters
#80
standard input path
#0
read the line
I$ReadLn
BRA if any 110 errors
ERROR
L1NLEN
save the line length
#0
return with no errors
F$ Ex it
terminate the process
FCC IHELLO WORLDI OUTPUT STRING
FeB $00
end-aI-line character
EQU ·-OUTSTR
string length
endsect
End 01
PSect
Following is the linkage map (Rlink output) for the Example program:
Linkage map for example File· IhO/CMD5/coior/exampie
Section
Code IDat UDat IOpD UDpD File
example
dpsiz
end
edata
btext
etext
os9defs_8
I$ReadLn
I$WritLn
F$Exit
00150000
udpd 0000
udal 0000
Idat 0000
0000 00 00 RELSlexample.r
code 0000
code 0045
00450000 0000 00 OO ..IUB/sys.1
enst 008b
enst OOSe
enst 0006
00300000 0000 00 00
4-3
Interactive Debugger
Using Debug 14
Note: This Psect Example has a value of $15, which is the
offset from the beginning of the final module.
Following is the display created by using OS-9'f; DUMP command on
the Example module:
OS9:dump IdO/cmds/example
Addr 0
1 2
3 4
0000 87CO 0058
0010 6070 6CES
0020 3F8C 2512
0030 0510 9FOO
0040 4F52 4C44
0050 6D70 6C65
5 6
0000
0030
3042
C600
0000
0091
7 8
9 ABC 0 E F
11Cl 3000 1500 COOS
8000 2010 BEOO 0C86
l06E 0050 6600 103F
103F 0648 454C 4C4F
0000 0000 0000 0065
A4B8
a 2 4 6 8 ACE
7861 .M.X...AO Hexa
0110
8825
2057
7861
mple.O
.
?%.OB P ?%
.... F.. ?HELLO W
ORLD......... exa
mple.. $8
Using Debug
Following is a sample session using the 05-9 Interactive Debugger:
First, run Debug by typing:
debug [ENTER]
The screen displays the Debug prompt DB:. To load the Example
program module. type:
$Ioad example rENTER]
The dollar sign ($) tells Debug that you want to use an 05-9 system
command and LOAD reads the example module from the current
directory to your computer's memory.
You now need to tell Debug what module you want to use. Do so with
the L (LINK) command. Type:
1 example [ENTERI
4-4
Interactive Debugger
Using Debug f 4
Debug links to Example and displays the module's address:
COGO 87
Redisplay the current address and its value using the DOT command.
Type:
. [ENTER]
The screen shows:
COOO 87
To display the contents of the entire module, use the M (display
memory) command. Type:
m ..+57 [ENTER)
The screen displays:
COOO
COlO
C020
C030
CQ40
COSO
87eD
6D70
3F8C
0510
4F52
6D70
0058 0000 11C1 3000 1500 cass 7861 ...X....O exa
6CES 0030 aDOO 2010 8Eoo OCB601'0 mpl ..O
.
2512 3042 lOBE 0050 8600 103F 8825 ?%.OB P ?%
9FOO C600 103F 0648 4S4C 4C4F 2057
?HELLO W
4C44 0000 0000 0000 0000 0065 7861 ORLD
exa
GeGS 0091 MB8 0000 FFFF 0000 0276 mple
v
Note: Psect of example program starts at an offset of $15
from the beginning linked module.
Prepare to run the Example program by typing:
e example [ENTER]
The screen displays the program's initial register values:
SP
2F3
CC
A8
A
00
B
01
OP
02
X
Y
U
02FF 0300 0200
To set a breakpoint at BCS ERROR, type:
b .+21 [ENTER]
4-5
PC
CQ1S
Interactive Debugger
Using Debug I 4
Then, display the breakpoint by typing:
b [ENTER]
The screen displays:
C02F
To run the program, type:
9 [ENTER]
The module displays HELLO WORLD. To complete the program. type a
message and press [ENTER], such as:
hello computer
Debug now encounters the breakpoint and displays the current
register values:
BKPT:
SP
02F3
CC
AO
A
00
8
01
DP
02
X
Y
U
PC
0202 OOOF 0200 C02F
You can display the module's data area by typing:
m :u :u+20 [ENTER]
The screen displays:
0200 0109 6865 6C6C 6F20 636F 6070 7574 6572 .. hello computer
0210 0086 A6A4 847F 8006 A6AO 2AF6 8620 3410
: .. 4.
0220 9EOl A780 9F01 3590 3432 8600 SOFO 3040
5.42 0M
Display the relative data area at offset 2 by typing:
:u+2 [ENTER]
4-6
Interactive Debugger
Using Debug / 4
To step through the data area, press the [ENTER] one or more times.
The screen displays the addresses and address values, such as:
020268
020365
02046C
02056C
02066F
To end the Debug session, type:
q [ENTER]
The OS9: prompt reappears on the screen.
Patching Programs
To patch a program (to change its object code), follow these steps:
1.
Load the program into memory, using OS-9's LOAD command.
2.
Use Debug's LINK, DOT, and EQUAL commands to link to and
change the program in memory.
3.
Save the new, patched version of the program on a disk file, using
OS-9's SAVE command.
4.
Update the program module's CRC check value, using OS-9's
VERIFY command. Be sure to use the U option.
5.
Set the module's execute status, using OS-9's ATTR command.
Step 4 is essential because 05-9 cannot load the patched program into
memory until the program's eRC check value is updated and correct.
4-7
Interactive Debugger
Using Debug! 4
The example that follows shows how the sample program is patched.
In this case, the Idy #80 instruction is changed to Idy #32.
059: debug
Interactive Debugger
DB: $load example
DB: I example
2000 87
DB: .. +29
2029 50
DB: =#32
202A 86
DB: 2029 20
DB: q
059: save temp example
059: verify U temp newex
059: aUr newex e pe
059: del temp
call Debug
call OS-9 to load the program
set dot to beg addr of program
actual address will vary
add offset of byte to change
current value is 00
change to decimal 32
next byte displayed
back up 1 byte
(change confirmed)
exit Debug
save infile called "temp"
update eRe and copy to "newex"
set execution status
delete temporary file
Patching 08-9 Component Modules
Patching modules that are part of 05-9 (are contained in the OS-9
Boot file) is different than patching a regular program because you
must use the COBBLER and OS9GEN programs to create a new OS~9
Boot file. This example shows how an 05-9 device descriptor module
is permanently patched, in this case to change the uppercase lock of
the device /TERM from on to off. This example assumes that a blank.
freshly formatted diskette is in Drive 1 (ID I).
Note: Always use a copy of your OS-9 System Disk when
patching, in case something goes wrong.
4-8
Using Debug I 4
Interactive Debugger
OS9: debug
Interactive Debugger
DB: I term
CA8287
DB: .. +13
call Debug
set dot to addr of TERM module
actual address will vary
add offset of byte to change
DB: =0
current value os 01
change value to 00 for "OFF"
CA96 01
DB:·
move back one byte
CA95 01
CA9S 00
change confirmed
DB; q
exit Debug
OS9: COBBLER 101
write new bootfile on /Dl
059: VERIFY </D1/0S9BOOT >IDQITEMP U update eRe value
OS9: DELlD1/0S9BOOT delete old boot file
059: COpy IDOITEMP ID1/0S9BOOT install updated boot file
You can now use the DSAVE command to build a new system disk.
4·9
Chapter 5
Debug Command Summary
and Error Codes
Debug Command Summary
[SPACEBAR]expression
Evaluate; display in hex.adecimal and
decimal form
Dot Commands
Display Dot address and contents
Restore last Dot address; display address
and content!;
. expression
=
expression
Set Dot to result of expression; display
address and contents
Set memory at Dot to result of
expression
Decrement Dot; display address and
contents
[ENTER]
Increment Dot; display address and
contents
5·1
interactive Debugger
Command SummalJ' and Error Codes / 5
Register Commands
Display all registers' contents
:register
Display the specified register's contents
:register e;cpression
Set register to the result of expression
Program Setup and Run Commands
E module-name
Prepare for execution
G
Go to the program
G expression
Goto the program at the address
specified by the result of expression
L module-name
Link to the module named; display
address
Breakpoint Commands
B
Display all breakpoints
B expression
Set a breakpoint at the result of
e;cpression
K
Kill all breakpoints
K expression
Kill the breakpoint at address specified
by expression
5-2
Interactive Debugger
Command Summary and Error Codes I 5
Utility Commands
M expression] expression2
Display memory dump in tabular
form
C expression] expression2
Clear and test memory
S expression] expression2
Search memory fOf pattern
$ text
Call OS-9 Shell
Q
Quit (exit) Debug
Debug Error Codes
Debug detects several types of errors, and displays a corresponding
error message and code number in decimal notation. The various
codes and descriptions are listed here. Error codes other than those
listed are standard 05-9 errOf codes returned by various system calls.
o
IIIegal Constant: The expression includes a constant that has an
illegal character or that is greater than 65,535.
Divide by Zero: You are trying to use a divisor of zero.
2 Multiplication Overflow: The product of the multiplication is
greater than 65,535.
3 Operand Missing: An operator is not followed by a legal
operand.
4 Right Parenthesis Missing: Parentheses afe not correctly nested.
5 Right Bracket Missing: Brackets are not correctly nested.
5-3
Interactive Debugger
Command Summary and Error Codes / 5
6 Right Angle Bracket Missing: A byte-indirect is not properly
nested.
7 Incorrect Register: A misspelled, missing, or illegal register
name follows the colon.
8 Byte Overflow: You are trying to store a value greater than 255
in a byte-sized destination.
9 Command Error: A command is misspelled, missing, or illegal.
10 No Change: The memory location does not match the value
assigned to it.
11 Breakpoint Table Full: Twelve breakpoints already exist.
12 Breakpoint Not Found: No breakpoint exists at the address
given.
13 Illegal SWI: Debug encountered an SWI instruction in the user
program at an address other than a breakpoint.
5-4
Interactive Debugger
Index
! operator 2-3
" (quotation marks) 2-2
# prefix 2-1 - 2-2
$ (SHELL) command 3-12 - 3-13
$ prefix 2-1 - 2-2
% prefix 2-1 - 2-2
& operator 2-3
. (DOT) command 2-2, 3-2 - 3-4, 4-5
.. (Dot-Dot) command 2-2, 2-3
* operator 2-3
+ operator 2-3
- operator 2-3
I operator 2-3
:(REGISTER) command 3-5 - 3-6
: (register names) 2-3
accumulator 2-3
addition 2-3
addresses, specifying 3-6 - 3-8
addressing, indirect 2-4
ASCII codes 2-2
ASCII conversion 3-2
B (BREAKPOINT) command 3-7, 4-5 - 4-6
binary conversion 3-2
breakpoints 3-6 - 3-8
C (CLEAR MEMORY) command 3-11
changing register contents 3-5 - 3-6
character constants 2-2
clearing memory 3-1 I
1
Interactive Debugger
Index
COBBLER 4-8 - 4-9
codes, ASCn 2-2
colon (REGISTER) command 3-5 - 3-6
command line 1-2
commands
$ (SHELL) 3-12 - 3-13
B (BREAKPOINT) 3-7,4-5 - 4-6
C (CLEAR MEMORY) 3-11
DOT 2-2 - 2-3, 4-5
DOT-DOT 2-2,3-3
E (ESTABLISH) 3-5,3-8-3-10,4-5
G (GOTO) 3-5,3-9 - 3-10
K (KILL) 3-8
L (LINK) 3-10,4-4 - 4-5
M (MEMORY) 4-5 - 4-6
OS-9 3-12- 3-13
REGISTER 3-5 - 3-6
S (SEARCH) 3-12
content of registers 3-5
converting values 3-1
current working address 2-2
Debug prompt 1-1
decimal
conversion 3-2
notation 1-2
deleting a line 1-1
diagnosing programs 1-1
displaying memory 3-12
division 2-3
Dot 2-2
Dot-Dot 2-2
DSAVE 4-9
E (ESTABLISH) command 3·5, 3-8, 3-10, 4-5
ending a debug session 3-13
examining registers 3-5 - 3-6
2
Interactive Debugger
Index
execution
of programs 3-9 - 3-10
testing 3-8 - 3-9
exiting a debug session 3-13
expressions 2-3, 3-1
displaying 1-2
G (GOTO) command 3-5,3-9 - 3-10
hexadecimal
conversion 3-2
notation 1-2
indirect addressing 2-4
inserting breakpoints 3-6 - 3-7
integers 2-1
integral expression interpreter - 2-1
K (KILL) command 3-8
L (LINK) command 3-10, 4-4 - 4-5
line deleting 1-1
loading a program module 4-4
logical operators 2-3
M (MEMORY) command 4-5 - 4-6
memory
clearing 3-11
displaying 3-12
searching 3-12
testing 3-11
modes, indirect addressing 2-4
modules
linking 3-10,4-4 - 4-5
loading 4-4
patching 4-8 - 4-9
multiplication 2-3
~-----
--------- - - - - -
3
Interactive Debugger
Index
negative arithmetic 2-1
negative numbers 2-3
notation (hexadecimal and decimal) 1-2
operands 2-1
operators 2-3
OS-9 Shell 3-12 - 3-13
OS9GEN 4-8
programs
executing 3-9 - 3-10
loading modules 4-4
patching 4-7 - 4-9
quitting debug 3-13
quotation marks 2-2
REGISTER command 3-5 - 3-6
registers 2-3
examining 3-5 - 3-6
resuming execution 3-9 - 3-10
S (SEARCH) command 3-12
sample session 4-4 - 4-9
searching memory 3-12
shell command 3-12 - 3-13
software interrupts 3-6 - 3-7
SP register 3-5
spaces 2-1
starting program execution 3-9 - 3-10
starting
address 3-10
Debug 1-1
subtraction 2-3
suspending execution 3-6 - 3-8
4
Index
Interactive Debugger
test
execution 3-8 - 3-9
memory 3-11
two's complement 2-1
value, assigning to a register 3-6
values, converting 3-1
working address 2-2
5
Screen Editor
Contents
Chapter 1 / Introduction
Modes Of Operation
Starting Scred
Available Options
1-1
1-1
1-2
1-2
Chapter 2 / The Termset File
Modifying the Termset File
The Termset File Format
Tennset Fields
2-1
2-1
2-2
2-2
Chapter 3 / Command Mode
Changing to the Edit Mode
Changing to the Insert Mode
Manipulating the Edit Buffer
Saving Text
,
Removing Text
Searching for Strings
Changing Strings
Using Wild Cards
Miscellaneous Commands
Exiting Scred
3-1
3-1
Chapter 4/ Edit Mode
Getting Help
Controlling the Cursor
Scrolling the Screen
Moving to a Specific Line
Finding a String
Replacing Strings
Deleting Text
Inserting or Replacing a Single Character
Cutting and Pasting
, ,
3-2
3-3
3-3
3-4
3-5
3-5
3-6
3-6
3-8
4-1
4-1
4-2
4-2
4-3
4-3
4-4
4-4
4-5
4-5
Screen Editor
Contents
---_._-----
Editing Lines
Displaying the Status Line
4-6
4-7
Chapter 5/ Insert Mode
5-1
Chapter 6 / Quick Reference ,
Command Mode
Edit Mode
Cursor Movement Commands
Cut and Paste Commands
Insert Mode
6-1
6-1
6-3
6-3
6-5
6-6
Chapter 1
Introduction
The OS-9 Level Two Screen Editor (Sered) is a powerful and simple to
learn screen-oriented text editor. You can use Scred to prepare text
for letters and documents or text to be used by other 05-9 programs
such as the assembler and high level languages. Sered's features
include:
•
Adjustable screen and workspace size
•
Continuously updated screen
•
Cursor positioning by characters, words, and
•
Scrolling
•
Cut and paste
•
Change, find, and search strings
•
Wild cards
line-by~line
Modes of Operation
Sered has three modes of operation: Command, Edit, and Insert. The
Command Mode lets you execute Scred commands that affect files or
the edit buffer. Sered starts up in Command Mode. The Edit Mode
lets you modify or manipulate text within the edit buffer. The Insert
Mode lets you enter new text into the edit buffer.
1-1
Screen Editor
Introduction I 1
Starting Scred
To start Scred. type:
scred filename [ENTER]
If the file exists, Sered loads the file into the edit buffer. displays the
beginning of the file, and enters Edit Mode.
If the file does not exist, Scred displays:
can't open filename
ERROR #216
and enters the Command Mode.
If you want to create a new file, type:
scred [ENTER]
This starts Scred in Command Mode, from which you can load
a file or begin creating a new one by using the NEW command (see
Chapter 3).
Note: Scred uses a special file called termset to describe the
attributes of a particular terminal. See Chapter 2, "The
Termset File," for more information on this file.
Available Options
You can use several options on the command line when starting up
Serect. These options specify the terminal type, buffer size, and so on.
Use the following form when starting Scred with options:
scred filename options [ENTER]
1-2
Screen Editor
Introduction! 1
The available options are:
-?
Displays a list of the Scred options.
-b= numk
Allocates numk bytes of memory for Scred's working
buffer. The buffer's default size is 12 kilobytes. The "_"
and "k" are optional parameters. For example, -b32 is the
same as ·b=32k.
-e
Configures Scred for terminals that have embedded video
attributes, that is, terminals in which the attribute start
flag uses one character position.
-g
Configures Scred for special graphic-oriented terminals
(terminals that do not support line feeds).
-l=num
Specifies the number of lines to be displayed on the
terminal screen.
You can also set this option in the
termset file. See Chapter 2, "The Termset File," for more
information.
-t=term
Specifies the terminal type. Use this option if your
terminal type is different from the default terminal type
as set in the termset file. See Chapter 2, "The Tennset
File," for more information.
-w=num
Specifies the maximum number of characters per line to
be displayed on the terminal screen. You can also set this
option in the termset file. See Chapter 2. "The Tennset
File," for more information.
-z=path
Sets the pathlist that Scred uses to find the tcrmset file.
See Chapter 2, "The Termset File," for more information.
Note: Since Scred normally checks the current window siz.e,
the -1 and -w options are not often needed. If you use them, be
certain you give valid values. Otherwise these options can
interfere with screen formatting.
1-3
Screen Editor
Introduction / 1
Examples
scred file1 -b=32k
This command starts up Scred with a 32k byte buffer.
scred file1 ·1=24 -w=30
This command starts up Scred with a screen size of 24 lines by 30
characters.
1·4
Chapter 2
The Termset File
To operate properly, Scred must know the type of terminal you are
using. Scred finds this information in a file named Tennset. The
Termset is a text file containing entries that describe a variety of
terminals. The terminal types currently supported in Termset are:
•
COCO (the default for windows)
•
KT7
•
VDG (for VDG screen)
•
ANSI
•
ABM85
•
ABM85H
If you using other than the COCO terminal, use the -t option and
specify the terminal name when starting Scred. If your terminal type
is not currently supported in the Termset file, read the rest of this
chapter for instructions to add your terminal to the file.
Scred looks for the Termset file in the directory IddJsys, where dd is
the default device for your system. If Scred doesn't find the file there,
it looks in JhOJsys and then in IdO/sys. You can use the ·z option of
Scred to specify a different path for the Tennset file.
Modifying the Termset File
To add a new terminal type to the Termset file, you can:
•
Edit the TeTmset file using a text editor
•
Use the Maketerm supplied on the Scred distribution diskette
Because Makefile is easier to use, it is the method shown in this
chapter's examples.
2-1
Screen Editor
The Termset File /2
The Termset File Format
The Termset file contains control code definitions for one or more
types of terminals. Each text line in the file is a complete description
list for a particular kind of terminal.
The first line of the Termset file contains the name and control code
definitions for the default terminal type. This is the terminal type
Scred uses if you do not use the -t option. The form is:
NAME:ccc:cov:dl:dc:cs:ce/:iI:S8v:eav:sJ:sw
Each field represents a different control code definition. Notice that
each field is separated by a colon (:). Even if the terminal cannot
perform a certain function, the colon must still be present to hold the
function's position.
Termset Fields
The following list defines each field in a terminal type entry:
NAME
Terminal Name
Specifies the identification name of the terminal
described in the line. Use this name with the -t option to
specify the terminal type for Scred to use. You must
specify the name in all uppercase, although you can
specify lowercase with the -t option on Scred's command
line.
cee
Cursor Control Code
Positions the cursor to any location on the screen. This
function is required. There are two parts to the Cursor
Control Code: (1) one or more position cursor command
characters, and (2) cursor coordinates. \X and \Y (or
\X\X and \Y\Y) are cursor coordinates where X and Y
refer to the column number and row number,
respectively. The order in which you specify the cursor
coordinates is dependent on your terminal's requirements.
2-2
Screen Editor
The Termset File 12
This infonnation should be supplied with the hardware
specifications that come with your tenninal.
Examples:
$1 b[\ Y\ Y ;\X\XH:
$lb$3d\Y\X:
$lbR\X\Y:
In the first example, the bracket character ([) has an
ASCII value of $5B. You could use $5B in place of r to
produce the same results.
cov
Cursor Offset Value
Sets the offset value for the cursor coordinates.
This
value, specified in hexadecimal, is always added to the
cursor X and Y coordinates. Many terminals use an
offset of $20.
dl
Delete Line Control Characler(s)
Deletes the current line and causes lines below the
deleted line to scroll up.
de
Delete Character Control Character(s)
Deletes the character under the cursor and shifts the
remaining characters on the line to the left by one
character position.
cs
Clear Screen
Erases the entire screen, and returns the cursor to the
home position.
eel
Clear to End of Line
Erases all characters on the line from the current cursor
position to the end of the line, including the character
under the cursor.
2·3
The Termsel File 12
Screen Editor
il
Insert Line
Creates a new blank line by scrolling the current and
subsequent lines down one line.
sav
Start Alternate Video
Displays all subsequent characters in reverse video,
different intensity. or any similar mode that is visibly
different from the normal video mode. This code is used
when highlighting text.
eav
End Alternate Video
Displays all subsequent characters in normal video mode.
You can specify 0--4 output control characters for the
following fields: Delete Line. Delete Character. Clear
Screen, Clear to End of Line, Insert Line, Start Alternate
Video. and End Alternate Video.
sl
Screen Length
Specifies, in hexadecimal, the number of lines to be
displayed on the terminal screen. This field is optional.
If you omit this value, Scred uses 24.
~"W
Screen Width
Specifies, in hexadecimal, the number of columns to be
displayed on the terminal screen. This field is optional.
If you omit this value, Scred uses 80.
Screen length and screen width are optional fields. If
you omit them, Scred checks the size of the current
screen (or part of the screen) and uses these values.
For external terminals, Scred assumes a screen size of
24 lines by 80 columns. If you do specify a length
and width, Scred uses these values and does not
check on the size of the current screen.
2·4
Screen Editor
The Termset File 12
Examples
Example 1
Create the following Termset entry:
ABM85:$1 b$3d\eY\eX:$20:$1 bR:$lbW:$l e$l bY;$1 bT:$1 bE:$1 bj :$1 bk:$18
:$50:
To create the above entry, type the following at the system prompt ($):
maketerm IENTER]
The Maketerm utility prompts you to supply a value for each field in
the Termset entry. If a Termset file does not exist, Maketerm creates
it. If the file does exist, Maketerm appends the new entry to the end of
the Termset file.
Note; If a particular terminal does not have one of the
requested features, simply press IENTER] at the prompt.
Following are the prompts displayed by Maketerm and the responses
needed to create the ABM85 entry:
terminal name: ABM85 [ENTER]
cursor positioning sequence: $lb$3d\eY\eX [ENTER]
cursor position offset: $20 [ENTER]
delete line sequence: $lbR (ENTER]
delete character sequence: $lbW [ENTER)
clear screen: $le$lbY [ENTER]
clear to end of line: $lbT [ENTER)
insert line: $1 bE [ENTER]
alternate video: $1 bj [ENTER]
restore normal video: $lbk (ENTER]
screen length: $18 [ENTER]
screen width: $50 [ENTER]
2·5
Screen Editor
The Termset File 12
Example 2
To create the following Tennset entry:
TERM=$1 bR\x\Y:$OO:::$Oe:: :$1 bj:$1 bl:::
Type maketenn [ENTERl· The prompts and responses look like this:
terminal name; TERM [ENTERl
positioning sequence: $1bR\X\Y [ENTER]
cursor position offset: $00 rENTER]
delete line sequence: [ENTER]
delete character sequence: [ENTER]
cur~or
clear screen: $Oe [ENTER]
clear to end of line: [ENTER]
insert line: [ENTER]
alternate video: $1bj [ENTER]
restore normal video: $1 bl IENTER]
screen length: [ENTER]
~creen width: [ENTER]
2-6
Chapter 3
Command Mode
The Command Mode lets you invoke commands that affect files or
manipulate the entire edit buffer. Scred starts up in Command Mode if
you do not specify a file on the command line. When you are in the
Command Mode, Scred displays the:> prompt in the lower left corner
of the display screen.
Command Mode commands (except the GOIO command) are at least
two characters long to distinguish them from the Edit and Insert Mode
commands. You can use either the full name for the command, such as
edit, or Sered's shortened form, ed. Commands that have short forms
are shown as follows:
ed[it]
This means you can type either ed or edit for the EDIT command. Do
not type the square brackets.
When entering commands in Command Mode, you can use the
standard 05-9 control keys to backspace, delete lines and characters,
and so on. Press [ENTER] after typing each command.
Changing to the Edit Mode
There are two methods in which you can enter Edit Mode from
Command Mode:
1.
Edit an existing file by typing at the> prompt:
ol[d] filename [ENTER]
If Scred can open the file, it then enters the Edit Mode.
3-1
Screen Editor
2.
Command Mode / 3
If you have a file open and want to enter the Edit Mode. type:
ed[it] [ENTER]
You can also press
[CTRL][E]
to enter the Edit Mode.
From the Edit Mode, you can change to the Command Mode by
pressing [CTRL][BREAK]
Changing to the Insert Mode
You can enter Insert Mode from Command Mode by typing:
in[sert] [ENTER]
Create a new file by typing at the
:>
prompt:
ne[w] f/Jename [ENTER]
If Scred can create the file, it loads the file into the edit buffer and
then enters the Edit Mode.
You can enter the Insert Mode from the Edit Mode by: (1) pressing
[ENTER] to insert text before the cursor position, and (2) pressing the
down arrow to insert a new line before the current line. You can then
begin typing the new line.
Note: You cannot enter the Insert or Edit Modes if no file
exists in the edit buffer.
3·2
Command Mode / 3
Screen Editor
Manipulating the Edit Buffer
Scred's edit buffer size is 12k bytes unless you use the -b option to
specify a different value. If your file is larger than the edit buffer,
Scred loads as much of the file as it can, while leaving approximately
2k free for changes and additions. With the 12k buffer size, Scred
loads 10k of the file. The following commands show how to write,
read, and insert files or sections of files.
Saving Text
The WRITE command writes the contents of the edit buffer and the
remainder of the input file (if any) to the output file. WRITE then
closes the file and clears the edit buffer. To write a file, type:
wr[ite] [ENTER]
When Scred saves a file, it creates an output file called Ed.tmp.xxx,
where xxx is the process id number. If Scred can successfully create
and write the entire output file, it deletes the current input file and
renames the output file to the old name.
The UPDATE command writes out the changes you made to the edit
buffer and re-enters the Edit Mode. To update a file, type:
up[date] [ENTER]
The ADD command lets you insert a specified file within the text of
the edit buffer. Scred inserts the file directly before the current line.
To add a file before the current line, type:
adld] filename [ENTER)
Note: There must be enough free space in the edit buffer for
the extra text. If Scred runs out of space, it terminates with the
message file too large to add and does not load any of the file.
3-3
Screen Editor
Command Mode /3
The MORE command lets you read in the next section of the input file.
Use this command when the file you are editing is too large to entirely
fit in the edit buffer. The MORE command causes Sered to write the
contents of the edit buffer between the top of the buffer and the
current cursor position to the output file and read the next section of
the input file into the edit buffer. To read the next section of a file,
type
mo[re] [ENTER]
Removing Text
Sered lets you delete specified lines of text from the edit buffer or
delete the entire buffer.
The DELETE command lets you delete specified lines from the edit
buffer. To delete lines, type:
de(Iete] start-line end-line [ENTER]
This command deletes text from start-line to end-line, inclusive.
The ABORT command erases the entire contents of the edit buffer and
closes the file. To erase and close a file, type:
ab(ort] [ENTER)
The CLEAR command also erases the entire contents of the edit buffer
but the file remains open. To clear the edit buffer, type:
cl[ear] [ENTER]
3-4
Screen Editor
COmnuJ.nd Mode /3
Searching for Strings
The FIND command prompts you to enter a search mask and then
searches for that string. If Scred finds the string, it positions the cursor
at the beginning of the first occurrence of the string and then enters
Edit Mode. To find a string, type:
fi[nd] [ENTER)
The SEARCH command prompts you to enter a search mask and then
searches for that string. In addition, SEARCH lets you search for that
string between specified lines instead of through the entire file. If
Scred finds the string, it displays the lines, including the line number,
in which the string was found. To search for a string, type:
se[arch] start-line end·line (ENTER)
This command searches for the string beginning at start-line through
end-line, inclusive. If you omit start-line and end-line, Sered searches
the entire edit buffer.
Note: The SEARCH and FIND commands accept a match first word
only character. By placing a 1\ as the first character in the search
string, Scred finds a match only if it finds the string at the beginning
of the line.
Changing Strings
The CHANGE command replaces all occurrences of a string within the
specified range of lines or over the entire edit buffer. To use the
CHANGE command, type:
ch[angel start-line end-line [ENTER]
If you omit start-line and end-line, Sered searches the entire edit
buffer.
Command Mode r3
Screen Editor
When you invoke the CHANGE command, Scred prompts you to enter
a Search mask:. Enter the string you want to change, Scred then
prompts you to enter a Change mask:. Enter the new string.
If Scred finds the search string, it displays the lines, including the line
numbers, in which the changes occurred.
Nole: The CHANGE command accepts a match first word
only character. By placing a 1\ as the first character in the
search string. Scred finds a match only if it finds the string at
the beginning of the line.
Using Wild Cards
When entering the search string for the FIND, SEARCH and CHANGE
commands, you can optionally use the wild card character "?". The
wild card character matches anyone character in the specified
location. For example:
m????? [ENTER]
Scred matches all strings that begin with the letter "rn" and are
followed by five characters. Sample strings that would match are:
"millio," "mister," and "my dog."
??_?? [ENTER]
In this example, Scred matches all five character strings with an underscore character CJ in the third character position. Some sample
strings that match this string are: "55_ill;' "WA_ 86," and" _dj,"
Note: Scred matches spaces between words when searching
for a wild card string.
3·6
Screen Editor
Command Mode I 3
Miscellaneous Commands
The GOTO command positions the cursor on a specified line and
enters Edit Mode. To position the cursor, type:
g[oto] line-number [ENTER]
The CHD command changes the current working directory to the
specified directory. You can specify either a relative or absolute path
to the new directory_ To change directories, type:
chd pathname [ENTE R]
The DIR command displays the directory listing for the current
directory. To obtain a listing, type:
dir [ENTER]
Scred can handle files with tabs in them. However, tabs are not a
function of Scred. The TABS command lets you set tab stops at each n
characters. To set the tab stops, type:
ta[bs] n [ENTER]
Serect sets tabs at every four characters by default.
Another feature of Scred is auto-indent. If you enter an indented line,
Scred automatically aligns the next line with it.
The NOTAB command turns off the auto-indent function. To disable
the auto-indent feature, type:
not[ab] [ENTER]
3-7
Command Mode /3
Screen Editor
The AUTO INDENT command turns the feature back on. To enable the
auto-indent feature, type:
au[to indent) [ENTER)
The $ command lets you execute a shell command line from within
Scred. To execute an OS-9 command, type:
$command-Jine (ENTER]
For example, to list the contents of a file, type:
$Ust filename [ENTER)
When you use the SHELL command ($ [ENTER)), OS-9 starts a new
shell (if your computer has enough free memory). In this way it can
process several OS-9 commands. To return to the Scred > prompt,
press [CTRL][BREAKJ.
Exiting Scred
The EXIT command ends the current editing session. If a file exists,
Scred saves the file to disk and returns to the 05-9 system. To exit
Scred, type:
ex [it] [ENTER)
3-8
Chapter 4
Edit Mode
The Edit Mode lets you control and modify text in the edit buffer and
on the screen display. You can enter Edit Mode from Command Mode
by typing ed [ENTER] or by pressing [CTRL][E]. You can enter Edit
Mode from Insert Mode by pressing [CTRL][BREAK]. When you enter
Edit Mode, Scred displays the text of the file being edited.
Commands in this chapter, appear in uppercase as they appear on your
keyboard. Unless specifically noted, you do not have to press [SHIFT]
to invoke the commands.
Getting Help
You can display help information at any time while in Edit Mode. To
do so, press 1. Scred displays a list of commands at the top of the
screen. The commands are divided into four groups:
•
Cursor control keys
•
Edit buffer controls
•
CUT and PASTE commands
•
Miscellaneous commands
Press the spacebar to review the display for each group. Press q to
exit the help function.
4-1
Screen Editor
Edit Mode /4
----~----
Controlling the Cursor
The following table lists the keys Scred uses to position the cursor.
When looking at this table, notice that the location of each key on the
keyboard is related to the movement it performs.
Key
Action
I
moves the cursor up one line
,(comma)
moves the cursor down one line.
J
moves the cursor left one character
L
moves the cursor right one character
K
moves the cursor alternately to the beginning or end of
the current line
H
moves the cursor one word to the left
moves the cursor one word to the right
Scrolling the Screen
Sered uses four keys to scroll the screen. The table below lists the
keys and their descriptions. As before, notice the location of the keys
on your keyboard.
Key
Action
U
M
scrolls
scrolls
scrolls
scrolls
a
the
the
the
the
screen
screen
screen
screen
up continuollsly
down continuously
up
down
The continuous scroll feature is useful when you want to quickly scan
through a file. Use the space bar to pause and restart scrolling. Type
any other character to terminate scrolling.
4-2
Screen Editor
Edit Mode! 4
When scrolling down one screenful, the line at the bottom of the
screen scrolls to the top of the screen. When scrolling up one
screenful, the line at the top of the screen scrolls to the bottom of the
screen.
Moving to a Specific Line
The GOTO command moves the cursor to the specified line within the
edit buffer. To move the cursor to a specific line, press G. Scred
prompts you to enter the line number with the prompt goto:. Enter the
line number to which you want to move the cursor. Sered positions
the cursor at the beginning of the specified line and positions that line
on the third line of the screen.
Line 1 is the first line of the edit buffer. Any number higher than the
last line number causes the last line to be selected.
Finding a String
The FIND command searches for a specified string and positions the
cursor on the first character of that string. To invoke FIND, press F.
Sered prompts you to enter a Searct1 mask:. Type the string you want
to find. If Sered finds the string, it positions the cursor on the first
character of the string and positions the line in which the string
occurred on the third line of the screen. If Scred cannot find the
string, it displays the message, find: no match.
To find another occurrence of the same string, press F and press
[ENTER] for the search mask. Scred moves the cursor to the next
occurrence of the previously entered string.
4·3
Edit Mode /4
Screen Editor
Replacing Strings
The REPLACE command lets you substitute one string for another. To
replace a string, press R [ENTER] and Scred prompts you to enter a
Search string:. Enter the string you want to replace. Scred then
prompts you to enter the Change string:. Enter the new string.
To replace the next occurrence of the search string with the same
string, press R and press [ENTER] for both prompts.
Deleting Text
Scred offers a variety of ways to delete text. You can delete
characters, words, and lines. The following table summarizes the key
commands and their definitions.
Key
Action
~J
deletes the character to the left of the cursor
[CTRL)[;]
deletes the character under the cursor
[CTRL][AI
deletes one word to the left of the cursor
[CTRL][DI
deletes one word to the right of the cursor
[CTRLJ[C]
deletes from the current cursor position to the end of
the line
[CTRLJ[Z]
deletes from the current cursor position to the
beginning of the line
[CTRLJ[XI
deletes the current line
Note: If you accidentally delete text, you can recover by
pressing [CTRLJ[F]. The [CTRLUF] command restores the
current line to its original state.
4·4
Screen EdilOr
Edit Mode /4
Inserting or Replacing a Single Character
Scred easily lets you insert one character or substitute one character
with another without having to enter Insert Mode.
The REPLACE CHARACTER command replaces the character under
the cursor. To replace a character, type Xcharacter. For example,
typing Xz replaces the character under the cursor with a "z."
The INSERT CHARACTER command inserts a character in front of
the character under the cursor. To insert a character. type Bcharacter.
For example, typing Ba inserts an "a" in front of the character under
the cursor.
Cutting and Pasting
Scred's cut and paste feature lets you move a block of text and insert
it at another location. Scred lets you move, delete, or duplicate blocks
of text.
Before you move a block of text, you must mark the beginning point
of the block. The SET command marks the starting line. To mark a
line, move the cursor to the first line of the block of text you want to
move, and press S. To mark in the middle of a line, first break: the line
into two lines, and then mark it. Scred displays the marked line in
reverse video if your tenninal has the capability.
Next, move the cursor to the last line of the text block you want to
move. Use the CUT command to remove the text from the edit buffer.
Scred places the text in its paste buffer.
You can add more text to the paste buffer by using the APPEND
command. To use the APPEND command, mark the beginning of the
text block using SET, and move the cursor to the end of the block.
Press A. and Scred appends the text block to the text already in the
paste buffer.
4·5
Screen Editor
Edit Mode /4
Use the PASTE command to return the contents of the paste buffer to
the edit buffer. Scred pastes text on the line above the current line.
Therefore, to paste the text, position the cursor one line below the line
on which you want the text inserted, and press P.
You can also duplicate text by using the NON-DESTRUCTIVE CUT
command. To do so, mark the beginning of the text block using the
SET command and move the cursor to the last line 9f the text to be
duplicated. Press Nand Scred copies the text block into the paste
buffer. The text in the edit buffer is untouched.
Scred also offers a NON-DESTRUCTIVE APPEND command. Mark
the beginning of the text block (SET), and move the cursor to the last
line of the text to duplicate. Press v. and Scred appends a copy of the
text to the end of the paste buffer. The text in the edit buffer is
untouched.
The ERASE command clears the paste buffer and returns its memory.
Press E to erase.
Scred also lets you write sections of text to a file using the WRITE
command. To do so, mark the beginning of the block (SET), and move
the cursor to the last line of the block. Press P. Scred prompts you to
enter an output filename. If you invoke the WRITE command without
marking a text block, Scred writes the paste buffer to the output file.
If Scred cannot create the file, it issues an error message.
Editing Lines
Scred allows you to use lines of up to 256 characters in length.
However, because Scred does not wrap lines, you can see only a
portion of the line if it is longer than the width of your screen. Scred
offers an easy method of breaking and joining lines.
4-6
Screen EditOr
Edit Mode /4
The BREAK command splits the line at the current cursor position.
Scred inserts the break before the cursor. To break a line. press
ICTRL][B].
The JOIN command joins the current line with the one above. To join
two lines. press [CTRL][P].
Displaying the Status Line
The status line displays the line number, column number. amount of
free space in the edit buffer, paste buffer size, current filename, and
the current mode (Command, Edit, or Insert). To display the status
line, press [CTRL][G]. Press the space bar to remove the status line
from the screen.
The following sample status line shows the current cursor position to
be Line 50, Column O. There is more than 14k bytes free in the edit
buffer and 51 bytes of text stored in the paste buffer. The filename is
Example, and Scred is in the Edit Mode.
L:50
C:O
MB:14526
CB:51
4·'
F:Example
edit:
Chapter 5
Insert Mode
The Insert Mode lets you enter new text into the edit buffer. To enter
the Insert Mode from the Command Mode, type in [ENTER]. To enter
the Insert Mode from the Edit Mode, press [ENTER] or [+].
Scred inserts the new text before the current cursor position and stores
it exactly as you type it. You can enter control characters. To enter
control characters, press [CTRL]IVl followed by the character you wish
to enter. For example, to enter a Control-L into the edit buffer, press
[CTRL][V], then [Ll·
5-1
Chapter 6
Quick Reference
The following tables provide a quick reference to the commands for
the Command, Edit, and Insert Modes.
Command Mode
Command
Description
ab[ort]
Cancels all changes made to the
current file, erases the entire edit
buffer, and closes the current file.
ad[d]filename
Adds the text of the specified file to
the edit buffer, starting at the line
above the current cursor position.
au[to indent]
Tells Scred to automatically indent
the next line after a carriage return
in the previous line begun with a tab
or space(s). Scred indents the new
line to the same column position as
the previous line. Scred starts up in
auto-indent mode.
ch[ange][start-line [end-line]]
Replaces all occurrences of a string
within the specified range of lines.
Omitting a range value causes Scred
searches the entire edit buffer.
6-1
Screen Editor
Quick Reference / 6
Command
Description
chd pathname
Changes the
directory.
c1[ear]
Erases all text in the edit buffer.
Scred does not close the file.
de[lete] [starr-line [end-line]]
Erases the specified range of lines
from the edit buffer.
dir
Displays the directory listing for the
current working directory.
ed[it]
Enters Edit Mode. You can also use
current
working
[CTRL][El
ex[it]
Writes the edit buffer to the output
file and exits Scred.
fi[nd]
Searches for the first occurrence of
a string. Enters the Edit Mode.
gf 010] line
Moves the cursor to the specified
line number. Enters the Edit Mode.
in[sertJ
Enters Insert Mode.
mo[re]
Saves the text in the edit buffer to
the output file and reads in the next
section of the input file.
nelw ]filename
Creates a new file with the specified
filename and enters. Insert Mode.
nat[ab]
Turns off the auto-indent mode.
ol[d]
Clears the edit buffer. opens an
existing file. and enters Edit Mode.
6·2
Screen Editor
Quick Reference I 6
Command
Description
se[arch] [start-line [end-linell
Searches for a string within the
specified lines. If you omit the line
numbers, Serect searches the entire
edit buffer.
ta[bs] n
Sets the tab stops
characters.
up[date]
Writes changes to the output file
and re-enters Edit Mode.
wr[ite]
Writes the contents of the edit
buffer and the remainder of the
input file, if any, to the output file.
$ [command]
Executes a shell command line.
[CTRL][G]
Displays the status line.
to every n
Edit Mode
Cursor Movement Commands
Command
Description
I
Moves the cursor up one line.
, (comma)
Moves the cursor down one line.
J
Moves the cursor left one character.
H
Moves the cursor left one word.
L
Moves the cursor right one character.
Moves the cursor right one word.
K
Moves the cursor to the beginning or end of the line.
R
Replaces a string.
6-3
Screen Editor
Quick Reference / 6
Command
Description
U
Scrolls the text up. Press the space bar to stop and
start. Press any other key to abandon.
M
Scrolls the text down. Press the space bar to stop and
start. Press any other key to abandon.
o
Scrolls text up on page.
Scrolls text down one page.
G
Moves the cursor to the specified line.
F
Finds the first occurrence of a string.
X char
Replaces the character under the cursor with the
specified character.
B char
Inserts the specified character before the cursor and
advances the cursor.
r+]
Deletes the character to the left of the cursor.
[CTRLH;]
Deletes the character under the cursor.
[ENTER]
Enters Insert Mode.
[
... ]
Moves the text in the edit buffer down one line and
enters Insert Mode with the cursor on the new line.
[CTRL)[BREAK] Returns to Command Mode.
?
Displays help information.
[CTRL][A]
Era"es one word to the left of the cursor.
[CTRL][DI
Erases one word to the right of the cursor.
[CTRL][F)
Cancels any changes made to the current line.
6-4
Screen Editor
Quick Reference! 6
Command
Description
[CTRL][C]
Erases text from the cursor to the end of the line.
[CTRLHZ]
Erases text from the cursor to the beginning of the
line.
[CTRL][X]
Erases the entire line.
[CTRLH8]
Splits the current line into two lines at the cursor
position.
[CTRL][P]
Jains the current line with the line above.
[CTRL][G]
Displays the status line.
Cut and Paste Commands
Command
Description
s
Set. Marks the first line of a text block to be deleted,
duplicated, or moved. If the starting mark is already
set, s removes the mark.
c
Cut. Deletes the selected block of text from the edit
buffer and stores it in the paste buffer.
N
Non-destructive Cut. Places the selected block of
text in the paste buffer without altering the edit
buffer.
p
Paste. Inserts the contents of the paste buffer at the
line above the cursor.
A
Append. Deletes the specified block of text from the
edit buffer and adds it to the end of the paste buffer.
6-5
Quick Reference / 6
Screen Editor
_
~O
Command
Description
_ _ _ '0
_
v
Non-destructive Append. Appends the specified
block of text to the paste buffer without altering the
edit buffer.
E
Erase. Erases the content of the paste buffer and
releases its memory space to the edit buffer.
w
Write. Writes the specified lines to the output file. If
no lines are marked, Sered writes the paste buffer to
the output file.
Insert Mode
Command
Description
[CTRL][V]char
Inserts the specified control character into the edit
buffer.
[CTRLJ(BREAK]
Returns to Edit Mode.
6-6
Screen Editor
Index
$ command 3-8
-? (list options) 1-3
-b (buffer size) 1-3,3-3
-e (embedded video attributes) 1-3
-g (graphics terminals) 1-3
-I (display lines) 1-3
-t (terminal type) 1-3
-w (text width) 1-3
-z (termset path) 1-3,2-1
> prompt 3-1
? (display help) 4-1
? (wild card) 3-6
ABM85 terminal 2-1
ABM85H terminal 2-1
ABORT command 3-4
ADD command 3-3
adding terminal type 2-1
allocating memory 1-3
ANSI terminal 2-1
APPEND command 4-5 - 4-6
auto-indent 3-7 - 3-8
BREAK command 4-7
buffer size 1-3, 3-3
CHANGE command 3-5 - 3-6
character
deleting 4-4
inserting 4-5
characters per line 1-3
1
Screen Editor
Index
CHD command 3-7
CLEAR command 3-4
clear screen code 2-3
clearing to end of line code 2-3
closing a file3-4
COCO tenninal 2-1
command mode 1-1 - 1-2
commands 3-1
$ 3-8
ABORT 3-4
ADD 3-3
APPEND 4-5 - 4-6
BREAK 4-7
CHANGE 3-5 - 3-6
CHD 3-7
CLEAR 3-4
CUT 4-5 -4-6
DELETE 3-4
ERASE 4-6
FIND 3-5,4-3
GOTO 3-7,4-3
INSERT 4-5
JOIN 4-7
MORE 3-4
NEW 1-2
NOTAB 3-7 - 3-8
REPLACE 4-4 - 4-5
SEARCH 3-5
SET 4-5 - 4-6
TABS 3-7
UPDATE 3-3
WRITE 3-3, 4-6
configuring term i naIs 1-3
creating a file 1-2,3-2
cursor control 4-2
cursor control code 2-2 - 2-3
cursor offset value 2-3
2
Screen Editor
Index
cursor, moving 4-3
CUT command 4-5 - 4-6
cutting and pasting 4-5 - 4-6
DELETE command 3-4
deleting
character codes 2-3
line codes 2-3
text 3-4, 4-4
directories
changing 3-7
listing 3-7
duplicating text 4-5 - 4-6
edit buffer, erasing 3-4
Edit mode 1-1, 3-1 - 3-2, 4-1 - 4-7
ERASE command 4-6
erasing the edit buffer 3-4
exiting Scred 3-8
features 1-1
file
closing 3-4
creating 1-2
reading in 3-4
saving 3-3
FIND command 3-5, 4-3
GOTO conunand 3-7,4-3
graphics 1-3
help 4-1
indent, auto 3-7 - 3-8
INSERT command 4-5
Insert Line code 2-4
3
Index
Screen Editor
insert mode 1-1,3-2,5-1
characters 4-5
files 3-3
JOIN command 4-7
KTI terminal 2-1
line character width 1-3
lines
deleting 3-4
moving to 4-3
listing
directories 3-7
options 1-3
Maketerm 2-1.2-5 - 2-6
mask, search 3-5 - 3-6, 4-3
memory allocation 1-3
modes
Command 1-1 - 1-2
Edit 1-1,3-1 - 3-2,4-1 - 4-7
Insert 1-1,3-2,5-1
MORE command 3-4
name of terminal 2-2
NEW command 1-2,3-2
new text 5-1
NOTAB command 3-7 - 3-8
operation modes 1-1
options 1-2 - 1-3
05-9 commands 3-8
paste 4-5 - 4-6
4
Screen Editor
Index
quitting Scred 3-8
reading files 3-4
replacing characters 4-5
REPLACE command 4-4 - 4-5
reverse video codes 2-4
saving text 3-3
screen, scrolling 4-2 - 4-3
screen length code 2-4
screen width code 2-4
scroll 4-2 - 4-3
SEARCH command 3-5
search mask 3-5 - 3-6. 4-3
SET command 4-5 - 4-6
shell 3-8
size of buffer 3-3
starting Sered 1-2 - 1-3
status line 4-7
string
changing 3-5 - 3-6
replacing 4-4
searching for 3-5, 4-3
TABS command 3-7
terminal 2-1
name 2-2
type 1-3,2-1
terminati ng Sered 3- 8
termset file 1-2 - 1-3,2-1 - 2-6
text
deleting 3-4,4-4
duplicating 4-6
entering 5-1
saving 3-3
type of terminal 1-3, 2-1
5
Screen Editor
Index
UPDATE command 3-3
VDG terminal 2-1
video attributes 1-2
width of line 1-3
wild cards 3-6
WRITE command 3-3, 4-6
6
Relocating Macro Assembler
Contents
Chapter 1 / Introduction
Installation
Using the RMA
Available Options
Chapter 2/ General Information
Source File Fonnat
The Label Field
The Operation Field
The Operand Field
The Comment Field
The Assembly Listing Format
Evaluation of Expressions
Expression Operands
Expression Operators
Symbolic Names
Symbolic Names for System Calls
The DEFS Directory
The LID Directory
Chapter 3/ Macros
Macro Structure
Macro Arguments
Special Arguments
Automatic Internal Lables
Documenting Macros
Chapter 4 / Program Sections
Program Section Declarations
1-1
1-2
1-2
1-3
2-1
2-2
2-2
2-3
2-3
2-4
2-4
2-4
2-5
2-7
2-7
2-8
2-9
2-10
3-1
3-2
3-3
3-4
3-5
3-7
4-1
4-2
Relocatable Macro Assembler
Contents
Chapter 5 / Program Section Directives
PSECf Directive
VSECf Directive
CSECf Directive
Chapter 6/ Assembler Directive Statements
End Statement
EQU and SET Statements
FAIL Statement
IF, ELSE, and ENDC Statements
NAM and TIL Statements
OPT Statement
PAG and SPC: Statements
REPI' and ENDR Statemenl'i
RMB Statement
USE Statement
5-1
5-1
5-3
5-5
,
_
,
6-1
6-1
6-1
6-2
6-3
6-5
6-5
6-6
6-6
6-7
6- 8
Chapter 7 / Pseudo-Instructions
FCB and FOB Statements
FCC and FCS Statements
RZB Statement
059 Statement
7-1
Chapter 8 / Accessing the Data Area
Using Non-Initialized Data
Using Initialized Data
8-1
8-1
8-2
Chapter 9/ Using the Linker
7-1
7-2
7-3
7-3
9-1
Running the Linker
9-2
Available Options
9-2
Chapter 10/ Error Messages
10-1
Chapter 111 Examples
11-1
Appendix A / 6809 Instructions and Addressing Modes
A-I
--
---
Chapter 1
------------- -----------
Introduction
The OS-9 Level Two Relocatable Macro Assembler (RMA) is a fullfeature relocatable macro assembler and linkage editor designed to be
used by advanced programmers or with compiler systems.
The RMA lets you assemble sections of assembly-language programs
independently to create relocatable object files- The linkage editor,
RLlNK, takes any number of program sections and/or library sections.
and combines them into a single executable OS-9 memory module.
The RMA's features include:
•
05-9 modular. multi-tasking environment support
•
Built-in functions for calling OS-9 system routines
•
Position-independent, re-entrant code support
•
Creating of standard subroutine libraries by allOWing programs to
be written and assembled separately and then linked together.
•
Macro capabilities
•
OS-9 Level Two compatibility
•
Automatic resolution of global data and program references
•
Conditional assembly and library source file support
This manual describes how to use the RMA and basic programming
techniques for the 05-9 environment. However, this manual does not
attempt to teach 6809 assembly language programming. If you are
not familiar with 6809 programming, consult the Motorola 6809
programming manuals or an assembly-language programming book
available at most bookstores and libraries.
1-1
Relocating Macro Assembler
Introduction / 1
Installation
The RMA distribution diskette contains a number of files that you will
want to copy to a working system disk. After copying the files, store
the original diskette in a safe place.
The files included on the distribution diskette are:
RMA
Relocatable Macro Assembler program. Copy this file to
the system's execution directory (CMDS).
RLINK
Linkage Editor program. Copy this file to the system's
execution directory (CMDS).
ROOT.a
Assembly-language source code file used as a front end
section for programs that use initialized data. Copy this
file to an RMA working data directory.
Using the RMA
RMA is a command program that you can run from the OS-9 Shell,
from a Shell procedure file, or from another program. The basic format
used to run the RMA is:
RMA filename options> listing
The filename argument represents the source text file. It is the only
required argument.
The options argument lets you specify certain RMA features, such as
the ability to generate a listing or object file. The list of available
options is given in the next section.
The listing option tells the RMA to generate a program listing. The
redirection symbol (» lets you redirect the listing to a printer or a
disk file, or even pipe the listing to another program. If you omit the
redirection symbol, OS-9 prints the listing on your terminal screen.
1-2
Relocating Macro Assembler
Introduction / 1
Available Options
You specify options on the command line by using the prefix - or --.
Use - to turn on an option and -- to turn off an option. The available
RMA options are:
-o=path
Writes the relocatable output to the specified mass
storage file. (Default=off)
-I
Writes the formatted assembler listing to standard
output. When this option is off, OS-9 prints error
messages only. (Default=off)
-c
Suppresses conditional assembly lines in assembler
listings. (Default=on)
-f
Sends a top-of-form
(Defau1t=off)
-g
Lists all code bytes generated. (Defau1t=off)
-x
Suppresses macro expansions in assembler listings.
(Default=on)
-e
Suppresses error messages in assembler listings.
(Default=on)
-s
Prints the symbol table at the end of the assembly
listing. (Default=off)
-dn
Sets the number of lines per page, for the listing, to n.
(Default=66)
signal
to
the
printer.
Note: You can override command line options by using the
OPT statement with a source program. See the OPT statement
for more information.
1·3
Relocating Macro Assembler
Introduction / 1
Examples
RMA prog5 -I-s -c >/p [ENTER]
This command line tells RMA to assemble the source program, Prog5.
The -1 and >/p options causes the RMA to write the formatted
assembler listing to the printer. The -s option tells the RMA to print
the symbol table. The -c option tells the RMA not to print any
conditional assembly lines in the listing.
RMA sample -I -x --c >/hOlprograms/sample.lst [ENTER]
This command line assembles the source program, sample, and sends
the listing to the file Sample.1st on the hard disk. The -x option tells
the RMA to suppress macro expansion in the listing. The --c option
tells the RMA to print conditional assembly lines.
1-4
Chapter 2
General Information
The RMA is a two-pass assembler. During the first pass through the
source file, it creates the symbol table. During the second pass, the
RMA places the machine-language instructions and data values into
the relocatable object file.
Writing and testing an assembly-language program using the RMA
involves a basic edit. assemble, link, and test cycle. The RMA
simplifies this process by letting you write programs in sections that
you can assemble separately then link to form the entire program.
With this method, if you must change one program section. you do not
have to reassemble the entire program.
When using the RMA to develop assembly-language programs, follow
these steps:
1.
Create a source program file using a text editor, such as the OS-9
Level Two screen editor, Scred.
2.
Run the RMA to translate the source file(s) to relocatable object
module(s).
3.
If the assembler reports any errors, correct the source files and
reassemble.
4.
Run RLINK to combine the relocatable object modules(s).
5.
If RLINK reports any errors, correct the source files, reassemble,
and relink.
6.
Run and test your program. You can use the Interactive Debugger
to help you with this step. Correct errors, if any.
You now have an executable assembly-language program.
2·1
Relocating Macro Assembler
General Information / 2
Source File Format
The assembler reads its input from the specified source file. This
source file contains variable-length lines of ASCII characters. You
can create the source file using any text editor, such as Scred.
Each line of the source file is a text string terminated by an end-ofline character (carriage return). The maximum length for a line is 256
characters. Each line can have from one to four fields, which are:
•
Label field (optional)
•
Operation field
•
Operand field (for some operations)
•
Comment field (optional)
You can specify an entire line as a comment by placing an asterisk (*)
as the first character of the line.
Note: The assembler ignores any blank lines in the source
file.
The Label Field
The label field begins at the first character position of the line. Some
statements require labels (for example, EQU and SET); others must not
have them (for example SPC and TTL).
If a label is present, the assembler usually defines the label as the
program address of the first object code byte generated for the line.
Exceptions occur in the SET, EQU, and RMB statements. In the SET
and EQU statements, the assembler gives the label the value of the
result of the operand field. In the RMB statement, it gives the current
value of the data address counter.
The label must be a legal symbolic name consisting of from one to
eight upper or lowercase characters. Letters, numbers, dollar signs
2-2
Relocating Macro Assembler
General Information / 2
($), dots (.), and underline characters C) are all allowed. The first
character must be a letter. You must not define a label more than once
in a program (except when using it with the SET directive).
If you follow the symbolic name in a label field with a colon (:), the
RMA makes the name globally known to ail modules that are linked
together. In this way, you can execute a branch or jump to a label in
another module. If you do not place a colon after the label, that label
is known only in its own PSECT .
If a line does not contain a label, the first character must be a space.
The Operation Field
The operation field specifies the machine-language instruction or
assembler directive statement mnemonic name. Use one or more
spaces between it and the label field.
Some instructions include a register name (such as LDA, LDD, or
LDU) in the operation field. In these cases, you cannot separate the
register name from the rest of the field with a space. The RMA accepts
instruction mnemonic names in either upper- or lowercase characters.
Instructions generate from one to five bytes of object code depending
on the specific instruction and address mode. Some assembler
directives (such as FCB and FCC) also cause the assembler to generate
object code.
The Operand Field
The operand field follows the operation field. You must separate the
two fields by at least one space. Some instructions do not use the
operand field; other instructions and assembler directives require an
operand to specify an addressing mode, operand address, parameters,
and so on.
2-3
Relocating Macro Assembler
General Information j 2
The Comment Field
The comment field is the last field of a source statement. It is an
optional field you can use to include a comment about the instruction.
The RMA does not process this field but copies it to the program
listing.
The Assembly Listing Format
If you specify the -1 option with the RMA, the assembler generates a
formatted assembly listing. The output listing uses the following
format:
0098
0032 59
+
rolb
00117 0045=17ffb8
copyit , '-------'
Ibsr dmove
' - - _....., L.....I.
,copy result
1Lab! m,,",,~:~e~:l area
L..'_ _- - - '
macro expansion indicator
Object code bytes
external reference indicator
location counter value
listing line number
Evaluation of Expressions
Operands of many instructions and assembler directives can include
numeric expressions in one or more places, The assembler can
evaluate expressions of almost any complexity using a form similar to
the algebraic notation used in programming languages such as BASIC
and FORTRAN.
An expression consists of an operand and an operator. An operand is
a symbolic name and an operator specifies an arithmetic or logical
function. All assembler arithmetic uses 2-byte (16-bit binary
2-4
Relocating Macro Assembler
General Information f 2
internally) signed or unsigned integers in the range of 0 to 65535 for
unsigned numbers, or -32768 to +32767 for signed numbers.
In some cases, the assembler expects expressions to produce a value
that fits in one byte, such as 8-bit register instructions. Such values
must be in the range 0 to 255 for unsigned values and -128 to +127 for
signed values.
If the result of an expression is outside its range, 05-9 returns an error
message.
OS-9 evaluates expressions from left to right using the algebraic order
of operations. That is, it performs multiplication and divisions before
addition and subtraction. You can use parentheses to alter the natural
order of evaluation.
Expression Operands
You can use the following items as operands within an expression:
decimal numbers
A positive or negative value containing one to five digits (values are
in the range of -32768 through
+32767). Examples:
100
-32767
o
12
2-5
General Information / 2
Relocating Macro Assembler
hexadecimal numbers
The dollar sign ($) followed by one
to four hexadecimal characters (0-9,
A-F, or a-f). Examples:
$ECOO
$1000
$3
$0300
binary numbers
Percent sign (%) followed by one to
16 binary digits (0 or ]). Examples:
%0101
% 1111000011110000
%10101010
%11
character constants
Single quotation mark (') followed
by any printable ASCII character.
Examples:
'X
'c
'5
T
symbolic names
One to nine characters, the first
character must be a letter. Legal
characters are upper- and lowercase
letters (A-Z. a-z), digits (0-9), and
the special characters underscore
C), period C.), dollar sign ($), and
"at" (@).
instruction counter
Placed at the beginning of the expression, the asterisk (*) represents
the program instruction counter
value.
2-6
Genera/Information I 2
Relocating Macro Assembler
Expression Operators
The following list shows the available operators in the order in which
OS-9 evaluates them. Operators listed on the same line have identical
precedence. 05-9 processes them left to right when they occur in the
same expression.
Assembler Operators By Order of Evaluation
&
*
+
negative
logical AND
multiplication
addition
/I
logical NOT
logical OR
division
subtraction
Logical operations are performed bit-by-bit for each bit of the
operands.
Division and multiplication functions expect unsigned operands, but
subtraction and addition accept signed (2's complement) or unsigned
numbers. 05-9 returns an error if you attempt to divide by 'Zero or
multiply by a factor that results in a product larger that 65535.
Symbolic Names
A symbolic name consists of one to nine lower- or uppercase
characters, decimal digits, or the special characters dollar sign ($),
undescore C}, period (.), or the at (@). The first character in a
symbolic name must be a letter. Some examples of legal symbolic
names are:
HERE
Q1020.1
there
t$lnteger
SPL030
L123.X
Note: The RMA does not convert lowercase characters to
uppercase. The names file_A and FILE_A are unique names.
2·7
Relocating Macro Assembler
Genera/Information / 2
The following are examples of illegal symbol names:
2move
The first character is not a letter.
maln.backup
There are more than nine characters.
Ibl#123
The number sign (#) is not a legal character.
You define a name the first time you use it as a label in an instruction
or directive statement. You can define a name only once in a program
(except if it is a SET label). OS-9 returns an error message if you
attempt to redefine a name.
If you use an undefined symbolic name in an expression, the RMA
assumes the name is external to the PSECT. The RMA records
infonnation about the reference so the linker can adjust the operand
accordingly.
Note: You cannot use external names in operand expressions
for assembler directives.
Symbolic Names for System Calls
A system-wide assembly language equate file called OS9defs.a
defines the RMA symbolic names for all system calls. You can include
this file when the RMA assembles hand-written or compiler-generated
code by using the USE a'isembler directive (see Chapter 6). The RMA
has a built-in macro that generates the system calls from the symbolic
names.
Symbolic System names can also be resolved by using sys.l in the LIB
directory with RLINK. This chapter contains additional information
on the LIB Directory. Chapter 9 discusses RLINK.
2-8
General Information / 2
Relocating Macro Assembler
The DEFS Directory
The OS9defs.a file contains the following groups of defined symbols:
System Service Request Code definitions
I/O Service Request Code definitions
File access modes
Signal codes
Status codes for GetStatlPutStat structure formats
Module definitions
Universal module offsets
Type-dependent module offsets
System module
File manager module
Device driver module
Program module
Device descriptor module
Machine characteristics definitions
Error code definitions
System dependent error codes
Standard 05-9 error codes
To view the contents of the OS9defs.a file, which includes a brief
description of each symbol name, use the 05-9 LIST command. For
example, if your OS-9 Level Two Development Pack Diskette I is in
the current drive, type:
list IdO/defs/os9defs.a
Or send the file to your printer by typing:
list IdO/defs/os9defs.a > Ip
To include the OS9defs file with your source code when assembling a
file, you can use the following statements:
[Ipl
use os9defs.a
endc
2-9
Relocating Macro Assembler
General Information! 2
However, OS9Defs.a provides the assembly source from which Sys.l
is created (see the following section "The LIB Directory"). In many
cases, using Sys.l requires less memory and processes faster.
For programmers who prefer to use the OS-9 Level One ASM program
for writing code, the DEFS directory contains four other files:
Defsfile. Defsfile.dd. OS9defs. and Systype. These four files contain
Level Two infonnation but are in the fonnat required by ASM.
Also included in the DEFS directory are Wind.h, Stdmenu.h, Mouse.h,
and Buffs.h. These four files contain Level 2 data structures for
window, menu, mouse, and buffer manipulation using the C language.
The LIB Directory
Two 05-9 library files are also included in the Lm directory on
Diskette 1 of your Development Pack. The files are:
cgfx.l
that provides Level Two graphics routines for the C
language
sys.l
the system library--defines the standard symbolic
references (error messages, 1$ and F$ system calls, and so
on). Use with RLINK to resolve references rather than the
USE instruction in your source code.
For instance. to link a program called Updn (see Chapter
11, "Examples"), you could type:
RLINK RELS/UPDN.R -1",ldOlllblsys.l -o=/dO/cmdsfupdn
_ __
- - - - - - - - - - - - - - - - - - - - _ . ..
2·10
._--~---
Chapter 3
Macros
At times, you might need to use an identical sequence of instructions
more than once in a program, such as a routine to display messages to
the screen. Instead of repeating the routine in your program, you can
create a macro that you can call just like any other assembly-language
instruction.
A macro defines a set of instructions with a name you assign. Using
this name, you can call the macro as many times as you want. In
addition, you can use macros to create complex constant tables and
data structures. To define a macro, use the MACRO and ENDM
directives. For example, the following macro performs a 16-bit left
shift on the Register D:
dasl
aslb
MACRO
rola
ENDM
The MACRO directive marks the beginning of the macro definition.
The name assigned to the macro is dasl. To use this new macro,
specify dasl as an instruction as shown here:
Idd 12,8
dasl
std 12,s
get operand
double It
savo operand
If the RMA encounters a macro name in the instruction field during
the assembly process, it replaces the macro name with the machine
instructions given in the macro definition. So, when the RMA
encounters the das1 macro name in the instruction field, it outputs the
codes for aslb and rola.
3-1
Relocating Macro Assembler
Macros / 3
Normally, RMA does not expand macros on listings. However, you
can use the -x option to cause it to do so.
Note: Macros are similar to subroutines, but do not confuse
the two. A macro duplicates the routine within your program
every time you call it. It also allows some alteration of the
instruction operands. A subroutine. however, appears only
once within a program and cannot be changed. Also, you call
a subroutine using the special instructions (BSR or JSR).
Generally. using a macro instead of a subroutine produces
longer but slightly faster programs.
Macro Structure
A macro definition consists of three sections: header, body, and
terminator. The macro header marks the beginning of the macro and
assigns the macro's name. The body of the macro contains the
statements. The terminator indicates the end of the macro. The general
format is as Shown here:
name
MACRO
I" macro header -I
body
ENDM
r
macro terminator */
The name is required by the MACRO directive. It can be any legal
assembler label. You can, if you wish, even redefine a 6809 directive,
such as LDA or CLR. by defining a macro with the same name. This
lets you use the RMA as a cross-assembler for non-6809 (8- or 16-bit)
processors by either defining (or re-defining) instructions for the
target CPU.
Note: Redefinition of assembler directives, such as RMB, can
cause unpredictable consequences. Redefine with care.
3-2
Relocating Macro Assembler
Macros /3
The body of the macro contains any number of legal RMA instruction
or directive statements. You can even include references to previously
defined macros. Calling another macro from within a macro is called
nesting. For example:
times4
MAC RD
dasl
dasl
ENOM
This example shows the times4 macro calling the dasl macro twice.
You can nest macros up to eight deep.
Note: You cannot define one new macro within another.
Macro Arguments
By using arguments with your macros, you can vary a macro each time
you call it. You can use arguments to pass operands, register names,
constants, variables, and so on, to the macro. A macro can have as
many as nine arguments in the operand field. An argument consists of
a backslash and an argument number (\1, \2, ...\9).
When the RMA expands the macro, the assembler replaces each
argument with the corresponding tex.t string argument specified in the
macro call. When using arguments within the macro, you can only use
them in the operand field. You can use arguments in any order and
any number of times.
The following example macro performs the typical instruction
sequence to create an OS-9 file:
create
MACRO
leax
Ida
Idb
os9
\1,pcr
#\2
#\3
get addr of filename string
set path number
set file access mode
I$CREATE
ENOM
3-3
Macros /3
Relocating Macro Assembler
The first argument, \1, supplies the filename string address. The
second argument, \2, specifies the path number, and the third, \3, gives
the file access-mode code. The following instruction shows how to
call the create macro with its arguments:
create outname,2,$1 E
RMA expands the create macro like this:
leax outname,pcr
Ida #2
Idb #$1E
059 I$CREATE
Note that if an argument string includes special characters such as
backslashes or commas, you must enclose the string in double
quotation marks. For example, the following instruction calls a macro
called double and passes two arguments:
double CQunt,"2,s"
To declare a null argument, omit the argument and use a comma to
hold its place in the sequence (if necessary). The RMA creates an
empty string. For example:
double count
or
double ,"2,5"
Special Arguments
RMA has two special argument operators that you might find useful
when constructing complex macros. They are:
\Ln
Returns the length of argument n in bytes
\#
Returns the number of arguments passed in a given macro
call
3-4
Relocating Macro Assembler
Macros! 3
Generally, you use these special operators with the RMA's conditional
assembly statements to test the validity of arguments used in a macro
call, or to customize a macro according to the actual arguments
passed. You can use the FAIL directive if you want a macro to report
errors that occur during execution. The following example is an
expanded version of the create macro:
create
MACRO
ifne
FAIL
endc
ifgt
FAIL
endc
leax
\# - 3
must have exactly 3 arguments
create: must have 3 arguments
\L1 - 29
filename can be 1 - 29 characters long
create: filename too long
Ida
\1 ,per
#\2
Idb
#\3
os9
ENDM
I$CREATE
get addr of filename strIng
set path number
set file access mode
Automatic Internal Labels
At times. it might be necessary to use labels within a macro. You can
specify macro-internal labels with \@. If there is more than one label,
you can add an extra character or characters for uniqueness. For
example, if you need two labels with a macro, you might use the
names \@A and \@B. You can add the extra character(s) before the
backslash or after the \@ symbol.
When the RMA expands the code, internal labels (\@) take the form
a decimal number between 000 and 999. For
example, the expansion of the labels \@A and \@B would be \OOIA
and \OOIB. If the macro is called again. the expansion would be \002A
and \002B, and so on.
\@xxx where xxx is
3-5
Relocating Macro Assembler
Macros /3
The following example shows a macro using internal labels:
testcvr MACRO
cmpd
bls
orcc
bra
@A andcc
@B equ
#\1
@A
#1
\@B
#$FE
I
compare to arg
branch if in range
set carry bit
and skip next instruction
crear carry
continue with routine...
ENDM
If you call the lestovr macro with the instruction:
testovr $80
RMA expands the labels in the following way:
cmpd
bls
cree
bra
@OOlA andcc
@OOlB equ
#$80
@OOlA
#1
@OOlB
#$FE
I
compare to arg
branch if in range
set carry bit
and skip next instruction
clear carry
continue with routine...
If you call the testovr macro a second time with:
testovr 240
RMA expands the labels in the following way:
cmpd
bla
orce
bra
@002A andec
@002B equ
#240
@002A
#1
@002B
#$FE
I
compare to arg
branch if in range
set carry bit
and skip next instruction
crear carry
continue with routine...
3-6
Relocating Macro Assembler
Macros/3
Documenting Macros
Although macros are a useful programming tool, you should use them
with care. Indiscriminate use can impair the readability of a program
and make it difficult for other programmers to understand the program
logic. Be sure to document your macros thoroughly.
3·7
Chapter 4
Program Sections
One of the most useful functions of the RMA is that it lets you write
programs in segments that you can assemble separately. You can then
use RLINK to combine the segments into one OS-9 memory module
with a coordinated data storage area.
When writing a program in segments, you must divide it into sections
for variable storage definitions (VSECTs) and sections for program
statements (PSECTs). By using external names, the code in one
segment can reference variables declared in another segment, or can
transfer program control to labels in another segments. The assembler
outputs a relocatable object file (ROF) for each program section. This
object file contains the object code output plus information about the
variable storage declarations for the linker to use.
RLINK reads relocatable object files, and assigns space in the data
storage area. It also combines all the object code into a single
executable memory module. To do this, RLINK must alter the
operands of instructions to refer to the final variable assignments and
must adjust program transfer control instructions that refer to labels in
other segments.
The following shows a simplified memory map after the linker has
processed three program segments (A, B, and C):
4-1
Relocating Macro Assembler
Program Sections I 4
process data area
Segment A Variables
Segment B Variables
Segment C Variables
Executable Memory Module
Module Header
Segment A Object Code
Segment B Object Code
Segment C Object Code
CRC Check Value
Each section in the process data area corresponds to each program
segment's VSECT. RLINK generates the module header and eRe
check values. The Segment A Object Code is the mainline, or
beginning, segment. Each object code segment corresponds to each
program segment's PSECT.
Program Section Declarations
The RMA uses three section directives (PSECT, VSECT, and CSECT)
to control the placement of object code and allocation of variable
space in the program. The ENDSECT directive indicates the end of a
section.
PSECT indicates the beginning of a relocatable object file. PSECT
causes the RMA to initialize the instruction and data location
counters, and assemble subsequent instructions into the ROF object
code area.
VSECT causes the RMA to change the variable (data) location
counters and to place information about subsequently declared
variables in the appropriate ROF data description area. You declare
VSECTs within PSECfs.
4·2
Relocating Macro Assembler
Program Sections /4
CSECT initializes a base value for assigning sequential numeric
values to symbolic names. CSECTS are provided for convenience
only. Their use is optional.
The RMA maintains the following counters within each section:
Directive
Counter
PSECf
instruction location counter
VSECT
initialized direct page counter
non-initialized direct page counter
initialized data location counter
non-initialized data location counter
Because the source statements within a certain program section cause
the linker to perform a function appropriate for the statement, the type
of mnemonic allowed within a section is sometimes restricted. However, the following mnemonics can appear inside gr outside any
section: nam, opt, ttl, pag, spc, use, fail, rept, endr, ifeq, ifne, iftt, ifte,
ifge, ifgt, ifpl, endc, else, equ, set, macro, endm, and endsect.
4-3
Chapter 5
Program Section Directives
PSECT Directive
The PSECT directive specifies the beginning of a program code
section. You can specify only one PSECT for each assembly-language
file. The PSECT directive initializes all assembler location counters
and marks the start of the program segment. You must declare all
instruction statements and VSECT data reservations (RMB) within the
PSECT/ENDSECT block.
The syntax for the PSECT directive is:
PSECT name,typeJang,attrrev,edition,stacksize,entry
If the program section is to be a mainline segment, you can specify the
name and five expressions as an operand list to PSECT. The RMA
stores the values of the operand list in the relocatable object file for
later use by the linker. If you omit the operand list, PSECT defaults to
the name Program and all expressions default to zero. The following
list describes the available expressions:
name
Used by the linker to identify the PSECT. The name
can be up to 20 bytes long and can consist of any
printable characters, except the space and comma.
The name does not need to be unique; however, it is
often easier to identify PSECTs when their names are
distinct.
typelang
Used by the linker as the executable module
type/language byte. If the PSECT is not a mainline
segment, typelang must be zero.
5-1
Relocating Macro Assembler
Program Section Directives I 5
attrrev
Used by the linker as the executable module
attribute/revision byte.
edition
Used by the linker as the executable module edition
byte.
stacksize
Used by the linker as the amount of stack storage
required by the PSECf. Specify stacksize as a word
expression. The linker adds the value in all PSECTs
that make up the executable module and adds the
total to any data storage requirement for the entire
program.
entry
Used by the linker as the program entry point offset
for the PSECf. Specify entry as a word expression. If
the PSECT is not a mainline segment. this value must
be zero.
Statements that you can use in a PSECT are: any 6809 mnemonic, fcc,
fdb, fes, fdb, rzb, vsect, endsect, os9, and end. Note that you cannot
use RMB in a PSECT.
Note: If you are familiar with the OS-9 Level J Interactive
Assembler, note the following difference between the RMA's
PSECT directive and the Interactive Assembler's MOD
statement. The MOD statement directly outputs an 05-9
module header, but PSECT only sets up information for the
linker. The linker creates the module header.
Example
• this program starts a baslc09 process
ifp1
use ....Idefs/os9defs.a
endc
PRGRM equ
OBJeT equ
$10
$1
5-2
Relocating Macro Assembler
Program Section Directives I 5
stk
equ 200
psect rmatest,$11 ,$61 ,O,stk,entry
name
fcs
prm
feb
prmsize ·.prm
entry
leax
leau
Idy
Ida
elrb
os9
os9
os9
endsect
Ibasic091
$d
name,pcr
prm,pcr
#prmslze
#PRGRM+OBJCT
F$FORK
F$WAIT
F$EXIT
VSECT Directive
The VSECT directive indicates the variable storage section, which can
contain either initialized or non-initialized variable storage definitions. The VSECT directive causes the RMA to change the data
location counters. The RMA offers two sets of counters for each
VSECT; one set for direct page variables and another for variables
that are nonnally index-register offsets into a process's data storage
area.
The syntax for a VSECT directive is:
VSECT lOP]
If you specify the DP operand, the RMA uses the direct page counters.
If you omit DP, the RMA uses the index register counters.
You can specify any number of VSECT blocks within a PSECT. Note,
however, that the data location counters maintain their values from
one VSECT to the next. Because the linker handles the actual data
allocation, there is no facility to adjust the data location counters.
5-3
Program Section Directives / 5
Relocating Macro Assembler
Statements that you can use within a VSECf are: nnb, fcc, fdb, fes,
feb, rzb. and endsect. The fcc, fdb, feb, fcs. and rzb directives place
data into the initialized data area. Programs move initialized constants
which appear inside a VSECT from the data section to the program
section for accessing by the 6809 program counter relative addressing
mode. Initialized constants can appear outside of a VSECT; however,
if they do, the program cannot change them.
Example
ifpl
use ....Idefs/os9defs.a
endc
PRGRM EQU
OBJeT EQU
$10
$1
stk
200
EQU
PSECT pgmlen,$ll ,$81,D,stk,start
• data storage declarations
VSECT
temp
RMB
1
addr
RMB
2
buffer RM B
500
ENDSECT
start
loop
leax
clr
inc
Idd
clr
subd
bne
butfer,U get address of buffer
temp
temp
#500
loop count
,x...
#1
loop
089
F$EXIT return to 089
ENDSECT
5-4
Program Seccion Direccives I 5
Relocacing Macro Assembler
CSECT Directive
The CSECf directive provides a method for assigning consecutive
offsets to labels without resorting to EQUs.
The syntax for the CSECT directive is:
CSECT expression
If you specify an expression, the RMA sets the CSECT base counter to
the specified value. If you do not include an expression, the RMA uses
a base counter value of zero.
Example
* This CSECT assigns offsets of 0,1, and 2 respectively.
CSECT 0
R$CC
R$A
R$B
RMB1
RMB1
RMB1
Condition code register
A accumulator
B accumulator
ENDSECT
See the Defs file that is included in the 059 Development diskette for
more CSECT examples.
5-5
Chapter 6
Assembler Directive Statements
Directive statements give the assembler information that affects the
assembly process, but they do not generate code. Read the descriptions in this chapter carefully. Some directives require labels. some
allow optional labels, and a few cannot have labels.
END Statement
The B-,'D statement indicates the end of a program. The syntax for
END is:
END
You cannot use a label with the END statement
Because the RMA assumes the end of file when it encounters an endof-file condition on the source file, the END statement is optional.
EQU and SET Statements
The EQU and SET statements let you assign a value to a symbolic
name (label). The syntaxes for these statements are:
label EQ U expression
label SET expression
The label is required. You can specify expression as an expression, a
name, or a constant.
6·1
Relocating Macro Assembler
Assembler Directive Statements /6
EQU lets you define symbols only once in the program. Usually, you
use EQU to define program symbolic constants, especially those useo:
with instructions. It is a standard programming practice to place all
EQUs at the beginning of the program.
When using EQU, the label must be unique, and you must define the
expression if you specify a name.
SET lets you redefine a symbol as many times as you want. Usually,
you use SET to define symbols used to control the assembler operations, such as conditional assembly and listing control.
Example
FIVE
OFFSET
EQU
EQU
address-base
TRUE
EQU
EQU
SET
$FF
ifne
use
SUBSET
subset.defs
FALSE
SUBSET
5
0
TRUE
else
SUBSET
use
endc
set
full.defs
FALSE
FAIL Statement
The FAIL statement forces the RMA to report an assembler error.
Generally, you use FAIL with conditional assembly directives that test
for various illegal conditions. The syntax for the FAIL statement is:
FAIL textstring
The RMA displays the textstring operand in the same manner as
normal RMA-generated error messages. Because the RMA assumes
the entire line after the FAIL keyword to be the error message, you
cannot specify a comment field.
6-2
Assembler Directive Statements 16
Relocating Macro Assembler
Example
ifeq
FAIL
ende
maxval
maxval cannot be zero
IF, ELSE, and ENDC Statements
The IF, ELSE, and ENDC statements let you selectively assemble (or
not assemble) one or more parts of a program, depending on the value
of a variable or computed value. The syntaxes for these statements
are:
IFxx
expression
statements
ELSE
statements
ENDC
When the RMA processes an IF statement, it makes the desired
comparison. If the comparison result is true, the RMA processes the
statements following tile IF statement until it finds an ENDC or ELSE.
The ELSE statement is optional. If the RMA encounters an ELSE
statement, it processes the statements following the ELSE if the result
of the comparison is false.
The ENDC statement marks the end of a conditional program section.
There are several available IF statements:
lFEQ
IFNE
IFLT
IFLE
IFGT
IFGE
IFPI
True if operand equals zero
True if operand does not equal zero
True if operand is less than zero
True if operand is less than or equal to zero
True if operand is greater than zero
True if operand is greater than or equal to zero
True only during the assembler's first pass (no operand)
6·3
Relocating Macro Assembler
Assembler Directive Statements I 6
Examples
In the following example, IFEQ tests if the operand is equal to zero:
IFEQ
Idd
leax
SWITCH
#0
l,x
assembled only if SWITCH=O
ENOC
The following example adds the ELSE condition to the preceding
program:
IFEQ
SWITCH
Idd
leax
ELSE
#0
1,x
assembled only if SWITCH=O
Idd
#1
-l,x
assembled only if SWITCH does not equal 0
leax
ENDC
You can use IF statements to test the result of a arithmetic evaluation
as an operand. This example tests to see if the result of the subtraction
of MIN from MAX is less than or equal to z.ero:
JFLE MAX-MIN
The IFFI statement tells the RMA to process subsequent statements
during the first pass only. You can use this for program sections that
contain only symbolic definitions to be processed only once during
the assembly. Because they do not generate actual object code output,
the symbolic definitions are processed during Pass 1 only. The
OS9Defs file is an example of a large section of slich definitions. For
example, you can use the following statements at the beginning of
many source files:
IFPl
use
ENDC
Ido/defs/OS9Defs
6-4
Relocating Macro Assembler
Assembler Directive Statements / 6
NAM and TTL Statements
The NAM and 1TL statements let you define or redefine a program
name or listing title line, respectively. The RMA prints this
information on each listing page header.
The syntaxes for NAM and TTL are:
NAM string
TTL string
You cannot specify a label with these statements.
The RMA prints the program name, set by NAM, on the left side of the
second line of each listing page. The RMA then prints a dash, and the
title line, set by TTL. You can change the program name and listing
title as often as you like.
Example
NAM Datae
TTL Data Acquisition System
This example prints the following information in the listing header:
Datae - Data Acquisition System
OPT Statement
The OPT statement lets you set or reset any of several assembler
control options. The syntax is:
OPT option
The operand option can be any of the assembler options described in
Chapter 1 of this manual. It consists of one character, except for the d
and w options, which require a number. Do not specify - or -- in the
OPT statement.
You cannot use the label or comment fields with the OPT statement.
6-5
Relocating Macro Assembler
Assembler Directive Statements / 6
Examples
The following statement suppresses the listing generation:
OPTI
The next example sets the line width to 72 charac '~rs:
OPTw72
P AG and SPC Statements
The PAG and SPC statements let you improve the readability of a
program listing by starting a new page or inserting blank lines. The
syntaxes for the statements are:
PAG
SPC expre~~ion
The P AG and SPC statements cannot have a label field.
The PAG statement causes the RMA to begin a new page in the listing.
For Motorola compatability you can also use the alternate form,
PAGE.
The SPC statements inserts blank lines in the listing. The operand
expression specifies the number of blank lines to be inserted. The
expression can be an expression, constant, or name. If you
omit the expression, the RMA inserts one blank line.
REPT and ENDR Statement
REPT and ENDR let you repeat the assembly of a sequence of
instructions a specified number of times. The syntaxes are:
REPT expression
statements
ENOR
6-6
Relocating Macro Assembler
Assembler Directive Statements 16
The operand expression specifies the number of times the assembly
is to be repeated. The expression cannot include EXTERNAL or
undefined symbols. You cannot nest REPT loops.
Example
* make module size exactly 2048 bytes
REPT
2048-*-3
compute fill size w/crc space
feb
0
ENDA
emod
* 20-cycle delay
REPT
nop
nop
ENDR
5
RMB Statement
The RMB statement has two uses. When used within a VSECT, RMB
declares storage for non-initialized variables in the data area. When
used within a CSECT, RMB assigns a sequential value to the symbolic
name given as its label. The syntax for RMB is:
label
RMB expression
When using RMB in a VSECf, specify a label that is assigned the
relative address of the variable. In OS-9, the address must not be
absolute and you should usually use indexed or direct page
addressing modes to access variables. The linker assigns the actual
relative address when processing the relocatable object file. It adds
the operand, expression to the address counter to update them.
When using RMB in a CSECf, specify a label to which you assign the
value of the current CSECT location counter. Doing this, then updates
the counter by causing the program to add the result of the expression
given.
6-7
Relocating Macro Assembler
Assembler Directive Statements 16
USE Statement
The USE statement causes the RMA to temporarily stop reading the
current input file. USE requests that OS-9 open and read input from
the specified file/device until an end-of-file occurs. OS-9 then closes
the new input file, and the RMA resumes processing at the statement
following the USE statement. The syntax is:
USE path/ist
The path/ist specifies the new input file or device. You cannot specify
a label with the USE statement.
You can nest as many USE statements as you can have open files at
one time (usually 13, not including the standard I/O paths).
Example
To accept interactive input from the keyboard during the assembly of
a disk file, use the following statement:
USE !term
6-8
Chapter 7
Pseudo-Instructions
Pseudo-instructions are special assembler statements that generate
object code, but do not correspond to actual 6809 machine
instructions. Their primary purpose is to create special sequences of
data to be included in the program. Labels are optional on pseudoinstructions.
FeB and FDB Statements
The FCB and FDB pseudo-instructions generate sequences of
constants within the program. The syntaxes for these pseudoinstructions are:
FeB expression, [eJl"pression, ... l
FOB expression, [expression, .•.]
Expression can be any legal expression. You can specify more than
one expression by separating them with commas.
FCB generates a sequence of single constants in the program. It
reports an error if an expression has a value that is greater than 255 or
less than -128.
FDB generates a sequence of double constants in the program. If FDB
evaluates an expression with an absolute value of less than 256, the
high-order byte is zero.
If FeB or FDB appears within a VSECT, the RMA assigns the data to
the appropriate initialized data area (DP or non-DP). Otherwise, the
RMA places the constant in the code area. If the constant contains an
EXTERNAL reference, the program, using Roota, must copy out and
adjust the references.
7-1
Relocating Macro Assembler
Pseudo-Instructions / 7
Examples
FeB
1,20,'A
index/2+1,0,0,1
FOB
FOB
1,10,100,1000,10000
$F900,$FAOO,$FBOO,$FCOO
FeB
FCC and FCS Statements
The FCC and FCS pseudo-instructions generate a series of bytes
corresponding to the specified character string. The syntaxes are:
FCC string
FCS string
FCS is the same as FCC except that the most significant bit (the sign
bit) of the last character in the string is set. This is a common OS-9
programming technique to indicate the end of a text string without
using additional storage.
String must be enclosed in delimiters. You can use the following characters as delimiters:
!"#$%&O·+,-·I
The beginning and ending delimiters must be the same character. The
delimiting character cannot appear in the character string.
FCC and FCS output bytes that are the literal numeric representation
of each ASCII character in the character string.
If FCC or FCS appear in a VSECT, the RMA assigns the data to the
appropriate initialized data area (DP or non-DP). Otherwise, the RMA
places the constant in the code area.
7-2
Pseudo-Instructions / 7
Relocating Macro Assembler
Examples
FCC
FCS
FCS
FCC
FCS
Ithis is the character stringl
,01234567899,
AA
null string
$z$
....
null string
RZB Statement
The RZB pseudo-instruction fills memory with a sequence of bytes,
each of which has a value of zero. The syntax is:
RZB expression
The expression is a 16-bit expression. The RlviA evaluates the
expression and places that number of zero bytes in the appropriate
code or data section.
OS9 Statement
The OS9 pseudo-instruction is a convenient way to generate 05-9
system calls. The syntax is:
059 expression
The RMA uses the expression value as the request code. The following instruction sequence is the equivalent to the OS9 pseudoinstruction:
SWI2
FCB operand
The OS9Defs file contains the standard definitions of the symbolic
names of all the OS-9 service requests. You can use these names with
the 059 pseudo-instruction to improve the readability and portability
of assembly-language software.
7·3
Relocating Macro Assembler
Pseudo-Instructions /7
Examples
099
I$READ
call 05-9 READ service request
059
F$EXJT
call 05-9 EXIT service request
7·4
Chapter 8
Accessing the Data Area
In general, the RMA assumes that the program will access data using
indexed or direct page addressing modes. By convention, one index
register contains the starting address of the data area, and the direct
page register contains the page number of the lowest-address page of
the data area. The RMAIRLINK system automatically adjust operands
of instructions, using indexed and direct page addressing modes.
The RMA accesses the data area differently depending on whether or
not your program uses initialized data. Initialized data is data that has
an initial value that is modified by the program. You create initialized
data with the FeB, FDB, FCC and similar directives used in a VSECT.
If you do not use initialized data, the RMA accesses program data
using index registers--this is the method used by the OS-9 Level I
Interactive Assembler.
Using Non-Initialized Data
Programs that do not used initialized data declare all data storage in
VSECTs using RMBs. The following diagram shows how the RMA
sets up the data memory area and registers for a new process:
<J- Y (highest address)
parameter area
data area
direct page
<J- X, SP
<]-- U, DP (lowest address)
8-1
Relocating Macro Assembler
Accessing the Data Area /8
When OS-9 executes a process, the MPU Registers contain the bounds
of the data area. Register U contains the beginning address and
Register Y contains the ending address. OS-9 sets the SP register to
the ending address + 1, unless you use a parameter. The direct page
register contains the page number of the beginning page. If you used
no parameters, Y, X, and SP are the same value. The OS-9 Shell always
passes at least an end-of-line character in the parameter area.
If Register U is maintained throughout the program, you can use
constant-offset-indexed addressing.
You can write part of the program's initialization routine to compute
the actual addresses of the data structure and store these addresses in
pointer locations in the direct page. Then, obtain the addresses later
using direct-page addressing mode instructions.
Note: Because the memory addresses assigned
program section and the address section are not
distance apart, you cannot use program-counter
addressing to obtain the address of objects in the data
to the
a fixed
relative
section.
Using Initialized Data
If you plan to use initialized data, you need to copy the data from the
initialized data section in the object module to the data storage area
pointed to by the Register U. Do so by using the Root.a mainline
module (object code that is directly executable by using the OS-9
F$FORK). The function of the Root.a mainline module is to use the
initializing values and offsets of the initialized data location, stored in
the object code module, to actually initialize variables. The linker
automatically generates the initialization information area of the
object code module based on information passed by the RMA in the
relocatable object file.
Root.a sets Register Y to point to the same location to which Register
U pointed. Register X points to the parameter area, and Register U
points to the top of data allocated by the linker. The data-index
8-2
Relocating Macro Assembler
Accessing the Data Area / 8
register choice is arbitrary, but use your choice consistently. To
maintain compatibility with code produced by the C compiler,
Register Y is used as the data pointer. For more information on Root.a,
study the commented source code supplied on the distribution
diskette. The following diagram shows how the RMA sets up the data
area:
Process Data Area Layout
parameters
stack
free memory
requested memory
<l-U
uniniti alized data
initialized data
unitiaJjzed direct page
initialized direct page
<J-Y,DP
Process Object Code
M 0 d ue
I L ayout
CRC Check Bytes
Initializing Data Offsets
Initializing Data Values
Additional (user)
Executable PSETS
Mainline PSET
(RooLa)
Standard OS-9
] <I- U"d by Root.'
<J- PC (this area)
<J- Program entry poim
Module Header
8-3
Chapter 9
Using the Linker
The Relocating Macro Assembler lets you write and assemble
programs separately and then link them to form a single object code
OS-9 module. The linker, RLINK, combines relocatable object files
(ROF) into a single OS-9 format memory module. It also resolves
external data and program references. Because RLINK allows
references to occur between modules, you can write one program that
references a symbol in another program.
If the RMA encounters an external reference during the assembly
process, it sets up information denoting the existence of an internal
reference. The RM:A does not know the location of the external
reference.
Because the RMA is a relocatable assembler, it produces relocatable
object files that do not have absolute addresses assigned. The RMA
assembles each section with the absolute address O.
RLINK reads in all the relocatable object files and assigns each an
absolute memory address for data locations and instruction locations
for branching. 05-9 resolves any other addresses at execution time.
By using the RMA and RLINK, you can write programs in smaller
sections that are easier to read and debug. In this way, if an error
occurs, you need edit and reassemble only the module in which the
error occurred. Then, you can relink the fixed module with the rest of
the pro gram.
9-1
Relocating Macro Assembler
Using the Linker /9
Running the Linker
You call the linker, RLINK, with the following command line:
RLiNK [options] mainline [sub1.... subn] [options]
All input files must be in relocatable object format (ROF).
Mainline specifies the pathlist of the mainline (first) segment from
which RLINK resolves external references and generates a module
header. It is the object of the mainline file to perform the initialization
of data and the relocation of any initialized data references within the
initialized data, using the information in the object module supplied
by RLINK (See Chapter 7.) You indicate that a program is the
mainline module by setting the typel/ang value in the PSECT directive
to a non-zero value.
The subl and subn options represent any additional modules to be
linked to the mainline module. The additional ROFs cannot contain a
mainline PSECT notation (typeflang>O).
RLINK includes the mainline file and all sub-modules in the final
linked object module, even if you did not reference the subroutine.
Available Options
You can use any of the following options on the RLINK command
line:
-o=path
Writes the linker object (memory module) output to
the file specified by the pathlist. RLINK assumes the
last element in the pathlist to be the module name
unless you use the -n option.
-n=name
Specifies name as the object file.
9·2
Relocating Macro Assembler
Using the Linker /9
.l""path
Specifies path as the library. A library file consists of
one or more merged assembly ROPs. The assembler
checks each PSECT in the file to see if it resolves any
unresolved references. If so, RLINK includes the
module in the final output module. Otherwise, RLINK
skips the file. RLINK searches library files in the
order in which you specify them on the command
line. A library file cannot contain a mainline PSECT.
-E=n
Sets the edition number in the final output module to
n. You can also use -e (lowercase).
-M=size
Sets the number of pages of additional memory for
C.LINK to allocate to the data area of the final object
module. If you omit this option. C.LINK adds up the
total data stack requirements found in the PSECT of
the input modules, and uses that value.
-m
Prints the linkage map that indicates base addresses
of the PSECTs in the final object module.
-s
Prints the final addresses that RLlNK assigned to
symbols in the final object module.
-b=ept
Links C-language functions so that they can be called
from BASIC09. The argument ept specifies the name
of the function to which control is transferred when
BASIC09 executes a RUN command.
-t
Allows static data to appear in a BASIC09 callable
module. RLINK assumes that the C function being
called and the calling BASIC09 program provide a
sufficiently large static storage data area pointed to
by Register Y.
9-3
Chapter 10
Error Messages
When the RMA detects an error during assembly, it prints an error
message in the listing just before the source line containing the error.
In some ca.<;es, the RMA might report more than one error for a source
line. If you do not use the -1 option to produce the listing, the RMA
still prints the error messages and the problem source line. At the end
of the listing, the RMA reports the total number of errors and warnings
in the assembly summary statistics.
The RMA prints all error messages, the associated source line, and the
assembly summary to the assembler's error path. You can redirect this
output using the shell redirection symbol. For example:
RMA sourcefile -o=sourcefile »src.error
During the initial stages of assembly, you might find it useful to
suppress generation of both the listing and object code (by omitting
the -1 and -0 options). Doing this lets the RMA perform a quick
assembly just to check for errors. In this way, you can find and correct
many errors before printing a lengthy listing.
Some errors stop execution on a line. In these cases, the RMA might
not detect all errors that occur on one line; so, make changes
carefully.
The following list shows the RMA error messages and a description
for each message.
Bad label
The label field contains an incorrectly formed label.
10·1
Relocating Macro Assembler
Error Messages I 10
Bad Mnemonic
The mnemonic field contains a mnemonic that the RMA does not
recognize or a mnemonic that is not allowed in the current program
section.
Bad number
The numeric constant definition contains a character that is not
allowed in the current radix.
Bad operand
The operand field is missing an expression or contains an incorrectly
formed operand expression.
Bad operator
The operator contains an incorrectly formed arithmetic expression.
Bad option
An option is not recognized or is incorrectly specified.
Bracket Missing
A bracket is missing from an expression.
Can't open file
The RMA encountered a problem when opening an input file.
Can't open macro work file
The RMA cannot open a macro work file.
10·2
Relocating Macro Assembler
Error Messages I 10
Comma expected
The RMA cannot find an expected comma.
Conditional nesting error
Program contains mismatched IF and ELSE/ENDC conditional
assembly directives.
Constant definition
The statement contains an incorrectly formed constant definition.
DP section???
Direct Page assignments have exceeded 256 bytes.
ENDM without MACRO
The RMA encountered an ENDM statement without a matching
MACRO statement.
ENDR without REPT
The RMA encountered an ENDR statement without a matching REPT
statement.
Fail message
The RMA encountered a FAIL directive.
File close error
An error occurred closing a file.
Illegal addressing mode
The specified addressing mode cannot be used with the instruction.
10-3
Relocating Macro Assembler
Error Messages I 10
Illegal external reference
You cannot use external names with assembler directives. If an
operand expression contains an external name. the RMA can only
perform binary plus and minus operations.
Illegal index register
You cannot use the specified register as an index register.
Label missing
The statement is missing a required label.
Macro arg too long
More than 60 characters (total) were passed to the macro.
Macro file error
The RMA experienced problems when trying to access the macro
work file.
Macro nesting too deep
You can nest macros up to eight levels deep.
Nested MACRO definitions
You carinot define a macro within another macro definition.
Nested REPT
You cannot nest repeat blocks.
10-4
Relocating Macro Assembler
Error Messages /10
New symbol in pass two
This indicates an assembler symbol lookup error. This error can be
caused by a symbol table overflow or bad memory.
No input files
You must specify an input file.
No param for arg
A macro expansion is attempting to access an argument that was not
passed by the macro call.
Phasing error
A label has a different value during Pass 2 than it did during Pass 1.
Redefined name
The name appears more than once in the label field (other than on a
SET directive).
Register list error
The legal register names allowed in tfr, exg, and pul are: A, B, CC, DP,
X, Y, U, S, and PC.
Register size mismatch
The registers specified in the tfr and exg instructions must be the same
size.
Symbol lost?
This indicates an assembler symbol lookup error. This error can be
caused by a symbol table overflow or bad memory.
10·5
Error Messages / 10
Relocating Macro Assembler
Too many args
You can pass up to nine arguments to a macro.
Too many object files
You can specify the
line.
-0
option to the RMA only once on the command
Too many input files
You can specify a maximum of 32 input files.
Undefined org
The
* (program counter org) cannot be accessed within a VSECT.
Unmatched quotes
A quotation mark is missing.
Value out of range
A byte expression value is less than -128 or greater than 255.
10-6
Chapter 11
Examples
The chapter contains two assembly language programming examples:
•
LSIT. to list files
•
UpDn, to convert input case to either upper or lower
*••*******
•
•
•
•
..
..
..
..
LSIT UTILITY COMMAND
A "LIST" Command for poor typists
Syntax: Isit ",path>
Lsit copies Input from path to standard output
NOTE: This command is similar to the
LIST command. Its name was changed
to allow easy assembly and testing
since LIST normally is already in memory.
PRGRM
OBJCT
STK
IPATH
PRMPTR
8UFSIZ
equ
$10
equ
$01
equ
200
csect
rmb
1
rmb
2
rmb
200
endsect
input path number
parameter pointer
size of input buffer
psect list, PRGRM+OBJCT,$81 ,O,STK, LSTENT
BUFFER
READ.
equ
200
allocate line buffer
equ
1 file
access mode
11-1
Examples ( 11
Relocating Macro Assembler
LSTENT
stx
Ida
059
bcs
9ta
stx
LSIT20
Ida
leax
Idy
os9
bC9
Ida
059
bee
bra
LSIT30
cmpb
bne
Ida
os9
bes
Idx
Ida
cmpa
bne
PRMPTR
#READ.
I$Open
LSIT50
IPATH
PRMPTR
save parameter ptr
select read access mode
open input file
exit if error
save input path number
save updated param plr
IPATH
BUFFER,u
#BUFSIZ
I$ReadLn
LSIT30
load input path number
load buffer pointer
max bytes to read
read line of input
exit If error
load st. out path #
output line
repeat if no error
exit if error
#1
I$WritLn
LSIT20
LSIT50
#E$EOF
LSIT50
IPATH
I$Crose
LSIT50
PRMPTR
O,x
#$00
LSTENT
at end of lile?
branch If not
load input path number
close input path
..exil if error
restore param ptr
end of param line?
.. no; list next file
clrb
LSIT50
F$Exit
endsect
059
..terminate
11·2
Relocating Macro Assembler
Examples I 11
* This is a program to convert characters from lower to
* upper case (by using the u option), and upper to lower
• (by using no option). To use type:
* updn u (for lower to upper) -= Input > output
nam
updn
opt
ttl
I
ASSEMBLY LANGUAGE EXAMPLE
PRGRM
OBJeT
equ
equ
$10
$01
stk
equ
250
psect updn,PAGRM+OBJCT,$8t,O,stk,entry
temp
uprbnd
Iwrbnd
entry
Ysect
nnb
1
nnb
1
rrnb
1
endsect
Ida
,X+
anda
.$df
cmpa #'U
beq
cmpa #$00
enlry
bne
Ida
sta
Ida
search parameter area
make upper case
see if a U was input
upper branch to set uppercase
carriage return?
no; go get another char
bra
#'A
Iwrbnd
#'Z
uprbnd
starU
get lower bound
set it in storage area
get upper bound
set It in storage area
go to start of code
upper
Ida
sta
Ida
sta
#'8
Iwrbnd
#'z
uprbnd
get lower bound
set it in storage
get upper bound
set It In storage
start1
leax
Ida
Idy
temp,u
#0
#$01
get storage address
standard input
number of characters
sis
11-3
Relocating Macro Assembler
loop
I$Read
exit
temp
Iwrbnd
write
cmpb uprbnd
bhi
write
eorb #$20
temp
stb
inca
reg 'a'
I$WritLn
os9
deca
loop
bee
empb #E$EOF
bne
exit1
clrb
F$Exit
os9
endsect
clrb
089
bcs
Idb
cmpb
blo
write
exit
exit1
Examples! 11
do the read
exit If error
get character read
test char bound
branch jf out
test char bound
branch if out
flip case bit
put it in storage
standard out
write the character
return to standard In
get char it no error
is it an EOF error
not eot, leave carry
clear carry, no error
error returned, exit
11-4
Appendix A
6809 Instructions
and Addressing Modes
Direct
Extended Index
Immed Accum
Tnher
ReIat
Regis
-------
ABX
ADCA
ADCB
ADDA
ADDB
ADDD
ANDA
ANDB
ANDCC
ASL
ASLA
ASLB
ASR
ASRA
ASRB
(L)BCC
(L)BCS
(L)BEQ
(L)BGE
(L)BGT
(L)BGJ
(L)BHS
BITA
BITB
-----
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
--------
A·l
Relocating Macro Assembler
Direct
6809 Instructions I A
Extended Index
Immed Accum
Inher Relat
(L)BLE
(L)BLO
(L)BLS
(L)BLT
(L)BMI
(L)BNE
(L)BPL
(L)BRA
(L)BRN
(L)BSR
(L)BYC
(L)BYS
CLR
X
X
X
X
X
X
X
X
X
X
X
X
X
CMPA
CMPB
X
X
X
X
CMPD
X
X
CMPS
X
X
CMPU
CMPX
X
X
CMPY
X
X
COM
CWAI
DAA
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
DEC
X
X
X
X
X
X
BORA
EORB
EXG
X
X
X
X
X
X
INC
X
X
X
IMP
ISR
LDA
LDB
LOD
LOS
X
X
X
X
LDU
Regis
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
A·2
Relocating Macro Assembler
Direct
6809 Instructions! A
Extended Index
Immed Accum
LDX
X
X
X
X
LOY
X
X
X
X
X
LEAS
LEAD
LEAX
LEAY
LSL
LSR
!vruL
NEG
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
ORCC
PSHS
PSHU
PlJLS
X
X
X
X
X
X
PULU
ROL
ROR
X
X
X
X
X
X
X
X
X
RTI
X
RTS
SI3CA
SBCB
X
SEX
STA
STB
STS
STIJ
STX
STY
SUB
SUBA
SUBB
Regis
X
X
NOP
ORA
ORB
Inher Relat
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
SWI
X
A-3
Relocating Macro Assembler
6809 Instructions / A
--------
Direct
Extended Index
lnuned Accum
Regis
X
X
X
SWI2
SWl3
SYNC
X
TFR
TST
Inher Relat
X
X
X
X
A-4
Relocating Macro Assembler
----
-----
---
---
Index
--~--
-- -------
! (logical OR) 2-7
& (logical AND) 2-7
>i< (comment) 2-2
*
(multiplication) 2-7
+ (addition) 2-7
- (negative) 2-7
- (subtraction) 2-7
-x option (expand macro listings) 3-2
\ (division) 2-7
\ (macro argument) 3-3 - 3-5
\# (macro argument) 3-4
\@ (macro labels) 3-5 - 3-6
\L (macro argument) 3-4
1\ (logical NOT) 2-7
additional memory, setting 9-3
arguments, macros 3-3 - 3-5
assembling programs 6-3 - 6-4
assembler control options 6-5 - 6-6
assembler error reporting 6-2 - 6-3
assembly location counters 5-1
assembly-language programs, developing 2-1
attributeJrevision byte 5-2
base counter, CSECT 5-5
binary numbers 2-6
blank lines 2-2
body, macro 3-2 - 3-3
1
-~~--
----
Relocating Macro Assembler
Index
C compiler, compatibility 8-3
C-language functions, linking 9-3
cgfx.l file 2-10
character
constants 2-6
string 7-2 - 7-3
code bytes, listing 1-3
colon (global name) 2-3
comment field 2-2, 2-4
comments 2-2
comparison statement 6-3 - 6-4
conditional assembly lines, suppressing 1-3
consecutive offsets to labels 5-5
constants
character 2-6
generating 7-1 - 7-2
counter, instruction 2-6
CSECT 4-2 - 4-3,5-5, 6-7
data
area 8-2
location counters 5-3
storage 8-1 - 8-2
data, initializ.ed 8-2 - 8-3
decimal numbers 2-5
defined symbols 2-9
DEFS directory 2-9 - 2-10
Defs file 5-5
device or file, opening 6-8
direct page
addressing 8-2
register 8-2
variable 5-3
2
Relocating Macro Assembler
Index
directives
CSECf 5-5
ENDSECT 4-2
FArr, 3-5
VSECT 5-3 - 5-4
directive statements 6-1 - 6-8
directory
DEFS 2-9 - 2-10
LIB 2-10
division functions 2-7
double constants 7-1 - 7-2
edition number option 9-3
ELSE statement 6-3 - 6-4
END statement 6-1
ENDC statement 6-3 - 6-4
ENDR statement 6-6 - 6-7
ENDSECf 4-2,5-1
entry point offset 5-2
EQU statement 6-1 - 6-2
error, assembler 6-2 - 6-3
error messages, suppressing 1-3
executable module edition byte 5-2
expanding macro listings 3-2
expression evaluation 2-4 - 2-8
external
data references 9-1 - 9-3
names 4-1
program references 9-1 - 9-3
EXTERN AL reference 7-1
FAn..
directive 3-5
statement 6-2 - 6-3
FCB statement 7-1 - 7-2, 8-1
FCC statement 7-2 - 7-3, 8-1
FCS statement 7-2 - 7-3
3
Relocating Macro Assembler
Index
FDB statement 7-1 - 7-2,8-1
features I - I
field 2-2
file or device, opening 6-8
files to copy 1-2
filling memory 7-3
final address, printing 9-3
format of assembly listings 2-4
global names 2-3
header, macro 3-2
hexadecimal numbers 2-6
IF statement 6-3 - 6-4
lFEQ 6-3 - 6-4
IFGE 6-3 - 6-4
IFGT 6-3 - 6-4
IFLE 6-3 - 6-4
IFLT 6-3 - 6-4
IFNE 6-3 - 6-4
IFPl 6-3 - 6-4
illegal symbolic names 2-8
index-register offsets 5-3, 8-1
initialized data 8-1 - 8-3
input file, reading 6-8
instruction counter 2-6
instructions
repeating 3-1 - 3-7, 6-6 - 6-7
integers 2-5
keyboard input 6-8
label field 2-2
labels (macro) 3-5 - 3-6
LIB directory 2-8,2-10
library path, specifying 9-3
4
Relocating Macro Assembler
Index
line
fields 2-2
maximum length 2-2
lines-per-page, setting 1-3
linking C-language functions 9-3
linkage map, printing 9-3
linker. starting 9-2
linker output 9-2
linking programs 9-1 - 9-3
listing
blank lines 6-6
code bytes 1-3
page 6-6
macro
arguments 3-3 - 3-5
body 3-2 - 3-3
expansion, suppressing 1-3
header 3-2
labels 3-5 - 3-6
terminator 3-2
MACRO directive 3-1
macros, documenting 3-7
memory, filling 7-3
MOD statement 5-2
multiplication functions 2-7
NAM statement 6-5
name, defining 6-5
PSECf 5-1
symbolic 2-6,2-7 - 2-10
nesting macros 3-3
non-initialized data 8-1 - 8-2
null argument (macro) 3-4
5
Relocating Macro Assembler
Index
numbers
binary 2-6
decimal 2-5
hexadecimal 2-6
numeric expressions 2-4
opening files or devices 6-8
operand 2-4
Operand field 2-2,2-3 - 2-4
operands, expression 2-5 - 2-6
operation field 2-2, 2-3
operator 2-4
precedence 2-7
OPT statement 1-3,6-5 - 6-6
options
assembler 1-3, 6-5 - 6-6
RLINK 9-2 - 9-3
OS9 statement 7-3 - 7-4
output, linker 9-2
PAG statement 6-6
page, starting new 6-6
page number 8-2
pointer locations 8-2
precedence of operators 2-7
printing the symbol table 1-3
printer, top-of-form 1-3
program segment 5-1
program statements 4-1
programs, assembling 6-3 - 6-4
PSECT 4-1 - 4-3,5-1 - 5-3, 9-3
statements 5-2
reading input files 6-8
register name 2-3
relocatable object file 2-1,4-1,9-1
repeating instructions 6-6 - 6-7
6
Relocating Macro Assembler
Index
REPT statement 6-6 - 6-7
RLINK 2-8,4-1,9-1 - 9-3
options 9-2 - 9-3
output 9-2
starting 9-2
RMB statement 6-7
Root.a mainline module 8-2
RZB statement 7-3
segments 4-1
setting lines-per-page 1-3
SET statement 6-1 - 6-2
single constants 7-1-7-2
source file 2-2
SPC statement 6-6
specifying
library path 9-3
name, RLINK 9-2
stack storage 5-2
starting
RLINK 9-2
RMA 1-2
statements
ELSE 6-3 - 6-4
END 6-1
El'J"DC 6-3 - 6-4
ENDR 6-6 - 6-7
EQU 6-1 - 6-2
FAIL 6-2 - 6-3
FCB 7-1 - 7-2
FCC 7-2 - 7-3
FCS 7-2 - 7-3
FDB 7-1 - 7-2
IF 6-3 - 6-4
NAM 6-5
OPT 6-5 - 6-6
059 7-3 - 7-4
7
Relocating Macro Assembler
Index
PAG 6-6
REPT 6-6 - 6-7
RMB 6-7
RZB 7-3
SET 6-1 - 6-2
SPC 6-6
TfL 6-5
USE 6-8
statements
directive 6-1 - 6-8
PSECf 5-2
VSECf 5-4
static
data 9-3
storage area 9-3
storage, declare 6-7
storage file s 1-3
string, character 7-2 - 7-3
structure, macro 3-2 - 3-3
suppressing
conditional lines 1-3
error messages 1-3
macro expansions 1-3
symbol table 2-1
printing 1-3
symbolic name 2-2 - 2-3, 2-6, 2-7 - 2-8, 6-1
assigning a sequential value 6-7
symbols
defining 2-9, 6-2
redefining 6-2
Sys.l file 2-10
system calls
symbolic names 2-8 - 2-10
generating 7-3 - 7-4
8
Index
Relocating Macro Assembler
terminator, macro 3-2
text string 7-2 - 7-3
title line 6-5
top-of-form signal 1-3
TTL statement 6-5
type/language byte 5-1
USE statement 6-8
variable storage
definitions 4-1
section 5-3 - 5-4
VSECT 4-1- 4-3, 5-1, 6-7, 7-1-7-2,8-1
directive 5-3 - 5-4
statements 5-4
writing
assembler listing 1-3
output 1-3
9
Utilities
Contents
Chapter 1 I Introduction
1-1
Chapter 2 I Make Utility
Using Make
EXaIUples
What is a Makefile?
Built-in Rules and Definitions
2-1
2-1
Macros
Special Macros
Reserved Macros
COIllIllands
Comments
Long Lines
How Make Works
Notes about Make
Examples of Makefiles
EXaIl1ple 1
EXanlple 2
EXaJllple 3
EXaIllple 4
Example 5
2-3
2-3
2-4
2-5
2~6
2~ 7
2-7
2-8
2-8
2-8
2-9
2-10
2-10
2-11
2-11
2-12
2-13
Chapter 3/ Touch Utility
Examples
3-2
Chapter 4/ Virtual Disk/RAM Disk Driver
4~ I
Initalizing VDD
3-1
4-1
Chapter 1
Introduction
The OS-9 Level Two Development Pack includes three utilities:
•
Make; Helps maintain the current version of software by keeping
track of modifications to program source to determine the need
for recompiling, reassembling, or relinking files.
•
TOllch: Updates the modification date of specified files.
•
Virtual Disk Driver/RAM Disk Driver: Creates a high-speed
storage system in your computer's RAM that simulates a disk
drive.
I-I
Chapter 2
Make Utility
The Make utility helps maintain the current version of software. It
uses built-in knowledge of OS-9 compilers, file types, and file naming
conventions to maintain up-to-date versions of your programs as you
develop them. By keeping track of modifications to program source,
make can determine the need to recompile, reassemble, and/or relink
the files necessary to create an object file.
Using Make
The syntax for Make is as follows:
make options targef1 [fsrget2j [macrosl
The target] argument specifies the program that Make is to create.
Make accepts multiple arguments (target2, rarget3, ... ,and so on). The
macros argument lets you specify macros that Make uses when
creating the new target program.
The options argument can be one of the following:
-?
Displays the usage of Make.
-b
Turns off built-in rules governing implicit file dependencies. Use this option if you are quite explicit about
your makefile dependencies and do not want Make to
assume anything.
-d
Turns on the Make debugger and gives a complete listing
of the macro definitions, a listing of the files as it checks
the dependency list, and all the file modification dates.
2-1
Make Utility ( 2
Utilities
-f[ = Jparh
Specifies path as the makefile. If you omit this option,
Make searches for the file named Makefile in the current
directory.
-f
causes Make to use the standard input instead of a
makefile.
-i
Ignores errors. If you omit this option, Make stops
execution if an error code is returned after executing a
command line in a makefile.
-n
Displays commands to standard output but does not
execute them.
-s
Executes command without echo (silent mode). If you
omit this option, Make echoes commands in the makefile
to standard output.
-t
Touches the files. Make opens the file for update and
then closes it. This updates the modification dates
without executing the commands.
-u
Causes Make to execute the makefile commands.
-x
Uses the cross-compiler/assembler.
-z
Reads a list of Make targets from standard input.
-z=path
Reads a list of Make targets from path.
You can include options on the command line when you run Make or
include them in the rnakefile. You can also define one or more macros
on a command line instead of a makefile or to override a macro definition in a makefile. Enclose in quotes any macro definitions that
contain spaces or other delimiters. See the following section
"Macros".
2·2
Utilities
Make Utility 12
E"amples
make -f/dOfsource/test.make -i test
This Make command creates a program called Test using the makcfile
IdO/source/test.make. Make ignores any errors that occur.
make -s myprog
Make uses the file Makefile in the current directory as the makefile
for the program Myprog. Make does not echo commands during
execution.
What is a Makefile?
A makefile is a special type of procedure file that describes the
dependencies between files that make up the target program. The
makefile contains a sequence of entries that specifies dependencies
and commands to resolve the dependencies. A dependency entry
begins with the target name of the file or module followed by a colon
(:). This is then followed by a list of files that are prerequisites to
building the target file. This is called a dependency list.
In addition to the dependency entry, the makefile can contain
commands on how to update a particular target file (if it needs to be
updated). Make updates a target file only if it depends on files that
are newer than the target file. If Make cannot find the file, it assumes a
date of ~Ol/OO/OO 00:00, indicating that the file needs updating. If you
do not specify update instructions, Make attempts to create a command line to perform the operation. Make recognizes a command line
because it begins with one or more spaces.
The following is a sample makefile:
program; xxx.r yyy.r
cc xxx.r yyy.r -xf;;;program
xxx.r: xxx.c IdO/defs/oskde1s.h
cc: xxx.c ·r
yyy.r: yyy.c IdO/defs/oskdets.h
cc: yyy.c·r
2-3
Make Utility r2
Utilities
This makefile specifies that the target file program is made up of two
relocatable files (.r suffix): xxx.r and yyy.r. These files are dependent
upon xxx.c and yyy.c, respectively, and both files are dependent on the
file oskdefs.h.
If either xxx.c or IdOldefsloskdefs.h has a more recent modification
date than xxx.r, Make executes the command cc xXX.c -r. Likewise, if
either yyy.c or IdOldefs/oskdefs.h has a more recent modification date
than yyy.r, Make executes the command cc yyy.c -T. If either of the
former commands is executed, Make also executes the command cc
xxx.r yyy.r -xf=program.
Built-in Rules and Definitions
Make uses the following conventions when determining file types or
in defining its rules:
Source Files
Files with a suffix of either .a, .c, .f, or .p are
source files in assembly, C, Fortran, and
Pascal, respectively.
Relocatable Files
Make determines a file to be relocatable if it
has the suffix. .r. Relocatable files are made
from source files and are assembled or
compiled, if necessary, during a make.
Object Files
Make determines a file to be an object file if
the file does not have a suffix. An object file
is made from a relocatable file and is linked,
if necessary, during a make.
Default Compiler
Make's default compiler is ce.
Default Assembler
Make's default assembler is the Relocatable
Macro Assembler (RMA).
2-4
Utilities
Make Utility 12
Default Linker
Make's default linker is CC. You should only
use the default linker with programs that use
Cstart.
Default Directory
Make uses the current directory (.) for all
files.
Macros
You can use macros within a makefile or on the command line. Use
the following form to specify a macro:
macro-name=expansion
Make then substitutes every occurrence of macro-name with the
expansion.
Macro names are prefixed with the dollar sign character ($). If you
want to specify a macro name longer than a single character, you must
enclose the name in parentheses. For example, $R refers to the macro
Rand $(PFLAGS) refers to the macro PFLAGS. The macro names
S(B) and $B refer to the same macro, B. The macro name $BR refers
to the B macro also, followed by the character R.
Note: If you define a macro in your makefile and then
redefine it on the command line, the command line definition
overrides the definition in the makefile. You might find this
feature useful for compiling with special options.
2-5
Utilities
Make U rWry / 2
S pedal Macros
Make provides the following special macros:
Macro
Definition
SDlR;;:path
Make searches the directory, specified by
path, for all implicitly defined source files.
If you do not define SDIR within the
makefile, Make searches [he current
directory.
RDIR"path
Make searches the directory, specified by
path, for all implicitly defined relocatable
files. If you do not define RDIR within the
makefile, Make searches the current
directory.
ODIR=path
Make searches the directory, specified by
path, for all files that have no suffix or
relative path list (object files). The default is
the current execution directory.
Make uses the specified compiler options to
generate command lines.
RFLAGS=options
Make uses the specified assembler optiom to
generate command lines.
LFLAGS=options
Make uses the specified linker options to
generate command line:;.
2-6
Utilities
Make Utility / 2
Reserved Macros
Make expands the foHowing macros when a command line associated
with a particular file dependency is forked. You might find these
macros useful when you need to be ex.plicit about a command line but
have a target program with several dependencies. You can use these
macros only in a makefile command.
Macro
Expands to:
[email protected]
The name of the file to be made by the command
$*
The prefix of the file to be made
$?
The list of files that were found to be newer than the
target file on a given dependency line
Commands
You can specify more than one command for any dependency. Make
forks each command separately unless it is continued from the previous command (see Long Lines).
If you start a command line with the @ symbol, Make docs not echo to
standard output. If you start a command line with a hyphen (-), Make
ignores any error codes returned on that line.
If your system runs Ollt of memory while ex.ecuting a command, you
can redirect the output of Make into a procedure file and execute the
procedure file.
Do not mix comments and commands.
2·7
Utilities
Make Utility / 2
Comments
You can specify an entire line as a comment by placing an asterisk (*)
as the first character in that line. You can place comments at the end
of a line by preceding the comment with the pound sign character (#).
Make ignores blank lines within a makefiIe.
Long Lines
If you use lines longer than 256 characters or lines wider than your
screen, you need to place a space followed by a backslash (\) at the
end of each line to be continued. The continuation line must have a
space or tab as its first character.
For example:
Files ~ aaa.r bbb.r CCC.r ddd.r eee.r fff.r ggg.r \
hhh.r lII.r jjj.r
Make ignores leading spaces and tabs on non-command lines and
continuation lines.
How Make Works
Make starts by using the makefile to set up a table of dependencies.
When Make encounters a name on the left side of a colon, Make first
checks to see if it has encountered the name before. If Make has, it
connects the lists and continues. It treats every item on the right side
of the colon as a unique structure.
After reading the entire makefile, Make determines the target file (the
main file to be made) on the list. It then makes a second pass through
the subtable. It looks for object files that have no relocatable files in
their dependency lists and for relocatable files that have no source
files in their dependency lists.
2·8
Utilities
Make Utility I 2
If Make needs to find any source files or relocatable files to complete
the dependency lists, it looks for them in the directory specified by the
macros SDIR and RDIR (or RDIR's default .). Make looks in these
directories for files with the same name as their dependent file. For
example, if no source file is found for program.r, Make searches the
specified directory (RDIR or .) for program.a (or .c, .p, .f).
Make does a third pass through the list to get the file dates and
compare them. When Make finds a file that is newer than its
dependent file, it generates the necessary command or executes the
command given. Since OS-9 only stores the time down to the closest
minute, Make remakes a file if its date matches one of its dependents.
Note: When Make generates a command line for the linker, it
looks at its list and uses the first relocatable file that it finds.
but only the first one. For example:
prog: x.r y.r z.r
generates the following:
CC
x.r
It does not generate cc x.r y.r z.r or cc prog.r
Notes about Make
If an object has more than one dependency, Make links the
dependency lists together. If the first dependency lists multiple
objects, then all the objects on that dependency line share the same set
of dependencies. This might or might not be correct, depending on
the situation. In the following example, the first makefile is correct,
and the second one creates some extra dependencies:
First makefile:
x.r: defs.h
x.r y.r z.r: defs2.h
Second makefile:
x.ry.r z.r: defs2.h
x.r: defs.h
2-9
Utilities
Make Utility /2
The first makefile specifies that xr is dependent on defLh and de/52.h.
It specifies y.r and z.r as dependent on defs2.h.
The second makefile specifies that all three .r files are dependent on
defs2.h, and seems to specify only x.r as dependent on defs.h. Because
the second makefile lists all three .r files on the same dependency line,
they implicitly share in any future dependencies for any of the
individual files. Therefore, x.r, y.r, and z.r are all implicitly dependent
on de/s.h.
Note: The Make language is very specific. Therefore, you
need to be careful when you use dummy files with names like
print. Unless a file is specifically an object file or you use the
-b option ta turn off the implicit rules, use a suffix far your
dummy files (i.e. prinUile and xxx.h for header files).
Examples of Makefiles
Example 1
prog ram: xxx.r yyy.r
cc xxx.r yyy.r -xf=program
xxx.r yyy.r: IdO/defs/oskdefs
This example shows a shorter version of the make file shown earlier in
this chapter. This example makes use of Make's awareness of file dependencies. Because the makefile makes no mention of C~language
files, Make looks in the directory specified by the macro definition
SDIR=path (in this case, the default of the current directory) and
adjusts the dependency list accordingly. Make also generates a command line to compile xxx.r and yyy.r if one or both need updating.
2-10
Utilities
Make Utility I 2
Example 2
program:
This simple makefile uses only one source file. Make assumes the
following from this simple command:
1.
Because program has no suffix, Make assumes that it is in an
object file and therefore needs to rely on relocatable files to be
made.
2.
Because there is no dependency list given, Make creates an entry
in the table for program.r.
3.
After creating an entry for program.r, Make creates an entry for a
source file connected to the relocatable file.
If Make finds the file prDgram.a, it checks the dates on the various
files and generates one or both of the following commands, if
required:
rma program.a -o=program.r
cc program.r
( + RFAGS ifused)
( + LFLAGS if used)
Example 3
* beginning
=
ODIR IdOJcmds
RDIR = rels
UTILS = attr copy load dir backup dsave
SDIR = ..Iutils/sources
utils.files:
$(UTILS)
touch utils. files
*end
2-11
Utilities
Make Utility I 2
In this example, Make looks in the re1s directory for attr.r, copy.r,
load.T, etc and looks in ..Iutilslsources for artr.c, copy.c, load.c and so
on. Make then generates the proper commands to compile and/or link
any of the programs that need to be made. If one of the files in the
utils directory is made, then Make forks the command touch util.files
to maintain a current overall date.
Example 4
* beginning
OOIR = IhO/cmds
RDIR = refs
CFILES = domake.c doname.c dodate.c domac.c
RFILES = domake.r doname.r dodate.r
R2
= ..Itest/domac.r
RFLAGS =-q
make: (RFILES)
(R2)
linker
$(RFILES): defs.h
$(R2): defs.h
cc $*.c -r= ..Itest
print.fiIe:
(CFILES)
list $? >/p
touch prinLfile
*
getfd.r
end
This example is a makefile to create Make. This makefile looks for
the .r files (listed in RFILES) in the directory specified by RDIR (rels).
The only exception is ..Itestldomac.r, which has a complete pathlist
specified.
Even though getfd.T does not have any explicit dependents, Make
checks its dependency on getfd.G. All of the source files are found in
the current directory.
2-12
Utilities
Make Utility /2
Notice that you can use this makefile to make listings as well. By
typing make print.file on the command line, Make expands the macro
$? to mean all of the files that were updated since the last time
printfile was updated. If you keep a dummy file called primfile in
your directory, it only prints out the newly made fjle. If no primfile
exists, Make prints all the files.
Example 5
See the makefile in the SOURCES directory of Disk 2 in the OS-9
Level Two Development Pack. This complete makefile is for use with
the updn.a and hit.a examples in Chapter 11 of the "ReJocatabJe
Macro Assembler" section of this manual.
2-13
Chapter 3
Touch Utility
The Touch utility updates the last modification date of a file. This
command is especially useful when used inside a makefile with Make.
Associated with every file is the date that the file was last modified.
The Touch utility simply opens a file and closes it, thereby updating
the time that the file was last modified with the current date.
If Touch cannot find the specified file, it creates the file with the
current date as the modification date.
The syntax for Touch is:
touch options filename
The options include any of the following:
Displays the usage of Touch
-c
Does not create a file if Touch cannot find the
specified file
-q
Does not stop execution if an error occurs
-x
Searches the execution directory for the file
-z
Reads the filenames from standard input
-z=path
Reads the filenames from path
3·1
Utilities
Touch Utility 13
Examples
touch -c IhO/doc/program
Touch searches for the specified file but does not create it if it does
not exist.
touch -cz
Touch reads the filenames from standard input. If it cannot find a
specified file, Touch does not create it. [CTRL][BREAK] at the
beginning of a line signals TOllch to terminage.
touch -zdilelist
Touch reads filenames from filelist, a file containing 1 filename on
each line.
3·2
Chapter 4
Virtual Disk/RAM Disk Driver
The Virtual Disk Driver is a high-speed, general storage/retrieval
system that uses your computer's memory to simulate a fast disk
device. You can use the VDD to store frequently used files (such as
OS9DEFS) and programs to cut down on floppy disk access time. The
Virtual Disk Driver uses two to six pages of system address space and
allocates the amount of RAM specified in the descriptor (RO).
The VOD system consists of two modules: RO (the VOD descriptor)
and RAM (the driver).
Initializing VDn
You can initialize the Virtual Disk Driver by issuing an I$Attach call
for RO or by opening or creating a file on RO. You can also use INIZ
to perform the I$Attach call. The syntax for INIZ is as follows:
iniz rO
Note: Do not use I$Open and I$Create to initialize VDD even
though they both do an implicit I$Attach, because the I$Close
call does an implicit I$Detach. If an I$Attach call is not made
before the file is opened, all data in the RAM disk is lost when
the file is closed.
When VDD is initialized, it obtains information about the total amount
of memory it is to allocate and the system memory block size from the
descriptor. VOD then initializes Sector zero, the bit map, and the root
directory. Once the Ram Disk is initialized, you can treat RO like any
other disk device.
4-1
Utilities
Virtual Disk/RAM Disk Driver
RO is a standard RBF device descriptor. You can choose the amount
of RAM used by VDD by changing the default sectors per track
(module offset $1B). To do so, use the debugger or reassemble RO
with the desired alteration. The size that VDD uses can be changed by
altering the number of surfaces (module offset $19).
Your development diskettes contain three versions of RO, a 96
kilobyte version, a 128 kilobyte version, and a 192 kilobyte version.
You can ani y use one version at a time.
4-2
Utilities
Index
access time, disk 4-1
arguments, macros 2-1
assembler 2-4
options 2-6
blank lines (Make) 2-8
CFLAGS (Make macro) 2-6
comments (Make) 2-8
compiler 2-4
options (Make) 2-6
cross-compiler/assembler (Make) 2-2
create file (Touch) 3-1
date, modification 3-1
debugger (Make) 2-1
default
assembler 2-4
compiler 2-4
directory 2-5
linker 2-5
dependencies 2-3, 2-9
dependency, line 2-7
directory 2-5
search 2-6
disk
access time 4-1
driver, virtual 4-1- 4-2
displaying commands (Make) 2-2
dollar sign (Make) 2-5
1
Utilities
Index
echoing commands (Make) 2-2
error (Touch) 3-1
error codes 2-7
errors, ignoring (Make) 2-2
execution directory, searching (Touch) 3-1
file
dates 2-3
dependencies 2-1, 2-3, 2-9
prefix 2-7
file touching 2-2
filename 2-7
filenames (Touch) 3-1
files
object 2-4
relocatable 2-4
source 2-4
initializing VDD 4-1
leading spaces (Make) 2-8
LFLAGS (Make macro) 2-6
line width 2-8
linker 2-5
options (Make) 2-6
macros 2-2, 2-5 - 2-7
arguments 2-1
reserved 2-7
special 2-6
maintain program 2-1 - 2-13
2
Utilities
Index
Make 2-1 - 2-13
conventions 2-4 - 2-5
debugger 2-1
language 2-10
macros 2-5 - 2-7
options 2-1 - 2-2
targets 2-2
makefile 2-2
path 2-2
modification date
Make 2-4
Touch 3-1
modifications 2-1 - 2-13
object files 2-4
ODIR (Make macro) 2-6
options
assembler 2-6
Make 2-1 - 2-2
compiler 2-6
linker 2-6
procedure file 2-3
program maintenance 2-1 - 2-13
RAM driver 4-1 - 4-2
RDIR (Make macro) 2-6
redirecting output (Make) 2-7
re10catable files 2-4
reserved macros (Make) 2-7
RFLAGS (Make macro) 2-6
SDIR (Make macro) 2-6
searching the directory 2-6
source files 2-4
3
Utilities
Index
standard input
Make 2-2
Touch 3-1
standard output (Make) 2-7
target file, updating 2-3
Touch 3-1 - 3-2
touching files 2-2
virtual disk 4-1 - 4-2
4
Commands
Contents
Chapter 1 / Introduction
Chapter 2 / Command Reference
BINEX
_ _
_._
1-1
2-1
2-1
DU1v1P
2-3
EXBIN
LOGIN
MODPATCH
MONTYPE
PARK
SAVE
SlEEP
2-6
2-7
2-14
2-16
2-18
2-19
TEE
2-21
TSMON
VERIFY
_
2~10
2-23
2-24
Chapter 1
Introduction
The CMDS directory of Disk I in the 05-9 Level Two Development
System contains several commands to help in system operations.
These commands and their functions are:
Command
Function
BINEX
Converts a binary file into an S-Record file
DUMP
Displays the physical data contents of a file or
device in both ASCII and hexadecimal form
EXBIN
Converts an S-Record file into its binary form
LOGIN
Provides login security on timesharing systems
MODPATCH
Modifies modules residing in memory
MONTYPE
Sets a system for the specified type of monitor
PARK
Moves the heads of a hard disk in preparation for
moving the drive unit
SAVE
Creates a file and writes a copy of the specified
memory module(s) into the file
SLEEP
Suspends a process for a specified time
TSMON
Supervises idle terminals and initiates login
TEE
Copies standard input to multiple devices
VERIFY
Checks module header parity and CRC values
1-1
Chapter 2
Command Reference
BINEX
Syntax:
binexfilenamel filename2
Function:
Converts a binary file into an
S~Record
file.
Parameters:
lilenamel
The name of the file to convert
li/ename2
The name of the file in which to store the
converted code
Notes:
•
Binex converts the specified 05-9 binary file (filenamel) to
an S-Record file and gives the new file the name specified by
filename2. If filename I is a non-binary load module file, OS-9
prints a warning message and asks you if BlNEX should
proceed anyway. Press y to continue with the conversion.
Pressing any other key causes BINEX to terminate.
2·1
Commands
•
Command Reference / 2
When you run BINEX, the program asks you for a program
name and a starting load address. It stores this information in
a header record. Although OS-9 is position independent and
does not require absolute addresses, S-Record files do. The
following example illustrates a BINEX command, its prompts,
and possible user input.
binex IdO/cmds/scanner scanner.51 [ENTER]
Enter starting address for file:
$100 [ENTER]
Enter name for header record:
scanner [ENTER]
•
To download the Scanner.sl file to a device (such as a PROM
programmer) using serial port ITI, type:
tist scanner.51 :>/t1 [ENTER]
•
An S-Record is a type of text file that contains records
representing binary data in hexadecimal character form. Most
commercial PROM programmers, emulators, logic analyzers,
and similar RS-232 devices can directly accept this Motorolastandard fonnat. You can also use S-Record files to transmit
data over data links that can only handle character-type data
or to convert OS-9 assembler- or compiler-generated programs to load on non-OS-9 systems.
Example:
To convert a binary file named Zap to an S-Record file named Zap.sr,
type:
binex IdOJcmds/zap Idl/srJzap.sr
2-2
Commands
Command Reference 12
DUMP
dump [name]
Syntax:
Function:
Displays the physical data contents of the specified
file or device in both ASCII and hexadecimal form.
Parameter:
name
Either a file pathlist or a device name
Notes:
•
If you do not specify a file or device, DUMP displays the
standard input path (the keyboard). Dump writes output to the
standard output path (the video display).
•
Use DUMP to examine the contents of non-text files.
•
The DUMP display adjusts to the type of screen you are
using. In 32- and 40-column screens. DUMP displays eight
bytes per line. In 80-column screens. DUMP displays 16 bytes
per line.
•
DUMP displays data in both hexadecimal and ASCII
character fonnat. If data bytes have non-displayable values,
DUMP displays them as periods (.).
•
The addresses displayed by DUMP are relative to the
beginning of the file. Because memory modules are positionindependent and are stored in files exactly as they exist in
memory, the addresses shown on the dump correspond to the
relative load addresses of memory-module files.
2-3
Command Referenc:e /2
Commands
Examples:
To display keyboard input in hex on the screen, type the following
command. Press [CTRLllBAEAK] to return to the shell.
dump
[ENTER]
Then, to display the contents of the diskette in Drive IDl, type:
dump @/d1 [ENTER]
The @ symbol causes 05-9 to treat the entire disk as a file.
Sample output, 32 columns:
DUMP SVS/password ;>/P [ENTER]
o
ADDR 8
123 4 5 6 7
024 6
8 ACE
9 ABC D E F
---- +-+-+-+-+-+-+-+- + + + +
0000
0008
0010
0018
0020
0028
0030
0038
2C2C302C3132382C
2F44302F434D4453
2C2D2C5348454C4C
OD55534552312C2C
312C3132382C2E2C
2E2C5348454C4COD
55534552322C2C32
2C3132382c232C23
,,0,128,
/DO/CMOS
, .,SHELL
.USERl"
1,128,_,
.,SHELL.
USER2,,2
,128,.,.
ADDR
o 123 4 5 6 7
8 9 ABC D E F
8 ACE
o
2 4 6
---- +-+-+-+-+-+-+-+- + + + +
0040 2C5348454C4COD55 ,SHELL.U
0048 534552332C2C332c SER3, ,3,
0050 3132382C232C2E2C 128,.,.,
0058 5348454C4COD5553 SHELL.US
0060 4552342C2C342c31 ER4,,4,l
0068 32382c2E2C2E2C53 28,., .,S
HELL.
0070 48454C4COD
2-4
Command Reference /2
Commands
The first column indicates the starting address. The next eight
columns (OO-EF) display data bytes in hexadecimal format. The final
column (O-E) displays data byes in ASCII format. The display shows
non-ASCII as periods in the ASCII character display section_
Sample output, 80-columns:
DUMP SYSlpassword >/P (ENTERl
ADD~
0000
0010
0020
0030
0040
0 1
2 3
4 5
6 1
2C2C 302C 3132 382e
2C2E 2C53 .845 4c4c
312C 3132 3A2C 2E2C
5553 4552 322c 2C32
2c53 4845 4C4C 0055
0050 3132 38ze ZE2C ZE2C
0060 4552 342C 2Cl4 2elA
0010 4a4S 4C4C 00
8 gAB
2r44
0055
2E2C
2C31
5345
5348
3238
C 0
302r
5345
5348
3238
5233
4340
5231
454C
lC2E
2C,C
4S4C 4COO
2C2E 2C2E
E
r
4453
2C2C
4COD
2C2E
332C
5553
2C53
0 2 4 6 8 A C 2
, ,0,128, /OO/CMOS
, ., SHi:L:L. USi:IU"
1,128, _, ",SHELL.
USEIt2" 2, 128, ., .
, SHELL .USER.3, t 3,
128, ... ,SHELL.US
2M, ,4, 128, "'"' S
HELL.
2-5
Commands
Command Reference /2
EXBIN
Syntax:
exbinfilenamel fi/ename2
Function:
Converts an S-Record file into its binary form
Parameters:
filename]
The name of the file to convert
filename2
The name of the file in which to store the
converted code
Notes:
•
EXBLN is the inverse operation of BINEX. It assumes the file
specified by filenamel is an S-Record fonnat text file and
converts it to a pure binary form in the file specified by
li/ename2. The load addresses of each data record must
describe contiguous data in ascending order.
•
EXBIN does not generate or check for the proper 05-9
module headers, the header CRC check value, or the module
eRe check value required to load the binary file. Use the
IDENT or VERIFY commands to check the validity of the
modules.
Examples:
•
To convert an S-Record file named Program.s I to a binary file
named Program and store it in the commands file of the
current diskette, type:
exbin program.s1 cmds/program (ENTER]
2-6
Commands
Command Reference 12
LOGIN
Syntax:
login
Function: Provides login security on timesharing systems. LOGIN
automatically adjusts its output for 32- or SO-column displays.
Parameters: None
Notes:
•
The timesharing monitor, TSMON. automatically calls
LOGIN. You can also use LOGIN after initial login to change
a terminal's user.
•
LOGIN requests your name and password. which it checks
against a validation file. If the information is correct, LOGIN
sets up your system priority. ill, and working directories
according to information stored in the file. Then, LOGIN
executes the initial program (usually shell) specified in the
password file.
•
The LOGIN process terminates if you cannot supply a correct
user name and password after three attempts.
•
The validation file is IDDfSYSfpassword. The file contains
one or more variable-length text records, one for each user
name. Each record has the following fields (the file uses
commas as delimiters):
User name. The name can be a maximum of 32 characters,
including spaces. If the name field is empty. any name
matches.
Password. The password can be a maximum of 32 characters.
including spaces. If the password field is blank, the system
does not require the record's owner to type a password.
2·7
Commands
Command Reference / 2
User index. This is the user ID number. It can be in the range
supcruser or system manager). Both the
file security system and the system-wide user ID use this
number to identify all processes initiated by the user. The
system manager should assign a unique ID to each potential
user.
o to 65535 (0 is the
Priority_ This is the initial process (CPU time) priority. It can
be in the range of I to 255.
Execution Directory.
This is a pathlist showing the name
and location of the initial execution directory (usually
IDO/CrvIDS).
Working Directory. This is a pathlist showing the name and
location of the initial data directory (the specific user's
directory). The initial data directory is usually the ROOT
directory.
Execution Program. This is the name of the initial program
to execute (usually shell). Do not use shell command lines,
such as DIR or DCHECK, as initial program names.
•
Here is the system default validation file:
"O.128,/DO/CMDS,_,SH ELL
USER1"1,' 28,.,.,SHELL
USER2,,2,128•.,.,SHELL
USER3,,3.128••,.,SHELL
USER4,,4,128,.,.,SHELL
In this sample, the superuser's record, the first entry, contains
no user name or password. The ID number is 0, the initial
process priority is 128, the execution directory is IDO/CMDS,
and the ROOT directory is the initial data directory. The
initial program to execute is shell. The second entry is the
same except the user's name is the default USER!.
2-8
Command Reference 12
Commands
•
To use LOGIN, type:
login [ENTER]
Prompts ask for your name and (optionally) a password. If
you answer correctly, the system completes your login.
LOGIN initializes the user number, working execution
directory, the working data directory, and executes a
specified program. It displays the date, time, and process
number. LOGIN adjusts its output format for 80- or 32column displays.
•
To kill the shell that called LOGIN, use EX, For example:
ex login [ENTER]
•
Use the OS-9 text editor to edit Password and add users.
•
Logging off the system terminates the program specified in
the password file. For most programs (including shell)
logging off involves typing an end-of-file character
([CTRl][BREAK)) as the first character on a line.
•
If Motd exists in the SYS directory, LOGIN displays its
contents (after a successful login).
Examples:
Following is possible user input and the screen display during LOGIN.
[ENTER]
OS-g Timesharing system
level II RS VR. 02.00.01
87/04/1008:35:44
User name?: superuser [ENTER]
Password: secret [ENTER]
Process #07 logged on 87/04/1008:36:01
Welcome!
(your entry does not
appear on the screen)
LOG IN then displays a message of the day from the Motd file.
2-9
Commands
Command Reference I 2
MODPATCH
Syntax:
Function:
modpatch [options]filename [options]
modifies modules
residing
In
memory.
MODPATCH reads a file and executes the
commands in the file to change the contents of
one or more modules.
Parameters:
filename
The name of a file containing instructions for
MODPATCH
options
One of the following options
MODPATCH's function
that change
Options:
-s
Silent mode, does not display patchfile command
lines as they are executed.
-w
Does not display warnings. if any
-c
Compares only, does not change the module
2-10
Command Reference / 2
Commands
Notes:
•
Before using MODPATCH, you must create a patchfile to
supply the data to control MODPATCH's operation. This file
contains single-letter commands and the appropriate module
addresses. The commands are:
I modulename
Link to the module specified by
modulename.
c offset origval newval
Change the byte at the offset
address specified by offset from
the value specified by origval to
the new value specified by
newval. If the original value
does
not
match
origval,
MODPATCH
displays
a
message.
v
Verify the module·-update the
modules eRC . If you plan to
save the patched module to a
file that the system can load,
you must use this command.
m
Mask IRQ's. Turns off interrupt
requests (for patching service
routines).
u
Unmask IRQ's. Turns
on
interrupt requests (for patching
service routines).
•
You can use the BUILD command or any word processing
program to create patchfiles.
•
Module byte addresses begin at O. MODPATCH changes
values pointed to by an offset address (offset from 0) rather
than an absolute memory address.
2-11
Commands
Command Reference /2
•
To view the contents of a memory module, use SAVE and
DUMP to copy the module to a file and display its contents.
Also use SA VE to copy the patched module to a disk file.
•
Changing a memory module might not produce an immediate
effect. You have to duplicate the initialization procedure for
that module. This means, if the module loads during bootup,
you have to create a new boot file that includes the changed
module, then reboot using the new boot file.
•
To use the patched module in future system boots, use SAVE
to store the module in the MODULES directory of your
system disk. You can then use OS9GEN to create a new
system disk using the patched module. If you are using the
patched module to replace another module, rename the
original module and then give the patched module the
original name.
•
If you patch a module that is loaded during the system boot,
you can use COBBLER to make a new system boot that uses
the patched module.
Examples:
The following example shows the commands, the screen prompts, and
the entries you make to patch the standard 40-column term window
descriptor to be an SO-column screen rather than the standard 40column screen:
OS9: build termpa1ch [ENTER]
? 1term [ENTER]
? c 002c 2850 [ENTER]
? c 0030 0102
? v [ENTER]
? [ENTER]
099: modpatch 1ermpatch [ENTER]
2-12
Commands
Command Reference /2
To change the size, columns, and colors of Device Window Wi, create
the following procedure file and name it W180:
Iw1
c 00300102
c 002c 1b 50
c 002d Ob 18
If the Wi module is not already in memory, load it from the
MODULES directory of your system disk. Then, before initializing
WI, run MODPATCH;
modpatch w180 [ENTERI
Next, initialize WI:
iniz w1 [ENTER]
shell i=/w1& [ENTER]
Press [CLEAR] to display the new window with 80 columns, 24 lines,
and a white background.
2-13
Command Reference 12
Commands
MONTYPE
Syntax:
montype type
Function:
using
Sets your system for the type of monitor you are
Parameters:
type
A single letter indicating the monitor type:
c
for composite monitors or color televisions
r
for ROB monitors
m
for monochrome monitors or black and white
televisions
Notes:
•
Different types of color monitors display colors differently. For
the best results, set your system to the type of monitor you are
using.
•
If you are using a monochrome monitor or black and white
television. you can obtain a sharper image by setting your monitor
type to monochrome.
•
Include the MONTYPE command in your system's Startup file to
automatically boot in the proper monitor mode.
•
If you do not use MONTYPE, the system defaults to c (composite
monitor).
Example:
To set your system for an RGB monitor, type:
montype r [ENTER]
2-14
Commands
Command Reference I 2
To add a MONTYPE command to your existing Startup file, first use
BUILD to create the new command. For example:
build temp [ENTER)
monlype r [ENTER]
[ENTER]
Next, append the file to Startup. Type:
merge startup temp> startup.new [ENTER]
Delete the temp file:
del temp [ENTER]
To enable the system to use Startup.new when booting, rename the
original Startup file:
rename Startup Startup.old
Then rename Startup.new:
rename Startup. new Startup
2-15
Command Reference /2
Commands
PARK
Syntax:
park drive
Function:
Moves the heads of a hard disk to the innermost
tracks in preparation for moving the drive unit.
Parameters:
drive
The hard disk drive for which you want to park
the heads
Notes:
•
Jarring your hard disk can cause its recording heads to bump
against the highly polished surface of the recording media,
destroying stored data. Such jarring can easily happen when you
move your hard disk drive.
PARK moves all of your disk's recording heads onto the
innermost tracks where information is not stored, and where such
inadvertent bumping cannot destroy data.
•
Always use PARK before relocating your hard disk or anytime
you think it might be bumped or jiggled.
•
After running PARK, turn off the system. Wait at least 15 seconds
before turning on the power again. When you do turn your system
on, the hard disk is immediately ready for use.
•
Your hard disk is a precision instrument, built to extremely close
tolerances. Always handle it carefully, even after parking its
heads.
2-16
Command Reference / 2
Commands
Example:
To park the heads of your hard disk, type:
park IhO [ENTER]
2-17
Commands
Command Reference /2
SAVE
Syntax:
save filename modname [...]
Function:
Creates a file and writes a copy of the specified
memory module(s) into the file
Parameters:
filename
Is the name of the file you want to create
modname
Secifies one or more modules to include in the
file
Notes:
•
The module name(s) must exist in the module directory when
SA VEd. SAVE gives the new file all access permission except
public write.
•
SAVE's default directory is the current data directory.
Generally, you should save executable modules in the default
execution directory.
•
You can use SAVE to create a file of the commands you use
most often so that you can load all of these commands using
only one filename.
Examples:
To save a module named Wcount into a newly created file called
Workcount in the IDO/CMDS directory, type:
save /dO/cmds/workcount wcount [ENTER]
The following command saves four modules (add. sub, mul and div)
into the new file called ID l/Mathyack.
save /d1/malh-l)ack add sub mul div [ENTERI
2-18
Command Reference / 2
Commands
SLEEP
sleep rickcount
Syntax:
Function:
Puts a process to sleep for the specified number of
clock ticks
Parameters:
Tickcount
Can be any number in the range 1 to 65535
Notes:
•
If you give SLEEP a value larger than 65535, OS-9 reduces
the value by mod 65536. For example, 65536, and all the
multiples of 65536, become O. A tick count of 95000 becomes
an actual tick count of 29464.
In other words, if you give SLEEP a value higher than 65535,
it reduces tickcount by subtracting the closest multiple of
65536 that is lower than your value.
•
Use SLEEP to generate time delays or to break up jobs
requiring a large amount of CPU time. The duration of a tick
is 16.66 milliseconds.
•
A tick count of I causes the process to give up its current time
slice. A tick count of 0 causes the process to sleep
indefinitely. (A signal sent to the process awakens it.)
Examples:
The following command puts the process to sleep for 25 ticks (416.50
milliseconds):
sleep 25 [ENTER]
2-19
Command Reference I 2
Commands
The following command sequence causes LIST to start running as a
child process invoked from the shell, and as a background task.
SLEEP then puts the shell to sleep indefinitely. When LIST attempts to
find the file Nothing, which does not exist, it terminates and sends a
signal (the error status), which wakes up the shell.
list startup sys/motd nothing & sleep 0
A sample screen display follows:
&004
setlme <!term
WELCOME TO COLOR COMPUTER 05-9
-004
ERROR #216
0S9:
If an error does not occur, the shell continues to sleep. (Use [BREAK]
to wake the shell. Any keys you pressed while the shell was asleep are
then displayed.
2-20
Commands
Command Reference I 2
TEE
Syntax:
tee pathlist or devname [...]
Function:
Copies standard input to multiple devices
Parameters:
palhlist
Is one or more paths for the input data to follow
devname
Is one or more devices to which the system
directs the input data
Options: TEE can send output to any number of devices specified by
devname.
Notes: TEE is a filter that copies all text lines from its standard input
path to the specified output paths.
Examples:
The following command line uses a pipeline and TEE to send the
output listing of DIR simultaneously to the terminal, the printer, and a
disk file:
dir e I tee IlOp IdO/dir.listing
Here, a pipeline takes the output of DIR E and sends it to the terminal
and TEE. TEE in turn sends the output to the printer and to a file called
IDOfDirJisting.
2-21
Commands
Command Reference / 2
In the following example, the pipeline and TEE send the output of an
assembler listing to a file (Pgm.1ist) and to the printer.
8sm pgm.src I ! tee pgm.list Ip [ENTER]
The next example broadcasts a message to the terminal.
echo WARNING SYSTEM DOWN IN 10 MINUTES! tee 1>t1 [ENTER]
2·22
Command Reference 12
Commands
TSMON
tsmon [devnamel
Syntax:
Function:
Supervises idle terminals and initiates the login
sequence for timesharing applications
Parameter:
devname
Is the device for which you want login and
supervision capabilities
Notes:
•
If you specify a devname, TSMON opens standard I/O paths
for that device. When you enter a carriage return, TSMON
automatically calls the LOGIN command. If the LOGIN fails
because the user cannot supply a valid user name or
password, control returns to TSMON. The LOGIN command
and its password file must be present for TSMON to work
correctly. (See the LOGIN command description.)
•
Logging Off the System: Most programs terminate when you
enter an end-of-file marker ([CTRL][BREAK}) as the first
character on a command line. Pressing [CTRL][BREAKI causes
your terminal to log off the system and to return to TSMON.
TSMON rons the login sequence again when you press
[ENTER].
Examples:
The following command line activates ITI.
tsmon /t1& [ENTER)
The command must run concurrently in order to keep (TERM active.
2-23
Commands
Command Reference / 2
VERIFY
Syntax:
verify [u] <filename] f>filename2]
Function:
Checks to see if the module header parity and CRC
value of one or more modules on a file are correct
Parameters:
filenamel
Is the name of the module to be checked
fi/ename2
Is the name for the verified module created with
the u option
Options:
u (update)
copies the module(s) to a new module with the header
and parity and CRe values replaced with VERIFY's
computed values
Notes:
•
VERIFY reads module(s) from the standard input and sends
output to the standard output. It sends messages to the
standard error path.
•
VERIFY is dependent on the input redirection command. If
you fail to use the redirection symbol, VERIFY causes the
system to lock. To gain control of the system, press [BREAK).
You must always redirect the input path. If you use the u
option, you must also redirect the output to the new file you
want to create.
•
Using the u (update) option causes VERIFY to copy the
module(s) to the standard output path with the module's
header parity and CRC values replaced with new computed
values. VERIFY, with the update option, does not set the
execute flag in the file attributes. Use ATIR to do this.
2-24
Command Reference I 2
Commands
•
If you do not use the u option. VERIFY does not copy the
module to standard output. VERIFY displays a message
indicating whether the module's header parity and CRe match
those computed by VERIFY.
Examples:
Because the following command line uses the u option, VERIFY
copies the edit module to a new module. Newedit, with the header
parity and eRe values replaced with VERIFY's computed values.
verify u </dO/cmds/edlt >/dO/cmds/newedit [ENTER]
The next command line checks the edit module. Because the command
does not specify the u option, VERIFY only displays a summary
message.
verify cedit [ENTER]
A possible screen display is:
Header parity Is correct
CRC is correct
In the next command line, VERIFY checks Myprogram2, an invalid
module. Because the command does not specify the u option, VERIFY
does not copy the module to standard output, but displays a message.
verify cmyprogram2 [ENTER]
The screen displays:
Header parity is INCORRECT!
CRC is INCORRECT!
2-25
Commands
Index
ASCII, file contents 2-3
binary file
converting to S-Record 2-1 - 2-2
converting from S-Record
2-6
BINEX command 2-1 - 2-2
BUILD command 2-11, 2-15
changing modules 2-10 - 2-13
clock ticks 2-19
COBBLER command 2-12
command list 1-1
commands, patchfile 2-1 1
contents, file 2-3 - 2-5
converting binary to S-Record/binary 2-1 - 2-2
converting S-Record to binary 2-6
CPU time 2-8
eRe value 2-24 - 2-25
devices, copying input to 2-21 - 2-22
DlR command 2-21
directory
execution 2-8
SYS 2-9
working 2-8
DUMP command 2-3 - 2-5, 2-12
emulators 2-2
EX command 2-9
EXBIN command 2-6
1
Commands
Index
execution
directory 2-8
program 2-8
file contents 2-3 - 2-5
File conversion, binary/S-Record 2-1 - 2-2
File, displaying contents 2-3 - 2-5
filter, TEE 2-21 - 2-22
hard disk, parking heads 2-16
hexadecimal form, file contents 2-3
input, standard 2-21 - 2-22
LIST command 2-20
logic analyzers 2-2
LOGIN command 2-23 , 2-7 - 2-9
memory modules, saving 2-18
modifying module 2-10 - 2-13
module header parity, checking 2-24 - 2-25
modules
modifying 2-10 - 2-13
saving from memory 2-18
updating 2-24
MODULES directory 2-12
monitor, setting type 2-14 - 2-15
monochrome monitors 2-14
MONTYPE command 2-14 - 2-15
non-text files 2-3
OS9GEN command 2-12
parity, module header 2-24 - 2-25
PARK command 2-16 - 2-17
password (LOGIN) 2-7
2
Commands
lruiex
patchfile commands 2-11
paths 2-21 - 2-22
pipeline (TEE) 2-21 - 2-22
priority 2-8
process, putting to sleep 2-19
PROM progranuners 2-2
reference, commands 1-1
RGB monitors 2-14
S-Record
from binary 2-1 - 2-2
to binary 2-6
SAVE command 2-12, 2-18
saving memory module 2-1 g
security, login 2-7 - 2-9
shell, killing 2-9
SLEEP command 2-19 - 2-20
standard
I/O paths 2-23
input 2-21 - 2-22
Startup file 2-1 S
suspending processes 2-19
SYS directory 2-9
TEE command 2-21 - 2-22
television 2-14
terminal, supervising 2-23
tick count 2-19
timesharing 2-7 - 2-9, 2-23
TSMON command 2-23
types of monitor 2-14 - 2-15
updating modules 2-24
user index (LOG IN) 2- 8
3
Commands
Index
validation file (LOGIN) 2-7
VERIFY command 2-24 - 2-25
working directory 2-8
4
08-9
Technical
Reference
Contents
Chapter 1 System Organization
1'0 System Modules
Color Computer 08-9 Modules
Kernel, Clock Module, and INIT
Input/Output Modules
I/O Manager
File Managers
Device Drivers
Device Descriptors . __ . __ . _
Shell
Chapter 2 The Kernel
,,
,
System Initialization .. ,
System Call Processing
,
,., .. ,
OS9Defs and Symbolic Names
Types of System Calls ,
Memory Management
Memory Use
,
Color Computer OS-9 Typical Memory Map
Memory Management Hardware
,
Multiprogramming
Process ereation
Process States
_
Execution Scheduling
, .. ,
Signals
Interrupt Processing
Logical Interrupt Polling System
Virtual Interrupt Processing . _.
.. _
1-1
1-1
1-2
1-2
1-3
1-3
1-3
1-3
1-4
1-4
2-1
2-1
2-4
2-4
2-4
2-5
2-5
2-7
2-7
, .. 2-12
2-12
2-13
2-14
2-15
2-16
2-17
2-19
Chapter 3 Memory Modules
3-1
Module Types
_
_
,
3-1
Module Format"
3-1
Module Header _
__ ." __ .. _
3-2
Module Body
3-2
eRe Value
,
3-2
Module Headers: Standard Information
3-3
Sync Bytes
,
3-3
Module Size
_. _3-3
Offset to Module Name
, .. ,
3-3
Type/Language Byte
,
3-4
Attributes/Revision Level Byte
3-4
Header Check
3-5
OS -9 Technical Reference
Module Headers: Type-Dependent Information
Executable Memory Module Format
3-5
3-6
Chapter 4 08-9's Unified Input'Output System
, . ,4-1
liO System Modules
,
The liD Manager
File Managers
File Manager Structure ,
Create, Open
Makdir
ChgDir
Delete
Seek
Read
Write
ReadLn
WriteLn
GetStat, PutStat
Close ........,...............
Interfacing with Device Drivers
Device Driver Modules
Device Driver Module Format
OS-9 Interaction With Devices
Suspend State (Level Two Only)
Device Descriptor Modules
Path Descriptors
Chapter 5 Random Block File Manager
,
,
,
,
4-1
4-2
4-3
4-3
4-4
4-4
4-4
4-5
4-5
4-5
4-6
4-6
.4-6
4-6
4-7
.4-7
4-8
4-10
.4-11
4-13
4-15
4-18
,
5-1
Logical and Physical Disk Organization
,
5·1
Identification Sector (LSN 0)
5-2
Disk Allocation Map Sector (LSN 1)
5-3
ROOT Directory
5-3
File Descriptor Sector
5-3
Directories
,
,
5-5
The REF Manager Definitions of the Path Descriptor .. 5-5
RBF-Type Device Descriptor Modules
5-8
RBF Record Locking
5-10
Record Locking and Unlocking
5-11
Non-Shareable Files
5-12
End-of-File Lock
5-12
Deadlock Detection
5-13
REF-Type Device Driver Modules
5-13
The REF Device Memory Area Definitions
5-13
RBF Device Driver Subroutines
5-16
Contents
Chapter 6 Sequential Character File Manager
SCF Line Editing Functions
Read and Write
Read Line and Write Line
SCF Definitions of the Path Descriptor
SCF-Type Device Descriptor Modules,
SCF-Type Device Driver Modules
SCF Device Driver Subroutines
6-1
6-1
6·1
6-2
6-2
6-6
6-9
6-10
Chapter 7 The Pipe File Manager (PIPE MAN)
7-1
Chapter B System Calls
Calling Procedure
,
lJO System Calls
,
System Call Descriptions
User Mode System Calls Quick Reference
System Mode Calls Quick Reference
User System Calls
lJO User System Calls
Privileged System Mode Calls
Get Status System Calls
Set Status System Calls
Appendices
A Memory Module Diagrams
B Standard Floppy Disk Format
C System Error Codes
Index
_
8-1
8-1
8-2
8-2
8-3
8-5
8-7
, . , .. 8-44
8-66
8-112
, 8-130
,
,
,
_
A-I
A-I
B-1
C-I
Chapter 1
System Organization
08-9 is composed of a group of modules, each of which has a specific function. The following illustration shows the major modules. Actual module names are capitalized.
I/O System Modules
OS-9 KERNEL
INIT
IOS9fl. OS9f2)
Clock
Input Output Manager
!lOMAN)
Manager
O,sk File
Pipe File
Manager
(RBF)
lPlpemanl
Cnar File
Manager
(SCFI
Wl1dlnt
CC31D
Interlace
0$·9 COMPONENT MODULE ORGANIZATION
1-1
08-9 Technical Reference
Color Computer 08-9 Modules
lOMAN
!NIT
CLOCK
RBF
SCF
PIPEMAN
CC3DI8K
CC3IO
Input/output management
System initialization table
Software routine time management
Random block file management
Sequential character file management
Pipe file management
Color Computer disk driver
Color Computer input/output driver
The VDGINT (video display generator) provides both interface
functions and low-level routines for Color Computer 2 VDG
compatibility.
The GRFINT interface provides high-level graphics code interpretation and interface functions.
The WINDINT interface contains all the functions of GRFINT,
along with additional support for Multiview functions. If you are
using Multiview, exclude GRFINT from the system.
Both WINDINT and GRFINT use the low-level driver GRFDRV
to perform the actual drawing on bitmap screens.
TernL-VDG uses CC3IO and VDGINT. TERM-WIN and all
window descriptors (W, WI, W2, and so on) use CC3IO, WINDINT, GRFINT, and GRFDRV modules.
Kernel, Clock Module, and INIT
The system's first level contains the kernel, clock module, and
INIT.
The kernel provides basic system services, such as multitasking
and memory management. It links all other 08-9 modules into
the system.
The clock module is a software handler for the real-time clock
hardware.
INIT is an initialization table used by the kernel during system
startup. This table loads initial tasks and specifies initial table
sizes and initial system device names. It is loaded into RAM
(random access memory) by the 08-9 bootstrap module Boot.
Boot also loads the 089P2 and INIT modules during system
startup.
1·2
System Organization / 1
There are two ways to run boot:
• Using the DOS command with Color Disk BASIC, Version 1.1, or later.
• Pressing the reset button after 08-9 is running.
Input/Output Modules
The remaining modules make up the 08-9 I/O system. They are
defined briefly here and are discussed in detail in Chapter 4.
I/O Manager
The system's second level (the level below the kernel) contains
the input/output manager, IOMAN. The 110 manager provides
common processing for all input/output operations. It is required
for performing any input/output supported by OS-9.
File Managers
The system's third level contains the file mnnagers. File managers perform I/O request processing for similar classes of liD
devices. There are three file managers:
RBF manager
The random block file manager processes
all disk liD operations.
SCF manager
The sequential character file manager handles all non-disk I/O operations that operate
one character at a time. These operations
include terminal and printer 1/0.
PIPE MAN
The pipe file manager handles pipes. Pipes
are memory buffers that act as files. Pipes
are used for data transfers between
processes.
Device Drivers
The system's fourth level contains the device drivers. Device
drivers handle basic 1/0 functions for specific I/O controller hardware. You can use pre-written drivers, or you can write your
own.
1-3
08-9 Technical Reference
Device Descriptors
The system's fifth level contains the device descriptors. Device
descriptors are small tables that define the logical name, device
driver, and file manager for each I/O port. They also contain port
initialization and port address infonnation. Device descriptors
require only one copy of each I/O controller driver used.
Shell
The shell is the command interpreter. It is a program and not a
part of the operating system. The shell is fully described in the
08-9 Commands manual.
1-4
Chapter 2
The Kernel
The kernel is the core of OS-9. The kernel supervises the system
and manages system resources. Half of the kernel (called
OS9Pl) resides in the boot module. The other half of the kernel
(called OS9P2) is loaded into RAM with the other 08-9 modules.
The kernel's main functions are:
• System initialization after reset
• Service request processing
• Memory management
• Multiprogramming management
• Interrupt processing
VO functions are not included in the list because the kernel does
not directly process them. Instead, it passes VO system calls to
the VO Manager for processing.
System Initialization
After a hardware reset, the kernel initializes the system. This
involves:
1.
Locating modules loaded in memory from the 08-9 Boot file.
2.
Determining the amount of available RAM.
3.
Loading any required modules that were not loaded from the
08·9 Boot file.
08-9 Level Two cannot install new system calls using the 08·9
Level One system call F$8Svc. F$SSvc does not work with a
Level Two user program because of the separation of system and
user address space.
2·1
08-9 Technical Reference
OS9P3 can be used to tailor the system to fit specific needs. The
following listing is an example of how to use the OS9P3 module,
~Jcro.~re
C5-9 4sseTbler 2.1
11/18183
'6:95:81
Pege iii
mil
9!912
!1m
8!9' I
8i8' 2
4' ~ • •
I'''''''' t .. I + """
un
f
of
Module
8/8' 4
81S' 5 91C1
TYfe
m1
~e,s
818' 6
818' 7
8m
818'8
me
87CDiiSE
4F533971
9112
II
It .+1 .. ' of of.tI'."'''' to' of
of
set
set
f'l
~Y5tm+Cb:ct
ReEnt+1
]S9E nd I CS9~ame ,Type, Revs I Co I c,156
"JS3p3"
m'e
81m
11m
9ml
91832
ii33
11841
IIW
11&43
1914'
99945
99945
91147
91948
9il4e
!m9
!SiS1
19152
19153
mS4
fd
li ~ ~
8m
level
{I'-I-III-"
ec"
opt
opt
+I+II-I--I-I' ••• ll
~ou;m
8113 31 BCi814
8i17 'i3F32
811 R 39
:old
1 ed~ t lOn n"mter
defs'de
-c
IU •••••••••••••••••• t.I."
Ccle
leey
~vc1bl,pcr
m
FI5Svc
get se'v:ce ·ouhne
lew service
Ln5t~L
rls
... +. II. f I of .... +.t +,. .. I' +.1+ I"' .. 1.1 i .. t.I'. 1+'. I.'.f t •• -l" I' f .......
mss
mS6
18157
Im8
99159
mol
2-2
0l2S
~dc
'
He~der
Md
DS9~eme
I.' f
FISA',I
equ $25 set "P 1e. clL
thlS Ie :,e mr os9defs hie,
..
The Kernel I 2
eql
iliol
lilB
1m2
8m
?S
fcb=SSAVH:
me)
~i1C
ml
iiS6~
!elf
8~
'db
hb
~tcra"e.r~
OS-s
~sseilltder
35-9 Level TWO V1 ,2,
~irt
+
:;aY~I"-2
18i
1fdU1 Pige m
2, \ , \1\8183
1 - 05-9 Syslen SYlbol DeflnlllOnS
moE
'Ser":ee call S~y ~ell~ to use'
19169
iim
ili71
li872
+ I n~ul:
U•
~e91llers
RIX,u •
mn
plr
Mm~ge
plr
~~X rn~s~~3e ~n9th
(If
'
~i
8 ~~nc
bytes.
dE'~.ltJ
Ii 974
11175
'Ou Iput: Message SEn1 to
error FaIr of uw.
51~ndard
lil76
18m
81878
11m
iiial
ma\
m82
91983
8ii84
181B"
i8!BS
'Da la:
D,Free
181 r
1121
1923
PE44
SoyHJ
mo
[024
maDS
m8
18193
lii94
i!i95
gel IE!S. address
)ra l' rot d~fa.l\
ge: pm descr olr
get coller's stad
PSSP ,y
m~s5CJg~
-48, "
rOOT
96~1
lc~
D,SylT;~
[626
:88[8828
39809911
ldb
PlT4SCy
'41
ml
moa
~SS
'y,t"'l t~sl n~m
calle' '5 la,', n~m
,~l by;e counl
jesllnatlo" ptr
":55 lnlc uSer ]ern
ii3A
31:4
me
!I8~m8
il4i
S14,
1145
11 48
DfS!
8128
1m
!ilBS !i33
~il92
199E51
m,u
SayM
~, P"oe
lei~
ma) ii2r
m3S
92198
91891
lax
tne
idy
Idu
'i~B
Jdy
[foX
1~!1
~ellD,pc'
Fl~ov:
e, ~
t41
D, Proc
AGCa32
:m8C
ldy
JdL
Jd.
QS9
mlr.tln
33
rts
SeyHI6
for
set
'1IPT~'2,~
Tal by! ~ count
get p'oc dele ptr
pair num of ~lde'r
~n te ~e,s 1tne
il~9b
m9,
2949
48b:;6C6~
8ma
liSA
iJ
W99
iNI
If I'
9158
511480
~~\lo
icc
fel
em::
\IH~Lo
Ihere
u~er,ll
l~
ncd~le
eRG
2-3
as -9 Technical Reference
W 12
Wi3
8!5E
OS9,nc
9!1 14
equ
~nc
8ml error(s)
81m ~arnln9(sJ
$USE lii94 prog'am bytes gerera:ed
lm~ mil data bytes allocated
12884 . ~m bytes u!ed for synbo:s
SysteIn Call Processing
SYstem calls are used to communicate between 08-9 and assembly-language programs for such functions as memory allocation
and process creation. In addition to lIO and memory management functions, system calls have other functions. These include
interprocess control and timekeeping.
System calls use the SWI2 instruction followed by a constant
byte representing the code. You usually pass parameters for system calls in the 6809 registers.
OS9Defs and Symbolic Names
A system-wide assembly-language equate file, called OS9Defs,
defines symbolic names for all system calls. This file is included
when assembling hand-written or compiler-generated code. The
08-9 assembler has a built-in macro to generate system calls.
For example:
059 I$Read
is recognized and assembled as equivalent to:
SWI2
FCB ]SR.,,,d
The 08-9 assembly macro 089 generates an SWI2 function. The
label I$Read is the label for the code $89.
Types of System Calls
System calls are divided into two categories, 1I0 calls and [urn:tion calls.
2-4
The Kernel ! 2
I/O calls perform various input/output functions. The kernel
passes calls of this type to the 1'0 manager for processing. The
symbolic names for I/O calls begin with 1$. For example, the
Read system call is called I$Read.
Function calls perform memory management, multi-programming, and other functions. Most are processed by the kernel. The
symbolic names for function calls begin with F$. For example,
the Link function call is called F$Link.
The function calls include user calls and privileged system mode
calls. (See Chapter 8, "System Calls", for more information.)
Memory Management
Memory management is an important operating system function.
Using memory modules, OS-9 manages the logical contents of
memory and the physical assignment of memory to programs.
All programs that are loaded must be in the memory module format. This fonnat allows 08-9 to maintain a module directory of
all the programs in memory. The directory contains information
about each module, including its name and address and the
number of processes using it. The number of processes using a
module is called the module's link count.
When a module's link count is zero, OS-9 deallocates its part of
memory and removes its name from the module directory.
Memory modules are the foundation of OS-9's modular software
environment. Advantages of memory management are:
• Automatic runtime linking of programs to libraries of
utility modules
• Automatic sharing of re-entrant programs
• Replacement of small sections of large programs into
memory for update or correction
Memory Use
08-9 reserves some space at the top and bottom of RAM for its
own use. The amount depends on the sizes of system tables that
are specified in the INIT module.
2-5
08-9 Technical Reference
08-9 pools all other RAM into a free memory space. As the system allocates or deallocates memory, it dynamically takes it
from or returns it to this pool. RAM does not need to be contiguous because the memory management unit can dynamically
rearrange memory addresses.
The basic unit of memory allocation is the 256-byte page. 08-9
always allocates memory in whole numbers of pages.
The data structure that OS-9 Level Two uses to keep track of
memory allocation is a 256-byte bit 11ULp. Each bit in this table
is associated with a specific page of memory. A cleared bit indicates that the page is free and available for assignment. A set
bit indicates that the page is in use (that no RAM is free at that
address). 08-9 Level Two always allocates memory in 8192-byte
increments. This is the smallest memory block that the memory
management hardware supports.
08-9 automatically allocates memory when any of the following
occurs:
• Program modules are loaded into RAM
• Processes are created
• Processes execute system calls to request additional
RAM
• 08-9 needs 110 buffers or larger tables
08-9 also has inverse functions to deallocate memory allocated
to program modules, new processes, buffers, and tables.
In general, memory for program modules and buffers is allocated
from high addresses downward. Memory for process data areas is
allocated from low addresses upward.
Fbllowing, is a memory map of a typical system. Actual memory
sizes and addresses can vary depending on the exact system
configuration.
2-6
The Kernel I 2
Color Computer 08-9 Typical Memory Map
.... $7FFFF
liD Device Addresses
Reserved I/O Devices
... $7FFOO
... $7FE80
Reserved Common Memory
08-9 Kernel
+-
$7FEOO
+- varies
Bottom of Memory
in a 128K System
... $60000
Bottom of Memory
in a 512K System
+-
$00000
Figure 2.1
Note: The high two pages of every logical address space
contain the defined areas 110 Device Addresses, Reserved
110 Devices, and Reserved Common Memory.
Memory Management Hardware
The 8-bit CPU in the Color Computer 3 can directly address only
64 kilobytes of memo~y using its 16 address lines (AO-A15). The
Color Computer 3'8 Memory Management Unit (MMU) extends
the addressing capability of the computer by increasing the
address lines to 19 (AD-A18). This lets the computer address up
to 512 kilobytes of memory ($O-$7FFFF).
The 512K address space is called the physical address space. The
physical address space is subdivided into 8K blocks. The six high
order address bits (A13·AIB) define a block number.
2·7
as -9 Technical Reference
08-9 creates a logical address space of up to 64K for each task
by using the FORK system call. Even though the memory
within a logical address space appears to be contiguous, it might
not be-the MMU translates the physical addresses to access
available memory. Address spaces can also contain blocks of
memory that are common to more than one map.
The MMU consists of a multiplexer and a 16 by 6-bit RAM
array. Each of the 6-bit elements in this array is an MMU task
register. The computer uses these task registers to determine
the proper 8-kilobyte memory segment to address.
The MMU task registers are loaded with addressing data by the
CPU. This data indicates the actual location of each 8-kilobyte
segment of the current system memory. The task registers are
divided into two sets consisting of eight registers each. Whether
the task register select bit (TR bit) is set or reset, determines
which of the two sets is to be used.
The relation between the data in the task register and the generated addresses is as follows:
Bit
Corresponding
Memory Address
D5
D4
D3
D2
Dl
DO
AlB
AI?
Al6
A15
Al4
A13
Figure 2.2
When the CPU accesses any memory outside the 110 and control
range (XFFOO = XFFFF), the CPU address lines (A13-A15) and
the TR bit determine what segment of memory to address. This
is done through the multiplexer when SELECT is low. (See the
following table.)
When the CPU writes data to the MMU, AO-A3 determine the
location of the MMU register to receive the incoming data when
SELECT is high. The following diagram illustrates the operation
of the Color Computer 3'8 memory management:
2-8
The Kernel I 2
DO D5
CPU data
A13-Al
TR bit
RAM
y
~
""V
Multiplexer
SELECT
D out
h.
l>
AO-A3
Din
1)
A13-A18
RAO-RA3
v
WE
I
I
f'.-..
V
Figure 2.3
The system uses the data from the MMU registers to determine
the block of memory to be accessed, according to the following
table:
TR
Bit
0
0
0
0
0
0
0
0
1
1
1
1
1
1
1
1
A15 A14 A13
0
0
0
0
1
0
0
1
0
1
0
1
1
0
0
1
1
0
1
1
0
1
1
1
0
0
0
0
a 1
0
1
0
1
0
1
1
0
0
1
1
0
1
1
0
1
1
1
AddressRange
XOOOO-XIFFF
X2000-X3FFF
X4000-X5FFF
X6000-X7FFF
X8000-X9FFF
XAOOO-XBFFF
XCOOO-XDFFF
XEOOO-XFFFF
XOOOO-XIFFF
X2000-X3FFF
X4000-X5FFF
X6000-X7FFF
X8000-X9FFF
XAOOO-XBFFF
XCOOO-XDFFF
XEOOO-XFFFF
MMU
Address
FFAO
FFAl
FFA2
FFA3
FFA4
FFA5
FFA6
FFA7
FFA8
FFA9
FFAA
FFAB
FFAC
FFAD
FFAE
FFAF
Figure 2.4
2-9
08-9 Technical Refere11£e
The translation of physical address to 8K-blocks is as follows:
Range
From
To
00000 OlFFF
02000 03FFF
04000 05FFF
06000 07FFF
08000 09FFF
OAOOO OBFFF
OCOOO ODFFF
OEOOO OFFFF
mock
Number
00
01
02
03
04
05
06
07
08
09
OA
OB
mock
Number
20
21
22
23
24
25
26
27
51FFF
53FFF
55FFF
57FFF
59FFF
5BFFF
5DFFF
5FFFF
28
29
2A
2B
OD
DE
OF
50000
52000
54000
56000
58000
5AOOO
5CODO
5EOOO
2lFFF
23FFF
25FFF
27FFF
29FFF
2BFFF
2DFFF
2EOOa 2FFFF
10
11
12
13
14
15
16
17
60000
62000
64000
66000
68000
6AOOO
6COOO
6EOOO
61FFF
63FFF
65FFF
67FFF
69FFF
6BFFF
6DFFF
6FFFF
30
31
31FFF
33FFF
35FFF
37FFF
39FFF
3BFFF
3DFFF
3FFFF
18
19
lA
70000
72000
74000
76000
78000
7AOOO
7COOO
7EOOO
71FFF
73FFF
75FFF
77FFF
79FFF
7BFFF
7DFFF
7FFFF
10000
12000
14000
16000
18000
lAOOO
1eOOO
lEOOO
11FFF
13FFF
15FFF
17FFF
19FFF
IBFFF
1DFFF
IFFFF
Range
From
To
40000 41FFF
42000 43FFF
44000 45FFF
46000 47FFF
48000 49FFF
4AOOO 4BFFF
4COOO 4DFFF
4EOOO 4FFFF
20000
22000
24000
26000
28000
2AOOO
2COOO
30000
32000
34000
36000
38000
3AOOO
3COOO
3EOOO
OC
IB
IC
ID
IE
IF
Figure 2.5
2·10
2C
2D
2E
2F
32
33
34
35
36
37
38
39
3A
3B
3C
3D
3E
3F
T hR. KernRI / 2
In order for the MMU to function, the TR bit at $FF90 must be
cleared and the MMU must be enabled. However, before doing
this, the address data for each memory segment must be loaded
into the designated set of task registers. For example, to select a
standard 64K map in the top range of the Color Computer 3's
512K RAM, with the TR bit set to 0, the following values must
be preloaded into the MMU's registers:
MMU
Location
Data
Address
(Hex)
FFAO
FFAl
FFA2
FFA3
FFA4
FFA5
FFA6
FFA7
38
39
3A
3B
3C
3D
3E
3F
Data
(Bin)
Address
111000
111001
111010
111011
111100
111101
111110
111111
70000-71FFF
72000-73FFF
74000- 7 5FFF
76000-77FFF
78000-79FFF
7AOOO-7BFFF
7COOO-7DFFF
!,
Range
7EOOO-7FFFF
Figure 2.6
Although this table shows MMU data in the range $38 to 3F,
any data between $0 and $3F can be loaded into the MMU registers to select memory addresses in the range 0 to $7FFFF, as
illustrated by Figure 2.5.
Normally, the blocks containing 110 devices are kept in the system map, but not in the user maps. This is appropriate for timesharing applications, but not for process control. To directly
access liO devices, use the F$MspBlk system call, This call
takes a starting block number and block count, and maps them
into unallocated spaces of the process's address space. The system call returns the logical address at which the blocks were
inserted.
For example, suppose a display screen in your system is allocated at extended addresses $7 AOOO-$7DFFF (blocks 3D and
3E). The following system call maps them into your address
space:
ldb
ldx
#3D
0!59
F$MapBl~
number of bloch;
starting block number
ca 11 MapEU
stu
IOPorts
save address where mapped
#2
2-11
08-9 Technical Reference
On return, the U register contains the starting address at which
the blocks were switched. For example, suppose that the call
returned $4000. 'Ib access extended address $7A020, write to
$4020.
Other system calls that copy data to or from one task's map to
another are available, such as F$STABX and F$Move. Some of
these calls are system mode privileged. You can unprotect them
by changing the appropriate bit in the corresponding entry of
the system service request table and then making a new system
boot with the patched table.
Multiprogramming
08-9 is a multiprogramming operating system, This means that
several independent programs called processes can be executed at
the same time. By issuing the appropriate system call to 08-9,
each process can have access to any system resource.
Multiprogramming functions use a hardware real-time clock.
The clock generates interrupts 60 times per second, or one every
16.67 milliseconds. These interrupts are called ticks.
Processes that are not waiting for some event are called active
processes. 08-9 runs active processes for a specific systemassigned period called a time slice. The number of time slices
per minute during which a process is allowed to execute depends
on a process's priority relative to all other active processes.
Many 08-9 system calls are available to create, terminate, and
control processes.
Process Creation
A process is created when an existing process executes a Fork
system call (F$Fork). This call's main argument is the name of
the program module that the new process is to execute first (the
primary nwdule).
Finding the Module. 08-9 first attempts to find the module in
the module directory. If it does not find the module, 08-9 usually attempts to load into memory a mass-storage file in the execution directory, with the requested module name as a filename.
2·12
T hR- Kernel ! 2
Assigning a Process Descriptor. Once 08-9 finds the module,
it assigns the process a data structure called a process descriptor. This is a 64~byte package that contains information about
the process, its state (see the following section "Process States"),
memory allocations, priority, queue pointers, and so on. 08-9
automatically initializes and maintains the process descriptor.
The process itself cannot access the descriptor; it has no need to
do so.
Allocate RAM. The next step is to allocate RAM for the process. The primary module's header contains a storage size. 08-9
uses this size unless the Fork system call requests a larger area.
08-9 then attempts to allocate a memory area of the specified
size from the free memory space. The memory space does not
need to be contiguous.
Proceed or Terminate. If 08-9 can perform all of the previous
steps, it adds the new process to the active process queue for execution scheduling. If it cannot, it terminates the creation; the
process that originated the Fork is informed of the error.
Assign Process ID and User ID. 08-9 assigns the new process
a unique number called a process ID. Other processes can communicate with the process by referring to its ID in various system calls.
The process also has a user ID, which is used to identify all processes and files belonging to a particular user. The user ID is
inherited from the parent process.
Process Termination. A process terminates when it executes
an Exit system call (F$Exit) or when it receives a fatal signal.
The termination closes any open paths, deallocates memory used
by the process, and unlinks its primary module.
Process States
At any instant a process can be in one of three states:
• Active-The process is ready for execution.
• Waiting-The process is suspended until a child process
terminates or until it receives a signal. A child process
is a process that is started (execution is begun by)
another process--a parent process.
2-13
as -9 Technical Reference
• Sleeping-The process is suspended for a specific period
of time or until it receives a signal.
Each state has its own queue, a linked list of descriptors of processes in that state. To change a process's state, move its
descriptor to another queue.
The Active State. Each active process is given a time slice for
execution, according to its priority. The scheduler in the kernel
ensures that all active processes, even those of low priority, get
some CPU time.
The Wait State. This state is entered when a process executes a
Wait system call (F$Wait). The process remains suspended until
one of its child processes terminates or until it receives a signal.
(See the "Signals" section later in this chapter.)
The Sleeping State. This state is entered when a process executes a Sleep system call (F$Sleep), which specifies the number
of ticks for which the process is to remain suspended. The process remains asleep until the specified time has elapsed or until
it receives a wakeup signaL
Execution Scheduling
The OS-9 scheduler uses an algorithm that ensures that all
active processes get some execution time.
All active processes are members of the active process queue,
which is kept sorted by process age. Age is the number of process
switches that have occurred since the process's last time slice.
When a process is moved to the active process queue from
another queue, its age is set according to its priority-the higher
the priority, the higher the age.
\Vhenever a new process becomes active, the ages of all other
active processes increase by one time slice count. When the executing process's time slice has elapsed, the scheduler selects the
next process to be executed (the one with the next highest age,
the first one in the queue). At this time, the ages of all other
active processes increase by one. Ages never go beyond 255.
A new active process that was terminated while in the system
state is an exception. This process is given high priority because
it is usually executing critical routines that affect shared system
resources.
2-14
The Kernel 12
When there are no active processes, the kernel handles the next
interrupt and then executes a CWA1 instruction. This procedure
decreases interrupt latency time (the time it takes the system to
process an interrupt).
Signals
A signal is an asynchronous control mechanism used for interprocess communication and control. It behaves like a software
interrupt. It can cause a process to suspend a program, execute
a specific routine, and then return to the interrupted program.
Signals can be sent from one process to another process by the
Send system call CF$Send). Or, they can be sent from OS-9 service routines to a process.
A signal can convey status information in the form of a l-byte
numeric value. Some signal codes (values) are predefined, but
you can define most. The signal codes are:
o
Kill (terminates the process, is noninterceptable)
1
Wakeup (wakes up a sleeping process)
2
Keyboard terminate
3
f(eyboard interrupt
4
Window change
128-2.55
User defined
When a signal is sent to a process, the signal is saved in the
process descriptor. If the process is in the sleeping or waiting
state, it is changed to the active state. When the process gets its
next time slice, the signal is processed.
What happens next depends on whether or not the process has
set up a signal intercept trap (signal service routine) by executing an Intercept system call (F$Icpt).
If the process has set up a signal intercept trap, the process
resumes execution at the address given in the Intercept call. The
signal code passes to this routine. Terminate the routine with
an RTI instruction to resume normal execution of the process.
2-15
as -9
Technical Reference
Note: A wakeup signal activates a sleeping process. It sets
a flag but ignores the call to branch to the intercept
routine.
If it has not set up a signal intercept trap, the process is terminated immediately. It is also terminated if the signal code is
zero. If the process is in the system mode, OS-9 defers the termination. The process dies upon return to the user state.
A process can have a signal pending (usually because the process has not been assigned a time slice since receiving the signaD. If it does, and another process tries to send it another
signal, the new signal is terminated, and the Send system call
returns an error. To give the destination process time to process
the pending signal, the sender needs to execute a Sleep system
call for a few ticks before trying to send the signal again.
Interrupt Processing
Interrupt processing is another important function of the kernel.
08-9 sends each hardware interrupt to a specific address. This
address, in turn, specifies the address of the device service routine to be executed. This is called vectoring the interrupt. The
address that points to the routine is called the vector. It has the
same name as the interrupt.
The SWI, SWI2, and SWI3 vectors point to routines that read
the corresponding pseudo vector from the process's descriptor
and dispatch to it. This is why the Set SWI system call
(F$SSWl) is local to a process; it only changes a pseudo vector in
the process descriptor.
Hard ware Vector
Table
2.16
Vector
Address
SWI3
SWI2
FIRQ
IRQ
SWI
NMI
RESTART
$FFF2
$FFF4
$FFF6
$FFF8
$FFFA
$FFFC
$FFFE
The Kernel / 2
FIRQ Interrupt. The system uses the FIRQ interrupt. The
FIRQ vector is not available to you. The FIRQ vector is reserved
for future use. Only one FIRQ generating device can be in the
system at a time.
Logical Interrupt Polling System
Because most OS-9 I/O devices use IRQ interrupts, 08-9
includes a sophisticated polling system. The IRQ polling system
automatically identifies the source of the interrupt, and then executes its associated user- or system-defined service routine.
IRQ Interrupt. Most OS-9 110 devices generate IRQ interrupts.
The IRQ vector points to the real-time clock and the keyboard
scanner routines. These routines, in turn, jump to a special IRQ
polling system that determines the source of the interrupt. The
polling system is discussed in the next section, "Logical Interrupt Polling System."
NMI Interrupt. The system uses the NMI interrupt. The NMI
vector, which points to the disk driver interrupt service routine,
is not available to you.
The Polling Table. The information required for IRQ polling is
maintained in a data structure called the IRQ polling table. The
table has a 9-byte entry for each device that might generate an
IRQ interrupt. The table size is permanent and is defined by an
initialization constant in the INIT module. Each entry in the
polling table is given a number from 0 (lowest priority) to 255
(highest priority). In this way, the more important devices (those
that have a higher interrupt frequency) can be polled before the
less important ones.
Each entry has six variables:
Polling Address
Points to the status register of the device.
The register must have a bit or bits that
indicate if it is the source of an interrupt.
Flip Byte
Selects whether the bits in the device status
register indicate active when set or active
when cleared. If a bit in the flip byte is set,
it indicates that the task is active whenever
the corresponding bit in the status register
is clear.
2-17
as -9 Technical Reference
Mask Byte
Selects one or more interrupt request flag
bits within the device status register. The
bits identify the active task or device.
Service
Routine Address
Points to the interrupt service routine for
the device. You supply this address.
Static
Storage Address
Points to the permanent storage area
required by the device service routine. You
supply this address.
Priority
Sets the order in which the deyices are
polled (a number from 0 to 255).
Polling the Entries. When an IRQ interrupt occurs, 08-9
enters the polling system via the corresponding RAM interrupt
vector. It starts polling the devices in order of priority. 08-9
loads the status register address of each entry into Accumulator
A, using the device address from the table.
08-9 performs an exclusive-OR operation using the flip byte, followed by a logical-AND operation using the mask byte. If the
result is non-zero, OS-9 assumes that the device is the source of
the interrupt.
08-9 reads the device memory address and service routine
address from the table, and performs the interrupt service
routine.
Note: If you are writing your own device driver, terminate
the interrupt service routine with an RTS instruction, not
an RTI instruction.
Adding Entries to the Table. You can make entries to the IRQ
(interrupt request) polling table by using the Set IRQ system
call (F$IRQ). Set IRQ is a privileged system call, 08-9 can execute it only in the system mode. 08-9 is in system mode whenever it is running a device driver.
Note: The code for the interrupt polling system is located
in the I/O Manager module. The 089Pl and 089P2 modules contain the physical interrupt processing routines.
2-18
The Kernel / 2
Virtual Interrupt Processing
A virtual IRQ, or VIRQ, is useful with devices in Multi-Pak
expansion slots. Because of the absence of an IRQ line from the
Multi-Pak interface, these devices cannot initiate physical interrupts. VIRQ enables these devices to act as if they were interrupt driven. Use VIRQ only with device driver and pseudo device
driver modules. VIRQ is handled in the Clock module, which
handles the VIRQ polling table and installs the F$VIRQ system
call. Since the F$VIRQ system call is dependent on clock initialization, the CC3GO module forces the clock to start.
The virtual interrupt is set up so that a device can be interrupted at a given number of clock ticks. The interrupt can occur
one time, or can be repeated as long as the device is used.
The F$VIRQ system call installs VIRQ in a table. This call
requires specification of a 5-byte packet for use in the VIRQ
table. This packet contains:
• Bytes for an actual counter
• A reset value for the counter
• A status byte that indicates whether a virtual interrupt
has occurred and whether the VIRQ is to be re-installed
in the table after being issued
F$VIRQ also specifies an initial tick count for the interrupt.
The actual call is summarized here and is described in detail in
Chapter 8.
Call:
Input:
Output:
089 F$VIRQ
(Y) = address of 5 -byte pocket
(X) = 0 to delete entry, 1 to install
(D) = initial count value
entry
none
(CC) carry set on error
(IS) appropriate error code
The 5-byte packet is defined as follows:
Name
Vi.Cnt
Vi.Rst
Vi.Stat
Offset
$0
$2
$4
Function
Actual counter
Reset value for counter
StatuB byte
2-19
as -9 Technical Reference
Two of the bits in the status byte are used. These are;
Bit 0 - set if VIRQ occurs
Bit 7 - set if a count reset is required
When making an F$VIRQ call, the packet might require initialization with a reset value. Bit 7 of the status byte must be
either set or cleared to signify a reset of the counter or a onetime VIRQ call. The reset value does not need to be the same as
the initial counter value. When 08-9 processes the call, it writes
the packet address into the VIRQ table.
At each clock tick, 08-9 scans the VIRQ table and subtracts one
from each timer value. When a timer count reaches zero, 08-9
performs the following actions:
1. Sets Bit 0 in the status byte. This specifies a Virtual IRQ.
2. Checks Bit 7 of the status byte for a count reset request.
3.
If bit 7 is set, resets the count using the reset value. If bit 7
is reset, deletes the packet address from the VIRQ table.
When a counter reaches zero and makes a virtual interrupt
request, 08-9 runs the standard interrupt polling routine and
services the interrupt. Because of this, you must install entries
on both the VIRQ and DIRQ polling tables whenever you are
using a VIRQ.
Unless the device has an actual physical interrupt, install the
device on the IRQ polling table via the F$IRQ system call before
placing it on the VIRQ table.
If the device has a physical interrupt, use the interrupt's hardware register address as the polling address for the F$IRQ call.
After setting the polling address, set the flip and mask bytes for
the device, and make the F$IRQ call.
If the device is totally VIRQ-driven, and has no interrupts, use
the status byte from the VIRQ packet as the status byte. Use a
mask byte of %00000001, defined as Vi.IFlag in the defs file.
Use a flip byte value of O. The following examples show how to
set up both types of VIRQ calls, The first example is taken from
an ACIA-type driver that has a physical interrupt found in a
status register, but that cannot be accessed by the processor if
used in the Multi-Pak. The second example is for a device with
no physical interrupt handling, all interrupts are handled
through the VIRQ.
2-20
The Kernel i 2
Capyr.gh: 1985,1986 by M.cro.~r~ 5y,t~ms
Rep'odJced Under _Ieen,~
CQrpQr~tJar.
• eetUe~ mes! byte for lerClllare In:errJpt
IRQReo set ::'8BBeeaS Irlerrupl RecJ~sl
• a"set te Ire actual
5:at J5 egu j
~3rj",are
status rqJster
• VIRQ countdown valJe
V,RQCNT eg~ I
do th~ VIRQ on every tid
-+i t-tf f .11 f i l i i f t<f+
• Static storage oFset;
0'9 V,SCF room for sc' vanables
VfRQBUF rrrb 5 Julfer lor fe(e In:errupl frem clad
..... 1.1+-1 If IIIII
• Module Header
mod MEND,NAM,DR[VR+OBuCT ,REENT+t ,EH ,MEM
feb UPDAT,
feb [di !Ian CJrrent
.+.++
+++.11'
~evislon
'
• Drlver entry lump table
ENT lora INIT
lbra READ
Ibr~ WRITE
lbre GETSTA
2-21
as -9 Technical Reference
Ibra PUTSH
bra TRMNAT
ma~k
I
Actual
I
hard\liar~ Int~rrupt
Information for FllRQ call for
MASK feb 8 no flip bJts
lrg poJlJng mask
I fcb IRQR~g
• fcb 18 (hlgh~r)
th~
prl~rity
IllIfflflt'-H.'"
• Inl t
InJtiallle the device
Indud~s ~ettlng up th~ IRQ anc vlRQ
entrle~
[NIT
• Install IRQ polling Table Entry f1ra:
Us~ th~ hard~ar~ statu; reSister and the hard~are
mal k
ldd V.PORT,U get port address In D
add ISta: us po I nt to ~ard'"are status byte
leax MASK,FCR get tn! hardWH! Interrupt mask
l~ay MIRQ,PCR address of lrt~rrJ:lt service routlnf
059 F$[RQ Add to [RQ pollIng tabl~
bcs lNlT9 error - return t1
• lrltall VIRG In
Cloc~
Module !econd
le9y VJRGBUr,U get the 5 byte VIRQ bJ'fer pointer
loa lIaS get re~et flag for repMl~d VIRQ's
St9 VI ,Stat.y put It Into buffer
Idd IV1RQCNT get count I cr number cf tlell for tr! VIRQ
std VI ,Rst,y put In Irl tlal reset vahe
lox '1 put onto tabl ~
D~9 FIVI~Q make th~ service reau~~t
:leI IMIT9 Error - return It
INlT9
READ
2-22
rt~
The Kernel ! 2
WRITE
GETSTA
~uT5TA
'."".'* t
tJ-" t f I I
• SubroutIne TRMNAT
TermInate devICe, Including removal from tables
remove from \lIRQ taole first
ldx Ie remove from V1RG table
leay VIRGBUF,U get addre"
os9 F$VIRa remove modem frem \lIRQ table
• next remove from IRQ ta~l~
l:1x #~
JS9 FtIRQ remove made~ from po1hn3 tll
r t5
I
1111,.** ..... II t t t t t f .
• !III RQ
;lro,e55 Interrupt
actual Interrupt service rcutlne
)
rts
erred Mo~ule ere
rEND ecu •
•
vl~Q Exa~ple
12 - Device Driver
WI thout
1ardware Interrupts
.+.I++I •• li,*,'.
• STATIC STORAGE
DEFIN1TIC~
2·23
os -9
Technical Reference
'lIR~BF rmb 5 "uffer ·Dr
DMEM e,u ,
'l1~Q
• Moduh Header
mod DoNO I D~AI" ,D~ [VR'08"CT I REENT '~E'l ,DENT ,DMEM
fcb U-D~T, mode byte
feb 3 EDITION BYE
• DrIver entry t~ble
DENT lbra IMIT lnl:laLlze
lbra READ
lbra WRrTE
lbra GETSTAT get status
lbra SETSTAT set status
lbra TERM terminate
• M~" Infarmattan paelet for FSIRG call
• NOTE: uses the virtual Interrupt 'lag, Vl, IFlag, for
• the maskbyte
DMSK feb ~ no 'b P bIt s
feb VI,IFlag polbng masl fer VIQQ
feb Ie prIorIty
"'11""".111 ••
• IN[TJALlZE STORAGE AND CO~lROLLER
• Includes settIng ~p the IR, and VI~Q taDle entnes
[N IT
•
•
•
•
set up IRQ lable entry flnt
NOTE: uses the status regIster of the 'lIRG b~ffer for
the Interrupt statJs regIster Slnce no haroware status
regl5ter i, avadaole
leay 'lIRQBF.VI.5tat,U get addres5 of status byte
2-24
The Kernel / 2
tfr y,o ~~t l t 1nto D res
iedy DI~Q,PCR get addr~55 of 1nterrupt routine
leaK DM5K,PCR get VIRO mask Info
059 FII,G lnstdll onto table
bes INIT9 eXl t on !rror
I
no~ set up the VlRQ :cbt~ ~ntry
leay V[~OBF,U pOint to tre 5'byte padel
lda 1$89 get the reset flag to repeat VIRG's
sta Vl.Stet,y save I: l ' tIe buffe'
ldd IV[ROC~T get t'e VIRQ co~nter vdl~e
std Vl.Rst,y save It In h~ re5et area of ~Llffer
ldx II code to Instal: the vlRQ
059 FIVIRa Install on tre table
be: [NIT9 exd on error
I ~ IT9 rts
WD
WRITE
GETmT
PUTmT
IltffUlfttfU Itfl Jt If*
• TERM· termInate the deVIce and r!move entries fro~
• tabl~5
TERM
re~ove from VIRQ t"ble first
ldx I~ get zero to remov~ from table
leily VIRQEF ,U get .ddrm of pac (et
059 FIVIRQ
• then remove froll' IRQ taJle
ldx Ii set z~ro to r~move from table
059 FIIRQ
•
rts
*,t, ,1 .. I'f++-.* t+"
I l f f ' • • 1' ' •• +1 i •• ' t l t l l l l 111 •• f l I ' t ' t .
2-25
as -9 Technical Referen£e
• DIRQ - Interrupt servIce rOJtlne
• iOTE; The ~erVlce routl~e mu~t be ~ure to reset the
• s:atus byte of the VIRQ pa,~et so th.tthe Interrupt
• locks as d tt IS cleared.
01 RG
lda
Cl~da
VI~QEF+Vl.Sta\,U
get status byte
I$'F-Vl.IFlag mask off Interrupt bit
sta VIRGEF'Vl.Stat,U put It bacl
rts
mo
DE~D
END
2·26
equ
Chapter 3
Memory Modules
In Chapter 2. you learned that 08-9 is based on the concept that
memory is modular. This means that each program is considered
to be an individually named object.
You also learned that each program loaded into memory must be
in the module fonnat. This format lets 08-9 manage the logical
contents of memory, as well as the physical contents. Module
types and formats are discussed in detail in this chapter.
Module Types
There are several types of modules. Each has a different use and
function. These are the main requirements of a module:
• It cannot modify itself.
• It must be position-independent so that 08-9 can load or
relocate it wherever space is available. In this respect,
the module format is the 08-9 equivalent of load records
used in older operating systems.
A module need not be a complete program or even 6809 machine
language. It can contain BASIC09 I-code, constants, single subroutines, and subroutine packages.
Module Format
Each module has three parts: a module header. a module body,
and a cyclic-redundancy-check valUE (eRe value).
3·1
08-9 Technical Reference
Module Header
Program
or
Constants
eRe Value
Figure 3.1
Module Header
At the beginning of the module (the lowest address) is the module header. Its form depends upon the module's use.
The header contains information about the module and its use.
This information includes the following:
•
•
•
•
•
Size
Type (machine code, BASIC09 compiled code, and so on)
Attributes (executable, re-entrant, and so on)
Data storage memory requirements
Execution starting address
Usually, you do not need to write routines to generate the modules and headers. All 08-9 programming languages automatically create modules and headers.
Module Body
The module body contains the program or constants. It usually
is pure code. The module name string is included in this area.
Figure 3.2 provides the offset values for calculating the location
of a module's name. (See "Offset to Module Name",)
eRe Value
The last three bytes of the module are the Cyclic Redundancy
Check (CRe) value. The eRe value is used to verify the integrity of a module.
3·2
Memory Modules / 3
When the system first loads the module into memory, it performs a 25-bit CRC over the entire module, from the first byte of
the module header to the byte immediately before the CRC. The
eRC polynomial used is $800FE3.
As with the header, you usually don't need to write routines to
generate the CRC value. Most 08-9 programs do this
automatically.
Module Headers: Standard Information
The first nine bytes of all module headers are defined as follows:
Relative
Address
$00,$01
$02,$03
$04,$05
$06
$07
$08
Use
Sync bytes ($87,$CD)
Module size
Offset to module name
Module typelLanguage
AttributeslRevision level
Header check
Figure 3.2
Sync Bytes
The sync bytes specify the location of the module. (The first sync
byte is the start of the module.) These two bytes are constant.
Module Size
The module size specifies the size of the module in bytes
(includes CRe).
Offset to Module Name
The offset to module name specifies the address of the module
name string relative to the start of the module. The name string
can be located anywhere in the module. It consists of a string of
ASCII characters with the most significant bit set on the last
character.
3·3
08-9 Technical Reference
Type/Language Byte
The type/language byte specifies the type and language of the
module.
The four most significant bits of this byte indicate the type.
Eight types are pre-defined. Some of these are for OS-9's internal use only. The type codes are given here (0 is not a legal type
code):
Code
$lx
$2x
$3x
$4x
$5x-$Bx
$Cx
$Dx
$Ex
$Fx
Module Type
Program module
Subroutine module
Multi-module (for future use)
Data module
User-definable module
OS-9 system module
OS-9 file manager module
08-9 device driver module
OS·9 device descriptor module
Name
Prgrm
Sbrtn
Multi
Data
Systm
FIMgr
Drivr
Devic
Figure 3.3
The four least significant bits of Byte 6 indicate the language
(denoted by x in the previous Figure), The language codes are
given here:
Code
$xO
$xl
$x2
$x3
$x4-$xF
Language
Data (non-executable)
6809 object code
BASIC09 I-code
PASCAL P-code
Reserved for future use
Figure 3.4
By checking the language type, high-level language runtime
systems can verify that a module is the correct type before
attempting execution. BASIC09, for example, can run either 1code or 6809 machine language procedures arbitrarily by checking the language type code.
Attributes/Revision Level Byte
The attributes/revision level byte defines the attributes and revision level of the module.
3·4
Memory Modules I 3
The four most significant bits of this byte are reserved for module attributes. Currently, only Bit 7 is defined. When set, it indicates the module is re-entrant and, therefore, shareable.
The four least significant bits of this byte are a revision level in
the range 0 to 15. If two or more modules have the same name,
type, language, and so on, 08-9 keeps in the module directory
only the module having the highest revision level. Therefore, you
can replace or patch a ROM module, simply by loading a new,
equivalent module that has a higher revision level.
Note: A previously linked module cannot be replaced until
its link count goes to zero.
Header Check
The header check byte contains the one's complement of the
Exclusive-OR of the previous eight bytes.
Module Headers: Type-Dependent
Information
More information usually follows the first nine bytes of a module
header. The layout and meaning vary, depending on the module
type.
Module types $Cx-$Fx (system module, file manager module,
device driver module, and device descriptor module) are used
only by OS-9. Their formats are given later in the manual.
Module types $lx through $Bx have a general-purpose executable format. This format is often used in programs called by
F$Fork or F$Chain. Here is the format used by these module
types:
3·5
OS-9 Technical Reference
Executable Memory Module Format
Relative
Address
Check
Range
Use
$00
f-----
Sync Bytes ($87,$CD)
-
~
Module Size (bytes)
-
Module Name Offset
-
$01
$02
$03
$04
-
header
aity
$05
$06
Type
Language
$07
Attributes
Revision
J
Header Parity Check
$08
$09
Execution Offset
-
Permanent Storage Size
-
,--
$OA
$OB
-
$OC
(Additional optional header
extensions)
$OD
~
•
•
f
•
f
••
f
f
•
•
•
•
I
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Module Body
object code, constants,
and so on
-
f--
CRC Check Value
-
f--
Figure 3.5
3-6
•
•
module
C C
Memnry Modules I 3
As you can see from the preceding chart, the executable memory
has four extra bytes in its header. They are:
$09,$OA
$OB,$OC
Execution offset
Permanent storage size
Execution Offset. The program or subroutine's offset starting
address, relative to the first byte of the sync code. A module that
has multiple entry points (such as cold start and warm start)
might have a branch table starting at this address.
Permanent Storage Size. The minimum number of bytes of
data storage required to run. Fbrk and Chain use this number
to allocate a process's data area.
If the module is not directly executed by a Fork or Chain system
call (for instance a subroutine package), this entry is not used by
OS-9. It is commonly used to specify the maximum stack size
required by re-entrant subroutine modules. The calling program
can check this value to determine if the subroutine has enough
stack space.
When OS-9 starts after a single system reset, it searches the
entire memory space for ROM modules. It finds them by looking
for the module header sync code ($87,$CD).
When OS-9 detects the header sync code, it checks to see if the
header is correct. If it is, the system obtains the module size
from the header and performs a 24-bit eRC over the entire module. If the CRC matches, 08-9 considers the module to be valid
and enters it into the module directory. All ROM modules that
are present in the system at startup are automatically included
in the system module directory.
After the module search, 08-9 links to the component modules it
found. This is the secret to OS-9's ability to adapt to almost any
6809 computer. It automatically locates its required and optional
component modules and rebuilds the system each time it is
started.
3-7
Chapter 4
OS-9's Unified
Input/Output System
Chapter 1 mentioned that 08-9 has a unified I/O system, consisting of all modules except those on the kernel level. This chapter discusses the I/O modules in detail.
I/O System Modules
-
INIT
05·9 KERNEL
(OS9P1, OS9P2)
I--
Clock
I
Input-Output Manager
(lOMAN)
I
I-------.
Disk File
Manager
(RBF)
Clla!, File
Pipe File
Manager
(Pipeman)
Manager
(SCF)
Pllnter
Driver
~ I"
CC3D,sk
DISk
Drr.!r
CC3Hdisk
I
I I
D,sk
Dr'ver
00110111 HO
RBF DeVice Descrrptors
Hl
Pipe
Oliver
(Piper)
I
Pipe
Pipe Descr,
.1
S1Q
0 0
I
Ram
Ram Disk
II
ACIAPak
Oliver
I I
Ml
121
ModPak
Dr ver
I
CC310
I
M2
T31
SCF DeVice DesGilptors
Vdglnt
CC310
In1eriace
Term_Vdg
Dese
Wlndlrrt
CC310
Interlaco
GrJl"t
CC310
Interlace
I !
GriDr.
RI
Ter~;~in I
Wl
II
W2
05-9 COMPONENT MODULE ORGANIZATION
4-1
08-9 Technical Reference
The VDG Interface performs both interface and low level routines
for VDG Color Computer 2 compatible modes and has limited
support for high res screen allocation.
The GrfInt Interface provides the standard code interpretations
and interface functions.
The Windlnt Interfuce, available in the Multi-view package, contains all the functionality of Grflnt, along with additional support features. If you UBe WindInt, do not include Grflnt.
Both Windlnt and Grnnt use the low-level driver GrtDrv to perform drawing on the bit-map screens.
TernL-VDG uses CC3IOIVdglnt while TerIlL-win and all window descriptors use CC3IOf(WindlntlGrflnt)/GrfDrv modules.
The I/O system provides system-wide, hardware-independent I/O
services for user programs and 08-9 itself. All I/O system calls
are received by the kernel and passed to the I/O manager for
processing.
The I/O manager performs some processing, such as the allocation of data structures for the lIO path. Then, it calls the file
managers and device drivers to do most of the work. Additional
file manager, device driver, and device descriptor modules can be
loaded into memory from files and used while the system is
running.
The 110 Manager
The I/O manager provides the first level of service of I/O system
calls. It routes data on lIO process paths to and from the appropriate file managers and device drivers.
The I/O Manager also maintains two important internal 08-9
data structures-the delJice table and the path table. Never modify the I/O manager.
When a path is opened, the I/O manager tries to link to a memory module that has the device name given or implied in the
pathlist. This module is the device descriptor. It contains the
names of the device driver and file manager for the device. The
manager saves the names so later system calls can be routed
to these modules.
va
4·2
08-9'8 Unified Input/Output System /4
File Managers
08-9 can have any number of file manager modules. Each of
these modules processes the raw data stream to or from a class
of device drivers that have similar operational characteristics. It
removes as many unique characteristics as possible from 110
operations. Thus, it assures that similar devices conform to the
08-9 standard I/O and file structure.
The file manager also is responsible for mass storage allocation
and directory processing, if these are applicable to the class of
devices it serves.
File managers usually buffer the data stream and issue requests
to the kernel for dynamic allocation of buffer memory. They can
also monitor and process the data stream, for example, adding
line-feed characters after carriage-return characters.
The file managers are re-entrant. The three standard 08-9 file
managers are:
• Random block file manager: The RBF manager supports
random-access, block-structured devices such as disk systems and bubble memories. (Chapter 5 discusses the
RBF manager in detail.)
• Sequential Character File Manager: The SCF manager
supports single-character-oriented devices, such as CRTs
or hardcopy terminals, printers, and modems. (Chapter 6
discusses SCF in detail.)
• Pipe File Manager (PIPEMAN): The pipe manager supports interprocess communication via pipes.
File Manager Structure
Every file manager must have a branch table in exactly the following format. Routines that are not used by the file manager
must branch to an error routine, that sets the carry and loads
Register B with an appropriate error code before returning. Routines returning without error must ensure that the carry bit is
clear.
4-3
OS·9 Technical Reference
* All
* {y>
*
(U)
ore entered wIth:
Path De5criptor pointer
routlne~
Caller's register stack
pOlnt~r
Entrypt equ ..
lbra Create
Ibra Open
I br
i'l
Mt"I k D i r
lbra ChgDir
Ibra Delete
Ibra Seek
lbra ReCld
Ibra Write
lbr .. ReadLn
Ibra WriteLn
Ibra GetStat
Ibra PutStat
Ibra Close
Create, Open
Create and Open handle file creating and opening for devices.
Typically, the process involves allocating any required buffers,
initializing path descriptor variables, and establishing the path
name. If the file manager controls multi-file devices (RBF),
directory searching is performed to find or create the specified
file.
Makdir
Makdir creates a directory file on multi·file devices. Makdir is
neither preceded by a Create nor followed by a Close. File managers that are incapable of supporting directories need to return
carry set with an appropriate error code in Register B.
ChgDir
On multi-file devices, ChgDir searches for a directory file. If
ChgDir finds the directory, it saves the address of the directory
(up to four bytes) in the caller's process descriptor. The descriptor is located at P$DIO+2 (for a data directory) or P$DIO+8
(for an execution directory),
4·4
OS-9's Unified Input/Output System /4
In the case of the REF manager, the address of the directory's
file descriptor is saved. Open/Create begins searching in the current directory when the caller's pathlist does not begin with a
slash (I). File managers that do not support directories should
return the carry set and an appropriate error code in Register
B.
Delete
Multi-file device managers handle file delete requests by initiating a directory search that is similar to Open. Once a device
manager finds the file, it removes the file from the directory.
Any media in use by the file are returned to unused status. In
the case of the RBF manager, space is returned for system use
and is marked as available in the free cluster bit map on the
disk. File managers that do not support multi· file devices
return an error.
Seek
File managers that support random access devices use Seek to
position file pointers of an already open path to the byte specified. Typically, the positioning is a logical movement. No error is
produced at the time of the seek if the position is beyond the
current "end of file".
Normally, file managers that do not support random access
ignore Seek. However, an SCF-type manager can use Seek to
perform cursor positioning.
Read
Read returns the number of bytes requested to the user's data
buffer. Make sure Read returns an EOF error if there is no data
available. Read must be capable of copying pure binary data, and
generally performs no editing on the data. Generally, the file
manager calls the device driver to actually read the data into
the buffer. Then, the file manager copies the data from the buffer
into the user's data area to keep file managers deviceindependent.
4-5
as -9 Technical Reference
Write
The Write request, like Read, must be capable of recording pure
binary data without alteration. The routines for Read and Write
are almost identical with the exception that Write uses the
device driver's output routine instead of the input routine. The
RBF manager and similar random access devices that use fixedlength records (sectors) must often preread a sector before writing it, unless they are writing the entire sector. In OS-9, writing
past the end of file on a device expands the file with new data.
ReadLn
ReadLn differs from Read in two respects. First, ReadLn terminates when the first end-of-line (carriage return) is encountered.
ReadLn performs any input editing that is appropriate for the
device. In the case of SCF, editing involves handling functions
such as backspace, line deletion, and the removal of the highorder bit from characters.
WriteLn
WriteLn is the counterpart of ReadLn. It calls the device driver
to transfer data up to and including the first (if any) carriage
return encountered. Appropriate output editing can also be performed. For example, SCF outputs a line feed, a carriage return
character, and nulls (if appropriate for the device), It also pauses
at the end of a screen page.
GetStat, PutStat
The GetStat (get status) and PutStat (put status) system calls
are wildcard calls designed to provide a method of accessing fea·
tures of a device (or file manager) that are not generally device
independent. The file manager can perform specific functions
such as setting the size of a file to a given value. Pass unkrwwn
status calls to the driver to provide further means of device independence. For example, a PutStat call to furmat a disk track
might behave differently on different types of disk controllers.
4-6
OS-9's Unified InputlOutput System 14
Close
Close is responsible for ensuring that any output to a device is
completed. (If necessary, Close writes out the last buffer.) It
releases any buffer space allocated in an Open or Create. Close
does not execute the device driver's terminate routine, but can
do specific end-of-file processing if you want it to, such as writing end-of-file records on disks, or form feeds on printers.
Interfacing with Device Drivers
Strictly speaking, device drivers must conform to the general format presented in this manual. The VO Manager is slightly different because it only uses the Init and Terminate entry points.
Other entry points need only be compatible with the file manager for which the driver is written. For example, the Read entry
point of an SCF driver is expected to return one byte from the
device. The Read entry point of an RBF driver, on the other
hand. expects Read to return an entire sector.
The following code is part of an SCF file manager. The code
shows how a file manager might call a driver.
4-7
as -9 Technical Refereru:e
*
"
"
IOEXEC
Execute Devlce's Reed/Write Routine
Passed:
"
*
•
. Output
(n
"
•
CA)
( Xl
(U)
Return5:
CA)
(B)
.
character (write)
Devi.ce Table entry ptr
Path Descrlptor pOinter
Offset of routine (DSRead,
DSWnte)
Input char (read)
Error code, CC ';jet 11 error
Destroys B,CC
IOEXEC p5hs a,x,y,u save registers
ldu VSSTAT,x get 5tetlc ~torage for drlver
ldx VSDRIV,x get drlver module address
Idd MSEXEC,x and off5et of executlon entries
addd 5,s offset by read/wrlte
lecx d,x absolute entry address
Ida ,s+ restore char (for write)
j5r O,x execute driver read/write
puIs x,y,u,pc return (A)~char, (8)~error
emod Module eRC
Slze egu * size of sequential file manager
Device Driver Modules
The device driver modules are subroutine packages that perform
basic, low-level 110 transfers to or from a specific type of I/O
device hardware controller. These modules are re-entrant. So,
one copy of the module can concurrently run several devices that
use identical 110 controllers.
Device driver modules use a standard module header, in which
the module type is specified as code $Ex (device driver), The execution offset address in the module header points to a branch
table that has a minimum of six 3-byte entries.
Each entry is typically an LBRA to the corresponding subroutine. The file managers call specific routines in the device driver
through this table, passing a pointer to a path descriptor and
passing the hardware control register address in the 6809 registers. The branch table looks like this:
4-8
08-9'8 Unified Input/Output System,' 4
Code
Meaning
+$00
Device initialization routine
Read from device
Write to device
Get device status
Set device status
Device termination routine
+$03
+$06
+$09
+$OC
+$OF
CFbr a complete description of the parameters passed to these
subroutines, see the "Device Driver Subroutines" sections in
Chapters 5 and 6.)
4-9
OS -9 Technical Referen£e
Device Driver Module Format
Relative
Address
Check
Range
Use
$00
f---
Sync Bytes ($87,$CD)
-
f---
Module Size (bytes)
-
r---
Module Name Offset
-
$01
$02
$03
$04
$05
$06
Type
Language
$07
Attributes
Revision
$09
$OA
MndUIe
CRe
Header Parity Check
$08
-
Execution Offset
-
-
Permanent Storage Size
-
$OB
$OC
Mode Byte
$OD
f---
Module Body
-
CRC Check Value
-
$OD Mode Byte - (D S PE PW PR E W R)
4-10
JilY
Header
OS-9'8 Unified Input/Output System /4
08-9 Interaction With Devices
Device drivers often must wait for hardware to complete a task
or for a user to enter data. Such a walt situation occurs if an
SCF device driver receives a Read but there is no data is available, or if it receives a Write and no buffer space is available.
08-9 drivers that encounter this situation should suspend the
current process (via F$Sleep). In this way the driver allows other
processes to continue using CPU time.
The most efficient way for a driver to awaken itself and resume
processing data is by using interrupt requests (IRQs). It is possible for the driver to sleep for a number of system clock ticks and
then check the device or buffer for a ready signal. The drawbacks
to this technique are:
• It requires the system clock to always remain active.
• It might require a large number of ticks (perhaps 20) for
the device to become ready. Such a case leaves you with
a dilemma. If you make the program sleep for two ticks,
the system wastes CPU time while checking for device
ready. If the driver sleeps 20 ticks, it does not have a
good response time.
An interrupt system allows the hardware to report to the CPU
and the device drivers when the device is finished with an operation. Using interrupts to its advantage, a device driver can set
up interrupt handling to occur when a character is sent or
received or when a disk operation is complete. There is a built-in
polling facility for pausing and awakening processes. Here is a
technique for handling interrupts in a device driver:
1.
Use the lnit routine to place the driver interrupt service call
(IRQSVC) routine in the IRQ polling sequence via an F$IRQ
system call:
ldd V.Port,u get address to poll
leax IRQPOLL,pcr pOint to IRQ packet
leay IRQSVC,pcr point to IRQ routine
059 F$IRQ add dev to poll sequence
bcs Error abnormal eXIt if error
2.
Ensure that driver programs waiting for their hardware, call
the sleep routine. The sleep routine copies V.Busy to
V.Wake. Then, it goes to sleep for some period of time.
4-11
08-9 Technical Reference
3. When the driver program wakes up, have it check to see
whether it was awakened by an interrupt or by a signal sent
from some other process.
Usually, the driver performs this check by reading the
V.Wake storage byte. The V.Busy byte is maintained by the
file manager to be used as the process ID of the process
using the driver. When V.Busy is copied into V.Wake, then
V.Wake becomes a flag byte and an information byte. A nonzero Wake byte indicates that there is a process awaiting an
interrupt. The value in the Wake byte indicates the process
to be awakened by sending a wakeup signal as shown in the
following code:
lda
sta
V.8usy,~
V.Wake,~
~ndcc
#AIntMasks
SleepSO ldx #0
059 FSSIE'ep
ldx D.Proc
ldb P$Slgnal,x
bne
Si9TE~t
tst V.wake,u
bne Sleepsa
get proc ID
arrangE for wake~p
prep for interrupts
or any other tIck time
( if s i. 9 na I t I'" S t )
await an IRQ
get proc desc ptr if
signal test
15 Signal present?
(If 5ignal test)
bra If 50 If SIgnal
test
IRQ. occur?
bra if not
Note that the code labeled "if signal test" is only necessary
if the driver wishes to return to the caller if a signal is sent
without waiting for the device to finish. Also note that IRQs
and FIRQs must be masked between the time a command is
given to the device and the moving of V.Busy and V.Wake. If
they are not masked, it is possible for the device IRQ to
occur and the IRQSVC routine to become confused as to
whether it is sending a wakeup signal or not.
4.12
08-9'8 Unified Input/Output System /4
4.
When the device issues an interrupt, 08-9 calls the routine
at the address given in F$IRQ with the interrupts masked.
Make the routine as short as possible, and have it return
with an RTS instruction. IRQSVC can verify that an interrupt has occurred for the device. It needs to clear the interrupt to retrieve any data in the device. Then the V.Wake
byte communicates with the main driver module. If V.Wake
is non-zero, clear it to indicate a true device interrupt and
use its contents as the process ID for an F$Send system call.
The F$Send call sends a wakeup signal to the process. Here
is an example:
ldx V.Port,u get deVice addre~~
tst ?? IS it real interrupt from device?
bn~ IRQSVC90 bra to ~rror if not
Ida Data,x get data from deVice
sta O,y
Ida V.Wake,u
beq IRGSVC80 bra If none
clr V.Wake,u clear it as flag to main
routine
ldb #SSWake,u get wakeup Signal
059 FS5end send signal to driver
IRQSVC80 clrb clear carry bit (all IS well)
rt s
IRQSVC90 comb set carry bit
(IS
an IRQ call)
r t s
Suspend State (Level Two only)
The Suspend State allows the elimination of the F$Send system
call during interrupt handling. Because the process is already in
the active queue, it need not be moved from one queue to
another. The device driver IRQSVC routine can now wake up the
:suspended main driver by clearing the process status byte suspend bit in the process state. Following are sample routines for
the Sleep and IRQSVC calls:
Ida D.P~o~ 9~t pro~e5s ptr
sta V.Wake,u prep for re-awake~i~g
enable device to IRQ, give command, etc.
bra CmdSO
e~ter
suspend loop
Cmd30 Idx D.Proc get ptr to proces5
de5C
4·13
08-9 Technical Reference
ld~ P$St~t~,x get st~te flag
ora #Suspend put proc In suspend state
st~ P$State,x save it in proc desc
andcc #~IntMasks unmask Interrupts
Idx #1 give up time slIce
059 FS5leep suspend (In active queue)
CmdSD orce #IntMasKs mask interrupts whIle
changIng 5tate
I d x D. Pro e get pro c des cad dr' ( i f 5 i 9 na I
test)
Ida P$Signal,x get sIgnal (if sIgnal test)
beg SigProc bra if signal to be handled
Ida V.Wake,u true Interrupt?
bne Cmd30 bra if not
andcc #AIntMesks assure interrupts unm~sked
Note that D.Proc is a pointer to the process descriptor of the current process. Process descriptors are always allocated on 256byte page boundaries. Thus, having the high order byte of the
address is adequate to locate the descriptor. D.Proc is put in
V.Wake as a dual value. In one instance, it is a flag byte indicating that a process is indeed suspended. In the other instance,
it is a pointer to the process descriptor which enables the
IRQSVC routine to clear the suspend bit. It is necessary to have
the interrupts masked from the time the device is enabled until
the suspend bit has been set. Making the interrupts ensure that
the IRQSVC routine does not think it has cleared the suspend
bit before it is even set. If this happens, when the bit is set the
process might go into permanent suspension. The IRQSVC routine sample follows:
ldy V.Port,U get dev Bddr
tst V,Wake,u is process aWBltlng
IRQ?
beg
IRQSVCER no exit
clear deVice Interrupt
eXIt if IRQ not from this device
Ida V.Wake,u get process ptr
clrb
stb V.Wnke,u clear proc wnIting flag
tfr d,x get process descrIptor ptr
Ida P$State,x get state flag
anda # Suspend clear ~uspend state
5ta PSState,x save it
4-14
08-9'8 Unified Input/Output System /4
clrb clear carry blt
rt5
IRQSVCER comb ~et carry bit
rts
Device Descriptor Modules
Device descriptor modules are small, non-executable modules.
Each one provides information that associates a specific I/O
device with its logical name, hardware controller addressees),
device driver, file manager name, and initialization parameters.
Unlike the device drivers and file managers, which operate on
classes of devices, each device descriptor tailors its functions to a
specific device. Each device must have a device descriptor.
Device descriptor modules use a standard module header, in
which the module type is specified as code $Fx (device descriptor), The name of the module is the name by which the system
and user know the device (the device name given in pathlists).
The rest of the device descriptor header consists of the information in the following chart:
Relative
Address(es)
$09,$OA
Use
The relative address of the file manager
name string address
$OB,$OC
The relative address of the device driver
name string
$OD
Mode/Capabilities: D S PE PW PR E W R
(directory, single user, public execute, public write, public read, execute, write, read)
$OE,$OF,$10
The absolute physical (24-bit) address of the
device controller
$11
The number of bytes (n bytes) in the initialization table
$12,$12+ n
Initialization table
When 08-9 opens a path to the device, the system copies the initialization table into the option section (PD.OPT) of the path
descriptor. (See "Path Descriptors" in this chapter.)
4-15
as -9 Technical Reference
The values in this table can be used to define the operating
parameters that are alterable by the Get Status and Set Status
system calls (I$GetStt and I$SetStt). For example, parameters
that are used when initializing terminals define which control
characters are to be used for functions such as backspace and
delete.
The initialization table can be a maximum of 32 bytes long. If
the table is fewer than 32 bytes long, 08-9 sets the remaining
values in the path descriptor to O.
You might wish to add devices to your system. If a similar device
driver already exists, all you need to do is add the new hardware
and load another device descriptor. Device descriptors can be in
the boot module or they can be loaded into RAM from mass-storage files while the system is running.
The following diagram illustrates the device descriptor format
4-16
08-9'8 Unified Input/Output System /4
Device Descriptor Format
Relative
Address
$00
Check
Use
Range
-
Sync Bytes ($87,$CD)
-
-
Module Size (bytes)
-
Offset to Module Name
-
$01
$02
$03
$04
f--
$05
$06
F$ (Type)
$1 (Lang)
$07
Attributes
Revision
$08
Header Parity Check
$09
f---
$OA
$OB
f--
Offset to File Manager
Name String
-
Offset to Device Driver
Name String
-
Mode Byte
$00
$OE
I--
$OF
I--
Device Controller
Absolute Physical Addr.
(24 bit)
-
$10
$11
lnitialization Table Size
$12,$12+n
(Initialization Table)
(Name Strings, and so on)
eRe Check Value
4·17
OS·9 Technical Referem:e
Path Descriptors
Every open path is represented by a data structure called a path
descriptor (PD). The PD contains the information the file managers and device drivers require to perform 110 functions.
PDs are 64 bytes long and are dynamically allocated and deallocated by the I/O manager as paths are opened and closed.
They are internal data structures, that are not normally referenced from user or applications programs. The description of PDs
is presented here mainly for those programmers who need to
write custom file managers, device drivers, or other extensions to
OS-g.
PDs have three sections. The first section, which is ten bytes
long, is the same for all file managers and device drivers. The
information in the first section is shown in the following chart.
Path Descriptor: Standard Information
Name
PD.PD
Relative Size
Address (Bytes)
$00
1
Use
Path number
PD.MOD $01
1
Access mode: 1 = read,2
write, 3 = update
PD.CNT $02
1
Number of open paths using
this PD
PD.DEV $03
2
Address of the associated
device table entry
PD.CPR
$05
1
Current process ID
PD.RGS
$06
2
Address of the caller's register stack
PD.BUF
$08
2
Address of the 256-byte
data buffur (if used)
PD.FST
$OA
22
Defined by the file manager
PD.OPT
$20
32
Reserved for the Getstat/
Setstat options
=
PD.FST is 22-byte storage reserved for and defined by each type
of file manager for file pointers, permanent variables, and so on.
4-18
08·9'8 Unified Input/Output System /4
PD.OPT is a 32-byte option area used for file or device operating parameters that are dynamically alterable. When the path is
opened, the 110 manager initializes these variables by copying
the initialization table that is in the device descriptor module.
User programs can change the values later, using the Get Status
and Set Status system calls.
PD.FST and PD.OPT are defined for the file manager in the
assembly-language equate file (SCFDefs for the SCF manager or
RBFDefs for the RBF manager).
4-19
Chapter 5
Random Block File Manager
The random block file manager (RBF manager) supports disk
storage. It is a re-entrant subroutine package called by the I/O
manager for I/O system calls to random-access devices. It maintains the logical and physical file structures.
During normal operation, the RBF manager requests allocation
and deallocation of 256-byte data buffers. Usually, one buffer is
required for each open file. When physical I/O functions are necessary, the RBF manager directly calls the subroutines in the
associated device drivers. All data transfers are performed using
256-byte data blocks (pages).
The RBF manager does not deal directly with physical addresses
such as tracks and cylinders. Instead, it passes to the device
drivers address parameters, using a standard address called a
logical sector number, or LSN. LSNs are integers from 0 to n-l,
where n is the maximum number of sectors on the media. The
driver translates the logical sector number to actual cylinderl
trackJsector values.
Because the RBF manager supports many devices that have different performance and storage capacities, it is highly parameter-driven. The physical parameters it uses are stored on the
media itself.
On disk systems, the parameters are written on the first few
sectors of Track O. The device drivers also use the information,
particularly the physical parameters stored on Sector O. These
parameters are written by the FORMAT program that initializes and tests the disk.
Logical and Physical Disk Organization
All disks used by OS-9 store basic identification, file structure,
and storage allocation information on these first few sectors.
LSN 0 is the identification sector. LSN 1 is the disk allocatwn
map sector. LSN 2 marks the beginning of the disk's ROOT
directory. The following section tells more about LSN 0 and LSN
1.
5-1
os -9 Technical Reference
Identification Sector (LSN 0)
L8N 0 contains a description of the physical and logical characteristics of the disk. These characteristics are set by the FORMAT command program when the disk is initialized.
The following table gives the 08-9 mnemonic name, byte
address, size, and description of each value stored in this LSN O.
Relative Size
Address (Bytes)
$00
3
Use
Number of sectors on disk
DD.TKS
$03
1
Track size (in sectors)
DD.MAP
$04
2
Number of bytes in the allocation bit map
DD.BIT
$06
2
Number of sectors per cluster
DD.DIR
$08
3
Starting sector of the ROOT
directory
DD.OWN
$OB
2
Owner's user number
DD.ATT
SOD
1
Disk attributes
DD.DSK
$OE
2
Disk identification (for internal
use)
DD.FMT
$10
1
Disk format, density, number
of sides
DD.SPT
$11
2
Number of sectors per track
DD.RES
$13
2
Reserved for future use
DD.BT
$15
3
Starting sector of the bootstrap file
DD.BSZ
$18
2
Size of the bootstrap file (in
bytes)
DD.DAT
$lA
5
Time of creation (Y;M;D;H;M)
DD.NAM
$lF
32
Volume name in which the last
character has the most significant bit set
DD.OPT
$3F
Name
DD.TOT
5-2
Path descriptor options
Random Block File Manager / 5
Disk Allocation Map Sector (LSN 1)
LSN 1 contains the disk allocation map, which is created by
FORMAT. This map shows which sectors are allocated to the
files and which are free for future use.
Each bit in the allocation map represents a sector or cluster of
sectors on the disk. If the bit is set, the sector is considered to be
in use, defective, or non-exi8tent. If the bit is cleared, the corresponding cluster is available. The allocation map usually starts
at LSNl. The number of sectors it requires varies according to
how many bits are needed for the map. DD.MAP specifies the
actual number of bytes used in the map.
Multiple sector allocation maps allow the number of 8ectors/cluster to be as small as possible for high volume media.
The FORMAT utility bases the size of the allocation map on the
size and number of sectors per cluster.
The DD.MAP value in LSN 0 specifies the number of bytes (in
LSN 1) that are used in the map.
Each bit on the disk allocation map corresponds to one sector
cluster on the disk. The DD.BIT value in LSN 0 specifies the
number of sectors per cluster. The number is an integral power
of 2 (1, 2, 4, 8, 16, and so on).
If a cluster is available, the corresponding bit is cleared. If it is
allocated, non-existent, or physically defective, the corresponding
bit is set.
ROOT Directory
This file is the parent directory of all other files and directories
on the disk. It is the directory accessed using the physical device
name (such as 1D1). Usually, it immediately follows the Alloca·
tion Map. The location of the ROOT directory file descriptor is
specified in DD.DIR. The ROOT directory contains an entry for
each file that resides in the directory, including other
directories.
File Descriptor Sector
The first sector of every file is the file ckscriptor. It contains the
logical and physical description of the file.
5-3
08-9 Technical Re{ere11£e
The following table describes the contents of the file descriptor.
Name
FD.ATT
Relative Size
Address (Bytes)
$00
1
FD.OWN
$01
2
Owner's user ID
FD.DAT
$03
5
Date last modified: (Y M D H
Use
File attributes: D S PE PW PR
E W R (see next chart)
M)
FD.LNK
$08
1
Link count
FD.SIZ
$09
4
File size (number of bytes)
FD.CREAT $OD
3
Date created (Y M D)
240
Segment list (see next chart)
FD.SEG
$10
FD.ATT. (The attribute byte) contains the file permission bits.
When set the bits indicate the following:
Bit
Bit
Bit
Bit
Bit
Bit
Bit
Bit
7 Directory
6 Single user
5 Public execute
4 Public write
3 Public read
2 Execute
1 Write
0 Read
FD.SEG (the segment list) consists of a maximum of 48 5-byte
entries that have the size and address of each file block in logical
order. Each entry has the block's 3-byte LSN and 2-byte size (in
sectors), The entry following the last segment is zero.
After creation, a file has no data segments allocated to it until
the first write. (Write operations past the current end-of-file
cause sectors to be added to the file. The first write is always
past the end-of-file.)
If the file has no segments, it is given an initial segment. Usually, this segment has the number of sectors specified by the
minimum allocation entry in the device descriptor. If, however,
the number of sectors requested is more than the minimum, the
initial segment has the requested number.
5-4
Random Block File Manager ( 5
Later expansions of the file usually are also made in minimum
allocation increments. Whenever possible, 08-9 expands the last
segment, instead of adding a segment. When the file is closed,
08-9 truncates unused sectors in the last segment.
08-9 tries to minimize the number of storage segments used in
a file. In fact, many files have only one segment. In such cases,
no extra Read operations are needed to randomly access any byte
in the file.
If a file is repeatedly closed, opened, and expanded, it can
become fragmented so that it has many segments. You can avoid
this fragmentation by writing a byte at the highest address you
want to be used on a file. Do this before writing any other data.
Directories
Disk directories are files that have the D attribute set. A directory contains an integral number of entries, each of which can
hold the name and LSN of a file or another directory.
Each directory entry contains 29 bytes for the filename, followed
by the three bytes for the LSN of the file's descriptor sector. The
filename is left-justified in the field, with the most significant bit
of the last character set. Unused entries have a zero byte in the
first filename character position.
Every disk has a master directory called the ROOT directory.
The DD.DIR value in LSN 0 (identification sector) specifies the
starting sector of the ROOT directory.
The RBF Manager Definitions of the Path
Descriptor
As stated earlier in this chapter, the PD.F8T section of the path
descriptor is reserved for and defined by the file manager. The
following table describes the use of this section by the REF manager. For your convenience, it also includes the other sections of
the PD.
5-5
08-9 Technical Reference
Relative Size
Address (Bytes) Use
Name
Universal Section (Same for all file managers and device drivers)
PD.PD
$00
1
Path number
PD.MOO
$01
1
Access
1 =
2 =
3 =
PO.CNT
$02
1
Number of open images (paths
using this PO)
PO.DEV
$03
2
Address of the associated
device table entry
PD.CPR
$05
1
Current process ID
PD.RGS
$06
2
Address of the caller's 6809
register stack
PD.BUF
$08
2
Address of the 256-byte data
buffer (if used)
mode
read,
write,
update
Relative Size
Name
Address (Bytes) Use
The RBF manager Path Descriptor Definitions (PO.FST Section)
PD.SMF
$OA
1
State flag:
Bit 0 = current buffer is
altered
Bit 1 = current sector is in
the buffer
Bit 2 = descriptor sector is
in the buffer
PD.CP
$OB
4
Current logical file position
(byte address)
PD.SIZ
$OF
4
File size
PD.SBL
$13
3
Segment beginning logical sector number (LSN)
PD.SBP
$16
3
Segment beginning physical
sector number (PSN)
5-6
Random Block File Manager I 5
Name
PD.SSZ
Relative Size
Address (Bytes)
$19
3
Use
Segment size
PD.DSK
$lC
2
Disk. ID (for internal use only)
PD.DTB
$lE
2
Address of drive table
Rei a tive Size
Name
Address (Bytes) Use
The REF manager Option Section Definition:s ePD.OPT Section)
(Copied from the device descriptor)
PD.DTP
$20
1
Device class:
o =- SCF
1 = RBF
2 = PIPE
3 = SBF
PD.DRV
$21
1
Drive number (O .. n)
PD.STP
$22
1
Step rate
PD.TYP
$23
1
Device type
PD.DNS
$24
1
Density capability
PD.CYL
$25
2
Number of cylinders (tracks)
PD. SID
$27
1
Number of sides (surfaces)
PD.VFY
$28
1
o=
PD.8CT
$29
2
Default number of sectors per
track
PD.TOS
$2B
2
Default number of sectors per
track (Track 0)
PD.ILV
$2D
1
Sector interleave factor
PD.SAS
$2E
1
Segment allocation size
PD.TFM
$2F
1
DMA transfer mode
PD.EXTEN
$30
2
Path extension for record
locking
PD.STOFF
$32
1
Sector/track offsets
verify disk writes
5-7
OS -9 Technical Reference
Relative Size
Name
Address (Bytes) Use
(Not copied from the device descriptor):
PD.ATT
$33
1
File attributes
(D S PE PW PR E W R)
PD.FD
$34
3
File descriptor PSN
PD.DFD
$37
3
Directory file descriptor PSN
PD.DCP
$3A
4
File's directory entry pointer
PS.DVT
$3E
2
Address of the device table
entry
Any values not determined by this table default to zero.
RBF-Type Device Descriptor Modules
This section describes the use of the initialization table contained in the device descriptor modules for RBF-type devices.
The following values are those the va manager copies from the
device descriptor to the path descriptor.
5-8
Random Block File Manager I 5
Name
Relative Size
Address (Bytes)
$0-$11
Use
Standard device descriptor
module header
IT.DTP
$12
1
Device
0=
1 =
2 =
3 =
IT.DRV
$13
1
Drive number
IT.STP
$14
1
Step rate
IT.TYP
$15
1
Device type (see RBF path
descriptor)
IT.DNS
$16
1
Media density:
Always 1 (double)
(see following information)
IT.CYL
$17
2
Number of cylinders (tracks)
IT.SID
$19
1
Number of sides
IT.VFY
$IA
1
o=
1
=
type:
SCF
RBF
PIPE
SBF
Verify disk writes
no verify
IT.SCT
$lB
2
Default number of sectors per
track
IT.TOS
$lD
2
Default number of sectors per
track (Track 0)
IT.ILV
$lF
1
Sector interleave factor
IT.SAS
$20
1
Minimum size of segment allocation (number of sectors to be
allocated at one time)
IT.DRV is used to associate a I-byte integer with each drive
that a controller handles. Number the drives for each controller
as 0 to n-l, where n is the maximum number of drives the controller can handle.
5·9
OS -9 Technical Reference
IT.TYP specifies the device type (all types).
= 5·inch floppy diskette
Bit 0 -
0
Bit 5 -
0 = Non-Color Computer format
1
Color Computer format
Bit 6 -
0
Standard OS-9 format
Non-standard format
1
Bit 7 -
0
Floppy diskette
1 = Hard disk
IT.DNS specifies the density capabilities (floppy diskette only).
Bit
a- a =
1
Bit 1 -
=
Single-bit density (FM)
Double·bit density (MFM)
a = Single-track density (5-inch, 48 tracks per
inch)
1 = Double-track density (5-inch, 96 tracks per
inch)
IT.MS specifies the minimum number of sectors allowed at one
time.
RBF Record Locking
Record locking is a general term that refers to methods designed
to preserve the integrity of files that can be accessed by more
than one user or process. The 08-9 implementation of record
locking is designed to be as invisible as possible. This means
that existing programs do not have to be rewritten to take
advantage of record locking facilities. You can usually write new
programs without special concern for multi-user activity.
Record locking involves detecting and preventing conflicts during
record access. Whenever a process modifies a record, the system
locks out other procedures from accessing the file. It defers
access to other procedures until it is safe for them to write to the
record. The system does not lock records during reads; so, multiple processes can read the record at the same time.
5.10
Random Block File Manager 15
Record Locking and Unlocking
To detect conflicts, 08-9 must recognize when a record is being
updated. The RBF manager provides true record locking on a
byte basis. A typical record update sequence is:
059 ISRead
progrem reeds record
RECORD IS LOCKED
program updates record
OS9 [SSeek
059
!$Wrlte
repo~ition to record
record i~ rewritten
RECORD [5 RELEASED
When a file is opened in update mode, any read causes locking
of the record being accessed. This happens because the RBF
manager cannot determine in advance if the record is to be
updated. The record stays locked out until the next read, write,
or close.
However, when a file is opened in the read or execute modes, the
system does not lock accessed records because the records cannot
be updated in these two modes.
A subtle but important problem exists for programs that interrogate a data base and occasionally update its data. If you neglect
to release a record after accessing it, the record might be locked
up indefinitely. This problem is characteristic of record locking
systems and you can avoid it with careful programming.
Only one portion of a file can be locked out at a time. If an
application requires more than one record to be locked out, open
multiple paths to the same file and lock the record accessed by
each path. RBF notices that the same process owns both paths
and keeps them from locking each other out.
5-11
as -9 Technical Reference
Non·Shareable Files
Sometimes (although rarely), you must create a file that can
never be accessed by more than one user at a time. To lock the
file, you set the single-user (s) bit in the file's attribute byte. You
can do this by using the proper option when the file is created,
or later using the 08-9 ATTR command. Once the single-user
bit is set, only one user can open the file at a time. If other users
attempt to open the file, Error 253 is returned. Note however,
that non-shareable means only one path can be opened to a file
at one time. Do not allow two processes to concurrently access a
non-shareable file through the same path.
More commonly, you need to declare a file as single-user only
during the execution of a specific program. You can do this by
opening the file with the single-user bit set. For example, suppose a process is sorting a file. With the file's single-user bit set,
08-9 treats the file exactly as though it had a single-user attribute. If another process attempts to open the file, 08-9 returns
Error 253.
You can duplicate non-shareable paths by using the I$Dup system call. This means that it can be inherited, and therefore
accessible to more than one process at a time. Single-user means
that the file can be opened only once.
End·of·File Lock
A special case of record locking occurs when a user reads or
writes data at the end of a file, creating an EOF Lock. An EOF
Lock keeps the end of the file locked out until a process performs
a READ or WRITE that is not at the end of the file. It prevents
problems that might otherwise occur when two users want to
simultaneously extend a file. The EOF Lock is the only case in
which a WRITE call automatically causes portions of a file to be
locked out. An interesting and useful side effect of the EOF Lock
function occurs if a program creates a file for sequential output.
As soon as the program -creates the file, EOF Lock is set and no
other process can pass the writer in processing the file. For
example, if an assembler redirects a listing to a disk file, and a
spooler utility tries to print a line from the file before it is written, record locking makes the spooler wait and stay at least one
step behind the assembler.
5·12
Random Block File Manager I 5
Deadlock Detection
A deadly embrace, or deadlock, typically occurs when two processes attempt to gain control of two or more disk areas at the
same time. If each process gets one area (locking out the other
process), both processes become permanently stuck. Each waits
for a segment that can never become free. This situation is not
restricted to any particular record locking scheme or operating
system.
When a deadly embrace occurs, RBF returns a deadlock error
(Error 254) to the process that caused OS-9 to detect the deadlock. To avoid deadlocks, make sure that processes always access
records of shared files in the same sequence.
When a deadlock error occurs, it is not sufficient for a program
to retry the operation that caused the error. If all processes use
this strategy, none can ever succeed. For any process to proceed,
at least one must cancel operation to release its control over a
requesting segment.
RBF-Type Device Driver Modules
An RBF-type device driver module contains a package of subroutines that perform sector-oriented I/O to or from a specific hardware controller. Such a module is usually re-entrant. Because of
this, one copy of one device driver module can simultaneously
run several devices that use identical 1'0 controllers.
The VO manager allocates a permanent memory area for each
device driver. The size of the memory area is given in the device
driver module header. The lIO manager and the RBF manager
use some of this area. The device driver can use the rest in any
manner. This area is used as follows:
The RBF Device Memory Area Dermitions
Relative Size
Name
V.PAGE
Address (Bytes)
$00
1
Use
Port extended address bits
A20-A16
V.PORT
$01
2
Device base address (defined
by the I/O manager)
5-13
OS -9 Technical Reference
Name
V.LPRC
Relative Size
Address (Bytes)
Use
ID of the last active process
(not used by RBF device
drivers)
$03
1
V.BUSY
$04
1
ID of the current process using
driver (defined by RBF)
o = no current process
V. WAKE
$05
1
ID of the process waiting for
liO completion (defined by the
device driver)
V.USER
$06
o
Beginning of file manager specific storage
V.NDRV
$06
1
Maximum number of drives
the controller can use (defined
by the device driver)
$07
8
Reserved
DRVBEG
$OF
o
Beginning of the drive tables
TABLES
$OF
DRVMEN*N Space for number of tables
reserved (n)
FREE
a
Beginning of space available
for driver
These values are defined in files in the DEFS directory on the
Development Package disk.
TABLES. This area contains one table for each drive that the
controller handles. (The RBF manager assumes that there are as
many tables as indicated by V.NDRV,) Some time after the
driver Init routine is called, the RBF manager issues a request
for the driver to read LSN a from a drive table by copying the
first part of LSN 0 (up to nn.BIZ) into the table. Following is
the format of each drive table:
5-14
Random Block File Manager I 5
Name
DD.TOT
Relative Size
Address (Bytes)
$00
3
DD.TKS
$03
1
Track size (in sectors).
DD.MAP
$04
2
Number of bytes in the allocation bit map.
DD.BIT
$06
2
Number of sectors per bit
(cluster size).
DD.DIR
$08
3
Address (LSN) of the ROOT
directory.
DD.OWN
$OB
2
Owner's user number.
DD.ATT
$OD
1
Use
Number of sectors.
Disk access attributes
S PE PW PR E W R).
(D
DD.DSK
$OE
2
Disk 10 (a pseudo-random
number used to detect diskette
swaps).
DD.FMT
$10
1
Media format.
DD.SPT
$11
2
Number of sectors per track.
(Track 0 can use a different
value specified by IT.TOS in
the device descriptor.)
DD.RES
$13
2
Reserved for future use.
DD.SIZ
$15
o
Minimum
descriptor.
V.TRAK
$15
2
Number of the current track
(the track that the head is on,
and the track updated by the
driver).
V.BMB
$17
1
Bit-map use flag:
o = Bit map is not in use.
(Disk dri ver routines
must not alter V.BMB.)
V.FILEHD $18
2
Open file list for this drive.
SIze
of device
5-15
OS -9 Technical Reference
Relative Size
Address (Bytes)
Name
V.DISKID
$lA
2
Use
Disk ID.
V.BMAPSZ $lC
1
Size of bitmap.
V.MAPSCT $ID
1
Lowest reasonable bitmap
sector.
V.RESBIT
$lE
1
Reserved bitmap sector.
V.SCTKOF $lF
1
Sector/track byte.
V.SCOFST
$20
1
Sector offset
V.sCTKOF.
split
from
V.TKOFST $21
1
Track offset
V.SCTKOF.
split
from
RESERVED $22
4
Reserved for future use,
DRVMEN
$26
Size of each drive table.
The format attributes CDD.FMT) are these:
= Number of sides
o = Single-sided
Bi t BO
1 = Double-sided
Bit Bl
=
1
=
Bit B2
=
1
=
o=
o=
Density
Single-density
Double-density
Track density
Single (48 tracks per inch)
Double (96 tracks per inch)
RBF Device Driver Subroutines
Like all device driver modules, RBF device drivers use a standard executable memory module format.
The execution offset address in the module header points to a
branch table that has six 3-byte entries. Each entry is typically
a long branch (LBRA) to the corresponding subroutine. The
branch table is defined as follows:
5-16
Random Block File Manager / 5
ENTRY
LBRA
LBRA
LBRA
LBRA
LBRA
LBRA
INIT
READ
WRITE
GETSTA
SETSTA
TERM
Initialize drive
Read sector
Write sector
Get status
Set status
Terminate device
Ensure that each subroutine exists with the C bit of the condition code register cleared if no error occurred. If an error occurs,
set the C bit and return an appropriate error code Register B.
The rest of this chapter describes the RBF device driver subroutines and their entry and exit conditions.
5·17
OS -9 Technwal Reference
Init
Initializes a device and the device's memory
area.
Entry Conditions:
Y
=
U
= address of the device menwry area
address of the device descriptor
Exit Conditions:
CC
B
=
carry set on error
= error code (if any)
Additional Information:
• If you want 08-9 to verify disk writes, use the Request
Memory system call (F$8RqMem) to allocate a 256-byte
buffer area in which a sector can be read back and verified
after a write.
• You must initialize the device memory area. For floppy
diskette controllers, initialization typically consists of:
1. Initializing V.NDRV to the number of drives with which
the controller works
2. Initializing DD.TOT (in the drive table) to a non-zero
value so that Sector 0 can be read or written
3. Initializing V.TRAK to $FF so that the first seek finds
Track 0
4. Placing the IRQ service routine on the IRQ polling list,
using the Set IRQ system call (F$IRQ)
5. Initializing the device control registers (enabling interrupts if necessary)
• Prior to being called, the device memory area is cleared (set
to zero), except for V.PAGE and V.PORT. (These areas contain the 24- bit device address.) Ensure the driver initializes each drive table appropriately for the type of diskette
that the driver expects to be used on the corresponding
drive.
5-18
Random BkJck File Manager ( 5
Read
Reads a 256- byte sector from a disk and
places it in a 256-byte sector buffer.
Entry Conditions:
B
X
== LSB of the disk's LSN
Y
=
U
= address of the devi!:e lnenwry area
=
MSB of the disk's LSN
address of the path descriptor
Exit Conditions:
CC
B
=
carry set on error
(if any)
= error code
Additional Information:
• The following is a typical routine for using Read:
1. Get the sector buffer address from PD .BUF in the path
descriptor.
2. Get the drive number from PD.DRV in the path
descriptor.
3. Compute the physical disk address from the logical sector number.
4. Initiate the Read operation.
5. Copy V.BUSY to V.WAKE. The driver goes to sleep and
waits for the I/O to complete. (The IRQ service routine is
responsible for sending a wakeup signal.) After awakening, the driver tests V.WAKE to see if it is clear. If it
isn't clear, the driver goes back to sleep.
• Whenever you read LSN 0, you must copy the first part of
this sector into the proper drive table. (Get the drive number from PD.DRV in the path descriptor.) The number of
bytes to copy is in DD.SIZ. Use the drive number (PD.DRV)
to compute the offset for the corresponding drive table as
follows:
5-19
OS -9 Technical Reference
LDA PD.DRV,Y
LDE #DRVMEN
Get the drive number
Get the ~lze of a
drlv~
MUL
LEAX DRVEEG,U
LEAX D,X
table
Get the addre== of
the fir~t table
Compute the address
of the table
5-20
Random Block File Manager / 5
Write
Writes a 256-byte sector buffer to a disk.
Entry Conditions:
B
=
=
X
Y
U
MSB of the disk LSN
LSB of the disk LSN
address of the path ckscriptor
= address of the device menwry area
=
Exit Conditions:
CC
B
=
=
carry set on error
error code
Additional Information:
• Following is a typical routine for using Write:
1. Get the sector buffer address from PD.BUF m the path
descriptor.
2. Get the drive number from PD.DRV in the path descriptor.
3. Compute the physical disk address from the logical sector
number.
4. Initiate the Write operation.
5. Copy V.BUSY to V.WAKE. The driver then goes to sleep
and waits for the liD to complete. (The IRQ service routine
sends the wakeup signal.) After awakening, the driver tests
V.WAKE to see if it is clear. If it is not, the driver goes
back to sleep. If the disk controller cannot be interrupt-driven, it is necessary to perform a programmed I/O transfer.
6. If PF, VFY in the path descriptor is equal to zero, read the
sector back in and verify that it is written correctly. Verification usually does not involve a comparison of all of the
data bytes .
•
disk writes are to be verified, the [nit routine must
request the buffer in which to place the sector when it is
read back. Do not copy LSN 0 into the drive table when
reading it back for verification.
[f
5-21
08-9 Technical Reference
• Use the drive number (PD.DRV) to compute the offset to
the corresponding drive table as shown for the Read
routine.
5-22
Random Block File Manager I 5
Getstats and Setstats
Reads or changes device's operating parameters.
Entry Conditions:
U
Y
=
address of the device memory area
address of the path descriptor
A
=
status code
=
Exit Conditions:
B
CC
= error code (if any)
=
carry set on error
Additional Information:
• Get/set the device's operating parameters (status) as specified for the Get Status and Set Status system calls. Getsta
and Setsta are wild card calls.
• It might be necessary to examine or change the register
stack that contains the values of the 6809 register at the
time of the call. The address of the register stack is in
PD.RGS, which is located in the path descriptor. You can
use the following offsets to access any value in the register
stack:
Reg.
Relative
Addr.
R$CC
R$D
R$A
R$B
R$DP
$00
$01
$01
$02
$03
1
2
1
1
1
R$X
$04
2
R$Y
R$U
R$PC
$06
$08
$OA
2
2
2
Size
6809 Reg.
Condition Code Reg.
Register D
Register A
Register B
Register DP
Register X
Register Y
Register U
Program Counter
• Register D overlays Registers A and B.
5-23
OS -9 Technical Reference
Term
Terminate a device.
Entry Conditions:
U
=
address of the device menwry area
Exit Conditions:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
• This routine is called when a device is no longer in use in
the system (when the link count of its device descriptor
module becomes zero).
• Following is a typical routine for using Term:
1. Wait until any pending VO is completed.
2. Disable the device interrupts.
3. Remove the device from the IRQ polling list.
4. If the Init routine reserved a 256-byte buffer for verify-
ing disk writes, return the memory with the Return
Sysmem system call (F$SRtMem).
5-24
Random Block File Manager /5
IRQ Service Routine
Services device interrupts.
Additional Information:
• The IRQ Service routine sends a wakeup signal to the process indicated by the process ID in V.WAKE when the VO
is complete. It then clears V.WAKE as a flag to indicate to
the main program that the IRQ has indeed occurred.
• When the IRQ service routine finishes servicing an interrupt it must clear the carry and exit with an RTS
instruction.
• Although this routine is not included in the device driver
module branch table and is not called directly by the RBF
manager, it is a key routine in interrupt-driven drivers. Its
function is to:
1. Service the device interrupts (receive data from device or
send data to it). The IRQ service routine puts its data
into and get its data from buffers that are defined in the
device memory area.
2. Wake up a process that is waiting for 110 to be completed. To do this, the routine checks to see if there is a
process ID in V.WAKE (if the bit is non-zero); if so, it
sends a wakeup signal to that process.
3. If the device is ready to send more data, and the output
buffer is empty, disable the device's ready to transmit
interrupts.
5-25
08-9 Technical Reference
Boot (Bootstran Module)
Loads the boot file into rtAM.
Entry Conditions:
None
Exit Conditions:
D
X
CC
B
=
=
=
=
size of the boot file (in bytes)
address at which the boot file was loaded into memnry
carry set on error
error code (if any)
Additional Information:
• The Boot module is not part of the disk driver. It is a separate module that is stored on the boot track of the system
disk with OS9Pl and REL.
• The bootstrap module contains one subroutine that loads
the bootstrap file and related information into memory. It
uses the standard executable module format with a module
type of $C. The execution offset in the module header contains the offset to the entry point of this subroutine.
• The module gets the starting sector number and size of the
OS9Boot file from LSN O. 08-9 allocates a memory area
large enough for the Boot file. Then, it loads the Boot file
into this memory area.
• Following is a typical routine for using Boot:
1. Read LSN 0 from the
module must pick its
the values for DD.BT
file), and DD.BSZ (the
disk into a buffer area. The Boot
own buffer area. LSN 0 contains
(the 24-bit LSN of the bootstrap
size of the bootstrap file in bytes).
2. Get the 24-bit LSN of the bootstrap file from DD.BT.
3. Get the size of the bootstrap file from DD.BSZ. The Boot
module is contained in one logically contiguous block
beginning at the logical sector specified in DD.BT and
extending for DD.BSZJ256 + 1 sectors.
5-26
Random Block File Manager I 5
4. Use the OS-9 Request Sysmem system call (F$SRqMem)
to request the memory area in which the Boot file is
loaded.
5. Read the Boot file into this memory area.
6. Return the size of the Boot file and its location. Boot file
is loaded.
5-27
Chapter 6
Sequential Character
File Manager
The Sequential Character File Manager (SCF) supports devices
that operate on a character-by-character basis. These include
terminals, printers, and modems.
SCF is a re-entrant subroutine package. The I/O manager calls
the SeF manager for
system handling of sequential, character-oriented devices. The SCF manager includes the extensive 110
editing functions typical of line-oriented operation, such as:
va
• backspace
• line delete
• line repeat
• auto line feed
• screen pause
• return delay padding
The SCF-type device driver modules are CC3IO, PRINTER, and
RS-232. They run the video display, printer, and serial ports
respectively. See the OS-9 Commands manual for additional
Color Computer I/O devices.
SCF Line Editing Functions
The SCF manager supports two sets of read and write functions.
I$Read and I$Write pass data with no modification. I$ReadLn
and I$WritLn provide full line editing of device functions.
Read and Write
The Read and Write system calls to SCF-type devices correspond
to the BASIC09 GET and PUT statements. While they perform
little modification to the data they pass, they do filter out keyboard interrupt, keyboard terminate, and pause character. (Edit·
ing is disabled if the corresponding character in the path
descriptor contains a zero.)
6-1
OS -9 Technical Referena
Carriage returns are not followed by line feeds or nulls automatically, and the high order bitlS are passed as sent/received.
Read Line and Write Line
The Read Line and Write Line system calls to 8CF-type devices
correspond to the BASIC09 INPUT, PRINT, READ, and WRITE
statements. They provide full line editing of all functions enabled
for a particular device.
The system initializes I$ReadLn and I$WritLn functions when
you first use a particular device. (08·9 copies the option table
from the device descriptor table associated with the specific
device.)
Later, you can alter the calls-either from assembly-language
programs (using the Get Status system cam, or from the keyboard (using the TMODE command). All bytes transferred by
Readln and Writln have the high order bit cleared.
SCF Definitions of the Path Descriptor
The PD.FST and PD.OPT sections of the path descriptor are
reserved for and used by the SCF file manager.
The following table describes the SCF manager's use of PD.FST
and PD.OPT. For your convenience, the table also includes the
other sections of the PD.
The PD.OPI' section contains the values that determine the line
editing functions. It contains many device operating parameters
that can be read or written by the Set Status or Get Status system call. Any values not set by this table default to zero.
Note: You can disable most of the editing functions by setting the corresponding control character in the path
descriptor to zero. You can use the Set Status system call
or the TMODE command to do this. Or, you can go a step
further by setting the corresponding control character value
in the device descriptor module to zero.
To determine the default settings for a specific device, you can
inspect the device descriptor.
6-2
Sequential Character File Manager / 6
Relative
Size
Address (Bytes) Use
Name
Universal Section (Same for all file managers)
PD.PD
$00
1
Path number
PD.MOD
$01
I
Access mode:
1 = read
2 = write
3 = update
PD.CNT
$02
1
Number of open images (paths
using this PD)
PD.DEV
$03
2
Address of the associated
device table entry
PD.CPR
$05
1
Current process ID
PD.RGS
$06
2
Address of the caller's 6809
register stack
PD.BUF
$08
2
Address of the 256-byte data
buffer (if used)
Relative
Size
Name
Address (Bytes) Use
SCF Path Descriptor Definitions (PD.FST Section)
PD.DV2
$OA
2
Device table address of the second (echo) device
PD. RAW
$OC
1
Edit flag:
o = raw mode
1 = edit mode
PD.MAX
$OD
2
Read Line maximum character
count
PD.MIN
$OF
1
Devices are mine if cleared
PD.STS
$10
2
Status routine module address
PD.STM
$12
2
Reserved for status routine
6-3
as -9
Technical Reference
Relative
Size Use
Name
Address (Bytes)
SCF Option Section Definition (PD.OPT Section)
(Copied from the device descriptor)
PD.DTP
$20
1
Device class:
o = SCF
1 = RBF
2 = PIPE
3
PD.UPC
$21
1
$22
1
SBF
Case:
o=
1
PD.BSO
=
=
upper and lower
upper only
Backspace:
o = backspace
1 = backspace, space and
backspace
PD.DLO
$23
1
Delete:
o=
1
PD.EKO
$24
1
=
backspace over line
carriage return, line
feed
Echo:
o=
no echo
PD.ALF
$25
1
Auto line feed:
o = no auto line feed
PD.NUL
$26
1
End-of-line null count:
n = number of nulls ($00)
sent after each carnage
return or carriage return
and line feed (n = $OO-$FF)
PD.PAU
$27
1
End of page pause:
o = no pause
PD.PAG
$28
1
Number of lines per page
PD.BSP
$29
1
Backspace character
PD.DEL
$2A
1
Delete-line character
6·4
Sequentwl Character File Manager 16
Relative
Size
Address (Bytes) Use
BCF Option Section Definition continued (PD.OPT Section)
Name
PD.EOR
$2B
1
End-of-record character (Endof-li ne character) Read only.
Normally set to $OD:
o = Terminate read-line
only at the end of the
file
PD.EOF
$2C
1
End-of-file character (read
only)
PD.RPR
$2D
1
Reprint-line character
PD.DUP
$2E
1
Duplicate-last-line character
PD.PSC
$2F
1
Pause character
PD.INT
$30
1
Keyboard-interrupt character
PD.QUT
$31
1
Keyboard-terminate character
PD.BBE
$32
1
Backspace-echo character
PD.OVF
$33
1
Line-overflow character (bell
I CIRL [email protected]])
PD.PAR
$34
1
Device-initialization value
(parity)
PD.BAD
$35
1
Software setable baud rate
PD.D2P
$36
2
Offset to second device name
string
PP.XON
$38
1
ACIA XON char
PD.XOFF
$39
1
ACIA XOFF char
PD.ERR
$3A
1
Most recent I/O error status
PD.TBL
$3B
2
Copy of device table address
PD.PLP
$3D
2
Path descriptor list pointer
PD.PST
$3F
1
Current path status
6·5
as -9 Technical Reference
PD.EOF specifies the end-of-file character. If this is the first
and only character that is input to the SCF device, SCF returns
an end-of-file error on Read or Headln.
PD.PSC specifies the pause character, which suspends output to
the device before the next end-of-record character. The pause
character also deletes any type-ahead input for Readln.
PD.INT specifies the keyboard-interrupt character. When the
character is received, the system sends a keyboard terminate
signal to the last user of a path. The character also terminates
the current 110 request (if any) with an error identical to the
keyboard interrupt signal code.
PD.QUT specifies the keyboard-terminate character. When this
character is received, the system sends a keyboard terminate
signal to the last user of a path. The system also cancels the
current I/O request (if any) by sending error code identical to the
keyboard interrupt signal code.
PD.PAR specifies the parity information for external serial
devices.
PD.BAU specifies baud rate, word length and stop bit information for serial devices.
PD.XON contains either the character used to enable transmission of characters or a null character that disables the use of
XON.
PD.XOFF contains either the character used to disable transmission of characters or a null character that disables the use of
XOFF.
SCF-Type Device Descriptor Modules
The following chart shows how the initialization table in the
device descriptors is used for SCF-type devices. The values are
those the I/O manager copies from the device descriptor to the
path descriptor.
An SCF editing function is turned off if its corresponding value
is set to zero. For example, if IT.EOF is set to zero, there is no
end-of-file character.
6-6
Sequential Character File Manager 16
Name
Size
Relative
Address (Bytes) Use
(header)
$0011
IT.DVe
$12
1
Device class:
o = SCF
1 = RBF
2 = PIPE
3 = SBF
IT.UPC
$13
1
Case:
Standard device descriptor
module header
o=
1
=
upper- and lowercase
uppercase only
IT.BSO
$14
1
Backspace:
o = backspace
1 = backspace, then space
and backspace
IT.DLO
$15
1
Delete:
o = backspace over line
1 = carriage return
IT.EKO
$16
1
Echo:
o=
echo off
IT.ALF
$17
1
Auto line feed:
o = auto line feed disabled
IT.NUL
$18
1
End-of-line null count
IT. PAD
$19
1
Pause:
o = end-of-page pause
disabled
IT.PAG
$lA
1
Number of lines per page
IT.BSP
$lB
1
Backspace character
IT.DEL
$IC
1
Delete-line character
IT.EOR
$lD
1
End-of-record character
IT.EOF
$lE
1
End-of-file character
IT.RPR
$IF
1
Reprint-line character
6-7
OS-9 Teehnical Reference
Name
Relative
Size
Address (Bytes) Use
IT.DUP
$20
1
Duplicate-Iast-line character
IT.PSC
$21
1
Pause character
IT.INT
$22
1
Interrupt character
IT.QUT
$23
1
Quit character
IT.BSE
$24
1
Backspace echo character
IT.OVF
$25
1
Line-overflow character (bell)
IT.PAR
$26
1
Initialization value-used to
initialize a device control register when a path is opened to
it (parity)
IT.BAD
$27
1
Baud rate
IT.D2P
$28
2
Attached device name string
offset
IT.XON
$2A
1
X-ON character
IT,XOFF
$2B
1
X-OFF character
IT.COL
$2C
1
Number of columns for display
IT. ROW
$2D
1
Number of rows for display
IT.WND
$2E
1
Window number
IT.VAL
$2F
1
Data in rest of descriptor
valid
IT.STY
$30
1
Window type
IT.CPX
$31
1
X cursor position
IT.CPY
$32
1
Y cursor position
IT.FGC
$33
1
Foreground color
IT.BGC
$34
1
Background color
IT.BDC
$35
1
Border color
6-8
1S
Sequential Character File Manager 16
SCF-Type Device Driver Modules
An SCF-type device driver module contains a package of subroutines that perform raw (unformatted) data 110 transfers to or
from a specific hardware controller. Such a module is usually reentrant so that one copy of the module can simultaneously run
several devices that use identical I/O controllers. The
I/O manager allocates a permanent memory area for each controller sharing the driver.
The size of the memory area is defined in the device driver module header. The I/O manager and SCF use some of the memory
area. The device driver can use the rest in any way (typically as
variables and buffers). Typically, the driver uses the area as
follows:
Name
Relative
Size
Address (Bytes) Use
V.PAGE
$00
1
Port extended 24 bit address
V.PORT
$01
2
Device base address (defined
by the I/O manager)
V.LPRC
$03
1
ill of the last active process
V.BUSY
$04
1
ID of the active process
(defined by RBF):
o = no active process
V.WAKE
$05
1
ID of the process to reawaken
after the device completes 1'0
(defined by the device driver):
o = no waiting process
V.USER
$06
0
Beginning of file manager
specific storage
V,TYPE
$06
1
Device type or parity
V.LINE
$07
1
Lines left until the end of the
page
V.PAUS
$08
1
Pause request:
o = no pause requested
V.DEV2
$09
2
Attached device memory area
V.INTR
$OB
1
Interrupt character
6-9
os -9 Technical Reference
Name
V.QUIT
Relative
Address
$OC
(Bytes)
Size
1
Use
Quit character
V.PCHR
$OD
1
Pause character
V.ERR
$OE
1
Error accumulator
V.XON
$OF
1
XON character
V.XOFF
$10
1
XOFF character
V.KANJI
$11
1
Reserved
V.KBUF
$12
2
Reserved
V.MODADR
$14
2
Reserved
V.PDLHD
$16
2
Path descriptor list header
V.RSV
$18
5
Reserved
V.SCF
$lD
0
End of SCF memory
requirements
FREE
$lD
0
Free for the device driver to
use
V,LPRC contains the process ID of the last process to use the
device. The IRQ service routine sends this process the proper signal if it receives a quit character or an interrupt character.
V.LPRC is defined by SCF.
V.BUSY contains the process ID of the process that is using the
device. (If the device is not being used, V.BUSY contains a zero,)
The process ID is used by SCF to prevent more than one process
from using the device at the same time. V.BUSY is defined by
SCF.
SCF Device Driver Subroutines
Like all device drivers, SCF device drivers use a standard executable memory module format.
The execution offset address in the module header points to a
branch table that has six 3-byte entries. Each entry is typically
an LBRA to the corresponding subroutine. The branch table is
defined as follows:
6-10
Sequential Character File Manager /6
Ei'lTRY
LBRA
LERA
LBRA
I NIT
WRITE
Initialize driver
Read character
WrIt!" character
LBRA
LBRA
GETSTA
Get status
SETSTA
Set
LBRA
TERM
Terminate device
READ
5tatu~
If no error occurs, each subroutine exits with the C bit in the
Condition Code Register cleared. If an error occurred, each subroutine sets the C bit and returns an appropriate error code in
Register B.
The rest of this chapter describes these subroutines and their
entry and exit conditions.
6-11
as -9
Technical Reference
Init
Initializes device control registers, and
enables interrupts if necessary.
Entry Conditions:
Y
U
=
=
address of the device descriptor
address of the device memory area
Exit Conditions:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Prior to being called, the device memory area is cleared (set
to zero), except for V.PAGE and V.PORT. (V.PAGE and
V.PORT contain the device address,) There is no need to
initialize the part of the memory area used by the 1/0
manager and SCF.
• Follow these steps to use Init:
1. Initialize the device memory area.
2. Place the IRQ service routine on the IRQ polling list,
using the Set IRQ system call CF$IRQ).
3. lnitialize the device control registers.
6-12
Sequential Character File Manager /6
Read
Reads the next character from the input
buffer.
Entry Conditions:
Y
U
=
=
address of the path descriptor
address of the device menwry area
Exit Conditions:
A
CC
B
=
=
=
character read
carry set on error
error code (if any)
Additional Information:
• This is a step by step description of a Read operation:
1.
Read gets the next character from the input buffer.
2. If no data is ready, Read copies its process In from
V.BUSY into V.WAKE. It then uses the Sleep system
call to put itself to sleep.
3.
Later, when Read receives data, the IRQ service routine leaves the data in a buffer. Then, the routine
checks V.WAKE to see if any process is waiting for the
device to complete I/O. If so, the IRQ service routine
sends a wakeup signal to the waiting process.
• Data buffers are not automatically allocated. If a buffer is
used, it defines it in the device memory area.
6-13
as -9 Technical Reference
Write
Sends a character (places a data byte in
an output buffer) and enables the device
output interrupts.
Entry Conditions:
A
Y
U
=
=
=
character to write
address of the path descriptor
address of the ckuice merrwry area
Exit Conditions:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• If the data buffer is full, Write copies its process ID from
V.BUSY into V.WAKE. Write then puts itself to sleep.
Later, when the IRQ service routine transmits a character
and makes room for more data, it checks V.WAKE to see if
there is a process waiting for the device to complete liD. If
there is, the routine sends a wakeup signal to that process.
• Write must ensure that the IRQ service routine that starts
it begins to place data in the buffer. After an interrupt is
generated, the IRQ service routine continues to transmit
data until the data buffer is empty. Then, it disables the
device's ready-to-transmit interrupts.
• Data buffers are not allocated automatically. If a buffer is
used, define it in the device memory area.
6·14
Sequential Character File Manager / 6
Getsta and Setsta
Gets/sets device operating parameters (status) as
specified for the Get Status and Set Status system
calls. Getsta and Setsta are wildcard calls.
Entry Conditions:
A
Y
=
depends on the function code
= address of the path descriptor
U
= address of the device mEmory area
Other registers depend on the function code.
Exit Conditions:
B
= error code (if any)
CC = carry set on error
Other registers depend on the function code
Additional Information:
• Any codes not defined by the VO manager or SCF are
passed to the device driver.
• You might need to examine or change the register stack
that contains the values of the 6809 registers at the time of
the call. The address of the register stack can be found in
PD.RGS, which is located in the path descriptor.
• You can use the following offsets to access any value in the
register packet:
Relative
Size
Name
Address
(Bytes)
R$CC
R$D
R$A
$00
$01
R$B
$01
$02
R$DP
$03
R$X
$04
R$Y
$06
R$U
$08
R$PC
$OA
The function code is
6809 Register
Condition Codes Register
Register D
1
Register A
1
Register B
1
Register DP
2
Register X
2
Register Y
2
Register U
2
Program Counter
retrieved from the R$B on the user stack.
1
0
6-15
OS -9 Technu:al RefereruJe
Term
Terminates a device. Term is called when a
device is no longer in use (when the link
count of the device descriptor module
becomes zero).
Entry Conditions:
U
pointer to the device memory area
=
Exit Conditions:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
• To use Term:
1.
Wait until the IRQ service routine empties the output
buffer.
2. Disable the device interrupts.
3.
Remove the device from the IRQ polling list.
• When Term closes the last path to a device, 08-9 returns
to the memory pool the memory that the device used. If the
device has been attached to the system using the I$Attach
system call, 08-9 does not return the static storage for the
driver until an I$Detach call is made to the device. Modules contained in the Boot file are never terminated, even if
their link counts reach O.
6-16
Sequential Character File Manager / 6
IRQ Service Routine
Receives device interrupts. When 110 is complete, the
routine sends a wakeup signal to the process identified by the process ID in V.WAKE. The routine also
clears V.WAKE as a flag to indicate to the main program that the IRQ has occurred.
Additional Information:
• The IRQ Service Routine is not included in device driver
branch tables, and is not called directly by SCF. However, it
is a key routine in device drivers.
• When the IRQ Service routine finishes servicing an interrupt, the routine must clear the carry and exit with an
RTS instruction.
• Here is a typical sequence of events that the IRQ Service
Routine performs:
L
Service the device interrupts (receive data from the
device or send data to it). Ensure this routine puts its
data into and get its data from buffers that are defined
in the device memory area.
va
to complete.
2. Wake up any process that is waiting for
To do this, the routine checks to see if there is a process ID in V.WAKE (a value other than zero); if so, it
sends a wakeup signal to that process.
3. If the device is ready to send more data, and the output
buffer is empty, disable the device's ready-to-transmit
interrupts.
4.
If a pause character is received, set V.PADS in the
attached device storage area to a value other than zero.
The address of the attached device memory area is in
V.DEV2.
V.PADS in the attached device storage area to non-zero
value. The address of the attached device memory area
is in V.DEV2.
5. If a keyboard terminate or interrupt character is
received, signal the process in V.LPRC (last known
process) if any.
6-17
Chapter 7
The Pipe File Manager
(PIPEMAN)
The Pipe file manager handles control of processes that use
paths to pipes. Pipes allow concurrently executing processes to
send each other data by using the output of one process (the
writer) as input to a second process (the reader). The reader gets
input from the standard input. The exclamation point (!) operator specifies that the input or output is from or to a pipe. The
Pipe file manager allocates a 256-byte block and a path descriptor for data transfer. The Pipe file manager also determines
which process has control of the pipe. The Pipe file manager has
the standard file manager branch table at its entry point;
PipeEnt
lbra Create
Ibra Open
lbra MakDir
Ibra ChgDir
Ibra Delete
Ibra Seek
Ibra PRead
Ibra PWrite
Ibra PRdLn
Ibra PWrLn
Ibra Getstat
Ibra Putstat
Ibra Close
You cannot use MakDir, ChgDir, Delete, and Seek with pipes. If
you try to do so, the system returns E$UNKSVC (unknown service request). Getstat and Putstat are also no-action service routines. They return without error.
Create and Open perform the same functions. They set up the
256-byte data exchange buffer, and save several addresses in the
path descriptor.
The Close request checks to see if any process is reading or writing through the pipe. If not, 08-9 returns the buffer.
PRead, PWrite, PRdLn, and PWrLn read data from the buffer
and write data to it.
7-1
as -9 Technical Reference
The! operator tells the Shell that processes wish to communicate
through a pipe. For example:
proc1
!
proc2
1 ENTER)
In this example, shell forks Procl with the standard output path
to a pipe, and forks Proc2 with the Standard input path from a
pipe.
Shell can also handle a series of processes using pipes. Example:
proc1
! proc2
! proc3 ! proc4 rENTERI
The following outline shows how to set up pipes between
processes:
Open tplpe
Dup path #1
Dup )(
Fork proc1
Close #1
Dup y
Close y
Dup path
Close #0
Dup x
For k 2
Close:: "'0
Dup y
Close x
Close y
7-2
#~
save path in variable x
save stdout in variable y
make path avaIlable
put plpe In stdout
(Dup uses lowest avail~ble)
make path avaIlable
re~tore stdout
make path available
save:: "tdln ln Y
make path available
put pipe In stdln
fork process 2
make path avaIlable
restore :itdin
no longer needed
no longer needed
T/U; Pipe File Manager (PIPEMAN) / 7
Example: The following example shows how an application can
initiate another process with the stdin and stdout routed
through a pipe.
Open /plpe1
Op~n
Iplpe2
Dup 1/1
Dup 1
Close 1/1
Close 1
Dup a
save
save
save
save
moke
make
make
make
path In varlable a
path in varlable b
stdln ln variable x
stdout in variable y
poth available
path avallable
pipe1 stdin
pipe2 5tdout
Dup b
Fork new process
Close 1/1
make path avallable
make path available
Close 1
Dup x
restore stdin
restore stdcut
Dup y
return pipe path numbers to caller
Return a&b
7-3
Chapter 8
System Calls
System calls are used to communicate between the OS-9 operating system and assembly-language programs. There are two
major types of calls-I/O calls and function calls.
Function calls include user mode calls and system mode calls.
Each system call has a mnemonic name. Names of 110 calls start
with 1$. Fbr example, the Change Directory call is I$ChgDir.
Names of function calls start with F$. For example, the Allocate
Bits call is F$AllBit. The names are defined in the assemblerinput conditions equate file called OS9Defs.
System mode calls are privileged. You can execute them only
while 08-9 is in the system state (when it is processing another
system call, executing a file manager or device driver, and so
on).
System mode calls are included in this manual primarily for programmers writing device drivers and other system-level
applications.
Calling Procedure
To execute any system calls, you need to use an SWI2
instruction:
1.
Load the 6809 registers with any appropriate parameters.
2.
Execute an SWI2 instruction, followed immediately by a constant byte, which is the request code. In the references in
this chapter, the first line is the system call name (for example Close Path) and the second line contains the call's mnemonic name (for example I$Close), the software interrupt
Code 2 (103F), and the call's request code (for example, 8F)
in hexadecimal.
3.
After 08-9 processes the call, it returns any parameters in
the 6809 registers. If an error occurs, the C bit of the condition code register is set, and Register B contains the appropriate error code. This feature permits a BCS or BCC
instruction immediately following the system call to branch
either if there is an error or if no error occurs.
8·1
OS -9 Technu.:al Reference
As an example, here is the Close system call:
LDA PATHNUM
SWI2
FCE
$8F
BCS
ERROR
You can use the assembler's 089 directive to simplify the call, as
follows.
LDA
PATHNUM
059
[$Clo!5e
BC5
ERROR
The ASM assembler allows any combination of upper- or lowercase letters. The RMA assembler, included in the 08-9 Level
Two Development Pak, is case sensitive. The names in this manual have been spelled with upper and lower case letters, matching the clefs for RMA.
I/O System Calls
08-9's I/O calls are easier to use than many other systems' I/O
calls. This is because the calling program does not have to allocate and set up file control blocks, sector buffers, and so on.
Instead, 08-9 returns a I-byte path number whenever a process
opens a path to a file or device. Until the path is closed, you can
use this path number in later I/O requests to identify the file or
device.
In addition, 08-9 allocates and maintains its own data structures; so, you need not deal with them.
System Call Descriptions
The rest of this chapter consists of the system call descriptions.
At the top of each description is the system call name, followed
by its mnemonic name, the SWI2 code and the request code.
Next are the call's entry and exit conditions, followed by additional information about the code where appropriate.
In the system call descriptions, registers not specified as entry
or exit conditions are not altered. Strings passed as parameters
are normally terminated with a space character and end-of-line
character, or with Bit 7 of the last character set.
8-2
System Calls / 8
If an error occurs on a system call, the C bit of Register CC is
set, and Register B contains the error code. If no error occurs,
the C bit is clear, and Register B contains a value of zero,
User Mode System Calls Quick Reference
Following is a summary of the User Mode System Calls referenced in this chapter:
F$AllBit
Sets bits in an allocation bit map
F$Chain
Chains a process to a new module
F$CmpNam
Compares two names
F$C py Mem
Copies external memory
F$CRC
Generates a cyclic redundancy check
F$DelBit
Deallocates bits in an allocation bit map
F$Exit
Terminates a process
F$Fork
Starts a new process
F$GBlkMp
Gets a copy of a system block map
F$GModDr
Gets a copy of a module directory
F$GPrDsc
Gets a copy of a process descriptor
F$Icpt
Sets a signal intercept trap
F$ID
Returns a process ID
F$Link
Links to a memory module
F$Load
Loads a module from mass storage
F$Mem
Changes a process's data area size
F$NMLink
Links to a module; does not map the module into the user's address space
F$NMLoad
Loads a module but does not map it into the
user's address space
F$Perr
Prints an error message
F$PrsNam
Parses a pathlist name
F$SchBit
Searches a bit map
8-3
os -9 Technical Reference
F$Send
Sends a signal to a process
F$Sleep
Suspends a process
F$SPrior
Sets a process's priority
F$SSWI
Sets a software interrupt vector
F$STime
Sets the system time
F$SUser
Sets the user ID number
F$Time
Returns the current time
F$UnLink
Unlinks a module
F$UnLoad
Unlinks a module by name
F$Wait
Waits for a signal
I$Attach
Attaches an I/O device
I$Chgdir
Changes a working directory
I$Close
Closes a path
I$Create
Creates a new file
I$Delete
Deletes a file
I$DeletX
Deletes a file from the execution directory
I$Detach
Detaches an I/O device
I$Dup
Duplicates a path
I$GetStt
Gets a device's status
I$MakDir
Creates a directory file
I$Open
Opens a path to an existing file
I$Read
Reads data from a device
I$ReadLn
Reads a line of data from a device
I$Seek
Positions a file pointer
I$SetStt
Sets a device's status
I$Write
Writes data to a device
I$WritLn
Writes a data line to a device
8-4
System Calls / 8
System Mode Calls Quick Reference
Following is a summary of the System Mode Calls referenced in
this chapter:
F$Alarm
Sets up an alarm
F$All64
Allocates a 64-byte memory block
F$AllHRAM
Allocates high RAM
F$AllImg
Allocates image RAM blocks
F$AllPrc
Allocates a process descriptor
F$AlIRAM
Allocates RAM blocks
F$AlITsk
Allocates a process task number
F$AProc
Enters active process queue
F$Boot
Performs a system bootstrap
F$BtMem
Performs a memory request bootstrap
F$ClrBlk
Clears the specified block of memory
F$DATLog
Converts a DAT block offset to a logical
address
F$DelImg
Deallocates image RAM blocks
F$DelPrc
Deallocates a process descriptor
F$DelRAM
Deallocates RAM blocks
F$DeITsk
Deallocates a process task number
F$ELink
Links modules using a module directory
entry
F$FModul
Finds a module directory entry
F$Find64
Finds a 64-byte memory block
F$FreeHB
Gets a free high block
F$FreeLB
Gets a free low block
F$GCMDir
Compacts module directory entries
F$GProcP
Gets a process's pointer
8-5
08-9 Technical Reference
F$IODel
Deletes an 110 module
F$IOQu
Puts an entry into an 1/0 queue
F$IRQ
Makes an entry into IRQ polling table
F$LDABX
Loads Register A from O,X in Task B
F$LDAXY
Loads A[X,[Y]]
F$LDDDXY
Loads OlD + X,[YJ]
F$MapBlk
Maps the specified block
F$Move
Moves data to a different address space
F$NProc
Starts the next process
F$RelTsk
Releases a task number
F$ResTsk
Reserves a task number
F$Ret64
Retums a 64-byte memory block
F$SetImg
Sets a process DAT image
F$SetTsk
Sets a process's task DAT registers
F$SLink
Perfonns a system link
F$SRqMem
Performs a system memory request
F$SRtMem
Performs a system memory return
F$SSvc
Installs a function request
F$STABX
Stores Register A at O,X in Task B
F$VIRQ
Makes an entry in a virtual IRQ polling
table
F$VModul
8-6
Validates a module
User System Calls I 8
User System Calls
Allocate Bits
OS9 F$AllBit l03F 13
Sets bits in an
allocation bit map
Entry Conditions:
D
X
Y
= number of the first bit to set
= starting address of the allocation bit map
=
number of bits to set
Error Output:
CC
=
B
=
carry set on error
error codR (if any)
Additional Information:
• Bit numbers range from 0 to n-l, where n is the number of
bits in the allocation bit map.
• Warning: Do not issue the Allocate Bits call with Register
Y set to 0 (a bit count of 0).
8·7
OS -9 Teehnical Reference
Chain
089 F$Chain 103F 05
Loads and executes a
new primary module
without creating a new
process
Entry Conditions:
language/type code
size of the data area (in pages); must be at least one
page
= address of the module name or filename
= parameter area size (in bytes); defaults to zero if not
specifIed
= starting address of the paramEter area
A
B
=
=
X
Y
U
Error Output:
CC
B
= carry set on eITor
= error code (if any)
Additional Information:
• Chain laMS and executes a new primary module, but does
not create a new process. A Chain system call is similar t(l
a Fbrk followed by an Exit, but it has less processing over·
head. Chain resets the calling process program and data
memory areas and begins executing a new primary module.
It does not affect open paths. This is a user mode system
call.
• Warning: Make sure that the hardware stack pointer (Register SP) is located in the direct page before Chain executes. Otherwise the system might crash or return a
suicide attempt error. This precaution also prevents a suicide in the event that the new module requires a smaller
data area than that in use. Allow approximately 200 bytes
of stack space for execution of the Chain system call.
• Chain performs the follOWing steps:
1. It causes 08-9 to unlink the process's old primary
module.
8-8
User System Calls / 8
2.
08-9 parses the name string of the new process's primary module (the program that is to be executed first).
Then, it causes 08-9 to search the system module
directory to see if a module with the same name, type,
and language is already in memory.
3.
If the module is in memory, it links to it. If the module
is not in memory, it uses the name string as the pathlist of a file to load into memory. Then, it links to the
first module in this file. (Several modules can be loaded
from a singIe file.)
4.
It reconfigures the data memory area to the size specified in the new primary module's header.
5.
It intercepts and erases any pending signals.
The following diagram shows how Chain sets up the
data memory area and registers for the new module.
r-----------,...
Parameter Area
f-------------i _
Y (highest address)
X,8P
Data Area
Direct Page
L-
---'...
U,DP (lowest address)
parameter area size
rrwdule entry point absolute address
= F= 0, 1=0; others are undefined
D
=
PC
CC
=
Registers Y and U (the top-of-memory and bottom-of-memory
pointers, respectively) always have values at page boundaries. If
the parent process does not specify a size for the parameter area,
the size (Register D) defaults to zero. The data area must be at
least one page long.
(For more information, see the Fork system call.)
8-9
OS -9 Technical Reference
Compare Names
089 F$CmpNam l03F 11
Compares two strings
for a match
Entry Conditions:
B
=
X
=
Y
=
length of stringl
address of stringl
address of string2
Exit Conditions:
CC
=
carry clear if the strings match
Additional Information:
• The Compare Names call compares two strings and indicates whether they match. Use this call with the Parse
Name system call~ The second string must have the most
significant bit (Bit 7) of the last character set.
8-10
User System Calls / 8
Copy External
Memory
Reads external memory
into the user's buffer
for inspection
OS9 F$CpyMem
I03F IB
Entry Conditions:
D
X
Y
U
DAT image pointer
offset in bwck to begin copy
byte count
= caller's destination buffer
=
=
=
Error Output:
CC
B
=
=
C bit set on error
appropriate error code
Additional Information:
• You can view any system memory through the use of the
Copy External Memory call. The call assumes X is the
address of the 64K space described by the DAT image
given.
• If you pass the entire DAT image of a process, place a value
in the X Register that equals the address in the process
space. If you pass a partial DAT image (the upper halD,
then place a value in Register X that equals the offset from
the beginning of the DAT image ($8000).
• The support module for this call is OS9p2.
8·11
08-9 Technical Reference
CRC
OS9 F$CRC 103F 17
Calculates the CRC of
a module
Entry Conditions:
X
=
Y
=
U
=
starting byte address
number of bytes
address of the 3-byte eRG accumulator
Exit Conditions:
Updates the CRC accumulator.
Additional Information:
• The eRG call calculates the CRC (cyclic redundancy count)
for use by compilers, assemblers, or other module
generators.
• The calculation begins at the starting byte address and continues over the specified number of bytes.
• You need not cover an entire module in one call, since the
eRe can be accumulated over several calls. The eRe accumulator can be any 3-byte memory area. You must initialize it to $FFFFFF before the first CRe call.
• When checking an existing module eRG, the calculation
should be performed on the entire module (including the
module CRC). The CRe accumulator will contain the CRC
constant bytes if the module CRC is correct.
• If the CRC of a new module is to be generated, the CRC is
accumulated over the module (excluding CRe). The accumulated eRG is complemented then stored in the correct
position in the module.
• Be sure to initialize the eRG accumulator only once for
each module checked by CRe.
8-12
User System Calls;' 8
Deallocate Bits
089 F$DeiBit 103F 14
Clears allocation map
bits
Entry Conditions:
D
=
X
Y
=
=
number of tlu! first bit to set
starting address of the allocation bit map
number of bits to set
Exit Conditions: None
Additional Information:
• The Deallocate Bits call clears bits in the allocation bit
map pointed to by Register X. Bit numbers are in the
range 0 to n-l, where n is the number of bits in the allocation bit map .
• Warning: Do not call Deallocate Bits with Register Y set
to 0 (a bit count of 0).
8-13
OS -9 Technical Reference
Exit
089 F$Exit 103F 06
Terminates the calling
process
Entry Conditions:
B
= status code to return to the parent
Exit Conditions:
The process is terminated.
Additional Information:
• The Exit system call is the only way a process can terminate itself. Exit deal10cates the process's data memory
area, and unlinks the process's primary module. It also
closes all open paths automatically.
• The Wait system call always returns to the parent the status code passed by the child in its Exit call. Therefore, if
the parent executes a Wait and receives the status code, it
knows the child has died. This is a user mode system call.
• Exit unlinks only the primary module. Unlink any module
that is loaded or linked to by the process before calling
Exit.
8-14
User System Calls I 8
Fork
Creates a child process
089 F$Fork I03F 03
Entry Conditions:
X
language/type code
size of the optional data area (in pages)
= address of the nwdule name or filename (See the follow-
Y
= size of the parameter area (in pages); defaults to zero if
U
= starting
A
=
B
=
ing example.)
not specified
address of the parameter area; must be at
least one page
Exit Conditions:
address of the last byte of the name + 1 (See the fol-
X
=
A
lowing example.)
= new process IO number
Error Output:
B
CC
=
error code (if any)
=
carry set on error
Additional Information:
• Fork creates a new process, a child of the calling process.
Fork also sets up the child process's memory and 6809 registers and standard I/O paths.
• Before the Fork call:
~
+
X
8·15
as -9
Technical Reference
• After the Fork call:
~
+
X
• This is the sequence of Fork's operations:
1.
08-9 parses the name string of the new process's primary module (the program that 08-9 executes first).
Then, it searches the system module directory to see if
the program already is in memory.
2a. The next step depends on whether or not the program is
already in memory. If the program is in memory, 08-9
links the module to the process and executes it.
b. If the program is not in memory, OS-9 uses the name
as the pathlist of the file that is to be loaded into memory. Then, the first module in this file is linked to and
executed. (Several modules can be loaded from one file.)
3. 08-9 uses the primary module's header to determine
the initial size of the process's data area. It then tries
to allocate a contiguous RAM area of that size. (This
area includes the parameter passing area, which is copied from the parent process's data area.)
4.
The new process's data memory area and registers are
set up as shown in the following diagram. 08-9 uses
the execution offset given in the module header to set
the program counter to the module's entry point.
.-------------,4-
Parameter Area
1--------------14-
Y
X,SP (highest address)
Data Area
Direct Page
L.-----------1U,DP (lowest address)
8-16
User System Calls / 8
D
PC
CC
=
=
=
size of the parameter area
nwdule entry point absolute address
F = 0, 1=0, other condition code flags are undefined
Registers Y and U (the top-of-memory pointer and bottomof-memory pointer, respectively) always have values at page
boundaries.
As stated earlier, if the parent does not specify the size of
the parameter area, the size defaults to zero. The minimum
overall data area size is one page.
When the shell processes a command line, it passes a
string in the parameter area. This string is a copy of the
parameter part of the command line. To simplify stringoriented processing, the shell also inserts an end-of-line
character at the end of the parameter string.
Register X points to the start byte of the parameter string.
If the command line includes the optional memory size
specification (#11 or #nK), the shell passes that size as the
requested memory size when executing the Fork.
• If any of the preceding operations is unsuccessful, the Fork
is terminated and 08-9 returns an error to the caller.
• The child and parent processes execute at the same time
unless the parent executes a Wait system call immediately
after the Fork. In this case, the parent waits until the child
dies before it resumes execution.
• Be careful when recursively calling a program that uses
the Fork system call. Another child can be created with
each new execution. This continues until the process table
becomes full.
• Do not fork a process with a memory size of O.
8·17
08-9 Technical Refereru:e
Get System
Block Map
Gets a copy of the
system block map
089 F$GBlkMp 103F 19
Entry Conditions:
X
=
pointer to the 1024 -byte buffer
Exit Conditions:
D
=
Y
=
number of bytes per block ($2000) (MMU block size
dependent)
system memory block map size
Error Output:
CC
B
= carry set on error
= error code (if any)
Additional Information:
• The Get System Block Map call copies the system's memory
block map into the user's buffer for inspection. The 08-9
MFREE command uses this call to find out how much free
memory exists.
• The support module for this call is OS9p2.
8·18
User System Calls! 8
Get Module
Directory
Gets a copy of the
system module
directory
F$GModDr l03F lA
Entry Conditions:
X
= pointer to the 2048-byte buffer
Y
=
U
=
end of copied module directory
start address of system module directory
Error Output:
CC
B
=
carry set on error
=
error code (if any)
Additional Information:
• The Get Module Directory call copies the system's module
directory into the user's buffer for inspection. The 08-9
MDIR command uses this call to read the module
directory.
• The support module for this call is OS9p2.
8-19
OS -9 Technu.:al Reference
Get Process
Descriptor
Gets a copy of the
process's process
descriptor
F$GPrDsc l03F 18
Entry Conditions:
A
X
=
=
reqURsted process ID
pointer to a 512 -byte buffer
Error Output:
CC
B
=
=
carry set on error
error code (if anyl
Additional Information:
• The Get Process Descriptor call copies a process descriptor
into the calling process's buffer for inspection. The data in
the process descriptor cannot be changed. The OS-9 PROCS
command uses this call to get information about each existmg proceslS.
• The support module for this call is OS9p2.
8·20
U.;er System Calls I 8
Intercept
089 F$Icpt 103F 09
Sets a signal intercept
trap
Entry Conditions:
X
U
address of the intercept routinR
starting address of the routine's memory area
=
=
Exit Conditions:
Signals sent to the process cause the intercept routine to be
called instead of the process being kined.
Additional Information:
• Intercept tells 08-9 to set a signal intercept trap. Then,
whenever the process receives a signal, 08-9 executes the
process's intercept routine.
• Store the address of the signal handler routine in Register
X and the base addres5 of the routine's storage area in
Register D.
• Once the signal trap is set, 08-9 can execute the intercept
routine at any time because a signal can occur at any
time.
• Terminate the intercept routine with an RTI instruction.
• If a process has not used the Intercept system call to set a
signal trap, the process terminates if it receives a signal.
• This is the order in which F$Icpt operates:
L
When the process receives a signal, 08-9 sets Registers
D and B as follows:
e
=
B
=
8tarting address of the intercept routine's
memory area
signal code iprocess's termination status)
Note: The value of Register DP cannot be the
same as it was when the Intercept call was
made.
2.
After setting the registers. OS-9 transfers execution to
the intercept routine.
8-21
OS -9 Technical Reference
Get ID
089 F$ID l03F OC
Return's a caller's
process ID and user ID
Entry Conditions:
None
Exit Conditions:
A
Y
=
=
process ID
user ID
Additional Information:
• The process ID i::; a byte value in the range 1 to 255. 08-9
assigns each process a unique process ID.
• The user ID is an integer from 0 to 65535. It is defined in
the system password file. and is used by the file security
system and a few other functions. Several processes can
have the same user ID.
• On a single user system (such as the Color Computer 31,
the user ID is inherited from CC3go, \vhich forks the initial
shell.
8-22
User System Calls / 8
Link
089 F$Link I03F 00
Links to a memory
module that has the
specified name,
language, and type
Entry Conditions:
A
=
X
=
type/language byte
address of the module name (See the following
example.)
Exit Conditions:
type/language code
A
B
= attributes / reviswn level (if no error)
X
=
arklress of the last byte of the module name
Y
=
U
=
the following example.)
module enlry poinl absolute address
module header absolute address
=
+
1 (See
Error Output:
CC
= C bit
set if error encountered
Additional Information:
• The module's link count increases by one whenever Link
references its name. Incrementing in this manner keeps
track of how many processes are using the module.
• If the module requested is not shareable (not re-entrant),
only one process can link to it at a time.
• Before the Link call:
~
+
X
• After the Link call:
~
+
X
8-23
as -9 Technical Reference
• This is the order in which the Link call operates:
1.
08-9 searches the module directory for a module that
has the specified name, language, and type.
2.
If 08-9 finds the module, the address of the module's
header is returned in Register U, and the absolute
address of the module's execution entry point is
returned in Register Y. (This, and other information is
contained in the module header.)
• If 08-9 doesn't find the module-or if the type/language
codes in the entry and exit conditions don't match-OS-9
returns one of the following errors:
• Module not found
• Module busy (not shareable and in use)
• Incorrect or defective module header
8·24
User System Calls / 8
Load
089 F$Load 103F 01
Loads a module or
modules from a file
Entry Conditions:
A
X
=
=
language/type code; 0 = any language/type
address of the pathlist (filename) (See the following
example.)
Exit Conditions:
A
= language/type code
B
X
attributes / revision level (if no error)
address of the last byte of the pathlist (filename) + 1
(See the following example.)
= primary module entry point address
= address of the nwdule header
=
=
Y
U
Error Output:
CC
=
carry set if error encountered
Additional Information:
• The Load call loads one or more modules from the file specified by a complete pathlist or from the working execution
directory (if an incomplete pathlist is given).
• The file must have the execute access mode bit set. It also
must contain one or more with proper module headers.
• OS-9 adds all modules loaded to the system module directory. It links the first module read. The exit conditions
apply only to the first module loaded.
• Before the Load call:
cz::I:QIQJ / I A I c @I!li] Ric
...
~
X
8-25
as -9 Technical Reference
After the Load call:
• Possible errors:
• Module directory full
• Memory full
• Errors that occur on the Open, Read, Close, and Link
system calls
8·26
User System Calls / 8
Memory
089 F$Mem
103F 07
Changes process's data
area size
Entry Conditions:
D
=
size of the new memory area (in bytes);
o = return current size and upper bound
Exit Conditions:
Y
D
=
=
address of the new memory area upper bound
actual size of the new memory (in bytes)
Error Output:
CC
B
= carry set on error
= error code (if any)
Additional Information:
• The memory call expands or contracts the process's data
memory area to the specified size. Or, if you specify zero as
the new size, the call returns the current size and upper
boundaries of data memory.
• 08-9 rounds off the size to the next page boundary. In aUocating additional memory, 08-9 continues upward from the
previous highest address_ In deallocating unneeded memory, it continues downward from that address.
8-27
08-9 Technical Reference
Link to a module
089 F$NMLink
103F 21
Links to a module;
does not map the
module into the user"s
address space
Entry Conditions:
= type!language byte
A
X
= address of the mndule name
Exit Conditions:
A
B
X
=
Y
=
=
type/language code
=
module revision
address of the last byte of the module name + 1; any
trailing blanks are skipped
storage requirement for the module
Error Output:
CC
= carry set on error
B
= error code if any
Additional Information:
• Although this call is similar to F$Link, it does not map
the specified module into the user's address space but does
return the memory requirement for the module. A calling
process can use this memory requirement information to
fork a program with a maximum amount of space.
F$NMLink can therefore fork larger programs than can be
forked by F$Link.
8-28
User System Calls I 8
Load a module
089 F$NMLoad
l03F 22
Loads one or more
modules from a file but
does not map the
module into the user's
address space
Entry Conditions:
type/language byte
A
=
X
= address of the pathlist
Exit Conditions:
A
B
X
Y
=
type/language code
= mndule revision
= address of the last byte of the pathlist + 1
= storage requirement for the mndule
Error Output:
CC
B
=
=
carry set on error
error codE if any
Additional Information:
• If you do not provide a full pathlist for this call, it attempts
to load from a file in the current execution directory.
• Although this call is similar to F$Load, it does not map
the specified module into the user's address space but does
return the memory requirement for the module. A calling
process can use this memory requirement infonnation to
fork a program with a maximum amount of space.
F$NMLoad can therefore fork larger programs than can be
forked by F$Load.
8-29
OS -9 Technical Reference
Print Error
089 F$Perr l03F OF
Writes an error
message to a specified
path
Entry Conditions:
B
=
error code
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Print Error writes an error message to the standard error
path for the specified process. By default, 08-9 shows:
ERROR #declmal number
• The error reporting routine is vectored. Using the Set sve
system call, you can replace it with a more elaborate
reporting module.
8-30
User System Calls I 8
Parse Name
089 F$PrsNam 103F 10
Scans an input string
for a valid OS·9 name
Entry Conditions:
X
=
address of the pathlist (See the following example.)
Exit Conditions:
X
Y
A
B
= address of the optional slash + 1
address of the last character of the name + 1
trailing byte (delimiter character)
= length of the name
=
=
Error Output:
CC
B
Y
=
=
=
carry set
error code
address of the first non-delimiter character in the
string
Additional Information:
• Parses, or scans, the input text string for a legal 08-9
name. It terminates the name with any character that is
not a legal name character.
• Parse Name is useful for processing pathlist arguments
passed to new processes.
• Because Parse Name processes only one name, you might
need several calls to process a pathlist that has more than
one name. As you can see from the following example,
Parse Name finishes with Register Y in position for the
next parse.
• If Register Y was at the end of a pathlist, Parse Name
returns a bad name error, It then moves the pointer in Register Y past any space characters so that it can parse the
next pathlist in a command line.
8-31
os -9 Technical Reference
• Before the Parse Name call:
+
X
After the Parse Name call:
+
X
8-32
+
Y
User System Calls I 8
Search Bits
089 F$8chBit 103F 12
Searches a specified
memory allocation bit
map for a free memory
block of a specified
size
Entry Conditions:
starting bit number
starting address of the map
= bit count (free bit block size)
= ending address of the map
D
=
X
=
Y
U
Error Output:
cc
=
C bit set
Exit Conditions:
D
Y
= starting bit number
= bit count
Additional Information:
• The Search Bit call searches the specified allocation bit
map for a free block (cleared bits) of the required length.
The search starts at the starting bit number. If no block of
the specified size exists, the call returns with the carry set,
starting bit number, and size of the largest block.
8-33
as -9 Technical Reference
Send
Sends a signal to a
089 F$8end l03F 08
specified process
Entry Conditions:
A
=
B
=
destination's process ID
signal code
Error Output:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
• The signal code is a single byte value in the range 0
through 255.
• If the destination process is sleeping or waiting, 08-9 acti-
vates the process so that the process can process the signal.
• If a signal trap is set up, F$Send executes the signal processing routine (Intercept). If none was set up, the signal
terminates the destination process, and the signal code
becomes the exit status. (See the Wait system call.) An
exception is the wakeup signal; that signal does not cause
the signal intercept routine to be executed.
• Signal codes are defined as follows:
o
1
2
3
128-255
=
=
=
=
=
System terminate
(cannot be intercepted)
Wake up the process
Keyboard terminate
Keyboard interrupt
User defined
• If you try to send a signal to a process that has a signal
pending, OS-9 cancels the current Send call, and returns
an error. Issue a Sleep call for a few ticks; then, try again.
• The Sleep call saves CPU time. See the Intercept, Wait,
and Sleep system calls for more information.
8-34
User System Calls I 8
Sleep
Temporarily turns off
089 F$Sleep l03F OA
the calling process
Entry Conditions:
X
=
One of the following:
sleep timE (in ticks)
o (sleep indefinitely)
1 (sleep for the remainder of
the current time slice)
Exit Conditions:
X
=
sleep time minus the number of ticks that the process
was asleep
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• If Register X contains 0, 08-9 turns the process off until it
receives a signal. Putting a process to sleep is a good way
to wait for a signal or interrupt without wasting CPU time.
• If Register X contains 1, 08-9 turns the process off for the
remainder of the process's current time slice. It inserts the
process into the active process queue immediately. The process resumes execution when it reaches the front of the
queue.
• If Register X contains an integer in the range 2-255, 08-9
turns off the process for the specified number of ticks, n. It
inserts the process into the active process queue after n-l
ticks. The process resumes execution when it reaches the
front of the queue. If the process receives a signal, it awakens before the time has elapsed.
• When you select processes among multiple windows, you
might need to set sleep for two ticks.
8-35
as -9 Technical Reference
Set Priority
089 F$8Prior l03F
on
Changes the priority
of a process
Entry Conditions:
A
B
=
process ID
= priority
a=
255
=
lowest
highest
Error Output:
CC
B
=
carry set on error
=
error code (if any)
Additional Information:
• Set Priority changes the process's priority to the priority
specified. A process can change another process's priority
only if it has the same user ID.
8-36
User System Calls 18
Set SWI
089 F$88WI l03F OE
Sets the SWI2 and
SWI3 vectors
Entry Conditions:
A
X
=
=
SWI type code
address of the user software interrupt routine
Exit Conditions:
CC
B
carry set on error
= error code (if any)
=
Additional Information:
• Sets the interrupt vectors for SWI, SWI2 and SWI3
instructions.
• Each process has its own local vectors. Each Set SWI call
sets one type of vector according to the code number passed
in Register A:
1 = SWI
2 = SWI2
3
=
SWI3
• When 08-9 creates a process, it initializes all three vectors
with the address of the 08-9 service call processor.
• Warning: Microware-supplied software uses SWI2 to call
OS-9. If you reset this vector, these programs cannot work.
If you change all three vectors, you cannot call 08-9 at all.
8·97
as -9
Technical Reference
Set Time
OS9 F$STime 103F 16
Sets the system time
and date
Entry Conditions:
= relative address of the time pm:ket
X
Error Output:
cc
B
=
=
C bit set
error code
Additional Information:
• Set Time sets the current system date and time and starts
the system real-time clock. The date and time are passed
in a time packet as follows.
Relative
Address
o
1
2
3
4
5
Value
year
month
day
hours
minutes
seconds
Then, the call makes a link system call to find the clock. If
the link is successful, OS-9 calls the clock initialization.
The clock initialization:
8-38
1.
Sets up hardware dependent functions
2.
Sets up the F$Time system call via F$SSvc
User System Calls I 8
Set User ID
Number
F$SUser l03F lC
Changes the current
user ID without
checking for errors or
checking the ID
number of the caller
Entry Conditions:
Y
=
desired user ID number
Error Output:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
• The support module for this call is OS9p 1.
8-39
as -9 Technical Reference
Time
089 F$Time l03F 15
Gets the system date
and time
Entry Conditions:
X
=
address of the area in which to stnre the date and time
packet
Exit Conditions:
X
=
date and time
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• The Time call returns the current system date and time in
the form of a 6-byte packet (in binary), 08-9 copies the
packet to the address passed in Register X.
• The packet looks like this:
Relative
Address
o
1
2
3
4
5
Value
year
month
day
hours
minutes
seconds
• Time is a part of the clock module and it does not exist if
no previous call to F$Time has been made.
User System Calls / 8
Unlink
089 F$UnLink 103F 02
Unlinks (removes
from memory) a
module that is not
in use and that has
a link count of 0
Entry Conditions:
= address of thR.
U
mndule hR.ader
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Unlink unlinks a module from the current process's
address space, decreases its link count by one and, if the
link count becomes zero, returns the memory where the
module was located to the sY6tem for use by other
processes.
• You cannot unlink 6ystem modules or device drivers that
are in use.
• Unlink operates in the following order:
1.
Unlink tells 08-9 that the calling process no longer
needs the module.
2.
08-9 decreases the module's link count by one.
3.
When the resulting link count is zero, 08-9 destroys
the module.
If any other process is using the module, the module's
link count cannot fall to zero. Therefore, 08-9 does not
destroy the module.
• If you pass a bad address, Unlink cannot find a module in
the module directory and does not return an error.
8-41
as -9 Technical Reference
Unlink
A Module
By Name
F$UnLoad 103F lD
Decrements a specified
module's link count,
and removes the
module from memory if
the resulting link count
is zero
Entry Conditions:
A
X
= modulR type
=
pointer to module name
Error Output:
CC
B
= carry set on error
=
error code (if any)
Additional Information:
• This system call differs from Unlink in that it uses a
pointer to the module name, instead of the address of the
module header.
• The support module for this call is OS9p2.
8-42
User System Calls! 8
Wait
OS9 F$Wait 103F 04
Temporarily turns off a
calling process
Entry Conditions: None
Exit Conditions:
A
B
= deceased child process's ID
= deceased child process's exit status codE (if no error)
Error Output:
CC
B
=
=
carry set on error
error code if any
Additional Information:
• The Wait call turns off the calling process until a child process dies, either by executing an Exit system call, or by
receiving a signal. The Wait call helps you save system
time.
• 08-9 returns the child's process's ID and exit status to the
parent. If the child died because of a signal, the exit status
byte (Register B) contains the signal code.
• If the caller has several children, 08-9 activates the caller
when the first one dies. Therefore, you need to use one Wait
system call to detect the termination of each child.
• 08-9 immediately reactivates the caller if a child dies
before the Wait call. If the caller has no children, Wait
returns an error, (See the Exit system call for more
information. )
• If the Wait call returns with the carry bit set, the Wait
function was not successful. If the carry bit is cleared, Wait
functioned normally and any error that occurred in the
child process is returned in Register B.
8-43
as -9 Technical Re{ereJU:e
I/O User System Calls
Attach
089 I$Attach l03F 80
Attaches a device to
the system or verifies
device attachment
Entry Conditions:
A
X
=
access mode
= cuk1ress of the
devil:e name string
Exit Conditions:
X
U
=
=
updated past device name
address of the device table entry
Error Output:
B
= error code
cc
=
(if any)
carry set on error
Additional Information:
• Attach does not reserve the device. It only prepares the
device for later use by any process.
• 08-9 installs most devices automatically on startup. Therefore, you need to use Attach only when installing a device
dynamically or when verifying the existence of a device. You
need not use the Attach system call to perform routine 1'0.
• The access mode parameter specifies the read and/or write
operations to be allowed. These are;
8·44
o=
Use any special device capabilities
1
2
3
Write only
Update (read and write)
= Read only
=
=
I/O User System Calls / 8
• Attach operates in this sequence:
1.
08-9 searches the system module to see if memory contains a device descriptor that has the same name as the
device.
2a. 08-9'15 next operation depends on whether or not the
device is already attached. If 08-9 finds the descriptor
and if the device is not already attached, 08-9 links the
device's file manager and device driver. It then places
the address of the manager and the driver in a new
device table entry. 08-9 then allocates any memory
needed by the device driver, and calls the driver's initialization routine which initializes the hardware.
b. If 08-9 finds the descriptor, and if the device is already
attached, OS-9 verifies the attachment.
8-45
as -9
Technical Reference
Change Directory
089I$Chgdir l03F 86
Changes the working
directory of a process
to a directory specified
by a pathlist
Entry Conditions:
A
X
=
=
access mode
address of the pathlist
Exit Conditions:
X
=
updated past pathlist
Error Output:
CC
=
B
=
carry set on error
error code (if any)
Additional InforJIlation:
• If the access mode is read, write, or update, 08-9 changes
the current data directory. If the access mode is execute,
08-9 changes the current execution directory.
• The calling process must have read access to the directory
specified (public read if the directory is not owned by the
calling process).
• The access modes are:
1 = Read
2 = Write
8·46
3
=
Update (read and write)
4
=
Execute
110 User System Calls / 8
Close Path
Terminates an I/O path
089 I$Close l03F SF
Entry Conditions:
A
=
path number
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Close Path terminates the I/O path to the file or device
specified by path number. Until you use another Open,
Dup, or Create system call for that path, you can no longer
perform 1/0 to the file or device.
• If you close a path to a single-user device, the device
becomes available to other requesting processes. 06-9 deallocates internally managed buffers and descriptors.
• The Exit system call automatically closes all open paths.
Therefore, you might not need to use the Close Path system
call to close some paths.
• Do not close a standard I/O path unless you want to change
the file or device to which it corresponds.
• Close Path performs an implied I$Detach call. If it causes
the device link count to become 0, the device termination
routine is executed. See I5Detach for additional
information.
8-47
as -9 Thchnical Reference
Create File
089 I$Create 103F 83
Creates and opens a
disk file
Entry Conditions:
B
A
= access rrwde (write or update)
= file attributes
X
=
address of the pathlist; (See the following example.)
Exit Conditions:
A
X
= path
=
number
address of the last byte of the pathlist + 1; skips any
trailing blanks (See the following example.)
Error Output:
CC
=
B
=
carry set on error
error code (if any)
Additional Infonnation:
• 08-9 parses the pathlist and enters the new filename in the
specified directory. If you do not specify a directory, OS-9
enters the new filename in the the working directory.
• 08-9 gives the file the attributes passed in Register B,
which has bits defined as follows:
Bit
Definition
o
Read
1
Write
Execute
Public read
Public write
Public execute
Shareable file
2
3
4
5
6
• The access mode parameter passed in Register A must have
the write bit set if any data is to be written. These access
codes are defined as fullows: 2 = write; 3 = update. The
mode affects the file only until the file is closed.
8-48
I/O User System Calls / 8
• You can reopen the file in any access mode allowed by the
file attributes. (See the Open system call.)
• Files opened for write can allow faster data transfer than
those opened for update because update sometimes needs to
pre-read sectors.
• If the execute bit (Bit 2) is set, the file is created in the
working execution directory instead of the working data
directory.
• Create File causes an implicit I$Attach call. If the device
has not previously been attached, the device's initialization
routine is called.
• Later 110 calls use the path number to identify the file,
until the file is closed.
• 08-9 does not allocate data storage for a file at creation.
Instead, it allocates the storage either automatically when
you first issue a write or explicitly by the Setstat
subroutine.
• If the filename already exists in the directory, an error
occurs. If the call specifies a non-multiple file device (such
as a printer or terminaD, Create behaves the same as
Open.
• You cannot use Create to make directories. (See the Make
Directory system call for instructions on how to do make
directories.)
• Before the Create File call:
...
X
After the Create File call:
...
X
8·49
as -9 Technical Refererwe
Delete File
089I$Delete l03F 87
Deletes a specified disk
file
Entry Conditions:
X
= address of the pathlist (See the following example.)
Exit Conditions:
X
= address of th£ last byte of the pathlist -
1; any trailing blanks are skipped (See the following example.)
Error Output:
B
=
CC
=
error code (if any)
carry set on error
Additional Information:
• The Delete File call deletes the disk file specified by the
pathlist. The file must have write permission attributes
(public write, if the calling process is not the owner). An
attempt to delete a device results in an error. The caller
must have non-shareable write access to the file or an error
results.
Example:
Before the Delete File call:
.
X
After the Delete File call:
,..
X
8-50
I/O User System Calls /8
Delete A File
OS9I$DeletX l03F 90
Deletes a file from the
current data or current
execution directory
Entry Conditions:
A
=
X
=
access nwde
address of the pathlist
Exit Conditions:
X
=
address of the last byte of the pathlist + 1; any trailing
blanks are skipped
Error Output:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
• The Delete A File call removes the disk file specified by the
selected pathlist. This function is similar to I$Delete except
that it accepts an access mode byte, If the access mode is
execute, the call selects the current execution directory.
Otherwise, it selects the current data directory.
• If a complete pathlist is provided (the pathlist begins with
a slash (/), the access mode the call ignores the access
mode.
• Only use this call to delete a file. If you attempt to use
I$DeletX to delete a device, the system returns an error.
8·51
os -9 Technical Reference
Detach Device
089I$Detach 103F 81
Removes a device
from the system
device tahIe
Entry Conditions:
U
=
address of the device table entry
Exit Conditions:
CC
= carry set on error
B
=
error code
(if any)
Additional Information:
• The Detach Device call removes a deYice from both the system and the system device table, assuming the device is not
being used by another process. You must use this call to
detach devices attached using the Attach system call.
Attach and Detach are both used mainly by the IO manager. SCF also uses Attach and Detach to set up its second
device (echo device).
• This is the sequence of the operation of Detach Device:
1.
Detach Device calls the device driver's termination routine. Then, 08-9 deallocates any memory assigned to
the driver.
2.
08-9 unlinks the associated device driver and file manager modules.
3.
08-9 then removes the driver, as long as no other module is using that driver.
8·52
110 User System Calls / 8
Duplicate Path
089 I$Dup l03F 82
Returns a synonymous
path number
Entry Conditions:
A
=
old path number (number of path to duplicate)
Exit Conditions:
A
=
new path number (if no error)
Error Output:
B
CC
=
=
error code (if error encountered)
carry set on error
Additional Information:
• The Duplicate Path returns another, synonymous path
number for the file or device specified by the old path
number.
• The shell uses the Duplicate Path call when it redirects
1'0.
• System calls can use either path number (old or new) to
operate on the same file or device.
• Make sure that no more than one process is performing 1'0
on anyone path at the same time. Concurrent 1'0 on the
same path can cause unpredictable results with RBF files.
• The I$Dup call always uses the lowest available path numpaths to contain
ber. This lets you manipulate standard
any desired paths.
va
8-53
as -9 Technical Reference
Get Status
OS9 I$GetStt l03F 8D
Returns the status of a
file or device
Entry Conditions:
A
B
=
=
path number
function code
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• The Status is a wildcard call. Use it to handle device
parameters that:
• Are not the same for all devices
• Are highly hardware-dependent
• Must be user-changeable
• The exact operation of the Get Status system call depends
on the device driver and file manager associated with the
path. A typical use is to determine a terminal's parameters
for such functions as backspace character and echo on/off.
The Get Status call is commonly used with the Set Status
call.
• The Get Status function codes that are currently defined
are listed in the "Get Status System Calls" section.
8·54
110 User System Calls I 8
Make Directory
089I$MakDir 103F 85
Creates and initializes
a directory
Entry Conditions:
B
X
=
=
directory attributes
address of the pathlist
Exit Conditions:
X
=
address of the last byte of the pathlist + 1; Make Directory skips trailing blanks.
Error Output:
B
=
CC
=
error code (if any)
carry set on error
Additional Information:
• The Make Directory call creates and initializes a directory
as specified by the pathlist. The directory contains only two
entries, one for itself (.) and one for its parent directory (.. )
• 08-9 makes the calling process the owner of the directory,
• Because the Make Directory call does not open the directory, it does not return a path number.
• The new directory automatically has its directory bit set in
the access permission attributes. The remaining attributes
are specified by the byte passed in Register B. The hits are
defined as follows:
Bit
Definition
o
Read
1
2
3
4
5
Write
Execute
Public read
Public write
Public execute
Single-user
Don't care
6
7
8-55
08-9 Technical Reference
• Before the Make Directory call:
+
X
After the Make Directory call:
8·56
liD User System Calls /8
Open Path
089I$Open l03F 84
Opens a path to an
existing file or device
as specified by the
pathlist
Entry Conditions:
A
X
= w.:ceS8 mode
CD S PE PW PR E W R)
= address of the pathlist (See the following example.)
Exit Conditions:
A
=
=
X
path number
address of the last byte of the pathlist
+1
Error Output:
B
CC
= error code (if any)
= carry set on error
Additional Information:
• OS-9 searches for the file in one of the following:
• The directory specified by the pathlist if the pathlist
begins with a slash.
• The working data directory, if the pathlist does not
begin with a slash.
• The working execution directory, if the pathlist does not
begin with a slash and if the execution bit is set in the
access mode.
• 08-9 returns a path number for later system calls to use to
identify the file.
• The access mode parameter lets you specify which read
andior write operations are to be permitted. When set, each
access mode bit enables one of the following: Write, Read,
Read and Write, Update, Directory I/O.
• The access mode must conform to the access permission
attributes associated with the file or device. (See the Create system call.! Only the owner can access a file unless
the appropriate public permission bits are set.
8-57
08-9 Technical Reference
• The update mode might be slightly slower than the others
because it might require pre-reading of sectors for random
access of bytes within sectors.
• Several processes (users) can open files at the same time.
Each device has an attribute that specifies whether or not
it is shareable.
• Before the Open Path call:
I
..
X
After the Open Path call:
.
X
• If the single-user bit is set, the file is opened for single-user
access regardless of the settings of the file's permission
bits.
• You must open directory files for read or write if the directory bit (Bit 7) is set in the access mode.
• Open Path always uses the lowest path number available
for the process.
8-58
I/O User System Calls / 8
Read
089I$Read l03F 89
Reads n bytes from a
specified path
Entry Conditions:
A
Y
X
=
=
=
path number
number of bytes to read
address in whu:h to store tm data
Exit Conditions:
Y
=
number of bytes read
Error Output:
B
CC
=
=
error code (if any)
carry set on error
Additional Information:
• The Read call reads the specified number of bytes from the
specified path. It returns the data exactly as read from the
file/device, without additional processing or editing. The
path must be opened in the read or update mode.
• If there is not enough data in the specified file to satisfy
the read request, the call reads fewer bytes than requested
but an end-of-file error is not returned. After all data in a
file is read, the next I$Read call returns an end-of-file
error.
• If the specified file is open for update, the record read is
locked out on RBF-type devices.
• The keyboard terminate, keyboard interrupt, and end-of-file
characters are filtered out of the Entry Conditions data on
SCF-type devices unless the corresponding entries in the
path descriptor have been set to zero. You might want to
modify the device descriptor so that these values are initialized to zero when the path is opened.
8-59
OS -9 Technical Reference
• The call reads the number of bytes requested unless Read
encounters any of the following:
• An end-of-file character
• An end-of-record character (SCF only)
• An error
8-60
110 User System Calls I 8
Read Line With
Editing
Reads a text line with
editing
089I$ReadLn l03F 8B
Entry Conditions:
A
X
Y
=
=
=
path number
address at which to store data
maximum number of bytes to read
Exit Conditions:
Y
=
number of bytes read
Error Output:
B
CC
= error code (if any)
=
carry set on error
Additional Information:
• Read Line is similar to Read. The difference is that Read
Line reads the input file or device until it encounters a carriage return character or until it reaches the maximum
byte count specified, whichever comes first. The Read Line
also automatically activates line editing on character oriented devices, such as terminals and printers. The line
editing refers to auto line feed, null padding at the end of
the line, backspacing, line deleting, and so on.
• SCF requires that the last byte entered be an end-of-record
character (usually a carriage return). If more data is
entered than the maximum specified, Read Line does not
accept it and a PD.OVF character (usually a bell) is
echoed.
• Mter one Read Line call reads all data in a file, the next
Read Line call generates an end-of-file error.
• (Fbr more information about line editing, see "SCF Line
Editing Functions" in Chapter 6.)
8-61
as -9
Technical Reference
Seek
089I$8eek l03F 88
Repositions a file
pointer
Entry Conditions:
A
X
U
=
=
=
path number
MS 16 bits of the desired file position
LS 16 bits of the desired file position
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• The Seek Call repositions the path's logical file pointer, the
32-bit address of the next byte in the file to be read from or
written to.
• You can perform a seek to any value, regardless of the file's
size. Later writes automatically expand the file to the
required size (if possible). Later reads, however, return an
end-of-file condition. Note that a seek to Address 0 is the
same as a rewind operation.
• 08-9 usually ignores seeks to non-random access devices,
and returns without error.
• On RBF devices, seeking to a new disk sector causes the
internal disk buffer to be rewritten to disk if it has been
modified. Seek does not change the state of record locking.
8-62
liD User System Calls! 8
Set Status
OS9I$SetStt l03F BE
Sets the status of a file
or device
Entry Conditions:
A
=
B
=
path number
function code
Other registers depend on the function code.
Error Output:
B
= error code (if any)
CC = carry set on error
Other registers depend on the function code.
Additional Information:
• Set Status is a wildcard call. Use it to handle device
parameters that:
• Are not the same for all devices
• Are highly hardware-dependent
• Must be user-changeable
• The exact operation of the Set Status system call depends
on the device driver and file manager associated with the
path. A typical use is to set a terminal's parameters for
such functions as backspace character and echo on/off. The
Set Status call is commonly used with the Get Status call.
• The Set Status function codes that are currently defined
are listed in the "Set Status System Calls" section.
8-63
OS -9 Technical Reference
Write
089 I$Write 103F 8A
Writes to a file or
device
Entry Conditions:
A
X
Y
=
=
=
path number
starting address of data to write
number of bytes to write
Exit Conditions:
Y
=
number of bytes written
Error Output:
B
CC
=
=
error code (if any)
carry set on error
Additional Information:
• The Write system call writes to the file or device associated
with the path number specified.
• Before using Write, be sure the path is opened or created
in the Write or Update access mode. 08-9 writes data to
the file or device without processing or editing the data.
08-9 automatically expands the file if you write data past
the present end-of-file.
8-64
I/O User System Calls J 8
Write Line
089 I$WritLn l03F
Be
Writes to a file or
device until it
encounters a carriage
return
Entry Conditions:
A
X
Y
= path number
= address of the data to write
= maximum number of bytes to write
Exit Conditions:
Y
=
number of bytes written
Error Output:
B
CC
=
=
error code (if any)
carry set on error
Additional Information:
• Writes to the file or device that is associated with the path
number specified.
• Write Line is similar to Write. The difference is that Write
Line writes data until it encounters a carriage return character. It also activates line editing for character-oriented
devices, such as terminals and printers. The line editing
refers to auto line feed, null padding at the end of the line,
backspacing, line deleting, and so on.
• Before using Write Line, be sure the path is opened or created in the write or update access mode.
• (For more information about line editing, see "SCF Line
Editing Functions" in Chapter 6.)
8·65
08-9 Technical Reference
Privileged System Mode Calls
Set an alarm
089 F$Alarm I03F IE
Sets an alarm to ring
the bell at a specified
time
Entry Conditions:
X
=
relative address of time packet
Error Output:
CC
=
B
=
carry set on error
appropriate error code
Additional Information:
• When the system reaches the specified alarm time, it rings
the bell for 15 seconds.
• The time packet is identical to the packet used in the
F$STime call. See F$STime for additional information on
the format of the packet.
• All alarms begin at the start of a minute and any seconds
in the packet are ignored.
• The system is limited to one alarm at a time.
8-66
Privileged System Mode Calls /8
Allocate 64
OS9 F$A1l64 lQ3F 30
Dynamically allocates
64-byte blocks of
memory
Entry Conditions:
= base address of the page table; 0
not been allocated
X
the page table has
Exit Conditions:
A
=
=
X
Y
=
block number
base address of the page table
address of the block
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• The Allocate 64 system call allocates the 64~byte blocks of
memory by splitting pages (256·byte sections) into four
sections.
• 08-9 uses the first 64 bytes of the base page as a page
table. This table contains the page number (most significant byte of the address) of all pages in the memory structure. If Register X passes a value of zero, the call allocates
a new base page and the first 64-byte memory block.
• Whenever a new page is needed, a Request System Memory
system call (F$SRqMem) executes automatically.
• The first byte of each block contains the block number.
Routines that use the Allocate 64 call should not alter this
byte.
8-67
os -9 Technical Reference
• The following diagram shows how seven blocks might be
allocated:
B ase P age ....
Any Memory Page
Any Memory Page
X
Page Table
Block 4
(64 bytes)
(64 bytes)
X
X
Block 1
(64 bytes)
X
Block 5
(64 bytes)
X
Block 2
(64 bytes)
X
X
Block 3
(64 bytes)
8·68
Block 6
(64 bytes)
Block 7
(64 bytes)
Privileged System Mode Calls / 8
Allocate High
RAM
Allocate system
memory from high
physical memory
089 F$AlHRam l03F 53
Entry Conditions:
B
=
number of blocks
Error Output:
CC
=
B
=
carry set on error
appropriate error code
Additional Information:
• This call searches for the desired number of contiguous free
RAM blocks, starting its search at the top of memory.
F$AllHRam is similar to F$AllRAM except F$AllRAM
begins its search at the bottom of memory.
• Screen allocation routines use this call to provide a better
chance of finding the necessary memory for a screen.
8-69
as -9
Technical Reference
Allocate Image
089 F$AllImg l03F 3A
Allocates RAM
blocks for process
DAT image
Entry Conditions;
A
B
=
X
=
=
starting block number
number of blocks
process descriptor pointer
Exit Conditions:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
• Use the Allocate Image system call to allocate a data area
for a process. The blocks that Allocate Image defines might
not be contiguous.
• The support module for this system call is OS9pl.
8-70
Privileged System Mode Calls! 8
Allocate Process
Descriptor
Allocates and
initializes a 512-byte
process descriptor
089 F$AllPrc l03F 4B
Entry Conditions: None
Exit Conditions:
U
=
process descripwr pointer
Error Output:
CC
B
= C bit set on error
=
appropriate error code
Additional Information:
• The process descriptor table houses the address of the
descriptor. Initialization of the process descriptor consists
of clearing the first 256 bytes of the descriptor, setting up
the state as a system state, and marking as unallocated as
much of the DAT image as the system allows-typically,
60-64 kilobytes.
• The support module for this system call is OS9p2. The call
also branches to the F$SRqMem call.
8-71
as -9 Technical Reference
Allocate RAM
OS9 F$A1IRAM I03F 39
Searches the
memory block map
for the desired
number of
contiguous free
RAM blocks
Entry Conditions:
B
=
number of blocks
Exit Conditions:
cc
B
=
C bit set on error
= appropriate error code
Additional Information:
• The support module for this system call is OS9pl.
8·72
Privileged System Mode Calls /8
Allocate Process
Task Number
Determines whether
OS·9 has assigned a
task number to the
089 F$AllTsk l03F 3F
specified process
Entry Conditions:
X
= process descriptor pointer
Error Output:
cc
=
B
=
C bit set
appropriate error code
Additional Information:
• If the process does not have a task number, 08-9 allocates
a task number and copies the DAT image into the DAT
hardware.
• The support module for this call is 089pl. Allocate Process
Task number also branches to F$ResTsk and F$SetTsk.
8-73
as -9 Technical Reference
Insert Process
089 F$AProc l03F 2C
Inserts a process into
the queue for execution
Entry Conditions:
;: address of the process descriptor
X
Error Output:
CC
B
= carry set on error
= error code (if any)
Additional Information:
• The Insert Process system call inserts a process into the
active process queue so that 08-9 can schedule the process
for execution.
• 08-9 sorts all processes in the queue by process age (the
count of how many process switches have occurred since the
process's last time slice). When a process is moved to the
active process queue, 08-9 sets its age according to its
priority-the higher the priority. the higher the age.
An exception is a newly active process that was deactivated
while in the system state. 08-9 gives such a process higher
priority because the process usually is executing critical
routines that affect shared system resources.
8·74
Privileged System Mock Calls! 8
Bootstrap System
089 F$Boot l03F 35
Links either the
module named Boot
or the module
specified in the INIT
module
Entry Conditions: None
Error Output:
cc
B
=
C bit set on error
= appropriate error code
Additional Information:
• When it calls the linked module, Boot expects to receive a
pointer giving it the location and size of an area in which
to search for the new module.
• The support module for this call is OS9pl. Bootstrap System also branches to the F$Link and F$VModul system
calls.
8·75
as -9 Technical Reference
Bootstrap
Memory Request
089 F$BtMem 103F 36
Allocates the
requested memory
(rounded to the
nearest block) as
contiguous memory
in the system's
address space
Entry Conditions:
D
=
byte count req/JJ!sted
Exit Conditions:
D
U
~
=
byte count granted
pointer to memnry alwcated
Error Output:
cc
=
B
=
C bit set on error
appropriate error code
Additional Information:
• This call is identical to F$SRqMem.
• The Bootstrap Memory Request support module is OS9pL
8-76
Prit1ileged System Mode Calls /8
Clear Specified
Block
Marks blocks in the
process DAT image as
unallocated
089 F$ClrBlk 103F 50
Entry Conditions:
B
=
U
=
number of blocks
address of first block
Exit Conditions: None
Additional Information:
• After Clear Specified Block deallocates blocks, the blocks
are free for the process to use fur other data or program
areas. If the block address passed to Clear Specified Block
is invalid or if the call attempts to clear the stack area, it
returns E$IBA.
• The support module for the call is OS9p2.
8·77
as -9 Technical Reference
DAT to Logical
Address
089 F$DATLog l03F 44
Converts a DAT image
clock number and
block offset to its
equivalent logical
address
Entry Conditions:
B
X
=
=
DAT image offset
block offset
Exit Conditions:
X
= logical address
Error Output:
CC
B
=
=
C bit set on error
appropriate error code
Additional Information:
• Following is a sample conversion:
Input: B
=
2
X
=
$0329
2000 - 2FFF
Output: X
1000 - lFFF
0- FFF
• The support module for this call is OS9pl.
8-78
=
$2329
Privileged System Mode Calls! 8
Deallocate Image
RAM Blocks
Deallocates image
RAM blocks
089 F$DelImg I03F 3B
Entry Conditions:
A
B
X
=
number of starting block
= block count
=
process descriptor pointer
Error Output:
cc
=
B
=
C bit set on error
appropriate error code
Additional Information:
• This system call deallocates memory from a process's
address space. It frees the RAM for system use and frees
the DAT image for the process. Its main use is to let the
system clean up after a process death.
• The support module for this call is OS9p2.
8·79
os -9 Teehnical Reference
Deallocate
Process
Descriptor
Returns a process
descriptor's memory to
a free memory pool
089 F$DelPrc l03F 4C
Entry Conditions:
A
=
process ID
Error Output:
cc
B
=
=
C hit set on error
appropriate error code
Additional Information:
• Use this call to clear the system scratch memory and stack
area associated with the process.
• The support module for this call is OS9p2.
s-so
Privileged System Mode Calls J 8
Deallocate RAM
blocks
Clears a block's RAM
In Use flag in the
system memory block
089 F$DeIRAM 103F 51
map
Entry Conditions:
B
X
=
number of blocks
= starting block number
Exit Conditions: None
Additional Information:
• The Deallocate RAM Blocks call assumes the blocks being
deallocated are not associated with any DAT image.
• The support module for this call is OS9p2.
8·81
as -9 Technical Reference
Deallocate Task
Number
089 F$DelTsk 103F 40
Releases the task
number that the
process specified by
the passed descriptor
pointer
Entry Conditions:
X
=
process descriptor pointer
Error Output:
CC
B
=
C bit set on error
error code
= appropriate
Additional Information:
• The support module for this call is OS9pl.
8-82
Privikged System Mode Calls ! 8
Link Using
Module Directory
Entry
Performs a link using a
pointer to a module
directory entry
089 F$ELink l03F 4D
Entry Conditions:
B
X
=
=
nwdule type
pointer to nwdule directory entry
Exit Conditions:
U
=
Y
=
nwdule header address
rrwdule entry point
Error Output:
cc
=
B
=
C bit set on error
appropriate error cock
Additional Information:
• This call differs from Link in that you supply a pointer to
the module directory entry rather than a pointer to a module name .
• The support module for this call is OS9pl.
8·83
as -9 Technical Reference
Find Module
Directory Entry
Returns a pointer to
the module directory
entry
089 F$FModul I03F 4E
Entry Conditions:
A
X
Y
=
=
=
module type
pointer to the name string
DAT image pointer (for name)
Exit Conditions:
A
B
X
=
U
=
=
=
module type
module revision number
updated name string; (if Register A contains 0 on
entry)
module directory entry pointer
Error Output:
bit set on error
appropriate error code
Cc
= C
B
=
Additional Information:
• The Find Module Directory Entry call returns a pointer to
the module directory entry for the first module that has a
name and type matching the specified name and type. If
you pass a module type of zero, the system call finds any
module.
• The support module for this call is OS9pl.
8·84
Privileged System Mock Calls / 8
Find 64
089 F$Find64 l03F 2F
Returns the address
of a 64-byte memory
block
Entry Conditions:
A
=
X
=
block number
address of the block
Exit Conditions:
Y
CC
= address of the block
= carry set if block not allowed or not in use
Additional Information:
• 08-9 uses Find 64 to find path descriptors when given
their block number. The block number can be any positive
integer.
8-85
as -9 Technical Reference
Get Free High
Block
089 F$FreeHB l03F 3E
Searches the DAT
image for the
highest set of
contiguous free
blocks of the
specified size
Entry Conditions:
B
=
block count
Y
=
DAT image pointer
Exit Conditions:
A
= starting block number
Error Output:
CC
=
B
=
C bit set on error
appropriate error code
Additional Information:
• The Get Free High Block call returns the block number of
the beginning memory address of the free blocks.
• The support module for this system call is OS9pl.
8-86
Privileged System Mode Calls / 8
Get Free Low
Block
089 F$FreeLB 103F 3D
Searches the DAT
image for the lowest set
of contiguous free
blocks of the specified
size
Entry Conditions:
B
=
Y
=
block count
DAT image poini€r
Exit Conditions:
A
'" starting block number
Error Output:
CC
B
=
=
C bit set on error
appropriate error code
Additional Information:
• The Get Free Low Block call returns the block number of
the beginning memory address of the free blocks .
• The support module for this system call is OS9pl.
8·87
OS -9 Technical Reference
Compact Module
Directory
Compacts the entries in
the module directory
089 F$GCMDir l03F 52
Entry Conditions: None
Exit Conditions: None
Additional Information:
• This function is only for internal 08-9 system use. You
should never call it from a program.
8-88
Privileged System Mode Calls I 8
Get Process
Pointer
Gets a pointer to a
process
F$GProcP l03F 37
Entry Conditions:
A
= process ID
Exit Conditions:
B
=
poimer
tD
process descriptor
(if no
error)
Error Output:
CC
= carry
B
=
set on error
error code (If an error occurs (E$BPrcID)
Additional Information:
• The Get Process Pointer call translates a process ID number to the address of its process descriptor in the system
address space. Process descriptors exist only in the system
task address space. Because of this, the address returned
only refers to system address space.
• The support module for this call is OS9p2.
8·89
as -9
Technical Reference
I/O Delete
089 F$IODel 103F 33
Deletes an 110 module
that is not being used
Entry Conditions:
X
== address of an 1/0 nwdule
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• The I/O Delete deletes the specified I/O module from the
system, if the module is not in use. This system call is
used mainly by the I/O MANAGER, and can be of limited
or no use for other applications.
• This is the order in which 1/0 Delete operates:
1.
Register X passes the address of a device descriptor
module, device driver module, or file manager module.
2.
08-9 searches the device table for the address.
3.
If 08-9 finds the address, it checks the module's use
count. If the count is zero, the module is not being
used; 08-9 deletes it. If the count is not zero, the mod·
ule is being used; 08-9 returns an error.
• 1/0 Delete returns information to the Unlink system call
after determining whether a device is busy.
8·90
Privileged System Mode Calls! 8
110 Queue
OS9 F$IOQu l03F 2B
Inserts the calling
process into another
process's I/O queue,
and puts the calling
process to sleep
Entry Conditions:
A
=
process number
Error Output:
CC
= carry set on error
B
=
error code (if any)
Additional Information:
• The liD Queue call links the calling process into the 110
queue of the specified process and performs an untimed
sleep. The 10 Manager and the file managers are primary
and extensive users of I/O Queue .
• Routines associated with the specified process send a wakeup signal to the calling process.
8·91
OS -9 Technieal ReferelWe
Set IRQ
089 F$IRQ I03F 2A
Adds a device to or
removes it from the
polling table
Entry Conditions:
D
X
=
address of th£ device status register
= 0 (to remove a device) or the address of a packet (to
add a device)
Y
U
=
=
• the address at X is the flip byte
• the address at X + 1 is the mask byte
• the address at X + 2 is the priority byte
address of the device IRQ service routine
address of the service routine's menwry area
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Set IRQ is used mainly by device driver routines. (See
"Interrupt Processing" in Chapter 2 for a complete discussion of the interrupt polling system.)
• Packet Definitions:
The Flip Byte. Determines whether the bits in the device
status register indicate active when set or active when
cleared. If a bit in the flip byte is set, it indicates that the
task is active whenever the corresponding bit in the status
register is clear (and vice versa).
The Mask Byte. Selects one or more bits within the device
status register that are interrupt request flag(s). One or
more set bits identify which task or device is active.
The Priority Byte. Contains the device priority number (0
= lowest priority, 255 = highest priority).
8-92
Privileged System Mode Calls! 8
Load A From
TaskB
Loads A from O,X in
taskB
F$LDABX I03F 49
Entry Conditions:
B
X
= task TUlmber
= pointer
to data
Exit Conditions:
A
=
byte at 0)( in task address space
Error Output:
CC
B
;;;;: carry set on error
error code (if any)
=
Additional Information:
• The value in Register X is an offset value from the beginning address of the Task module. The Load A From Task B
call returns one byte from this logical address. Use this
system call to get one byte from the current process's memory in a system state routine.
8·93
as -9
Technical Reference
Get One Byte
Loads A from [X, [V]]
F$LDAXY l03F 46
Entry Conditions:
X
Y
=
=
block offset
DAT image pointer
Exit Conditions:
A
= contents of byte at DAT image (Yj offset by X
Error Output:
CC
B
=
carry set on error
= error code (if any)
Additional Information:
• The Get One Byte system call gets the contents of one byte
in the specified memory block. The block is specified by the
DAT image in (Y), offset by (X). The call assumes that the
DAT image pointer is to the actual block desired, and that
X is only an offset within the DAT block. The value in Register X must be less than the size of the DAT block. 08-9
does not check to see if X is out of range.
8-94
Privileged System Mode Calls /8
Get Two Bytes
F$LDDDXY l03F 48
Loads D from
[D+X],[Y]
Entry Conditions:
D
X
Y
=
=
Offset to the offset within tlu! DAT image
Offset within the DAT image
=
DAT image pointer
Exit Conditions:
D
=
contents of two bytes at {D + X, Y7
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Get Two Bytes loads two bytes from the address space
described by the DAT image pointer. If the DAT image
pointer is to the entire DAT, then make D + X equal to the
process address for data. If the DAT image is not the entire
image (64K), then you must adjust D+X relative to the
beginning of the DAT image. Using D + X lets you keep a
local pointer within a block, and also lets you point to an
offset within the DAT image that points to a specified block
number.
8·95
as -9 Technical Reference
Map Specific
Block
F$MapBlk 103F 4F
Maps the specified
block(s) into
unallocated blocks of
process space
Entry Conditions:
X
=
B
=
starting block number
number of blocks
Exit Conditions:
U
= address of first block
Error Output:
B
CC
=
=
error code (if any)
carry set on error
Additional Information:
• The system maps blocks from the top down. It maps new
blocks into the highest available addresses in the address
space. See Clear Specified Block for information on
unmapping.
8-96
Privileged System Mode Calls I 8
Move Data
F$Move l03F 38
Moves data bytes from
one address space to
another
Entry Conditions:
A
B
X
Y
U
source task number
destination task number
source pointer
= byte count
= destination pointer
=
=
=
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Vou can use the Move Data system call to move data bytes
from one address space to another, usually from system to
user, or vice versa.
• The support module for this call is OS9pl.
8·97
OS -9 Technical Reference
Next Process
089 F$NProc l03F 2D
Executes the next
process in the active
process queue
Entry Conditions: None
Exit Conditions:
Control does not return to caller.
Additional Information:
• The Next Process system call takes the next process out of
the active process queue and initiates its execution. If the
queue contains no process, 08-9 waits for an interrupt, and
then checks the queue again.
• The process calling Next Process must already be in one of
the three process queues. If it is not, it becomes unknown
to the system even though the process descriptor still exists
and can be displayed by a PROCS command.
8-98
Privileged System Mode Calls! 8
Release A Task
F$RelTsk l03F 43
Releases a specified
DAT task number from
use by a process,
making the task's DAT
hardware available for
use by another task
Entry Conditions:
B
= task numher
Error Output:
CC
B
=
carry set on error
= error code (if any)
Additional Information:
• The support module for this call OS9pl.
8·99
as -9 Technical Reference
Reserve Task
Number
Reserves a DAT task
number
F$ResTsk l03F 42
Entry Conditions: none
Exit Conditions:
B
=
task number (if no error)
Error Output:
CC
B
:; carry set on error
= error code if an error occurs
Additional Information:
• The Reserve Task Number call finds a free DAT task number, reserves it, and returns the task number to the caller.
The caller often then assigns the task number to a process.
• The support module for this call is OS9pl.
8-100
Privileged System Mode Calls I 8
Return 64
089 F$Ret64 l03F 31
Deallocates a 64.byte
block of memory
Entry Conditions:
A
X
=
=
block number
cukiress of the base page
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• See the Allocate 64 system call for more information.
8·101
as -9 Technical Reference
Set Process DAT
Image
Copies all or part of
the DAT image into a
process descriptor
F$Setlmg l03F 3C
Entry Condition:
A
B
X
U
starting image block number
block count
process descriptor pointer
= new image pointer
=
=
=
Error Output:
CC
B
=
=
carry set on error
error cock (if any)
Additional Information:
• While copying part or all of the DAT image, this system
call also sets an image change flag in the process descriptor. This flag guarantees that as a process returns from
the system call. The call updates the hardware to match
the new process DAT image .
• The support module for this call is OS9pl.
8·102
Privileged System Mode Calls I 8
Set Process Task
DAT Registers
Writes to the hardware
DAT registers
F$SetTsk 103F 41
Entry Conditions:
X
=
pointer to process descriptor
Error Output:
CC
=
B
= error code (if any)
carry set on error
Additional Information:
• This system call sets the process task hardware DAT registers, and clears the image change flag in the process
descriptor. It also writes to DAT RAM the process's segment address information.
• The support module for this call is OS9pL
8·103
as -9 Technical Reference
System Link
F$SLink l03F 34
Adds a module from
outside the current
address space into the
current address space
Entry Conditions:
A
X
Y
=
=
=
module type
module name string pointer
name string DAT image pointer
Exit Conditions:
A
B
X
Y
U
= module type
=
=
=
=
module revision (if 1W error)
updated name string pointer
module entry point
module pointer
Error Output:
CC
B
= carry set on error
=
error code (If an error occurs)
Additional Information:
• The I/O System uses the System Link call to link into the
current process's address space those modules specified by a
device name in a user call. User calls such as Create File
and Open Path use this System Link.
• The support module for this call is OS9pl.
8-104
Privileged System Mode Calls / 8
Request System
Memory
089 F$8RqMem l03F 28
Allocates a block of
memory of the
specified size from the
top of available RAM
Entry Conditions:
D
= byte
count
Exit Conditions:
U
D
= starting address of the mellWry area
= new menwry size
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• The Request System Memory call rounds the size request
to the next page boundary.
• This call allocates memory only for system address space.
8·105
OS·9 Technical Referem;e
Return System
Memory
Deallocates a block of
contiguous pages
089 F$8RtMem l03F 29
Entry Conditions:
U
D
= starting address of rnerrwry to return;
=
must point to an
even page boundary
number of bytes to return
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Register U must point to an even page boundary .
• This call deallocates memory for system address space only.
8·106
Privileged System Mode Calls /8
Set SVC
Adds or replaces a
system call
089 F$88vc 103F 32
Entry Conditions:
Y
=
address of the system call
initialization table
Error Output:
cc
B
=
~
C bit set
error code
Additional Information:
• Set sve adds or replaces a system call, which you have
written, to 08-9'8 user and system mode system call tables.
• Register Y passes the address of a table, which contains the
function codes and offsets, to the corresponding system call
handler routines. This table has the following format:
Relative
Address
$00
$01
$02
$03
$04
$05
Use
Function Code
Offset From Byte 3
To Function Handler
Function Code
Offset From Byte 6 To Function Handler
More Entries
$80
... First entry
.... Second entry
... More entries
.... End-of-table mark
8·107
OS -9 Technical Reference
• If the most significant bit of the function code is set, 08-9
updates the system table.
If the most significant bit of the function code is not set,
08-9 updates the system and user tables.
• The function request codes are in the range $29-$34. 10
calls are in the range $80-$90
• To use a privileged system call, you must be executing a
program that resides in the system map and that executes
in the system state.
• The system call handler routine must process the system
call and return from the subroutine with an RTS
instruction.
• The handler routine might alter all CPU registers (except
Register SP).
• Register U passes the address of the register stack to the
system call handler as shown in the following diagram:
Relative
Address
u ...
Name
CC
$00
R$CC
f---------
A
$01
$01
R$D
R$A
B
$02
R$B
DP
$03
R$DP
X
$04
R$X
Y
$06
R$Y
U
$08
R$U
PC
$OA
R$PC
Codes $70-$7F are reserved for user definition.
8-108
Privileged System Mode Calls / 8
Store A Byte
In A Task
Stores A at O,X in
TaskB
F$STABX l03F 4A
Entry Conditions:
A
B
X
=
bYte to store
= destination task number
=
logical destination acklress
Error Output:
CC
B
=
carry set on error
=
error code (if any)
Additional Information:
• This system call is similar to the assembly language
instruction "STA O,X". The difference is that in the system
call, X refers to an address in the given task's address
space, instead of the current address space.
• The support module for this system call is OS9pl.
8·109
08-9 Technical Refereru:e
Install virtual
interrupt
Installs a virtual
interrupt handler
routine
OS9 F$VIRQ I03F 27
Entry Conditions:
D
'=
initial count valUR
to delete entry
1 to install entry
address of 5 -byte packet
X
=0
Y
=
Error Output:
CC
=
carry set on error
B
'=
appropriate error cock
Additional Information:
• Install VIRQ for use with devices in the Multi-Pak Expansion Interface. This call is explained in detail in Chapter 2.
8·110
Privileged System Mode Calls I 8
Validate Module
089 F$VModul l03F 2E
Checks the module
header parity and CRC
bytes of a module
Entry Conditions:
D
X
= DAT image pointer
new module block offset
=
Exit Conditions:
U
=
address of the module directory entry
Error Output:
CC
B
= carry set on error
=
error code (if any)
Additional Information:
• If the values of the specified module are valid, 08-9
searches the module directory for a module with the same
name. If one exists, 08-9 keeps in memory the module that
has the higher revision level. If both modules have the save
revision level, 08-9 retains the module in memory.
8-111
OS -9 Technical Reference
Get Status System Calls
You use the Get Status system calls with the RBF manager subroutine GETSTA. The 08-9 Level Two system reserves function
Codes 7-127 for use by Microware. You can define Codes 128-255
and their parameter-passing conventions for your own use. (See
the sections on device drivers in Chapters 4, 5, and 6.)
The Get Status routine passes the register stack and the specified function code to the device driver.
Following are the Get Status functions and their codes.
SS.OPT
(Function code $00). Reads the option section of the path
descriptor, and copies it into the 32-byte area pointed to by Register X
Entry Conditions:
path number
A
=
B
--= $00
X
=
address to receive status packet
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Use SS.OPr to determine the current settings for editing
functions, such as echo and auto line feed.
8·112
System Calls! 8
SS.RDY
(Function code $01). Tests for data available on SCF -supported
devices
Entry Conditions:
A
B
=
=
path number
$01
Exit Conditions:
If the device is ready:
CC = carry clear
B
=
$00
If the device is not ready:
CC = carry set
B
= $F6 (E$SRNDY)
Error Output:
CC
B
=
=
carry set
error cock
SS.SIZ
(Function code $02). Gets the current file size on a RBF -supported devices only
Entry Conditions:
path number
A
=
B
= $02
Exit Conditions:
X
=
U
=
most significant 16 bits of the current file size
least significant 16 bits of the current file size
Error Output:
CC
B
=
=
carry set on error
error code (if any)
8·113
as -9 Technical Reference
SS.POS
(Function code $05). Gets the current file position (RBF-supported devices only)
Entry Conditions:
A
B
=
=
path number
$05
Exit Conditions:
X
U
=
=
most significant 16 bits of the current file position
least significant 16 bits of the current file position
Error Output:
CC
B
=
=
carry set on error
error cock (if any)
SS.EOF
(Function code $06). Tests for the end of the file (EOF)
Entry Conditions:
A
= path number
B
= $06
Exit Conditions:
If there is no EOF:
CC = carry clear
B
=
$00
If there is an EOF:
CC = carry set
B
=
$D3 (E$EOF)
Error Output:
CC
B
8-114
=
carry set
= error code
System Calls / 8
SS.DevNm
(Function Code $OE). Returns a device name
Entry Conditions:
A
B
X
=
=
=
path number
$OE
address of32-byte buffer for
M11l£
Exit Conditions:
X
=
address of buffer, name nwved to buffer
SS.DSTAT
(Function code $12). Returns the display status
Entry Conditions:
A
B
= path number
= $12
Exit Conditions:
color code of the pixel at the cursor address
A
=
X
Y
= graphics cursor address;
= address of the graphics display 11l£TTWry
X = MSB, Y = LSB
Additional Information:
• This function is supported only with the VDGINT module
and deals with VDG-compatible graphics screens. See
SS.AAGBf for information regarding Level Two operation.
8·115
os -9 Technical Reference
SS.JOY
(Function code $13). Returns the joystick values
Entry Conditions:
A
B
X
path number
$13
= joystwk lUlmber
o = (right joystick)
1 = (left joystick)
=
=
Exit Conditions:
A
=
fire button dnwn
o = none
1 = Button 1
2 = Button 2
3 = Button 1 and Button 2
X
= selected joystick x value (0-63)
Y
= sekctedjoystick y value (0·63)
Note: Under Levell, the following values are returned by
this call:
= fire button status
A
$FF = fire button is on
$00 = fire button is off
8-116
System Calls / 8
SS.AlfaS
(Function code $lC). Returns VDG alpha screen memory
information
Entry Conditions:
A
=
B
=
path number
$lC
Exit Conditions:
A
X
Y
caps lock status
$00 = lower case
$FF = upper case
= menwry address of the buffer
:;:; menwry address of the cursor
=
Additional InforJllation:
• SS.AlfaS maps the screen into the user address space. The
call requires a full block of memory for screen mapping.
This call is only for use with VDG text screens handled by
VDGINT.
• The support module for this call is VDGINT.
• Warning: Use extreme care when poking the screen, since
other system variables reside in screen memory. Do not
change any addresses outside of the screen.
8·117
as -9 Technical Reference
SS.Cursr
(Function code $25). Returns VDG alpha screen cursor
infonnation
Entry Conditions:
A
B
= path number
= $25
Exit Conditions:
A
X
Y
character codR of the char(J(!ter at the current cursor
address
= cursor X position (column)
= cursor Y position (row)
=
Additional Information:
• SS.Cursr returns the character at the current cursor position. It also returns the X-Y address of the cursor relative
to the current device's window or screen. SS.Cursr works
only with text screens.
• The support module for this call is VDGINT.
8-118
System Calls / 8
SS.ScSiz
(Function code $26). Returns the window or screen size
Entry Conditions:
A
= path number
B
=
$26
Exit Conditions:
x
Y
=
number of columns on screen/window
= number of rows on screenlwirulnw
Additional Information:
• Use this call to determine the size of an output screen. The
values returned depend on the device in use:
For non-CCIO devices, the call returns the values following the XON/XOFF bytes in the device descriptor.
For CCIO devices, the call returns the size of the window
or screen in use by the specified device.
For window devices. the call returns the size of the current working area of the window.
• The support modules for this call are VDGINT, Grflnt, and
WindInt.
8-119
os -9 Technical Reference
SS.I\YSns
(Function code $27). Returns key down status
Entry Conditions:
A
B
= path number
= $27
Exit Conditions:
A
=
keyboard scan information
Additional Information:
• Accumulator A returns with a bit pattern representing
eight keys. With each keyboard scan, OS9 updates this bit
pattern. A set bit (1) indicates that a key was pressed since
the last scan. A clear bit (0) indicates that a key was not
pressed. Definitions for the bits are as follows:
Bit
o
1
2
3
4
5
6
7
Key
I
I CTRL I or I CLEAR I
[ALT] or ~
(up arrow)
(down arrow)
8 (left arrow)
~ (right arrow)
Space Bar
(SHIFT
rn
rn
The bits can be masked with the following equates:
SHIFTBIT
CNTRLBIT
ALTERBIT
UPBIT
DOWNBIT
LEFTBIT
RIGHTBIT
SPACEBIT
equ
equ
equ
equ
equ
equ
equ
equ
%00000001
%00000010
%00000100
%00001000
%00010000
%00100000
%01000000
%10000000
• The support module for this call is CC3IO.
8-120
System Calls I 8
SS.ComSt
(Function code $28). Return serial port configuration
information
Entry Conditions:
A
B
=
=
path number
$28
Exit Conditions:
Y
'" high byte: parity
low byte: baud rate
(See the Setstat call SS.ComSt for values)
Error Output:
CC
B
= carry set on error
= error code
(if any)
Additional Information:
• The SCF manager uses this call when performing an
SS.Opt Getstat on an SCF -type device. User calls to
SS.ComSt do not update the path descriptor. Use the
SS.OPT Getstat call for most applications, because it automatically updates the path descriptor.
8-121
OS-9 Technical Referenee
SS.MnSel
(Function code $87). Requests that the high-level menu handler
take control of menu selection
Entry Conditions:
A
B
=
=
path number
$87
Exit Conditions:
menu ID (if valid selection)
A
=
B
= item number of menu (if valid
o (if invalid selp.ction)
selection)
Error Output:
CC
B
=
=
carry set on error
error code (if invalid selection)
Additional Information:
• After detecting a valid mOuse click (when the mouse is
pointing to a control area on a window), a process needs to
call SS.MnSel. This call tells the enhanced window interface to handle any menu selection being made. If accumulator A returns with 0, then no selection has been made. The
calling process needs to test and handle other returned
values.
• A condition where Register A returns a valid menu ID
number and Register B returns 0 signals the selection of a
menu with no items. The application can now take over and
do a special graphics pull down of its own. The menu title
remains highlighted until the application calls the
SS.UMBar SetStat to update the menu bar.
• The support module for this call is WindInt.
8·122
System Calls / 8
SS.MOllse
(Function code $89). Gets mouse statuB
Entry Conditions:
A
B
X
Y
path number
$89
= data storage area address
= nwuse port select:
=
=
o
automatic selection
1 ;;;;; right side
2 = left side
Exit Conditions:
X
=
data storage area address
Error Output:
CC
=
B
=
carry set on error
error code (if any)
8·123
08-9 Technical Reference
Additional Information:
• SS.Mouse returns information on the current mouse and its
fire button. The following list defines the 32-byte data
packet that SS.Mouse creates:
Pt. Valid
rmb 1
Pt.Actv
rmb 1
Pt.ToTm
Pt.TITo
rmb 1
rmb 1
rmb 2
rmb2
rmb 1
rmb 1
rmb 1
rmb 1
rmb 1
rmb 1
rmb 1
rmb 1
rmb 2
rmh2
rmb 2
rmb 1
rmb 1
rmb 2
rmb 2
rmb 2
rmb 2
equ.
rmb 2
rmb 2
equ.
Pt.TSSt
Pt.CBSA
Pt.CBSB
Pt.CCtA
Pt.CCtB
Pt.TTSA
Pt.TTSB
pt.TLSA
Pt.TLSB
Pt.BDX
Pt.BDY
Pt.Stat
Pt.Res
Pt.AcX
Pt.AcY
Pt.WRX
Pt.WRY
Pt.Siz
SPt.SRX
SPt.SHY
8Pt.Siz
Is returned info valid? (0 = no,
1 = yes)
Active side (0 = off, 1 = right, 2 =
left)
Timeout initial value
Time until timeout
RESERVED
Time since counter start
Current button state
Current button state
Click count
Click count
Time this state counter
Time this state counter
Time last state counter
Time last state counter
(Button A)
(Button B)
(Button
(Button
(Button
(Button
(Button
(Button
A)
B)
A)
B)
A)
B)
RESERVED
Button down frozen Actual X
Button down frozen Actual Y
Window pointer type location
Resolution (0-640 by 0 = 10/1 = 1)
Actual X value
Actual Y value
Window relative X
Window relative Y
Packet size 32 bytes
System use, screen relative X
System use, screen relative Y
Size of packet for system use
• Button Information:
Pt.Valid. The valid byte gives the caller an indication of
whether the infurmation contained in the returned packet
is accurate. The information returned by this call is only
valid if the process is running on the current interactive
window. If the process is on a non-interactive wind{JW, the
byte is zero and the process can ignore the information
returned.
8·124
System Calls! 8
pt.Actv. This byte shows which port is selected for use by
all mouse functions. The default value is Right (1). You can
change this value with the SS.GIP &t8tat caU.
Pt.ToTm. This is the initial value used by Pt.TTTo.
Pt. TITo. This is the count down value (as of the instant
the Getstat call is made). This value starts at the value
contained in the Pt.ToTm and counts down to zero at a rate
of 60 counts per second. The system maintains all counters
until this value reaches 0, at which point it sets all
counters and states to O. The mouse scan routine changes
into a quiet mode which requires less overhead than when
the mouse is active. The timeout begins when both buttons
are in the up (open) state. The timer is reinitialized to the
value in Pt.ToTm when either button goes down (closed).
Pt.TSSt. This counter is constantly increasing, beginning
when either button is pressed while the mouse is in the
quiet state. All counts are a number of ticks (60 per second). The timer counts to $FFFF, then stays at that value
if additional ticks occur.
Pt.CBSA. These flag bytes indicate the state of the button
Pt.CBSB. at the last system clock tick. A value of 0 indicates that the button is up (open). A value other than zero
indicates that the button is down (closed). Button A is
available on all Tandy joysticks and mice. Button B is only
available for products that have two buttons.
The system scans the mouse buttons each time it scans the
keyboard.
Pt.CCtA. This is the number of clicks that have occurred
Pt.CCtB. since the mouse went into an active state. A
click is defined as pressing (closing) the button, then releasing (opening) the button. The system counts the clicks as
the button is relea,sed.
Pt. TTSA. This counter is the number of ticks that have
Pt.1TSB. occurred during the current state, as defined by
Pt.CBSx. This counter starts at one (counts the tick when
the state changes) and increases by one for each tick that
occurs while the button remains in the same state (open or
closed).
8-125
as -9 Technical Reference
Pt.TLSA. This counter is the number of ticks that have
Pt.TLSB. occurred during the time that a button is in a
state opposite of the current state. Using this count and
the ITSAITTSB count, you can determine how a button
was in the previous state, even if the system returns the
packet after the state has changed. Use these counters,
along with the state and click count values, to define any
type of click, drag, or hold convention you want.
Reserved. Two packet bytes are reserved for future expansion of the returned data.
• Position Information:
Pt.BDX. These values are copies of the Pt.AcX and Pt.AcY
Pt.BDY. values when either of the buttons change from an
open state to a closed state.
Pt.Stat. This byte contains information about the area of
the screen on which the mouse is positioned. Pt.Valid must
be a value other than 0 for this information to be accurate.
If Pt. Valid is 0, this value is also and not accurate. Three
types of areas are currently defined:
°
o
1
2
content region or current working area of the
window
control region (for use by Multi-View)
off window, or on an area of the screen that is not
part of the window
Pt.Res. This value is the current resolution for the mouse.
The mouse must always return coordinates in the range of
0-639 for the X axis and 0-191 for the Y axis. If the system
is so configured, you can use the high-resolution mouse
adapter which provides a 1 to 1 ratio with these values plus
1. If the adapter is not in use, the resolution is a ratio of 1
to 10 on the X axis and 1 to 3 on the Y axis. The keyboard
mouse provides a resolution of 1 to 1. The values in Pt.Res
are:
o = low res (x:10, y:3)
1 = high res (x,y:l)
Pt.AcX. The values read from the mouse returned in the
Pt.AcY. resolution as described under Pt.Res.
8-126
System Calls / 8
Pt.WRX. The values read from the mouse minus the
Pt. WRY. starting coordinates of the current window's
working area. These values return the coordinates in numbers relative to the type of screen. For example, the X axis
is in the range 0-639 for high-resolution screens and 0-319
for low resolution screens. You can divide the window relative values by 8 to obtain absolute character positions.
These values are mo!:>t helpful when working in non-scaled
modes.
• The support modules for this call are CC3IO, GrfInt, and
Windlnt.
SS.Palet
(Function code $91). Gets palette information
Entry Conditions:
A
B
X
=
path number
= $91
= pointer to the 16-byte palette informatiDn buffer
Exit Conditions:
X
=
pointer to the 16- byte palette infOrmation buffer
Additional Information:
• SS.Palet reads the contents of the 16 screen palette registers, and stores them in a 16-byte buffer. When you make
the call, be sure the X register points to the desired buffer
location. The pointer is retained on exit. The palette values
returned are specific to the screen on which the call is
made.
• The support modules for this call are VDGINT, GrfInt, and
WindInt.
8·127
OS·9 Technical Reference
SS.ScTyp
(Function code $93), Returns the type of a screen to a calling
program.
Entry Conditions:
A
B
=
=
path
$93
Exit Conditions:
= screen type code
A
1 = 40 x 24 text screen
2 = 80 x 24 text screen
3 = not used
4 = not used
5 = 640 x 192, 2-color graphics screen
6 = 320 x 192, 4-color graphics screen
7 = 640 x 192, 4-color graphics screen
8 = 320 x 192, 16-color graphics screen
Additional Information:
• Support modules for this system call are Grflnt and
Windlnt.
8-128
System Calls I 8
SS.FBRgs
(Function code $96). Returns the foreground, background and
border palette registers for a window.
Entry Conditions:
A
B
= path number
;;;;; $96
Exit Conditions:
A
B
X
;: foreground palRtte register number
= background palette register number (if carry clear)
= least significant byte of border palette register number
Error Output:
B
CC
;;;;; error code if any
= carry set on error
Additional Infonnation:
• Support modules for SS.FBRgs are Grflnt and WindInt.
SS.DFPal
(Function code $97). Returns the default palette registeI
settings.
Entry Conditions:
A
B
X
= path
= $97
=
number
pointer to 16-byte data space
Exit Conditions:
X
=
default palette data moved to user spoce
Error Output:
error code, if any
B
=
CC
;;;;; carry set on error
8-129
OS-9 Technical Reference
Additional Information:
• You can use SS.DFPal to find the values of the default palette registers that are used when a new screen is allocated
by Grflnt or Windlnt. The corresponding SetStat can alter
the default registers. This GetStat/SetStat pair is for system configuration utilities and should not be used by general applications.
Set Status System Calls
Use the Set Status system calls with the REF manager subroutine SETSTA. The 08-9 Level Two system reserves function
Codes 7-127 for use by Microware. You can define Codes 200-255
and their parameter-passing conventions for your own use. (See
the sections on device drivers in Chapters 4, 5, and 6.)
Following are the Set Status functions and their codes.
SS.OPT
(Function code $00). Writes the option section of the path
descriptor
Entry Conditions:
A
B
X
=
=
=::;
path number
$00
address of the status packet
Error Output:
CC
B
= carry set on error
= error code (if any)
Additional Information:
• SS.OPr writes the option section of the path descriptor
from the 32-byte status packet pointed to by Register X.
Use this system call to set the device operating parameters,
such as echo and line feed.
8-130
System Calls / 8
SS.SIZ
(Function code $02). Changes the size of a file for RBF.type
devices
Entry Conditions;
= path number
A
B
X
=
U
=
=
$02
most significant 16 bits of the desired file size
least significant 16 bits of the desired file size
Error Output:
CC
= carry set on error
B
=
error code (if any)
SS.RESET
(Function code $03). Restores the disk drive head to Track 0 in
preparation for formatting and error recovery (use only with
RBF -type devices)
Entry Conditions:
A
=
path number
B
=
$03
Error Output:
CC
B
=
=
carry set on error
error code (if any)
8-131
OS -9 Technical Reference
SS.WTRK
(Function code $04). Fbrmats (writes) a track on a disk (RBFtype devices only)
Entry Conditions:
A
B
V
X
Y
path number
$04
= track number (least significant 8 bits)
= address of t~ track buffer
= side/density
Bit BO = side
o = Side 0
1 = Side 1
Bit Bl = density
o = single
=
=
1 = double
Error Output:
CC
B
=
=
carry set on error
error cock (if any)
Additional Information:
• For hard disks or floppy disks that have a "format entire
diskette command," SS.WTRK formats the entire disk only
when the track number is zero.
8·132
System Calls / 8
SS.SQD
(Function code $OC). Starts the shutdown procedure for a hard
disk that has sequence-down requirements prior to removal of
power. (Use only with RBF-type devices.)
Entry Conditions:
A
B
=
=
path number
SOC
Exit Conditions: None
SS.KySns
(Function code $27). Turns the key sense function on and off
Entry Conditions:
A
B
X
=
path number
= $27
=
key sense switch value
o = normal key operation
1 = key sense operation
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• When SS. KySns switches the keyboard to key sense mode,
the CC3IO module suspends transmission of keyboard characters to the SCF manager and the user. While the computer is in key sense mode, the only way to detect key press
is with SS.KySns.
• The support module for this call is CC3IO.
8·133
08-9 Technical Reference
SS.ComSt
(Function code $28). Used by the SCF manager to configure a
serial port
Entry Conditions:
A
=
B
=
=
Y
path number
$28
high byte: parity
low byte: baud rate
Error Output:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
Baud Configuration. The high order byte of Y determines the
baud rate, the word length, and number of stop bits. The byte is
configured as follows:
PD.BAU
I
Baud rate
Reserved
Word length
Stop bits
Stop bits:
0=1
1 = 2
Word length:
00 = 8 bit
01 = 7 bit
Baud rate:
0000 = 110
0001 = 300
0010 = 600
0011 = 1200
0100 = 2400
0101 = 4800
0110 = 9600
0111 = 19200
lxxx = undefined
8-134
System Calls / 8
• Parity Configuration. The low order byte of Y determines
parity. The byte is configured as follows:
PD.BAU
I
7
6
Parity:
5
--,----'1
,--I
I
4
3
I
L
I
2
I
1
I
0
1
I
I
Special use
Parity
xxO
= none
001
= odd (ACIAPAK and MODPAK only)
all
=
101
= transmit:
111
=
even (ACIAPAK and MODPAK only)
mark
receive: ignore
transmit: space
receive: ignore
• The SCF manager uses SS.ComSt to inform a driver that
serial port configuration information has been changed in
the path descriptor. After calling SS.ComSt, a user routine
must call the SS.OPT SetStat to correctly update the path
descriptor.
• This call is for the use of the SCF manager. Use SS.OPT
for changing baud, stop bit, and parity values.
SS.Close
(Function code $2A). Informs a device driver that a path is
closed.
Additional Information:
This call is used internally by OS-9's SCF file manager and is
not available for user programs. It can be used only by device
drivers and file managers.
8-135
os -9 Technical Refereru:e
SS.AAGBf
(Function code $80). Reserves an additional graphics buffer
Entry Conditions:
== path number
$80
A
B
=
Exit Conditions:
buffer address
X
=
Y
== buffer number (1-2)
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• SS.AAGBf allocates an additional 8K graphics buffer. The
first buffer (Buffer 0) must be allocated by using the DIS·
PLAY GRAPHICS command. To use the DISPLAY GRAPHICS command, send control code $OF to the standard
terminal driver. SS.AAGBf can allocate up to two additional buffers (Buffers 1 and 2), one at a time.
• After calling SS.AAGBf, Register X contains the address of
the new buffer. Register Y contains the buffer number.
• To deallocate all graphics buffers, use the END GRAPHICS
control code.
• When SS.AAGBf allocates a buffer, it also maps the buffer
into the application's address space. Each buffer uses 8K of
the available memory in the application's address space.
Also, if SS.DStat is called, Buffer 0 is also mapped into the
application's address space. Allocation of all three buffers
reduces the application's free memory by 24K.
• The support module for this call is VDGINT.
8·136
System Calls J 8
SS.SLGBf
(Function code $81), Selects a graphics buffer
Entry Conditions:
A
=
path number
B
=
$81
X
= $00
Y
=
select buffer for use
$OI-$FF sel£ct buffer for use arul display
buffer number (0-2)
Exit Conditions:
X
=
Y
=
um:hanged from entry
unchanged from entry
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• Use DISPLAY GRAPHICS to allocate the first graphics
burrer. Use SS.AAGBf to allocate the second and third
graphics buffers.
• Save each return address when writing directly to a screen.
It is not necessary to save return addresses when using
operating system graphics commands.
• SS.SLGBf does not update hardware information until the
next vertical retrace (60Hz rate). Programs that use
SS.AAGBf to change current draw buffers need to wait long
enough to ensure that OS-9 has moved the current buffer to
the screen.
• The screen shows the buffer only if the buffer is selected as
the interactive device. If the device does not possess the
keyboard, 08-9 stores the information until the device is
selected as the interactive device. When the device is
selected as the interactive device, the display shows the
selected device's screen.
• The support module for this call is VDGINT.
8·137
as -9 Technical Reference
SS.MpGPB
(Function code $84). Maps the Get/Put buffer into a user
address space
Entry Conditions:
A
B
X
Y
path number
$84
= high byte: buffer group number
low byte: buffer number
= action to take
1 = map buffer
o = unmap buffer
=
=
Exit Conditions:
X
= address of the
Y
=
mapped buffer
number of bytes in buffer
Error Output:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
• The support modules for this call are GrfInt and Windlnt .
• SS.MpGPB maps a Get/Put buffer into the user address
space. You can then save the buffer to disk or directly modify the pixel data contained in the buffer. Use extreme care
when modifying the buffer so that you do not write outside
of the buffer data area.
8-138
System Calls / 8
SS.WnSet
(Function code $86). Set up a high level window handler
Entry Conditions:
A
B
X
Y
= path number
$86
= wiruiow data pointer (if Y
= window type code
=
=
WT.FSWin or WT.Win)
Error Output:
CC
B
=
carry set on error
(if any)
= error code
Additional Information:
• The C language data structures for windowing are defined
in the wind.h file in the DEFS directory of the system disk.
• The support module for this call is Windlnt.
SS.SBar
(Function code $88). Puts a scroll block at a specified position
Entry Conditions:
A
B
X
Y
= path number
=
$88
= lwrizomal position of scroll block
=
vertical position of scroll block
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• WT.FSWin-type windows have areas at the bottom and
right sides to indicate their relative positions within a
larger area. These areas are called scroll bars. SS.SBar
gives an application the ability to maintain relative position markers within the scroll bars. The markers indicate
8-139
as -9 Technical Reference
the location of the current screen within a larger screen.
Calling SS.SBar, updates both scroll markers.
• The support module for this call is WindInt.
SS.Mouse
(Function code $89). Sets the sample rate and button timeout
for a mouse
Entry Conditions:
A
B
=
X
=
= path number
$89
mouse sample rate and timeout
most significant byte = mouse sample rate
least significant byte = mouse timeout
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• SS. Mouse allows the application to define the mouse
parameters. The sample rate is the number of clock ticks
between the actual readings of the mouse status.
• The support module for the call is CC3IO.
8·140
System Calls J 8
SS.MsSig
(Function code $8A). Sends a signal to a process when the
mouse button is pressed
Entry Conditions:
A
B
=
path number
"" $8A
== user defined signal codE (low byte only)
X
Error Output:
carry set on error
CC
=
B
= error code (if any)
Additional Information:
• SS.MsSig sends the process a signal the next time a mouse
button changes state (from open to closed). Once SS.MsSig
sends the signal, the process must repeat the Setstat each
time that it needs to set up the signal.
• Processes using SS.MsSig should have an intercept routine
to trap the signal. By intereepting the signal, other processes can be notified when the change Occurs. Therefore,
the other processes do not need to continually poll the
mouse.
• The SS.Relea Setstat clears the pending signal request, if
desired. It also clears any pending signal from SS.SSig,
Because of this, if you want to clear only one signal, you
must reset the other signal after calling SS.MsSig.
• The support module for this call is CC3IO.
8-141
as -9 Technical Reference
SS.AScrn
(Function code $8B). Allocates and maps a high-resolution
screen into an application address space
Entry Conditions:
A
B
X
path number
$8B
= screen type
o 640 x 192
1
320 x 192
2
160 x 192
3
640 x 192
4 = 320 x 192
=
=
x 2 colors (l6K)
x 4 colors (l6K)
x 16 colors (16K)
x 4 colors (32K)
x 16 colors (32K)
Exit Conditions:
X
Y
;;;;; application address spcue of screen
screen number (1-3)
=
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• SS.AScrn is particularly useful in systems with minimal
memory when you want to allocate a high resolution graphics screen with all screen updating handled by a process.
• This call uses VDGInt (GRFINT is not required).
• All screens are allocated in multiples of 8K blocks. You can
allocate a maximum of three buffers at one time. To select
between buffers, use the SS.DScrn Setstat call.
• Screen memory is allocated but not cleared. The application
using the screen must do this.
• Screens must be allocated from a VDG-type device-a
standard 32-column text screen must be available for the
device.
• The support module for this call is VDGINT.
8-142
System Calls / 8
SS.DScrn
(Function code $8C). Causes VDGINT to display a screen that
was allocated by SS.AScrn
Entry Conditions:
A
B
Y
= path number
= $8C
= screen number (1-3)
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• SS.DScrn shows the requested screen if the requested
screen is the current interactive device.
• The support module for this call is VDGINT.
8-143
os -9 Technical Reference
SS.FScrn
(Function code $8D). Frees the memory of a screen allocated
by SS.AScrn
Entry Conditions:
A
B
=
path number
=
$8D
Y
=
screen number (1-3)
Error Output:
CC
=
B
=
carry set on error
error code (if any)
Additional Information:
• Do not attempt to free a screen that is currently on the
display.
• SS.FScrn returns the screen memory to the system and
removes it from an application's address space.
• The support module for this call is VDGINT.
8-144
System Calls / 8
SS.PScrn
(Function code $8E). Converts a screen to a different type
Entry Conditions:
A
B
X
Y
=
path number
= $8E
=
=
new screen
o = 640
1 = 320
2 = 160
type
x 192 x 2
colors (l6K)
x 192 x 4 colors (16K)
x 192 x 16 colors Cl6K)
3 = 640 x 192 x 4 colors (32K)
4 = 320 x 192 x 16 colors C32K)
screen number
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• SS.PScrn changes a screen allocated by SS.AScrn to a new
screen type. You can change a 32K screen to either a 32K
screen, or a 16K screen. You can change a 16K screen only
to another 16K screen type. SS.PScrn updates the current
display screen at the next clock interrupt.
• However, if you change a 32K screen to a 16K screen, 08-9
does not reclaim the extra 16K of memory. This means
that you can later change the 16K screen back to a 32K
screen.
• The support module for this call is VDGINT.
8·145
OS -9 Technical Reference
SS.Montr
(Function code $92). Sets the monitor type
Entry Conditions:
A
=
B
=
=
X
path number
$92
monitor type
color composite
1 = analog RGB
2 = monochrome composite
o
Error Output:
CC
B
=
=
carry set on error
error code (if any)
Additional Information:
• SS,Montr loads the hardware palette registers with the
codes for the default color set for three types of monitors.
The system default initializes the palette for a composite
color monitor_
• The monochrome mode removes color information from the
signals sent to a monitor.
• When a composite monitor is in use, a conversion table
maps colors from RGB color numbers. In RGB and monochrome modes, the system uses the RGB color numbers
directly.
• The support modules for this call are VDGINT and GrfDrv.
8-146
System Calls / 8
SS.GIP
(Function code $94). Sets the system wide mouse and key
repeat parameters
Entry Conditions:
= path number
A
B
X
$94
mouse resolution; in the most significant byte
o = low resolution mouse
1 = optional high resolution adapter
= mouse port location; in the least significant byte
1 = right port
2 = left port
= key repeat start constant; in the most significant byte
= key repeat delay; in the least significant byte
OOXX = no repeat
FFFF = unchanged
=
=
Y
Error Output:
CC
B
=
=
carry set if error
error code, if any
Additional Infonnation:
• Because this function affects system-wide settings, it is
best to use it from system configuration utilities and not
from general application program.
• The support module for this call is CC3IO.
8-147
as -9 Technical Reference
SS.UMBAR
(Function code $95). Requests the high level menu manager to
update the menu bar.
Entry Conditions:
A
=
path number
B
=
$95
Exit Conditions:
CC
B
=
carry set on error
= error code (if any)
Additional Information:
• An application can call SS.UMBar when it needs to redraw
menu bar information, such as when it enables or disables
menus, or when it completes a window pull down and needs
to restore the menu.
• The support module for this call is WindInt.
8-148
System Calls /8
SS.DFPal
(Function code $97). Sets the default palette register values
Entry Conditions:
A
B
X
=
=
=
path number
$97
pointer to 16 bytes ofpalette data
Exit Conditions:
X
CC
B
=
=
=
unchanged, bytes moved to system defaults
carry set on error
error code (if any)
Additional Infonnation:
• Use SS.DFPal to alter the system-wide palette register
defaults. The system uses these defaults when it allocates a
new screen using the DWSet command.
• Because this function affects system wide settings, it is
best to use it from system configuration utilities, not gen-
eral application programs.
8·149
OS·9 Technical Reference
SS.Tone
(Function code $98). Creates a sound through the terminal
output device.
Entry Conditions:
A
B
= path number
= $98
X
=
Y
=
duration and amplitude of the tone
LSB = duration in ticks (GO-sec) in the range 0-255
MSB = amplitude of tone in the range 0-63
relative frequency counter (0 = low, 4095 = high)
Exit Conditions:
These are the same as the entry conditions. There are no
error conditions.
Additional Information:
• This call produces a programmed 10 tone through the
speaker of the monitor used by the tenninal device. You can
make the call on any valid path open to term or to a window device.
• The system does not mask interrupts during the time the
tone is being produced.
• The frequency of the tone is a relative number ranging
from 0 for a low frequency to 4095 for a high frequency.
The widest variation of tones occurs at the high range of
the scale.
8-150
Appendix A
Memory Module Diagrams
Executable Memory Module Format
Relative
Address
$00
Check
Range
Use
f-----
Sync Bytes ($87,$CD)
-
f----
Module Size (bytes)
-
~
Module Name Offset
-
$01
$02
$03
$04
$05
$06
Type
Language
$07
Attributes
Revision
J
Header Parity Check
$08
header
aity
module
C C
$09
-
Execution Offset
-
f>erDlanent Storage Size
-
$OA
$OB
f----
$OC
(Additional Dictional header
extensions ocated here)
$OD
.....
,
.
Module Body
object code, constants,
and so on
f-----
f----
eRe
Check Value
-
A-I
as -9 Technical Reference
Device Descriptor Format
Relative
Address
$00
$01
Check
Range
Use
-
Sync Bytes ($87,$CD)
-
Module Size (bytes)
-
$02
f---
$03
$04
f---
Offset to Module Name -
$05
$06
$F (Type)
$1 (Lang)
$07
Attributes
Revision
J
Header Parity Check
$08
$09
f---
Offset to File Manager
Name String
-
f---
Offset to Device Driver
Name String
-
$OA
$OB
Mode Byte
$OD
$OE
f---
$OF
f---
Device Controller
Absolute Physical Addr.
(24 bit)
$10
$11
$12,$12+n
Initialization Table Size
(Initialization Table)
(Name Strings, and so on)
CRC Check Value
A-2
header
aity
-
Module
C C
Memory Module Diagrams I Appendix A
INIT Module Format
Relative
Address
$00
~
Sync Bytes ($87,$CD)
-
~
Module Size (bytes)
-
t--
Module Name Offset
-
$01
$02
$03
$04
$05
$06
$F (Type)
$1 (Lang)
$07
Attributes
Revision
$09
t--
t--
$OB
$OC
$OD
-
-
-
Offset to Default Mass
Storage Device Name String
-
-
Offset to Bootstrap
Module Name String
-
$11
$13
C C
-
Offset t{) Startup
Module Name String
f--
$OF
$12
Module
#IRQ Polling Table Entries
# Device Table Entries
$OE
$10
Forced Limit of Top
of Free RAM
header
aity
J
Header Parity Check
$08
$OA
Check
Range
Use
Name Strings
$14-n
'--
eRe Check Value
-
A·3
Appendix B
Standard Floppy Disk Format
Color Computer 3
Physical Track Format Pattern
Format
Header pattern
(once per track)
Sector pattern
(repeated 18 times)
Bytes
Value
(Dec)
(Hex)
32
4E
12
3
1
00
F5
FC
32
4E
12
00
F5
track number (0-34)
side number (0-1)
sector number (1-18)
sector length code (1)
3
1
1
1
1
2
22
4E
12
00
3
1
F5
256
2
24
Trailer pattern
(once per track)
CRC
N
FB
data area
CRC
4E
4E (fill to index mark)
B-1
Appendix C
System Error Codes
The error codes are shown in both hexadecimal and decimal. The
error codes listed include 08-9 system error codes, BASIC error
codes, and standard windowing system error codes.
Code
Code Meaning
HEX
DEC
$01
001
UNCONDITIONAL ABORT - An error occurred
from which OS-9 cannot recover. All processes
are terminated.
$02
002
KEYBOARD ABORT - You pressed I BREAK I to
terminate the current operation.
$03
003
KEYBOARD INTERRUPT -
You pressed
I SHIFT II BREAK I either to cause the current operation
to function as a background task with no video
display or to cause the current task to terminate.
$B7
183
ILLEGAL WINDOW TYPE - You tried to
define a text type window for graphics or used
illegal parameters.
$B8
184
WINDOW ALREADY DEFINED - You tried to
create a window that is already established.
$B9
185
FONT NOT FOUND - You tried to use a window font that does not exist.
$BA
186
STACK OVERFLOW - Your process (or processes) requires more stack space than is available on the system.
$BB
187
ILLEGAL ARGUMENT - You have used an
argument with a command that is inappropriate.
$BD
189
ILLEGAL COORDINATES - You have given
coordinates to a graphics command which are
outside the screen boundaries.
$BE
190
INTERNAL INTEGRITY CHECK - System
modules or data are changed and no longer
reliable.
$BF
191
BUFFER SIZE IS TOO SMALL - The data you
assigned to a buffer is larger than the buffer.
C·I
OS-9 Technical Reference
Code
HEX DEC
Code Meaning
$CO
192
ILLEGAL COMMAND - You have issued a
command in a form unacceptable to OS-g.
$C1
193
SCREEN OR WINDOW TABLE IS FULL - You
do not have enough room in the system window
table to keep track of any more windows or
screens.
$C2
194
BAD/UNDEFINED BUFFER NUMBER - You
have specified an illegal or undefined buffer
number.
$C3
195
ILLEGAL WINDOW DEFINITION - You have
tried to give a window illegal parameters.
$C4
196
WINDOW UNDEFINED - You have tried to
access a window that you have not yet defined.
$C8
200
PATH TABLE FULL - 08-9 cannot open the
file, because the system path table is full.
$C9
201
ILLEGAL PATH NUMBER - The path number
is too large, or you specified a non-existent path.
SCA
202
INTERRUPT POLLING TABLE FULL - Your
system cannot handle an interrupt request,
because the polling table does not have room for
more entries.
$eB
203
ILLEGAL MODE - The specified device cannot
perform the indicated input or output function.
$eC
204
DEVICE TABLE FULL - The device table does
not have enough room for another device.
$eD
205
ILLEGAL MODULE HEADER - 08-9 cannot
load the specified module because its sync code,
header parity, or Cyclic Redundancy Code is
incorrect.
$CE
206
MODULE DIRECTORY FULL - The module
directory does not have enough room for another
module entry.
C-2
System Error Codes I C
Code
HEX DEC
$CF
207
Code Meaning
MEMORY FULL - Process address space is full
or your computer does not have sufficient memory
to perform the specified task.
$DO
208
ILLEGAL SERVICE REQUEST - The current
program has issued a system call containing an
illegal code number.
$D1
209
MODULE BUSY - Another process is already
using a non-shareable module.
$D2
210
BOUNDARY ERROR - 08-9 has received a
memory allocation or deallocation request that is
not on a page boundary.
$D3
211
END OF FILE - A read operation has encountered an end-of-file character and has
terminated.
$D4
212
RETURNING NON-ALLOCATED MEMORY The current operation has attempted to deallocate memory not previously assigned.
$D5
213
NON-EXISTING SEGMENT - The file structure of the specified device is damaged.
$D6
214
NO PERMISSION - The attributes of the specified file or device do not permit the requested
access.
$D7
215
BAD PATH NAME - The specified pathlist contains a syntax error, for instance an illegal
character.
$D8
216
PATH NAME NOT FOUND not find the specified pathlist.
$D9
217
SEGMENT LIST FULL - The specified file is
too fragmented for further expansion.
$DA
218
FILE ALREADY EXISTS - The specified filename already exists in the specified directory.
$DB
219
ILLEGAL BLOCK ADDRESS - The file structure of the specified device is damaged.
The system can-
C-3
as -9 Technical Reference
Code
HEX DEC
Code Meaning
$DC
220
PHONE HANGUP-DATA CARRIER DETECT
LOST - The data carrier detect is lost on the
RS-232 port.
$DD
221
MODULE NOT FOUND - The system received
a request to link a module that is not in the
specified directory.
$DF
223
SUICIDE ATIEMPT - The current operation
has attempted to return to the memory location
of the stack.
$EO
224
ILLEGAL PROCESS NUMBER process does not exist.
$E2
226
NO CHILDREN - The system has issued a wait
service request but the current process has no
dependent process to execute.
$E3
227
ILLEGAL SWI CODE - The system received a
software interrupt code that is less than 1 or
greater than 3.
$E4
228
PROCESS ABORTED - The system received a
signal Code 2 to terminate the current process.
$E5
229
PROCESS TABLE FULL - A fork request cannot execute because the process table has no
room for more entries.
$E6
230
ILLEGAL PARAMETER AREA - A fork call
has passed incorrect high and low bounds.
$E7
231
KNOWN MODULE -
The specified
The specified module is
furinternaluseon~.
$E8
232
INCORRECT MODULE eRe - The CRe for the
module being accessed is bad.
$E9
233
SIGNAL ERROR - The receiving process has a
previous, unprocessed signal pending.
$EA
234
NON-EXISTENT MODULE - The system cannot locate the specified module.
C-4
System Error Codes / C
Code
HEX DEC
$EB
235
Code Meaning
BAD NAME - The specified device, file, or module name is illegal.
$EC
236
BAD MODULE HEADER - The specified module header parity is incorrect.
$ED
237
RAM FULL - No free system random access
memory is available: the system address space is
full, or there is no physical memory available
when requested by the operating system in the
system state.
$EE
238
UNKNOWN PROCESS ID cess ID number is incorrect.
$EF
239
NO TASK NUMBER AVAILABLE able task numbers are in use.
The specified proAll avail-
Device Driver Errors
I/O device drivers generate the following error codes. In most
cases, the codes are hardware-dependent. Consult your device
manual for more details.
Code
HEX DEC
Code Meaning
$FO
240
UNIT ERROR doesn't exist.
$F1
241
SECTOR ERROR - The specified sector number
is out of range.
$F2
242
WRITE PROTECT write-protected.
$F3
243
eRC ERROR - A Cyclic Redundancy Code error
occurred on a read or write verify.
$F4
244
READ ERROR - A data transfer error occurred
during a disk read operation, or there is a SCF
(terminal) input buffer overrun.
The specified device unit
The specified device is
C-5
os -9 Technical Reference
Code
Code Meaning
HEX DEC
$F5
245
WRITE ERROR write operation.
$F6
246
NOT READY ready status.
$F7
247
SEEK ERROR - The system attempted a seek
operation on a non-existent sector.
$F8
248
MEDIA FULL - The specified media has insufficient free space for the operation.
$F9
249
WRONG TYPE - An attempt is made to read
incompatible media (for instance an attempt to
read double-side disk on single-side drivel,
$FA
250
DEVICE BUSY use.
$FB
251
DISK ID CHANGE - You changed diskettes
when one or more files are open.
$FC
252
RECORD IS LOCKED-OUT - Another process
is accessing the requested record.
$FD
253
NON-SHAREABLE FILE BUSY - Another process is accessing the requested file.
$FE
254
I/O DEADLOCK ERROR - Two processes have
attempted to gain control of the same disk area
at the same time.
C-6
An error occurred during a
The device specified has a rwt
A non-shareable device is in
Index
ACIAPAK 8-135
active process 2-12 - 2-13
queue 2-14, 8-98
state 2-13 - 2-14
address
find 64K block 8-85
lines 2-7
polling 2-17
space, add module 8-104
age, process 2-14
alarm, set 8-66
allocate
high RAM 8-69
image 8-70
memory 8-76
memory blocks 8-678-68
process descriptor 8-71
process task number
8-73
RAM 8-72
allocation
bit map 8-7
map sector 5-1
of memory 2-5 - 2-7
polling 2-17
allocation map
clear 8-13
disk 5-3
alpha screen
cursor 8-118
memory 8-11 7
ASM assembler 8-2
aBsembler, RMA 8-2
attach a device 8-44 - 8-45
attribute
byte 5-5,
file 5-12
background color, get 8-129
bell, set alarm 8-66
bit map 2-5
allocation 8-7
bit map (cont'd.)
search memory
allocation 8-33
block
allocate system
memory 8-105
deallocate system
memory 8-106
map into process
space 8-96
number 2-7
scroll 8-139
block map, system 8-18
boot
file, load 5-26
module, link 8-75
booting 08-9 1-3
bootstrap
memory request 8-76
system 8-75
border color, get 8-129
buffer
map (Get/Put) 8-138
reserve graphics 8-136
button
state, mouse 8-1248-125, 8-126
timeout, mouse 8-140
byte
attribute 5-5
deallocate 64-byte
block 8-101
get from memory
block 8-94
get two bytes 8-95
read from path 8-598-60
store in task 8-109
calling process
insert in I/O queue 8-91
terminate 8-14
turn off 8-35, 8-43
CC3DISK 1·2
1
os -9 Technical Reference
CC3GO module 2-19
CC3IO 1-2, 6-1
chain 8-8 - 8-9
change
device operating
parameters 5-23
directory 8-46
character
read SCF input 6-13
write, SCF 6-14
ChgDir 4-4
child process 2-13
create 8-15 - 8-17
clear specified block 8-77
click 8-126
CLOCK 1-2
clock
module 1-2, 2-19
real-time 2-12, 2-17
close
file 4-7
path 8-47, 8-135
codes
signal 2-15
system error C-1
command interpreter 1-4
communication,
interprocess 2-15
compact module directory
8·88
compare strings 8-10
compatibility with Level
One 2-1
concurrent execution 7-1 - 7-3
copy external memory 8-11
count, link 2-5
counter start, mouse 8-124
CPU 2-7
time 4-11
CRe
calculate 8-12
validate module 8-111
value 3-1 - 3-3
create
directory 8-55 - 8-56
2
create (cont'd.)
file 8-48 - 8-49
current
data directory 8-51
execution directory 8-51
cursor positioning 4-5
cyclic redundancy check 3-13-3
DAT
hardware 8-99
registers 8-103
to logical address 8-78
data
available, SCF test
8-113
directory 8-51
stream 4-3
transfer, pipes 7-1 - 7-3
move in memory 8-97
DAT image 8-70
conversion 8-78
copy into process
descriptor 8-102
deallocate block 8-77
high block 8-86
low block 8-87
pointer 8-95
DAT task number
release 8-99
reserve 8-100
date
get system 8-40
set 8-38
deadlock 5-13
deadly embrace 5-13
deallocate
image RAM blocks 8-79
map bits 8-13
process descriptor 8-80
RAM blocks 8-81
task number 8-82
default palette registers
8-129, 8-149
delete file 8-50 - 8-51
Index
descriptions. system call 8-2
descriptor
get process 8-20
path 4-18
pointer 8-82
process 2-13
detach device 8-52
device
add or remove from
polling table 8-92
attach 8-44 - 8·45
attachment, verify 8-44
·8·45
controller 5-15
control registers,
initialize 6-12
control registers, SCF
6-12
descriptor 1-4, 4-2. 4-17,
A-2
detach 8-52
modules 5-15
modules, RBF 5-8 - 5-10
modules, SCF 6-6 - 6-8
name. get 8-115
open path to 8-57 - 8-58
operating parameters.
RBF 5-23
operating parameters,
SCF 6-15
status 2-17 - 2-18, 8-63
status, get 8-54
table 4-2, 8-52
terminate. RBF 5-24
terminate, SCF 6-16
write to 8-64 - 8-65
device driver 1-3, 4-11
close path 8-135
modules 4-8
name 5-15
SCF 6-9 - 6-17
SCF subroutines 6-106-17
subroutines. RBF 5-16-
device driver modules.
REF 5-13 - 5-17
device interrupt 5-25
SCF 6-17
directory
attribute byte 5-5
change 8-46
disk 5-5
entry, module 8-83
get module 8-19
make 8-55 - 8-56
module 2·12,8-88
disk
directories 5-5
sector read 5·19. 5-21
disk allocation map 5-3
sector 5-1
diskette furmat B-1
display
screen 8-143
status, get 8-115
drag 8-126
drive head, restore 8-131
duplicate path 8-53
editing, line 6-1, 8-61
end-of-file, test for 8-114
equate file 2-4
equivalent logical address
8-78
error
codes, system C-l - C-G
message, write 8-30
print 8-30
exclamation point, pipes 7-1-
7·3
execute
mode 5-11
system calls 8-1 - 8-2
execution
directory 8-51
offset. module 3·7
exit calling process 8-14
external memory, read 8-11
5-27
3
as -9 Technical Reference
fatal signal 2-13
file
attribute byte 5-12
closing 4-7
create 4-4, 5-12, 8-48 8-49
deadlock 5-13
delete 4-5, 8-50 - 8-51
descriptor 5-3· 5-4
execute mode 5-11
get pointer position
8-114
line reading/writing 4-6
load module 8-29
locking 5-12
non-shareable 5-12
opening 4-4
open path 8-57 - 8-58
permission bits 5-4
pipe 7-1 - 7-3
pointer 4-5, 8-62
position, RBF 8-114
read 5-1, 4-5
sharing 5-12
size, get 8-114
status, get 8-54, 8-114
update mode 5-11
write line to 8-64 - 8·65
writing 4-6
file manager 1-3
modules 4-3
name 5-15
find
64-byte block 8-85
module directory
entry 8-84
fire button 8-123 - 8-127
FIRQ 4-12
interrupt 2-17
flag, RAM In Use 8-81
flip byte 2-17
floppy diskette format B·1
foreground color get 8-129
FORK 2-8
fork, child process 8-15 - 8-17
I
4
FORMAT 5-2
format
device descriptor 4-17,
A-2
[NIT module A·3
memory module 3·63-7, A·I
of device driver
modules 4-10
track 8-132
function
calls 2-4 - 2-5, 8-1
key sense 8-133
get
a byte 8-94
free high block 8-86
free low block 8-87
ID 8-22
process pointer 8-89
status 8-54
Status system calls
8-112 - 8-130
system time 8-40
Get/Put buffer, map 8-138
GETSTA 8-112
SCF 6-15
GetStat 4-6
Getstats 5-23
graphics buffer
reserve 8-136
select 8-137
graphics interface 1-2
GRFINT 1-2
handler routine, virtual
interrupt 8-11 0
hard disk shutdown 8-133
hardware
controller, SCF 6-9
DAT registers 8-103
vector 2-16
header
module 3-1 - 3-2
parity 8-111
Index
header (cont'd.)
pattern, floppy
diskette B-t
high block, memory search
8-86
high-level
menu handler 8-122
menu manager 8-148
window handler 8-139
high-resolution
mouse adapter 8-126
screen, allocate 8-142
hold, button 8-126
110
calls 2-4 - 2-5, 8-1
device accessing 2-11
module, delete 8-90
path, close 8-47
queue, insert calling
process 8-91
DO system 1-3 - 1-4
calls 2-1, 8-2
system modules 1-1-
interface
graphics 1-2
VDG 4-2
Windint 4-2
interprocess
communication 2-15
interrupt
device 5-25
enable, SCF 6-12
FIRQ 2-17
processing 2-1
lOMAN 1-2
IRQ 4-12
add/remove device from
polling table 8-92
interrupt 2-17
polling 2-17
polling table 2-18
service routine 5-25
IRQSVC routine 4-13
IRQSV 4-11
joystick value, get 8-116
1-4, 4-1
transfers
4-8
ID
return caller's
process 8-22
set user 8-39
identification sector 5-1
image, allocate 8-70
!NIT 1-2, 5-18
INIT module 2-17
format A-3
link 8-75
lnit, SFC 6-12
initialization table, SCF
device 6-6 - 6-8
initialize device memory 5-18
input buffer, read SCF
character 6-13
insert process 8-74
install virtual interrupt
8-110
intercept, set signal 8-21
kernel 1-2
key
repeat parameters,
set 8-147
sense function 8-133
status, get 8-120
keyboard scan 2-17
language byte 3-4
line
editing 6·1, 8-61
reads 4-6, 8-61
writes 4-6, 8-65
link
to memory module 8-23
- 8-24, 8-28
using module directory
entry 8-83
link count 2-5
decrease 8-42
5
as -9 Technical Reference
load
boot file 5-26
byte from memory
block 8-94
from task offset 8-93
module 8-25 - 8-26, 8-29
two bytes 8-95
lock, end-of-Iock 5-12
locking
files 5-12
record 5-10 - 5-11
logical
address space 2-6,2-8
sector number 5-1
LSN 5-2,5-5
macro 2-4
MAKDIR 4-4
make directory 8-55 - 8-56
manager
file 1-3
random block 1-3
sequential file 1-3
map
block 8-96
search allocation 8-33
mask byte 2-18
memory
allocate 8-76
allocate blocks 8-678-68
allocate high RAM 8-69
change process data
size 8-27
deallocate 2-5
find low block 8-87
free screen 8-144
map 2-6
module fonnat 3-6 - 3-7,
A-I
module, link 8-23 - 8-24
move data 8-97
page 2-5
pool 8-80
request, bootstrap 8-76
6
memory (cont'd.)
segment 2-8
memory allocation 2-5 - 2-7
memory block 2-7
find 64K 8-85
get byte 8-94
get high 8-86
map 8-81
map, search 8-72
memory management 2-1,2-5
- 2-12
unit 2-7 - 2-8
menu
manager, update
request 8-148
selection 8-122
message, write error 8-30
MMU registers 2-8
mnemonic name, LSN 5-2
MODPAK 8-135
module
add into address
space 8-104
body 3-1 - 3-2
clock 2-19
eRe calculate 8-12
decrease link count 8-42
delete 110 module 8-90
device descriptor 5-15
device driver 4-8
file manager 4-3
finding 2-12
format 3-1 - 3-3
link 8-28
link count, decrease
8-42
linking 1-2
load 8-25· 8-26, 8-29
load and execute
primary 8-8 - 8-9
name 3-3
RBF-type device
drivers 5-13 - 5-17
SCF device descriptor
6-6 - 6-8
Index
module (cont'd.)
types 3-1, 3-5
unlink 8-41
validate 8-111
module directory 2-5, 2-12
compact 8-88
entry, link using 8-83
find 8-84
get 8-19
pointer 8-84
module header 3-1 - 3-3, 5·15
SCF device driver 6-9
monitor, set type 8·146
mouse
button state 8-125
button timeout 8-140
click 8-122
coordinates 8-127
countdown 8-125
countup 8-125
parameters, set 8-147
port 8-125
resolution 8-126
screen position 8-126
send signal to process 8141
status, get 8-123
timeout 8-124
window working area
8-127
move data 8-97
mul ti plexer 2-8
multiprogramming 2-122-16
management 2-1
multitasking 1-2
name parse 8-31 - 8-32
names, compare 8-10
next process 8-98
NMI interrupt 2-17
non-Shareable file 5-12
number, path 8·53
open
file 8-48 - 8-49
path 8-57· 8-58
operation of memory
management 2-8· 2-12
08-9
Level One
compatibility 2-1
modules 1-2
scheduler 2-14 - 2-15
OS9P3 2-1
module 2-2
packet size 8-124
palette, get information 8-127
palette register 8·129
set default 8-149
settings 8-129
parameters, mouse and key
repeat 8-147
parent
directory 5-3
process 2·13
parity 8-135
parse name 8-31 - 8·32
path
close 8-47,8-135
duplicate 8-53
open 8-57· 8-58
read bytes 8-59 - 8-60
table 4-2
path descriptor 4-18, 5-5 5-8
read option section
8-112
SCF 6-2 - 6-6
write option section
8-130
permanent storage size,
module 3-7
physical address space 2·7
pipe file manager 4-3
PIPEMAN 1·2 - 1-3,4-3
pipes 4·3, 7-1 - 7-3
7
as -9 Technical Reference
process descriptor 2-132·14,8.102
deallocate 8-80
descriptor, allocate 8-71
get 8-20
pointer 8-82
processes
active 2-12
data size, change 8-27
process 10 2-13
return caller's 8-22
pseudo vector 2-16
Put8tat 4·6
RAM
2-5 - 2-7
allocate 8-69, 8-72
allocate blocks 8-70
allocation 2-13
blocks, deallocate 8·81
blocks, deallocate
image 8-79
interrupt vector 2-18
random
access 5-1
block file manager 1-3,
4-3
RBF
change file size 8-131
format track 8-132
get file size 8-114
manager 4-3
tables 5-14 - 5-17
read
bytes 8-59 - 8-60
device operating
parameters 5-23
disk sector 5-19
external memory 8-11
input character, SCF
6-13
line 6-2, 8-61
mode 5·11
system call 6-1
real-time clock 2·12, 2-17
record locking 5-10
8
reference
System Mode calls 8-58-6
User Mode system
calls 8-3 - 8-4
registers
OAT 8-103
MMU 2-8
release a task 8-99
request system memory
8-105
reserved memory 2-5 - 2·7
reserve task number 8-100
return
64 bytes 8-101
system memory 8-106
RMA assembler 8·2
ROOT directory 5-3, 5-5
RTS instruction 2-18
SCF
configure serial port
8-134 - 8·135
data available test
8-113
device control
registers 6-12
Getsta 6-15
manager 4-3
path descriptor 6-2 - 6-6
terminate device 6-16
scheduler, 08·9 2-14 - 2·15
screen
allocate highresolution 8-142
convert type 8·145
display 8-143
free memory 8-144
mouse position 8·126
palette 8-127
size, get 8-119
type 8-128, 8-142, 8-145
scroll block, install 8-139
search bits 8-33
Index
sector 5-3
pattern, floppy
diskette B-1
seek, file pointer 8-62
segment, memory 2-8
select graphics buffer 8-137
send signal 8-34
sequential character
file manager 1·3, 4-3
I/O 6-1
serial port configuration
8-121
service
request processing 2-1
routine, IRQ 5-25
set
alarm 8-66
date 8-38
IRQ 8-92
priority 8-36
process DAT image
8-102
process task DAT
registers 8-103
status 8-63
SVC 8-107 - 8-108
SWI 8·37
time 8-38
user ID 8-39
Setstats 5-23
Set Status system calls 8-130
- 8-150
shareable bit 3-5
sharing, file 5·12
shell 1-4
shutdown hard disk 8-133
signal 2-15 - 2-16
codes 2-15
fatal 2-13
from mouse to
process 8-141
intercept trap 2-152-16
intercept, set 8-21
send to process 8-34
single-user
attribute 5·12
bit, files 5-12
size
of screen 8·119
of window 8-119
sleep
calling process 8-35
sleeping process 2·14, 2-16
slices, time 2-12
sound, create 8-150
speaker, create sound 8-150
state
active 2-13
of button 8-126
sleeping 2-14
suspend 4-13
waiting 2-13
static storage address 2-18
status
display 8-115
get, SCF 6-15
get mouse 8-123· 8-127
of key 8-120
register 2-17
set, SCF 6-15
status, get 8-54
status, set 8-63
store byte in a task 8-109
string, scan input 8-31 - 8-32
strings, compare 8-10
subroutines
RBF device driver 5-16·
5-27
SCF device drivers 6-10
- 6-17
suspend
bit 4-13 - 4-14
state 4-13
SWI, set 8-37
SWI2 instruction 2-4
symbolic names 2-4
sync byte 3-3
synonymous path number,
return 8-53
9
08-9 Technical Refereru:e
system
block map, get 8-18
boot 1-3
bootstrap 8-75
date, get 8-40
device, attach 8-44
error codes C-1 - C-6
initialization 2-1
link 8-104
mode call reference 8-58-6
time, get 8-40
system call
add 8-107 - 8-108
descriptions 8-2, 2-4
execution 8-1 - 8-2
get status 8-112 - 8-130
mnemonics names 8-1
User Mode reference 8-3
·8-4
system memory
allocate high RAM 8-69
block map 8-81
deallocate 8-106
module directory, get
8-19
request 8-105
system modules I-I - 1-4
table
device 8-52
IRQ polling
2-18
RBF 5-14 - 5-17
SCF device descriptor
6-6 - 6-8
VIRQ 2-20
task
map 2-12
offset, load from 8-93
register 2-8
release 8-99
store byte 8-109
task number 8-73
DAT 8-100
deallocate 8·82
10
terminal, create sound 8-150
terminate
a device 5-24
calling process 8-14
SCF device 6-16
ticks 4-11
time
CPU 4-11
get system 8-40
set 8-38
sharing 2-11
slice 2-16, 2-12
timeout, mouse 8-124
track
furmat 8-132
restore drive head 8-131
trailer pattern, floppy
diskette B-1
trap, signal intercept 2-152-16
type
convert screen 8-145
of screen 8·128
set monitor 8-146
window screen 8-142
unlink module 8-41 - 8-42
update mode 5-11
user calls 2·5
user ID 2-13
set 8-39
User Mode system calls
reference 8-3· 8-4
validate module 8-111
VOG 1-2
alpha screen cursor
8-118
alpha screen memory
8-117
interface 4-2
vector
pseudo 2-16
set SWI 8-37
vectoring 2-16
Index
verify device attachment
8-44 - 8-45
video display generator 1-2
VIRQ 2-19 - 2-20
polling table 2-19· 2-20
virtual interrupt, install
8-110
wait
calling process 8-43
state 2-13 - 2-14
waiting process 2-13
wildcard 4-6
WINDINT 1-2
Windint interface 4-2
window
descriptors 1-2
high-level handler 8-139
pointer location 8-124
screen, type 8-142
size, get 8-119
type 8-145
working area, mouse
8-127
working directory, change
8-46
write
character to SCF
output 6-14
disk sector 5-21
path descriptor 8-1308-131
to file or device 8-64
write line 8-65
line system call 6-2
11
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement