TRS-80 DOS - VTOS 4.0 for the Model I - SYS9/SYS Extended Debugger Disassembled

Installation Sequence Begin
The following instructions calculate the destination address for SYS9 in high memory, adjust the high-memory boundary pointer, and copy SYS9's code into place using LDIR.

Parse First Parameter: Source Address
4063H holds the current display address and serves as the first parameter register for the B command. The routine reads any user-typed address into 4063H, falling through to print a comma separator if the address was entered (Z not set from CALL 51A3H).

Parse Second Parameter: Destination Address
4060H holds the destination address for the B command.

Parse Third Parameter: Byte Count
The default byte count is 0100H (256 bytes) if the user provides no third parameter. If Carry is set from the previous accumulator call the third-parameter parse is skipped.

Execute Block Move
HL now holds the byte count. The source address is in 4063H and the destination is in 4060H. These are loaded into the appropriate register pairs for LDIR.

Parse Starting Address
4060H holds the current memory address pointer. If the user types an address it is stored here; otherwise the current value is used as the default.

Loop Start - Enter Data Loop
Each iteration of this loop displays the current address, displays the byte currently at that address as a dash-prefix prompt, waits for the user to type a new hex value, stores it at the current address, and advances HL to the next address. The loop continues until BREAK is pressed.

Loop Start - Fill Loop
Each iteration stores E at (HL), INCrements HL, and checks whether HL has passed BC (the end address) using a 16-bit subtraction. The loop runs from start through end inclusive.

Parse Optional Starting Address
4060H holds the current address pointer. If the user provides a new starting address it is stored here; otherwise the search begins from the current 4060H value.

Parse Optional Target Byte
The user may type a new byte value to locate. If no byte is entered, the previous target byte (from 4062H) is used.

Execute Memory Search via CPIR
CPIR searches forward from (HL), comparing each byte to A, decrementing BC after each comparison. With BC=0000H, the instruction searches through the entire 64K address space (wrapping around) until a match is found (Z set) or BC wraps to 0 (NZ).

Match Found - Compute Page-Aligned Display Address
HL points one byte past the match. The address is adjusted back one byte, then its low byte is page-aligned (low 6 bits cleared) to produce a 64-byte-aligned display address for the memory dump window.

Loop Start - Type Data Loop
Each iteration outputs a 1EH cursor control, displays the current byte as an ASCII character (or period for non-printable), outputs a dash prompt, reads an input character, stores it (unless it is a space), advances the pointer, and loops.

Parse First Parameter: Source Address

Parse Second Parameter: Destination Address

Parse Optional Third Parameter: Byte Count
The default count is 0000H. With BC=0000H the comparison loop will run for 65536 iterations (the full address space) if no mismatch is found.

Execute Verify Loop
HL = byte count (BC after the next two instructions). Source at 4063H (in HL after load), destination at 4060H (in DE). Each byte pair is compared; the loop runs until BC=0 or a mismatch is found.

Loop Start - Verify Loop
Each iteration reads one byte from each block and compares them. On a mismatch the loop continues (both pointers advance). On a full match (BC exhausted), both updated pointers are stored back.

Parse Starting Address and Target Word
The W command needs a starting address and the 16-bit word to find. The starting address is read from 4060H (with INC HL to start searching at the next address). The word to find is stored split across 4062H (low byte) and 405FH (high byte).

Parse Optional Target Word
If a new target word is entered it overwrites the defaults in HL. The parsed word is then split back into 4062H (low byte) and 405FH (high byte) for future W commands.

Execute Word Search via CPIR (Two-Phase)
The search uses CPIR to find the low byte, then manually checks that the following byte matches the high byte. This implements a little-endian 16-bit word search: low byte at address aaaa, high byte at aaaa+1.

Word Match Found - Compute Address and Page-Align
HL points one past the high byte (i.e., two bytes past the start of the found word). The routine steps back two bytes to reach the word start, stores it, then page-aligns for display.

Drive Number Dispatch Check
The disk command is triggered not by a letter but by a decimal digit (0-7) as the command character. The check tests that A is in the range 30H-37H (ASCII digits '0' to '7').

Select Drive and Compute Sectors-Per-Track
The drive number is converted from ASCII to binary, the drive parameter block is selected via CALL 478FH, and the sectors-per-track value is derived from IY+07H (the sectors/track and interleave byte in the drive parameter block).

Loop Start - Multiply Loop (Sectors-per-Track Calculation)
This loop computes A = H * B by repeated addition. B is the sectors-per-track count; H is the per-sector value. The result in A is the total sectors per cylinder.

Parse Command Parameters: Cylinder, Sector, Operation, Address, Length
The disk command now parses the remaining parameters. 518AH reads the full input line; 51A3H accumulates hex digits. The operation character (R/W/*) is stored in B. The parsed track, sector, and length are used to drive the SYS0 I/O routines.

Parse Optional Length Parameter
If the user specifies a length (number of sectors) it overrides the default count.

Dispatch to I/O Routine Based on Operation Character
The operation character in B is checked against R (52H), W (57H), and * (2AH). Each dispatches to the appropriate SYS0 read or write routine. Unknown operation characters fall through to the sector-step loop which processes the transfer iteratively.

Loop Start - Multi-Sector Transfer Loop
For operations that do not immediately dispatch to a single-call I/O routine, the following loop advances through DE (track and sector), decrements the sector count, and repeats. This handles multi-sector transfers by iterating one sector at a time.

Post-Read: Update Display Addresses
For a read operation, after all sectors have been loaded into memory, the display address registers are updated to point at the start of the loaded data so the user can immediately examine the result.

Single I/O Dispatch Routines
The following three short sections handle direct single-call dispatches to the three SYS0 I/O routines for the R, W, and * operations respectively. Each calls the SYS0 routine and then either loops back for another sector or exits.

I/O Error Display and Acknowledge
On an I/O error, the routine displays a space, the error code as two hex digits, an asterisk pair flanking the current operation character, and then waits for the user to press any key before returning to the multi-sector loop or exiting.

Parse Start and End Addresses
The P command requires exactly two parameters: start address and end address. If either is zero (Z set from 51A3H) the command returns immediately.

Align Start Address to 16-Byte Boundary
The P command's hex dump lines are 16 bytes wide. The start address is rounded down to the nearest 16-byte boundary (clearing the low 4 bits) so the first displayed line begins at a clean hex address ending in 0.

Loop Start - Outer Dump Loop (One Line = 16 Bytes per Iteration)
Each outer iteration saves HL (the current 16-byte line start address), outputs the 4-digit hex address, then outputs 16 bytes in hex, then outputs the 16 bytes as ASCII, then checks whether the end address BC has been reached.

Inner Hex Byte Output Loop Entry (from Line-Wrap)
5191H is the re-entry point for subsequent lines of the dump (reached via the JR C,5191H at 51E7H). It re-enters the outer loop at 514EH to begin a new line.

Loop Start - Inner Hex Byte Output Loop (16 bytes per line)
Each iteration of this inner loop outputs one byte as two hex digits, followed by a space, then checks for group spacing (extra space every 4 bytes) and line-end (after 16 bytes). HL points to the current byte; INC HL advances after each byte.

Shared Entry Point: 51A3H - Low Nibble Output
51A3H is both the second half of the per-byte hex output (outputting the low nibble after the high nibble has been sent) and a shared entry point used by the extended command parameter parsers throughout SYS9 to accumulate a hex digit from input into HL. When called from 51A0H it outputs the low nibble of (HL); when called directly by parameter parsers it reads one more nibble from the keyboard and accumulates it.

ASCII Portion of Dump Line
After 16 hex bytes have been output, a separator space is added and then the same 16 bytes are displayed again as ASCII characters. The saved HL from the PUSH at 514EH is popped to restore the line-start address.

Loop Start - ASCII Byte Output Loop (16 bytes per line)
Each iteration reads one byte, determines whether it is printable ASCII (20H-7FH), outputs the character or a period substitute, and advances HL. The loop ends when the address reaches the same 16-byte boundary it stopped at during the hex output.

End of Line - Carriage Return and End-of-Dump Test
After the 16th ASCII character has been output, a carriage return ends the line. The current address HL is then compared against the end address BC; if HL >= BC the dump is complete.

End of Dump - Output Trailing Carriage Returns
Three carriage returns are output via a fall-through and a final JP 003BH to terminate the dump display cleanly.