General Information

All programs to be accessed by the Command String Interpreter should be written as a "large" subroutine using a RET instruction when finished or, preferably, SC 0

(QUIT) •

When a program is executed by the CSI the HL register pair will contain the address of the first character of the tokenized command string (the program name is excluded); the IX index register will contain the address of the list of delimiters used in the command string; the B register will contain the drive code that the program came from; the DE register pair will contain the starting sector number of the program on disk.

The tokenized command string is a list of the words used in the command, each word translated to upper case and filled out (or truncated) to eight characters (trailing spaces are added when necessary). The open parentheses at the beginning of an option list is considered to be a word by itself and the list is terminated by a token of a carriage return (ODH).

The list of delimiters used is merely a list of the characters that were used to separate the words in the command string. This list matches in a one-to-one relation to the tokenized command string starting with the delimiter between the program name and the first word following. When multiple characters (spaces) are used to separate two words only the first character is placed in the list of delimiters. An open parentheses is assumed to be followed by a space character even when no delimiter is actually used. The list is always terminated by a CR charcter.

For example:

>PROG NAME.TYPE:LABEL (OPT1 OPT2,OPT3

When control is passed to the program named PROG the HL and IX registers will be addressing the following character strings:

(HL): 4E414D45 20202020 54595045 20202020 'NAME 4C414245 4C202020 28202020 20202020 'LABEL 4F505431 20202020 4F50S432 20202020 'OPT1 4FSOS433 20202020 OD202020 20202020 'OPT3 (IX): 202E3A20 20202COD

. . . ^, .

TYPE

(

OPT2 ,

, , , ,

The quotes used in the tokenized list are only for documenting the trailing spaces and are not actually in the list.

Note: The list of tokens is always terminated by a CR token.

The information provided by these two registers allows the program to access all of the data and options specified in the command.

The information provided in the B and DE registers allows the program to get any program overlay segments, if used.

MACRO 125

-MACRO REFERENCE· HANUAL

9.2 Peripheral Dev1ce Drivers

The OASIS operating system contains many of the device drivers that are normally needed. For special peripherals or applications it might be desirable for you to write your own device driver.

A user written device driver should be written using the same format and protocalls as the OASIS device drivers, even when you don't plan to interface OASIS to your driver--you may want to in the future.

OASIS device drivers are written as relocatable subroutines. Each device driver has five entry point vectors, one for each major function of the driver. The sequence of these entry point vectors is as follows:

JP ST JP IN JP OUT JP INIT JP UNINIT

ST is entry point of device status subroutine IN is entry point of input byte routine

OUT is entry point of output byte routine INIT is entry point of device initialization UNINIT is entry point of device de-intialization

It is not necessary to actually use the jump instructions at these entry points but

~ach entry point vector must be three bytes in length.

Each of the five routines in a device driver is a subroutine that is called by certain system calls. These subroutine functions, requirements, and system calls are described below.

ST Accessed by system call 62. Input to this routine is the physical device number in the B register, and the

ueB

address in the IY register. The responsibility of this routine is to return the status of the device in the Z and e flags. This routine should not actually read the byte of data. If it is necessary to read the byte to determine the status then the byte should be saved in an input buffer area.

Z Set

=

no input available Z Reset

=

input available

e

Set

=

output ready

e Reset

=

output not ready

If the device is an output only device then this routine should always set the Z flag, indicating that there is no data to be read in.from the device.

IN Accessed by system call 63. Input to this routine is the physical device number in the B register, and the UCB address in the IY register. The responsibility of this routine is to return one byte of input from the device in the A register. If no byte is available from the device this routine should wait (use SC 107 for interrupt driven device or SC 79 for non-interrupt driven devices). It should be the responsibility of the calling program to test if a byte was available or not. When register A is set to zero it means that a data byte of zero was input, not that there was no byte available.

If the device driver is for an output only device then this entry point should return immediately.

- 126 - MACRO

OUT

IRIT

CHAPTER. 9: INTEIlFACIHG TO OASIS This routine (non-interrupt system) or the interrupt input routine should use system call 102 (CHARIN) for every character input to trap any escape sequence entered and to perform character translations.

Accessed by system call 64. Input to this routine is the physical device number in the B register, the UCB address in the IY register, and the character to be output in register C. This routine accepts a byte of output from register C and outputs the byte to the device. An interrupt driven device might just store the byte in its buffer and return control to the caller, allowing an interrupt service routine to actually output the byte. However, this routine should handle all error conditions relating to output to the device.

Accessed by system call 61. Input to this routine is the physical device number in the B register, and the UCB address in the IY register. The responsibility of this routine is to initialize the device driver and the device. The OASIS ATTACH command calls this entry point once when the device is attached to a logical name.

If the device is an interrupt driven device this routine would establish the interrupt vector using SC 103, initialize the I/O buffer, etc.

UNINIT Accessed by system call 68. Input to this routine is the physical device number in the B register, and the UCB address in the IY register. The responsibility of this routine is to un-intiialize the device. The OASIS ATTACH command calls this entry point once when the device is detached from a logical name.

If the device is an interrupt driven device this routine would probably make sure that the I/O buffer was empty, disable the interrupt for this routine using SC 103, etc.

When an interrupt service routine is entered the interrupts are disabled. The routine must enable the interrupts before an RETI instruction is executed. The interrupts may be enabled any time after entry to the routine but make sure that the routine is prepared for another interrupt to itself when the interrupts are enabled.

All routines, interrupt registers used and not parameters.

or otherwise, should restore the status of any specified as part of the input or output

Multi-user note: an interrupt driven device driver must take into account the fact that the owning partition may not be the active partition when the calling interrupt occurs. It may be necessary to activate the owning partition in order to service the interrupt. The system calls 84 (ONEONLY), 85 (NOTONLY), and 86 (SETPIN) may assist you in this task.

Interfacing user written device drivers to OASIS

To interface a user written device driver to the OASIS operating system you must follow these steps:

1. Decide upon a device number. OASIS references physical device

MACRO 127

-MACRO REFERENCE IWWAL

Dans le document REFERENCE ASSEMBLER (Page 132-135)