TRS-80 DOS - LDOS 5.3.1 for the Model I - SYS5/SYS Disassembled

SYS5/SYS

Other Navigation

LDOS 5.3.1 SYS5/SYS Disassembly - DEBUG Monitor (Model I)

SYS5/SYS is the LDOS 5.3.1 DEBUG overlay for the TRS-80 Model I. It is the interactive machine-language monitor that the operating system enters whenever the user issues the DEBUG command, whenever a planted breakpoint fires, or whenever a program transfers control to the DEBUG re-entry hook. DEBUG lets the user inspect and change the Z80 register set, examine and patch memory in hexadecimal or ASCII, set execution breakpoints, single-step or trace through code, and resume execution.

Like every other LDOS system overlay, SYS5/SYS is not resident. It is pulled in from disk by the resident RST 28H supervisor at SYSRES address 4BF5H, loaded into the overlay region beginning at 4E00H, and given control at its transfer address 4E00H. When DEBUG first gains control it takes a complete snapshot of the caller's Z80 registers into the resident DEBUG save area DBGSV$ (405DH-407CH), then runs its own command loop until the user resumes the program with the G (Go) command, at which point the saved registers are reloaded and control returns to the program under test.

The overlay reaches the interactive user only through the resident kernel. It calls SYSRES routines for none of its disk work (DEBUG performs no direct disk I/O once it is loaded); instead it drives the screen and keyboard through the Model I ROM (character output at 0033H, keyboard scan at 002BH and 0049H) and manipulates the resident video Device Control Block DODCB$ cursor field at 4020H to place its display. Breakpoints are implemented by overwriting the target instruction with an RST 30H opcode (F7H); when that RST fires it vectors through ROM 0030H to the resident hook at 400FH, which re-enters this overlay so the saved-register snapshot can be rebuilt.

Two regions of the overlay are pure data that the source-listing disassembler renders as meaningless instructions: the register/flag name table at 4F53H-4F7EH, and the three instruction-length/type lookup tables at 50E0H-5130H that drive the single-step next-address calculation. Both are documented here as data.

Program Variables and Work Areas (in resident SYSRES DBGSV$ and DODCB$)

DEBUG keeps all of its state in the resident SYSRES DEBUG save area DBGSV$, which begins at 405DH. The low six bytes are shared: on entry they hold the two-entry breakpoint table, but while the user is browsing interactively DEBUG reuses the same bytes as its display-mode flags. The register snapshot occupies the upper 24 bytes.

Major Routines

Cross-Reference Notes

SYS5/SYS is entered by the resident RST 28H overlay loader at SYSRES 4BF5H and by the RST 30H breakpoint hook at 400FH. It reads and writes the resident DEBUG save area DBGSV$ (405DH), the video DCB cursor field 4020H, and the hooks/state bytes 4310H-4317H, all of which live in SYS0/SYS (SYSRES). It calls no other SYS overlay. Its only external calls are to the Model I ROM: 002BH (scan keyboard), 0033H (display character), and 0049H (wait for a key).

4BC9H - Resident Load Block

A two-byte block deposited by the overlay loader into the SYSRES padding at 4BBCH-4BCAH, just ahead of the resident execute-drive-operation routine at 4BCBH. It is data, not executed on the DEBUG path. Each SYS overlay leaves its own two bytes here (SYS1 wrote F9H 03H, SYS2 wrote 00H 04H, SYS3 wrote A6H 02H, SYS4 wrote AFH 03H, SYS5 writes FFH 03H).

4E00H - DEBUG Entry: Full Register Save

The overlay transfer address. On entry the caller's registers are exactly as they were when DEBUG was invoked (via the RST 28H DEBUG request, or via an RST 30H breakpoint that vectored through the resident hook at 400FH). This block captures every Z80 register so the user can inspect and later restore them.

4E23H - Breakpoint PC Fix-up

DEBUG plants breakpoints as an RST 30H opcode (F7H). When one fires, the CPU has already advanced the program counter past the F7H byte, so the saved PC points one byte too high. This block detects that case and backs the PC up onto the breakpoint.

4E2FH - Clear Breakpoint Table and Restore Bytes

DEBUG keeps a two-entry breakpoint table in the resident save area at 405DH-4062H. Each entry is a two-byte address followed by the one original opcode byte that the F7H breakpoint overwrote. This loop restores those original bytes and zeroes the table so the same six bytes can be reused as display flags while the user browses.

4E49H - Main Command Loop and Dispatch

The heart of DEBUG. It resets the stack, repaints the display, positions the cursor on the bottom screen line, reads one command key, and dispatches to the handler for that key. Every command handler returns here (its return address is pushed at 4E5EH) so DEBUG loops until the user issues the Go command.

4E99H - Display Mode Command Handlers

Short handlers for the display-control keys. The x and s keys set the screen-layout flag at 405EH; u enters a live update loop; d sets the memory window address; ; and - scroll it; a and h set the memory-display mode at 405DH. Each returns to the command loop at 4E49H pushed on the stack.

4ECFH - Screen Refresh: Register and Memory Display

Repaints the DEBUG screen. In the register layout it prints twelve lines, one per register pair (AF, BC, DE, HL, AF', BC', DE', HL', IX, IY, SP, PC), each showing the register value, and for AF and AF' a decoded flag field, followed by the sixteen memory bytes that register points at. If the full-memory flag at 405EH is set it hands off to 4F44H instead.

4F2EH - Memory-Window Painter (Register Screen)

The lower part of the register screen. After the twelve register lines, four lines of the memory window at 4063H are painted. The per-line loop at 4F33H is shared with the full-memory screen, which enters it with a line count of sixteen.

4F44H - Full-Screen Memory Display

Reached when the full-memory layout is selected by the s command. It paints sixteen lines of memory, each showing an address and sixteen bytes, starting at the memory window address held at 4063H.

4F53H - Register and Flag Name Table (Data)

Non-executable data. The register-name strings printed by the screen refresh (twelve three-character entries) followed by the eight flag-bit names decoded for the AF and AF' registers. The name for the two unused flag-register bits (bit 5 and bit 3) is the digit 1. The source-listing disassembler misreads this table as instructions.

4F7FH - Go Command

Resumes the program under test. It reads an optional new program counter and up to two breakpoint addresses, plants F7H (RST 30H) breakpoints at them, arms the resident RST 30H re-entry hook, reloads every Z80 register from the snapshot, and transfers control to the saved program counter.

4FA3H - Register Restore and Transfer

Reloads the CPU from the 24-byte snapshot and jumps to the saved program counter. The eleven register-pair words are pushed onto the stack in reverse and popped back into every register (both banks, IX, IY, SP), then the saved PC is placed so the final RET transfers to it.

4FC9H - Breakpoint Store Helper

Plants one breakpoint. It saves the original opcode byte, writes an F7H (RST 30H) over it, verifies the write took (guarding against ROM or non-existent RAM), and records the address in the breakpoint table. Register Pair HL holds the breakpoint address; Register Pair DE points at the table slot and is decremented past the three bytes written.

4FDAH - Modify Memory Command

The m command. It sets the memory-modify pointer at 4060H (optionally to a new address), then repeatedly shows the address and current byte on the screen, prompts with a dash, and stores a new hexadecimal byte if one is typed, advancing byte by byte until ENTER.

5010H - Modify Register Command

The r command. It reads a one or two character register name (with an optional apostrophe for the alternate set), locates the matching entry in the name table, computes that register's slot in the snapshot at 4065H, and stores a new hexadecimal value there. The change takes effect when the program is resumed with Go.

505EH - Single-Step Next-Address Decoder

The c (step over) and i (step into) commands. It reads the opcode at the saved program counter, looks up its length and type in the tables at 50E0H-5130H, and plants a temporary breakpoint at the instruction that will execute next: always the sequential next instruction, and for branches also the branch target. It then transfers control so the program runs to the first breakpoint. The two commands differ only in how they treat a CALL: i breaks inside the called routine, c breaks after it returns.

50E0H - Instruction Length and Type Tables (Data)

Non-executable data used by the single-step decoder at 505EH. Three tables of three-byte entries (mask, match, result), each ending in a one-byte default less than 5. The result byte's low nibble is the instruction length in bytes and its high nibble is the branch type. The source-listing disassembler renders this region as meaningless instructions.

5131H - Memory Line Display

Displays one line of sixteen memory bytes starting at the address in Register Pair HL, advancing HL by sixteen. Bytes are shown in hexadecimal, or as characters when the display mode at 405DH is ASCII. Called for each memory line and, on the register screen, for the memory each register points at.

5164H - Memory Cursor Marker and Separator

Called once per byte before it is displayed. It draws a graphics block marker where the memory-modify pointer at 4060H falls within the line, and inserts a space between the two groups of eight bytes.

5189H - Keyboard Command Reader

Waits for a keystroke, discards control characters, folds letters to lowercase, echoes the accepted key, and reports the delimiter type. ENTER returns with the CARRY FLAG set; a comma or space returns with the Z FLAG set; any other key returns with neither, its code in Register A.

51A4H - Hexadecimal Parameter Parser

Reads a hexadecimal number from the keyboard into Register Pair HL. It returns immediately with the Z FLAG set if only a delimiter was typed; otherwise it accumulates digits until a delimiter, then encodes that delimiter in the CARRY FLAG (set for ENTER) so callers know whether further parameters follow. An invalid hex digit aborts to the command loop.

51C0H - ASCII to Hexadecimal Digit

Converts one ASCII character in Register A to a binary value 0 through 15, returning with the CARRY FLAG set if the character is not a valid hexadecimal digit.

51D1H - Hexadecimal Output Routines

A family of routines that print binary values as ASCII hexadecimal digits through ROM 0033H. 51D1H prints the byte at HL and advances; 51D5H prints Register Pair HL as four digits; 51DAH prints Register A as two digits; 51EEH and 51F1H add trailing spaces. The nibble-to-ASCII conversion uses the classic add-and-decimal-adjust technique.

51EEH - Hex-Plus-Space and Space Output

Convenience printers: 51EEH prints Register A as two hex digits followed by a space; 51F1H prints a single space. Both finish through the character output at 51EBH.

51F5H - Two-Character Display

Displays two consecutive characters from the string at Register Pair HL, advancing HL. Used to print each two-character register name on the register screen.