CIO Reference

The Central Input/Output Utility (CIO) is the primary I/O system used by the Atari 8-bit computers. Nearly all input or output passes through this utility.

Overview

CIO uses eight "channels" as paths for I/O. There are not really separate channels for I/O but the computer acts as if there were. Each channel is controlled by a 16 byte block of memory called an Input/Output Control Block or IOCB.

CIO Channels

There are eight CIO channels, numbered from 0 to 7. In BASIC some channels are reserved for BASIC's use.

BASIC CIO Channel Assignments

Channel	Assignment
0	Permanently assigned to the screen editor
6	Used for graphics commands
7	Used for the Cassette, disk and printer

Channels 6 and 7 are free to use when they are not being used by BASIC. With machine language, all of the channels are available to the programmer.

IOCB Structure

The IOCB for channel zero starts at address $0340 (decimal 832). This is the only address you need to know. Indexing from this address is used to find all of the other bytes.

IOCB Bytes and Uses

Address	Name	Explanation
$0340	ICHID	Handler Identifier
$0341	ICDNO	Device number (disk)
$0342	ICCOM	Command
$0343	ICSTA	Status
$0344	ICBAL	Buffer address (low byte)
$0345	ICBAH	Buffer address (high byte)
$0346	ICPTL	Address of put byte routine (used by BASIC)
$0347	ICPTH	Address of put byte routine (used by BASIC)
$0348	ICBLL	Buffer length (low byte)
$0349	ICBLH	Buffer length (high byte)
$034A	ICAX1	Auxiliary information
$034B	ICAX2	-
$034C	ICAX3	The remaining auxiliary bytes are rarely used
$034D	ICAX4	-
$034E	ICAX5	-
$034F	ICAX6	-

ICHID

When a channel is open, the handler I.D. contains an index to the handler table. The handler table holds the address of the device handling routines. When the channel is closed ICHID contains $FF.

ICDNO

The device number is used to distinguish between multiple devices with the same name, such as disk drives.

ICCOM

The command byte tells CIO what operation to perform.

ICSTA

The status byte contains an error code if something goes wrong. If bit 7 is 0 there have been no errors.

ICBAL and ICBAH

Before a channel is opened, the buffer address bytes are set point to the block of memory which contains the name of the device the channel is to be opened to. Before actual input or output these bytes are set to point to the block of memory where the I/O data is stored or is to be stored.

ICBLL and ICBLH

The buffer length bytes show the number of bytes in the block of memory used to store the input or output data. If the amount of data read during an input operation is less than the length of the buffer, the number of bytes actually read will be put in ICBLL and ICBLH by CIO.

ICAX1 through ICAX6

The auxiliary information bytes are used to give CIO or the device any special information needed.

CIO Command Codes

Hex	Dec	Command	Notes
$03	3	Open	May be made to a closed channel
$05	5	Get Record	-
$07	7	Get	-
$09	9	Print	-
$0B	11	Put	-
$0C	12	Close	May be made to a closed channel
$0D	13	Status	May be made to a closed channel
>$0D	>13	Special	Device specific commands

Opening a CIO Channel

Before using a CIO channel it must be assigned to an I/O device.

Channel-Open Parameters

ICCOM - open code ($03)
ICBAL - address of device name in memory (low byte)
ICBAH - address of device name in memory (high byte)
ICAX1 - direction code
ICAX2 - zero

Direction Codes (ICAX1)

Hex	Dec	Operation
$04	4	Input
$08	8	Output
$0C	12	Input and output (cannot change the length of a disk file)

ICAX1 format for opening a channel:

7 6 5 4 3 2 1 0
----------------
|        W R    |
----------------
        8 4 2 1

W = 1 = open for output (write)
R = 1 = open for input (read)

Device Names

ICBAL and ICBAH point to the device name stored in memory. The device and file name must be followed by 0 or $9B (decimal 155).

CIO device names:

Device	Description
C	Cassette recorder
D	Disk drive (uses non-resident handler)
E	Screen editor
K	Keyboard
P	Printer
R	RS-232 I/O port (uses non-resident handler)
S	Screen handler

The device name must usually be followed by a colon. With the disk drive a file name is expected after the device name.

Using an Open Channel

INPUT (ICCOM = $05)

The computer reads data from the device until a carriage-return is read (decimal number 155, hex $9B) or the end of the file (EOF) is reached.

IOCB input parameters:

ICCOM - get record code ($05)
ICBAL - address of buffer to store the data in (low byte)
ICBAH - address of buffer to store the data in (high byte)
ICBLL - length of the data buffer (low byte)
ICBLH - length of the data buffer (high byte)

If the data retrieved is shorter than the prepared buffer, the number of bytes actually read will be put into ICBLL and ICBLH.

PRINT (ICCOM = $09)

In assembly language the print command is identical to the input command. The only difference is that the PUTREC code ($09) is stored in ICCOM. The buffer bytes of the IOCB then specify the block of memory to be output from rather than input to. With the print command, EOLs within the string or buffer are ignored but an EOL is placed at the end of the data when sent to the device.

GET (ICCOM = $07)

In BASIC this command inputs a single byte of data from the device. EOLs are ignored.

IOCB get-byte parameters:

ICCOM - get-character (single byte) code ($07)
ICBAL, ICBAH, ICBLL, ICBLH - same as in input

PUT (ICCOM = $0B)

In BASIC, PUT is the opposite of GET. It outputs a single byte from a variable to the device.

In assembly language, the command byte of the IOCB is loaded with the put-character code (PUTCHR = $0B). Otherwise the PUT command is identical to GET.

Closing a Channel

Closing a channel frees it for use by another device or for changing parameters.

IOCB close command:

ICCOM - close code ($0C)

With the disk drive, the file name is not put into the directory until the channel is closed.

Status Codes

ICSTA (IOCB status byte) is the result code from the last CIO operation done on that IOCB.

Location: 851 decimal = $0353 (for IOCB1)

Meaning:

0 = success
Anything else = some kind of error or special condition

Common Status Values

Success:

0 = OK / Success

Non-fatal / end-of-data:

136 ($88) = End of File (EOF)
137 ($89) = Truncated record / line too long

Fatal errors (128-255):

Bad IOCB / channel not open
Device/handler not found
Bad command
Invalid parameter
Timeout
Device NAK / not responding
Framing / overrun errors (serial)

Interpreting ICSTA

Simple check:

S = PEEK(851)
IF S = 0 THEN ? "OK" ELSE ? "ERROR/STATUS="; S

With EOF handling:

S = PEEK(851)
IF S = 0 THEN ? "OK"
IF S = 136 THEN ? "EOF"
IF S > 127 AND S <> 136 THEN ? "ERROR="; S

Device Table

CIO uses a jump table located at $031A (794). When a CIO call is made, CIO searches the table for the one-byte device name. The two bytes following the device name contain the address of the device handler's vector table. CIO searches the device table from the end, $033D (829) to the beginning.

Handler Vector Table

Each handler has its own vector table. This vector table is 16 bytes long. The two-byte vectors point to the various handler routines.

Handler vector table order:

open
close
get byte
put byte
get stat
special
JMP init code (3 bytes)

Important Addresses

Name	Address	Description
DOSINI	$000C,2	Initialization vector
BRKKEY	$0011	Break key flag
ICHID	$0340	Start of IOCBs
HATABS	$031A,16	Device handler table
CIOV	$E456	CIO entry vector

FORGE Usage

In FORGE, you typically use high-level statements that call CIO internally:

OPEN #channel, mode, aux, "device"
INPUT #channel, variable
PRINT #channel, data
GET #channel, variable
PUT #channel, value
CLOSE #channel
STATUS #channel, statusVar
XIO #channel, cmd, aux1, aux2, "device"

See Statements for complete syntax.

cio-reference