The Write request, like Read, must be capable of recording pure

binary data without alteration. The routines for Read and Write

are almost identical with the exception that Write uses the

device driver's output routine instead of the input routine. The

RBF manager and similar random access devices that use fixed

length records (sectors) must often preread a sector before writ

ing it, unless they are writing the entire sector. In OS-9, writing

past the end of file on a device expands the file with new data.

ReadLn differs from Read in two respects. First, ReadLn termi

nates when the first end-of-line (carriage return) is encountered.

ReadLn performs any input editing that is appropriate for the

device. In the case of SCF, editing involves handling functions

such as backspace, line deletion, and the removal of the high

order bit from characters.

WriteLn is the counterpart of ReadLn. It calls the device driver

to transfer data up to and including the first (if any) carriage

return encountered. Appropriate output editing can also be per

formed. For example, SCF outputs a line feed, a carriage return

character, and nulls (if appropriate for the device). It also pauses

at the end of a screen page.

The GetStat (get status) and PutStat (put status) system calls

are wildcard calls designed to provide a method of accessing fea

tures of a device (or file manager) that are not generally device

independent. The file manager can perform specific functions

such as setting the size of a file to a given value. Pass unknown

status calls to the driver to provide further means of device inde

pendence. For example, a PutStat call to format a disk track

might behave differently on different types of disk controllers.

4-6

OS-9's Unified Input/Output System l 4

Close is responsible for ensuring that any output to a device is

completed. (If necessary, Close writes out the last buffer.) It

releases any buffer space allocated in an Open or Create. Close

does not execute the device driver's terminate routine, but can

do specific end-of-file processing if you want it to, such as writ

ing end-of-file records on disks, or form feeds on printers.

Strictly speaking, device drivers must conform to the general for

mat presented in this manual. The I/O Manager is slightly dif

ferent because it only uses the Init and Terminate entry points.

Other entry points need only be compatible with the file man

ager for which the driver is written. For example, the Read entry

point of an SCF driver is expected to return one byte from the

device. The Read entry point of an RBF driver, on the other

hand, expects Read to return an entire sector.

The following code is part of an SCF file manager. The code

shows how a file manager might call a driver.

IOEXEC

Execute Device's Read/Write Routine

Passed: (A) = Output character (write)

(X) = Device Table entry ptr

(Y) = Path Descriptor pointer

(U) = Offset of routine (D$Read,

D$Write)

Returns: (A) = Input char (read)

(B) = Error code, CC set if error

Destroys B,CC

IOEXEC pshs a,x,y,u save registers

ldu V$STAT,x get static storage for driver

ldx V$DRIV,x get driver module address

ldd M$EXEC,x and offset of execution entries

addd 5,s offset by read/write

leax d,x absolute entry address

lda ,s+ restore char (for write)

jsr O,x execute driver read/write

puts x,y,u,pc return (A)=char, (B)=error

emod Module CRC

Size equ * size of sequential file manager

The device driver modules are subroutine packages that perform

basic, low-level I/O transfers to or from a specific type of I/O

device hardware controller. These modules are re-entrant. So,

one copy of the module can concurrently run several devices that

use identical I/O controllers.

Device driver modules use a standard module header, in which

the module type is specified as code $Ex (device driver). The exe

cution offset address in the module header points to a branch

table that has a minimum of six 3-byte entries.

Each entry is typically an LBRA to the corresponding subrou

tine. The file managers call specific routines in the device driver

through this table, passing a pointer to a path descriptor and

passing the hardware control register address in the 6809 regis

ters. The branch table looks like this:

4-8

OS-9's Unified Input/Output System / 4

Code Meaning

+ $00 Device initialization routine

+ $03 Read from device

+ $06 Write to device

+ $09 Get device status

+ $OC Set device status

+ $OF Device termination routine

Chapters 5 and 6.)

$00

Parity

4-10

CRC

Device drivers often must wait for hardware to complete a task

or for a user to enter data. Such a wait situation occurs if an

SCF device driver receives a Read but there is no data is avail

able, or if it receives a Write and no buffer space is available.

OS-9 drivers that encounter this situation should suspend the

current process (via F$Sleep). In this way the driver allows other

processes to continue using CPU time.

The most efficient way for a driver to awaken itself and resume

processing data is by using interrupt requests (IRAs). It is possi

ble for the driver to sleep for a number of system clock ticks and

then check the device or buffer for a ready signal. The drawbacks

to this technique are:

0 It requires the system clock to always remain active.

It might require a large number of ticks (perhaps 20) for

the device to become ready. Such a case leaves you with

a dilemma. If you make the program sleep for two ticks,

the system wastes CPU time while checking for device

ready. If the driver sleeps 20 ticks, it does not have a

good response time.

An interrupt system allows the hardware to report to the CPU

and the device drivers when the device is finished with an opera

tion. Using interrupts to its advantage, a device driver can set

up interrupt handling to occur when a character is sent or

received or when a disk operation is complete. There is a built-in

polling facility for pausing and awakening processes. Here is a

technique for handling interrupts in a device driver:

1. Use the Init routine to place the driver interrupt service call

(IRQSVC) routine in the IRQ polling sequence via an F$IRQ

system call:

ldd V.Port,u get addre55 to poll

leax IRQPOLL,pcr point to IRQ packet

leay IRQSERVC,pcr point to IRQ routine

OS9 F$IRQ add dev to poll Sequence

bc5 Error abnormal exit if error

2. Ensure that driver programs waiting for their hardware, call

the sleep routine. The sleep routine copies V.Busy to

V.Wake. Then, it goes to sleep for some period of time.

3. When the driver program wakes up, have it check to see

whether it was awakened by an interrupt or by a signal sent

from some other process.

Usually, the driver performs this check by reading the

V.Wake storage byte. The V.Busy byte is maintained by the

file manager to be used as the process ID of the process

using the driver. When V.Busy is copied into V.Wake, then

V.Wake becomes a flag byte and an information byte. A non

zero Wake byte indicates that there is a process awaiting an

interrupt. The value in the Wake byte indicates the process

to be awakened by sending a wakeup signal as shown in the

following code:

Note that the code labeled "if signal test" is only necessary

if the driver wishes to return to the caller if a signal is sent

without waiting for the device to finish. Also note that IRQs

and FIRQs must be masked between the time a command is

given to the device and the moving of V.Busy and V .Wake . If

they are not masked, it is possible for the device IRQ to

occur and the IRQSERVC routine to become confused as to

whether it is sending a wakeup signal or not.

OS-9's Unified Input/Output System / 4

4. When the device issues an interrupt, 4S-9 calls the routine

at the address given in F$IRQ with the interrupts masked.

Make the routine as short as possible, and have it return

with an RTS instruction. IRQSERVC can verify that an

interrupt has occurred for the device. It needs to clear the

interrupt to retrieve any data in the device. Then the

V.Wake byte communicates with the main driver module. If

V.Wake is non-zero, clear it to indicate a true device inter

rupt and use its contents as the process ID for an F$Send

system call. The F$Send call sends a wakeup signal to the

process. Here is an example:

The Suspend State allows the elimination of the F$Send system

call during interrupt handling. Because the process is already in

the active queue, it need not be moved from one queue to

another. The device driver IRQSERVC routine can now wake up

the suspended main driver by clearing the process status byte

suspend bit in the process state. Following are sample routines

for the Sleep and IRQSERVC calls:

Ida D.Proc get proce55 ptr

5ta V.Wake,u prep for re-awakening

bra CmdSO enter 5u5pend loop

Cmd30 ldx D.Proc get ptr to proce55 desc

4-13

OS-9 Technical Reference

Ida P$State,x get state flag

ora `Suspend put proc in suspend state

sta P$State,x save it in proc desc

andcc #^IntMasks unmask interrupts

ldx #1 give up time slice

OS9 F$Sleep suspend (in active queue)

Cmd50 orcc #IntMasks mask interrupts while

changing state

ldx D.Proc get proc desc addr (if signal

test)

Ida P$Signal,x get signal (if signal test)

beg SigProc bra if signal to be handled

Ida V.Wake,u true interrupt?

bne Cmd30 bra if not

andcc #^IntMasks assure interrupts unmasked

Note that D.Proc is a pointer to the process descriptor of the cur

rent process. Process descriptors are always allocated on 256

byte page boundaries. Thus, having the high order byte of the

address is adequate to locate the descriptor. D.Proc is put in

V.Wake as a dual value. In one instance, it is a flag byte indi

cating that a process is indeed suspended. In the other instance,

it is a pointer to the process descriptor which enables the

IRQSERVC routine to clear the suspend bit. It is necessary to

have the interrupts masked from the time the device is enabled

until the suspend bit has been set. Making the interrupts

ensure that the IRQSERVC routine does not think it has cleared

the suspend bit before it is even set. If this happens, when the

bit is set the process might go into permanent suspension. The

IRQSERVC routine sample follows:

ldy V.Port,u get dev addr

tst V.Wake,u is process awaiting

IRQ?

beg IRQSVCER no exit

clear device interrupt

exit if IRQ not from this device

Ida V.Wake,u get process ptr

clrb

stb V.Wake,u clear proc waiting flag

tfr d,x get process descriptor ptr

Ida P$State,x get state flag

anda # Suspend clear suspend state

sta P$State,x save it

4-14

OS-9's Unified Input/Output System / 4

clrb clear carry bit

rt5

r-- IRQSVCER comb Set carry bit

rt5

Device Descriptor Modules

Device descriptor modules are small, non-executable modules.

Each one provides information that associates a specific 1/O

device with its logical name, hardware controller address(es),

device driver, file manager name, and initialization parameters.

Unlike the device drivers and file managers, which operate on

classes of devices, each device descriptor tailors its functions to a

specific device. Each device must have a device descriptor.

Device descriptor modules use a standard module header, in

which the module type is specified as code $Fx (device descrip

tor). The name of the module is the name by which the system

and user know the device (the device name given in pathlists).

The rest of the device descriptor header consists of the informa

tion in the following chart:

Relative
Address(es) Use
$09,$OA The relative address of the file manager
name string address
$OB,$OC The relative address of the device driver
name string
$OD Mode/Capabilities: D S PE PW PR E W R
(directory, single user, public execute, pub
lic write, public read, execute, write, read)
$OE,$OF,$10 The absolute physical (24-bit) address of the
device controller
$11 The number of bytes (n bytes) in the ini
tialization table
$12,$12 + n Initialization table

When OS-9 opens a path to the device, the system copies the ini-

tialization table into the option section (PD.OPT) of the path

descriptor. (See "Path Descriptors" in this chapter.)

4-15

OS-9 Technical Reference

The values in this table can be used to define the operating

parameters that are alterable by the Get Status and Set Status

system calls (I$GetStt and I$SetStt). For example, parameters

that are used when initializing terminals define which control

characters are to be used for functions such as backspace and

delete.

The initialization table can be a maximum of 32 bytes long. If

the table is fewer than 32 bytes long, OS-9 sets the remaining

values in the path descriptor to 0.

You might wish to add devices to your system. If a similar device

driver already exists, all you need to do is add the new hardware

and load another device descriptor. Device descriptors can be in

the boot module or they can be loaded into RAM from mass-stor

age files while the system is running.

The following diagram illustrates the device descriptor format:

4-16
OS-9's Unified Input/Output System l 4

Device Descriptor Format

Relative

Address

$00

$01

$02

$03

$04

$05

$06

$07

$08

$09

$OA

$OB

Use

$OD

$OE

$OF

$10

$11

$12,$12 + n

Sync Bytes ($87CD)
Module Size (bytes)
Offset to Module Name
F$ (Type) $1 (Lang)
Attributes Revision
Header Parity Check
Offset to File Manager
Name String
Offset to Device Driver
Name String
Mode Byte
Device Controller
Absolute Physical Addr.
(24 bit)
Initialization Table Size
(Initialization Table)
(Name Strings, and so on)
CRC Check Value

Check
Range

header
parity

module

CRC

1 Y,o

DN LL" ~lGL
OFF
)w U s? B E
$D7
R^TNBOLr
,MAY t f9 7
P,A

4-17
OS-9 Technical Reference

Path Descriptors

Every open path is represented by a data structure called a path _ ,
descriptor (PD). The PD contains the information the file man
agers and device drivers require to perform I/O functions.
PDs are 64 bytes long and are dynamically allocated and deallo
cated by the I/O manager as paths are opened and closed.
They are internal data structures, that are not normally refer
enced from user or applications programs. The description of PDs
is presented here mainly for those programmers who need to
write custom file managers, device drivers, or other extensions to
OS-9.
PDs have three sections. The first section, which is ten bytes
long, is the same for all file managers and device drivers. The
information in the first section is shown in the following chart.
Path Descriptor: Standard Information
Relative Size

Name Address (Bytes) Use
PD.PD $00 1 Path number
PD.MOD $01 1 Access mode: 1 = read, 2 =
write, 3 = update
PD.CNT $02 1 Number of open paths using
this PD
PD.DEV $03 2 Address of the associated
device table entry
PD.CPR $05 1 Current process ID
PD.RGS $06 2 Address of the caller's regis
ter stack
PD.BUF $08 2 Address of the 256-byte
data buffer (if used)
PDYST $OA 22 Defined by the file manager
PD.OPT $20 32 Reserved for the Getstat/
Setstat options

PD.FST is 12-byte storage reserved for and defined by each type
of file manager for file pointers, permanent variables, and so on.

4-18

OS-9's Unified Input/Output System / 4

PROPT is a 32-byte option area used for file or device operat

ing parameters that are dynamically alterable. When the path is

opened, the 1/O manager initializes these variables by copying

the initialization table that is in the device descriptor module.

User programs can change the values later, using the Get Status

and Set Status system calls.

PD.FST and PD.OPT are defined for the file manager in the

assembly-language equate file (SCFDefs for the SCF manager or

RBFDefs for the RBF manager).

4-19