Writing a Bootable Disk Program (No DOS Required)

Black screen with the text BOOTED FROM SECTOR ONE! and a coloured border

Before DOS, and below it, there's the boot. At power-up the Atari OS reads sector 1 of drive 1, and from that point your code can take over the whole machine. Every DOS starts this way, and so do countless single-load games, demos and modern loaders. This guide works through the process through the original OS source code, then builds a tiny bootable disk you can run in any emulator.

What you'll learn: exactly what the OS does during a disk boot, the boot header, how DOSINI, DOSVEC and the carry flag fit together, what happens on RESET, how to load more sectors yourself, and how to make an ATR image.

What you need: MADS (or any assembler that can produce raw output), Python 3 for the image builder, and an emulator.

1. What the OS does, step by step

These steps follow the BOOT/DOBOOT routines in the Atari 400/800 OS Rev. A source listing. By then the OS has cleared memory, initialised any cartridges and opened the screen editor.

  1. It sends a status command to D1:. If the drive doesn't answer, there is no disk boot.
  2. It reads sector 1 into the cassette buffer at $0400.
  3. It copies the first four bytes into DFLAGS ($240), DBSECT ($241, the number of boot sectors) and BOOTAD ($242/$243, the load address). Bytes 4–5 go to DOSINI ($0C/$0D).
  4. It copies the 128-byte sector to BOOTAD, then reads sectors 2, 3… and appends each one 128 bytes further on, until DBSECT sectors have been loaded. On a read error it prints BOOT ERROR and starts again.
  5. It jumps to BOOTAD + 6, the first byte after the header. Your code runs and returns with RTS. If the carry flag is set, the OS treats the boot as failed and tries again. Clear carry for success.
  6. It calls your init routine through DOSINI, then sets bit 0 of BOOT? ($09) to record a successful disk boot.
  7. Coldstart finishes. If a cartridge (including XL/XE built-in BASIC) asks to run, the OS jumps to it. Otherwise it jumps through DOSVEC ($0A/$0B).

That's the whole mechanism. To recap the header layout: byte 0 the flag (unused, zero), byte 1 the sector count, bytes 2–3 the load address, bytes 4–5 the init address, and at byte 6 DOS's own JMP to its boot-continuation code.

What RESET does

On a warm start (RESET) the OS checks BOOT?. If the disk boot had succeeded, it calls DOSINI again. Then it goes back to the cartridge or to DOSVEC. Two consequences:

  • Your DOSINI routine runs on every RESET. DOSINI is the only place to "trap" the RESET sequence, which is why programs that protect a memory area by moving MEMLO hook it.
  • If your program sets DOSVEC to its own entry point, RESET restarts the program instead of dropping into the Memo Pad.

2. A one-sector boot program

This program fits in one sector. It prints a line by writing screen codes straight into screen memory, then cycles the border colour for ever. All the addresses are standard OS and hardware locations.

; boot1.asm - a one-sector boot program (MADS)
; build: mads boot1.asm -o:boot1.bin
DOSVEC  = $0A           ; run vector used by the OS after booting
SAVMSC  = $58           ; pointer to screen memory
COLOR2  = $02C6         ; GR.0 background shadow
COLOR4  = $02C8         ; border shadow
RTCLOK  = $12           ; RTCLOK+2 ticks once per frame

        opt h-f+                ; raw bytes, one block, no DOS headers
        org $0700

boot    dta 0                   ; byte 0: flags (copied to DFLAGS)
        dta 1                   ; byte 1: sectors to load (DBSECT)
        dta a(boot)             ; bytes 2-3: load address (BOOTAD)
        dta a(init)             ; bytes 4-5: init address (DOSINI)

; byte 6: the OS jumps here after loading all boot sectors
        lda #<main
        sta DOSVEC
        lda #>main
        sta DOSVEC+1            ; where the OS goes when booting is done
        clc                     ; carry clear = boot OK (set = boot error)
init    rts                     ; DOSINI routine: also called on every RESET

main    ldy #msglen-1
copy    lda msg,y               ; copy screen-code text to the top line
        sta (SAVMSC),y
        dey
        bpl copy
        lda #$00
        sta COLOR2
loop    lda RTCLOK+2
        sta COLOR4              ; cycle the border once per frame
        jmp loop

msg     dta d'BOOTED FROM SECTOR ONE!'
msglen  = *-msg

        org boot+$7F            ; pad the file to exactly 128 bytes
        dta 0

Some notes:

  • opt h-f+ tells MADS to write raw bytes with no $FFFF headers, and to emit everything as one block, filling gaps. Together with the final org boot+$7F / dta 0 (the same trick JAC!'s Boot.asm example uses), the output is exactly one 128-byte sector.
  • $0700 is the address DOS itself boots to. A game that doesn't need DOS can use any free RAM. Page six, $0600, is another favourite.
  • The boot entry and the init routine share one RTS. CLC falls through into init, which returns to the OS. When the OS later calls DOSINI it finds a bare RTS.
  • dta d'…' writes internal screen codes, because the text goes straight into screen memory rather than through CIO.

3. Turning it into a disk image

An ATR file is a 16-byte header followed by the sectors in order. ATasm's disk-image code reads it like this: bytes 0–1 hold the signature $96 $02, bytes 2–3 and 6–7 hold the image size in 16-byte units (low and high words), and bytes 4–5 hold the sector size.

#!/usr/bin/env python3
"""mkbootatr.py boot.bin out.atr - put a raw boot image on a blank 90K ATR."""
import sys

SECTORS, SECSIZE = 720, 128          # single density, 720 x 128 = 92,160 bytes
boot = open(sys.argv[1], 'rb').read()
if len(boot) % SECSIZE or len(boot) > SECTORS * SECSIZE:
    sys.exit('boot image must be a whole number of 128-byte sectors')

body = boot + bytes(SECTORS * SECSIZE - len(boot))
paras = len(body) // 16              # ATR stores the image size in 16-byte units
header = bytes([0x96, 0x02,                      # ATR signature
                paras & 0xFF, (paras >> 8) & 0xFF,
                SECSIZE & 0xFF, SECSIZE >> 8,
                (paras >> 16) & 0xFF, 0]) + bytes(8)
open(sys.argv[2], 'wb').write(header + body)
print(f'{sys.argv[2]}: {len(boot) // SECSIZE} boot sector(s), {SECTORS} sectors total')
mads boot1.asm -o:boot1.bin
python3 mkbootatr.py boot1.bin boot1.atr

Boot boot1.atr with BASIC disabled (hold OPTION on an XL/XE, use /nobasic in Altirra, or -nobasic in atari800). The message appears and the border cycles. Press RESET and the program restarts through DOSVEC. With BASIC enabled you'll get the READY prompt instead, because the OS offers control to the cartridge before it tries DOSVEC (step 7).

4. Loading more than one sector

Let the OS do it. Set byte 1 to the number of sectors (1–255) and assemble that many 128-byte sectors in a row. The OS loads them all before jumping to byte 6. Standard DOSes use 1–3 sectors for their first stage, while games may use any count.

Load the rest yourself. For big programs, a small first stage reads further sectors through the disk handler. Fill in the device control block at $0300 and call DSKINV ($E453):

DUNIT   = $0301     ; drive number
DCOMND  = $0302     ; 'R' ($52) = read sector
DBUFLO  = $0304     ; buffer address (lo/hi)
DAUX1   = $030A     ; sector number (lo/hi)
DSKINV  = $E453     ; disk handler entry

        lda #1
        sta DUNIT
        lda #'R'
        sta DCOMND
        lda #<$2000
        sta DBUFLO
        lda #>$2000
        sta DBUFLO+1
        lda #2
        sta DAUX1
        lda #0
        sta DAUX1+1
        jsr DSKINV          ; read sector 2 to $2000
        bmi error           ; negative status = I/O error

Loop over the sector number and buffer address, adding 128 each time. That's exactly what examples/Boot.asm in the MADS repository does to load $0800–$BFFF from sector 2 onward. (The disk handler's commands are read $52, write $50, write with verify $57, status $53 and format $21.)

5. Gotchas

  • Double density. By convention the first three sectors of a double-density (256-byte) disk are still 128 bytes, because the OS boot code can only load that size. A double-density first stage must fit in 384 bytes and switch the sector size itself, the pattern DOS 2.0 established.
  • Never returning from byte 6. Many games simply jump into the main program from the boot entry. It works, but the OS never finishes its coldstart. COLDST ($244) stays non-zero, and a non-zero COLDST makes RESET reboot the machine. For many games that's exactly what's wanted.
  • Clobbering the OS's working areas. Boot code runs before anything else, but the OS still uses page zero, pages two to five and the stack. Load into free RAM.
  • Turning BASIC off from boot code. On XL/XE machines you can switch BASIC out through PORTB ($D301), as JAC!'s loader does. If you then return to the OS, it will still try to start the "cartridge" it detected earlier, which is now gone. Only switch BASIC out if your program never hands control back.
  • Cassette boots use the same idea. A cassette boot file has the same kind of six-byte header (ignored byte, record count, load address, init address), with initialisation through CASINI ($02) instead of DOSINI.

Troubleshooting

  • BOOT ERROR loops for ever. Your entry code returned with carry set, or the image isn't a valid ATR (check the header and that the size is a multiple of 128).
  • Blank screen, then READY. BASIC was enabled. Boot with BASIC off.
  • Works once, crashes on RESET. Your DOSINI routine runs on every RESET. Make sure it is safe to call again, and that DOSVEC still points where you expect.
  • Program larger than the sector count. The OS loaded only DBSECT sectors. Recount, or load the rest yourself.

Further reading

  • Mapping the Atari (Ian Chadwick, COMPUTE! Books, 1983): locations 2–15, 576–580 and 768–779, and the DOS boot-record table.
  • Inside Atari DOS, Bill Wilkinson (1982), for DOS 2.0S's own boot code. It's still the standard reference for this.
  • The OS Rev. A source listing on KSquiggle's site. Search for DOBOOT.
  • MADS examples/Boot.asm, a complete multi-sector loader.

Credits