3.6.1. The Active State

This state includes all "runnable" processes, which are given time slices for execution according to their relative priority with respect to all other active processes. The scheduler uses a pseudo-round-robin scheme that gives all active processes some CPU time, even if they have a very low relative priority.

3.6.2. The Wait State

This state is entered when a process executes a F$Wait system service request. The process remains suspended until the death of any of its descendant processes, or, until it receives a signal.

3.6.3. The Sleeping State

This state is entered when a process executes a F$Sleep service request, which specifies a time interval. (a specific number of ticks) for which the process is to remain suspended. The process remains asleep until the specified time has elapsed, or until a signal is received.

3.9.1. Physical Interrupt Processing

The OS-9 kernel. ROMs contain the hardware vectors required by the 6809 MPU at addresses $FFF0 through $FFFF. These vectors each point to jump-extended-indirect instruction which vector the MPU to the actual interrupt service routine. A RAM vector table in page zero of memory contains the target addresses of the jump instructions as follows:

OS-9 initializes each of these locations after reset to point to a specific service routine in the kernel. The SWI, SWI2, and SWI3 vectors point to specific routines which in turn read the corresponding pseudo vector from the process' process descriptor and dispatch to it. This is why the F$SSWI service request to be local to a process since it only changes a pseudo vector in the process descriptor. The IRQ routine points directly to the IRQ polling system, or to it indirectly via the real-time clock device service routine. The FIRQ and NMI vectors are not normally used by OS-9 and point to RTI instructions.

A secondary vector table located at $FFE0 contains the addresses of the routines that the RAM vectors are initialized to. They may be used when it is necessary to restore the original service routines after altering the RAM vectors. On the next page are the definitions of both the actual hardware interrupt vector table, and the secondary vector table:

If it is necessary to alter the RAM vectors use the secondary vector table to exit the substitute routine. The technique of altering the IRQ pointer is usually used by the clock service routines to reduce latency time of this frequent interrupt source.

3.9.2. Logical Interrupt Polling System

In OS-9 systems, most I/O devices use IRQ-type interrupts, so OS-9 includes a sophisticated polling system that automatically identifies the source of the interrupt and dispatches to its associated user-defined service routine. 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 possible IRQ-generating device. The table size is static and defined by an initialization constant in the System Configuration Module.

The polling system is prioritized so devices having a relatively greater importance (i.e., interrupt frequency) are polled before those of lesser priority. This is accomplished by keeping the entries sorted by priority, which is a number between 0 (lowest) and 255 (highest). Each entry in the table has 6 variables:

1. POLLING ADDRESS: The address of the device's status register, which must have a bit or bits that indicate it is the source of an interrupt.

2. MASK BYTE; This byte selects one or more bits within the device status register that are interrupt request flag(s). A set bit identifies the active bit(s).

3. FLIP BYTE: This byte selects whether the bits in the device status register are true when set or true when cleared. Cleared bits indicate active when set.

4. SERVICE ROUTINE ADDRESS: The user-supplied address of the device's interrupt service routine.

5. STATIC STORAGE ADDRESS: a user-supplied pointer to the permanent storage required by the device service routine.

6. PRIORITY; The device priority number: 0 to 255. This value determines the order in which the devices in the polling table will be polled. Note: this is not the same as a process priority which is used by the execution scheduler to decide which process gets the next time slice for MPU execution.

When an IRQ interrupt occurs, the polling system is entered via the corresponding RAM interrupt vector. It starts polling the devices, using the entries in the polling table in priority order. For each entry, the status register address is loaded into accumulator A using the device address from the table. An exclusive-or operation using the flip-byte is executed, followed by a logical-and operation using the mask byte. If the result is non-zero, the device is assumed to be the cause of the interrupt.

The device's static storage address and service routine address is read from the table and executed.

The interrupt service routine should terminate with an an RTS, not an RTI instruction.

Entries can be made to the IRQ polling table by use of a special OS-9 service request called F$IRQ. This is a privileged service request that can be executed only when OS-9 is in System Mode (which is the case when device drivers are executed).

The actual code for the interrupt polling system is located in the IOMAN module. The kernel P1 and P2 modules contain the physical interrupt processing routines.

4.2.1. Type/Language Byte

The module type is coded into the four most significant bits of byte 6 of the module header. Eight types are pre-defined by convention, some of which are for OS-9's internal use only. The type codes are:

0 is not a legal type code.

The four least significant bits of byte 6 describe the language type as listed below:

The purpose of the language type is so high-level language run-time systems can verify that a module is of the correct type before execution is attempted. BASIC09, for example, may run either I-code or 6809 machine language procedures arbitrarily by checking the language type code.

4.2.2. Attribute/Revision Byte

The upper four bits of this byte are reserved for module attributes. Currently, only bit 7 is defined, and when set indicates the module is reentrant and therefore "sharable".

The lower four bits are a revision level from zero (lowest) to fifteen. If more than one module has the same name, type, language, etc., OS-9 only keeps in the module directory the module having the highest revision level. This is how ROMed modules can be replaced or patched: you load a new equivalent module having a higher revision level. Because all modules locate each other by using the LINK system call which searches the module directory by name, it always returns the latest revision of the module, wherever it may be.

NOTE: A previously linked module can not be replaced until all processes which linked to it have unlinked it (after its link count goes to zero).

6.1.1. Identification Sector

Logical sector number zero contains a description of the physical and logical characteristics of the volume. These are established by the format command program when the media is initialized, the table below gives the OS-9 mnemonic name, byte address, size, and description of each value stored in this sector.

6.1.2. Disk Allocation Map Sector

One sector (usually LSN 1) of the disk is used for the "disk allocation map" that specifies which clusters on the disk are available for allocation of file storage space The address of this sector is always assigned logical sector 1 by the format program DD.MAP specifies the number of bytes in this sector which are actually used in the map.

Each bit in the map corresponds to a cluster of sectors on the disk. The number of sectors per cluster is specified by the "DD.BIT" variable in the identification sector, and is always an integral power of two, i,e., 1, 2, 4, 8, 16, etc. There are a maximum of 4096 bits in the map, so media such as double-density double-sided floppy disks and hard disks will use a cluster size of two or more sectors. Each bit is cleared if the corresponding cluster is available for allocation, or set if the sector is already allocated, non-existent, or physically defective. The bitmap is initially created by the format utility program.

6.1.3. File Descriptor Sectors

The first sector of every file is called a "file descriptor", which contains the logical and physical description of the file.. The table below describes the contents of the descriptor.

The attribute byte contains the file permission bits. Bit 7 is set to indicate a directory file, bit 6 indicates a "sharable" file, bit 5 is public execute, bit 4 is public write, etc.

The segment list consists of up to 48 five-byte entries that have the size and address of each block of storage that comprise the file in logical order. Each entry has a three-byte logical sector number of the block, and a two-byte block size (in sectors). The entry following the last segment will be zero.

When a file is created, it initially has no data segments allocated to it. Write operations past the current end-of-file (the first write is always past the end-of-file) cause additional sectors to be allocated to the file. If the file has no segments, it is given an initial segment having the number of sectors specified by the minimum allocation entry in the device descriptor, or the number of sectors requested if greater than the minimum. Subsequent expansions of the file are also generally made in minimum allocation increments. An attempt is made to expand the last segment wherever possible rather than adding a new segment. When the file is closed, unused sectors in the last segment are truncated.

A note about disk allocation: OS-9 attempts to minimize the number of storage segments used in a file. In fact, many files will only have one segment in which case no extra read operations are needed to randomly access any byte on the file. Files can have multiple segments if the free space of the disk becomes very fragmented, or if a file is repeatedly closed, then opened and expanded at some later time. This can be avoided by writing a byte at the highest address to be used on a file before writing any other data.

6.1.4. Directory Files

Disk directories are files that have the "D" attribute set. Directory files contain an integral number of directory entries each of which can bold the name and LSN of a single regular or directory file.

Each directory entry is 32 bytes long, consisting of 29 bytes for the file name followed by a three byte logical sector number of the file's descriptor sector. The file name is left-justified in the field with the sign bit of the last character set. Unused entries have a zero byte in the first file name character position.

Every mass-storage media must have a master directory called the "root directory". The beginning logical sector number of this directory is stored in the identification sector, as previously described.

6.5.1. NAME: INIT

1. If disk writes are verified, use the F$SRqMem service request to allocate a 256 byte buffer area where a sector may be read back and verified after a write.

2. Initialize the device permanent storage. For floppy disk controller typically this consists of initializing V.NDRV to the number of drives that the controller will work with, initializing DD.TOT in the drive table to a non-zero value so that sector zero may be read or written to, and initializing V.TRAK to $FF so that the first seek will find track zero.

3. Place the IRQ service routine on the IRQ polling list by using the OS9 F$IRQ service request.

4. Initialize the device control registers (enable interrupts if necessary).

Prior to being called, the device permanent storage will be cleared (set to zero) except for V.PAGE and V.PORT which will contain the 24 bit device address. The driver should initialize each drive table appropriately for the type of disk the driver expects to be used on the corresponding drive.

6.5.2. NAME: READ

Read a sector from the disk and place it in the sector buffer (256 byte). Below are the things that the disk driver must do:

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, then go to sleep and wait for the I/O to complete (the IRQ service routine is responsible for sending a wake up signal). After awakening, test V.WAKE to see if it is clear, if not, go back to sleep.

If the disk controller can not be interrupt driven it will be necessary to perform programmed I/O.

NOTE 1: Whenever logical sector zero is read, the first part of this sector must be copied into the proper drive table (get the drive number from PD.DRV in the path descriptor). The number of bytes to copy is DD.SIZ.

NOTE 2: The drive number (PD.DRV) should be used to compute the offset to the corresponding drive table as follows:

LDA PD.DRV.Y Get drive number
LDB #DRVMEM Get size of a drive table
MUL
LEAX DRVBEG,U Get address of first table
LEAX D,X           Compute address of table N

6.5.3. NAME: WRITE

Write the sector buffer (256 bytes) to the disk. Below are the things that a disk driver must do:

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 write operation.

5. Copy V.BUSY to V.WAKE, then go to sleep and wait for the I/O to complete (the IRQ service routine is responsible for sending the wakeup signal). After awakening, test V.WAKE to see if it is clear, if it is not, then go back to sleep. If the disk controller can not be interrupt-driven, it will be necessary to perform a programmed I/O transfer.

6. If PD.VFY in the path descriptor is equal to zero, read the sector back in and verify that it was written correctly. This usually does not involve a compare of the data.

NOTE 1: If disk writes are to be verified, the INIT routine must request the buffer where the sector may be placed when it is read back in. Do not copy sector zero into the drive table when it is read back to be verified.

NOTE 2: Use the drive number (PD.DRV) to compute the offset to the corresponding drive table as shown for the READ routine.

6.5.4. NAME: GETSTA PUTSTA

These routines are wild card calls used to get (set) the device's operating parameters as specified for the OS9 I$GetStt and I$SetStt service requests.

It may be necessary to examine or change the register stack which contains the values of MPU registers at the time of the I$GetStt or I$SetStt service request. The address of the register stack may be found in PD.RGS, which is located in the path descriptor, . The following offsets may be used to access any particular value in the register stack:

6.5.5. NAME: TERM

This routine is called when a device is no longer in use in the system, which is defined to be when the link count of its device descriptor module becomes zero). The TERM routine must:

1. Wait until any pending I/O has 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 verifying disk writes, return the memory with the F$Mem service request.

6.5.6. NAME: IRQ SERVICE ROUTINE

Although this routine is not included in the device driver module branch table and is not called directly by RBFMAN, it is an key routine in interrupt-driven device drivers. Its function is to:

1. Service device interrupts.

2. When the I/O is complete, the IRQ service routine should send a wake up signal to the process whose process ID is in V.WAKE

Also clear V.WAKE as a flag to the mainline program that the IRQ has indeed occurred.

NOTE: When the IRQ service routine finishes servicing an interrupt it must clear the array and exit with an RTS instruction.

6.5.7. NAME: BOOT (Bootstrap Module)

NOTE: The BOOT module is not part of the disk driver. It is a separate module which is normally co-resident with the "OS9P2" module in the system firmware.

The bootstrap module contains one subroutine that loads the bootstrap file and some related information into memory, it uses the standard executable module format with a module type of "system" (code $C). The execution offset in the module header contains the offset to the entry point of this subroutine.

It obtains the starting sector number and size of the OS9Boot file from the identification sector (LSN 0). OS-9 is called to allocate a memory area large enough for the boot file, and then it loads the boot file into this memory area.

1. Read the identification sector (sector zero) from the disk. BOOT must pick its own buffer area. The identification sector contains the values for DD.BT (the 24 bit logical sector number of the bootstrap file), and DD.BSZ (the size of the bootstrap file in bytes). For a full description of the identification sector. See Section 6.1.2.

2. After reading the identification sector into the buffer, get the 24 bit logical sector number of the bootstrap file from DD.BT.

3. Get the size (in bytes) of the bootstrap file from DD.BSZ. The boot is contained in one logically contiguous block beginning at the logical sector specified in DD.BT and extending for (DD.BSZ/256+1) sectors.

4. Use the OS9 F$SRqMem service request to request the memory area where the boot file will be loaded into.

5. Read the boot file into this memory area.

6. Return the size of the boot file and its location.

7.5.1. NAME: INIT

1. Initialize the device static storage.

2. Place the IRQ service routine on the IRQ polling list by using the OS9 F$IRQ service request.

3. Initialize the device control registers (enable interrupts if necessary).

NOTE: Prior to being called, the device static storage will be cleared (set to zero) except for V.PAGE and V.PORT which will contain the 24 bit device address. There is no need to initialize the portion of static storage used by IOMAN and SCFMAN.

7.5.2. NAME: READ

This routine should get the next character from the input buffer. If there is no data ready, this routine should copy its process ID from V.BUSY into V.WAKE and then use the F$Sleep service request to put itself to sleep.

Later when data is received, the IRQ service routine will leave the data in a buffer, then check V.WAKE to see if any process is waiting for the device to complete I/O. If so, the IRQ service routine should send a wakeup signal to it.

NOTE: Data buffers are not automatically allocated. It any are used, they should be defined in the device's static storage area.

7.5.3. NAME: WRITE

This routine places a data byte into an output buffer and enables the device output interrupts. It the data buffer is already full, this routine should copy its process ID from V.BUSY into V.WAKE and then put itself to sleep.

Later when the IRQ service routine transmits a character and makes room for more data in the buffer, it will check V.WAKE to see if there is a process waiting for the device to complete I/O. It there is, it will send a wake up signal to that process.

NOTE: This routine must ensure that the IRQ service routine will start up when data is placed into the buffer. After an interrupt is generated the IRQ service routine will continue to transmit data until the data butter is empty, and then it will disable the device's "ready to transmit" interrupts.

NOTE: Data buffers are not automatically allocated. If any are used, they should be defined in the device's static storage.

7.5.4. NAME: GETSTA/SETSTA

This routine is a wild card call used to get (set) the device parameters specified in the I$GetStt and I$SetStt service requests. Currently all of the function codes defined by Microware for SCF-type devices are handled by IOMAN or SCFMAN. Any codes not defined by Microware will be passed to the device driver.

It may be necessary to examine or change the register packet which contains the values of the 6809 registers at the time the OS9 service request was issued. The address of the register packet may be found in PD.RGS, which is located in the path descriptor. The following offsets may be used to access any particular value in the register packet:

7.5.5. NAME. TERM

This routine is called when a device is no longer in use, defined as when its device descriptor module's link count becomes zero). It must perform the following:

1. Wait until the output buffer has been emptied (by the IRQ service routine)

2. Disable device interrupts.

3. Remove device from the IRQ polling list.

NOTE: Static storage used by device drivers is never returned to the free memory pool. Therefore, it is desirable to NEVER terminate any device that might be used again. Modules contained in the Boot file will NEVER be terminated.

7.5.6. NAME: IRQ SERVICE ROUTINE

Although this routine is not included in the device drivers branch table and not called directly from SCFMAN, it is an important routine in device drivers. The main things that it does are:

1. Service the device interrupts (receive data from device or send data to it). This routine should put its data into and get its data from buffers which are defined in the device static storage.

2. Wake up any process waiting for I/O to complete by checking to see if there is a process ID in V.WAKE (non-zero) and it so send 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.PAUS in the attached device static storage to a non-zero value. The address of the attached device static storage is in V.DEV2.

When the IRQ service routine finishes servicing an interrupt, it must clear the carry and exit with an RTS instruction.

10.1.1. F$AllBit - Set bits in an allocation bit map

This system mode service request sets bits in the allocation bit map specified by the X register.

Bit numbers range from 0..N-1, where N is the number of bits in the allocation bit map.

10.1.2. F$Chain - Load and execute a new primary module

This system call is similar to F$Fork, but it does not create a new process. It effectively "resets" the calling process' program and data memory areas and begins execution of a new primary module. Open paths are not closed or otherwise affected.

This system call is used when it is necessary to execute an entirely new program, but without the overhead of creating a new process. It is functionally similar to a F$Fork followed by an F$Exit, but with less processing overhead.

The sequence of operations taken by F$Chain is as follows:

1. The system parses the name string of the new process' "primary module" - the program that will initially be executed. Then the system module directory is searched to see if a module with the same name and type / language is already in memory. If so it is linked to. If not, the name string is used as the pathlist of a file which is to be loaded into memory. Then the first module in this file is linked to (several modules may have been loaded from a single file).

2. The process' old primary module is unlinked.

3. The data memory area is reconfigured to the size specified in the new primary module's header.

The diagram below shows how F$Chain sets up the data memory area and registers for the new module.

   +-----------------+  <--  Y          (highest address)
   !                 !
   !   Parameter     !
   !     Area        !
   !                 !
   +-----------------+  <-- X, SP
   !                 !
   !                 !
   !   Data Area     !
   !                 !
   !                 !
   +-----------------+
   !   Direct Page   !
   +-----------------+  <-- U, DP       (lowest address)

   D = parameter area size
  PC = module entry point abs. address
  CC = F=0, I=0, others undefined

Y (top of memory pointer) and U (bottom of memory pointer) will always have a values at 256-byte page boundaries. If the parent does not specify a parameter area, Y, X, and SP will be the same, and D will equal zero. The minimum overall data area size is one page (256 bytes).

The hardware stack pointer (SP) should be located somewhere in the direct page before the F$Chain service request is executed to prevent a "suicide attempt" error or an actual suicide (system crash). This will prevent a suicide from occurring in case the new module requires a smaller data area than what is currently being used. You should allow approximately 200 bytes of stack space for execution of the F$Chain service request and other system "overhead".

For more information, please see the F$Fork service request description.

10.1.3. F$CmpNam - Compare two names

Given the address and length of a string, and the address of a second string, compares them and indicates whether they match. Typically used in conjunction with "parsename".

The second name must have the sign bit (bit 7) of the last character set.

10.1.4. F$CRC - Compute CRC

This service request calculates the CRC (cyclic redundancy count) for use by compilers, assemblers, or other module generators. The CRC is calculated starting at the source address over "byte count" bytes, it is not necessary to cover an entire module in one call, since the CRC may be "accumulated" over several calls. The CRC accumulator can be any three byte memory location and must be initialized to $FFFFFF before the first F$CRC call.

The last three bytes in the module (where the three CRC bytes will be stored) are not included in the CRC generation.

The polynomial is $800063. If you perform the CRC over the module minus the stored CRC then you must exclusive-or the result with $FFFFFF to compare directly with the stored CRC. If you perform CRC over the module including the last three bytes then the result must be $800FE3.

Example C code of CRC algorithm (with 32-bit longs):

unsigned long compute_crc()
    unsigned long crc;
    unsigned char *octets;
    int len;
{
    int i;

    while (len--) {
        crc ^= (*octets++) << 16;
        for (i = 0; i < 8; i++) {
            crc <<= 1;
            if (crc & 0x1000000L)
                crc ^= 0x800063L;
        }
    }
    return crc & 0xffffffL;
}

10.1.5. F$DelBit - Deallocate in a bit map

This system mode service request is used to clear bits in the allocation bit map pointed to by X.

Bit numbers range from 0..N-1, where N is the number of bits in the allocation bit map.

10.1.6. F$Exit - Terminate the calling process

This call kills the calling process and is the only means by which a process can terminate itself. Its data memory area is deallocated, and its primary module is UNLINKed. All open paths are automatically closed.

The death of the process can be detected by the parent executing a F$Wait call, which returns to the parent the status byte passed by the child in its F$Exit call. The status byte can be an OS-9 error code the terminating process wishes to pass back to its parent process (the shell assumes this), or can be used to pass a user-defined status value. Processes to be called directly by the shell should only return an OS-9 error code or zero if no error occurred.

10.1.7. F$Fork - Create a new process

This system call creates a new process which becomes a "child" of the caller, and sets up the new process' memory and MPU registers.

The system parses the name string of the new process' "primary module" - the program that will initially be executed. Then the system module directory is searched to see if the program is already in memory. If so, the module is linked to and executed. If not, the name string is used as the pathlist of the file which is to loaded into memory. Then the first module in this file is linked to and executed (several modules may have been loaded from a single file).

The primary module's module header is used to determine the process' initial data area size. OS-9 then attempts to allocate a contiguous RAM area equal to the required data storage size, (includes the parameter passing area, which is copied from the parent process' data area). The new process' registers are set up as shown in the diagram on the next page. The execution offset given in the module header is used to set the PC to the module's entry point.

When the shell processes a command line it passes a string in the parameter area which is a copy of the parameter part (if any) of the command line. It also inserts an end-of-line character at the end of the parameter string to simplify string-oriented processing. The X register will point to the beginning of the parameter string. If the command line included the optional memory size specification (#n or #nK), the shell will pass that size as the requested memory size when executing the F$Fork.

If any of the above operations are unsuccessful, the F$Fork is aborted and the caller is returned an error.

The diagram below shows how F$Fork sets up the data memory area and registers for a newly-created process.

   +-----------------+  <--  Y          (highest address)
   !                 !
   !   Parameter     !
   !     Area        !
   !                 !
   +-----------------+  <-- X, SP
   !                 !
   !                 !
   !   Data Area     !
   !                 !
   !                 !
   +-----------------+
   !   Direct Page   !
   +-----------------+  <-- U, DP       (lowest address)

   D = parameter area size
  PC = module entry point abs. address
  CC = F=0, I=0, others undefined

Y (top of memory pointer) and U (bottom of memory pointer) will always have a values at 256-byte page boundaries. If the parent does not specify a parameter area, Y, X, and SP will be the same, and D will equal zero. The minimum overall data area size is one page (256 bytes). Shell will always pass at least an end of line character in the parameter area.

NOTE: Both the child and parent process will execute concurrently. If the parent executes a F$Wait call immediately after the fork, it will wait until the child dies before it resumes execution. Caution should be exercised when recursively calling a program that uses the F$Fork service request since another child may be created with each "incarnation". This will continue until the process table becomes full.

10.1.8. F$ICPT - Set up a signal intercept trap

This system call tells OS-9 to set a signal intercept trap, where X contains the address of the signal handler routine, and U contains the base address of the routine's storage area. After a signal trap has been set, whenever the process receives a signal, its intercept routine will be executed. A signal will abort any process which has not used the F$ICPT service request to set a signal trap, and its termination status (B register) will be the signal code. Many interactive programs will set up an intercept routine to handle keyboard abort (controlQ), and keyboard interrupt (controlC).

The intercept routine is entered asynchronously because a signal may be sent at any time (it is like an interrupt) and is passed the following:

U = Address of intercept routine local storage.

B = Signal code.

NOTE: The value of DP may not be the same as it was when the F$ICPT call was made.

Whenever a signal is received. OS-9 will pass the signal code and the base address of its data area (which was defined by a F$ICPT service request) to the signal intercept routine. The base address of the data area is selected by the user and is typically a pointer to the process' data area.

The intercept routine is activated when a signal is received, then it takes some action based upon the value of the signal code such as setting a flag in the process' data area. After the signal has been processed, the handler routine should terminate with an RTI instruction.

10.1.9. F$ID - Get process ID / user ID

Returns the caller's process ID number, which is a byte value in the range of 1 to 255, and the user ID which is a integer in the range 0 to 65535. The process ID is assigned by OS-9 and is unique to the process. The user ID 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.

10.1.10. F$Link - Link to memory module

This system call causes OS-9 to search the module directory for a module having a name, language and type as given in the parameters. If found, the address of the module's header is returned in U, and the absolute address of the module's execution entry point is returned in Y (as a convenience: this and other information can be obtained from the module header). The module's link count' is incremented whenever a F$Link references its name, thus keeping track of how many processes are using the module. If the module requested has an attribute byte indicating it is not sharable (meaning it is not reentrant) only one process may link to it at a time.

Possible errors:

(A) Module not found.

(B) Module busy (not sharable and in use).

(C) Incorrect or defective module header.

10.1.11. F$Load - Load module(s) from a file

Opens a file specified by the pathlist, reads one or more memory modules from the file into memory, then closes the file. All modules loaded are added to the system module directory, and the first module read is LINKed. The parameters returned are the same as the F$Link call and apply only to the first module loaded.

In order to be loaded, the file must have the "execute" permission and contain a module or modules that have a proper module header. The file will be loaded from the working execution directory unless a complete pathlist is given.

Possible errors: module directory full; memory full; plus errors that occur on I$Open, I$Read, I$Close and F$Link system calls.

10.1.12. F$Mem - Resize data memory area

Used to expand or contract the process' data memory area. The new size requested is rounded up to the next 256-byte page boundary. Additional memory is allocated contiguously upward (towards higher addresses), or deallocated downward from the old highest address. If D = 0, then the current upper bound and size will be returned.

This request can never return all of a process' memory, or the page in which its SP register points to.

In Level One systems, the request may return an error upon an expansion request even though adequate free memory exists. This is because the data area is always made contiguous, and memory requests by other processes may fragment free memory into smaller, scattered blocks that are not adjacent to the caller's present data area. Level Two systems do not have this restriction because of the availability of hardware for memory relocation, and because each process has its own "address space".

10.1.13. F$PErr - Print error message

This is the system's error reporting utility. It writes an error message to the output path specified. Most OS-9 systems will display:

ERROR #<decimal number>

by default. The error reporting routine is vectored and can be replaced with a more elaborate reporting module. To replace this routine use the F$SSVC service request.

10.1.14. F$PrsNam - Parse a path name

Parses the input text string for a legal OS-9 name. The name is terminated by any character that is not a legal component character. This system call is useful for processing pathlist arguments passed to new processes. Also if X was at the end of a pathlist, a bad name error will be returned and X will be moved past any space characters so that the next pathlist in a command line may be parsed.

Note that this system call processes only one name, so several calls may be needed to process a pathlist that has more than one name.

BEFORE F$PrsNam CALL:

+---+---+---+---+---+---+---+---+---+---+---+---+---
! / ! D ! 0 ! / ! F ! I ! L ! E !   !   !   !   !
+---+---+---+---+---+---+---+---+---+---+---+---+---
  ^
  X

AFTER THE F$PrsNam CALL:

+---+---+---+---+---+---+---+---+---+---+---+---+---
! / ! D ! 0 ! / ! F ! I ! L ! E !   !   !   !   !
+---+---+---+---+---+---+---+---+---+---+---+---+---
      ^       ^
      X       Y       (B) = 2

10.1.15. F$SchBit - Search bit map for a free area

This system mode service request searches the specified allocation bit map starting at the "beginning bit number" for a free block (cleared bits) of the required length.

If no block of the specified size exists, it returns with the carry set, beginning bit number and size of the largest block.

10.1.16. F$Send - Send a signal to another process

This system call sends a "signal" to the process specified. The signal code is a single byte value of 1 - 255.

If the signal's destination process is sleeping or waiting, it will be activated so that it may process the signal. The signal processing routine (intercept) will be executed if a signal trap was set up (see F$ICPT), otherwise the signal will abort the destination process, and the signal code becomes the exit status (see F$Wait). An exception is the WAKEUP signal, which activates a sleeping process but does not cause the signal intercept routine to be executed.

Some of the signal codes have meanings defined by convention:

0 = System Abort (cannot be intercepted)
1 = Wake Up Process
2 = Keyboard Abort
3 = Keyboard Interrupt
4-255 = user defined

If an attempt is made to send a signal to a process that has an unprocessed, previous signal pending, the current "send" request will be canceled and an error will be returned. An attempt can be made to re-send the signal later. It is good practice to issue a "sleep" call for a few ticks before a retry to avoid wasting MPU time.

For related information see the F$ICPT, F$Wait and F$Sleep service request descriptions.

10.1.17. F$Sleep - Put calling process to sleep

This call deactivates the calling process for a specified time, or indefinitely if X = 0. If X = 1, the effect is to have the caller give up its current time slice. The process will be activated before the full time interval if a signal is received, therefore sleeping indefinitely is a good way to wait for a signal or interrupt without wasting CPU time.

The duration of a "tick" is system dependent but is most commonly 100 milliseconds.

Due to the fact that it is not known when the F$Sleep request was made during the current tick, F$Sleep can not be used for precise timing. A sleep of one tick is effectively a "give up remaining time slice" request; the process is immediately inserted into the active process queue and will resume execution when it reaches the front of the queue. A sleep of two or more ticks causes the process to be inserted into the active process queue after N-1 ticks occur and will resume execution when it reaches the front of the queue.

10.1.18. F$SPrior - Set process priority

Changes the process' priority to the new value given. $FF is the highest possible priority, $00 is the lowest. A process can change another process' priority only if it has the same user ID.

10.1.19. F$SSVC - Install function request

This system mode service request is used to add a new function request to OS-9's user and privileged system service request tables, or to replace an old one. The Y register passes the address of a table which contains the function codes and offsets to the corresponding service request handler routines. This table has the following format:

OFFSET

          +----------------------+
 $00      !     Function Code    !  <--- First entry
          +----------------------+
 $01      ! Offset From Byte 3   !
          +--                  --+
 $02      !  To Function Handler !
          +----------------------+
 $03      !     Function Code    !  <--- Second entry
          +----------------------+
 $04      ! Offset From Byte 6   !
          +--                  --+
 $05      !  To Function Handler !
          +----------------------+
          !                      !   <--- Third entry etc.
          !     MORE ENTRIES     !
          !                      !
          !                      !
          +----------------------+
          !         $80          !   <--- End of table mark
          +----------------------+

NOTE: If the sign bit of the function code is set, only the system table will be updated. Otherwise both the system and user tables will be updated. Privileged system service requests may be called only while executing a system routine.

The service request handler routine should process the service request and return from subroutine with an RTS instruction. They may alter all MPU registers (except for SP). The U register will pass the address of the register stack to the service request handler as shown in the following diagram:

                         OFFSET   OS9Defs
                                  MNEMONIC
        +------+
U --->  !  CC  !            $0      R$CC
        +------+            $1      R$D
        !  A   !            $1      R$A
        +------+
        !  B   !            $2      R$B
        +------+
        !  DP  !            $3      R$DP
        +------+------+
        !      X      !     $4      R$X
        +-------------+
        !      Y      !     $6      R$Y
        +-------------+
        !      U      !     $8      R$U
        +-------------+
        !      PC     !     $A      R$PC
        +-------------+

Function request codes are broken into the two categories as shown below:

NOTE: These categories are defined by convention and not enforced by OS9.

Codes $25..$27, and $70..$7F will not be used by the operating system and are free for user definition.

10.1.20. F$SSWI - Set SWI vector

Sets up the interrupt vectors for SWI, SWI2 and SWI3 instructions. Each process has its own local vectors. Each F$SSWI call sets up one type of vector according to the code number passed in A.

1 = SWI 
2 = SWI2 
3 = SWI3 

When a process is created, all three vectors are initialized with the address of the OS-9 service call processor.

Software built for OS-9 uses SWI2 to call OS-9. If you reset this vector these programs will not work. If you change all three vectors, you will not be able to call OS-9 at all.

10.1.21. F$STime - Set system date and time

This service request is used to set the current system date/time and start the system real-time clock. The date and time are passed in a time packet as follows:

10.1.22. F$Time - Get system date and time

This returns the current system date and time in the form of a six byte packet (in binary). The packet is copied to the address passed in X. The packet looks like:

10.1.23. F$Unlink - Unlink a module

Tells OS-9 that the module is no longer needed by the calling process. The module's link count is decremented, and the module is destroyed and its memory deallocated when the link count equals zero. The module will not be destroyed if in use by any other process(es) because its link count will be non-zero. In Level Two systems, the module is usually switched out of the process' address space.

Device driver modules in use or certain system modules cannot he unlinked. ROMed modules can be unlinked but cannot be deleted from the module directory.

10.1.24. F$Wait - Wait for child process to die

The calling process is deactivated until a child process terminates by executing an F$Exit system call, or by receiving a signal. The child's ID number and exit status is returned to the parent. If the child died due to a signal, the exit status byte (B register) is the signal code.

If the caller has several children, the caller is activated when the first one dies, so one F$Wait system call is required to detect termination of each child.

If a child died before the F$Wait call, the caller is reactivated almost immediately. F$Wait will return an error if the caller has no children.

See the F$Exit description for more related information.

10.2.1. F$All64 - Allocate a 64 byte memory block

This system mode service request is used to dynamically allocate 64 byte blocks of memory by splitting whole pages (256 byte) into four sections. The first 64 bytes of the base page are used as a "page table", which contains the MSB of all pages in the memory structure. Passing a value of zero in the X register will cause the F$All64 service request to allocate a new base page and the first 64 byte memory block. Whenever a new page is needed, an F$SRqMem service request will automatically be executed. The first byte of each block contains the block number; routines using this service request should not alter it. Below is a diagram to show how 7 blocks might be allocated:

                   ANY 256 BYTE            ANY 256 BYTE
                   MEMORY PAGE             MEMORY PAGE
BASE PAGE  --->   +-------------+         +-------------+
                  !             !         !X            !
                  !  PAGE TABLE !         !   BLOCK 4   !
                  !  (64 bytes) !         !  (64 bytes) !
                  +-------------+         +-------------+
                  !X            !         !X            !
                  !   BLOCK 1   !         !   BLOCK 5   !
                  !  (64 bytes) !         !  (64 bytes) !
                  +-------------+         +-------------+
                  !X            !         !X            !
                  !   BLOCK 2   !         !   BLOCK 6   !
                  !  (64 bytes) !         !  (64 bytes) !
                  +-------------+         +-------------+
                  !X            !         !X            !
                  !   BLOCK 3   !         !   BLOCK 7   !
                  !  (64 bytes) !         !  (64 bytes) !
                  +-------------+         +-------------+

This is a privileged system mode service request.

10.2.2. F$AProc - Insert process in active process queue

This system mode service request inserts a process into the active process queue so that it may be scheduled for execution.

All processes already in the active process queue are aged, and the age of the specified process is set to its priority. If the process is in system state, it is inserted after any other process's also in system state, but before any process in user state. If the process is in user state, it is inserted according to its age.

This is a privileged system mode service request.

10.2.3. F$Find64 - Find a 64 byte memory block

This system mode service request will return the address of a 64 byte memory block as described in the F$All64 service request. OS-9 uses this service request to find process descriptors and path descriptors when given their number.

Block numbers range from 1..N

This is a privileged system mode service request.

10.2.4. F$IODel - Delete I/O device from system

This system mode service request is used to determine whether or not an I/O module is being used. The X register passes the address of a device descriptor module, device driver module, or file manager module. The address is used to search the device table, and if found the use count is checked to see if it is zero. If it is not zero, an error condition is returned.

This service request is used primarily by IOMAN and may be of limited or no use for other applications.

This is a privileged system mode service request.

10.2.5. F$IOQU - Enter I/O queue

This system mode service request links the calling process into the I/O queue of the specified process and performs an untimed sleep. It is assumed that routines associated with the specified process will send a wakeup signal to the calling process.

This is a privileged system mode service request.

10.2.6. F$IRQ - Add or remove device from IRQ table

This service request is used to add a device to or remove a device from the IRQ polling table. To remove a device from the table the input should be (X)=0, (U)= Addr of service routine's static storage. This service request is primarily used by device driver routines. See the text of this manual for a complete discussion of the interrupt polling system.

PACKET DEFINITIONS:

This is a privileged system mode service request.

10.2.7. F$NProc - Start next process

This system mode service request takes the next process out of the Active Process Queue and initiates its execution. If there is no process in the queue, OS-9 waits for an interrupt, and then checks the active process queue again.

This is a privileged system mode service request.

10.2.8. F$Ret64 - Deallocate a 64 byte memory block

This system mode service request deallocates a 64 byte block of memory as described in the F$All64 service request.

This is a privileged system mode service request.

10.2.9. F$SRqMem - System memory request

This system mode service request allocates a block of memory from the top of available RAM of the specified size. The size requested is rounded to the next 256 byte page boundary.

This is a privileged system mode service request.

10.2.10. F$SRtMem - Return System Memory

This system mode service request is used to deallocate a block of contiguous 256 byte pages. The U register must point to an even page boundary.

This is a privileged system mode service request.

10.2.11. F$VModul - Verify module

This system mode service request checks the module header parity and CRC bytes of an OS-9 module. If these values are valid, then the module directory is searched for a module with the same name. If a module with the same name exists, the one with the highest revision level is retained in the module directory. Ties are broken in favor of the established module.

This is a privileged system mode service request.

10.3.1. I$Attach - Attach a new device to the system

This service request is used to attach a new device to the system, or verify that it is already attached. The device's name string is used to search the system module directory to see if a device descriptor module with the same name is in memory (this is the name the device will be known by). The descriptor module will contain the name of the device's file manager, device driver and other related information. It it is found and the device is not already attached, OS-9 will link to its file manager and device driver, and then place their address' in a new device table entry. Any permanent storage needed by the device driver is allocated, and the driver's initialization routine is called (which usually initializes the hardware).

If the device has already been attached, it will not be reinitialized.

An I$Attach system call is not required to perform routine I/O. It does not "reserve" the device in question - it just prepares it for subsequent use by any process. Most devices are automatically installed, so it is used mostly when devices are dynamically installed or to verify the existence of a device.

The access mode parameter specifies which subsequent read and/or write operations will be permitted as follows:

0 = Use device capabilities.

1 = Read only.

2 = Write only.

3 = Both read and write.

10.3.2. I$ChgDir - Change working directory

Changes a process' working directory to another directory file specified by the pathlist. Depending on the access mode given, the current execution or the current data directory may be changed (but only one may be changed per call). The file specified must be a directory file, and the caller must have read permission for it (public read if not owned by the calling process).

ACCESS MODES

1 = Read

2 = Write

3 = Update (read or write)

4 = Execute

If the access mode is read, write, or update the current data directory is changed. If the access mode is execute, the current execution directory is changed.

10.3.3. I$Close - Close a path to a file/device

Terminates the I/O path specified by the path number. I/O can no longer be performed to the file/device, unless another I$Open or I$Create call is used. Devices that are non-sharable become available to other requesting processes. All OS-9 internally managed buffers and descriptors are deallocated.

Note: Because the OS9 F$Exit service request automatically closes all open paths (except the standard I/O paths), it may not he necessary to close them individually with the OS9 I$Close service request.

Standard I/O paths are not typically closed except when it is desired to change the files/devices they correspond to.

10.3.4. I$Create - Create a path to a new file

Used to create a new file on a multifile mass storage device. The pathlist is parsed, and the new file name is entered in the specified (or default working) directory. The file is given the attributes passed in the B register, which has individual bits defined as follows:

bit 0 = read permit
bit 1 = write permit
bit 2 = execute permit
bit 3 = public read permit
bit 4 = public write permit
bit 5 - public execute permit
bit 6 = sharable file

The access mode parameter passed in register A must be either "WRITE" or "UPDATE". This only affects the file until it is closed; it can be reopened later in any access mode allowed by the file attributes (see I$Open). Files open for "WRITE" may allow faster data transfer than "UPDATE", which sometimes needs to preread sectors. These access codes are defined as given below:

2 = Write only
3 = Update (read and write)

NOTE: If the execute bit (bit 2) is set, the file will be created in the working execution directory instead of the working data directory.

The path number returned by OS-9 is used to identify the file in subsequent I/O service requests until the file is closed.

No data storage is initially allocated for the file at the time it is created; this is done automatically by I$Write or explicitly by the I$SetStt call.

An error will occur if the file name already exists in the directory. I$Create calls that specify non-multiple file devices (such as printers, terminals, etc.) work correctly: the I$Create behaves the same as I$Open. Create cannot be used to make directory files (see I$MakDir).

10.3.5. I$Delete - Delete a file

This service request deletes the file specified by the pathlist. The file must have write permission attributes (public write if not the owner), and reside on a multifile mass storage device. Attempts to delete devices will result in an error.

10.3.6. I$Detach - Remove a device from the system

Removes a device from the system device table if not in use by any other process. The device driver's termination routine is called, then any permanent storage assigned to the driver is deallocated. The device driver and file manager modules associated with the device are unlinked (and may be destroyed if not in use by another process.

The I$Detach service request must be used to un-attach devices that were attached with the I$Attach service request. Both of these are used mainly by IOMAN and are of limited (or no use) to the typical user. SCFMAN also uses I$Attach/I$Detach to setup its second (echo) device.

10.3.7. I$Dup Duplicate a path

Given the number of an existing path, returns another synonymous path number for the same file or device. Shell uses this service request when it redirects I/O. Service requests using either the old or new path numbers operate on the same file or device.

NOTE: This only increments the "use count" of a path descriptor and returns the synonymous path number. The path descriptor is not copied.

10.3.8. I$GetStt - Get file device status

This system is a "wild card" call used to handle individual device parameters that:

1. are not uniform on all devices

2. are highly hardware dependent

3. need to be user-changeable

The exact operation of this call depends on the device driver an file manager associated with the path. A typical use is to determine a terminal's parameters for backspace character, delete character, echo on/off, null padding, paging, etc. It is commonly used in conjunction with the I$SetStt service request which is used to set the device operating parameters. Below are presently defined function codes for I$GetStt:

CODES 7-127 Reserved for future use.

CODES 128-255 These getstat codes and their parameter passing conventions are user definable (see the sections of this manual on writing device drivers). The function code and register stack are passed to the device driver.

Parameter Passing Conventions

The parameter passing conventions for each of these function codes are given below:

This getstat function reads the option section of the path descriptor and copies it into the 32 byte area pointed to by the X register. It is typically used to determine the current settings for echo, auto line feed, etc. For a complete description of the status packet, please see the section of this manual on path descriptors.

10.3.9. I$MakDir - Make a new directory

I$MakDir is the only way a new directory file can be created. It will create and initialize a new directory as specified by the pathlist. The new directory file contains no entries, except for an entry for itself (".") and its parent directory ("..")

The caller is made the owner of the directory. I$MakDir does not return a path number because directory files are not "opened" by this request (use I$Open to do so). The new directory will automatically have its "directory" bit set in the access permission attributes. The remaining attributes are specified by the byte passed in the B register, which has individual bits defined as follows:

bit 0 = read permit
bit 1 = write permit
bit 2 = execute permit
bit 3 = public read permit
bit 4 = public write permit
bit 5 - public execute permit
bit 6 = sharable file
bit 7 = (don't care)

10.3.10. I$Open - Open a path to a file or device

Opens a path to an existing file or device as specified by the pathlist. A path number is returned which is used in subsequent service requests to identify the file.

The access mode parameter specifies which subsequent read and/or write operation are permitted as follows:

1 = read mode
2 = write mode
3 = update mode (both read and write)

Update mode can be slightly slower because pre-reading of sectors may be required for random access of bytes within sectors. The access mode must conform to the access permission attributes associated with the file or device (see I$Create). Only the owner may access a file unless the appropriate "public permit" bits are set.

Files can be opened by several processes (users) simultaneously. Devices have an attribute that specifies whether or not they are sharable on an individual basis.

NOTES:

If the execution bit is set in the access mode, OS-9 will begin searching for the file in the working execution directory (unless the pathlist begins with a slash).

The sharable bit (bit 6) in the access mode can not lock other users out of file in OS-9 Level I. It is present only for upward compatibility with OS-9 Level II.

Directory files may be read or written if the D bit (bit 7) is set in the access mode.

10.3.11. I$Read - Read data from a file or device

Reads a specified number of bytes from the path number given. The path must previously have been opened in READ or UPDATE mode. The data is returned exactly as read from the file/device without additional processing or editing such as backspace, line delete, end-of-file, etc.

After all data in a file has been read, the next I$Read service request will return an end of file error.

NOTES:

The keyboard abort, keyboard interrupt, and end-of-file characters may be filtered out of the input data on SCFMAN-type devices unless the corresponding entries in the path descriptor have been set to zero. It may be desirable to modify the device descriptor so that these values in the path descriptor are initialized to zero when the path is opened.

The number of bytes requested will be read unless:

A. An end-of-file occurs
B. An end-of-record occurs (SCFMAN only)
C. An error condition occurs.

10.3.12. I$ReadLn - Read a text line with editing

This system call is the same as I$Read except it reads data from the input file or device until a carriage return character is encountered or until the maximum byte count specified is reached, and that line editing will occur on SCFMAN-type devices. Line editing refers to backspace, line delete, echo automatic line feed, etc.

SCFMAN requires that the last byte entered be an end-of-record character (normally carriage return). If more data is entered than the maximum specified, it will not be accepted and a PD.OVF character (normally bell) will be echoed.

After all data in the file has been read, the next I$ReadLn service request will return an end of file error.

NOTE: For more information on line editing, see 7.1.

10.3.13. I$Seek - Reposition the logical file pointer

This system call repositions the path's "file pointer"; which is the 32-bit address of the next byte in the file to be read from or written to.

A seek may be performed to any value even if the file is not large enough. Subsequent WRITEs will automatically expand the file to the required size (if possible), but READs will return an end-of-file condition. Note that a SEEK to address zero is the same as a "rewind" operation.

Seeks to non-random access devices are usually ignored and return without error.

10.3.14. I$SetStt - Set file/device status

This system is a "wild card" call used to handle individual device parameters that:

1. are not uniform on all devices

2. are highly hardware dependent

3. need to be user-changeable

The exact operation of this call depends on the device driver and file manager associated with the path. A typical use is to set a terminal's parameters for backspace character, delete character, echo on/off, null padding, paging, etc. It is commonly used in conjunction with the I$GetStt service request which is used to read the device operating parameters. Below are presently defined function codes:

Codes 128 through 255 their parameter passing conventions are user definable (see the sections of this manual on writing device drivers). The function code and register stack are passed to the device driver.

This setstat function writes the option section of the path descriptor from the 32 byte status packet pointed to by the X register. It is typically used to set the device operating parameters, such as echo, auto line feed, etc.

This setstat function is used to change the file's size.

Home disk head to track zero. Used for formatting and for error recovery.

This code causes a format track (most floppy disks) operation to occur. For hard disks or floppy disks with a "format entire disk" command, this command should format the entire media only when the track number equals zero.

Inhibits the reading of identification sector (LSN 0) to DD.xxx variables (that define disk formats) so non-standard disks may be read.

10.3.15. I$Write - Write data to file or device

I$Write outputs one or more bytes to a file or device associated with the path number specified. The path must have been OPENed or CREATEd in the WRITE or UPDATE access modes.

Data is written to the file or device without processing or editing. If data is written past the present end-of-file, the file is automatically expanded.

10.3.16. I$WritLn - Write line of text with editing

This system call is similar to I$Write except it writes data until a carriage return character is encountered. Line editing is also activated for character-oriented devices such as terminals, printers, etc. The line editing refers to auto line feed, null padding at end of line, etc.

For more information about line editing, see section 7.1.