Chapter 6
Sequential Character
File Manager
The Sequential Character File Manager (SCFMAN) supports
devices that operate on a character-by-character basis. These
include terminals, printers, and modems.
SCF is a re-entrant subroutine package. The I/O manager calls
the SCF manager for I/0 system handling of sequential, charac
ter-oriented devices. The SCF manager includes the extensive I/O
editing functions typical of line-oriented operation, such as:
The SCF-type device driver modules are CC310, PRINTER, and
RS-232. They run the video display, printer, and serial ports
respectively. See the OS-9
Commands
manual for additional
Color Computer I/O devices.
SCF Line Editing Functions
The SCF manager supports two sets of read and write functions.
I$Read and I$Write pass data with no modification. I$ReadLn
and I$WritLn provide full line editing of device functions.
Read and Write
The Read and Write system calls to SCF-type devices correspond
to the BASIC09 GET and PUT statements. While they perform
little modification to the data they pass, they do filter out key
board interrupt, keyboard terminate, and pause character. (Edit
ing is
disabled if the corresponding character in the path
descriptor contains a zero.)
6-1
OS-9 Technical Reference
Carriage returns are not followed by line feeds or nulls automat
ically, and the high order bits are passed as sent/received.
Read Line and Write Line
The Read Line and Write Line system calls to SCF-type devices
correspond to the BASIC09 INPUT, PRINT, READ, and WRITE
statements. They provide full line editing of all functions enabled
for a particular device.
The system initializes I$ReadLn and I$WritLn functions when
you first use a particular device. (OS-9 copies the option table
from the device descriptor table associated with the specific
device.)
Later, you can alter the calls-either from assembly-language
programs (using the Get Status system call), or from the key
board (using the TMODE command). All bytes transferred by
Readln and Writln have the high order bit cleared.
SCF Definitions of the Path Descriptor
The PDYST and PD.OPT sections of the path descriptor are
reserved for and used by the SCF file manager.
The following table describes the SCF manager's use of PDYST
and PD.OPT. For your convenience, the table also includes the
other sections of the PD.
The PD.OPT section contains the values that determine the line
editing functions. It contains many device operating parameters
that can be read or written by the Set Status or Get Status sys
tem call. Any values not set by this table default to zero.
Note: You can disable most of the editing functions by set
ting the corresponding control character in the path
descriptor to zero. You can use the Set Status system call
or the TMODE command to do this. Or, you can go a step
further by setting the corresponding control character value
in the device descriptor module to zero.
To determine the default settings for a specific device, you can
inspect the device descriptor.
6-2
Sequential Character File Manager / 6
Relative Size
Name Address (Bytes) Use
Universal Section (Same for all file managers)
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 images (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 6809
register stack
PD.BUF $08 2 Address of the 256-byte data
buffer (if used)
Relative Size
Name Address (Bytes) Use
SCF Path Descriptor Definitions (PD.FST Section)
PD.DV2 $OA 2 Device table address of the sec
ond (echo) device
PD.RAW $OC 1 Edit flag:
0 = raw mode
1 = edit mode
PD.MAX $OD 2 Read Line maximum character
count
PD.MIN $OF 1 Devices are
mine
if cleared
PD .STS $10 2 Status routine module address
PD.STM $12 2 Reserved for status routine
6-3
OS-9 Technical Reference
Relative Size Use
Name Address (Bytes)
SCF Option Section Definition (PD.OPT Section)
(Copied from the device descriptor)
PD.DTP $20 1 Device class:
0=SCF
1 = RBF
2 = PIPE
3 = SBF
PD.UPC $21 1 Case:
0 = upper and lower
1 = upper only
PD.BSO $22 1 Backspace:
0 = backspace
1 = backspace, space and
backspace
PD.DLO $23 1 Delete:
0 = backspace over line
1 = carriage return, line
feed
PD.EKO $24 1 Echo:
0 = no echo
PD.ALF $25 1 Auto line feed:
0 = no auto line feed
PD.NUL $26 1 End-of-line null count:
n
= number of nulls ($00)
sent after each carriage
return or carriage return
and line feed
(n = $00
-$FF)
PD.PAU $27 1 End of page pause:
0 = no pause
PD.PAG $28 1 Number of lines per page
PD.BSP $29 1 Backspace character
PD.DEL $2A 1 Delete-line character
6-4
Sequential Character File Manager l 6
Relative Size
Name Address (Bytes) Use
SCF Option Section Definition continued (PD.OPT Section)
PD.EOR $2B 1 End-of-record character (End
of-line character) Read only.
Normally set to $OD:
0 = Terminate read-line
only at the end of the
file
PD.EOF $2C 1 End-of-file character (read
only)
PD.RPR $2D 1 Reprint-line character
PD.DUP $2E 1 Duplicate-last-line character
PD.PSC $2F 1 Pause character
PD.INT $30 1 Keyboard-interrupt character
PD.QUT $31 1 Keyboard-terminate character
PD.BSE $32 1 Backspace-echo character
PD.OVF $33 1 Line-overflow character (bell
CTRL
GO)
PD.PAR $34 1 Device-initialization value
(parity)
PD.BAU $35 1 Software setable baud rate
PD.D2P $36 2 Offset to second device name
string
PP.XON $38 1 ACIA XON char
PD.XOFF $39 1 ACIA XOFF char
PD.ERR $3A 1 Most recent I/O error status
PD.TBL $38 2 Copy of device table address
PD.PLP $38 2 Path descriptor list pointer
PD.PST $3F 1 Current path status
6-5
OS-9 Technical Reference
PD.EOF specifies the end-of-file character. If this is the first
and only character that is input to the SCF device, SCF returns
an end-of-file error on Read or Readln.
PD.PSC specifies the pause character, which suspends output to
the device before the next end-of-record character. The pause
character also deletes any type-ahead input for Readln.
PD.INT specifies the keyboard-interrupt character. When the
character is received, the system sends a keyboard terminate
signal to the last user of a path. The character also terminates
the current I/O request (if any) with an error identical to the
keyboard interrupt signal code.
PD.QUT specifies the keyboard-terminate character. When this
character is received, the system sends a keyboard terminate
signal to the last user of a path. The system also cancels the
current I/O request (if any) by sending error code identical to the
keyboard interrupt signal code.
PD.PAR specifies the parity information for external serial
devices.
PD.BAU specifies baud rate, word length and stop bit informa
tion for serial devices.
PD.XON contains either the character used to enable transmis
sion of characters or a null character that disables the use of
XON.
PD.XOFF contains either the character used to disable trans
mission of characters or a null character that disables the use of
XOFF.
SCF-Type Device Descriptor Modules
The following chart shows how the initialization table in the
device descriptors is used for SCF-type devices. The values are
those the I/O manager copies from the device descriptor to the
path descriptor.
An SCF editing function is turned off if its corresponding value
is set to zero. For example, if IT.EOF is set to zero, there is no
end-of-file character.
6-6
Sequential Character File Manager / 6
Relative Size
Name Address (Bytes) Use
(header) $00- Standard device descriptor
11 module header
IT.DVC $12 1 Device class:
0=SCF
1 = RBF
2 = PIPE
3=SBF
IT. UPC $13 1 Case:
0 = upper- and lowercase
1 = uppercase only
IT.BSO $14 1 Backspace:
0 = backspace
1 = backspace, then space
and backspace
'' IT.DLO $15 1 Delete:
0 = backspace over line
1 = carriage return
IT.EKO $16 1 Echo:
0 = echo off
IT. ALF $17 1 Auto. line feed:
0 = auto line feed disabled
IT.NUL $18 1 End-of-line null count
ITTAU $19 1 Pause:
0 = end-of-page pause
disabled
ITTAG $lA 1 Number of lines per page
IT. BSP $1 B 1 Backspace character
IT. DE L $1 C 1 Delete-line character
IT.EOR $1D 1 End-of-record character
IT. E OF $1 E 1 End-of-file character
IT.RPR $1F 1 Reprint-line character
6-7
OS-9 Technical Reference
Relative Size
Name Address (Bytes) Use
IT.DUP $20 1 Duplicate-last-line character
IT.PSC $21 1 Pause character
MINT $22 1 Interrupt character
IT. QUT $23 1 (quit character
IT.BSE $24 1 Backspace echo character
IT.OVF $25 1 Line-overflow character (bell)
ITTAR $26 1 Initialization value used to
initialize a device control reg
ister when a path is opened to
it (parity)
IT.BAU $27 1 Baud rate
IT.D2P $28 2 Attached device name string
offset
IT. XON $2A 1 X-ON character
IT.XOFF $2B 1 X-OFF character
IT.COL $2C 1 Number of columns for display
IT.ROW $2D 1 Number of rows for display
IT.WND $2E 1 Window number
IT. VAL $2F 1 Data in rest of descriptor is
valid
IT.STY $30 1 Window type
IT.CPX $31 1 X cursor position
IT.CPY $32 1 Y cursor position
IT.FGC $33 1 Foreground color
IT.BGC $34 1 Background color
IT.BDC $35 1 Border color
6-8
Sequential Character File Manager l 6
SCF-Type Device Driver Modules
An SCF-type device driver module contains a package of subrou
tines that perform raw (unformatted) data I/O transfers to or
from a specific hardware controller. Such a module is usually re
entrant so that one copy of the module can simultaneously run
several devices that use identical I/O controllers. The
I/O manager allocates a permanent memory area for each con
troller sharing the driver.
The size of the memory area is defined in the device driver mod
ule header. The I/O manager and SCF use some of the memory
area. The device driver can use the rest in any way (typically as
variables and buffers). Typically, the driver uses the area as
follows:
Relative Size
Name Address (Bytes) Use
V.PAGE $00 1 Port extended 24 bit address
V.PORT $01 2 Device base address (defined
by the I/O manager)
V.LPRC $03 1 ID of the last active process
V.BUSY $04 1 ID of the active process
(defined by RBF):
0 = no active process
V.WAKE $05 1 ID of the process to reawaken
after the device completes I/O
(defined by the device driver):
0 = no waiting process
V.USER $06 0 Beginning of file manager
specific storage
V.TYPE $06 1 Device type or parity
V.LINE $07 1 Lines left until the end of the
page
V.PAUS $08 1 Pause request:
0 = no pause requested
V.DEV2 $09 2 Attached device memory area
V.INTR $OB 1 Interrupt character
6-9
OS-9 Technical Reference
Relative Size
Name Address (Bytes) Use
V.QUIT
$OC 1 Quit character
V.PCHR $OD 1 Pause character
V.ERR $OE 1 Error accumulator
V.XON $OF 1 XON character
V.XOFF $10 1 XOFF character
V. KANJI $11 1 Reserved
V.KBUF $12 2 Reserved
V . MODADR $14 2 Reserved
V.PDLHD $16 2 Path descriptor list header
V.RSV $18 5 Reserved
V.SCF $1D 0 End of SCF memory
requirements
FREE $1 D 0 Free for the device driver to
use
V.LPRC
contains the process ID of the last process to use the
device. The IRQ service routine sends this process the proper sig
nal if it receives a quit character or an interrupt character.
V.LPRC is defined by SCF.
V.BUSY
contains the process ID of the process that is using the
device. (If the device is not being used, V.BUSY contains a zero.)
The process ID is used by SCF to prevent more than one process
from using the device at the same time. V.BUSY is defined by
SCF.
SCF Device Driver Subroutines
Like all device drivers, SCF device drivers use a standard exe
cutable memory module format.
The execution offset address in the module header points to a
branch table that has six 3-byte entries. Each entry is typically
an LBRA to the corresponding subroutine. The branch table is
defined as follows:
6-10
Sequential Character File Manager / 6
ENTRY LBRA INIT Initialize driver
LBRA READ Read character
r-- LBRA WRITE Write character
LBRA GETSTA Get 5tatu5
LBRA SETSTA Set 5tatu5
LBRA TERM Terminate device
If no error occurs, each subroutine exits with the C bit in the
Condition Code Register cleared. If an error occurred, each sub
routine sets the C bit and returns an appropriate error code in
Register B.
The rest of this chapter describes these subroutines and their
entry and exit conditions.
6-11
OS-9 Technical Reference
Init
Initializes device control registers, and
enables interrupts if necessary.
Entry Conditions:
Y = address of the device descriptor
U = address o f the device memory area
Exit Conditions:
CC = carry set on error
B = error code (if
any)
Additional Information:
· Prior to being called, the device memory area is cleared (set
to zero), except for V.PAGE and V.PORT. (V.PAGE and
V.PORT contain the device address.) There is no need to
initialize the part of the memory area used by the I/0
· Follow these steps to use Init:
1. Initialize the device memory area.
2. Place the IRQ service routine on the IRQ polling list,
using the Set IRQ system call (F$IRQ).
3. Initialize the device control registers.
6-12
Sequential Character File Manager l 6
Read
Reads the next character from the input
buffer.
Entry Conditions:
Y = address of the path descriptor
U = address of the device memory area
Exit Conditions:
A = character read
CC = carry set on error
B = error
code (if
any)
Additional Information:
0
This is a step by step description of a Read operation:
1. Read gets the next character from the input buffer.
2. If no data is ready, Read copies its process ID from
V.BUSY into V.WAKE. It then uses the Sleep system
call to put itself to sleep.
3. Later, when Read receives data, the IRQ service rou
tine leaves the data in a buffer. Then, the routine
checks V. WAKE to see if any process is waiting for the
device to complete I/O. If so, the IRQ service routine
sends a wakeup signal to the waiting process.
0
Data buffers are not automatically allocated.
If
a buffer is
used, it defines it in the device memory area.
6-13
OS-9 Technical Reference
Write
Sends a character (places a data byte in
an output buffer) and enables the device
output interrupts.
Entry Conditions:
A = character to write
Y = address of the path descriptor
U = address of the device memory area
Exit Conditions:
CC = carry set on error
B = error
code (if
any)
Additional Information:
0
If the data buffer is full, Write copies its process ID from
V.BUSY into VMAKE. Write then puts itself to sleep.
Later, when the IRQ service routine transmits a character
and makes room for more data, it checks VMAKE to see
if
there is a process waiting for the device to complete I/O. If
there is, the routine sends a wakeup signal to that process.
Write must ensure that the IRQ service routine that starts
it begins to place data in the buffer. After an interrupt is
generated, the IRQ service routine continues to transmit
data until the data buffer is empty. Then, it disables the
device's ready-to-transmit interrupts.
0
Data buffers are not allocated automatically. If a buffer is
used, define it in the device memory area.
6-14
Sequential Character File Manager l 6
Getsta and Setsta
Gets/sets device operating parameters (status) as
specified for the Get Status and Set Status system
calls. Getsta and Setsta are wildcard calls.
Entry Conditions:
A = depends on the function code
Y = address of the pith
descriptor
U = address of
the
device memory area
Other registers depend on the function code.
Exit Conditions:
B = error code (if any)
CC = carry set on error
Other registers depend on the function code
Additional Information:
0
Any codes not defined by the I/O manager or SCF are
passed to the device driver.
You might need to examine or change the register stack
that contains the values of the 6809 registers at the time of
the call. The address of the register stack can be found in
PD.RGS, which is located in the path descriptor.
0
You can use the following offsets to access any value in the
register packet:
Relative Size
Name Address (Bytes) 6809 Register
R$CC $00 1 Condition Codes Register
R$D $01 0 Register D
R$A $01 1 Register A
R$B $02 1 Register B
R$DP $03 1 Register DP
R$X $04 2 Register X
R$Y $06 2 Register Y
R$U $08 2 Register U
R$PC $OA 2 Program Counter
The function code is retrieved from the R$B on the user stack.
6-15
OS-9 Technical Reference
Term
Terminates a device. Term is called when a
device is no longer in use (when the link
count of the device descriptor module
Entry Conditions:
U = pointer to the device memory area
Exit Conditions:
CC = carry set on error
B = error
code (if
any)
Additional Information:
· To use Term:
1. Wait until the IRQ service routine empties the output
buffer.
2. Disable the device interrupts.
3. Remove the device from the IRQ polling list.
· When Term closes the last path to a device, OS-9 returns
to the memory pool the memory that the device used.
If
the
device has been attached to the system using the I$Attach
system call, OS-9 does not return the static storage for the
driver until an I$Detach call is made to the device. Mod
ules contained in the Boot file are never terminated, even
if
their link counts reach 0.
6-16
Sequential Character File Manager / 6
IRQ Service Routine
-- Receives device interrupts. When I/O is complete, the
routine sends a wakeup signal to the process identi
fied by the process ID in VMAKE. The routine also
clears VMAKE as a flag to indicate to the main pro
gram that the IR Q has occurred.
Additional Information:
0
The IRfa Service Routine is not included in device driver
branch tables, and is not called directly by SCF. However, it
is a key routine in device drivers.
When the IRQ Service routine finishes servicing an inter-
rupt, the routine must clear the carry and exit with an
RTS instruction.
- Here is a typical sequence of events that the IRQ Service
Routine performs:
1. Service the device interrupts (receive data from the
device or send data to it). Ensure this routine puts its
data into and get its data from buffers that are defined
in the device memory area.
2. Wake up any process that is waiting for I/O to complete.
To do this, the routine checks to see if there is a pro
cess ID in VMAKE (a value. other than zero); if so, it
sends 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
4. If a pause character is received, set V.PAUS in the
attached device storage area to a value other than zero.
The address of the attached device memory area is in
V.PAUS in the attached device storage area to non-zero
'~ value. The address of the attached device memory area
- is in V.DEV2.
5. If a keyboard terminate or interrupt character is
received, signal the process in V.LPRC (last known
6-17
