System Calls
Contents
System Calls
System calls are used to communicate between the NitrOS-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 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$AllBit. The names are defined in the assembler-input conditions equate file called OS9Defs.
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:
- Load the 6809 registers with any appropriate parameters.
- Execute an SWI instruction, followed immediately by a constant byte, which is the requested 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.
- After NitrOS-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.
As an example, here is the Close system call:
LDA PATHNUM SWI2 FCB $8F BCS ERROR
You can use the assembler's OS9 directive to simplify the call, as follows:
LDA PATHNUM OS9 I$Close BCS ERROR
The ASM assembler allows any combination of upper- or lowercase letters. The RMA assembler, included in the OS-9 Level Two Development Pack, is case sensitive. The names in this manual have been spelled with upper- and lowercase letters, matching the defs for RMA.
I/O System Calls
NitrOS-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, NitrOS-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, NitrOS-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.
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 quick summary of the User Mode System Calls referenced in this chapter:
I/O System Calls Quick Reference
System Mode Calls Quick Reference
Following is a summary of the System Mode Calls referenced in this chapter:
System Calls in Numeric Order
| Code | Mnemonic | Mode | Description |
|---|---|---|---|
| $00 | F$Link | User | Links to a memory module |
| $01 | F$Load | User | Loads a module from mass storage |
| $02 | F$Unlink | User | Unlinks a module |
| $03 | F$Fork | User | Starts a new process |
| $04 | F$Wait | User | Waits for a signal |
| $05 | F$Chain | User | Chains a process to a new module |
| $06 | F$Exit | User | Terminates a process |
| $07 | F$Mem | User | Changes a process's data area size |
| $08 | F$Send | User | Sends a signal to a process |
| $09 | F$Icpt | User | Sets a signal intercept trap |
| $0A | F$Sleep | User | Suspends a process |
| $0B | F$SSpd | User | Suspends a process |
| $0C | F$ID | User | Returns a process ID |
| $0D | F$SPrior | User | Sets a process's priority |
| $0E | F$SSWI | User | Sets a software interrupt vector |
| $0F | F$PErr | User | Prints an error message |
| $10 | F$PrsNam | User | Parses a pathlist name |
| $11 | F$CmpNam | User | Compares two names |
| $12 | F$SchBit | User | Searches a bit map |
| $13 | F$AllBit | User | Sets bits in an allocation bit map |
| $14 | F$DelBit | User | Deallocates bits in an allocation bit map |
| $15 | F$Time | User | Returns the current time |
| $16 | F$STime | User | Sets the system time |
| $17 | F$CRC | User | Generates a cyclic redundancy check |
| $18 | F$GPrDsc | User | Gets a copy of a process descriptor |
| $19 | F$GBlkMp | User | Gets a copy of a system block map |
| $1A | F$GModDr | User | Gets a copy of the module directory |
| $1B | F$CpyMem | User | Copies external memory |
| $1C | F$SUser | User | Sets the user ID number |
| $1D | F$Unload | User | Unlinks a module by name |
| $1E | F$Alarm | User | Color Computer 3 Alarm Call |
| $21 | F$NMLink | User | Links to a module; does not map the module into the user's address space |
| $22 | F$NMLoad | User | Loads a memory but does not map it into the user's address space |
| $23 | F$Debug | User | Drop the system into the debugger |
| $25 | F$TPS | User | Return the system's ticks per second |
| $26 | F$TimAlm | User | CoCo individual process alarm call |
| $27 | F$VIRQ | User | Makes an entry in a virtual IRQ polling table |
| $28 | F$SRqMem | System | Performs a system memory request |
| $29 | F$SRtMem | System | Performs a system memory return |
| $2A | F$IRQ | System | Makes an entry into the IRQ polling table |
| $2B | F$IOQu | System | Puts an entry into an I/O queue |
| $2C | F$AProc | System | Inserts a process into the queue for execution |
| $2D | F$NProc | System | Starts the next process |
| $2E | F$VModul | System | Validates a module |
| $2F | F$Find64 | System | Finds a 64-byte memory block |
| $30 | F$All64 | System | Allocates a 64-byte memory block |
| $31 | F$Ret64 | System | Returns a 64-byte memory block |
| $32 | F$SSvc | System | Installs a function request |
| $33 | F$IODel | System | Deletes an I/O module |
| $34 | F$SLink | System | Performs a system link |
| $35 | F$Boot | System | Bootstrap system |
| $36 | F$BtMem | System | Bootstrap memory request |
| $37 | F$GProcP | System | Gets a process's pointer |
| $38 | F$Move | System | Moves data to a different address space |
| $39 | F$AllRAM | System | Allocates RAM blocks |
| $3A | F$AllImg | System | Allocates image RAM blocks |
| $3B | F$DelImg | System | Deallocates image RAM blocks |
| $3C | F$SetImg | System | Sets a process DAT image |
| $3D | F$FreeLB | System | Gets a free low block |
| $3E | F$FreeHB | System | Gets a free high block |
| $3F | F$AllTsk | System | Allocates a process task number |
| $40 | F$DelTsk | System | Deallocates a process task number |
| $41 | F$SetTsk | System | Sets a process's task DAT registers |
| $42 | F$ResTsk | System | Reserves a task number |
| $43 | F$RelTsk | System | Releases a task number |
| $44 | F$DATLog | System | Converts a DAT block offset to a logical address |
| $45 | F$DATTmp | System | Make temporary DAT image (obsolete) |
| $46 | F$LDAXY | System | Loads A[X,[Y]] |
| $47 | F$LDAXYP | System | Loads A[X+,[Y]] |
| $48 | F$LDDDXY | System | Loads D[D+X,[Y]] |
| $49 | F$LDABX | System | Loads Register A from 0,X in Task B |
| $4A | F$STABX | System | Stores Register A at 0,X in Task B |
| $4B | F$AllPrc | System | Allocates a process descriptor |
| $4C | F$DelPrc | System | Deallocates a process descriptor |
| $4D | F$ELink | System | Links modules using a module directory entry |
| $4E | F$FModul | System | Finds a module directory entry |
| $4F | F$MapBlk | System | Maps the specified blocks |
| $50 | F$ClrBlk | System | Clears the specified block of memory |
| $51 | F$DelRAM | System | Deallocates RAM blocks |
| $52 | F$GCMDir | System | Compacts module directory entries |
| $53 | F$AllHRAM | System | Allocates high RAM |
| $54 | F$ReBoot | System | Reboot machine (reload OS9Boot) or drop to RS-DOS |
| $55 | F$CRCMod | User | New system call to change module CRC calcs on/off |
| $56 | F$XTime | System | Gets extended time packet from RTC (fractions of a second) |
| $57 | F$VBlock | System | Verify modules in a block of memory, add to module directory |
| $70 | F$RegDmp | User | User register dump system call for NitrOS-9 Level 2 |
| $71 | F$NVRAM | User | Read/Write RTC non-volatile RAM (NVRAM) |
| $80 | I$Attach | I/O | Attaches to an I/O device |
| $81 | I$Detach | I/O | Detaches an I/O device |
| $82 | I$Dup | I/O | Duplicates a path |
| $83 | I$Create | I/O | Creates a new file |
| $84 | I$Open | I/O | Opens a path to an existing file |
| $85 | I$MakDir | I/O | Creates a directory file |
| $86 | I$ChgDir | I/O | Changes a working directory |
| $87 | I$Delete | I/O | Deletes a file |
| $88 | I$Seek | I/O | Positions a file pointer |
| $89 | I$Read | I/O | Reads data from a device |
| $8A | I$Write | I/O | Writes data to a device |
| $8B | I$ReadLn | I/O | Reads a line of data from a device |
| $8C | I$WritLn | I/O | Writes a data line to a device |
| $8D | I$GetStt | I/O | Gets a device's status |
| $8E | I$SetStt | I/O | Sets a device's status |
| $8F | I$Close | I/O | Closes a path |
| $90 | I$DeletX | I/O | Deletes a file from the execution directory |
Get Status System Calls
You use the Get Status system calls with the RBF manager subroutine GETSTA. The NitrOS-9 Level Two system reserves the 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 Chapter 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.
Set Status System Calls
Use the Set Status system calls with the RBF manager subroutine SETSTA. The NitrOS-9 Level Two system reserves codes 7-127 for use by Microware. You can define codes 200-255 and their parameter-passing conventions for your own use. (See the section on device drivers in Chapters 4, 5, and 6.)
Following are the Set Status functions and their codes.
