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

SYS12/SYS

Other Navigation

LDOS 5.3.1 SYS12/SYS Disassembly - Directory Services @DODIR and @RAMDIR (Model I)

SYS12/SYS is the last of the twelve LDOS 5.3.1 system overlays. It contains the two "mini" directory services: @DODIR, which either displays an abbreviated directory on the video screen or copies raw directory records into a caller's buffer, and @RAMDIR, which builds a compact table of fixed-length directory records in memory for a program to browse. The MiniDOS filter uses both, and any application that offers its own directory display can call them. Because nothing in the resident kernel depends on it, SYS12/SYS can be purged from a working system diskette when the two mini directory routines are not needed.

The overlay is loaded to 4E00H by the resident overlay loader at 4BF5H and occupies 4E00H through 50FDH, 766 bytes, in one contiguous piece. It also deposits a two-byte load block at 4BC9H in the resident padding area, and the value it deposits, 02FEH, is exactly that 766-byte length. Entry is at 4E00H with the RST 28H request code still in Register A; the overlay masks it with 70H and services two sub-functions, 10H for @RAMDIR (request code 9EH) and 20H for @DODIR (request code AEH, the code loaded by the resident @DODIR vector at 4463H). Any other value returns immediately. Every path RETurns to the RST 28H dispatcher in SYS0/SYS with Register A holding a standard LDOS error number and the Z flag set on success.

Neither service reads the directory a record at a time from disk. Both walk the Hash Index Table, the second sector of the directory cylinder, which holds one non-zero hash byte for every directory record in use and a zero for every free slot. SYS12/SYS reads that whole sector into 5100H-51FFH, a page above its own image that no part of SYS12/SYS occupies, and then steps a record number through it in slot-major order: the low five bits of a record number are the directory sector and the high three bits are the slot within that sector, so the scan adds 20H each time and increments the sector part when that addition carries. Only slots whose hash byte is non-zero are looked up, and a self-modifying compare remembers which directory sector is already sitting in the resident directory buffer at 4200H so that eight consecutive records cost one disk read.

The free-space arithmetic is shared by three of the five entry paths. The Granule Allocation Table, sector 0 of the directory cylinder, is read into the same 5100H page; the count of cylinders to examine is taken from the configuration byte at GAT offset CCH plus 35, and free granules are counted by rotating each GAT byte right with a 1 shifted in from the left, which both tests bit 0 and guarantees the loop ends when the byte has become 0FFH. Granules are converted to sectors through the drive's geometry bytes, and sectors are converted to kilobytes by adding 2 and dividing by 4, since four 256-byte sectors make one K.

Before touching the directory at all, every entry runs the drive-ready test at 50AEH. That routine seeks the drive to the cylinder its control block says the head is already on, then samples the WD1771 status register three times, waiting for the index pulse to go away, come back and go away again. Seeing a full index-pulse cycle inside twenty clock ticks proves a diskette is actually turning; failing to see one returns error 8, device not available.

Variable and Self-Modifying Code List

Address Range	Purpose
4BC9H-4BCAH 2 bytes	Overlay load block deposited in the resident padding area of SYS0/SYS. The word value 02FEH is the length of the SYS12/SYS image, 766 bytes, which is 50FDH minus 4E00H plus one.
4200H-42FFH 256 bytes	SBUFF$, the resident shared directory/sector buffer in SYS0/SYS. DIRRD at 4B10H reads the directory sector holding the wanted record into it, and SYS12/SYS addresses the record as 4200H plus the slot offset.
4480H-4482H 3 bytes	CFCB$, the resident command file control block buffer, borrowed by @DODIR to hold the three-character extension mask copied out of the caller's buffer. The character 24H (a dollar sign) in any position matches anything.
4483H-4492H 16 bytes	CFCB$ plus three, borrowed as the scratch area in which the display path builds each fifteen-character file specification before handing it to @DSPLY.
5100H-51FFH 256 bytes	Scratch page immediately above the SYS12/SYS image, used for the Granule Allocation Table sector on the free-space paths and for the Hash Index Table sector on both directory scans. 51CCH is the low byte of the GAT configuration word (the cylinder count less 35) and 51CDH its high byte, which FORMAT/CMD builds at 6318H to 6335H as the eight inch flag in bit 5, the double density flag in bit 6, the granules per track in bits 2 to 0, bits 7 and 3 always set, and bit 4 set only when the SYSTEM parameter has re-formatted cylinder 0 in single density to make a dual density boot disk. Bit 3 additionally marks a disk in the LDOS 5.3 x.3 extended-dating format and bit 7 exempts it from the DATECONV/CMD system-disk check. 51D0H-51D7H hold the disk name and 51D8H-51DFH the disk date.
4ECAH 1 byte	Self-modifying operand of the CP 0FFH at 4EC9H in the @RAMDIR scan. It caches the directory sector number currently held in SBUFF$ so that the next record in the same sector skips the disk read. Loaded as 0FFH so the first record always reads.
4F5AH 1 byte	Self-modifying operand of the CP 0FFH at 4F59H, the identical directory-sector cache for the @DODIR scan. Loaded as 0FFH.
4F6CH 1 byte	Self-modifying operand of the LD A,00H at 4F6BH, holding the @DODIR function code 0 to 4 taken from Register B at entry. Bit 0 selects buffer output over screen display and bit 1 selects extension filtering.
4FA0H 1 byte	Self-modifying operand of the LD A,00H at 4F9FH, the countdown of file specifications remaining on the current display line. Set to 4 when a display request starts and reloaded with 4 each time a line is completed.
4FB1H 1 byte	Self-modifying operand of the LD A,00H at 4FB0H, the countdown of display lines remaining on the current screen. Set to 0FH when a display request starts and reloaded with 0FH after the operator acknowledges a full screen.
5017H 1 byte	Self-modifying operand of the LD A,00H at 5016H, the ASCII drive digit planted into every file specification the builder produces. Written at 50B1H as the drive number ORed with 30H.

Major Routine List

Address	Routine
4E00H	Request Code Dispatch Masks the RST 28H request code with 70H. 20H is @DODIR and jumps to 4EE6H, 10H is @RAMDIR and falls through to 4E0AH, and anything else returns at once.
4E0AH	@RAMDIR Entry Register B is the drive number, Register C selects the request, and Register Pair HL is the caller's buffer. Rejects a drive number above 7 with error 32, swaps the two registers so Register C is the drive, and runs the drive-ready test. Register C of 0FFH asks for free space, 00H asks for the whole directory, anything else asks for one directory record.
4E1DH	Free-Space Reply Calls the capacity calculator at 5025H, then rewrites the caller's four-byte reply as used kilobytes followed by free kilobytes.
4E3DH	Single Directory Record Request Computes how many directory sectors the drive geometry allows, rejects a record whose sector part is out of range with error 16, reads the record and rejects anything that is not an in-use, primary, visible, non-system entry with error 25.
4E77H	@RAMDIR Record Builder Turns the directory record addressed by Register Pair HL into the 22-byte @RAMDIR record at the buffer addressed by Register Pair DE, and writes a 2BH end marker in the byte after it which the next record overwrites.
4EA6H	Full @RAMDIR Scan Reads the Hash Index Table, walks every record slot in it, and appends a 22-byte record for each qualifying file.
4EE6H	@DODIR Entry Register B is the function code 0 to 4, Register C is the drive number and Register Pair HL is the caller's buffer, whose first three bytes are the extension mask for functions 2 and 3. Function 4 is the disk-information request; a function above 4 is rejected with error 29.
4F1AH	Disk Information Reply Builds the twenty-byte reply: eight bytes of disk name, eight bytes of disk date, the capacity in kilobytes and the free space in kilobytes.
4F2CH	@DODIR Record Iterator Steps the record number to the next Hash Index Table slot and, when the table is exhausted, either writes an 0FFH terminator into the caller's buffer or sends a final carriage return to the screen.
4F4EH	@DODIR Hash Index Table Scan Skips free slots, reads the directory sector when it is not already buffered, and calls the extension filter and then the per-record handler.
4F75H	Per-Record Handler Function code bit 0 set copies eighteen raw directory bytes to the buffer; bit 0 clear builds the file specification and displays it four to a line, fifteen lines to a screen.
4FC4H	Extension Filter Compares the three-character extension of the directory record against the mask in CFCB$, upper-casing the mask characters and treating a dollar sign as a wildcard. Returns NZ to reject the record.
4FE2H	File Specification Builder Builds a fifteen-byte blank-padded NAME/EXT:d string plus an 03H terminator from a directory record into the buffer addressed by Register Pair DE.
5025H	Capacity and Free-Space Calculator Reads the Granule Allocation Table, works out the total sectors on the diskette from the drive geometry and counts the free granules, and stores the total kilobytes and the free kilobytes as two words at the caller's buffer.
5075H	Kilobyte Conversion and Store Multiplies a granule or cylinder count by a sectors-per-unit figure, rounds and divides the sector total by four to give kilobytes, and stores the result as a word. Entered both as a subroutine and by falling through from 5073H.
508BH	Read the Granule Allocation Table Reads sector 0 of the drive's directory cylinder into 5100H, leaving error 20 in Register A for a failure.
509CH	Read the Hash Index Table Reads sector 1 of the drive's directory cylinder into 5100H, leaving error 22 in Register A for a failure.
50AEH	Drive Ready Test Plants the drive digit in the file specification builder, verifies that the unit has a real drive control block, seeks it and waits for a complete WD1771 index-pulse cycle, returning error 8 if none arrives within twenty clock ticks.
50ECH	Index Pulse Sample Compares the clock tick counter against the deadline, and otherwise re-selects the drive and returns the index bit of the WD1771 status register. On the deadline it discards its caller's return address and forces error 8.

Cross-Reference Notes

SYS12/SYS is called from outside by way of two RST 28H request codes. Code AEH is loaded by the resident @DODIR vector at 4463H in SYS0/SYS, so any program that calls @DODIR reaches this overlay. Code 9EH has no resident vector in the LDOS 5.3.1 Model I supervisor-call table and is issued directly by the caller, which is how @RAMDIR is reached. The MiniDOS filter uses both.

SYS12/SYS calls into the resident core of SYS0/SYS for every service it needs: the file-operation prologue at 49F1H, the drive control table lookups GETDCT at 478FH and DCTBYT at 479CH, the disk primitives SEEK at 475EH and RSELCT at 4759H, the directory helpers DIRCYL at 4B65H, RDSSEC at 4B45H and DIRRD at 4B10H, the multiply helpers MULTEA at 4B6CH and @MULT at 44C1H, and @DSPLY at 4467H. It reads the clock tick counter TIMER$ at 4040H. From the Model I ROM it uses the character display routine at 0033H, the wait-for-key routine at 0049H and the clear-screen routine at 01C9H. It issues no RST 28H requests of its own and never touches the WD1771 registers directly; all controller traffic goes through the SYS0/SYS primitives.

4BC9H - Overlay Load Block

Every LDOS overlay deposits a two-byte record into the padding area at the end of the resident RST 28H dispatcher in SYS0/SYS. The word records the length of the overlay image just loaded, which for SYS12/SYS is 02FEH, 766 bytes, matching the span 4E00H through 50FDH. The disassembler renders the two bytes as an instruction; they are data and are never executed.

4E00H - Request Code Dispatch

The overlay is entered here by the self-modified CALL inside the resident RST 28H dispatcher, with Register A still holding the request code the caller placed there. Masking with 70H reduces the code to a sub-function selector: 20H is @DODIR (request code AEH) and 10H is @RAMDIR (request code 9EH).

4E0AH - @RAMDIR Entry and Parameter Validation

The @RAMDIR service is entered with Register B holding the drive number 0 to 7, Register C selecting which of the three replies is wanted, and Register Pair HL addressing the caller's buffer. Register C of 0FFH asks only for the disk's used and free space, 00H asks for a table covering every file on the disk, and any other value asks for one single directory record.

4E1DH - Free-Space Reply

Reached when the caller passed 0FFH in Register C. The calculator at 5025H writes the disk's total capacity in kilobytes into the first word of the caller's buffer and the free space in kilobytes into the second. This section reads both words straight back out, converts the capacity into the space in use by subtracting the free space, and rewrites the buffer as used kilobytes followed by free kilobytes.

4E3AH - Single Record Request and Directory Range Check

Reached when the caller's selector in Register B was not 0FFH. A selector of zero asks for the whole directory and is sent to 4EA6H; anything else is a single-record request, and the code adds one to it to form the directory record number. Before the record can be read, the number of directory sectors the drive's geometry provides is computed from the drive control table so the record number's sector part can be range checked. The formula is the standard LDOS one: sectors per track multiplied by heads, doubled for a double-sided drive, less the two sectors that hold the Granule Allocation Table and the Hash Index Table.

4E69H - Read and Qualify the Requested Record

The record number in Register B and the drive in Register C are handed to the resident DIRRD routine, which reads the containing directory sector into SBUFF$ at 4200H and points Register Pair HL at the record itself. The attribute byte is then tested: only a record that is in use, primary rather than a secondary extended entry, and neither system nor invisible is reported.

4E77H - @RAMDIR Record Builder

The heart of @RAMDIR. Register Pair HL addresses a qualifying 32-byte directory record in SBUFF$ and Register Pair DE addresses the place in the caller's buffer where the reply record goes. The result is a fixed 22-byte record: fifteen bytes of blank-padded file specification, the access level, the end-of-file byte, the logical record length, the ending record number as a word and the file size in kilobytes as a word. A 2BH marker is written in the byte after it, which the next record of a full scan overwrites and which therefore remains as the end-of-table marker after the last record.

4EA6H - Full @RAMDIR Directory Scan

Reached when the caller passed 00H in Register C, asking for every file on the disk. The Hash Index Table is read into 5100H and every one of its 256 slots is examined in slot-major order, the record number stepping by 20H so that all eight slots of one directory sector are visited before moving to the next sector. A self-modifying compare at 4EC9H remembers which directory sector already sits in SBUFF$, so a run of records in the same sector costs a single disk read. Each qualifying file adds a 22-byte record to the caller's buffer and the table ends with the 2BH marker left by the last record built.

4EE6H - @DODIR Entry and Function Dispatch

The @DODIR service is entered with Register B holding a function code 0 to 4, Register C the drive number and Register Pair HL the caller's buffer. Bit 0 of the function code decides whether records go to the caller's buffer or file specifications go to the screen, and bit 1 decides whether the files are filtered by a three-character extension mask taken from the first three bytes of that buffer. Function 4 is a separate request for the disk's name, date, capacity and free space.

4F1AH - Function 4, Disk Information Reply

Function 4 fills a twenty-byte reply: the eight-character disk name, the eight-character disk date, the disk capacity in kilobytes and the free space in kilobytes. The capacity calculator is run first because it is what brings the Granule Allocation Table into 5100H, and the name and date are then copied straight out of that image from GAT offsets D0H and D8H.

4F2CH - @DODIR Record Iterator and End of Scan

Every record handler returns here, because the address 4F2CH is pushed as a return address at 4F6AH before the handler is reached. The iterator steps the record number to the next Hash Index Table slot in the same slot-major order the @RAMDIR scan uses. When the table is exhausted, a buffer request is closed with an 0FFH terminator and a display request with a final carriage return.

4F4EH - @DODIR Hash Index Table Scan

The body of the @DODIR scan. Free Hash Index Table slots are skipped without any disk activity; for an occupied slot the record number is split into its slot offset and its directory sector, the sector is read only if it is not already the one sitting in SBUFF$, and the record is then passed through the extension filter and on to the per-record handler. The return address 4F2CH is pushed by hand before the handler runs, so that both the filter rejecting a record and the handler finishing normally land back on the iterator.

4F75H - Per-Record Handler

Bit 0 of the function code chooses between the two things @DODIR can do with a record that has passed the filter. With the bit set, eighteen bytes of the raw directory record are copied to the caller's buffer: the sixteen bytes from the attribute byte through the extension, then the ending record number word, the four password bytes in between being skipped. With the bit clear, the record is turned into a file specification and displayed.

4F8FH - Directory Display Path

The abbreviated directory display. Only in-use primary records for files that are neither system nor invisible are shown. Each file specification is built into the scratch area at 4483H and sent to @DSPLY, four to a line and fifteen lines to a screen; when a screen fills, the routine waits for a keypress and clears the screen before going on. The two counters are self-modifying operands rather than variables.

4FC4H - Extension Filter

Applied to every record when bit 1 of the @DODIR function code is set. The three characters of the mask copied into CFCB$ at 4F06H are compared against the three extension characters at offset 0DH of the directory record. A mask character of 24H, the dollar sign, matches anything; a mask character of 41H or above has bit 5 cleared so that a lower-case letter typed by the operator matches the upper-case letter stored in the directory.

4FE2H - File Specification Builder

Shared by both services. Register Pair HL addresses offset 0 of a directory record in SBUFF$ and Register Pair DE the place the string is to go. The result is always exactly fifteen bytes followed by an 03H terminator: the name with its trailing blanks removed, a slash and the extension when there is one, a colon, the drive digit and enough blanks to bring the printable part up to a fixed width. Register C carries a running budget of thirteen characters for the name, slash and extension so that the blank padding always makes the total the same.

5025H - Capacity and Free-Space Calculator

Reads the Granule Allocation Table for the drive in Register C and writes two words into the buffer addressed by Register Pair HL: the total capacity of the diskette in kilobytes and the free space in kilobytes. The capacity comes from the drive geometry in the drive control table, the free space from counting zero bits in the allocation table itself. The count of cylinders to examine is taken from the configuration byte at Granule Allocation Table offset CCH, which holds the cylinder count less 35.

5075H - Kilobyte Conversion and Store

Entered twice for every free-space request: once as a subroutine from 5052H, with Register Pair HL holding the number of cylinders and Register A the sectors per cylinder, and once by falling through from 5073H, with Register Pair HL holding the number of free granules and Register A the sectors per granule. Either way the product is a count of 256-byte sectors, which is converted to kilobytes by adding two and dividing by four, and stored as a word at the address in Register Pair BC.

508BH - Read the Granule Allocation Table

Fetches sector 0 of the drive's directory cylinder, the Granule Allocation Table, into the scratch page at 5100H. Register C names the drive. The error code is loaded after the read so that it does not disturb the flags the read routine returned.

509CH - Read the Hash Index Table

Fetches sector 1 of the drive's directory cylinder, the Hash Index Table, into the same scratch page at 5100H. The table holds one byte per directory record: the hash of the file name occupying that record, or zero when the record is free. Both directory scans use it to avoid reading directory sectors that hold nothing.

50AEH - Drive Ready Test

Called by both services before any directory work. It plants the ASCII drive digit in the file specification builder, checks that the unit really has a drive control block, seeks the drive to the cylinder its block says the head is already on, and then watches the WD1771 index-pulse status bit for a complete pulse cycle. A diskette that is present and turning produces that cycle within a few clock ticks; if twenty ticks pass without it, error 8 is returned.

50ECH - Index Pulse Sample

One sample of the WD1771 index-pulse status bit, with the deadline test folded in. When the tick counter has reached the deadline in Register D the routine does not return normally at all: it pops its caller's return address off the stack and jumps into the middle of the ready test's exit sequence, so that a stalled drive unwinds cleanly with error 8 no matter which of the three waits was running.