,ll 6.6
,cs 10
,pl 66
,lm 0.2,0.5
,pn 1
,ju
,hd
,ce
OmegaSoft 6809 Cross Pascal Language Handbook (V1.0)
,,
,ft

,ce 1
8-##
,,
,ce
OmegaSoft 6809 Cross Pascal Language Handbook (V1.0)

,ce
WRITING DEVICE DRIVERS

This chapter is meant for those of you are very familiar at assembly language programming. Custom device drivers are useful when you have some I/O device that would fit in well with the Pascal I/O procedures and functions. Examples of possibilities include : printers, plotters, custom disk systems, modems, memory-mapped crts, and networking systems.

When designing your drivers it is recommended that you look over the drivers that came with your system for the standard devices and make sure you understand what they do and how they do it.

device-type = [interactive] [packed] device [ [ extra-alloc ] ]
              [ at address ] of (type | text) 
extra-alloc = (unsigned-integer-constant | hex-constant)
address = (unsigned-integer-constant | hex-constant)

 
        interactive         packed           device


 
    [     extra-alloc      ]      at      address


 
                         of             type

                                        text
 

Devices are the entity that represent I/O devices in a system. As is true with all types, PACKED has no meaning in this compiler and is ignored. If INTERACTIVE is specified it sets the M$INT bit in the mode byte which will affect the meaning of the EOF and EOLN flags. If the integer/hex constant in brackets is specified it is the amount of extra stack space to be allocated for the device descriptor in addition to the minimum amount required. This is normally used to reserve space for flags or buffers that are normally device and/or system dependant. If the integer/hex constant is specified following the word "at" it is the address of the device driver vector table. If this value is not specified the device type name is used preceded by a period as the address of the table.

FORMAT OF A DEVICE DESCRIPTOR :
 
byte #      0      1      2      3      4      5      6      N
        +-------------------------------------------------------+
        |P$MODE|P$ERR |    P$DRV    |    P$ELNT   |   P$ELMT    |
        +-------------------------------------------------------+
 
where :
 
P$MODE is the current mode/flags
P$ERR  is the error status of the device
P$DRV  is the address of the device driver vector table
P$ELNT is the length (in bytes) of the element
P$ELMT is the element
,pg
,ce
WRITING DEVICE DRIVERS

There may be additional bytes after the element to hold flags or buffers.

FORMAT OF THE MODE BYTE :
 
bit #       7      6      5      4      3      2      1      0
        +-------------------------------------------------------+
        |M$INT |M$EOLN|M$EOF |M$BK  |M$VAL |M$TEXT|    status   |
        +-------------------------------------------------------+
 
where :
 
M$INT  device is interactive if set
M$EOLN current element is end of line if set
M$EOF  current element is end of file if set
M$BK   break occurred on device if set
M$VAL  current element is valid if set
M$TEXT device is text device if set
 
status has four possible states 

0 - M$CLOS device is closed
1 - M$IN   device is open for input
2 - M$OUT  device is open for output
3 - M$UPDT device is open for input and output

STANDARD DEVICE DRIVERS :
 
There are five device drivers that are supplied by OmegaSoft as part of the standard runtime package. These are used to handle the standard devices of INPUT, OUTPUT, AUXOUT, and KEYBOARD, The FILE type, and a means for reporting runtime errors. If you wish to re-define the standard devices for your target system, you may modify these drivers in the runtime package.
 
.input   : INPUT
.output  : OUTPUT
.auxout  : AUXOUT
.keyboar : KEYBOARD
.disk    : DISK (FILES)
.error   : ERROR PRINTER (special format)
 
FORMAT OF DEVICE DRIVERS :
 
Each device driver (except .ERROR) has four entry points. These entry points are accessed via the device driver vector table. The table consists of a branch to the appropriate code with the following offsets :
 
Offset   Label   Destination                  

  0     O$INIT   Initialize device
  3     O$XFOT   Transfer data to device
  6     O$XFIN   Transfer data from device
  9     O$SET    Setup device
 
If any of the entry points are not used they can be replaced by an RTS. The O$INIT entry will be called when the block is entered that contains the device definition therefore the table must be at the first location for that driver. The U and X registers must not be altered by any of these device drivers.  
,ce
WRITING DEVICE DRIVERS

.ERROR has only one entry point and accumulator A is used to transfer a one byte error code. The OmegaSoft supplied driver will perform a system dependant transformation to the error code, report it in some manner, and return to the operating system. The exception is in the case of error code = 255 in which no error is reported but control is returned to the operating system.

REQUIREMENTS FOR O$INIT :
 
On entry X contains the address of the descriptor and A contains the mode (only the text, interactive, and break bits are valid, all others are zero). The Y register must not be altered by this entry point. The mode must be stored in P$MODE, P$ERR must be cleared, and the address of the device driver must be stored in P$DRV. If this is a driver for a device that has an implicit open (such as the standard devices) you must also set the appropriate status into P$MODE, set P$ELNT, and setup any extra buffers or flags as required. If the break bit (M$BK) bit is set this indicates that the compiler {$B+} option was on during the initialization of this device. If so, then normally you would clear out this bit in P$MODE and would set a flag of some sort to indicate this option is effective.
 
REQUIREMENTS FOR O$XFOT :
 
On entry X contains the address of the descriptor and A contains the writeln flag (text devices only). If A = $01 then a Writeln should be performed on the device. If A = $00 then the data in the element buffer should transferred to the device. If A = $FF then the B register contains a byte count and the U register points one byte below the data to be transferred. The byte count indicates how many bytes starting at (U + 1) are to be transferred to the device. This entry point is used for writing strings to a text device. If any errors occur during the transfer then P$ERR should be set to the appropriate value (System dependant). Note that the Y register is not valid.
 
REQUIREMENTS FOR O$XFIN :
 
On entry X contains the address of the descriptor. If M$EOF is set in P$MODE then runtime error E$EOF should be set into P$ERR and no transfer should take place. Data should be transferred from the device and stored in the element buffer. If end of file was encountered on that transfer then M$EOF should be set in P$MODE. If this is a text device and the current element is an end of line then M$EOLN should be set in P$MODE or cleared otherwise. If this is a text device and the current element is a ASCII null then a new transfer should take place (ignore nulls). M$VAL should be set in P$MODE to indicate that the contents of the element buffer are valid. If M$EOF or M$EOLN are set in P$MODE of a text device then the element buffer must be set to a space ($20). Note that the Y register is not valid.

REQUIREMENTS FOR O$SET :
 
On entry X contains the address of the descriptor and A contains the function code.
,pg 
,ce
WRITING DEVICE DRIVERS

IF THE FUNCTION CODE = 0 (ST$BRK) :
 
Then a break check should be done and bit M$BK set or cleared in P$MODE. This is ignored by most drivers. It is used in the driver for INPUT to allow the operator to stop and/or terminate display activity on the CRT or terminate a long execution program.

IF THE FUNCTION CODE = 1 (ST$OPN) :
 
Then Y points to the file name (terminated with a CR) and B is a flag byte. This entry point is normally used for multi-file devices such as a disk to access one existing file on the device. The status bits of P$MODE have already been set by the Pascal I/O handler. The driver must open the file using the file name in Y. The flags in B are available for system dependent functions. If there are any errors encountered during the open the error code should be set into P$ERR (system dependant).
 
IF THE FUNCTION CODE = 2 (ST$CRE) :
 
Then Y points to the file name (terminated with a CR) and B is a flag byte. This entry point is normally used for multi-file devices such as a disk to access one new file on the device. The status bits of P$MODE have already been set by the Pascal I/O handler. The driver must create the file using the file name in Y. The flags in B are available for system dependent functions. If there are any errors encountered during the create the error code should be set into P$ERR (system dependant).
 
IF THE FUNCTION CODE = 3 (ST$CLS) :
 
This entry point is normally used for multi-file devices such as a disk to close access to one file on the device. The status bits of P$MODE have already been set by the Pascal I/O handler. The driver must close the file. If there are any errors encountered during the close the error code should be set into P$ERR (system dependant).
 
IF THE FUNCTION CODE = 4 (ST$DEL) :
 
Then Y points to the file name (terminated with a CR). This entry point is normally used for multi-file devices such as disk to remove one file from the device directory. That status bits of P$MODE have been set to closed and must remain closed. The driver must delete the file named by Y. If there are any errors encountered during the delete the error code should be set into P$ERR (system dependant).

IF THE FUNCTION CODE = 5 (ST$SEK) :
 
Then Y points to a 32 bit byte address. This entry point is normally used for random access devices such as disk to position the "window". The M$VAL, M$EOF, and M$EOLN (if applicable) bits must be cleared after the seek to indicate that the element buffer is not valid. The driver must move the "window" to reflect the byte address pointed to by Y. The driver must not do a data transfer at this point since it does not know the direction of the next transfer. If there are any errors encountered during the seek the error code should be set into P$ERR (system dependant).
,PG
,ce
WRITING DEVICE DRIVERS

IF THE FUNCTION CODE = 6 (ST$PAG) :
 
Then a Page operation should be done on the Text device. This operation is normally only used for printers and the requirements for pagination vary from printer to printer. The two OmegaSoft standard output devices (OUTPUT and AUXOUT) both support the page operation. There is a byte in the device descriptor to mark whether or not a Writeln was the last operation performed. If it was not one will be generated to make sure the printer is at the beginning of a line. An ASCII form feed will then be sent to the device. One extra byte has been included in the device descriptor that will allow you to keep a line count in cases where the printer does not support form feeds. You could then see how many line feeds were needed to move the printer to the top of the page.

IF THE FUNCTION CODE = 7 (ST$STAT) :

Then Y points to the parameter (any type). This entry point is used for "wild-card" operations and it's function is defined by the device driver.

,ce
EXAMPLE DRIVER

The example below was written for a Gespac model GESSBS-4 card. This card has one serial port using a MC68661 (or 2661) serial chip. The example used memory map 2, which puts the base address of the 68661 at location $BF40. Both the Receiver ready and Transmitter ready interrupts are used, being fed into the IRQ input.

The device driver for input, output, and keyboard has the following features.

  1) Input to and output of the 68661 are interrupt driven, using a 128 byte buffer for each direction.
  2) Input allows backspace (cntrl-H) and line delete (cntrl-X) handling.
  3) Devstat for input and keyboard will return boolean true if there is a character available.
  4) Devstat for output will return a boolean true if the output interrupt buffer is empty.

File exdrive contains the drivers for input, output, and keyboard.

exdrive  idnt    1,7          example input,output,keyboard
*
         include /dd/pdef/xpasequ 
*
* misc
*
break    equ     $5           used for break function
qsize    equ     128          queue size
reset    equ     $10          reset 2661
mode1a   equ     $4e          eight bits, no parity
mode1b   equ     $7e          baud rate
mode2    equ     $26          receive interrupt enabled
mode3    equ     $27          same with receive and xmit interrupt enabl
readerr  equ     100          I/O error on 2661 input
back     equ     8            
del      equ     $7f          
