mcdis

This program is a Z80 machine code disassembler and development toolkit designed to be merged into an existing BASIC program, with all line numbers starting at 7999. It relies on a companion machine code block (“mcdiscode”) loaded at address 62720 that handles the actual Z80 instruction decoding, with the BASIC layer providing a menu-driven interface for disassembly, hex/decimal conversion, memory peeking, and a simple address dictionary for labeling. The disassembler reads decoded instruction text from address 65216, uses PEEK 64973 to determine operand type, and dispatches to subroutines for relative jumps (including proper signed-offset calculation for JR and DJNZ) and address lookups. A custom hex-input function, defined via DEF FN, converts both digit and lowercase-letter hex characters to numeric values. The dictionary feature stores 8-byte records (2-byte address plus 6-character label) growing downward from address 63080, and a machine code search routine at 62720 performs label lookups during disassembly output.

---

Program Analysis

Program Structure

The program is organized as a menu-driven toolkit with line numbers starting at 7999, explicitly designed to be merged with a user’s existing BASIC program. The entry point at line 7999 branches to 8183 (initialization), and the menu at line 8000 lists eight functional areas by their starting line numbers.

Line Range	Function
7999–8029	Entry point, initialization branch, menu display
8102	Hex-digit conversion function (DEF FN)
8110–8128	Hex loader (POKE bytes into memory) and address input subroutine
8130–8174	Disassembler main loop
8180–8188	Machine code loader and variable initialization
8190–8196	Decimal-to-hex conversion subroutine
8210–8214	Decimal-to-hex display utility
8220–8229	Operand dispatcher (reads PEEK 64973 type flag)
8230–8252	Dictionary entry (label assignment to an address)
8260–8288	Dictionary lookup and display during disassembly
8290–8293	Hex-to-decimal converter (interactive)
8300–8329	Instruction display with color coding and JR offset resolution
8350–8385	Memory peek utility with hex, decimal, and CHR$ display
8990–8996	Save routine (BASIC + machine code block)
8999	REM credits line
9000–9006	Extended help text (intended for deletion after familiarization)

Machine Code Integration

The core disassembly engine resides in a 2560-byte machine code block loaded at address 62720 via LOAD "mcdiscode" CODE. The BASIC program communicates with it through a shared memory interface:

• POKE 64044/64045/64046 — pass the address to disassemble (low and high bytes)
• POKE 64973,0 — clear the operand-type flag before calling the routine
• RANDOMIZE USR 65040 — invoke the disassembler; decoded mnemonic text is written to 65216
• PEEK 64973 — read back operand type: 0 = none, 1 = byte/offset operand, 2 = word/address operand
• PEEK 64974 / PEEK 64975 — retrieve the operand byte(s)
• PEEK 64045 / PEEK 64046 — read back the updated program counter after disassembly

A second machine code routine at 62720 (invoked via USR 62720 after poking a target address into 62728/62734) performs the dictionary label search, returning either a pointer to a matching 6-character label or 0 if not found.

Key BASIC Idioms and Techniques

The hex-digit conversion at line 8102 uses DEF FN v(v$)=CODE v$-48-39*(CODE v$>96). Subtracting 48 converts ASCII digits 0–9 to 0–9; the additional -39*(CODE v$>96) handles lowercase a–f, where CODE "a"=97, so 97-48-39=10 as required. This is a compact single-expression function avoiding any branching.

The decimal-to-hex conversion subroutine at lines 8192–8196 builds the hex string right-to-left using repeated modulo-16 extraction and indexing into h$="0123456789ABCDEF", terminating when the result is exactly 4 characters. The result is placed in n$ for use by the caller.

The address input subroutine (lines 8121–8128) supports toggling between decimal and hex entry: entering "0" flips the h flag with LET h=NOT h and loops back to re-prompt. Four-nibble hex input is parsed using four successive calls to FN v() with positional weights 4096, 256 (tfs), 16 (sx), and 1.

Disassembly Loop

The main disassembly loop (lines 8131–8174) operates as follows:

1. Call address input subroutine (GO SUB 8120) to get starting address n
2. Print address (decimal or hex depending on h)
3. Decompose n into high/low bytes and POKE into 64045/64046
4. Call machine code disassembler via RANDOMIZE USR 65040
5. Read mnemonic text from 65216 into i$ by scanning for a zero terminator
6. Display mnemonic with optional INK 2 coloring for jump instructions
7. Dispatch operand display via GO SUB 8220 based on PEEK 64973
8. Advance n from updated PC in 64045/64046 and loop

Jump Target Resolution

Lines 8310–8329 handle relative jump operands for JR and DJNZ instructions. The signed offset is read from PEEK 64974 and the resolved absolute address is computed as n+2+oo-tfs*(oo>=128), where subtracting 256 when the offset byte is ≥ 128 correctly implements two’s-complement sign extension. The result is then displayed as either hex or decimal according to the h flag.

Dictionary System

The dictionary stores 8-byte records growing downward from end=63080. Each record consists of a 2-byte little-endian address followed by a 6-character label. Adding an entry (lines 8230–8252) prompts for an address and a label, POKEs the data, then decrements end by 8. The machine code search routine at 62720 receives the target address in 62728/62734 and scans the dictionary, returning either the address of the matching label string or 0 for no match.

Memory Peek Utility

Lines 8350–8385 implement a memory browser displaying each byte as a 4-digit hex address, 5-digit decimal value, 2-digit hex byte, decimal byte value, and the CHR$ character (suppressed for values below 32). The hex address display reuses the n$/8190 subroutine, and decimal values are right-justified to 5 characters using a string-padding loop at lines 8357–8357 (a GO TO-based loop prepending spaces until LEN v$=5).

Variable Conventions

Variable	Purpose
tfs	256 — used as the high-byte multiplier (“two fifty-six”)
sx	16 — used as the nibble multiplier (“sixteen”)
h	Flag: 1=hex display/input mode, 0=decimal
h$	“0123456789ABCDEF” — hex digit lookup string
n	Current memory address being processed
n$	Hex string result from conversion subroutine
end	Current top of dictionary storage (grows downward from 63080)
d$	Label string retrieved from dictionary
i$	Decoded mnemonic string from disassembler output buffer

Notable Anomalies

Line 8120 is the target of GO SUB 8120 calls but does not appear in the listing — execution falls through to line 8121, which is the actual start of the address input subroutine. This is a standard technique where the GO SUB target line simply doesn’t exist and execution continues at the next available line.

Line 8183 is the target of the initial GO TO 8183 at line 7999, but it does not appear as an explicit line in the listing; line 8184 contains the variable initialization. After saving and reloading, execution resumes at 8184 via SAVE "mcdis" LINE 8180, which causes the loader to run first.

The CLEAR 62719 at line 8180 sets RAMTOP just below the machine code block, protecting it from BASIC memory management before the LOAD "mcdiscode" CODE at 8182 places the code at 62720.