Chapter 8
System Calls
r
System calls are used to communicate between the OS-9 operat
ing 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 I/O calls start
with I$. For example, the Change Directory call is I$ChgDir.
Names of function calls start with F$. For example, the Allocate
Bits call is F$Al1Bit. The names are defined in the assembler
input conditions equate file called OS9Defs.
System mode calls are privileged. You can execute them only
while OS-9 is in the system state (when it is processing another
system call, executing a file manager or device driver, and so
System mode calls are included in this manual primarily for pro
grammers writing device drivers and other system-level
applications.
Calling Procedure
To execute any system calls, you need to use an SW12
instruction:
1. Load the 6809 registers with any appropriate parameters:
2. Execute an SW12 instruction, followed immediately by a con
stant byte, which is the request code. In the references in
this chapter, the first line is the system call name (for exam
ple Close Path) and the second line contains the call's mne
monic name (for example I$Close), the software interrupt
Code 2 (103F), and the call's request code (for example, 8F)
3. After OS-9 processes the call, it returns any parameters in
the 6809 registers. If an error occurs, the C bit of the condi
tion code register is set, and Register B contains the appro
priate 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 Technical Reference
As an example, here is the Close system call:
LDA PATHNUM
SW12
FCB $8F
BCS ERROR
You can use the assembler's OS9
directive
to simplify the call, as
follows.
LDA PATHNUM
OS9 I$Clo5e
BCS ERROR
The ASM assembler allows any combination of upper- or lower
case letters. The RMA assembler, included in the OS-9 Level
Two Development Pak, is case sensitive. The names in this man
ual have been spelled with upper and lower case letters, match
ing the defs for RMA.
I/O System Calls
OS-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 allo
cate and set up
file control blocks, sector buffers,
and so on.
Instead, OS-9 returns a 1-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, OS-9 allocates and maintains its own data struc
tures; 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 SW12 code and the request code.
Next are the call's entry and exit conditions, followed by addi
tional 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 refer
enced in this chapter:
F$Al1Bit Sets bits in an allocation bit map
F$Chain Chains a process to a new module
F$CmpNam Compares two names
F$CpyMem Copies external memory
F$CRC Generates a cyclic redundancy check
F$De1Bit Deallocates bits in an allocation bit map
F$Exit Terminates a process
F$Fork Starts a new process
F$GB1kMp 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 mod
ule 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 l 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$Al1HRAM Allocates high RAM
F$Al1Img Allocates image RAM blocks
F$AllPrc Allocates a process descriptor
F$Al1RAM Allocates RAM blocks
F$Al1Tsk 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$C1rBlk Clears the specified block of memory
F$DATLog Converts a DAT block offset to a logical
address
F$DelImg Deallocates image RAM blocks
F$De1Prc Deallocates a process descriptor
F$De1RAM Deallocates RAM blocks
F$De1Tsk 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
OS-9 Technical Reference
F$IODeI Deletes an I/O module
F$IOQu Puts an entry into an I/D queue
F$IRQ Makes an entry into IRfa polling table
F$LDABX Loads Register A from O,X in Task B
F$LDAXY Loads A[X,[Y]]
F$LDDDXY Loads D[D + X,[Y]]
F$MapBlk Maps the specified block
F$Move Moves data to a different address space
F$NProc Starts the next process
F$Re1Tsk Releases a task number
F$ResTsk Reserves a task number
F$Ret64 Returns a 64-byte memory block
F$SetImg Sets a process DAT image
F$SetTsk Sets a process's task DAT registers
F$SLink Performs 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 Validates a module
8-6
User System Calls l 8
User System Calls
Allocate Bits
Sets bits in an
OS9 F$Al1Bit 103E 13 allocation bit map
Entry Conditions:
D
= number
of
the first bit to set
X = starting address
of
the allocation bit map
Y = number of bits to set
Error Output:
CC = carry set on error
B = error code (if
any)
Additional Information:
· Bit numbers range from 0 to n-1, 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 Technical Reference
Chain
OS9 F$Chain 103E 05
Entry Conditions:
A
B
X
Y
Error Output:
Loads and executes a
new primary module
without creating a new
process
= language/type code
= size of the data area
(in pages); must be at
= address of the module name or filename
= parameter area size
(in pages); defaults to zero if not
specified
= starting address of the parameter area;
must be at
least one page
CC = carry set on error
B = error
code (if
any)
Additional Information:
~ Chain loads and executes a new primary module, but does
not create a new process. A Chain system call is similar to
a Fork 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
Warning:
Make sure that the hardware stack pointer (Reg
ister SP) is located in the direct page before Chain exe
cutes. Otherwise the system might crash or return a
suicide attempt error. This precaution also prevents a sui
cide 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 OS-9 to unlink the process's old primary
module.
8-8
User System Calls / 8
2. OS-9
parses the name string of the new process's pri
mary module (the program that is to be executed first).
Then, it causes OS-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 path
list of a file to load into memory. Then, it links to the
first module in this file. (Several modules can be loaded
4. It reconfigures the data memory area to the size speci
fied 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.
Y (highest address)
Parameter Area
X,SP
Data Area
Direct Page
V,DP (lowest address)
D = parameter area size
PC = module entry point absolute address
CC = F = 0, I = 0; others are undefined
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
Compares two strings
OS9 F$CmpNam 103E 11 for a match
Entry Conditions:
B = length of stringl
X = address of stringl
Y = address of string2
Exit Conditions:
CC = carry clear if the strings match
Additional Information:
0
The Compare Names call compares two strings and indi
cates 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
OS9 F$CpyMem
103E 1B
Entry Conditions:
D = DAT image pointer
X = offset in block to begin copy
Y = byte count
U = caller's destination buffer
Error Output:
CC = C bit set on error
B = appropriate error code
Additional Information:
Reads external memory
into the user's buffer
for inspection
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 half),
then place a value in Register X that equals the offset from
the beginning of the DAT image ($8000).
0
The support module for this call is OS9p2.
8-11
OS-9 Technical Reference
CRC
OS9 F$CRC 103E 17
Entry Conditions:
X
Y
U
Exit Conditions:
Calculates the CRC of
a module
starting byte address
number
of
bytes
address of the
3-byte CRC accumulator
Updates the CRC accumulator.
Additional Information:
The CRC 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 con
tinues over the specified
number
of
bytes.
· You need not cover an entire module in one call, since the
CRC can be accumulated over several calls. The CRC accu
mulator can be any 3-byte memory area. You must initial
ize it to $FFFFFF before the first CRC call.
The updated accumulator does not include the last three
bytes of the module. The three CRC bytes are stored there.
0
Be sure to initialize the CRC accumulator only once for
each module checked by CRC.
8-12
User System Calls l 8
Deallocate Bits
Clears allocation map
OS9 F$De1Bit 103E 14 bits
Entry Conditions:
D = number of the first bit to set
X = starting address of the allocation bit map
Y = 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-1,
where
n is
the number of bits in the alloca
· Warning: Do not call Deallocate Bits with Register Y set
to 0 (a bit count of 0).
8-13
OS-9 Technical Reference
Exit
OS9 F$Exit 103E 06
Entry Conditions:
B = status code to return to the parent
Exit Conditions:
The process is terminated.
Additional Information:
Terminates the calling
process
The Exit system call is the only way a process can termi
nate itself. Exit deallocates 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 sta
tus 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 l 8
Fork
Creates a child process
OS9 F$Fork 103E 03
Entry Conditions:
A = language/type code
B = size of the optional data area
(in pages)
X = address of the module name or filename
(See the follow
Y = size of the parameter area
(in pages); defaults to zero if
U = starting address of the parameter area;
must be at
Exit Conditions:
X = address of the last byte of the name + 1
(See the fol
A = new process IO number
Error Output:
B = error code
(if any)
Error Output:
CC = 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 reg
isters and standard 1/O paths.
Before the Fork call:
T E S T $OD
X
8-15
OS-9 Technical Reference
After the Fork call:
T
E ]_S ] T $OD]
X
· This is the sequence of Fork's operations:
1. OS-9 parses the name string of the new process's pri
mary module (the program that OS-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, OS-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 mem
ory. Then, the first module in this file is linked to and
executed. (Several modules can be loaded from one file.)
3. OS-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 cop
ied 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. OS-9 uses
the execution offset given in the module header to set
the program counter to the module's entry point.
Y
Parameter Area X ,SP (highest address)
Data Area
Direct Page
V,DP (lowest address)
8-16
User System Calls / 8
D = size of the parameter area
PC = module entry point absolute address
CC = F = 0, I = 0, other condition code flags are undefined
Registers Y and U (the top-of-memory pointer and bottom
of-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 string
oriented 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
(#n
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 OS-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 0.
8-17
OS-9 Technical Reference
Get System
Gets a copy of the
Block Map
system block map
OS9 F$GB1kMp 103E 19
Entry Conditions:
X = pointer to the 1024-byte buffer
Exit Conditions:
D = number of bytes per block
($2000) (MMU block size
dependent)
Y = system memory block map size
Error Output:
CC = carry set on error
B = 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 OS-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
F$GModDr 103E 1A
Entry Conditions:
X
Y
U
Gets a copy of the
system module
directory
pointer to the 2048-byte buffer
end of copied module directory
start address of system module directory
Error Output:
CC = carry set on error
B = 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 OS-9
MDIR command uses this call to read the module
directory.
· The support module for this call is OS9p2.
8-19
OS-9 Technical Reference
Get Process
Descriptor
F$GPrDsc 103E 18
Entry Conditions:
A
X
Gets a copy of the
process's process
descriptor
requested process ID
pointer to a 512 -byte buffer
Error Output:
CC = carry set on error
B = error code (if
any)
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 exist
ing process.
The support module for this call is OS9p2.
8-20
User System Calls / 8
Intercept
Sets a signal intercept
OS9 F$Ic t 103E 09 trap
Entry Conditions:
X = address of the intercept routine
U = 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 killed.
Additional Information:
· Intercept tells OS-9 to set a signal intercept trap. Then,
whenever the process receives a signal, OS-9 executes the
process's intercept routine.
Store the address of the signal handler routine in Register
X and the base address of the routine's storage area in
Once the signal trap is set, OS-9 can execute the intercept
routine at any time because a signal can occur at any
· 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:
1. When the process receives a signal, OS-9 sets Registers
U and B as follows:
U = starting address of the intercept routine's
memorv area
V
B = signal
code
(process's termination status)
Note:
The value of Register DP cannot be the
same as it was when the Intercept call was
2. After setting the registers, OS-9 transfers execution to
the intercept routine.
8-21
OS-9 Technical Reference
Get ID
Return's a caller's
OS9 F$ID 103E OC process ID and user ID
Entry Conditions:
None
Exit Conditions:
A = process ID
Y = user ID
Additional Information:
The
process ID is
a byte value in the range 1 to 255. OS-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 3 ),
the user ID is inherited from CC3go, which forks the initial
shell.
8-22
User System Calls / 8
Link
Links to a memory
OS9 F$Link 103E 00 module that has the
specified name,
language, and type
Entry Conditions:
A = type/language byte
X = address of the module name
(See the following
example.)
Exit Conditions:
A = type/language code
B = attributes / revision level (if
no error)
X = address of the last byte of the module name + 1
(See
the following example.)
Y = module entry point absolute address
U = module header absolute address
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:
T E S T
$OD]
t _
X
After the Link call:
T E S T $OD
X
8-23
OS-9 Technical Reference
· This is the order in which the Link call operates:
1. OS-9 searches the module directory for a module that
has the specified name, language, and type.
2. If OS-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 OS-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' l 8
Load
Loads a module or
OS9 F$Load 103E Ol modules from a file
Entry Conditions:
A = language/type code; 0 = any
language/type
X = address
of
the pathlist (filename)
(See the following
example.)
Exit Conditions:
A = language/type code
B = attributes l revision level (if
no error)
X = address of the last byte of the pathlist
(filename) + 1
(See the following example.)
Y = primary module entry point address
U = address
of
the module header
Error Output:
CC = carry set if error encountered
Additional Information:
· The Load call loads one or more modules from the file spec
ified 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 direc
tory. It links the first module read. The exit conditions
apply only to the first module loaded.
Before the Load call:
/ D
10 / A
C C T S R C V $OD]
8-25
OS-9 Technical Reference
After the Load call:
/ D
10 / A
C C T S R C ZT $OD
X
Possible errors:
· Module directory full
· Memory full
· Errors that occur on the Open, Read, Close, and Link
system calls
8-26