LDOS 5.3.1 for the Model III - SYS5/SYS Disassembled

SYS5/SYS

Other Navigation

LDOS 5.3.1 SYS5/SYS Disassembly - DEBUG, the System Debugger (Model III)

SYS5/SYS is the DEBUG monitor of LDOS: it shows the registers of the program it stops and the memory they point at, lets them be changed, and runs the program on with up to two breakpoints or one instruction at a time. It is a system file, loaded into the overlay area at 4E00H by the supervisor dispatcher of SYS0/SYS (4BCCH) for request 87H, which only 440DH issues (PUSH AF / LD A,87H / RST 28H). It uses no disk call: it reads the keyboard and writes the screen through the ROM (002BH, 0049H, 0033H) and places its text by setting the cursor position of the video device control block at 4020H-4021H. The manual calls it the ghost debugger, needed only to test machine language programs with the DEBUG library command; SYS9/SYS, the extended debugger that DEBUG (EXT) installs in high memory, has no use without it, since it borrows SYS5/SYS's key reader, number reader and hexadecimal output (5189H, 51A4H, 51D1H, 51D5H, 51DAH, 51F1H) and its cells at 405DH-407CH.

The file is a load module of 1100 bytes: a record of type 1FH with the text Copyright 1991 MISOSYS, Inc., All rights reserved, four load blocks for 4E00H-51FEH, a load block for the two bytes 4BC8H-4BC9H (03FFH, the 1023 bytes that SYS5/SYS takes up in the overlay area) and the transfer address record for 4E00H.

How DEBUG Is Entered

The Cells at 405DH-407CH

The Commands

The Register Screen

The Single Step

About This Page

4BC8H - The Overlay Length (Data)

Every system file from SYS1/SYS to SYS12/SYS carries a load block for the two bytes 4BC8H-4BC9H in the resident area of SYS0/SYS. They hold the length of the file's part in the overlay area: for SYS5/SYS 03FFH, the 1023 bytes 4E00H-51FEH. In the file this block is the last load block, after the four blocks of 4E00H-51FEH and before the transfer address record (4E00H). The two bytes are data, not instructions.

4E00H - DEBUG Entry: Save Every Register

The supervisor dispatcher (4BCCH) loads SYS5/SYS into 4E00H for request 87H and calls 4E00H. Request 87H comes only from 440DH (PUSH AF / LD A,87H / RST 28H), which three roads lead to: the RST 30H vector at 400FH (a breakpoint F7H that DEBUG planted, or the start of a program run while DEBUG is on, SYS0/SYS 4C72H), the BREAK trap when 4406H holds 400FH or 440DH, and @DEBUG at 440DH (the D key held at boot). The dispatcher drops the return address of its RST 28H, so on entry the stack holds the dispatcher's return 4BE6H, then the program's Register Pair AF pushed by 440DH, then the program's address (its PC): the address after the RST 30H, the interrupted address, or the program's transfer address. DEBUG never returns to 4BE6H, so the BREAK trap switch at 4405H stays off (C9H, stored by the dispatcher at 4BD9H) until the G command turns it on. The registers are pushed and copied in one move to the register save area 4065H-407CH.

4E23H - Back the PC onto a Breakpoint

A breakpoint is an F7H (RST 30H) written over the first byte of an instruction. When it runs, the RST pushes the address after it, so the saved PC is one past the breakpoint. If the byte before the saved PC is F7H, the PC is moved back one, onto the instruction the breakpoint stood on; 4E2FH then puts its first byte back. The test is made on every entry, so a BREAK or a program start whose address follows an F7H byte is moved back too.

4E2FH - Clear the Two Breakpoint Slots

Two slots of three bytes: slot A at 405DH-405FH and slot B at 4060H-4062H, each the address of a breakpoint (low byte first) and the byte the F7H was written over. For each slot the address is read and cleared; if it is not 0000H and the byte there is still F7H, the saved byte is put back. Both addresses are 0000H afterwards. The same bytes are used for other things between breakpoints: 405DH is the memory display mode, 405EH the screen layout and 4060H-4061H the address the M command changes, so entering DEBUG sets the display back to the hexadecimal register screen and the M address to 0000H. When the G command set only one breakpoint, or none, 405DH-405EH still hold the display mode bytes and are taken as an address; the saved byte is written there only if that address holds F7H. The G command (4FD0H) also jumps here when a breakpoint cannot be written, to take back the breakpoints already planted.

4E49H - The Command Loop

Every command but G comes back here. The Stack Pointer is put back to the program's (from 4079H), the screen is drawn, the cursor goes to the start of the bottom line (3FC0H) and one key is read by 5189H, which shows it there in lower case. G (67H) is tested first; for the other commands the address 4E49H is pushed so that each handler's RET comes back here. The keys: S full screen memory, ; and - move the memory display, A and H the ASCII or hexadecimal memory display, C and I single step, D set the memory display address, M change memory, R change a register pair, U keep redrawing, X the register screen. Any other key goes to the address held at 4400H (4876H, which only returns, unless SYS9/SYS has put its extended commands there), with Register A = the key and 4E49H on the stack.

4E99H - X and S: Choose the Screen

405EH is the screen layout: 00H the register screen (twelve register pairs and four lines of memory), any other value the full screen of sixteen lines of memory. X enters at 4E99H with Register A cleared; S enters at 4E9AH with Register A = 73H, its key.

4E9EH - U: Keep Redrawing the Screen

The screen is drawn again and again so that memory a background task changes (the clock at 4217H-4219H, for instance) is seen changing, until a key is pressed.

4EA8H - D: Set the Memory Display Address

Reads a hexadecimal address and makes it the first address of the memory display (4063H-4064H). D with no number leaves it as it is.

4EAEH - ; and -: Move the Memory Display

The semicolon moves the memory display address at 4063H-4064H forward and the minus sign moves it back: by 64 bytes (the four lines) on the register screen, by 256 bytes (the sixteen lines) on the full screen. The minus sign enters at 4EC6H with Register Pair BC = FFC0H; for the full screen Register B tells the two apart (00H forward, FFH back).

4ECBH - A and H: Choose the Memory Display Mode

Register A holds the key: 61H (a) or 68H (h). It is kept at 405DH, which 5143H tests for 61H: memory is then shown as characters, otherwise in hexadecimal. 405DH is also the low byte of the address in breakpoint slot A, cleared on every entry (4E2FH), so DEBUG starts in hexadecimal.

4ECFH - Draw the Register Screen

With 405EH = 00H the screen shows twelve lines, one for each register pair of the save area (4065H-407CH) in the order of the name table at 4F53H: the name, an equals sign, the high and the low byte in hexadecimal; for AF and AF' then the eight flags of Register F by name (4F77H), for the others the sixteen bytes of memory the pair points at (5131H). Four lines of memory from the display address at 4063H-4064H follow (4F2EH). All text goes through the ROM's display routine at 0033H, which also takes the control codes 0DH (next line) and 1CH (cursor to the top left corner) and the codes C0H-FFH, each of which shows 0-63 spaces. With 405EH not 00H, 4F44H draws sixteen lines of memory instead.

4F2EH - Draw the Memory Lines

Register B lines of sixteen bytes, from the address in Register Pair HL. Each line starts with seven spaces (code C7H), of which the first completes the line before (the register lines and the memory lines are each 63 characters long, without a carriage return), then the address in hexadecimal and a space, then the sixteen bytes (5131H): with seven, four, one and 52 characters, each line ends exactly at the last column, so the next one starts on a new line. The register screen enters at 4F2EH for four lines from the memory display address; the full screen enters at 4F33H with sixteen lines.

4F44H - Draw the Full Screen of Memory

The S command's screen: the 256 bytes of the page that holds the memory display address, on sixteen lines. The cursor starts at 3BFFH, one byte before video memory, so the first of the seven spaces of the first line falls outside the screen and the 1024 characters end at 3FFEH: the screen is filled without scrolling.

4F53H - The Register Pair and Flag Names (Data)

Twelve names of three characters, in the order of the register save area at 4065H-407CH: 4EEAH shows them on the register screen and the R command (502CH) looks a name up here to find the word it changes. Then the eight flag names, one for each bit of Register F from bit 7 to bit 0: S sign, Z zero, 1 for bit 5, H half carry, 1 for bit 3, P parity or overflow, N subtract, C carry. Bits 5 and 3 have no name of their own and show 1 when they are set.

4F7FH - G: Go, with up to Two Breakpoints

G aaaa,b1,b2 then ENTER. aaaa, when given, replaces the saved PC at 407BH-407CH; each breakpoint address given is planted by 4FC9H, the first in slot B (4060H-4062H), the second in slot A (405DH-405FH). ENTER ends the line at any point. Then the BREAK trap is turned on with 400FH as its address, so BREAK enters DEBUG again, and the program goes on at 4FA3H with every register taken from the save area.

4FA3H - Run the Program with the Saved Registers

The G command and the single step (50B5H) come here. The eleven words of the save area from AF to SP are pushed onto the stack from the top down and popped into the registers, both sets; the Stack Pointer is set to the program's, the saved PC is pushed onto the program's stack and a RET jumps to it, with Register Pair HL loaded from the save area just before.

4FC9H - Plant a Breakpoint

Register Pair HL = the address, Register Pair DE = the last byte of a slot (4062H for slot B, 405FH for slot A). The byte at the address is kept in the slot, F7H (RST 30H) is written over it and read back: if the byte did not change to F7H (ROM, or no memory there), the command is given up at 4E2FH, which takes back the breakpoints already planted and goes back to the command loop. Otherwise the address is stored in the slot, high byte then low byte going down, and Register Pair DE is left at the last byte of the slot below (405FH after slot B).

4FDAH - M: Change Memory

M aaaa then a space. The address typed (or, when none is typed, the one at 4060H-4061H) becomes the M address at 4060H-4061H, which the memory display marks with bars on both sides of its byte. If ENTER ended the address the command stops there. Otherwise the screen is drawn, the address is shown at the start of line 13 (3F40H) and its byte at the start of line 14 (3F80H) with a minus sign, and a new value is read: a space stores it and goes on to the next address, ENTER stores it and stops, a space or ENTER with no digits leaves the byte as it is, and any other key that is not a hexadecimal digit (X, say) stops without storing. Only the last two digits typed count.

5010H - R: Change a Register Pair

R, the name of a register pair (two letters, a third character for the alternate pairs: AF', BC', DE', HL'), a space, the new value in hexadecimal and ENTER. The name is looked up in the table at 4F53H, which gives the word of the save area at 4065H + 2 x its place; every pair can be changed this way, the Stack Pointer and the PC too. A name not in the table, or ENTER before the value, ends the command with nothing changed; a space or ENTER with no digits leaves the pair as it is. Letters come from 5189H in lower case and are made capitals here (RES 5) to match the table.

505EH - C and I: Single Step

Runs the one instruction at the saved PC. The first byte (or, after a prefix DDH, FDH or EDH, the second) is looked up in one of the three tables at 50E0H: each entry is a mask, a value and a result; the first entry for which the byte AND the mask equals the value gives the result, and when none does the table's last byte is the result. Bits 3-0 of the result are the instruction's length, bits 7-4 its kind: 0 none, 1 JP (HL), 2 JP (IX) or JP (IY), 3 a relative jump (JR, DJNZ), 4 an absolute jump, 5 a return, 6 a call. A breakpoint is planted after the instruction (slot B); for kinds 1-5 a second one at the place it goes to (slot A): Register Pair HL from the save area, Index Register IY from the save area, the relative target, the operand, the return address on the program's stack. A call gets the second breakpoint at its operand for I only; for C it runs in full and stops after it. Then the program runs (4FA3H) and either breakpoint brings it back to DEBUG. A breakpoint that cannot be written (ROM) gives the command up (4FD0H). The RST instructions are not in the tables: they count as one byte with no target.

50E0H - The Instruction Tables of the Single Step (Data)

Three tables of entries of three bytes: a mask, a value and a result. The single step (507DH) takes the first entry for which the instruction byte AND the mask equals the value; each table ends with one byte, below 05H, that is the result when no entry matches. In a result, bits 3-0 are the length of the instruction in bytes and bits 7-4 its kind: 0 none, 1 JP (HL), 2 JP (IX) or JP (IY), 3 a relative jump, 4 an absolute jump, 5 a return, 6 a call. 50E0H is for the first byte of an instruction with no prefix, 510EH for the byte after EDH, 5115H for the byte after DDH or FDH.

5131H - Show Sixteen Bytes of Memory

Register Pair HL = the first address. Shows => and a space, then the sixteen bytes, each after one separator character (5164H): in hexadecimal, two digits; with 405DH = 61H (the A command), a space and the byte as a character, a period for 00H-1FH and C0H-FFH. Register Pair HL ends sixteen bytes further on. Register Pair BC is kept.

5164H - The Separator before a Byte

Register Pair HL = the address of the byte about to be shown, Register B = the bytes left on the line (16 down to 1). Before the byte at the M address (4060H-4061H) the code AAH is shown, a graphics character lit on its right half: a bar just left of the byte. Before the byte after it the code 95H is shown, lit on its left half: a bar just right of the M address's byte. Before any other byte a space. Before the ninth byte of the line (Register B = 08H) one more space splits the line in two halves of eight.

5189H - Read One Key of a Command

Waits for a key and shows it at the cursor. ENTER returns at once, not shown, with the Z FLAG and the CARRY FLAG set. Keys below 20H are ignored. Any other key is made lower case (bit 5 set) and shown, and returns with the CARRY FLAG clear and the Z FLAG set for a comma or a space, clear for anything else. Register Pair DE is kept. SYS9/SYS's extended debugger changes the byte at 5196H (EFH, the SET 5,A of 5195H) to 6FH while text is typed, making the instruction BIT 5,A so that capitals are kept, and puts EFH back afterwards.

51A4H - Read a Hexadecimal Number

Reads keys until a comma, a space or ENTER. When that is the first key, returns at once with the Z FLAG set (the CARRY FLAG too for ENTER) and Register Pair HL as it was. Otherwise Register Pair HL = the number, the last four digits typed, and the Z FLAG is clear; the CARRY FLAG is set when ENTER ended it. A key that is not a hexadecimal digit ends the command: JP C,4E49H back to the command loop, which resets the Stack Pointer (the X key is used for this). SYS9/SYS calls this routine for its own commands.

51C0H - Hexadecimal Digit to Its Value

Register A = a character. Returns Register A = 00H-0FH with the CARRY FLAG clear for 0-9 and a-f (the keys come lower case from 5189H), or the CARRY FLAG set for any other character. Each test is an addition that carries out of Register A when the character is past the end of a range.

51D1H - Hexadecimal Output

51D1H shows the byte at Register Pair HL and steps Register Pair HL past it; 51D5H shows Register Pair HL as four digits; 51DAH shows Register A as two digits; 51E3H shows bits 3-0 of Register A as one digit. Each digit goes to the ROM's display routine at 0033H, which 51EBH jumps to. SYS9/SYS calls 51D1H, 51D5H and 51DAH too.

51EEH - A Byte and a Space, or a Space

51EEH shows Register A as two hexadecimal digits and a space; 51F1H shows only the space. SYS9/SYS calls 51F1H.

51F5H - Show Three Characters

Shows the three bytes from Register Pair HL as characters (the register pair names at 4F53H) and leaves Register Pair HL past them: 51F5H calls 51FBH twice and then goes on into it.