CIO and IOCBs: How Atari Input/Output Really Works

One of the Atari 400/800's best design decisions was to make all input and output device-independent. Printing to the screen, a printer, a cassette or a disk file uses the same calls with a different device name. The design goals: data transfer independent of the device, support for byte, block and record transfers, several devices open at once, and new handlers added without having to change the OS ROM. The machinery behind this is CIO (Central Input/Output) and its eight IOCBs (Input/Output Control Blocks). Once you understand them, BASIC's OPEN, PRINT #, GET #, XIO and NOTE stop being magic, and you can call the same services from assembly.

You need: Atari BASIC, and an assembler for the machine-language examples. Everything here works on all models and with all common DOSes.

1. The layers

Your program (BASIC, assembly, Action!...)
        |  IOCB + JSR CIOV ($E456)
       CIO  -- looks up the device letter in HATABS
        |
Device handler: E: S: K: P: C: (in ROM)  D: (DOS)  R: (850)  ...
        |  DCB + JSR SIOV ($E459)   (serial devices only)
       SIO  -- talks to peripherals over the serial bus

E: is the screen editor, S: the screen display, K: the keyboard, P: the printer and C: the cassette. Those five are resident in ROM. D: is added by DOS when it boots, and R: by the 850 interface's downloaded handler. For the bottom layer, see SIO explained.

2. The eight IOCBs

The IOCBs sit in page 3, 16 bytes each, at $0340 + 16 × channel number (832–959 decimal):

Channel Address Used by BASIC / OS for
#0 $340 (832) Screen editor E:, always open
#1–#5 $350–$390 Free for your files
#6 $3A0 (928) GRAPHICS statement opens S: here
#7 $3B0 (944) LPRINT, and BASIC's LOAD/SAVE/LIST/ENTER

Avoid #0, #6 and #7 in your own programs. BASIC closes every channel except #0 on RUN, NEW, LOAD and when DOS is called.

Each IOCB has the same layout. The names below are the official labels, as used in cc65's atari.inc:

Offset Name Meaning
+0 ICHID Handler index into HATABS ($FF = IOCB free)
+1 ICDNO Device number (e.g. 2 for D2:)
+2 ICCOM Command byte
+3 ICSTA Status of the last operation
+4,+5 ICBAL/ICBAH Buffer address
+6,+7 ICPTL/ICPTH Handler's put-byte address minus 1 (set by CIO)
+8,+9 ICBLL/ICBLH Buffer length / byte count
+10 ICAX1 Auxiliary byte 1 (open mode)
+11 ICAX2 Auxiliary byte 2 (device-specific)
+12–15 ICAX3–6 Spare / handler use (NOTE and POINT values live here)

You fill in ICCOM, the buffer address, the length and the AUX bytes. CIO fills in the rest.

3. CIO commands

Code Command Notes
3 OPEN Buffer points to the device/file name, e.g. D:TEST.DAT
5 GET RECORD Read up to an EOL ($9B) or the buffer length
7 GET CHARACTERS Read exactly N bytes (block read)
9 PUT RECORD Write up to and including an EOL
11 ($0B) PUT CHARACTERS Write N bytes (block write)
12 ($0C) CLOSE
13 ($0D) STATUS
14+ SPECIAL Handler-specific. DOS uses 32 rename, 33 delete, 35 lock, 36 unlock, 37 POINT, 38 NOTE, 254 format. S: uses 17 draw line, 18 fill

The OPEN mode goes in ICAX1. For disk files, De Re Atari's bit layout is W R D A (bits 3–0):

ICAX1 Mode
4 Read
8 Write (any existing file is deleted first)
9 Write append
12 Update (read and write)
6 Read the disk directory

The screen handlers add 16 for "mixed mode" (text window) and 32 for "don't clear the screen". This is why BASIC's GRAPHICS 8+16 removes the text window and GRAPHICS 8+32 keeps the old picture.

4. Status codes

After every call, CIO returns the status in the Y register and in ICSTA, and sets the 6502 N flag if it is an error (128 or higher). In assembly, BMI straight after JSR CIOV is the standard error test. A few of the codes listed in atari.inc that you will meet constantly:

Code Meaning
1 Success
3 Success, and the next read will hit end of file (warning, not an error)
129 IOCB already open
130 Nonexistent device
136 End of file
138 Device timeout (device not responding)
144 Device done error (e.g. write-protected disk)
146 Function not implemented in handler
162 Disk full
165 Invalid file name
167 File locked
170 File not found

BASIC reports exactly these numbers as ERROR- 170 and so on, and stores the last one in location 195.

5. Calling CIO from assembly

De Re Atari's calling sequence is three instructions:

        LDX #IOCBNUM*16 ; IOCB index, not the channel number!
        JSR CIOV        ; $E456
        BMI ERROR       ; Y holds the error code

Here is a complete example that opens a disk file on channel 1, reads one line and prints it through channel 0:

CIOV   = $E456
ICCOM  = $0342
ICSTA  = $0343
ICBAL  = $0344
ICBLL  = $0348
ICAX1  = $034A
ICAX2  = $034B

        *= $3000
START   LDX #$10        ; channel 1
        LDA #3          ; OPEN
        STA ICCOM,X
        LDA #<FNAME
        STA ICBAL,X
        LDA #>FNAME
        STA ICBAL+1,X
        LDA #4          ; read
        STA ICAX1,X
        LDA #0
        STA ICAX2,X
        JSR CIOV
        BMI FAIL

        LDA #5          ; GET RECORD
        STA ICCOM,X     ; X is still $10 after a successful call
        LDA #<BUF
        STA ICBAL,X
        LDA #>BUF
        STA ICBAL+1,X
        LDA #120
        STA ICBLL,X
        LDA #0
        STA ICBLL+1,X
        JSR CIOV
        BMI FAIL

        LDX #0          ; channel 0 = E:
        LDA #9          ; PUT RECORD
        STA ICCOM,X
        LDA #<BUF
        STA ICBAL,X
        LDA #>BUF
        STA ICBAL+1,X
        LDA #120
        STA ICBLL,X
        LDA #0
        STA ICBLL+1,X
        JSR CIOV

FAIL    LDX #$10        ; always close channel 1
        LDA #12         ; CLOSE
        STA ICCOM,X
        JSR CIOV
        RTS
FNAME   .BYTE "D:TEST.TXT",$9B
BUF     .DS 120

Two habits worth forming: always reload X before each call if there is any doubt, and always CLOSE, even after an error. An IOCB left open causes error 129 on the next OPEN.

6. The missing BASIC feature: block I/O

BASIC's PRINT # and INPUT # use record I/O, and GET # and PUT # move one byte at a time. BASIC never uses CIO's GET CHARACTERS and PUT CHARACTERS commands, which move an entire block in one call. You can reach them with a seven-byte USR routine, which De Re Atari prints as PLA,PLA,PLA,TAX,JMP $E456. It takes the IOCB index as its argument and jumps into CIO.

This program loads a 7,680-byte GRAPHICS 8 picture straight into screen memory in a single disk read:

10 DIM CIO$(7),F$(20)
20 FOR I=1 TO 7:READ B:CIO$(I,I)=CHR$(B):NEXT I
30 DATA 104,104,104,170,76,86,228
40 F$="D:PICTURE.PIC"
50 GRAPHICS 8+16:SC=PEEK(88)+256*PEEK(89)
60 OPEN #1,4,0,F$:X=16
70 POKE 834+X,7:REM GET CHARACTERS
80 POKE 836+X,SC-INT(SC/256)*256:POKE 837+X,INT(SC/256)
90 POKE 840+X,0:POKE 841+X,30:REM 30*256=7680 BYTES
100 R=USR(ADR(CIO$),X)
110 ST=PEEK(835+X):CLOSE #1
120 IF PEEK(764)=255 THEN 120
130 GRAPHICS 0:PRINT "STATUS ";ST

Locations 88–89 (SAVMSC) point to the screen. Lines 70–90 poke ICCOM, ICBAL and ICBLL for channel 1, and line 100 calls CIO. To save a picture, open the file with mode 8 and use command 11 (PUT CHARACTERS) instead. De Re Atari's Figure 8-16 is a general-purpose version of the same routine. It is also the classic way to load machine code into page 6 from BASIC.

7. XIO: CIO commands from BASIC

BASIC's XIO statement issues any CIO command directly:

XIO command,#channel,aux1,aux2,"filespec"

So XIO 33,#1,0,0,"D:OLD.BAK" deletes a file, XIO 32,#1,0,0,"D:A.DAT,B.DAT" renames one, and XIO 18,#6,0,0,"S:" performs the screen handler's fill. The disk commands are covered in Disk files in BASIC.

8. Handlers and HATABS

When you OPEN "P:", CIO searches the Handler Address Table, HATABS at $031A, for the letter P. Each entry is three bytes: the device letter and the address of that handler's table of entry points (OPEN, CLOSE, GET, PUT, STATUS, SPECIAL, each stored as address minus 1, then a JMP to its init routine). CIO searches from the end of the table backwards, so a newly added handler for an existing letter takes priority over the ROM version. This is how DOS adds D:, the 850 adds R:, and modern devices add N: (FujiNet) or other drivers. De Re Atari's Figure 8-14 adds a do-nothing "N:" null handler in about 50 bytes, a handy debugging device.

A fun IOCB #0 trick: POKE 842,13 sets the editor's AUX1 so that it reads its next input from the screen instead of the keyboard. A program can print commands on screen and then "type" them into itself; POKE 842,12 restores normal input. This "forced read" trick is the classic way for a BASIC program to delete or add its own lines.

Troubleshooting

  • ERROR 129 (already open): CLOSE the channel first. Many programs simply CLOSE before every OPEN.
  • ERROR 130 (nonexistent device): you used D: without DOS booted, or forgot the colon.
  • ERROR 136 at the end of a read loop: this is normal. TRAP it as your end-of-file test.
  • Assembly call crashes or uses the wrong file: X must be the channel number × 16 ($10, $20 ...), not 1, 2.
  • Block load fills the screen with garbage: the file is not a raw screen dump of the same mode and size, or ICBLL is wrong.

Further reading

  • De Re Atari (Atari, Inc., 1982), Chapter 8 (CIO, HATABS, null handler, BASIC direct CIO call) and Chapter 9 (DOS functions).
  • Mapping the Atari by Ian Chadwick (Small System Services, 1983), locations 794–959.
  • Inside Atari DOS by Bill Wilkinson (Small System Services, 1982): the FMS (D: handler) from the inside.
  • On this site: SIO explained, Disk files in BASIC.

Credits