Spectrum Disassembler

This program is a Z80 disassembler that decodes machine code bytes in memory and outputs human-readable Z80 assembly mnemonics. It handles the full Z80 instruction set including the CB, DD, ED, and FD prefix bytes, correctly resolving IX and IY indexed addressing. A lookup system using RESTORE and READ with computed DATA-line addresses decodes each opcode’s mnemonic, source, and destination fields from compact string tables. Optional features include byte-sequence searching, jump-following with optional address relocation, and output routing to screen, printer, or serial (TTY) streams via OPEN #3.

---

Program Structure

The program is organized into several functional regions:

• Lines 10–24: Byte-sequence locator — scans memory for a user-specified byte pattern.
• Lines 100–180: Opcode fetch and prefix handling — reads the next byte, classifies DD/FD/CB/ED prefixes.
• Lines 200–280: Opcode decoding — computes a DATA line address from the opcode fields and reads the mnemonic.
• Lines 300–730: Output formatting — wraps operands in parentheses, prints address, mnemonic, and optional raw bytes.
• Lines 800–997: Subroutine for argument substitution (GOSub 900) — handles relative offsets (u), immediate bytes (v), 16-bit words (w), register-pair substitution (y), and address relocation.
• Lines 1001–4078: DATA tables — all opcode mnemonic/operand/flag triples.
• Lines 4500–4560: Interactive menu — output routing, byte display toggle, locate, relocate, and jump-follow controls.
• Lines 4600–4630: Byte-sequence search configuration.
• Lines 4900–6000: Initialization — string tables for registers, conditions, ALU ops, rotation ops, and block instructions.

Opcode Decoding Technique

The heart of the disassembler is the computed RESTORE trick at line 200. The Z80 opcode byte q is decomposed into three octal fields:

• a = bits 7–6 (the “x” field in standard Z80 notation), range 1–4
• b = bits 5–3 (the “y” field), range 1–8
• c = bits 2–0 (the “z” field), range 1–8
• d = INT(b/2)+1, the register-pair index
• e = b - 2*d + 3, the odd/even parity of b

These fields are combined into a DATA line number: k*1000 + a*100 + c*10 + e - 111, where k is 1 for unprefixed, 2 for CB-prefixed, and 3 for ED-prefixed instructions. The program then does RESTORE to that line and reads the mnemonic. If the DATA entry starts with ">", a secondary redirect reads two further values to construct a new RESTORE target, allowing irregular opcode encodings to be handled without a full table entry for every combination.

Argument Substitution (GOSub 900)

Operand placeholders in the DATA entries are single lowercase letters read from b$ and c$. The subroutine at line 900 substitutes them as follows:

Code	Meaning
u	Signed 8-bit relative offset (for JR, DJNZ) — computes absolute target from p
v	Unsigned 8-bit immediate
w	16-bit little-endian word — also triggers address relocation if in range
y	Current index register (HL, IX, or IY)
↑	Undefined/invalid opcode sentinel — triggers error output at line 850

The flag variable i is set to 1 whenever a y substitution occurs; this is used at line 280 to suppress DD/FD-prefixed instructions that do not actually reference the index register (falling back to the HL form).

String Tables

All register and condition-code strings are stored as fixed-width string arrays initialized at lines 5000–5080. Substrings are extracted by index arithmetic (2*z-1 TO 2*z or 3*z-2 TO 3*z, etc.):

• r$: 8-character string for 8-bit registers B, C, D, E, H, L, (HL), A — with x as a placeholder for the indexed form.
• s$(z): 16-bit register pairs BC, DE, HL/IY/IX, SP.
• t$(z): Stack register pairs BC, DE, HL/IY/IX, AF.
• q$(z): Condition codes NZ, Z, NC, C, PO, PE, P, M.
• x$(z): ALU operations ADD, ADC, SUB, SBC, AND, XOR, OR, CP.
• w$(z): Rotation/shift operations RLC, RRC, RL, RR, SLA, SRA, undefined, SRL.
• v$(z): Miscellaneous accumulator operations RLCA, RRCA, RLA, RRA, DAA, CPL, SCF, CCF.
• y$(z): Block instruction suffixes for LDI/LDD/LDIR/LDDR and related.
• u$(z): Block instruction prefixes LD, CP, IN.
• p$: Interrupt mode values 0, ↑, 1, 2 (with invalid entries marked).
• o$: Used as a dummy second operand for ED-prefix instructions that have invalid variants.

Output and I/O Routing

All disassembly output goes to stream #3. At line 105, CLOSE #3 followed by OPEN #3,f$(1) sets the output channel. The menu at line 4500 allows switching f$ between "Scr/Pri/Tty", "Pri/Tty/Scr", and "Tty/Scr/Pri", effectively cycling the primary output target among screen, printer, and serial TTY. The FORMAT command at line 4512 sets the TTY baud rate to 300.

Line 700 formats each instruction as a fixed-width line: address left-padded in a 6-character field (l$(7 TO) for the mnemonic), followed by operands. When the byte-display flag s is set, raw decimal byte values are printed alongside, with a printable-character column using CHR$(PEEK z AND (g<16 OR g>23)) — the AND expression masks non-printable control character ranges to zero.

Line 730 includes POKE 23692,255 to reset the scroll counter (preventing the “scroll?” prompt) each time a line is printed.

Jump Following and Address Relocation

When jump is enabled (toggled via the menu), the program pauses at JP, JR, CALL, and RET instructions and asks the user whether to follow. An empty response causes the program counter p to be set to the branch target decoded from c$ or b$.

When shift is non-zero, every 16-bit word operand (w placeholder) that falls within the range [start, end] is adjusted by adding shift and the modified bytes are written back into memory via two POKE calls. The adjusted value is also appended to the disassembly output with a >= annotation. This is a relocation patching feature intended for moving code blocks.

Byte-Sequence Locator

Lines 10–24 implement a simple memory scanner. The user specifies up to b bytes to locate, stored in string h$. Line 20 walks address a forward comparing PEEK a against CODE h$ (the first byte). Line 22 then verifies the remaining bytes with a FOR loop. Matches are printed to stream #3. Pressing Space interrupts and returns to the menu. The INKEY$ check at line 20 inside the scanning loop doubles as a fast interrupt mechanism.

Error Handling and Invalid Opcodes

Invalid or undefined Z80 opcodes are represented in the DATA tables by the sentinel string "↑". When detected at line 240 or in the argument subroutine at line 945, the program jumps to line 850, which sets the mnemonic to n$ (a flashing inverse ? character defined at line 4990 using CHR$ 18 + CHR$ 1 + "?"), sounds a short beep, sets s=1 to enable byte display, and continues output.

Notable Bugs and Anomalies

• Line 200 uses LET a=... for the opcode field, overwriting the variable a used in the byte locator (lines 10–24). These two features cannot be used simultaneously without state corruption, though in practice they are separate operational modes.
• The r$ entry for register index 7 (the (HL) form) is "x", which is the same placeholder character used for DD/FD indexing. The logic at line 280 uses the i flag to disambiguate, but relies on the argument substitution subroutine having been called.
• Line 4074 uses a substring extraction from a literal string "OUTIOUTDOTIROTDR" keyed on b, covering the four block output/input instructions. The computation 4*b-3 TO 4*b extracts 4-character mnemonics, which is valid for OUTI (b=1), OUTD (b=2), OTIR (b=3), OTDR (b=4).
• The NOT PI expression evaluates to 0 (since PI is non-zero, NOT PI = 0), and is used as the g flag throughout the DATA tables to indicate “no parentheses wrapping,” making it a semantic zero constant rather than a meaningful flag value.