TRS-80 DOS - LDOS 5.3.1 for the Model I - SYS9/SYS Disassembled

SYS9/SYS

Other Navigation

LDOS 5.3.1 SYS9/SYS Disassembly - Extended DEBUG Commands (Model I)

SYS9/SYS is what the DEBUG (EXT) option installs. On its own the DEBUG monitor in SYS5/SYS understands a small set of single-key commands; anything else it does not recognise is passed to a resident vector at 4310H, which by default holds 4876H, an OR A followed by a RET that does nothing at all. SYS9/SYS captures that vector and hangs thirteen further commands off it.

The overlay is unusual in that almost none of it runs where it is loaded. The first thirty-eight bytes are an installer: they check the vector still holds its default, so that a second DEBUG (EXT) cannot install the extension twice, lower HIGH$ at 4049H by 03D8H bytes to reserve space at the top of memory, copy the remaining 03D8H bytes of the overlay up into it, and point 4310H at the copy. The overlay then returns and is never needed again; the extension it left behind lives in high memory for as long as the machine is up.

What gets copied is a properly formed resident module. Its first byte is 18H, the relative jump that every LDOS module header begins with, hopping over the header to the code; the word at offset 2 is the link to the previous module, which the installer fills in with the value HIGH$ had before it was lowered; the byte at offset 4 holds the name length in its low nibble; and the six characters that follow spell EXTDBG. That is exactly the layout the module lookup in SYS10/SYS walks when a program asks whether a named module is resident, so the extension can be found by name like any driver or filter.

Copying code to an address decided at run time only works if the code does not care where it is, and this module is written so that it does not. Every transfer inside it is a relative jump, of which there are sixty, and every absolute address it names belongs to something that does not move: the ROM at 0033H and 003BH, the resident core at 402DH, 4763H, 4768H, 4777H and 478FH, and six routines in the SYS5/SYS DEBUG overlay. It never refers to itself by an absolute address at all.

Those six SYS5/SYS routines are worth spelling out, because at first sight they look like references into the module itself. The addresses 5189H, 51A4H, 51D1H, 51D5H, 51DAH and 51F1H fall inside the range the overlay occupies when it is loaded, but the module never executes at those addresses once it has been relocated. They are the DEBUG monitor's own single-key command reader, hexadecimal parameter parser and hexadecimal display routines, which sit at fixed addresses in the transient overlay region whenever DEBUG is resident. The extension borrows all of its parsing and display from them, which is why it fits into 03D8H bytes while offering as much as it does.

It borrows DEBUG's variables too. The memory-modify pointer at 4060H and the memory-display window at 4063H in the save area DBGSV$ are read as the default operands of most commands and written back afterwards, so that the extended commands and DEBUG's own display stay in step; 4062H and 405FH are used as scratch to remember the last value searched for; 405EH is the screen-layout flag, which the disk read command sets to 73H so that DEBUG comes back showing the sector that was just read; and 407BH is the saved program counter of the program under test, which the j command increments.

The commands themselves fall into three groups. Seven work on memory: b moves a block, f fills a range, e and t examine and alter it as hexadecimal and as text, l and w search for a byte and for a two-byte value, and v compares two blocks and stops at the first difference. Three are about control and hardware: j steps the saved program counter over a byte, q reads and writes Z80 ports, and o leaves DEBUG through the resident @EXIT vector. One, n, walks from one record of an LDOS load module to the next by decoding its length byte. The digits 0 to 7 open raw disk sector access on that drive, and @ prints a range of memory to the printer.

The overlay spans 4E00H through 51FDH plus the usual two-byte load block at 4BC9H, and its transfer address is 4E00H. It may be purged if the extended commands are not wanted, and keeping it serves no purpose if SYS5/SYS has itself been purged.

Extended Commands

Memory Map

Borrowed SYS5/SYS Routines and DEBUG Variables

Cross-References

SYS9/SYS is loaded by RST 28H request code 8BH, issued by the DEBUG command in SYS7/SYS when its EXT option is given and by SYS5/SYS itself. Unlike the other overlays it does not mask the request code at all, since it has only one thing to do. It is undone by the DEBUG OFF and RESET paths in SYS7/SYS, which put 4876H back into the vector at 4310H.

Its whole working life is spent inside SYS5/SYS, whose command loop calls it, whose parser and display routines it borrows, and whose save area DBGSV$ it shares. For raw disk access it calls the resident primitives in SYS0/SYS: GETDCT at 478FH for the drive geometry, and RDSECT at 4777H, WRSECT at 4763H and WRPROT at 4768H for the transfers, the last of these being the same deleted-data write that SYS8/SYS and SYS10/SYS use for the Granule Allocation Table and Hash Index Table. The module header it builds is read by the resident module lookup in SYS10/SYS, request code 0BCH.

4BC9H - Overlay Load Block

The two bytes every SYS overlay deposits into the padding area of the resident core immediately below the RST 28H dispatcher. They are data, not instructions, and are never executed.

4E00H - Install the Extended Command Module

The overlay itself does almost nothing: it checks that no extension is already installed, reserves room at the top of memory, copies its own body up there as a resident module named EXTDBG, links it into the chain of resident modules and points the resident vector at 4310H at it. Once that is done the overlay is finished with and the extension lives on in high memory for as long as the machine is up.

4E26H - Resident Module Header

The first eleven bytes of the relocatable module, in the standard LDOS resident module format. The installer above copies this header and everything after it into high memory, and the module lookup in SYS10/SYS walks exactly these fields when a program asks whether a named module is present.

4E31H - Command Dispatch and the o Command

This is the first byte the resident vector reaches, and it is where SYS5/SYS DEBUG sends every command character it does not recognise, with that character in Register A. The tests run one after another down the whole of the module. The first of them, o, asks for confirmation and then leaves DEBUG altogether through the resident @EXIT vector.

4E3CH - The b Command, Block Move

Moves a block of memory. The source, destination and length are each collected in turn, any of them defaulting to what DEBUG is already pointing at, and anything defaulted is echoed so the operator can see what was assumed. The destination pointer is left advanced so that repeating the command carries straight on.

4E88H - The e Command, Examine and Enter

Walks through memory a byte at a time, showing each one and offering a hyphen prompt at which a replacement may be typed. Typing nothing leaves the byte as it stands and moves on, so the command doubles as a slow scroll through memory.

4EBBH - The f Command, Fill Memory

Fills a range of memory with a single byte value. The start, end and fill byte are collected in turn, and the loop stops as soon as the current address reaches the end of the range.

4EDBH - The j Command, Skip a Byte

Adds one to the program counter that DEBUG saved when it was entered, so that the program under test restarts one byte further on. It is the way past a breakpoint opcode or an instruction that is not to be executed.

4EE7H - The l Command, Locate a Byte

Searches forward through memory for a byte value, using the Z80 block-compare instruction with a count of zero so that the whole of memory is covered. The value is remembered so that repeating the command searches for the same one, and a match leaves both the editing pointer and the display window sitting on it.

4F2EH - The n Command, Next Load Record

Steps to the next record of an LDOS load module. The byte after the record type is its length, and a length below three means the count has wrapped and 256 must be added back, which is the same convention the system loader itself follows. The command is what makes it practical to walk through a program file in memory.

4F4FH - The q Command, Port Input and Output

Reads or writes a Z80 port. Giving only a port number reads it and shows the value; giving a port number and a value writes it. Because the port number is taken into Register C the full sixteen-bit port addressing of the Z80 is available.

4F73H - The t Command, Text Entry

The character-oriented counterpart of the e command, for patching text rather than opcodes. Each byte is shown as a character, a hyphen prompt invites a replacement, and typing a space leaves the byte alone. To let ordinary text through, the routine patches one byte inside the DEBUG keyboard reader before each keystroke and puts it back afterwards.

4FBBH - The v Command, Verify Two Blocks

Compares two blocks of memory and stops at the first difference, leaving one pointer on each block so that the mismatch can be examined at once. Running to the end without a difference leaves both pointers past the blocks.

5016H - The w Command, Locate a Word

The two-byte form of the l command. The block compare finds a byte matching the low half and the byte after it is then tested against the high half, the search resuming from the same place when only the low half matched.

506CH - The Disk Sector Commands

A digit key names a drive and opens the disk commands, which read and write raw sectors. The drive geometry is read from the Drive Code Table to work out how many sectors a cylinder holds, so that a transfer can roll from one cylinder to the next and so that naming no sector transfers a whole cylinder. Three operations are offered: r reads, w writes, and * writes with a deleted-data address mark as the directory cylinder is recorded. An error is shown bracketed by asterisks and the operator decides whether to carry on, and after a read DEBUG is switched to its full-memory screen showing the data.

513EH - The @ Command, Print a Memory Range

Prints a range of memory to the printer, sixteen bytes to a line, as a four-digit address followed by the bytes in hexadecimal grouped in fours and then the same bytes as characters, with a full stop standing in for anything that cannot be printed. The hexadecimal digits are produced without a lookup table by the classic add-90H, decimal-adjust, add-40H-with-carry, decimal-adjust sequence.