TRS-80 DOS - VTOS 4.0 for the Model I - SYS2/SYS Disassembled

SYS2/SYS

Other Navigation

VTOS 4.0 SYS2/SYS Disassembly - File OPEN, INIT, and Directory Management (Model I)

SYS2/SYS is the file management overlay for VTOS 4.0 (Virtual Technology Operating System v4.0.2 by Randolph Cook). It is loaded into the overlay area at 4E00H-51FFH and provides the core file OPEN, INIT, and supporting routines that allow programs to access files on disk.

The overlay handles six request codes dispatched through the standard RST 28H mechanism. Request code 10H opens an existing file by searching the directory using a two-level matching system: an 8-bit CRC hash for fast rejection followed by a full 11-byte filename comparison for confirmation. Request code 20H opens a new or existing file, first attempting to find the file and falling through to directory slot allocation if not found. The remaining four request codes (40H-60H) expose the internal utility routines - drive select with write-protect detection, filename hash computation, and password hash computation - for use by other overlays.

A notable feature is the INIT handler at 4E1CH, which is triggered when the FCB status byte contains 2AH ('*'). Rather than performing a directory search, INIT populates the FCB directly from a drive configuration table entry, enabling direct sector-level I/O without a file association. The code scans two configuration table ranges (4015H-402CH and 43C0H-43D7H) looking for a matching sector buffer address.

The directory search mechanism distributes new file entries across the directory using the system tick counter (4040H) as a pseudo-random starting offset, reducing clustering. Password verification employs a 16-bit polynomial CRC hash with a special bypass: if the caller provides the blank-password hash, any file matches regardless of its actual password.

The drive select routine at 5147H includes a three-phase FDC index pulse polling technique for write-protect detection, reading the WD1771 status register after confirming a full disk rotation has occurred.

Request Code Summary

Memory Variables Used

Self-Modifying Code Locations

Major Routines

SYS0 Routines Called by SYS2

Error Codes Returned by SYS2

Cross-Reference Notes

SYS2 is loaded via RST 28H with SVC codes 94H (open existing, request 10H) and A4H (open new/existing, request 20H). The SVC stubs at 4424H and 4420H in the SYS0 jump table invoke SYS2 through the overlay dispatcher at 4BA2H.

SYS2 calls extensively into the SYS0 resident module for disk I/O (4B45H read with retry, 4B10H directory write), drive management (478FH drive select, 4B65H track cache), and context management (49E9H overlay context save). The 430FH system flags byte is modified by SYS2: bit 1 is set when an existing file is opened with bit 2 of the access mode set (at 4F4DH), and bit 2 is cleared during the open-new path (at 4F65H).

SYS2 shares the same INIT mechanism as TRSDOS 2.3 SYS2, using FCB status byte 2AH ('*') as the trigger for direct sector I/O setup. The drive configuration tables at 4015H-402CH and 43C0H-43D7H are scanned in pairs, with each 8-byte entry containing a 2-byte sector buffer address at offset +06H/+07H.

4E00H - Request Code Dispatcher

Entry point for the SYS2 overlay. Register A contains the full SVC code from RST 28H. The dispatcher masks bits 4-6 to extract the request code and routes to the appropriate handler. Six request codes are supported (10H through 60H); any other value falls through to RET.

4E1CH - INIT FCB Handler (Direct Sector I/O Setup)

This routine is reached from the Open Existing File handler (4E7CH) when the FCB status byte at IX+00H contains 2AH ('*'), which is the INIT marker. Instead of performing a directory search, INIT populates the FCB directly from a drive configuration table entry, enabling raw sector-level I/O without a file association. The routine scans two configuration table ranges (4015H-402CH and 43C0H-43D7H) looking for an entry whose sector buffer address matches the value in IX+01H/IX+02H.

4E61H - Open New or Existing File Handler (Request 20H)

Entry point for request code 20H. This handler sets up the overlay context via SYS0 at 49E9H, then falls through to the open-new-file logic at 4F5EH with Register A = 00H (indicating no access restrictions). The actual directory search for an existing file is performed within the 4F5EH routine.

4E69H - Open Existing File Handler (Request 10H)

Entry point for request code 10H. This is the primary file open routine that searches the directory for a matching filename. It saves and modifies the system flags at 430FH, checks for the INIT marker ('*' = 2AH), parses the filespec, computes the filename hash, and begins the directory search loop.

4E8CH - Directory Search Loop

With the filespec successfully parsed, this routine computes the filename and password hashes, then searches the directory across multiple drives and sectors. For each directory entry, the 8-bit filename hash is compared first for fast rejection; on a hash match, the full 11-byte filename comparison is performed. Register C tracks the drive number (0-7), and the self-modifying operand at 4E9FH tracks the specific drive identifier (FFH = no specific drive requested).

4ECDH - Hash Match Cleanup and Re-Read Directory

This routine is the error/mismatch exit from the full filename comparison at 4EE2H. When the detailed comparison fails (after a hash match), the saved stack state from the comparison must be cleaned up, the directory sector re-read (since it may have been overwritten), and the scan resumed at the next entry. This is also reached when the directory entry's bit 7 flag indicates a chain continuation entry (not a primary filename entry).

4ED7H - Hash Match - Read Directory and Compare Filename

When the 8-bit hash at a directory entry matches the target filename hash, this routine performs the full verification. It reads the complete directory entry from disk using the SYS0 routine at 4B10H, checks whether the entry is a chain continuation (bit 7 of first byte), and if not, compares all 11 bytes of the filename (8 name + 3 extension) against the parsed filename buffer at 51E8H.

4EE2H - Full Filename Comparison (11-Byte Match)

After the directory entry has been read successfully, this routine checks whether the entry is a chain continuation (bit 7 of byte 0) and, if not, performs a byte-by-byte comparison of the 11-byte filename (8 name + 3 extension) at directory entry offset +05H against the parsed filename buffer at 51E8H. A mismatch jumps to the cleanup routine at 4ECDH.

4EFFH - Match Found - Extract File Metadata and Verify Password

After the full 11-byte filename comparison succeeds, this routine extracts the directory entry metadata and verifies the password. It reads the directory entry flags byte, extracts the extent count from bits 0-2, and checks up to two password hash locations in the extent chain area. The blank-password hash value CAD2H is special: if the caller's password hash matches CAD2H, password verification is bypassed entirely, allowing access to any file without a password.

4F5EH - Open New or Existing File Entry

Entry point for the open-new-or-existing file path. Reached from request 20H (via 4E61H with A=00H) or internally when the open-existing path needs to fall through to creating a new file. This routine clears bit 2 of the system flags at 430FH, then attempts to open an existing file. If the file is not found (error 18H), it falls through to the new-file creation logic.

4F9CH - Write New Directory Entry

A free directory slot has been found by the scanner at 50DDH. This routine writes the filename hash as the entry's first byte, writes the directory sector to disk, then reads the full entry back and populates it with the filename, extension, flags, and padding. Finally it writes the entry to disk and calls the FCB population routine.

4FCEH - Populate FCB From Directory Entry

This routine fills the FCB at IX with the file's metadata extracted from the directory entry. It sets the status byte to 80H (file open), constructs the access mode flags from the saved parameters, copies the sector buffer address, drive number, directory info byte, EOF byte offset, access mode, sector count, and extent chain data from the directory entry into the FCB fields.

5024H - Copy Remaining Extent Chain Into FCB

This loop copies up to 4 additional extent entries from the directory entry into the FCB, accumulating the total granule count in BC. Each extent entry is a 2-byte pair where the second byte's bits 0-4 contain the granule count minus 1. The loop terminates when a terminator byte (FEH or FFH) is encountered or all 4 entries have been processed. Any remaining FCB extent slots are filled with FFH padding.

5045H - Pad Remaining FCB Extent Slots With FFH

When the extent chain terminates early (FEH or FFH encountered before all 4 entries are processed), this routine fills the remaining FCB extent slots with FFH to indicate unused entries. The number of remaining slots is calculated from the loop counter.

5050H - Filespec Parser (NAME/EXT.PASSWORD:DRIVE)

Parses a filespec string from the command line (pointed to by HL) into separate buffers for filename (51E8H, 8 bytes), password (51E0H, 8 bytes), extension (51F0H, 3 bytes within the filename area), and drive number (4E9FH). All buffers are first filled with spaces (20H). The parser handles the format NAME/EXT.PASSWORD:DRIVE, where / separates name from extension, . separates extension from password, and : precedes the drive number. The '!' suffix is detected and flagged.

50B1H - Character Extraction Subroutine

Extracts alphanumeric characters from the command line (at HL) and stores them into a buffer (at DE), up to a maximum of B characters. The first character is accepted if it is a letter (A-Z); subsequent characters are accepted if they are digits (0-9) or letters (A-Z). Extraction stops when a non-alphanumeric character is encountered or the buffer is full. On return, Register A contains the delimiter character that stopped extraction.

50CBH - Compute 8-Bit Filename CRC Hash (Request 50H)

Computes an 8-bit CRC hash over 11 bytes of filename data (8 name + 3 extension) pointed to by HL. The algorithm XORs each byte into an accumulator and rotates left after each byte. The result is stored at 51DEH (both bytes set to the same hash value). A special case ensures the hash is never zero (since 00H is used for empty directory entries): if the computed hash is zero, it is changed to 01H. This routine is also the handler for request code 50H.

50DDH - Scan Directory for Free Entry Slot

Searches the directory for an unused entry slot to hold a new file. Uses the system tick counter at 4040H as a pseudo-random starting offset to distribute new files across the directory, reducing clustering. The routine scans through directory sectors, advancing by 32-byte entry boundaries, and returns Z flag set with HL pointing to the free slot when found.

511EH - Compute 16-Bit Password Hash

Computes a 16-bit polynomial CRC hash over an 8-byte password string. The hash is used for password verification during file open operations. The algorithm processes each byte of the password through a series of bit manipulations, shifts, and XOR operations that produce a well-distributed 16-bit hash value. Entry: DE points to the password buffer (8 bytes, processed in reverse order from offset +07H). Exit: HL contains the 16-bit password hash.

5147H - Select Drive and Detect Write Protect Status

Selects the specified drive, reads the disk's GAT sector, and detects the write-protect status using a 3-phase FDC index pulse polling technique. The routine checks whether the drive has a valid configuration (IY+00H contains a JP instruction C3H) and whether the drive supports write operations (IY+03H bit 3 clear). It reads the GAT sector to extract format parameters and then polls the FDC status register for the index pulse to determine write-protect state. Entry: Register C contains the drive number. Exit: Z flag set if drive valid and accessible; Carry flag indicates write-protect status (set = write-protected).

51A4H - Poll FDC Status Register With Timeout

Polls the FDC status register for index pulse transitions (bit 1) with a timeout based on the system tick counter. Returns the current index pulse state in the Z flag, or forces a timeout exit if the tick counter reaches the target value in Register D. Used by the 3-phase index pulse detection at 516DH-5175H.

51B0H - Timeout or Error Exit for Drive Operations

Error exit point for drive select timeout or disk read failure. Cleans up the stack by popping the saved AF value, forces the carry flag set (OR 01H makes A non-zero, then the JR falls through to POP DE and POP IY), and returns with NZ flag indicating an error.

51B5H - Read Directory Sector

Reads directory sector 1 from the current drive into the buffer at 4200H. Preserves BC and DE. Returns with Z flag set on success, NZ on error (with error code 16H preloaded in Register A). This is the standard directory sector read routine used throughout SYS2.

51C7H - Write Directory Sector

Writes the directory sector buffer at 4200H back to directory sector 1 on the current drive, with optional write-verify. Preserves BC and DE. Returns with the result of the write operation in Register A and flags. Uses the SYS0 write routine at 4768H followed by a conditional verify read at 4772H.

51DEH - Data Area (Runtime Variables and Buffers)

Runtime variable storage and working buffers used by SYS2. These locations are modified during execution by the various file management routines. All values shown are initial/default values from the overlay image on disk; runtime values are set by the routines that use them.

Gap: 51DEH-51FFH
The area from 51DEH to 51FFH (34 bytes) serves as runtime variable storage for SYS2. Although initialized to zeros in the overlay image on disk, these locations are written by the file management routines during execution. The overlay occupies the full 1024-byte slot from 4E00H to 51FFH.