ZX Spectrum ROM disassembly

Every 48K Spectrum carries a 16 KB program it cannot forget, in ROM at $0000-$3FFF. It is the BASIC you type into, but it is also a library. Fifty times a second on a British machine it stops whatever else is running to update a clock and read the keyboard, and its routines for printing, clearing the screen and sounding the speaker sit at fixed addresses that any machine-code program can call. The catch is that the routines were written to serve BASIC. Each expects its input in particular registers or system variables, most leave side effects behind, and some can only be reached from BASIC at all.

Spectrum owners mapped it themselves. In December 1982 a reader wrote to Sinclair User with a warning about RST $10, the ROM’s print routine: it “is also used to output characters to the printer and microdrives, so to be sure of screen output place at the beginning of any routine the instructions” LD A,02h and CALL 1601h. A month later Ian Logan and Frank O’Hara signed the preface to The Complete Spectrum ROM Disassembly (Melbourne House, 1983), which prints the whole ROM as commented Z80 assembly language and names every routine. The book’s story is on its own entry. The names and addresses below are the book’s, checked against the ROM’s bytes.

The authors describe the ROM as “developed directly from the 4K program of the ZX 80”, and say its programmers “have always however been short of ‘room’ and hence the program is written for ‘compactness’ rather than ‘speed’”. That trade-off decides which routines a game borrows and which it rewrites.

What is where

• $0000-$0038: the eight restart vectors, the targets of the one-byte RST instructions.
• $0038: the maskable-interrupt routine, reached every 20 ms in interrupt mode 1, which the ROM selects when the machine starts.
• Up to $386D: the BASIC interpreter and everything it uses: the keyboard and tape routines, screen and printer output, channels and streams, error handling, expression evaluation and the floating-point calculator.
• $386E-$3CFF: unused. The book notes that these locations are “spare” and “all hold +FF”.
• $3D00-$3FFF: the 768-byte character set.

The ROM keeps its working state in RAM, in the system variables at $5C00-$5CB5 (23552-23733), just above the printer buffer. It reads and writes them constantly, and a machine-code program can do the same.

The restarts

RST n is a one-byte call to one of eight fixed addresses, where CALL takes three bytes, and the ROM uses the restarts for the routines it calls most often: printing, reading the next character of a BASIC line, the calculator. The book’s names:

A game usually meets two of these: RST $10 for printing and, as long as it leaves interrupt mode 1 on, RST $38. RST $08 is worth knowing because the ROM’s own routines use it when something is wrong. CHAN-OPEN, for example, ends in report O, “Invalid stream”, if it is given a stream that is not open, and the error handler abandons the machine-code program and goes back to BASIC.

The interrupt: $0038

The book sums it up in one sentence: “The real time clock is incremented and the keyboard scanned whenever a maskable interrupt occurs.” MASK-INT adds one to the low two bytes of FRAMES, adds one to the third byte when they wrap round to zero, and calls KEYBOARD at $02BF. KEYBOARD scans the keys and, once the repeat delay allows it, puts the new key’s code in LAST-K. All of this happens between two instructions of your program every 20 ms, unless you disable interrupts with DI or install your own interrupt-mode-2 handler.

Routines a game calls

Printing: RST $10

The character in A goes to whichever channel is current, and that is not always the one you expect. A program started with RANDOMIZE USR often finds channel K, the lower screen, current, unless the BASIC before it has just printed something. Its text then goes to the bottom two lines, and the “0 OK” report wipes it out as soon as the program returns. The fix is the one Sinclair User’s reader gave in 1982: open stream 2, the upper screen, first.

        ld      a,2
        call    $1601           ; CHAN-OPEN: stream 2 = upper screen
        ld      hl,text
loop:   ld      a,(hl)
        or      a
        ret     z
        rst     $10             ; PRINT-A-1 -> PRINT-A-2
        inc     hl
        jr      loop

text:   defm    "HELLO"
        defb    0

The ROM does the rest. PRINT-OUT understands the same control codes as BASIC’s PRINT: 22 (AT) followed by a row and a column, 16 to 21 for INK, PAPER, FLASH, BRIGHT, INVERSE and OVER, each followed by a value, and 13 for a new line. A game that prints its score through the ROM gets positioning and colour for a few bytes of control codes. What it pays is speed: the book calls PRINT-OUT “rather slow”, because it checks every option for every byte it puts on the screen.

CLS: $0D6B

In the book’s words, “the whole of the display is ‘cleared’ - the ‘pixels’ are all reset and the attribute bytes are set to equal the value in ATTR-P - then the lower part of the display is reformed.” Set ATTR-P ($5C8D) first and the ROM clears to your colours. The lower two lines take their colours from BORDCR instead. CLS finishes by opening channel K, so a program that calls it and then prints needs LD A,2 / CALL $1601 again.

The direct alternative is two LDIRs, one for the 6,144-byte bitmap and one for the 768 attribute bytes:

        ld      hl,$4000
        ld      de,$4001
        ld      bc,6143
        ld      (hl),0
        ldir                    ; bitmap
        ld      hl,$5800
        ld      de,$5801
        ld      bc,767
        ld      (hl),$38        ; black ink on white paper
        ldir                    ; attributes

It takes 26 bytes, keeps no records, and uses whatever colours you give it. The attribute byte holds the paper colour in bits 3-5 and the ink in bits 0-2, so $38 is white paper (7) with black ink (0), the Spectrum’s colours at switch-on.

BORDER: $2294

The ROM’s BORDER is the BASIC command itself, not a subroutine with a register interface. It fetches its parameter from the calculator stack with FIND-INT1, compares it with 8, and gives report K, “Invalid colour”, if it is too big. What it does next is the instructive part. It writes the colour to port $FE, multiplies it by eight to move it into the paper bits, and stores the result in BORDCR, the attribute byte for the lower screen. On a dark border it first XORs in 7, making the lower screen’s ink white; on a light one (green, cyan, yellow or white) it leaves the ink black. After BORDER 2, BORDCR holds 23: red paper, white ink. After BORDER 5 it holds 40: cyan paper, black ink.

A game does the first step itself:

        ld      a,2
        out     ($FE),a         ; red border

If it will return to BASIC it should update BORDCR the same way, so that the editor does not come back with unreadable text on the lower screen. The other bits of port $FE drive the speaker and the MIC socket; see hardware ports.

BEEPER: $03B5

DE holds the frequency multiplied by the duration in seconds, and HL the length of the timing loop in T-states divided by 4. The book works through middle C. At 261.63 Hz on a 3.5 MHz clock the speaker has to be switched “as close as possible to every 6,689 T states”, so for one second DE is $0105 and HL is $066A, “derived from 6,689/4 - 30.125”. BEEPER’s first instruction is DI, “Disable the interrupt for the duration of a ‘beep’”, so FRAMES stops and the keyboard goes unread until the note ends. Its last is EI, which switches interrupts back on whether or not they were on before. Beeper music tells what programmers did when they wanted more than one note at a time.

KEY-SCAN: $028E

KEY-SCAN returns a key value, not a character. E is a number from $00 to $27, a different one for each of the forty keys; D holds the value of a shift key if one is down; DE is $FFFF when nothing is pressed. It scans the eight half-rows of the keyboard one at a time, and gives up as soon as it finds a third key. A game that needs several keys at once, such as fire while moving diagonally, reads port $FE itself, as described under hardware ports. A game that only wants “press any key” can call KEY-SCAN and test for $FFFF.

The character set: $3D00-$3FFF

The ROM holds 96 characters, codes $20 (space) to $7F (©), each eight bytes deep, top row first:

Address = $3D00 + ((code - 32) × 8)

The book’s example is the letter A, at $3E08: 00 3C 42 42 7E 42 42 00.

+0    $00   ........
+1    $3C   ..████..
+2    $42   .█....█.
+3    $42   .█....█.
+4    $7E   .██████.
+5    $42   .█....█.
+6    $42   .█....█.
+7    $00   ........

The system variable CHARS ($5C36) holds $3C00, 256 less than the start of the table, so that the ROM can find a character from its code without first subtracting 32. Point CHARS at a table of your own in RAM and every ROM print uses your font. To draw with the ROM’s letters yourself:

        ld      a,'A'
        sub     32
        ld      l,a
        ld      h,0
        add     hl,hl
        add     hl,hl
        add     hl,hl           ; × 8
        ld      bc,$3D00
        add     hl,bc           ; HL -> eight bytes of 'A'

System variables: $5C00-$5CB5

The ones a game is most likely to read or write, with the descriptions from the Spectrum manuals:

FRAMES

FRAMES is the machine’s clock. The Spectrum’s manual introduces it to BASIC programmers: “The one that increases most often is PEEK 23672. Every 1/50 second it increases by 1.” It also warns that the clock “stops temporarily whenever you do BEEP, or a cassette tape operation, or use the printer”, because those routines turn interrupts off.

For a game, FRAMES is a free frame counter. This loop waits until the next interrupt has been and gone:

        ld      hl,$5C78
        ld      a,(hl)
wait:   cp      (hl)
        jr      z,wait

HALT does the same in one instruction. Both depend on the interrupt: with interrupts off, or with an interrupt-mode-2 handler that does not call the ROM’s, FRAMES never changes and the loop never ends. What the counter offers that HALT does not is a record. A game can save FRAMES, do a variable amount of work, and then see how many frames went by.

See also

• ZX Spectrum
• The Complete Spectrum ROM Disassembly, the book these names come from
• Ian Logan
• Steven Vickers, who wrote most of the ROM
• Z80, the processor these routines are written for
• ULA, the chip that OUT ($FE),A talks to
• ZX Spectrum hardware ports
• Beeper music
• User-defined graphics
• Sinclair BASIC, the interpreter this ROM holds
• Machine code for beginners