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
- De Re Atari, Chapter 8: The Centralized Input/Output Subsystem — Jim Dunion (Section 8 of De Re Atari)
- De Re Atari, Chapter 9: The Disk Operating System (OPEN modes, XIO) — AtariArchives.org
- Mapping the Atari (Ian Chadwick) — IOCBs 832–959, HATABS 794–831 — AtariArchives.org
- cc65 atari.inc (IOCB, command and error equates) — GitHub project authors
