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

SYS2/SYS

Other Navigation

LDOS 5.3.1 SYS2/SYS Disassembly - File/Device Open and Initialize (Model I)

SYS2/SYS is the LDOS 5.3.1 file and device open/initialize overlay. It is one of the system overlays that share the resident SYS0/SYS core: it is loaded into the transient overlay window at 4E00H and entered with the RST 28H request code in Register A. The overlay masks the request code with 70H to select one of five sub-functions - open an existing file or device, initialize (create) a new file, check a drive and load its geometry from the disk, compute the one-byte directory HIT hash of a filename, or compute the 16-bit password hash. When it finishes it RETurns to the resident RST 28H dispatcher in SYS0.

The open path parses a caller-supplied filespec into its component fields (password, filename, extension and drive), hashes the filename to a single byte and the password to a 16-bit value, then walks each drive's directory. For each drive it verifies the drive is present and ready (the drive-check logic that services @CKDRV), reads the Granule Allocation Table (GAT) sector to obtain the disk geometry, reads the Hash Index Table (HIT) sector, and scans the HIT for a byte matching the filename hash. On a hash hit it reads the full directory record, confirms the eleven-character name and extension match, checks the stored password hashes against the caller's password hash, enforces the access-level protection, and finally builds the caller's File Control Block (FCB) from the directory record. The initialize path performs the same search first; if the file does not exist it allocates a free HIT slot and directory record, writes the new directory entry, and returns a freshly built FCB.

A special case handles device opens: when the first filespec character is an asterisk (*) the overlay searches the resident Device Control Block (DCB) chain (the KI/DO/PR blocks at 4015H and the JL/SI/SO blocks at 43C0H) for the two-character device name and links the FCB to the matching DCB instead of to a disk file.

The overlay is Model I hardware: all disk access is performed through the resident SYS0 disk primitives that drive the memory-mapped WD1771 floppy disk controller at 37ECH-37EFH. SYS2 itself issues no direct controller I/O; it calls the SYS0 SEEK, RESELECT, WRITE-PROTECT and VERIFY-SECTOR primitives and the SYS0 directory read/write routines. The HIT sector is rewritten through the SYS0 WRPROT primitive (disk op 0EH), which lays down a deleted-data address mark, the LDOS convention that distinguishes directory sectors from ordinary data sectors.

Variable List

All SYS2 working variables live in the overlay's own RAM tail (51E1H-51FFH) and in a small reserved block (51A6H-51BCH). These addresses are not loaded from the file image; they are scratch RAM the overlay initializes at run time. Several instruction operands inside the loaded code are patched at run time and are listed here as self-modifying code locations.

Major Routine List

Cross-Reference Notes

SYS2/SYS is invoked by the resident RST 28H dispatcher in SYS0/SYS whenever a caller issues an open, initialize or drive-check request. It calls extensively into the resident SYS0 core: the drive/directory primitives GETDCT (478FH), DCTBYT (479CH), SEEK (475EH), RESELECT (4759H), WRITE-PROTECT (4768H) and VERIFY-SECTOR (4772H); the directory sector routines DIRRD (4B10H), DIRWR (4B1FH) and the directory-track/sector helpers at 4B45H and 4B65H; the multiply helper MULTEA (4B6CH); and the FCB prologue at 49F1H. It reads the SYS0 configuration flags at 430FH and the interrupt tick counter at 4040H, uses the shared 4200H sector buffer, references the resident DCBs at 4015H and 43C0H, and deposits a RET into the SYS0 dispatcher self-modify byte at 4BE9H. Every reference to an address from 4000H through 4DFFH is a call into resident SYS0 and is linked to the SYS0/SYS disassembly page.

4BC9H - Resident Low-RAM Load Block

A two-byte block the overlay loader deposits into SYS0's 4BBC-4BCA unused padding, immediately ahead of the resident exec-drive-op at 4BCBH. It is the same low-RAM slot each SYS overlay writes a small block into; it is not executed on the SYS2 code path.

4E00H - Overlay Entry and Sub-Function Dispatch

The overlay is loaded at 4E00H and entered here by the SYS0 RST 28H dispatcher with Register A holding the request code. Bits 6-4 of the request code (isolated with 70H) select the sub-function; the low nibble carries per-call flags used further on.

4E17H - Filename HIT Hash

Computes the LDOS directory Hash Index Table code for a filename: an XOR-and-rotate hash over the eleven-byte name-plus-extension field pointed to by HL, reduced to a single byte and stored at 51E1H. A hash of zero is reserved (it marks an empty HIT slot) and is forced to one. Reached by sub-function 50H and called from the open path at 4F51H.

4E27H - 16-Bit Password Hash

Computes a 16-bit hash over the eight-byte password field whose base is passed in DE, returning the hash in HL with the Z FLAG set. The result is stored at 51F5H and compared against the owner and update password hashes held in each directory record. Reached by sub-function 60H and called from the open path at 4F57H.

4E52H - Check Drive / Read GAT

Verifies that the current drive is configured, waits for it to become ready, seeks it, and reads the Granule Allocation Table (GAT) sector to obtain the disk geometry and density flags, which it stores into the drive's Drive Code Table (DCT). This is the drive-check logic that services @CKDRV; it is reached by sub-function 40H and called from the open and create search loops. The DCT is the ten-byte-per-drive table based at 4700H (IY): offset 00-02 is the resident JP 45FBH vector, offset 03 the option flags, offset 04 the select-mask/flag byte, offset 05 the current track, offsets 06-09 the geometry.

4ED7H - Drive Ready Poll

A helper the ready wait calls repeatedly. It checks whether the frame-counter deadline in Register D has been reached and reads the drive's index-pulse status bit, returning the Z FLAG for the caller's timing loops. Reaching the deadline diverts to the timeout error path.

4EE3H - Drive Error Exit

The shared error tail for the GAT-read failure and the drive-ready timeout. It discards the saved status, forces an error indication, and rejoins the main exit sequence.

4EE8H - Open Device

Handles a device open, reached from the open path at 4F3EH when the first filespec character is an asterisk. It searches the resident Device Control Block chain (the KI/DO/PR blocks starting at 4015H and the JL/SI/SO blocks at 43C0H) for the caller's two-character device name, then links the caller's FCB to the matching DCB and tags it as a device.

4F2BH - Open File

The sub-function 10H entry. It validates the FCB, parses the filespec, hashes the filename and password, then searches each candidate drive's directory for a matching record. A leading asterisk diverts to the device open. The 4F2EH label is a second entry the create path calls to attempt an open without re-validating the FCB.

4F85H - Advance To Next Drive

Steps the drive counter during a multi-drive search. If a specific drive was requested (4F5EH is not FFH) there is nowhere else to look, so it returns NZ. Otherwise it advances the counter and returns carry while it is still below drive 8.

4F90H - Resume Directory Scan

The continue point used when a HIT hash matched but the directory record failed verification. It unwinds the verifier's saved registers, rereads the HIT sector, and resumes the scan at the next entry.

4F9AH - Verify Directory Record

Entered when a HIT byte matched the filename hash. It reads the corresponding directory record, checks the record is an active primary entry, confirms the full eleven-character name and extension, then compares the caller's password hash against the record's password hash and enforces the access level. On success it records the matched drive and jumps to the FCB finalizer. The LDOS directory record layout used here is: offset 00 attribute byte, offset 05 the eleven-byte name/extension, and a password-hash word further into the record.

5016H - Initialize (Create) File

The sub-function 20H entry. It first attempts an ordinary open; if the file already exists it returns that. If the open reports file-not-found it allocates a free HIT slot and directory record on a candidate drive, writes the new directory entry (attributes, name, password hashes, cleared extents), then builds the FCB and returns with carry set to signal a newly created file.

5084H - Build FCB From Directory Record

Populates the caller's File Control Block (IX) from the located or newly created directory record pointed to by HL. It writes the FCB type and access bytes, initializes the buffer and position fields from the finalizer operands patched during the open, copies the directory-locator bytes, and walks the record's extents to compute the file's end-of-file position.

50EDH - Fill FFH Block

Writes FFH into B consecutive bytes starting at the address in HL, then returns with Register A cleared. It clears directory extent bytes for a new record and the trailing FCB extent slots after the extent walk.

50F4H - Parse Filespec

Splits the caller's filespec (pointed to by HL) into its component fields in the 51E2H buffer. It first blanks all nineteen field bytes, defaults the drive to "search all", scans the eight-character name, then honors an optional / extension, . password and : drive number. Throughout, Register D stays 51H so the LD E,xx instructions simply select the destination sub-field within the 51E2H-51F4H buffer.

513FH - Set Password Field Mode

Called when the filespec contains a password. It patches the create path's directory access mode to the password value, then falls straight into the name-field scanner to copy the eight-character password.

5144H - Scan Name Field

Copies up to B alphanumeric characters from the filespec at HL into the field buffer at DE, stopping at the first non-alphanumeric character, which it returns in Register A. The 5144H entry presets a width of 8 (the name); callers enter at 5146H with their own width for the extension and password. The first character is accepted through the letter test only, and subsequent characters are validated as digits or letters.

5160H - Allocate Free Directory Slot

Computes the number of directory records this disk holds from the drive geometry, then scans the Hash Index Table already in the 4200H buffer for a free (zero) entry within that range. It seeds the scan position from the interrupt tick counter, skips the low HIT entries reserved by the system, and returns the Z FLAG with HL pointing at a free slot, or NZ when the directory is full. The scan limit is written into the self-modified compare at 5197H.

51A6H - Reserved Workspace

Addresses 51A6H through 51BCH (23 bytes) are not present in the file image; the overlay's ORG jumps from the end of the free-slot allocator directly to 51BDH. This region is reserved, uninitialized overlay RAM lying between the allocator and the HIT read/write routine. No SYS2 code reads or writes it.

51BDH - Read / Write HIT Sector

Reads or writes this drive's Hash Index Table sector (sector 1 of the directory track) through the 4200H buffer. It is a dual-entry routine built from overlapping bytes: entering at 51BDH performs a read, while entering one byte later at 51BEH performs a write. Both entries share the sector setup and converge at 51BFH; the read/write choice is carried in the Z FLAG derived from the differing entry byte.

51E1H - Overlay Variable Block

Addresses 51E1H through 51F8H (24 bytes) are not present in the file image; the ORG jumps from 51E0H to 51F9H. This region is the overlay's run-time variable block, initialized by the code above rather than loaded from disk. Its fields are the one-byte filename hash (51E1H), the parsed password/name/extension buffer (51E2H-51F4H) and the 16-bit password hash (51F5H-51F6H).

51F9H - Tail Padding and Directory Template

The final bytes of the loaded image are zero padding. At run time the overlaid region from 51FBH holds the directory-record template staged by the create path (attribute byte at 51FBH) and the caller access flag at 51FFH.