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

SYS5/SYS

Other Navigation

TRSDOS v2.3 SYS5/SYS Disassembly - DEBUG (Model I)

SYS5/SYS is the TRSDOS 2.3 system overlay that holds DEBUG. SYS0/SYS loads it into the overlay area at 4E00H when an RST 28H code with 7 in bits 0-3 is executed. SYS0/SYS's 44B4H executes that call with code 87H; the RST 30H vector at 400FH and the DEBUG entry at 440DH jump there. DEBUG saves every register of the interrupted program, shows them with the memory they point to, and lets the person change memory and registers, execute the program one instruction at a time, or let it run on to as many as two breakpoints. It never returns to SYS0/SYS: it leaves only by restarting the program.

The file holds 1,024 bytes in five load records covering 4E00H-51FFH, after a name record and a 169-byte copyright comment record; its transfer address is 4E00H. Every byte is shown once on this page, in address order, checked against S:\1\SYS5.SYS and its listing.

Memory Map

How DEBUG Is Entered

All the ways in end at 400FH (JP 44B4H) or 440DH (JP 44B4H): 44B4H pushes the program's Register Pair AF and executes RST 28H with Register A = 87H, and SYS0/SYS's overlay call loads SYS5/SYS if it is not already in memory and CALLs 4E00H. The address on the stack under Register Pair AF becomes the program counter DEBUG shows:

• an F7H byte (RST 30H) executed in the program: the address after it. A breakpoint planted by DEBUG is such a byte.
• a CALL 440DH or CALL 400FH in a program: the address after the CALL.
• a program loaded while bit 7 of 430FH (DEBUG, set by SYS1/SYS's DEBUG command) is set: 4C12H jumps to 400FH with the program's transfer address on the stack, so DEBUG starts before the program's first instruction.
• the exit after an error, 4030H, which SYS1/SYS's DEBUG command changes to CALL 400FH: the address after that CALL.
• BREAK, when the BREAK vector at 4315H holds C3H (the G command arms it as JP 400FH, and so does SYS1/SYS's DEBUG command): the interrupt handler leaves through 400FH with the interrupted address on the stack.

SYS5/SYS takes SYS0/SYS's return address off the stack and discards it, copies Register Pairs AF, BC, DE and HL, the four alternate register pairs, Index Registers IX and IY, the program's Stack Pointer and the program counter to 4065H-407CH, and goes on using the program's own stack. When the byte before the program counter is F7H, the program counter is moved back onto it, so after a breakpoint DEBUG shows and resumes at the breakpoint address. Then it takes out both breakpoints, putting back the bytes it saved.

The Commands

The command letter is typed at the start of the bottom line of the screen. Numbers are hexadecimal (0-9 and A-F; only the last four digits typed count) and are separated by a space or a comma; ENTER ends the command. A key that is not a hexadecimal digit where a number is expected abandons the command.

Any other key, ENTER and the space bar included, executes RST 28H with Register A = the key; with SYS0/SYS's hook at 4312H as SYS0/SYS's file sets it (JP 4BA0H) this does nothing, and the display is drawn again.

The Display

The register display starts at the top left of the screen. Each line is the register's name, its value as two bytes in hexadecimal, and then either the flags as the letters SZ1H1PNC (a minus sign for a clear flag) for AF and AF', or => and the 16 bytes at the address the register holds. The four memory lines below show the display address and 16 bytes each, indented so their arrows line up with the registers'. The full screen of memory shows sixteen such lines. The byte at the address of the M command is framed by Model I graphics bars (AAH before it, 95H after it), and a space separates the eighth byte of a line from the ninth. The display is built with the ROM's control and space compression codes: 1CH to go to the top left, a carriage return (which blanks the next line) between registers, ECH (44 spaces) after the flags and C7H (7 spaces) before each memory line.

Breakpoints and Single Stepping

A breakpoint is an F7H byte (RST 30H) written over the first byte of an instruction. DEBUG keeps two breakpoint entries of three bytes, 4060H-4062H and 405DH-405FH, each holding the address and the byte that was there. On every entry it takes both out again (405DH first, so two breakpoints on the same address come back in the right order), leaving a byte alone when it no longer holds F7H. A breakpoint cannot be planted where the F7H does not stay (ROM, or no memory): the command is abandoned and the program does not start.

I and C execute one instruction by planting breakpoints. The table at 50E0H gives the length and the kind of the instruction at the program counter, with separate parts for instructions without a prefix, after EDH, and after DDH or FDH. A breakpoint goes on the instruction that follows it; for a jump, a relative jump, a return or (with I) a call, a second breakpoint goes where the instruction can go: the operand of JP or CALL, the program counter plus the displacement for JR and DJNZ, the word at the top of the program's stack for a return, or the saved Register Pair HL for JP (HL). Then the registers are put back and the program runs until one of the breakpoints brings it back. BREAK is not armed for a step.

Notes from the Code

• 4E00H discards the return address into SYS0/SYS's overlay call, so 4BFFH-4C01H never put back the BREAK vector byte that 4BEEH-4BF5H saved and cleared. The BREAK vector stays disarmed while DEBUG runs and until G arms it again; G arms it whether or not SYS1/SYS's DEBUG command is on.
• The test for a breakpoint (4E23H-4E2CH) looks only at the byte before the program counter. When DEBUG is entered by a CALL, at a transfer address or by BREAK, and that byte happens to be F7H, the program counter is moved back one byte.
• 405DH, 405EH and 4060H-4061H are the address bytes of the two breakpoint entries and also hold the display letter (A or H), the display mode (S or X) and the M command's address while the commands run. They are cleared on each entry, so the display returns to registers in hexadecimal and the M address to 0000H. When G or a step leaves an entry unused, those values stay as its address, and on the next entry 4E2FH-4E49H examine the byte at that address (for example 5341H after S and A) and replace it with the entry's stale saved byte if it is F7H.
• For JP (IX) and JP (IY) the second breakpoint should go at the saved Index Register named by the prefix. 50CFH tests bit 5 of the byte after the prefix (E9H) instead of the prefix itself, so it always uses the saved Index Register IY; a step of JP (IX) plants its second breakpoint at the address in Index Register IY, and the program runs on from the address in Index Register IX without stopping there.
• A step is refused when the next instruction, or with I the subroutine of a CALL, is in ROM: the F7H does not stay and 4FD1H returns to the command loop.
• The RST instructions are in no group of the table, so a step treats them as one-byte instructions and the restart's routine runs at full speed.
• 4E35H loads Register C with 02H on each pass of the breakpoint loop; the value is never used. 4E98H (RET after the RST 28H for an unknown key) is never reached, because SYS0/SYS drops the RST's return address.
• 51A3H accepts only the upper case letters A-F as digits; with more than four digits typed, the earlier ones are shifted out.

DEBUG Work Area

Addresses Outside SYS5/SYS

4E00H - DEBUG Entry (code 87H): Save the Program's Registers

SYS0/SYS's overlay call enters SYS5/SYS here with Register A = 87H. 400FH (RST 30H) and 440DH both jump to 44B4H, which pushes the program's Register Pair AF and executes RST 28H with Register A = 87H; 4BA2H-4BA3H drop the RST's own return address and 4BFBH CALLs 4E00H. So the stack holds, from the top: the overlay call's return address 4BFEH, the program's Register Pair AF, and the program counter DEBUG is to show (the address after a CALL 440DH or an RST 30H, the transfer address when 4C12H jumps to 400FH, or the interrupted address when BREAK leaves the interrupt through 4316H). Register Pairs BC, DE and HL, Index Registers IX and IY and the alternate registers are the program's. SYS5/SYS copies all of them to 4065H-407CH, takes away an RST 30H breakpoint it finds, and goes into its command loop on the program's own stack.

4E4BH - The Command Loop

Every command returns here: 4E60H-4E63H push 4E4BH as the return address, and the hex input routine at 51ADH jumps here when a key that is not a hexadecimal digit is typed. The stack is reset to the program's Stack Pointer, the display is drawn, and one key is read on the bottom line of the screen.

4E99H - X and S: Choose the Display

X stores 00H and S stores 53H at 405EH, the display mode: 00H shows the registers with four lines of memory, any other value a full screen of memory.

4E9EH - U: Keep Redrawing Until a Key Is Pressed

The U command redraws the display over and over, so memory that changes while DEBUG waits (the clock bytes at 4040H-4046H, the screen, a buffer filled by interrupts) is seen changing. Any key stops it; the key itself is not used as a command.

4EA8H - D: Set the Display Address

The D command takes a hexadecimal address and makes it the start of the memory shown under the registers (or of the full screen, rounded down to a 256-byte page).

4EAEH - ; and -: Move the Memory Display

The semicolon moves the display address forward and the minus sign moves it back: by 40H bytes (the four lines shown under the registers) in the register display, by 100H bytes (one full screen) when the S command chose the full screen of memory.

4ECBH - A and H: Characters or Hexadecimal

A stores 41H and H stores 48H at 405DH. When 405DH holds 41H the memory lines show each byte as a character; otherwise they show it as two hexadecimal digits. 405DH is also the low byte of the breakpoint entry at 405DH-405FH, so 4E38H clears it, and hexadecimal returns, each time DEBUG is entered.

4ECFH - Draw the Display

Called by the command loop (4E4FH), the U command (4EA3H) and the M command (4FE6H). With 405EH = 00H it shows the twelve saved registers on lines 0-11, each with its value and either the flags (AF and AF') or the 16 bytes it points to, then four lines of memory from the display address at 4063H. With any other value at 405EH it shows sixteen lines of memory, the 256-byte page holding the display address. Every character goes through the ROM display routine at 0033H, which keeps Register A, Register Pair BC and Register Pair HL and leaves Register Pair DE = 401DH.

4F54H - Register Names and Flag Letters (Data)

Data, not code: the twelve register names shown at the start of each line of the register display (three characters each, in the order of the save area at 4065H-407CH) and the eight letters shown for the bits of a flag register. The R command (5029H) searches the same name table.

4F80H - G: Go

The G command takes up to three hexadecimal numbers: a new program counter, then up to two breakpoint addresses, separated by spaces or commas and ended by ENTER. G with no number resumes at the saved program counter. Each breakpoint is planted as an F7H byte (RST 30H) and recorded in the entries at 4060H-4062H and 405DH-405FH; the BREAK vector is armed to re-enter DEBUG through 400FH; then every saved register is put back and the program continues. Execution reaches 400FH, and SYS5/SYS again, when a breakpoint's RST 30H executes or BREAK is pressed.

4FCAH - Plant a Breakpoint

Called by the Go command (4F93H) and the step commands (5095H, 50DBH) with Register Pair HL = the address and Register Pair DE = the saved byte of the next free breakpoint entry (4062H, then 405FH). The byte at the address is saved, an F7H (RST 30H) is written over it, and the address is recorded below the saved byte. If the memory does not keep the F7H (ROM, or no memory there), the command is abandoned at 4E2FH.

4FDBH - M: Examine and Change Memory

The M command takes an address (or uses the one at 4060H-4061H from the last M command; it is 0000H after DEBUG is entered, since 4E37H-4E3BH clear it with the breakpoint entry). ENTER after the address only records it, so the byte is marked in the display. A space or comma goes on: the display is drawn with the byte marked, its address is shown at the start of line 13 and its value at the start of line 14 followed by a minus sign, and a new value can be typed. Each space or comma moves to the next address; ENTER ends the command.

5011H - R: Change a Register

The R command takes a register name as the display shows it (two letters, plus an apostrophe for an alternate register), then a space or comma and a hexadecimal value, which is stored in the saved register in 4065H-407CH. SP and PC can be changed too; the Go command uses the saved values. A wrong name, or ENTER before the value, leaves everything as it was.

505DH - I and C: Execute One Instruction

Entered from 4E82H with Register A = 49H (I) or 43H (C) and the Z FLAG set. SYS5/SYS finds the length and kind of the instruction at the saved program counter from the table at 50E0H, plants a breakpoint on the instruction after it, and for a jump, a return, or (with I) a call, a second breakpoint where it can go. Then it puts back the registers at 4FA4H and lets that one instruction run; the breakpoint brings the program back into DEBUG. C differs from I only on CALL instructions: the subroutine runs at full speed and DEBUG stops after it returns. BREAK is not armed for a step.

50E0H - Instruction Classification Table (Data)

Data, not code: three-byte entries of a mask, a pattern and a type byte. An instruction belongs to an entry when its byte ANDed with the mask equals the pattern. In the type byte bits 0-3 are the length in bytes and bits 4-7 the kind: 0 plain, 1 JP (HL), 2 JP (IX) or JP (IY), 3 JR or DJNZ, 4 JP, 5 RET, 6 CALL. Each of the three parts ends with a single byte below 05H, the type for any instruction not listed: 50E0H-510DH for instructions without a prefix (length 1), 510EH-5114H for the byte after EDH (length 2), 5115H-5130H for the byte after DDH or FDH (length 2).

5131H - Show 16 Bytes of Memory

Called with Register Pair HL = the first address by the register lines (4F27H) and the memory lines (4F3FH). It shows => and a space, then 16 bytes, each after a one-character separator (5165H): two hexadecimal digits, or a space and the byte as a character when 405DH holds 41H (the A command). An extra space separates the eighth byte from the ninth. 52 characters in all. Register Pair HL returns 16 bytes further on; Register Pair BC is kept.

5165H - The Separator Before a Byte

Called by 5131H before each byte, with Register Pair HL = the address about to be shown and Register B = 10H for the first byte down to 01H for the last. The M command's address (4060H-4061H) is marked with Model I graphics bars: AAH (a bar in the right half of the cell) as the separator before it and 95H (a bar in the left half) as the separator after it, so the byte is framed. Any other separator is a space. Before the ninth byte (Register B = 08H) an extra space is shown.

518AH - Read and Echo One Key

Waits for a key through the ROM. ENTER returns at once, not echoed, with Register A = 0DH, the Z FLAG and the CARRY FLAG set. Codes below 20H (the arrows, CLEAR, BREAK) are ignored. Any other key is echoed at the cursor and returned in Register A with the CARRY FLAG clear; the Z FLAG is set for a comma or a space. Register Pair DE is kept.

51A3H - Read a Hexadecimal Number

Reads hexadecimal digits (0-9 and A-F) into Register Pair HL until a space, a comma or ENTER; only the last four digits count. If the first key is a space, a comma or ENTER, it returns at once with the Z FLAG set and Register Pair HL as the caller had it. After digits it returns with the NZ FLAG set. Either way the CARRY FLAG is set when ENTER ended the input. Any other key abandons the command: 51ADH jumps to the command loop at 4E4BH.

51BFH - Hexadecimal Digit Value

Turns the character in Register A into its value: 30H-39H (0-9) give 00H-09H and 41H-46H (A-F) give 0AH-0FH, with the CARRY FLAG clear. Any other character returns with the CARRY FLAG set.

51D0H - Display Hexadecimal Digits and Spaces

Small display routines, all ending in the ROM display routine at 0033H. 51D0H shows the byte at (HL) and advances Register Pair HL; 51D4H shows Register Pair HL as four digits; 51D9H shows Register A as two digits; 51E2H shows the low four bits of Register A as one digit; 51EFH shows Register A as two digits and a space; 51F2H shows a space; 51F6H shows three characters from (HL) and 51FCH one, advancing Register Pair HL.