The NitrOS-9 Project Old Wiki

OS-9/6809 compatible operating system for Tandy CoCo and Dragon

Brought to you by: aaronwolfe, boisy, tlindner, tormod

System_Calls

System Calls

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:

[F$Alarm]
$1E
Color Computer 3 Alarm Call

[F$AllBit]
$13
Sets bits in an allocation bit map

[F$Chain]
$05
Chains a process to a new module

[F$CmpNam]
$11
Compares two names

[F$CpyMem]
$1B
Copies external memory

[F$CRC]
$17
Generates a cyclic redundancy check

[F$CRCMod]
$55
New system call to change module CRC calcs on/off (krnp2)

[F$Debug]
$23
Drop the system into the debugger (krnp2)

[F$DelBit]
$14
Deallocates bits in an allocation bit map

[F$Exit]
$06
Terminates a process

[F$Fork]
$03
Starts a new process

[F$GBlkMp]
$19
Gets a copy of a system block map

[F$GModDr]
$1A
Gets a copy of the module directory

[F$GPrDsc]
$18
Gets a copy of a process descriptor

[F$Icpt]
$09
Sets a signal intercept trap

[F$ID]
$0C
Returns a process ID

[F$Link]
$00
Links to a memory module

[F$Load]
$01
Loads a module from mass storage

[F$Mem]
$07
Changes a process's data area size

[F$NMLink]
$21
Links to a module; does not map the module into the user's address space

[F$NMLoad]
$22
Loads a module but does not map it into the user's address space

[F$PErr]
$0F
Prints an error message

[F$PrsNam]
$10
Parses a pathlist name

[F$SchBit]
$12
Searches a bit map

[F$Send]
$08
Sends a signal to a process

[F$Sleep]
$0A
Suspends a process

[F$SPrior]
$0D
Sets a process's priority

[F$SSpd]
$0B
Suspends a process

[F$SSWI]
$0E
Sets a software interrupt vector

[F$STime]
$16
Sets the system time

[F$SUser]
$1C
Sets the user ID number

[F$TimAlm]
$26
CoCo individual process alarm call

[F$Time]
$15
Returns the current time

[F$TPS]
$25
Return the system's ticks per second

[F$Unlink]
$02
Unlinks a module

[F$Unload]
$1D
Unlinks a module by name

[F$Wait]
$04
Waits for a signal

I/O System Calls Quick Reference

[I$Attach]
$80
Attaches to an I/O device

[I$ChgDir]
$86
Changes a working directory

[I$Close]
$8F
Closes a path

[I$Create]
$83
Creates a new file

[I$Delete]
$87
Deletes a file

[I$DeletX]
$90
Deletes a file from the execution directory

[I$Detach]
$81
Detaches an I/O device

[I$Dup]
$82
Duplicates a path

[I$GetStt]
$8D
Gets a device's status

[I$MakDir]
$85
Creates a directory file

[I$Open]
$84
Opens a path to an existing file

[I$Read]
$89
Reads data from a device

[I$ReadLn]
$8B
Reads a line of data from a device

[I$Seek]
$88
Positions a file pointer

[I$SetStt]
$8E
Sets a device's status

[I$Write]
$8A
Writes data to a device

[I$WritLn]
$8C
Writes a data line to a device

System Mode Calls Quick Reference

Following is a summary of the System Mode Calls referenced in this chapter:

[F$All64]
$30
Allocates a 64-byte memory block

[F$AllHRAM]
$53
Allocates high RAM

[F$AllImg]
$3A
Allocates image RAM blocks

[F$AllPrc]
$4B
Allocates a process descriptor

[F$AllRAM]
$39
Allocates RAM blocks

[F$AllTsk]
$3F
Allocates a process task number

[F$AProc]
$2C
Inserts a process into the queue for execution

[F$Boot]
$35
Bootstrap system

[F$BtMem]
$36
Bootstrap memory request

[F$ClrBlk]
$50
Clears the specified block of memory

[F$DATLog]
$44
Converts a DAT block offset to a logical address

[F$DATTmp]
$45
Make temporary DAT image (obsolete)

[F$DelImg]
$3B
Deallocates image RAM blocks

[F$DelPrc]
$4C
Deallocates a process descriptor

[F$DelRAM]
$51
Deallocates RAM blocks

[F$DelTsk]
$40
Deallocates a process task number

[F$ELink]
$4D
Links modules using a module directory entry

[F$FModul]
$4E
Finds a module directory entry

[F$Find64]
$2F
Finds a 64-byte memory block

[F$FreeHB]
$3E
Gets a free high block

[F$FreeLB]
$3D
Gets a free low block

[F$GCMDir]
$52
Compacts module directory entries

[F$GProcP]
$37
Gets a process's pointer

[F$IODel]
$33
Deletes an I/O module

[F$IOQu]
$2B
Puts an entry into an I/O queue

[F$IRQ]
$2A
Makes an entry into the IRQ polling table

[F$LDABX]
$49
Loads Register A from 0,X in Task B

[F$LDAXY]
$46
[Loads A[X,]Y]

[F$LDAXYP]
$47
[Loads A[X+,]Y]

[F$LDDDXY]
$48
[Loads D[D+X,]Y]

[F$MapBlk]
$4F
Maps the specified blocks

[F$Move]
$38
Moves data to a different address space

[F$NProc]
$2D
Starts the next process

[F$ReBoot]
$54
Reboot machine (reload OS9Boot) or drop to RS-DOS

[F$RelTsk]
$43
Releases a task number

[F$ResTsk]
$42
Reserves a task number

[F$Ret64]
$31
Returns a 64-byte memory block

[F$SetImg]
$3C
Sets a process DAT image

[F$SetTsk]
$41
Sets a process's task DAT registers

[F$SLink]
$34
Performs a system link

[F$SRqMem]
$28
Performs a system memory request

[F$SRtMem]
$29
Performs a system memory return

[F$SSvc]
$32
Installs a function request

[F$STABX]
$4A
Stores Register A at 0,X in Task B

[F$VIRQ]
$27
Makes an entry in a virtual IRQ polling table

[F$VBlock]
$57
Verify modules in a block of memory, add to module directory (krn)

[F$VModul]
$2E
Validates a module

[F$XTime]
$56
Get extended time packet from RTC (fractions of a second)

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.

$00
SS.Opt
Read path descriptor options

$01
SS.Ready
Check for device ready

$02
SS.Size
Read file size

$05
SS.Pos
Get file current position

$06
SS.EOF
Test for end of file

$07
SS.Link
Link to status routines — No implementation found

$08
SS.ULink
Unlink status routines — No implementation found

$09
SS.Feed
Issue form feed — No implementation found

$0B
SS.SPT
Set DD.TKS to given value — No implementation found

$0E
SS.DevNm
Return device name

$0F
SS.FD
Return file descriptor

$12
SS.DStat
Return display status

$12
SS.VarSect
Variable sector size

$13
SS.Joy
Return joystick value

$14
SS.BlkRd
Block read

$15
SS.BlkWr
Block write

$16
SS.Reten
Retension cycle

$17
SS.WFM
Write file mark

$18
SS.RFM
Read past file mark

$19
SS.ELog
Read error log

$1A
SS.Sig
Send signal on data ready

$1B
SS.Relea
Release device

$1C
SS.AlfaS
Return alfa display status

$1C
SS.Attr
[To serve 68K/RBF/SetStat only, thru NET

$1D
[SS.Break Get Status|SS.Break
Send break signal out ACIA

$1E
SS.RsBit
Reserve bitmap sector

$20
SS.FDInf
[To serve 68K/RBF/GetStat only, thru NET

$20
[SS.DirEnt Get Status|SS.DirEnt
Reserve bitmap sector

$24
SS.SetMF
Reserve $24 for Gimix G68 (Flex compatibility?)

$25
SS.Cursr
Cursor information

$26
SS.ScSiz
Return screen size

$26
SS.DSize
Return disk size

$27
SS.KySns
GetStat/SetStat for CoCo keyboard

$28
SS.ComSt
GetStat/SetStat for baud/parity

$29
SS.Open
SetStat to tell driver a path was opened

$2A
SS.Close
SetStat to tell driver a path was closed

$2B
SS.HngUp
SetStat to tell driver to hangup phone

$2C
SS.FSig
New signal for temp locked files

$80
SS.AAGBf
SetStat to allocate additional graphic buffer

$80
SS.DRead
SDisk3 direct sector read

$80
SS.DWrit
SDisk3 direct sector write

$81
SS.SLGBf
SetStat to select a different graphic buffer

$81
SS.UnFrz
SDisk3 unfreeze DD info

$82
SS.Mount
Network 4 Mount SetStat

$82
SS.MOFF
SDisk3 fast motor off call

$83
SS.RdNet
Read Raw Sector from Network 4 Omnidrive

$83
SS.MoTim
SDisk3 set motor shut off time

$84
SS.MpGPB
SetStat to request a get/put buffer be mapped in workspace

$84
SS.SDRD
SDisk3 system direct read

$84
SS.SDWRT
SDisk3 system direct write

$85
SS.Slots
Network 4 slots GetStat

$85
SS.Sleep
SDisk3 (DMC ONLY) enable/disable F$Sleep calls in read/write 1773 I/O

$86
SS.WnSet
Set up high level windowing information

$86
SS.DrvCh
SDisk3 (DMC ONLY) set drive number to cache, or return drive number being cached

$87
SS.MnSel
Request high level menu handler determine next event

$88
SS.SBar
SetStat to set position block on window scroll bars

$89
SS.Mouse
Return mouse information packet

$8A
SS.MsSig
SetStat to tell driver to send signal on mouse event

$8B
SS.AScrn
Allocate a screen for application poking

$8C
SS.DScrn
Display a screen allocated by SS.AScrn

$8D
SS.FScrn
Free a screen allocated by SS.AScrn

$8E
SS.PScrn
Polymorph screen into different screen type

$8F
SS.ScInf
Get current screen info for direct writes

$91
SS.Palet
Return palette information

$92
SS.Montr
Get and set monitor type

$93
SS.ScTyp
Get screen type information

$94
SS.GIP
Global input parameters

$95
SS.UMBar
Update menu bar

$96
SS.FBRgs
Return color registers

$97
SS.DfPal
Set/return default palette registers

$98
SS.Tone
Generate a tone using 6 bit sound

$99
SS.GIP2
Global input parameters #2

$99
SS.CDSta
SS.CDSta

$9A
SS.AnPal
Animate palettes

$9A
SS.CDSig
SS.CDSig

$9B
SS.FndBf
Find named buffer

$9B
SS.CDRel
SS.CDRel

$A0
SS.Fill
Preload SCF device input buffer

$A1
SS.Hist
Enable command-line history

$B0
SS.ECC
ECC corrected data error enable/disable

$B0
SS.VCtr
Return FS2 total VIRQ counter

$B1
SS.VSig
Return FS2 number of signals sent

$B1
SS.FClr
Set/clear FS2 VIRQ

$C7
SS.FSet
Set FS2+ VIRQ

$C8
SS.KSet
Set KQ3 VIRQ

$C9
SS.KClr
Clear KQ3 VIRQ

$CA
SS.ARAM
Allocate RAM blocks

$CB
SS.DRAM
Deallocate RAM blocks

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.

$00
SS.Opt
Set path descriptor options

$01
SS.Ready
Check for device ready

$02
SS.Size
Read file size

$03
SS.Reset
Device restore

$04
SS.WTrk
Device write track

$05
SS.Pos
Get file current position

$06
SS.EOF
Test for end of file

$07
SS.Link
Link to status routines

$08
SS.ULink
Unlink status routines

$09
SS.Feed
Issue form feed

$0A
SS.Frz
Freeze DD. information