The OS Jump Table: Calling the Atari Operating System the Supported Way

Atari text screen headed OS JUMP TABLE listing sixteen names such as DISKIV, CIOV and SIOV with their addresses $E450 to $E47D and target addresses such as $C6A3 and $E4DF, then a DSKINV read status of $01 and free sectors $0106

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 JMP to 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 CIOV and JSR DSKINV are 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 JSR or JMP instructions 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 SYSVBV or JMP 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