TRS-80 Utility - TBUG Z-80 Monitor and Debugging Aid (26-2001) for the Model I LEVEL II - Disassembled

TBUG (LEVEL II)

TBUG Z-80 Monitor and Debugging Aid Disassembly - LEVEL II (Model I)

TBUG (Radio Shack catalog number 26-2001) is a compact machine-language monitor for the TRS-80. It gives the user direct access to the Z80 CPU so that machine-language programs can be entered, examined, modified, debugged with breakpoints and register displays, and saved to or loaded from cassette tape. This disassembly documents the LEVEL II version, which loads into memory from 4380H through 497FH. User programs therefore live from 4980H upward, and the monitor presets the user Stack Pointer to 4980H.

The monitor presents a live keyboard driven by a single-character command dispatcher. When the # prompt is shown, the dispatcher at 43E2H reads one key and branches to the handler for that command. The supported commands are Memory (M), Jump (J), Breakpoint (B), Fix (F), Go (G), Register (R), Punch (P), and Load (L). TBUG uses only the first 16 columns of the 64 by 16 video screen; all output cursor management is done through a private cursor pointer kept at 483DH rather than through the ROM display driver.

A central feature is the Register Save Area at 4825H through 483CH. When a user program hits a breakpoint the entire register file (including the alternate set, IX, IY, SP and PC) is pushed into this area; the Register command displays it, and the Jump and Go commands reload the CPU from it before transferring control. This lets the user inspect and edit register contents between runs by simply editing memory in the save area.

Program Origin and Entry

The assembled origin is 4380H and the tape entry point (the END address) is 43A0H. Entry at 43A0H sets the stack to 4980H and falls into the cold-start display setup at 43D3H. The breakpoint trap vector lives at 44B7H: a breakpoint is planted in user code as a three-byte CALL 44B7H sequence (opcode CDH, then 80H 43H little-endian for 4380H+... resolved to the trap), so that when the user program reaches the planted instruction it calls into TBUG and the full register state is captured.

Variables and Work Area (Register Save Area and Scratch)

Address Range	Purpose
4825H-482CH (8 bytes)	Alternate register set save area: F' (4825H), A' (4826H), C' (4827H), B' (4828H), E' (4829H), D' (482AH), L' (482BH), H' (482CH). Populated by the breakpoint trap and reloaded before Go/Jump.
482DH-4838H (12 bytes)	Main register set save area: F (482DH), A (482EH), C (482FH), B (4830H), E (4831H), D (4832H), L (4833H), H (4834H), IX lsb (4835H), IX msb (4836H), IY lsb (4837H), IY msb (4838H).
4839H-483AH (2 bytes)	Saved user Stack Pointer (SP lsb at 4839H, SP msb at 483AH). Also used as a temporary SP holding cell during command entry.
483BH-483CH (2 bytes)	Saved user Program Counter (PC lsb at 483BH, PC msb at 483CH). The Go command resumes execution here; the Fix command restores saved breakpoint bytes to this address.
483DH-483EH (2 bytes)	Current display cursor pointer into video RAM (3C00H-3FFFH). Advanced by the character output routine at 457BH and reset to 3C00H at cold start.
483FH-4840H (2 bytes)	Memory command working address (483FH) and the value byte just entered (4840H). IX is loaded from 483FH to point at the location being examined or modified.
4841H-4846H (6 bytes)	Punch command parameters: start address (4841H lsb, 4842H msb), end address (4843H lsb, 4844H msb), and entry point (4845H lsb, 4846H msb).
4847H-484CH (6 bytes)	Punch file name buffer, six characters padded with blanks (20H).
484DH (1 byte)	Keyboard debounce holding cell. Stores the last accepted key code so the scanner at 45C8H requires the key to be released and re-pressed before repeating.
484EH (1 byte)	Cassette port (FFH) output image. The latch is write-only, so TBUG keeps a shadow copy here and masks it (AND H / OR L) before every OUT (0FFH),A.
484FH-4851H (3 bytes)	Breakpoint save cells. Holds the three original user bytes that the Breakpoint command overwrote with the CALL trap, so the Fix command can restore them.

Major Routines

Address	Routine	Description and Entry/Exit
43A0H	Cold Start / Warm Restart Entry point from tape (END 43A0H). Sets SP to 4980H and joins the screen-clear and command loop. The shorter entry at 43ABH is used after saving the caller SP.
43E2H	Command Dispatcher Prints the # prompt, reads one key via 45C8H, and compares against the eight command letters, jumping to the matching handler. Unknown keys loop back.
44B7H	Breakpoint Trap / Register Save Reached by the planted CALL in user code. Saves every register into the save area (4825H-483CH), then returns to the command loop. On exit the user CPU state is preserved for inspection.
450FH	Display Byte As Hex Entry: IX points at the byte. Prints the two hex digits of (IX+00H) to the screen using the cursor pointer at 483DH.
4522H	Print One Hex Nibble Entry: A holds a value 00H-0FH. Converts to an ASCII hex digit (0-9, A-F) and writes it to video at the cursor, then advances the cursor.
453CH	Newline / Scroll Advances the cursor to the start of the next 16-column line, scrolling the 16-column window up by one line when the bottom is reached and blanking the freed line.
457BH	Advance Cursor Increments the cursor pointer at 483DH and wraps it within the video region (masking to keep the high byte in the 3CH-3FH range).
4589H	Input Two Hex Digits To Byte Reads two hex characters from the keyboard, echoes each, and returns the combined 8-bit value in A.
45A4H	Get Hex Digit Reads one key, validates it as a hex digit (0-9 or A-F), converts to 0-0FH, and returns it in A. The X key aborts to the command loop.
45C8H	Debounced Key Scan Waits for a fresh keypress using the debounce cell at 484DH and a settle delay, and returns the ASCII code in A.
45E9H	Raw Keyboard Decode Scans the memory-mapped keyboard matrix at 3801H-3880H and returns the ASCII code of the pressed key, or FFH if none.
4643H	Load Command Reads a SYSTEM-format tape from the cassette port, honoring the A5H sync, 55H name header, 3CH data blocks, and 78H entry-point trailer, storing bytes to memory and checking the block checksum.
46A5H	Punch Command Prompts for the six-character file name, then writes a SYSTEM-format tape (leader, A5H sync, 55H name header, 3CH data blocks with checksum, and 78H entry trailer) for the memory range in the Punch parameter cells.
4762H	Read One Cassette Bit Uses the alternate register set. Waits for the sync pulse on port FFH, delays, samples the data pulse, and shifts the bit into A. Called eight times per byte by 4782H.
478CH	Write One Cassette Byte Uses the alternate register set. Serializes the byte in A most-significant-bit first, driving the cassette port through the pulse routine at 47A6H.
47D2H	Cassette Port Output Masks the shadow image at 484EH with H (AND) and L (OR), writes the result to port FFH, and refreshes the shadow. Entry points at 47C5H/47CAH/47CFH preload HL for specific bit patterns.

Cross-Reference Notes

TBUG is self-contained and calls no LEVEL II ROM routines during normal monitor operation: it drives the keyboard matrix, the video RAM, and the cassette port directly. The one external interface is the cassette port at FFH (see Model I hardware notes). The breakpoint mechanism links back into the monitor from arbitrary user code via the planted CALL 44B7H sequence. The tape format produced by the Punch command at 46A5H is the standard Model I SYSTEM tape format, so tapes written by TBUG can be reloaded by the LEVEL II BASIC SYSTEM command as well as by TBUG's own Load command at 4643H.

4380H - Breakpoint Return Stub and Command Restart

This short block is the front door of the monitor. It contains the code that a planted breakpoint returns through, the Go/Jump re-entry helpers, and the common restart path that clears the screen and drops into the command loop. The tape entry point (43A0H) also lives here.

440DH - Memory Command

The Memory command examines and edits RAM or ROM one byte at a time. It reads a four-digit address, displays that byte, and then repeatedly shows a location and accepts either two hex digits (to change it and advance) or ENTER (to advance unchanged). Pressing X aborts back to the command loop.

4455H - Register Command

The Register command displays the contents of the Register Save Area in six labeled pairs of rows. It walks the save area in three-byte groups, printing pairs of bytes with spacing so the user can read the saved register file, then returns to the command loop.

4483H - Display Register Pair Subroutine

Helper for the Register command. Given IX pointing into the save area, this prints one register pair as four hex digits in msb,lsb order with a trailing space, then advances IX past the two bytes so successive calls walk the save area.

44A5H - Jump Command

The Jump command reads a four-digit target address, stores it as the user Program Counter in the save area, and then falls into the register-reload path so the CPU is loaded from the save area before execution begins at the requested address.

44B7H - Register Reload and Resume

This is the shared exit path used by Go and Jump. It saves TBUG's stack, switches to the Register Save Area as a stack, pops the entire register file back into the CPU (including the alternate set, IX, and IY), restores the user stack, and returns to the user Program Counter placed on the stack by the caller.

44D3H - Punch Command Parameter Entry

The Punch command dumps a block of memory to a SYSTEM-format cassette tape. This entry code reads the three four-digit addresses (start, end, and entry point) into the Punch parameter cells, then calls the tape-writer engine and returns to the command loop.

4506H - Load Command

The Load command reads a previously recorded SYSTEM-format tape into memory. It echoes the command letter, invokes the tape reader engine, and returns to the command loop.

450FH - Display Byte As Two Hex Digits

Given IX pointing at a byte, this splits the byte into its high and low nibbles and prints each as an ASCII hex digit at the current display cursor. It is the core of every hex value shown on screen by the Memory and Register commands.

4522H - Print One Hex Nibble

Converts a 4-bit value in Register A (0-0FH) into its ASCII hex character (0-9, A-F) and writes it to video RAM at the current cursor. This routine falls through into the cursor-advance helper so the cursor moves after the digit is written.

4532H - Print Character And Advance Twice

Displays the character in Register A at the cursor, then advances the cursor twice, leaving a blank between output characters for the monitor's spaced hex readouts.

453CH - Newline With Scroll

Advances the cursor to the beginning of the next 16-column line within the monitor's left-hand output window. When the cursor reaches the bottom of the screen it scrolls the 16-column window up by one line and blanks the vacated bottom line, so TBUG output stays inside the first 16 columns.

457BH - Advance Cursor

Increments the display cursor by one position and keeps it inside the video RAM region by forcing the high byte back into the 3CH-3FH range, so the cursor never leaves the screen.

4589H - Input Two Hex Digits To A Byte

Reads two hex characters from the keyboard, echoing each as it is entered, and combines them into a single 8-bit value returned in Register A. The first digit becomes the high nibble and the second the low nibble. The internal entry at 458CH is used by the Memory command when the first key has already been read.

45A4H - Get And Validate One Hex Digit

Reads a single key, accepts only valid hexadecimal characters (0-9 or A-F), and returns the 4-bit value in Register A. Non-hex keys are ignored (the routine loops), and the X key aborts the current command back to the command loop.

45C8H - Debounced Key Scan

Waits for a fresh keypress. It uses the last-key cell at 484DH to require that a key be released (or a different key pressed) before accepting a repeat, and inserts a settle delay to debounce the contacts. The accepted ASCII code is returned in Register A.

45E9H - Raw Keyboard Matrix Decode

Scans the Model I memory-mapped keyboard matrix at 3801H-3880H, which is read active-high per bit within each row address. It locates the first pressed key, computes a position code, and translates it to ASCII (with special handling for the shift row at 3880H). Returns the ASCII code in Register A, or FFH if no key is pressed.

463BH - Keyboard Symbol Translation Table

This is the lookup table used by the keyboard decoder at 462FH for the digit and symbol rows (position codes 30H and above). It is non-executable data; the disassembler misread the bytes as instructions, so they are shown here as their raw values. The bytes are the ASCII characters for the shifted/unshifted symbol keys.

4643H - Load Command Engine

Reads a SYSTEM-format tape from the cassette port into memory. It waits for the A5H sync byte, then the 55H file-name header, skips the six-byte name, and processes 3CH data blocks: each block gives a byte count and a load address, and the data bytes are stored to memory while a running checksum is accumulated. A 78H trailer marks the entry point and ends the load. Byte 3FCCH is used as a screen flag cell during loading.

469CH - Read Two-Byte Address From Tape

Reads a little-endian 16-bit address from the tape into Register Pair HL (low byte first into L, then high byte into H). Register A is left holding the high byte so the caller can seed a checksum.

46A5H - Punch Command Engine

Prompts for a six-character file name, then writes a SYSTEM-format tape for the memory range in the Punch parameter cells (4841H-4846H). It emits a leader of zero bytes, the A5H sync, the 55H name header and padded name, then 256-byte data blocks each with a 3CH header, byte count, load address and checksum, and finally a 78H trailer with the entry-point address.

4743H - Write Data Block Body And Checksum

Writes one block's two-byte load address followed by its data bytes, accumulating a checksum over the address and data, and finally writes the one-byte checksum. The data pointer is Register Pair DE and the byte count is Register B.

475CH - Punch Cancel And Resume Handlers

Two short exits used during file-name entry. The cancel path (475CH) discards the saved counter and returns to the command loop; the ENTER path (475EH) discards the counter and jumps into the tape-write sequence to punch the block using the name entered so far.

4762H - Read One Cassette Bit

Reads a single bit from the cassette port at FFH. It uses the alternate register set, waits for the sync pulse, delays, samples the data pulse, and rotates the bit into the accumulator. The Model I cassette interface presents data on the port bits, and the routine clears the read latch between samples via the port helper at 47CFH.

4782H - Read One Cassette Byte

Reads a full byte from the tape by calling the single-bit reader eight times. The bits accumulate in the alternate accumulator, and the completed byte is returned in Register A.

478CH - Write One Cassette Byte

Writes a single byte to the tape most-significant-bit first. It uses the alternate register set, and for each bit it emits a clock pulse and, if the bit is a one, a data pulse, using the pulse generator at 47A6H. The byte to write is passed in Register A.

47A6H - Cassette Pulse Generator

Produces one cassette write pulse by driving the port through its rising and falling levels with calibrated delays. It writes the three level patterns (FC01H, FC02H, FC00H masks) via the port output helper at 47D2H, each followed by a timing delay, generating the waveform recorded on tape.

47C5H - Cassette Port Control Entries

Three short entry points that preload Register Pair HL with a specific AND/OR mask pair and fall into the port output routine. 47C5H turns the cassette off, 47CAH enables the read latch and motor, and 47CFH clears the read latch. Each sets HL then reaches the common output code at 47D2H.

47D2H - Cassette Port Output

The single point through which all cassette port writes pass. Because port FFH is write-only, TBUG keeps a shadow image at 484EH; this routine masks that image with H (AND) and L (OR), writes the result to the port, and refreshes the shadow, then tests bit 2 (the read/data bit) for the caller.

47DFH - Breakpoint Command

The Breakpoint command reads a target address, saves the three original bytes at that address into the breakpoint save cells, and overwrites them with a three-byte CALL to the register-save trap. When the user program later reaches that address it calls into TBUG, which captures the registers. Only one breakpoint can be active because a single save area is used.

480DH - Fix Command

The Fix command undoes a breakpoint after it has been hit. It copies the three saved original bytes back to the location held in the user Program Counter, restoring the instruction the breakpoint replaced so that execution can be resumed cleanly with a Go or Jump.