Percom DoubleDOS 4.24 for the Model I - SYS5/SYS Disassembled

SYS5/SYS

Other Navigation

Percom DoubleDOS 4.24 SYS5/SYS Disassembly (Model I)

SYS5/SYS is the DEBUG monitor of DoubleDOS (DBLDOS in Percom's manual). It is overlay 7 (directory record 07H), loaded at 4E00H by the overlay dispatcher of SYS0/SYS (4BA2H) for request code 87H, which 44B4H gives after pushing Register Pair AF. Four ways lead there: the DEBUG vector 440DH; RST 30H, whose vector 400FH is JP 44B4H, so that a breakpoint (an F7H byte) stops the program; the BREAK key, when the BREAK flag 4315H is armed and the BREAK vector 4316H is 400FH (the interrupt routine of SYS0/SYS, 454FH); and the abnormal exit 4030H, which the DEBUG command of SYS1/SYS turns into CALL 400FH while DEBUG is on (SYS1/SYS 5162H), so that every error that ends a program enters DEBUG.

The file is 1227 bytes: a name record, the copyright record of 169 bytes, one load block, 4E00H-51FFH (1024 bytes), and the transfer address 4E00H. Every loaded byte is on exactly one row below. SYS5/SYS is the same in DoubleDOS 4.20, 4.23 (all three sets) and 4.24.

SYS5/SYS never returns into the dispatcher. It throws away the dispatcher's return address, saves all the program's registers (main, alternate, IX, IY, SP and PC) in 4065H-407CH, takes out its breakpoints, and runs its command loop on the program's own stack. G and the single step put the registers back and go to the program through a RET.

Load Map

The Commands

Each command is one key, typed at the left of the last line; it is shown as it is typed. Numbers are hexadecimal, ended by a space, a comma or ENTER; a key that is not a hexadecimal digit ends the command and the display is shown again. Any other key, ENTER among them, just shows the display again.

There is no command to leave DEBUG: G 402D goes to DOS READY (402DH is JP 4400H).

The Display

The X display puts the cursor at the top of the screen and shows one line for each register: the name, an equals sign and the value as two bytes in hexadecimal, then for AF and AF' the flags, each as its letter when set (S, Z, 1, H, 1, P, N, C for bits 7-0) or a minus sign when clear, and for the other registers an arrow (=>) and the sixteen bytes the register points to. Four lines of memory from the display address follow, each with its address. The S display shows sixteen such lines of memory. The first eight and the last eight bytes of a line are set apart by an extra space.

The ROM's display routine scrolls the screen as soon as a character is written at 3FFFH, the last place (ROM 0541H). Both displays are laid out to end at 3FFEH: the line of each register is 63 characters, so that the 64 character lines of memory start one place early, and the S display starts at 3BFFH, the byte before the screen. Each line of memory starts with seven spaces, the first of them at the end of the line above, and the command letter is typed over the first space of the last line.

Breakpoints and the Single Step

A breakpoint is an RST 30H (F7H) put over the program's byte; the byte and the address are kept, breakpoint 1 at 4060H-4062H and breakpoint 2 at 405DH-405FH. When DEBUG is entered, the saved PC is moved back by one when the byte before it is F7H, so that it points at the breakpoint, and each breakpoint address that still holds F7H gets its byte back (4E2FH). A breakpoint in memory that cannot hold the F7H (the ROM) ends the command.

I and C find the length of the instruction at the PC in a table of masks (50E0H, 510EH after EDH, 5115H after DDH or FDH), put breakpoint 1 after it, and for a jump, a relative jump, a return or (with I) a call breakpoint 2 at its target: the address in the instruction, the PC plus the displacement, the word at the saved SP, or the saved HL, IX or IY for JP (HL), JP (IX) and JP (IY). Then the program runs until one of the two is reached. An RST is stepped as one byte, so its routine runs whole.

Bugs

Every bug found in DoubleDOS is listed, with what a user would do to set it off, on the DoubleDOS reference page.

Differences From the Manual

Percom's manual does not describe DEBUG; it refers to the TRSDOS manual. Its note on BASCOM and L80 (appendix A1), that the BREAK vector they leave behind is cleared by DEBUG (OFF), concerns SYS1/SYS. G always sets the BREAK vector 4316H to DEBUG (4F9CH), over any vector the program had put there.

Notes

Memory Used by SYS5/SYS (Outside the Overlay)

SYS5/SYS writes none of its own bytes. Its variables are at 405DH-407CH, which no other DoubleDOS file uses.

Other Memory

The Stack at 4E00H

Outside Routines

4E00H - Enter DEBUG: Save the Program's Registers

The transfer address of SYS5/SYS, overlay 7. DEBUG (440DH), RST 30H (400FH), the BREAK key while the BREAK vector 4316H is 400FH, and 4030H while DEBUG is on (CALL 400FH) all reach 44B4H, which pushes Register Pair AF and gives request code 87H to the overlay dispatcher; the dispatcher calls 4E00H. On the stack are the dispatcher's return address 4BFEH, the program's Register Pair AF and the program's address (the return address of the RST 30H or CALL, or the address the BREAK interrupt left). SYS5/SYS never returns into the dispatcher: it saves every register in the area at 4065H-407CH and runs its own command loop on the program's stack.

4E2FH - Take the Breakpoints Out

The two breakpoints of G and of the single step are three bytes each: breakpoint 2 at 405DH-405FH and breakpoint 1 at 4060H-4062H, each the address (low byte first) and the byte that RST 30H replaced. Each address that is not 0000H and still holds F7H gets its byte back. Both addresses are cleared, which also clears 405DH-405EH, the A or H display and the S or X screen, and 4060H-4061H, the address of M: they share these bytes.

4E4BH - The Command Loop

The display is shown (X: the registers and four lines of memory, S: a full screen of memory), the cursor goes to 3FC0H, the start of the last line, and one key is read and shown. The letter chooses the command; every command but G returns to 4E4BH, the address pushed at 4E63H. Invalid hexadecimal input in any command also comes back here (51ADH). There is no command to leave DEBUG: G with an address, such as G 402D for DOS READY, does that.

4E99H - S and X: Choose the Display

X clears 405EH and S stores 53H there. With 405EH 00H the display shows the twelve registers and four lines of memory from 4063H; with any other value it shows sixteen lines of memory from the page of 4063H.

4E9EH - U: Show the Display Until a Key

The display is shown again and again, so that memory changed by interrupt tasks or by hardware is seen as it changes. Any key ends it; the key is not taken as a command.

4EA8H - D: Set the Address of the Memory Display

D followed by a hexadecimal address sets 4063H, the first address shown. With no address (ENTER, a space or a comma at once) nothing changes.

4EAEH - Semicolon and Minus Sign: Move the Memory Display

The semicolon moves the memory display forward and the minus sign back: by 40H bytes (four lines) with the X display, by 100H bytes (sixteen lines) with the S display.

4ECBH - A and H: Characters or Hexadecimal

A stores 41H and H stores 48H at 405DH. The memory lines (5131H) show the bytes as characters when 405DH is 41H, in hexadecimal otherwise.

4ECFH - Show the Display

With 405EH 00H (X) the screen is cleared to the top and the twelve registers are shown, one a line: the name, an equals sign and the value as two hexadecimal bytes, then for AF and AF' the eight flags and for the others the sixteen bytes the register points to; four lines of memory from 4063H follow. With 405EH not 00H (S) sixteen lines of memory are shown from the page of 4063H. Both displays start one character early (the last register line is 63 characters, the S display starts at 3BFFH), so that the last character goes to 3FFEH: writing 3FFFH would make the ROM scroll the screen (0541H).

4F54H - The Names of the Registers and the Flags

Twelve names of three characters, in the order of the register area at 4065H-407CH, read by the display (4EDEH) and by R (5029H), then the names of the eight flag bits, read by 4F0DH.

4F80H - G: Go to the Program

G, then an optional hexadecimal address (the new PC), then up to two breakpoint addresses, each ended by a space or a comma; ENTER ends the line at any point. Each breakpoint gets an RST 30H (F7H), its address and the byte it replaced kept at 4060H-4062H (the first) and 405DH-405FH (the second). The BREAK vector is set to DEBUG and the program's registers are put back.

4FA4H - Put the Registers Back and Go

The eleven words AF to SP of the register area are pushed, from SP down to AF, and popped into the registers, the alternate set through EX AF,AF' and EXX; the Stack Pointer becomes the saved SP and the saved PC is reached through a RET. The single step (50B4H) also goes to the program here. The interrupts are left as they are.

4FCAH - Place a Breakpoint

Register Pair HL is the address and Register Pair DE the last byte of the entry, filled downwards: the byte at the address, then its high and low bytes. The address gets F7H, RST 30H. A byte that does not keep the F7H (ROM, or no memory) ends the command: 4E2FH takes out the breakpoints placed and the command loop starts again.

4FDBH - M: Change Memory

M, then an optional hexadecimal address (else the address at 4060H, which the entry to DEBUG clears to 0000H), then the new bytes, each ended by a space or a comma; ENTER ends. Before each byte the display is shown with the byte marked (AAH before it, 95H after it, at 5165H), its address on the line at 3F40H and its value and a minus sign at 3F80H. A space or a comma with no number leaves the byte as it is and goes to the next.

5011H - R: Change a Register

R, the two letters of a register's name and, for an alternate register, a quote, then a space or a comma and the new value in hexadecimal. The name is looked up in the twelve names at 4F54H and the value stored in the register area, from which G and the single step put it back. A name that is not found, or ENTER after the name, does nothing.

505DH - I and C: Single Step

The instruction at the saved PC is looked up in one of three tables of three byte entries (mask, value, kind and length): 50E0H for an instruction without a prefix, 510EH after EDH, 5115H after DDH or FDH. The first entry whose mask, ANDed with the opcode (the byte after the prefix), gives its value is taken; a byte below 05H ends a table and is the kind and length of every other instruction. Breakpoint 1 goes after the instruction, and for a jump, call or return breakpoint 2 goes at its target. Then the program runs (4FA4H) until one of them is reached. C differs from I only at a CALL: C lets the called routine run whole, I stops at its first instruction.

50E0H - The Table of the Instructions Without a Prefix

Each entry is a mask, a value and a byte whose bits 7-4 give the kind (00H goes on to the next instruction only, 10H JP (HL), 20H JP (IX) or JP (IY), 30H a relative jump, 40H a jump to an address, 50H a return, 60H a call) and bits 3-0 the length. The opcode ANDed with the mask must give the value.

510EH - The Table of the Instructions After EDH

Opcodes after the prefix EDH; the length counts the prefix.

5115H - The Table of the Instructions After DDH or FDH

Opcodes after the prefix of Index Register IX or IY; the length counts the prefix.

5131H - Show Sixteen Bytes

An equals sign, a greater than sign and a space, then the sixteen bytes at Register Pair HL, each after a separator (5165H) and with an extra space after the eighth: in hexadecimal, or with A (405DH 41H) as a space and the character, a period for a byte below 20H or from C0H. Register Pair HL steps past the bytes; Register Pair BC is kept.

5165H - Show the Separator Before a Byte

Normally a space. Before the byte at the address of M (4060H) it is AAH, a graphics block with the left column lit, and before the byte after it 95H, a block with the right column lit, so the byte M changes is framed. Before the ninth byte (Register B 08H) an extra space splits the line in two.

518AH - Read and Show a Key

Wait for a key through ROM 0049H. ENTER returns with the C FLAG and the Z FLAG set and is not shown; the other control codes below 20H are ignored. Every other key is shown and returned in Register A, with the Z FLAG set for a comma or a space and the C FLAG clear. Register Pair DE is kept.

51A3H - Read a Hexadecimal Number

Keys are read through 518AH and shown. ENTER, a comma or a space at once returns the Z FLAG set and Register Pair HL unchanged (with the C FLAG for ENTER). Otherwise hexadecimal digits are taken into Register Pair HL, the last four counting, until ENTER, a comma or a space: the NZ FLAG is returned, with the C FLAG set when ENTER ended the number. Any other key ends the command: the command loop starts again at 4E4BH.

51D0H - Show Bytes in Hexadecimal

51D0H shows the byte at Register Pair HL and steps Register Pair HL past it; 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 the three characters at Register Pair HL. All of them leave through 51ECH to ROM 0033H.