Sequential_Character_File_Manager

• Sequential Character File Manager
  • SCF Line Editing Functions
    • Read and Write
    • Read Line and Write Line
    • SCF Definitions of the Path Descriptor
  • SCF-Type Device Descriptor Modules
  • SCF-Type Device Driver Modules
    • SCF Device Driver Subroutines

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/O system handling of sequential, character-oriented devices. The SCF manager includes the extensive I/O editing functions typical of line-oriented operations, such as:

• backspace
• line delete
• line repeat
• auto line feed
• screen pause
• return delay padding

The SCF-type device driver modules are VTIO, PRINTER, and RS-232. They run the video display, printer, and serial ports respectively. See the NitrOS-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 keyboard interrupt, keyboard terminate, and pause characters. (Editing is disabled if the corresponding character in the path descriptor contains a zero.

Carriage returns are not followed by line feeds or nulls automatically, 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. (NitrOS-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 keyboard (using the TMODE command). All bytes transferred by I$ReadLn and I$WritLn have the high order bit cleared.

SCF Definitions of the Path Descriptor

The PD.FST and PD.OPT sections of the path descriptor are reserved for an used by the SCF file manager.

The following table describes the SCF manager’s use of PD.FST and PD.OPT. For your convenience, the table also includes the other sections of the path descriptor.

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 system call. Any values not set by this table default to zero.

> Note: You can disable most of the editing functions by setting 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.

Name
Relative Address
Size (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 path descriptor)

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)

SCF Path Descriptor Definitions (PD.FST Section)

PD.DV2
$0A
2
Device table address of the second (echo) device

PD.RAW
$0C
1
Edit flag:
0 = raw mode
1 = edit mode

PD.MAX
$0D
2
Read Line maximum character count

PD.MIN
$0F
1
Devices are mine if cleared

PD.STS
$10
2
Status routine module address

PD.STM
$12
2
Reserved for status routine

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 = uppercase and lowercase
1 = uppercase 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
1 = echo

PD.ALF
$25
1
Auto line feed:
0 = no auto line feed
1 = 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
1 = pause

PD.PAG
$28
1
Number of lines per page

PD.BSP
$29
1
Backspace character

PD.DEL
$2A
1
Delete-line character

PD.EOR
$2B
1
End-of-record character (End-of-line character) Read only. Normally set to $0D0 = 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-G)

PD.PAR
$34
1
Device initialization value (parity)

PD.BAU
$35
1
Software settable baud rate

PD.D2P
$36
2
Offset to second device name string

PD.XON
$38
1
ACIA XON character

PD.XOFF
$39
1
ACIA XOFF character

PD.ERR
$3A
1
Most recent I/O error status

PD.TBL
$3B
2
Copy of device table address

PD.PLP
$3D
2
Path descriptor list pointer

PD.PST
$3F
1
Current path status

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 an 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 information for serial devices.

PD.XON contains either the character used to enable transmission of characters or a null character that disables the use of XON.

PD.XOFF contains either the character used to disable transmission 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.

Name
Relative Address
Size (Bytes)
Use

(header)
$00-$11
 
Standard device descriptor 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, space, and backspace

IT.DLO
$15
1
Delete:
0 = backspace over line
1 = carriage return

IT.EKO
$16
1
Echo:
0 = echo off
1 = echo on

IT.ALF
$17
1
Auto line feed:
0 = auto line feed disabled
1 = auto line feed enabled

IT.NUL
$18
1
End-of-line null count

IT.PAU
$19
1
Pause:
0 = end-of-page pause disabled
1 = end-of-page pause enabled

IT.PAG
$1A
1
Number of lines per page

IT.BSP
$1B
1
Backspace character

IT.DEL
$1C
1
Delete-line character

IT.EOR
$1D
1
End-of-record character

IT.EOF
$1E
1
End-of-file character

IT.RPR
$1F
1
Reprint-line character

IT.DUP
$20
1
Duplicate-last-line character

IT.PSC
$21
1
Pause character

IT.INT
$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)

IT.PAR
$26
1
Initialization value—used to initialize a device control register 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

SCF-Type Device Driver Modules

An SCF-type device driver module contains a package of subroutines 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 controller sharing the driver.

The size of the memory area is defined in the device driver module 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:

Name
Relative Address
Size (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
$0B
1
Interrupt character

V.QUIT
$0C
1
Quit character

V.PCHR
$0D
1
Pause character

V.ERR
$0E
1
Error accumulator

V.XON
$0F
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
$1D
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 routing sends this process the proper signal 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 executable 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:

ENTRY LBRA INIT   Initialize driver
      LBRA READ   Read character
      LBRA WRITE  Write character
      LBRA GETSTA Get status
      LBRA SETSTA Set status
      LBRA TERM   Terminate device

If no error occurs, each subroutine exits with the C bit in the Condition Code register cleared. If an error occurs, each subroutine 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.

Init Initializes device control registers and enables interrupts if necessary.

Entry Conditions

Y address of the device descriptor
U address of 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/O manager and SCF.
• Follow these steps to use Init:
  1. Initialize the device memory area.
  2. Place the IRQ service routine on the IRQ polling list, use the Set IRQ system call (F$IRQ).
  3. Initialize the device control registers.

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

• 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 routine 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.
• Data buffers are not automatically allocated. If a buffer is used, it defines it in the device memory area.

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

• If the data buffer is full, Write copies its process ID from V.BUSY into V.WAKE. Write then puts itself to sleep.
• Later, when the IRQ service routine transmits a character and makes room for more data, it checks V.WAKE 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.
• Data buffers are not allocated automatically. If a buffer is used, define it in the device memory area.

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 path descriptor
U address of the device memory area
Other registers depend on the function code.

Exit Conditions

CC carry set on error
B error code (if any)
Other registers depend on the function code

Additional Information

• 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.
• You can use the following offsets to access any value in the register packet:

Reg.
Relative Address
Size
6809 Register

R$CC
$00
1
Condition code register

R$D
$01
2
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
$0A
2
Program counter

The function code is retrieved from R$B on the user stack.

Term Terminates a device. Term is called when a device is no longer in use (when the link count of the device descriptor module becomes zero).

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, NitrOS-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, NitrOS-9 does not return the static storage for the driver until an I$Detach call is made to the device. Modules contained in the Boot file are never terminated, even if their link counts reach zero.

IRQ Service Routine

Receives device interrupts. When I/O is complete, the routine sends a wakeup signal to the process identified by the process ID in V.WAKE. The routine also clears V.WAKE as a flag to indicate to the main program that the IRQ has occurred.

Additional Information

• The IRQ Service Routine is not included in the 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 interrupt, the routine must clear the carry and exit with an RTS instructions.
• Here is a typical sequence of events that the IRQ Service Routing performs:
  1. Service the device interrupts (receive data from the device or send data to it). Ensure this routine puts its data into and gets 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 process ID in V.WAKE (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 interrupts.
  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.DEV2.
  5. If a keyboard terminate or interrupt character is received, signal the process in V.LPRC (last known process) if any.