The OS Jump Table: Calling the Atari Operating System the Supported Way
Every Atari machine-language program that prints text, reads a disk or installs an interrupt handler calls into the operating system ROM. Atari revised that ROM several times: OS-A and OS-B for the 400/800, then a largely rewritten OS for the XL and XE. Routines moved each time. What did not move is a short table of JMP instructions starting at $E450. Calling the OS through that table is the documented way, and programs that ignored it and jumped straight into the middle of the ROM are a large part of the reason some 400/800 software fails on an XL. This guide lists the table, shows where each entry leads on two real ROMs, explains the calling conventions of the entries you are allowed to use, and ends with a program that prints the table and reads a disk sector through it.
What you'll learn: the sixteen classic vectors and the five XL additions, which are public and which are for the OS only, how CIOV, SIOV, DSKINV and SETVBV are called, the device handler tables at $E400, and the other fixed addresses you can rely on.
What you need: MADS and an emulator with a DOS 2 disk in drive 1 for the example. It was assembled with MADS and run in atari800 on the genuine OS-B (400/800) and XL/XE Rev. 2 ROMs, with the emulator's SIO patch switched off (-nopatchall) so the ROM was unmodified.
1. Why a jump table?
A JSR $E456 always works because the three bytes at $E456 are a JMP to wherever CIO happens to live in that ROM. When Atari moved CIO, it only had to change the two address bytes of that JMP. A program that had found CIO's real start address with a disassembler and called that instead would break.
The changes were real. Between OS-A and OS-B, the vertical blank code moved 35 bytes and SETVBV's routine moved from $E912 to $E8ED. For the XL series, Atari rewrote the OS and moved the interrupt handlers into the new ROM area at $C000–$CFFF. Our program's output shows the effect: the same sixteen entry addresses on both machines, but only one target, $F223 at $E471, is the same on the 400/800 and the XL.
2. The table
Atari's documentation marks some entries as "for OS internal use only". The targets were read from the ROMs while the example ran:
| Address | Name | Purpose | Public? | OS-B target | XL/XE Rev. 2 target |
|---|---|---|---|---|---|
| $E450 (58448) | DISKIV | Disk handler initialisation | OS only | $EDEA | $C6A3 |
| $E453 (58451) | DSKINV | Disk handler: read or write one sector | Yes | $EDF0 | $C6B3 |
| $E456 (58454) | CIOV | Central I/O: all device-independent I/O | Yes | $E4C4 | $E4DF |
| $E459 (58457) | SIOV | Serial I/O: one command on the SIO bus | Yes | $E959 | $C933 |
| $E45C (58460) | SETVBV | Set a VBI vector or system timer safely | Yes | $E8ED | $C272 |
| $E45F (58463) | SYSVBV | Exit to the OS stage 1 vertical blank | Yes | $E7AE | $C0E2 |
| $E462 (58466) | XITVBV | Exit from a vertical blank routine | Yes | $E905 | $C28A |
| $E465 (58469) | SIOINV | SIO initialisation | OS only | $E944 | $E95C |
| $E468 (58472) | SENDEV | Serial "send enable" | OS only | $EBF2 | $EC17 |
| $E46B (58475) | INTINV | Interrupt handler initialisation | OS only | $E6D5 | $C00C |
| $E46E (58478) | CIOINV | CIO initialisation | OS only | $E4A6 | $E4C1 |
| $E471 (58481) | BLKBDV | Memo pad (400/800); self-test (XL/XE) | Yes | $F223 | $F223 |
| $E474 (58484) | WARMSV | Warm start, as if RESET was pressed | Yes | $F11B | $C290 |
| $E477 (58487) | COLDSV | Cold start, as if the power was cycled | Yes | $F125 | $C2C8 |
| $E47A (58490) | RBLOKV | Cassette: read a block | OS only | $EFE9 | $FD8D |
| $E47D (58493) | CSOPIV | Cassette: open for input | OS only | $EF5D | $FCF7 |
Both sets of values match the published tables for these ROMs. On XL/XE machines, the memo pad is gone: $E471 leads to the self-test, which is why typing BYE in BASIC starts it.
The XL OS adds five more jump vectors right after the table, where the 400/800 ROM kept the initial values for the RAM interrupt vectors:
| Address | Name | Purpose | Rev. 2 target |
|---|---|---|---|
| $E480 | PUPDIV | Power-on display (self-test on most XL/XEs) | $F223 |
| $E483 | SLFTSV | Self-test entry (1200XL) | $5000 |
| $E486 | PENTV | Entry to a handler uploaded from a peripheral | $EEBC |
| $E489 | PHUNLV | Unlink an uploaded handler | $E915 |
| $E48C | PHINIV | Initialise an uploaded handler | $E898 |
A program that must also run on a 400/800 cannot use these. The bytes at $E480 there are data, not code.
3. Calling the public entries
CIOV ($E456). Put the IOCB number × 16 in X (0, $10, $20 … $70), fill in that IOCB at $0340 + X (command, buffer address, length, AUX bytes) and JSR CIOV. On return, Y holds the status (1 = success, 128 and above = error), and the N flag is set on error, so BMI error works directly after the call. A useful special case appears in the example: with a buffer length of zero, the PUT CHARACTERS command (11) sends the single byte in A. See CIO and IOCBs: How Atari Input/Output Really Works for the commands.
DSKINV ($E453). Reads or writes one disk sector through the device control block (DCB) at $0300. You set DUNIT ($0301, drive 1–4), DCOMND ($0302: $52 read, $57 write with verify, $53 status, $21 format), DBUF ($0304–$0305) and the sector number in DAUX1–DAUX2 ($030A–$030B). The handler fills in the device ID, timeout, direction and byte count itself, then returns the result in DSTATS ($0303). On the XL/XE, the byte count comes from DSCTLN ($02D5), which holds 128 by default.
SIOV ($E459). The level below DSKINV, for any SIO device. You fill in the whole DCB yourself: device ID, unit, command, direction in DSTATS ($40 read, $80 write, 0 none), buffer, timeout, byte count and AUX bytes. SIO Explained: How the Atari Serial Bus Talks to Drives and Devices covers it in depth.
SETVBV ($E45C). Changes a two-byte vertical blank vector or system timer without a VBI arriving halfway through. A = what to set (1–5 for the system timers, 6 for VVBLKI, 7 for VVBLKD), X = high byte, Y = low byte. A, X and Y are changed by the call.
SYSVBV ($E45F) and XITVBV ($E462). Not subroutines but exits. An immediate VBI ends with JMP SYSVBV to let the OS do its normal stage 1 work, and a deferred VBI ends with JMP XITVBV, which restores the registers and returns from the interrupt. The OS User's Manual also points out that the address bytes after each JMP hold the default VVBLKI and VVBLKD values, so you can restore those vectors without saving the old ones.
WARMSV, COLDSV, BLKBDV. Jump (don't call) to restart the machine as RESET or power-on would, or to enter the memo pad or self-test. The vectors WARMSV and COLDSV are what a "reboot" menu option uses.
4. Other fixed addresses
The jump table is not the only stable part of the ROM:
- $E400–$E44F: the resident handler tables. Five 16-byte blocks for E: ($E400), S: ($E410), K: ($E420), P: ($E430) and C: ($E440). Each holds the addresses minus one of the handler's OPEN, CLOSE, GET BYTE, PUT BYTE, STATUS and SPECIAL routines, then a
JMPto its initialisation. HATABS points CIO at these tables. The "minus one" is because CIO reaches a handler by pushing the address on the stack and executing RTS, which adds one. Copying a table into RAM and changing one entry is the classic way to hook a device; some type-in proofreading programs did exactly that with E:. - $D800–$DFFF: the floating-point package, with entry points such as AFP ($D800), FASC ($D8E6) and IFP ($D9AA) fixed across revisions. See Using the Floating-Point ROM from Assembly Language.
- $E000–$E3FF: the standard character set, which CHBAS = $E0 selects.
- $FFFA–$FFFF: the 6502's own NMI, RESET and IRQ vectors. They point to different addresses on each OS, so only the CPU should use them (see Inside the OS Interrupt Handlers).
Everything else is internal and can change. One byte is a handy fingerprint: $E40F reads 56 on an OS-A ROM and 0 on OS-B. Our OS-B image read 0.
5. The example program
The program prints the table of whatever OS it runs on, then reads sector 360 (the DOS 2 VTOC) through DSKINV and prints the status and the free-sector count from bytes 3 and 4 of the sector.
; List the OS ROM jump table of whatever OS is running, then use one of
; its entries (DSKINV) to read the disk's VTOC sector.
ICCOM = $0342
ICBAL = $0344
ICBLL = $0348
DUNIT = $0301
DCOMND = $0302
DSTATS = $0303
DBUF = $0304
DAUX1 = $030A
DSKINV = $E453
CIOV = $E456
PTR = $CB
SPTR = $CD
org $3000
start lda #<head
ldy #>head
jsr puts
lda #$50 ; entries start at $E450, 3 bytes apart
sta PTR
lda #$E4
sta PTR+1
ldx #0 ; X = entry number 0-15
entry stx num
txa ; name: 7 characters per entry
asl
asl
asl
sec
sbc num
tay
lda #7
sta cnt
nm lda names,y
sty savy ; CIO doesn't preserve Y
jsr putc
ldy savy
iny
dec cnt
bne nm
lda #'$'
jsr putc
lda PTR+1 ; the vector's own address
jsr puthex
lda PTR
jsr puthex
lda #<arrow
ldy #>arrow
jsr puts
ldy #2 ; JMP operand, high byte then low byte
lda (PTR),y
jsr puthex
ldy #1
lda (PTR),y
jsr puthex
lda #$9B
jsr putc
clc
lda PTR
adc #3
sta PTR
ldx num
inx
cpx #16
bne entry
; read sector 360 (the DOS 2 VTOC) through DSKINV
lda #1
sta DUNIT ; drive 1
lda #$52
sta DCOMND ; 'R': read sector
lda #<buf
sta DBUF
lda #>buf
sta DBUF+1
lda #<360
sta DAUX1
lda #>360
sta DAUX1+1
jsr DSKINV
lda #<vtoc
ldy #>vtoc
jsr puts
lda DSTATS ; 1 = success
jsr puthex
lda #<freem
ldy #>freem
jsr puts
lda buf+4 ; VTOC bytes 3-4: free sectors
jsr puthex
lda buf+3
jsr puthex
jmp *
putc ldx #0 ; one character through CIO: with a buffer
stx ICBLL ; length of zero, CIO takes it from A
stx ICBLL+1
pha
lda #11 ; PUT CHARACTERS
sta ICCOM
pla
jsr CIOV
rts
puts sta SPTR ; print a zero-terminated string at A/Y
sty SPTR+1
ldy #0
ps1 lda (SPTR),y
beq ps2
sty savy
jsr putc
ldy savy
iny
bne ps1
ps2 rts
puthex pha
lsr
lsr
lsr
lsr
jsr hexd
pla
and #$0F
hexd tax
lda hexc,x
jmp putc
hexc dta c'0123456789ABCDEF'
num dta 0
cnt dta 0
savy dta 0
head dta c'OS JUMP TABLE',$9B,0
arrow dta c' -> $',0
vtoc dta c'DSKINV READ OF SECTOR 360: STATUS $',0
freem dta $9B,c'FREE SECTORS (VTOC BYTES 3-4): $',0
names dta c'DISKIV DSKINV CIOV SIOV SETVBV SYSVBV XITVBV '
dta c'SIOINV SENDEV INTINV CIOINV BLKBDV WARMSV COLDSV '
dta c'RBLOKV CSOPIV '
buf .ds 128
run start
Assemble with mads vectors.asm -o:vectors.xex and run it with a DOS 2 or DOS 2.5 disk in drive 1. Things to notice:
- The program reads the table instead of trusting it. For each entry it prints the address of the vector and the two operand bytes of its
JMP. JSR CIOVandJSR DSKINVare the only ways it calls the OS, so the same file ran unchanged on OS-B and on the XL OS, producing different targets and the same results.- CIO doesn't keep Y, because it returns the status there. The name loop saves Y around each call. That was a bug in our first version, whose names came out garbled.
- DSKINV returned status $01 and a free count of $0106 (262 sectors). The same disk image, examined on the PC, also had 262 free sectors.
One emulator detail is worth knowing if you try this yourself. By default, atari800 patches the SIOV entry in its ROM image with its own instruction, to speed up disk access. When we first dumped the table in the emulator's monitor, $E459 held that patch instead of a JMP. Starting the emulator with -nopatchall shows the real ROM. Other emulators can do the same, so don't take the bytes at $E459 in an emulator as proof of what a real machine contains.
Troubleshooting
- Works on one machine, crashes on another: look for
JSRorJMPinstructions into $C000–$FFFF that are not in the jump table, the handler tables or the floating-point package. - CIO returns garbage or loops: X must hold the IOCB number × 16, not the IOCB number.
- DSKINV returns 138 (timeout) or 139 (NAK): wrong drive number in DUNIT, no disk, or a sector number outside the disk.
- A counter or loop variable is wrong after a CIO call: Y, and often X, were changed by the call.
- VBI routine crashes on exit: an immediate VBI must end with
JMP SYSVBVorJMP XITVBV, not RTI, because the OS pushed A, X and Y before calling it.
Further reading
- Atari, Inc., Operating System User's Manual, Appendix J "ROM Vectors" and section 5 (the resident disk handler and DCB).
- Ian Chadwick, Mapping the Atari: locations 58368–58533 and Appendix Twelve (XL/XE jump table targets and new vectors).
- On this site: CIO and IOCBs: How Atari Input/Output Really Works, SIO Explained: How the Atari Serial Bus Talks to Drives and Devices, Vertical Blank Interrupts: Running Code 60 Times a Second, XL/XE Compatibility: Why Old 800 Software Fails, and How the Translator Fixes It.
Credits
- Picture: The example on the XL/XE OS Rev. 2: every vector jumps somewhere different than on the 400/800, but the entry addresses are the same. The last lines come from reading the disk's VTOC through DSKINV. — Program authors; screenshot by the site
- Atari Operating System User's Manual — Appendix J ROM Vectors (internal-use marks), resident diskette handler and DCB, SETVBV calling sequence, SYSVBV/XITVBV notes — ksquiggle
- Mapping the Atari — 58368-58533 (handler tables, jump vectors, E40F A/B test), Appendix Four (A vs B ROM changes), Appendix Twelve (XL jump table targets, PUPDIV/SLFTSV/PENTV/PHUNLV/PHINIV, SELFTST), 725 DSCTLN — AtariArchives.org
- Atari 400/800 OS Source Listing Rev. A — handler vector table 'addresses minus one', GOHAND/CIJUMP (RTS dispatch, status in Y, N flag) — ksquiggle
