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

SYS10/SYS

Other Navigation

VTOS 4.0 SYS10/SYS Disassembly - Sector Write-Back Overlay (Model I)

SYS10/SYS is the sector write-back overlay for VTOS 4.0 on the TRS-80 Model I. Its sole purpose is to flush a modified sector from an FCB's (File Control Block's) data buffer back to disk, then optionally clear the FCB's internal buffer so it is ready for the next sector.

The overlay loads at 4E00H in the standard VTOS overlay slot and occupies the range 4E00H-4E77H (120 bytes of executable code). It is reached via the RST 28H overlay dispatcher in SYS0.

The overall logic proceeds in two distinct phases depending on the dispatch byte received in the SVC mechanism:

• Phase 1 - Data Sector Write Path (entry at 4E00H). The overlay is entered with a dispatch byte whose upper nibble encodes the operation class. The code first checks whether the FCB's internal info byte (read from the IX register, which points to the FCB) indicates a data sector that actually needs to be written (AND A,0E0H tests the three directory-ownership bits; zero means the FCB holds a pure data sector). If the sector is already clean (zero), execution jumps forward to the FCB-clear path at 4E6DH. Otherwise the overlay calls the standard directory-sector context setup at 49EBH, locates the appropriate drive configuration entry, confirms the sector buffer address and record/sector coordinates are valid, constructs the full 16-bit disk sector address into DE from the FCB's extent-chain table, and writes the sector to disk via 4768H with a read-after-write verify via 4772H. After a successful write, the FCB's dirty-sector indicator byte at (HL) is cleared (RES 4) and the buffer clear loop executes.
• Phase 2 - FCB Buffer Clear Path (entry at 4E6DH). When the sector carries a non-zero directory-ownership value (upper three bits of FCB info byte are non-zero), the overlay is performing a directory sector write-back rather than a data write. In this case it calls the alternate context setup at 49E9H, walks the two drive configuration tables (4015H-402CH and 43C0H-43D7H) to find the matching drive entry (matched by the two-byte drive-type ID in IX+06H/IX+07H), validates that the entry's bit 3 is set (marking it as a terminal/active entry), then clears the 8-byte FCB internal buffer by writing 00H to (IX+00H) through (IX+07H) via a DJNZ loop.

All error returns from subroutine calls use the standard VTOS convention: A contains the error code and RET NZ returns it to the caller. Error codes returned include 14H (Read Error from the write-verify read-back), 15H (Write Error from the sector write), 16H (Directory Read Error), 17H (Directory Write Error), 25H (sector address out of range), and 28H (no matching active drive configuration entry found).

Key Variables and Data Locations

Major Routines

Cross-Reference Notes

SYS10 is called from SYS0 via the RST 28H overlay dispatcher whenever a file write operation determines that the FCB's current sector buffer must be flushed to disk before the next sector can be loaded. It is the write counterpart to the sector-read mechanism built into SYS0's file I/O engine.

4E00H - SYS10 Entry / Dispatch Gate

SYS10 is entered via the RST 28H overlay dispatcher. On entry, Register A holds the dispatch byte supplied by the caller's inline SVC byte. The upper nibble of that byte encodes the operation class. SYS10 handles only class 10H (sector write-back). Any other class indicates a dispatcher mismatch and the routine returns immediately without action.

4E05H - Data Sector Write Path

Execution reaches here with the dispatch class confirmed as 10H. Register IX points to the FCB (File Control Block) for the file whose buffer must be flushed. The first task is to examine the FCB's info byte to determine whether this is a pure data sector write or a directory-ownership write-back. The FCB info byte is held in DE: Register DE points to the current directory entry, and the info byte at (DE) encodes ownership in its upper three bits (bits 7-5). Zero in those bits means this is a pure data sector.

4E1AH - Drive Configuration Lookup and Sector Address Resolution

The drive index is valid (0 or 1). Load the FCB's drive number and directory entry info byte into BC for use in the SYS0 sector validation and write routines, then call the chain of SYS0 subroutines that confirm the sector buffer, locate the sector on disk, and perform the write.

4E28H - Sector Address Extraction Loop

The directory entry is valid. Now extract the 16-bit disk sector address (track and sector number) from the FCB's extent-chain table. The extent chain is an array of 2-byte entries embedded in the directory entry structure starting at offset +16H. Register HL currently points into the sector buffer; the code adjusts HL to point to the correct extent-chain entry for the current sector position, then reads the two-byte sector address from that entry. This loop advances through the chain until it reaches the entry whose embedded address is below the sentinel value 0FEFEH (which marks the end of the allocated chain).

4E3EH - Sector Write Execution

The extent-chain walk is complete. Register HL points one byte past the last valid entry (L now holds a page-aligned offset into the extent chain area). The sector address for this write has been saved to the self-modifying variable at 4E56H. The following code clears the dirty flag bit in the FCB, writes the sector to disk, and then clears the FCB's internal buffer.

4E6DH - Directory Sector Write-Back / FCB Buffer Clear

This path is reached when the FCB info byte's upper three bits (bits 7-5) are non-zero, indicating that the FCB's current buffer holds a directory-track sector rather than a pure data sector. In this case, no data write to the data area of the disk is required here - SYS0 handles directory writes through its own path. SYS10's job is instead to locate the drive configuration entry for this FCB and clear the FCB's 8-byte internal buffer, releasing the sector slot.

The drive configuration tables at 4015H-402CH (table #1) and 43C0H-43D7H (table #2) are walked. The match criterion is the two-byte drive-type ID stored at entry offsets +06H and +07H, compared against the FCB's drive number (IX+06H) and directory info byte (IX+07H).

4E8AH - Table Scan Advance (No Match at Current Entry)

The current entry did not match. Discard the saved entry base, advance HL to the next entry, and check whether the table scan has been exhausted or needs to switch to table #2.

4E9CH - Matched Entry Validation and FCB Buffer Clear

A matching drive configuration entry has been found (HL points to its base). Before zeroing the FCB buffer, validate that the matched entry is an active terminal entry (bit 3 of the entry type byte must be set). Then clear 8 bytes of the FCB's internal buffer by writing 00H to each byte starting at (IX+00H).

4EADH - FCB Internal Buffer Clear (8 Bytes)

The matched drive configuration entry is confirmed as an active terminal entry. Clear the 8-byte internal buffer in the FCB by writing 00H to each of (IX+00H) through (IX+07H). After clearing, check the drive configuration tables one more time to handle any secondary cleanup, then return.

4EB4H - Post-Clear Drive Configuration Check

The FCB internal buffer has been cleared. The code now re-examines the drive configuration table at 4015H to check bit 4 of the system flags byte there. If set, a secondary buffer address is fetched from the table and used to conditionally zero one additional byte at the secondary buffer's first entry. This handles a linked secondary configuration cleanup. The loop then advances through the 4015H table in the same way as the scan above, and finally returns.

4ECAH - Post-Clear Table Advance and Return

Advance HL through the current drive configuration table, checking for the end-of-table sentinel and switching to table #2 at 43C0H if necessary. When both tables are exhausted, return successfully.

4ED9H - Final FCB IX Buffer Clear and Return

Both drive configuration tables have been fully processed. Zero the 8-byte FCB internal buffer via the IX register directly, then return successfully.

4EE4H - Sector Address Extraction Subroutine

This subroutine is called from the extent-chain walk loop at 4E39H. On entry, DE points into the extent chain table (at the current entry), and the loop has already read a 2-byte sector address from the table into DE (track in D, sector in E). This routine reads the track byte via an FDC call to determine the WD1771 step rate and sector count, encodes the result into the self-modifying BIT instruction operand at 4F09H, then returns with HL and DE updated for the next loop iteration.

The FDC step rate is derived from the track number by rotating the upper bits of the track byte into the lower 3 bits. The sector count (number of sectors in this extent chunk) is incremented and stored to 4F09H as the operand of a CB-prefix BIT instruction, which will be executed later to test that sector bit in the WD1771 sector register.

4F14H - Sector Encoding Helper (Self-Modifying Opcode Writer)

This helper subroutine is called from CALL 4F14H at 4F02H. On entry, Register A holds the step-rate field (in bits 2-0) and Register B holds the GAT bitmap byte. The helper encodes the step-rate field into a CB-prefix opcode byte, writes it to 4F1FH (the second byte of the RES instruction at 4F1EH), and executes the RES instruction to clear the appropriate bit in Register B (marking the sector as write-in-progress in the GAT). This is a standard VTOS self-modifying BIT/RES pattern, identical in structure to the GAT bit-clear encoder in SYS8 at 5034H.

4F21H - Sector Buffer Validation (CALL 4F21H)

This subroutine (called at 4E20H) validates that the FCB sector buffer address and record position are legal for a write operation. It calls SYS0's directory I/O setup at 4B65H, then calls 4B45H to read the sector, returning Z on success and A=14H on failure. The data verified here includes the FCB buffer base address and the E parameter (sector type 00H for data sectors).

4F34H - FDC Track/Sector Setup for Data Write (CALL 4F34H)

This subroutine (called at 4E5EH) sets up the WD1771 FDC track and sector registers for the data sector write, then calls 4768H (Write Sector) and 4772H (Write-Verify). It uses the same directory I/O setup as 4F21H but with E = 00H and calls 4768H/4772H instead of 4B45H. Returns Z on success, NZ with A = 15H on write failure.

4F4DH - FCB Buffer Pre-Read (CALL 4F4DH)

This subroutine (called at 4E48H) reads the target data sector into the FCB buffer at 4200H before the write, implementing the read-modify-write (pre-read) cycle. It calls 4B65H and 4B45H with E = 01H (directory sector type), reading into the directory buffer at 4200H. Returns Z on success, A=16H on directory read error.

4F5FH - FCB Buffer Write with Verify (CALL 4F5FH)

This subroutine (called at 4E51H) writes the merged sector from the directory buffer at 4200H to disk and performs the read-after-write verify. Structure mirrors 4F34H but uses E = 01H and HL = 4200H. Returns Z on success, A=17H on write/verify error.