TRS-80 DOS - TRSDOS v2.3 for the Model I - SYS5/SYS Disassembled

SYS5/SYS

Other Navigation

TRSDOS 2.3 SYS5/SYS Disassembly - DEBUG Monitor (Model I)

SYS5/SYS is the interactive DEBUG monitor overlay for TRSDOS 2.3 on the TRS-80 Model I. It loads into the overlay area at 4E00H-51FFH when invoked through the RST 28H supervisor call mechanism with SVC code 87H, or directly via the DEBUG command (which sets bit 7 of system flags byte 430FH and patches the BREAK key handler and error exit vectors in SYS0). SYS5 provides a comprehensive set of debugging tools for examining and modifying the state of a running program.

Upon entry, SYS5 performs a complete CPU context save: it captures all primary registers (AF, BC, DE, HL), alternate registers (AF', BC', DE', HL'), index registers (IX, IY), and the stack pointer, storing them in a 24-byte save area at 4065H-407CH. The stack pointer value saved at 4079H allows the debugger to operate with its own stack space without corrupting the user program's stack. Before entering the command loop, SYS5 also checks for and removes RST 30H breakpoint markers (F7H bytes) that may have been inserted by a previous single-step operation, restoring the original instruction bytes.

The DEBUG command loop displays a register dump showing all 12 register pairs with their current values, including a bit-level flags breakdown for AF and AF' showing the state of each CPU flag (Sign, Zero, Half-carry, Parity/Overflow, Subtract, Carry). It then waits for a single-character command from the keyboard. The supported commands are:

Key	Command	Description
A or H	Set Address	Stores the input value into the current address variable at 405DH
C or I	Instruction Decode	Decodes and displays the Z80 instruction at the current PC, using an opcode classification table to determine instruction length and addressing mode
D	Display Memory	Displays a hex/ASCII dump of 16 bytes at the current display address
G	Go	Resumes execution from the saved PC. Optionally inserts up to 2 RST 30H breakpoints at user-specified addresses before resuming. Restores all registers from the save area and transfers control to the user program.
M	Modify Memory	Allows interactive byte-by-byte memory modification at a specified address, with display of current and new values
R	Register Modify	Searches the register name table for a matching register pair name, then allows the user to enter a new 16-bit hex value for that register in the save area
S	Step	Toggles single-step mode by writing the step flag value to 405EH
U	Wait	Waits for a keypress; loops until a non-zero key is detected
X	Exit Step	Clears the single-step flag at 405EH and exits the debug monitor
;	Scroll Forward	Advances the display address by 64 bytes (one screen line) or by the scroll increment
-	Scroll Backward	Decrements the display address by 64 bytes

The Go command's breakpoint system works by saving the original byte at each breakpoint address, replacing it with F7H (RST 30H opcode), and recording the address. When the program executes the RST 30H, control transfers to the RST 30H handler at 400FH (which SYS0 vectors to the DEBUG entry). Upon re-entry, SYS5 detects and removes the F7H bytes, restoring the original instructions. The Go command also patches the BREAK key handler (4315H-4317H) to route keyboard BREAK to the DEBUG entry point at 400FH.

The instruction decode system at 505DH uses an opcode classification table at 50E0H-512EH. Each table entry is a 3-byte record: a mask byte, a match byte, and a length/type byte. The decoder reads the opcode at the current PC, applies each mask/match pair to classify the instruction, and extracts the instruction length (bits 0-3) and addressing mode (bits 4-7) from the type byte. Prefix bytes (DDH, FDH for IX/IY, EDH for extended instructions) are handled by selecting different sub-tables within the classification data. The addressing mode determines how operands are displayed: immediate values, relative branches, register pairs from the save area, or memory contents.

Variable and Data Area List

Address Range	Purpose
4020H-4021H (2 bytes)	Video RAM cursor/display position (written by SYS5 for screen output positioning)
405DH-405DH (1 byte)	Command character / address input storage (A/H command stores value here)
405EH-405EH (1 byte)	Single-step mode flag (00H = normal, non-zero = step mode active)
4060H-4061H (2 bytes)	Memory modify address pointer (current address for M command)
4062H-4063H (2 bytes)	Breakpoint save area (2 bytes for saving original instruction bytes)
4063H-4064H (2 bytes)	Display address (current address for dump/scroll commands)
4065H-407CH (24 bytes)	Saved register area (12 register pairs: AF, BC, DE, HL, AF', BC', DE', HL', IX, IY, saved-AF, saved-HL)
4079H-407AH (2 bytes)	Saved stack pointer (user program SP before DEBUG took control)
407BH-407CH (2 bytes)	Saved program counter / breakpoint continuation address
4F54H-4F6BH (24 bytes)	Register name display table (12 entries x 2 bytes: two ASCII characters per register pair name)
4F78H-4F7FH (8 bytes)	Flags bit name table: "SZ1H1PNC" (Sign, Zero, fixed-1, Half-carry, fixed-1, Parity/Overflow, Subtract, Carry)
50E0H-512EH (79 bytes)	Z80 opcode classification table (mask/match/type triplets for unprefixed, ED-prefixed, and DD/FD-prefixed instructions)

Major Routine List

Address	Purpose
4E00H	DEBUG Entry Point Saves all CPU registers to 4065H, captures SP, removes breakpoint markers, enters command loop
4E2FH	Breakpoint Cleanup and Timer Dequeue Scans 405DH area for F7H breakpoint bytes and restores originals, dequeues timer callbacks
4E4BH	Command Loop Return Point Restores SP from 4079H, displays registers via 4ECFH, reads command key, dispatches
4E9AH	Step Command (S) Writes command character to 405EH as step mode flag
4E9EH	Wait Command (U) Waits for non-zero keypress via ROM 002BH
4EA8H	Display Command (D) Reads hex address, displays memory at that location
4EAEH	Scroll Forward (;) Advances display address by 64 bytes
4EC6H	Scroll Backward (-) Decrements display address by 64 bytes
4ECBH	Set Address (A/H) Stores command character to 405DH
4ECFH	Register Dump Display Displays all 12 register pairs with hex values, plus flags bit breakdown for AF/AF'
4F80H	Go Command (G) Reads optional breakpoint addresses, inserts F7H markers, patches BREAK handler, restores registers, resumes execution
4FCAH	Insert Breakpoint Saves byte at (HL), writes F7H, records address in breakpoint table at (DE)
4FDBH	Modify Command (M) Interactive memory editor: reads address, displays current byte, accepts new hex value
5011H	Register Modify (R) Reads register name, searches name table, writes new value to save area
505DH	Instruction Decode (C/I) Decodes Z80 instruction at current PC using opcode classification table, displays mnemonic and operands
518AH	Keyboard Input With Echo Scans keyboard via ROM 0049H, echoes printable characters, returns char in A
51A3H	Read Hex Number Reads hex digits from keyboard, builds 16-bit value in HL
51BFH	Hex Digit Converter Converts ASCII hex digit in A to binary 0-15, sets carry if invalid
51D0H	Display Byte as Hex Reads byte from (HL), displays as 2 hex digits
51D4H	Display HL as 4-Digit Hex Displays H then L as 2-digit hex values
51D9H	Hex Byte Output Converts byte in A to 2 hex ASCII chars via nibble splitter at 51E2H
51F2H	Print Space Outputs ASCII space (20H) via ROM 0033H
51F6H	Print Two Characters Reads and prints 2 consecutive bytes from (HL), advancing HL by 2

Cross-Reference Notes

SYS5 is invoked by SYS0 via SVC code 87H. It can also be entered through the RST 30H vector at 400FH when the DEBUG command has been activated (patching 4315H to JP 400FH). SYS5 calls ROM routines 0033H (character output), 0049H (keyboard scan), and 002BH (wait for keypress). The Go command at 4F99H patches the SYS0 BREAK key handler at 4315H-4317H to redirect BREAK to 400FH for debug re-entry. SYS5 also interacts with the RST 28H dispatcher at 4E97H (RST 28H / RET sequence) for unknown commands.

4E00H - DEBUG Entry Point

Main entry point for the DEBUG monitor overlay. Saves all CPU registers (primary, alternate, and index) to the register save area at 4065H, captures the stack pointer, and adjusts the stack for debugger operation. Called when RST 30H is executed (via the 400FH vector) or when SVC 87H is invoked directly.

4E2FH - Breakpoint Cleanup and Timer Dequeue

Scans up to 2 breakpoint entries in the 405DH area. For each entry, if the address is non-zero, checks whether the byte at that address is still F7H (RST 30H). If so, restores the original byte that was saved when the breakpoint was inserted. After cleanup, zeroes out the breakpoint entry. This ensures that any breakpoints from a previous Go command are removed before the debugger accepts new commands.

4E4BH - Command Loop Entry Point

Main command loop for the DEBUG monitor. Restores the debugger stack pointer, calls the register dump display, reads a command character from the keyboard, and dispatches to the appropriate handler based on ASCII value. Each handler returns to 4E4BH (pushed on the stack at 4E63H) to re-enter the loop. Unrecognized commands invoke RST 28H (which triggers the overlay loader to attempt loading a different overlay, effectively treating the unknown command as an SVC code).

4E99H - Exit Step Mode (X Command)

Clears the single-step flag and returns to the command loop. The XOR A sets A=00H, which falls through to 4E9AH to store 00H in the step flag, effectively disabling single-step mode.

4E9AH - Step Mode Toggle (S Command)

Stores the command character (53H = 'S' for step, or 00H from X command) into the single-step flag at 405EH. When non-zero, the Go command will insert a single-step breakpoint.

4E9EH - Wait for Keypress (U Command)

Waits in a tight loop for a non-zero keypress from the keyboard, providing a simple pause function. Useful when single-stepping to pause between steps until the user is ready.

4EA8H - Display Memory (D Command)

Reads a hex address from the keyboard and displays a hex/ASCII memory dump at that address. Falls through to the scroll forward handler to perform the actual display.

4EAEH - Scroll Forward (; Command)

Advances the display address by 64 bytes (one screen row of hex dump) or by the configured scroll increment. If the step flag is non-zero, advances by 256 bytes instead.

4EC6H - Scroll Backward (- Command)

Decrements the display address by 64 bytes by adding the two's complement value FFC0H.

4ECBH - Set Address (A/H Command)

Stores the command character ('A' = 41H or 'H' = 48H) into the address variable at 405DH. This variable is used by other commands to determine addressing mode.

4ECFH - Register Dump Display

Displays all 12 register pairs with their current hex values from the save area at 4065H. For the AF and AF' registers (detected when the loop counter B AND 0BH equals 08H), an additional flags bit breakdown is shown using the flags name table at 4F78H ("SZ1H1PNC"). For non-flags registers, the display includes an "=>" prefix followed by the memory contents at the register pair's address. Two display modes exist: normal mode (step flag = 0) clears the screen and shows 12 lines; step mode (step flag non-zero) shows a compact 16-register display without clearing.

4F45H - Step Mode Register Display (Compact Format)

When single-step mode is active, displays a more compact register dump without clearing the screen. Positions the cursor at the bottom of the display area and shows 16 lines of register data in a condensed format suitable for continuous stepping.

4F54H - Register Name Display Table

Lookup table of 12 two-byte entries, each containing the two ASCII characters of a register pair name. Used by the register dump display loop at 4ECFH to label each register value. The entries are in the same order as the saved register values at 4065H: AF, BC, DE, HL, AF', BC', DE', HL', IX, IY, SP, PC.

4F78H - Flags Bit Name Table

Eight ASCII characters representing the Z80 flags register bits from bit 7 (most significant) to bit 0 (least significant). Used by the flags breakdown display at 4F0BH.

4F80H - Go Command (G)

Resumes execution of the user program from the saved PC address. Optionally reads up to 2 breakpoint addresses from the keyboard and inserts RST 30H (F7H) breakpoint markers at those addresses. Patches the BREAK key handler to redirect to the DEBUG entry point. Then restores all saved registers from 4065H and transfers control to the user program via the saved PC at 407BH.

4FCAH - Insert Breakpoint

Saves the original byte at address (HL), writes the RST 30H opcode (F7H) in its place, and records the breakpoint address and saved byte in the breakpoint save area at (DE). Includes a write-verify check to ensure the F7H was successfully written (protecting against ROM or write-protected areas).

4FDBH - Modify Memory (M Command)

Interactive memory editor. Reads a starting address from the keyboard, then enters a loop displaying the current byte at that address and accepting a new hex value. Pressing Enter without a value advances to the next byte. Pressing Enter at the address prompt returns to the command loop.

5011H - Register Modify (R Command)

Reads a two-character register name from the keyboard, searches the register name table at 4F54H for a match, and if found, reads a new 16-bit hex value and stores it in the corresponding position in the register save area at 4065H. Supports an optional third character for the alternate register apostrophe.

505DH - Instruction Decode (C/I Command)

Decodes and displays the Z80 instruction at the current saved PC address. Uses the opcode classification table at 50E0H-512EH to determine the instruction's length and addressing mode based on the first (and optionally second) opcode byte. Handles prefix bytes DDH (IX), FDH (IY), and EDH (extended instructions) by selecting different sub-tables within the classification data. The complete instruction decode system displays the instruction address, raw bytes, and formatted operands.

50E0H - Z80 Opcode Classification Table

Lookup table used by the instruction decoder at 505DH to classify Z80 opcodes. Each entry is 3 bytes: a mask, a match value, and a length/type byte. The decoder applies (opcode AND mask) == match to find the matching entry. The length/type byte encodes: bits 0-3 = total instruction length in bytes, bits 4-7 = operand display/addressing mode (00=none, 10=HL-indirect, 20=IX/IY, 30=relative branch, 40=stack-read, 50=SP-indirect, 60=execute/step). Three sub-tables exist: main table at 50E0H for unprefixed opcodes, ED-prefix table at 510EH, and DD/FD-prefix table at 5115H.

5131H - Memory Dump Line Display

Displays a line of hex dump: saves BC, prints "=>" separator, space, then 16 hex bytes from (HL) with ASCII character representation. After the hex bytes, displays the corresponding ASCII characters (replacing non-printable bytes with '.'). Advances HL by 16 bytes. Used by both the register dump (showing memory at register addresses) and the main memory dump display.

5165H - Byte Display With PC Highlight

Displays a single byte from memory at (HL) as hex, with special highlighting when the address matches the saved program counter at 4060H. The PC byte is displayed with a special marker character (95H = inverse block) instead of a leading space.

518AH - Keyboard Input With Echo

Reads a single character from the keyboard using ROM 0049H (non-blocking scan), waiting in a loop until a key is pressed. Printable characters (20H and above) are echoed to the screen. Returns with A=character, Z FLAG set if Enter (0DH), CARRY set if Enter with comma or space preceding.

51A3H - Read Hexadecimal Number

Reads hex digits from the keyboard and builds a 16-bit value in HL. Each digit shifts HL left by 4 bits and ORs in the new digit value. Continues reading until a non-hex character is entered. Returns Z FLAG if Enter pressed with no digits, CARRY if Enter pressed, NZ with value in HL if valid hex entered.

51BFH - Hex Digit Converter

Converts an ASCII hex digit character in Register A to its binary value (0-15). Returns with A = digit value (0-15) and CARRY clear if valid, or CARRY set if the character is not a hex digit (0-9, A-F).

51D0H - Display Byte From Memory as Hex

Reads a byte from (HL), displays it as 2 hex digits, and increments HL.

51D4H - Display HL as 4-Digit Hexadecimal

Outputs the 16-bit value in HL as 4 hex digits (H byte first, then L byte).

51D9H - Hex Byte Output

Converts a byte in Register A to two hexadecimal ASCII characters and outputs them via ROM 0033H. High nibble first, then low nibble. Uses the standard hex conversion algorithm: nibble + 30H, adjust by +7 if >= 3AH.

51EFH - Hex Byte Output With Trailing Space

Outputs a byte as 2 hex digits followed by a space. Used in the register dump display.

51F2H - Print Space

Outputs a single ASCII space character (20H) via ROM 0033H.

51F6H - Print Two Characters From Table

Reads and prints two consecutive bytes from the address in HL, advancing HL by 2. Used by the register dump display to output register pair names from the name table.

51FCH - Print Character From Table

Reads a single byte from (HL), increments HL, and outputs the byte as a character via ROM 0033H.