EXOS 2.1 Kernel Specification

11. EXOS Function Calls in Detail

This chapter contains details of all EXOS function calls. Many of them have been described earlier in general terms. This section concentrates on details such as register usage and error codes, and describes the function calls from the point of view of the program making the call.

Parameters are passed to EXOS calls in registers A, BC and DE, and results are passed back in the same registers. Register A returns a status code which is zero if the call was successful and a non­zero error code otherwise. All other registers (HL, IX, IY, AF', BC', DE', HL') are preserved by all EXOS calls, and also the user's paging is not disturbed. EXOS calls can be made from any address in any Z80 page, and user's stack can be in any of the four pages.


11.1 Device Name and Filename String Syntax

The open channel and create channel function calls take a string parameter. This string defines which device driver the channel is being opened to, and also specifies a unit number and filename. The syntax of the string is:

    [[device-name][["-"]unit-number]":"][file-name]

where [ ] denotes an optional part and "" delimits literal characters.

The device name can be up to 28 characters and must be entirely letters, which will be uppercased before using so case is not significant. If it is not present then EXOS will use a default device name wich can be set with a set default device name EXOS call (code 19). If the unit number is also absent (see below) then the default unit number, which can also be set with this call, will be used.

The unit­number, if present, can be seperated from the device name with a single "-" (minus) character if desired or it can immediately follow it. The unit number consists of a series of decimal digits which will be converted into a one byte value by EXOS. If the device name is specified with no unit number, then a default unit number of zero is used.

The optional filename consists of up to 28 characters which can include letters, digits and any of the special characters:

    £ $ % & ' ( ) * - . / ? [ \ ] ^ _ (Also ASCII 60h)

Letters will be uppercased before the string is used. If there is no filename then it will just be taken as the null string.

The filename and unit number will be passed through to the device driver for interpretation. However if the device driver has the DD_UNIT_COUNT field in its device descriptor set then some manipulation of the unit number will occur.

If the DD_UNIT_COUNT field is set to N then this means that the device driver only accepts unit numbers in the range [ 0.. N-1 ]. If the unit number is greater than this then it will reduced by N and the search of the device chain will continue. When another device of the same name is found the process will be repeated and if it is now within range then the device will be called with the reduced unit number. In this way several device with the same name can be supported, with the distinction being by unit number. This is not used by any built in devices but could be used by add on disk units.


11.2 Function 0 - System Reset

    Parameters :  C Reset type flags
    Results    :  A Status (always zero but flags not set)
                  Interrupts disabled

This call causes a reset of EXOS. The flags passed in register C control exactly what the reset does, as below:

b0 ... b3
must be zero
b4 - set
Forcibly de­allocate all channel RAM, and re-initialise all devices. User device will be retained.
b5 - set
As bit 4 but also re­link in all built in and extension devices, and re­initialise system extensions. User devices will be lost. Device segments are not de-allocated.
b6 - set
De­allocate all user RAM segments.
b7 - set
Cold reset. This is equivalent to switching the machine off and on again. All RAM data is lost.

Note that the status register is not set to be consistent with the status code (which is always zero anyway) and registers BC', DE' and HL' are corrupted by this EXOS call. Also a side effect of the call is that interrupts are disabled.

An automatic RESET call with flags set to 10h is done by EXOS when a warm reset occurs (see section 3.2). Also an automatic RESET call with flags set to 20h is done by EXOS when it enters a RAM loaded applications program (see section 10.6).

A RESET call (with flags set to 60h or 00h depending on the action code) must be done by a system extension when it takes control as a new applications program (see section 9.3).

After any reset call, including the implicit ones done by EXOS as described above, the warm reset address, software interrupt address and hardware interrupt service routine address will all have been set to zero by EXOS and will thus have to be re­initialised by the user.


11.3 Function 1 - Open Channel

    Parameters :  A channel number (must not be 255)
                 DE pointer to device/filename string
    Results    :  A status                         

The format of the filename string was specified above. The filename and unit numbers are passed to the device driver for interpretation and many devices will just ignore them. If the device is one which supports filenames then it will return an error code if the file specified does not already exists. Some devices require options to be selected (by special function calls) before the channel can be used. Also some devices require parameters to be specified by setting EXOS variables before a channel can be opened.

The unit number is ignored by all built in devices except the network driver. If a device name with no unit number is specified then a default of zero is used which devices could translate into their own internal default if desired.

For the open channel function to be successfully completed, the device must allocate itself a channel buffer before it returns and an error may be returned if there is insufficient RAM available.


11.4 Function 2 - Create Channel

    Parameters :  A channel number (must not be 255)
                 DE pointer to device/filename string
    Results    :  A status                         

The create function is identical to the open function except that it if the device supports filenames, then the file will be created if it doesn't exist, and an error code returned if it does. It is identical to open channel for all built in devices except the cassette driver.


11.5 Function 3 - Close Channel

    Parameters :  A channel number (must not be 255)
    Results    :  A status                          

The close function flushes any buffers and de­allocates any RAM used by the channel. Further reference to this channel number will result in an error. The device's entry point is called before the channel RAM is de­allocated.


11.6 Function 4 - Destroy Channel

    Parameters :  A channel number (must not be 255)
    Results    :  A status                          

The destroy function is identical to the close function except that on a file handling device the file is deleted. It is identical for all built in devices.


11.7 Function 5 - Read Character

    Parameters :  A channel number
    Results    :  A status
                  B character        

The read character call allows single characters to be read from a channel without the explicit use of a buffer. If no character is ready then it waits until one is ready. This call is passed directly through to the device driver.


11.8 Function 6 - Read Block

    Parameters :  A channel number
                 BC byte count
                 DE buffer address
    Results    :  A status
                 BC bytes left to read
                 DE modified buffer address               

The read block function reads a variable sized block from a channel. The block may be from to 65535 bytes in length and can cross segment boundaries. Note that the byte count returned is valid even if the status code is negative, although not if it is an error such as non­existent channel. This allows a partially successful block read to be retried from the first character which failed. This call is passed directly through to the device driver.


11.9 Function 7 - Write Character

    Parameters :  A channel number
                  B character
    Results    :  A status                                 

The write character function allows single characters to be written to a channel. This call is passed directly to the device driver.


11.10 Function 8 - Write Block

    Parameters :  A channel number
                 BC byte count
                 DE buffer address
    Results    :  A status
                 BC bytes left to write
                 DE modified buffer address               

The block write function allows a variable sized block to be written to a channel and is similar to block read. The byte count returned in BC is valid even if the status code is negative. This call is passed directly through to the device driver.


11.11 Function 9 - Channel Read Status

    Parameters :  A channel number
    Results    :  A status
                  C 00h if character is ready to be read
                    FFh if at end of file
                    01h otherwise.                             

The read channel status function call is used to allow polling of a device such as the keyboard without making the system wait until a character is ready. This call is passed directly through to the device driver.


11.12 Function 10 - Set and Read Channel Status

    Parameters :  A channel number
                  C write flags
                 DE pointer to parameter block (16 bytes)
    Results    :  A status
                  C read flags                            

This function is used to provide random access facilities and file protection on file devices such as disk or a RAM driver. The format of the parameter block is:

  Byte:  0 ... 3  -  File pointer value (32 bits)
         4 ... 7  -  File size (32 bits)
               8  -  Protection byte (yet to be defined)
         9 .. 15  -  Zero (reserved for future expansion)

The assignment of bits in the read and write flags byte is as below. The specified action is taken if the bit is set.

   Bit(s)  Write Flags              Read Flags

       b0  Set new pointer value    File pointer is valid
       b1  not used (0)             File size is valid
       b2  Set new protection byte  Protection byte is valid
 b3 .. b7  not used (0)             always zero

This allows the file pointer and/or the protection byte to be set independently, or just to be read. Not all devices need to support this function, indeed none of the built in devices support it. If a device doesn't support it then it should return a .NOFN error code.


11.13 Function 11 - Special Function

    Parameters : A channel number
                 B sub-function number
                 C unspecified parameter
                DE unspecified parameter
    Result     : A status
                 C unspecified parameter
                DE unspecified parameter 

This function call allows device specific functions to be performed on a channel. If it is not supported by a device then a .ISPEC error will be returned.

The sub­function number specified in register B determines which special function is required. Sub­function numbers should be different for all devices, unless equivalent functions are implemented. The special functions for built in devices are (see device driver specifications for details):

Video
@@DISP = 1    Display page
@@SIZE = 2    Return page size and mode
@@ADDR = 3    Return video page address
@@FONT = 4    Reset character font
Keyboard
@@FKEY = 8    Program function key
@@JOY  = 9    Read joystick directly
Network
@@FLSH = 16   Flush output buffer
@@CLR  = 17   Clear input and output buffers
Editor
@@MARG = 24   Set margins
@@CHLD = 25   Load a document
@@CHSV = 26   Save a document

All other sub­function codes from zero to 63 are reserved for use by IS/Enterprise. Codes of 64 and above can be used by user devices.


11.14 Function 16 - Read, Write or Toggle EXOS Variable

    Parameters :  B = 0 read value
                    = 1 write value
                    = 2 toggle value
                  C EXOS variable number (0..255)
                  D new value to be written (only for write)
    Results    :  A status
                  D new value of EXOS variable             

This function allows EXOS variables to be set or inspected. These variables control various functions of the system and specific devices. Note that the value is returned in D even for write and toggle. There is a list of currently defined EXOS variables in chapter 8. System extensions can implement additional EXOS variables.


11.15 Function 17 - Capture Channel

    Parameters :  A main channel number
                  C secondary channel number
                    (0FFh to cancel capture)
    Results    :  A status              

The capture channel function causes subsequent read function calls (read character, read block and read status) to the main channel, to read data instead from the secondary channel. When the function call is made, the main channel must exist but no check is made on the secondary channel existing.

The capture applies to all subsequent input from the main channel number until either the secondary channel is closed or gives any error (such as end of file) or the main channel is captured from somewhere else. The effect of the capture can be cancelled by giving a secondary channel number of 0FFh which is not a valid channel number.


11.16 Function 18 - Re­direct Channel

    Parameters :  A main channel number
                  C secondary channel number
                    (0FFh to cancel redirection)
    Results    :  A status             

The re­direct function causes subsequent output sent to the main channel with write character or write block function call, to be sent to the secondary channel instead. The redirection lasts until the secondary channel is closed or returns an error, or the main channel is redirected somewhere else. A secondary channel number of 0FFh will cancel any redirection of the main channel.


11.17 Function 19 - Set Default Device Name

    Parameters : DE device name pointer (no colon)
                  C device type 0 = non file handling
                                1 = file handling
    Results    :  A status                        

The set default device name function specifies a device name and (optionally) a unit number which will be used in subsequent open channel or create channel function calls if no device name is specified by the user. Initially the default name will be "TAPE-1" but will be set to "DISK-1" if a disk device is linked in. The specified device name and unit number are checked for legality (ie. no invalid charcters) but not for existence in the device chain.

If a string with only a unit number, such as "45", is specified then this will set a new unit number but the default name will be unchanged. If the device name but no unit number is given, then the default unit number will be set to zero.

The device type given in register C is simply copied to the device type EXOS variable. This will be zero in the default machine because the default device is "TAPE" which is not a file handling device. If a disk unit is connected then the device type will be set to 1. This vaiable is not currently used by EXOS but can be of some use to applications programs.


11.18 Function 20 - Return System Status

    Parameters : DE pointer to parameter block (8 bytes)
    Results    :  A status code, always 0
                  B version numner (currently 20h)
                 DE unchanged                                 

This function returns the version number of the system and various parameters which describe the RAM segment usage in the system. The parameters (bytes) returned are, in order:

  1. Shared segment number (0 if no shared segment)
  2. Number of free segments
  3. Number of segments allocated to the user, excluding the page­zero segment and the shared segment (if there is one)
  4. Number of segments allocated to devices.
  5. Number of segments allocated to the system, including the shared segment (if there is one)
  6. Total number of working RAM segments
  7. Total number of non­working RAM segments.
  8. Not currently used.

11.19 Function 21 - Link Device

    Parameters : DE pointer to RAM in Z80 space containing
                    device descriptor
                 BC amount of device RAM required.
    Results    :  A status                                

The link device function causes the device descriptor pointed to by DE to be linked into the descriptor chain. The descriptor will be put at the start of the chain and any existing device with the same name will be disabled. DE must point at the TYPE field of the descriptor and the descriptor must not cross a segment boundary. Once linked in the user must ensure that the device code and descriptor are not corrupted until a reset function call with bit 5 set (to un­link user devices) has been made.

The amount of RAM requested will be allocated in the system segment. When the device is first initialised, this RAM area will be pointed to by IX and the device must remember this address since it will never be told it again, even when it is re­initialised.


11.20 Function 22 - Read EXOS Boundary

    Parameters :    none
    Results    :  A status (always zero)
                  C shared segment number. 0 If nonexistent.
                 DE EXOS boundary in shared segment (0..3FFFh)

The read EXOS boundary function returns the offset within the currently shared segment, of the lowest byte which the system is using. If there is no shared segment then DE will point to where the EXOS boundary would be if a shared segment where allocated.


11.21 Function 23 - Set User Boundary

    Parameters : DE offset of new USER boundary. (0..3FFFh)
    Result     :  A status                        

The set user boundary function allows the user to move the USER boundary within the currently shared segment. If there is no shared segment then this function call is not allowed. The boundary may not be set higher than the current EXOS boundary.


11.22 Function 24 - Allocate Segment

    Parameters :    none
    Results    :  A status
                  C segment number
                 DE EXOS boundary within this segment

The allocate segment function allows the user to obtain another 16K segment for his use. If a free segment is available then it will be allocated and status returned zero with the segment number in C and DE will be 4000h.

If there are no free segments but the user can be allocated a shared segment, then the segment number will be returned in C and DE will be the initial EXOS boundary. In this case a .SHARE error will be returned. The user boundary is initially set equal to the EXOS boundary.

If there are no free segments and there is already a shared segment then a .NOSEG error will be returned.

If this function call is made by a device driver then the segment will be marked as allocated to a device and a shared segment cannot be allocated.


11.23 Function 25 - Free Segment

    Parameters :  C segment number
    Results    :  A status        

The free segment function allows the user to free a 16K segment of RAM. The segment must be currently allocated to the user or be shared. The page zero segment cannot be freed as it was never allocated explicitly with an allocate segment call.

If this function call is made by a device driver then it must be to free a segment which was allocated to a device driver with an allocate segment call. There is no checking of which device is freeing the segment, devices are supposed to be well behaved.


11.24 Function 26 - Scan System Extensions

    Parameters : DE pointer to command string
    Results    :  A status                   

This function causes the string to be passed around all system extensions after some processing, with action code 2 (or 3 if the first word of the string is "HELP"). This allows services to be carried out by system extensions and also allows transfer to a new applications program.


11.25 Function 27 - Allocate Channel Buffer

    Parameters : DE amount of buffer which must be in one
                    segment
                 BC amount of buffer which needn't be in one
                    segment (only needed for video devices)
    Results    :  A status
                 IX points to newly allocated buffer
             PAGE-1 contains the new buffer segment.

The allocate channel buffer function is provided only for devices and may not be called by the applications program. It is used to provide a channel with a RAM buffer when it is opened. The multi segment size passed in register BC is ignored for non­video devices since they must have their buffer all in one segment. So for non­video devices BC need not be loaded before making the call.


11.26 Function 28 - Explain Error Code

    Parameters :  A error code which needs explaining
                 DE pointer to string buffer (64 bytes)
    Results    :  A status (always zero).
                 DE unchanged.                        

This function allows an EXOS error code to be converted into a short text message. System extensions are given a chance of doing the translation. All error codes generated by the EXOS kernel and the built in devices are explained by the internal ROM. If the string returned is of zero length then it is an error code which no one was willing to explain.


11.27 Function 29 - Load Module

    Parameters : DE pointer to a buffer for the module
                    header (16 bytes)
                  A channel number to load from
    Results    :  A status
                 DE unchanged
                  B if A = .ASCII : 1st character of file
                    if A = .ITYPE : module type
                    else          : undefined             

This function call was explained in the section on loading Enterprise module format files. It will load a module header and then either load the module itself, or pass it to the system extensions for loading. If the system extensions don't want it then it will be returned to the user in his buffer (pointed to by DE), for him to load.

If a module is loaded OK by EXOS or a system extension then a zero status code is returned. In this case, or if the module is successfully loaded by the user, the load module function call should be repeated to load the next module. This should continue until a .NOMOD error is returned which indicates that an end of file was read, or until a fatal error occurs.

If the first byte is not zero, or the type byte is zero then the file is not an Enterprise format file and a .ASCII error is returned with the first character in B. The user can then do what he wants with the ASCII data, but should not attempt to load another module from this file.


11.28 Function 30 - Load Relocatable Module

    Parameters :  A channel number to load from
                 DE starting address to load at
    Results    :  A status
                 DE unchanged                  

This function call can be used by the user to load user relocatable modules, with header type 2, which will be rejected by the load module call above.

The user must find the correct sized chunk of RAM to load the module into (from the size in the header). If the function call returns a zero error code then the user should call the initialisation entry point of the code loaded (if there is one) and should then call load module again to get the next module header. This is explained in more detail in section 10.2.


11.29 Function 31 - Set Time

    Parameters :  C hours   0 .. 23 (BCD)
                  D minutes 0 .. 59 (BCD)
                  E seconds 0 .. 59 (BCD)
    Results    :  A status              

This function sets the internal system clock. The parameters are checked for legality and a .ITIME error returned if they are illegal.


11.30 Function 32 - Read Time

    Parameters :    none
    Results    :  A status
                  C hours   0 .. 23 (BCD)
                  D minutes 0 .. 59 (BCD)
                  E seconds 0 .. 59 (BCD) 

This function reads the current value of the system clock. This clock is incremented every second, using the Enterprise's 1Hz interrupt. When it reaches midnight the date will automatically be incremented (see below).


11.31 Function 33 - Set Date

    Parameters :  C year    0 .. 99 (BCD)
                  D month   1 .. 12 (BCD)
                  E day     1 .. 32 (BCD)
    Results    :  A status             

This function sets the internal system date. The parameters are checked fully for legality, including the number of days in each month and leap years. The year is origined at 1980 so a year value of 4 actually represents 1984. This allows the date to go well into the future. (obsolescence built out !).


11.32 Function 34 - Read Date

    Parameters :    none
    Results    :  A status
                  C year    0 .. 99 (BCD)
                  D month   1 .. 12 (BCD)
                  E day     1 .. 31 (BCD) 

This function reads the current value of the internal system calender. This can be set by the user and will increment automatically when the system clock reaches midnight, coping correctly with the number of days in each month including leap years.



David Bouman. (dsbouma@cs.vu.nl)