TRS-80 DOS - LDOS 5.3.1 for the Model I - FDUBL/CMD Disassembled

FDUBL/CMD

Other Navigation

LDOS 5.3.1 FDUBL/CMD Disassembly - Double-Density Floppy Driver Installer (Model I)

FDUBL/CMD is the LDOS 5.3.1 utility that installs a resident double-density floppy disk driver on a TRS-80 Model I fitted with a double-density adapter board. The Model I Expansion Interface carries a Western Digital 1771 floppy disk controller, which can only record in single density (FM). A doubler board adds a Western Digital 1791 controller alongside it and provides a latch that decides which of the two chips answers at the memory-mapped controller addresses 37ECH to 37EFH. FDUBL supplies the software half of that arrangement: a replacement floppy driver that sets the density latch before every controller operation, understands both recording densities, and falls back to the other density automatically when a sector cannot be found.

The utility supports the two incompatible doubler designs sold for the Model I. The default is the Radio Shack Double-Density Adapter Kit (catalogue number 26-1143), whose control latch is driven by the three high-order bits of a write to the controller's sector register at 37EEH; those bits feed a one-of-eight decoder on the adapter board that latches both the density selection and the write-precompensation enable. The alternative, selected with the PERCOM parameter, is the Percom Doubler, whose latch is set by writing an otherwise meaningless command byte of 0FEH or 0FFH to the controller's command register at 37ECH and then cancelling it with a Force Interrupt. The Percom, LNW and Omikron boards do not implement write precompensation, so when the Percom variant is built FDUBL patches its own precompensation routine out of the driver entirely.

FDUBL is a transient command: it runs at 5200H, builds the requested variant of a driver module in its own image, relocates that module into high memory below HIGH$ (4049H), and lowers HIGH$ to protect it. The module carries the standard LDOS resident-module header, so it is named and discoverable through the module lookup service (RST 28H request code 0BCH, serviced by SYS10). Its name is $FDD. Once installed, FDUBL walks the Drive Control Table at 4700H and rewrites the driver address inside each drive's JP vector so that every disk operation on every fitted drive is routed through the new module instead of through the resident single-density driver at 45FBH in SYS0.

The driver module itself is a modified copy of the resident SYS0 floppy driver. Track positioning, drive selection and Type I command issue are still performed by the resident routines at 45E0H, 461CH, 462AH, 462DH and 4659H, and the controller status is still translated to an LDOS error number by the resident decoder at 46F4H. What FDUBL adds is the density latch write before each operation, a write-precompensation decision on the Radio Shack board, an unrolled data-request polling loop fast enough to keep up with the doubled MFM data rate, a density-dependent choice of the deleted-data-mark write command (0ABH on the 1771 in FM, 0A9H on the 1791 in MFM), and an error recovery path that toggles the density flag and re-seeds the drive geometry so a single-density diskette can be read on a double-density system and the other way round.

The distributed file carries the applied patch FDUBL1. The patch record set replaces the instruction at 5265H and adds a nine-byte routine at 5574H whose only job is to write 2CH into the relative-jump displacement inside the module header at 540DH. That displacement is the driver's entry point. In the Radio Shack build the header sits at 540CH and the original displacement of 41H correctly reaches the driver dispatcher at 544FH; in the Percom build the header is moved up to 5421H, 21 bytes higher, so the displacement has to be reduced by the same 21 bytes to reach the same dispatcher. Without the patch the Percom variant entered its driver 21 bytes past the dispatcher, in the middle of the operation-decoding chain. FDUBL1 is therefore the fix that makes Percom mode work at all.

Program Structure

The file loads as a single contiguous image from 5200H to 557CH, with a transfer address of 521EH. Everything from 5415H upward is either part of the resident module or install-time source material for it; everything below 5415H is install-time code, tables and messages that are discarded once the module is in place.

Variables and Self-Modified Cells

FDUBL modifies its own image extensively while it decides which variant to build. Every cell below is written by install-time code before the module is relocated, so the value present in the disk file is the Radio Shack default and the value the driver actually runs with may be different.

Major Routines

Cross-Reference Notes

FDUBL calls into the resident SYS0 core for every service it does not implement itself. The install-time code uses @DSPLY (4467H), @PARAM (4476H), @LOGOT (447BH), @ERROR (4409H) and @ABORT (4030H), reads and rewrites HIGH$ (4049H), tests SFLAG$ (430FH) bit 5 to decide whether a JCL job is running, and rewrites the Drive Control Table at 4700H.

The resident driver module continues to depend on six SYS0 entry points. 45E0H selects the drive and writes the drive-select latch at 37E1H. 461CH waits for the controller to become not-busy, re-asserting the drive-select latch on every pass so the motor stays selected. 462AH and 462DH are the two entry points of the resident seek routine, the first including the not-busy wait and the second beginning at the track register write. 4659H issues a Type I command with the drive's stepping rate merged in, and 4662H is its second entry for a command byte that is already assembled. 46FDH is the resident interrupt-suppression cell that the SYSTEM SMOOTH option patches. 46F4H is the resident routine that converts a controller status byte to an LDOS error number, and 46F6H is the base error number inside it, which FDUBL writes directly.

Nothing calls FDUBL. Once installed, the $FDD module is reached only through the Drive Control Table vectors that FDUBL rewrote, and it can be located by name through the resident module lookup service, RST 28H request code 0BCH, which is serviced by SYS10.

5200H - Relocation Address Table

Fifteen 2-byte entries. This is data, not code. Each entry holds the address of a 3-byte or 4-byte instruction inside the driver module whose 16-bit operand refers to another address inside the module. Before the module is copied to high memory the routine at 52B2H walks this table and adds the relocation distance to each of those operands. An entry points at the byte immediately BEFORE the operand, because the relocation loop performs an INC HL after loading the entry, so an entry of 547AH refers to the operand at 547BH-547CH. The last entry is used only by the Radio Shack build; the Percom build decrements the count at 535CH from 15 to 14 to drop it, because the instruction it refers to has already been rewritten to point at a resident SYS0 address that must not be relocated.

521EH - Program Entry, Sign-On Banner and Parameter Scan

The transfer address of the file. LDOS enters here with Register Pair HL pointing at the first character of the command line following the command name. The routine preserves the DOS stack pointer for the exit path, displays the sign-on banner, and hands the command line to @PARAM to pick up the PERCOM and TANDY keywords.

5243H - Percom Variant Construction

Reached only when PERCOM or P appeared on the command line. The Percom Doubler sets its density latch through the controller command register at 37ECH rather than through the sector register at 37EEH, and it provides no write precompensation, so this routine rebuilds the driver: it copies the Percom density latch routine over the Radio Shack one, redirects the two references to the precompensation routine at 5415H to the resident seek routine instead, moves the module header up 21 bytes so that the precompensation routine falls outside the module, and adjusts the length, base, end and relocation count accordingly.

5286H - Duplicate Installation Check

Walks all eight Drive Control Table entries at 4700H. Each entry begins with a 3-byte JP instruction whose operand is the address of the driver serving that drive. This loop follows that operand, steps four bytes into the driver to reach where a resident module header keeps its name-length byte, and compares the five bytes found there against the pattern at 5410H, which is the name-length byte 04H followed by the four characters $FDD. A match means an FDUBL driver is already installed on that drive and the utility refuses to install a second one.

52B2H - Relocation of the Module's Address Operands

Computes how far the module is about to move and applies that distance to every operand named in the relocation address table at 5200H. The module will be copied so that its last byte lands on HIGH$, so the distance is HIGH$ minus the module's present end address, held at 535AH.

52DCH - Module Installation and Drive Control Table Hook-Up

Copies the finished module into high memory so that its last byte occupies HIGH$, lowers HIGH$ by the module length to protect it, and then rewrites the driver address inside the Drive Control Table JP vector of every fitted drive so that all disk operations are routed through the new module.

530BH - Exit

The common exit for both the success and the failure paths. Every LDOS library command returns with the error code in Register Pair HL, zero for success and 0FFFFH for failure, and diverts to @ABORT only when a JCL job is running, which is signalled by bit 5 of SFLAG$ at 430FH.

531DH - Error Message Display and Error Exit

Two error reports sharing one message display sequence. The entry at 531DH loads the address of the "Can't specify both Percom and Tandy!" message and then executes an LD IX instruction whose second byte begins a second, independent LD HL instruction; the entry at 5321H starts on that second byte instead and therefore loads the address of the "Driver is already resident!" message. Both then fall into the same @LOGOT call and error exit.

5333H - @PARAM Keyword Table

The parameter table handed to @PARAM at 522DH. This is data, not code. Each entry is a 6-character keyword padded with blanks followed by the 2-byte address of the cell that receives the parameter's value, and the table is terminated by a zero byte. PERCOM and its abbreviation P both deposit into 523CH, the operand of the LD HL instruction at 523BH. TANDY and its abbreviation T both deposit into 5354H. @PARAM stores 0FFFFH in the named cell when the keyword is present.

5354H - Install-Time Control Variables

Five cells that describe the module about to be installed. This is data, not code. The values shown are those assembled into the file, which describe the Radio Shack build; the Percom construction routine at 5243H overwrites four of the five.

535DH - Message Text

The two error messages and the sign-on banner. This is data, not code. Each message ends with the 0DH terminator that @DSPLY and @LOGOT stop on; the banner contains an embedded 0AH line feed to separate its two lines.

540CH - Resident Module Header

The standard LDOS resident module header, which makes the driver discoverable by name through the module lookup service, RST 28H request code 0BCH. This is data with one executable byte pair: the 18H signature is also the opcode of a relative jump, so the address a Drive Control Table vector points at is simultaneously the header and the driver's entry point. In the Radio Shack build the header stays here at 540CH-5414H; in the Percom build the LDDR at 526EH copies these nine bytes up to 5421H-5429H and the module starts there instead.

5415H - Write Precompensation and Seek (Radio Shack build)

Radio Shack Double-Density Adapter builds only. Write precompensation shifts the timing of recorded bit cells slightly to counteract the crowding that occurs on the inner, shorter tracks of a diskette, and the Radio Shack board implements it while the Percom, LNW and Omikron boards do not. The routine enables precompensation once the head has passed the midpoint of the disk and then hands over to the resident SYS0 seek routine. Its control byte reaches the adapter through the controller's sector register at 37EEH: on the Radio Shack board the three high-order bits of a write to that address drive a one-of-eight decoder that latches the density selection and the precompensation enable, and because a genuine sector number never has those bits set, ordinary sector writes pass through untouched. In the Percom build this routine is not part of the module; the header is copied over 5421H-5429H, the jump at 545CH is redirected to 542AH and the call at 54C2H is redirected to the resident routine at 462AH.

542DH - Density Toggle and Geometry Reseed

Error recovery, called from 5540H when a sector operation fails with a record-not-found status. The most common cause on a double-density system is a diskette recorded in the other density, so this routine inverts the drive's density flag, reloads the two Drive Control Table geometry bytes with the sector and granule layout that matches the new density, and sets the hardware density latch. On alternate retries it also restores the head to track zero.

544FH - Driver Entry and Disk Operation Dispatcher

The driver's entry point. Every Drive Control Table vector that FDUBL rewrote points at the module header, whose relative jump lands here. Register B holds the LDOS disk operation code and Register Pair IY addresses the Drive Control Table entry for the drive concerned. The structure follows the resident SYS0 dispatcher at 45FBH, with the seek and read/write cases redirected into this module and the remaining cases handed straight back to the resident code.

5477H - Read, Verify and Write Sector Setup

Reached from 5457H for every operation code above 07H. Sets the hardware density latch for the drive, chooses the controller command byte and the retry count appropriate to the operation, refuses a write to a write protected drive, and installs the correct two-byte body into the data transfer loop by way of the inline parameter block reader at 54B1H. The three parameter blocks embedded in this routine are read as data by that routine, never executed.

54B1H - Inline Parameter Block Reader

Called with three parameter bytes placed immediately after the CALL. The routine takes the return address off the stack, uses it to read those three bytes, and then discards it, so control never comes back to the caller and instead falls through into the command issue routine below. The first parameter byte sets the base error number inside the resident controller status decoder in SYS0, and the following word is planted as the two-byte body of this module's data transfer loop.

54BFH - Command Issue, Data Transfer and Error Recovery

The heart of the driver, entered by falling through from the parameter block reader and re-entered at the same address for every retry. It performs the implied seek, loads the controller track register, adjusts the deleted data address mark command for the density in use, issues the command, runs the data transfer loop, and then examines the resulting status. A lost data indication retries immediately; a record not found or CRC failure toggles the density before retrying; anything else is converted to an LDOS error number by the resident decoder. The transfer loop itself is written out five times over so that the driver can keep pace with the doubled data rate of a double-density track, where a data request arrives roughly every 16 microseconds.

5558H - Density Latch, Radio Shack Double-Density Adapter

Sets the hardware density selection from the drive's density flag, and is the last routine of the Radio Shack module. On the Radio Shack Double-Density Adapter the three high-order bits of a write to the controller's sector register at 37EEH are decoded by a one-of-eight decoder on the adapter board and used to latch the density selection and the write-precompensation enable; because a real sector number never has those bits set, the ordinary sector writes the resident driver performs are unaffected. When the Percom variant is built, the install-time block move at 5255H overwrites these twelve bytes with the sixteen-byte Percom version from 5564H, so every caller reaches the right mechanism without any call site changing.

5564H - Density Latch, Percom Doubler (install-time source)

The Percom Doubler carries no decoder on the sector register. Its density latch is set instead by writing a command byte to the controller command register at 37ECH that no Western Digital controller implements, 0FEH or 0FFH, which the board recognises and consumes; a Force Interrupt is then issued so that the controller does not sit waiting on the meaningless command. These sixteen bytes are never executed where they are assembled: the install-time block move at 5255H copies them over the Radio Shack routine at 5558H, and this copy falls outside the module and is discarded.

5574H - FDUBL1 Patch Routine

Added to the file by the applied patch FDUBL1, whose patch records replace the instruction at 5265H with a call to this routine and append these nine bytes. Its only purpose is to correct the module header's entry displacement for the Percom build. It runs at install time and is not part of either module.