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

FORMAT/CMD

Other Navigation

LDOS 5.3.1 FORMAT/CMD Disassembly - Diskette Formatter (Model I)

FORMAT/CMD is the LDOS utility that lays down cylinders, sectors and a directory on a diskette so that the operating system can read and write it. The command syntax is FORMAT :d (parm,parm,...) with the parameters ABS, CYL, DIR, MPW, NAME, QUERY, SDEN, DDEN, SIDES, STEP, SYSTEM and WAIT. FORMAT produces a DATA disk: only two directory slots are reserved, where a SYSTEM disk configured by BACKUP reserves fifteen in total, those same two plus thirteen more for SYS0/SYS through SYS12/SYS. It is FORMAT that creates the two files DOS maintains itself and never copies, BOOT/SYS on cylinder 0 and DIR/SYS on the directory cylinder.

The program is a single LDOS /CMD load module preceded only by a type-1FH copyright record, Copyright 1991 MISOSYS, Inc., All rights reserved. Twenty-three type-01 load records place 4842 bytes into memory between 6000H and 7673H, and a type-02 record sets the transfer address to 6E00H. Six regions inside that span are deliberately left unloaded because they are working storage, and one of them, 6D00H-6DFFH, is the sector-identifier pointer table the track expander builds. The image was rebuilt from the load records and compared byte for byte against the listing on this page: 4842 of 4842 bytes covered, zero mismatches.

FORMAT runs in two phases that occupy the same memory. The transfer address 6E00H enters the FRONT END, which reads the system configuration sector, parses the command line through @PARAM, prompts for anything still missing, checks the target diskette and then does JP 6000H into the FORMAT ENGINE. The engine expands a packed track-image template into a buffer that begins at 6E00H, on top of the front end that has just finished running, and hands that buffer to the WD1771 Write Track command. This is why the front end has to test HIGH$ before it starts: the buffer it is about to be overwritten by can be as long as 10673 bytes.

FORMAT does not use the resident disk primitives at 4750H-478DH for the formatting pass. It takes a ten-byte copy of the target drive's Drive Code Table entry into 6564H, points Register Pair IY at that copy, and reaches the drive's own driver with JP (IY) through the JP instruction that occupies DCT+00H to DCT+02H. Working on a private copy lets it alter the side-select bit, the current cylinder and the geometry bytes without disturbing the DOS view of the drive. The head is positioned only by Restore and Step In; no seek is ever issued during the format pass.

Only two RST 28H supervisor requests are issued, both from three-byte stubs at 7277H and 727AH. Because the RST 28H dispatcher in SYS0 discards the return address the RST instruction pushed, a stub of the form LD A,code followed by RST 28H returns to whoever CALLed the stub, so no RET is needed and none is present. SYS6 uses the same construction, packing three such stubs nose to tail at 57C5H, 57C8H and 57CBH and CALLing each of them separately.

The first of the two requests, code 84H at 7277H, carries no sub-function. The overlay loader turns a request code into a SYS number with the low nibble less two, so 84H selects SYS2, and SYS2's own entry dispatcher at 4E00H masks the code with 70H and compares the result against 10H for @OPEN, 20H for @INIT, 40H for @CKDRV, 50H for the filename hash and 60H for the password hash. 84H masks to 00H, matches none of them and falls onto the RET at 4E16H. The request therefore does nothing except make SYS2 the resident overlay. That matters because the loader reuses an overlay whose low nibble already matches the one being asked for, so the password hash request 0E4H that FORMAT issues later, which is also SYS2, is answered out of memory without a further directory read.

Two complete boot sectors are carried in the image at 6B00H and 6C00H. Both are assembled to run at 4200H, which is where the Model I boot ROM places cylinder 0 sector 0 before jumping to it, so every internal address inside those two blocks reads 42xxH in the listing even though the bytes live at 6Bxxh and 6Cxxh in FORMAT's image. 6B00H is the single-density boot sector and 6C00H the double-density one; FORMAT patches the directory cylinder and the stepping rate into each from the table of patch addresses at 6900H and then writes them to cylinder 0 sectors 0 and 1.

Load Map

Variable and Buffer List

Track Format Descriptors at 6571H

Four six-byte descriptors, chosen by drive size and density. 6F75H points Register Pair HL at 6571H and adds twelve when DCT+03H bit 5 says the drive is eight inch, so 6571H and 6577H serve five and a quarter inch drives while 657DH and 6583H serve eight inch drives. Within a pair the first entry is single density and the second double density. Each descriptor is a DEFW address of the packed template, a DEFW written straight into DCT+07H and DCT+08H as the drive geometry, and a DEFW giving the memory the expanded image needs.

Packed Track-Image Template Format

A template is a byte-oriented run-length stream with five escape codes. Byte 0 is the sectors per track and byte 1 the cylinder-to-cylinder skew. The sector interleave table follows immediately and is skew plus one plus sectors long: the leading entries are the physical sector numbers in the order they are to be laid down, and the trailing entries are negative wrap values that pull the running pointer back to the head of the list. The compressed stream begins after that table, and behind the stream sits the list of sector numbers the verify pass walks.

Local Disk Driver Call Stubs at 6460H-6494H

Eleven two-byte stubs each load an operation code into Register A and fall into the common tail at 6489H, which puts the operation in Register B, the target drive number in Register C and 20H in Register A and then does JP (IY) into the working Drive Code Table copy. On a fitted unit DCT+00H is a JP to the drive's driver, so the call reaches the resident floppy engine at 45FBH or whatever replacement driver FDUBL or a hard-disk driver has hooked into DCT+01H and DCT+02H.

@PARAM Keyword Table at 72A8H

Nineteen entries of a six-character blank-padded keyword followed by a DEFW result cell, terminated by 00H. Every result cell is the operand field of a LD HL or LD DE instruction somewhere in the front end, so a parameter supplied on the command line is delivered by simply rewriting an instruction.

Cross-Reference Notes

FORMAT issues two RST 28H supervisor requests, and both of them are SYS2. Request 84H at 7277H, issued once immediately after the sign-on and before the configuration sector is read, has no sub-function and SYS2 rejects it with a RET; its only effect is to bring SYS2 into memory. Request 0E4H at 727AH is the SYS2 password hash, taking the eight-byte field at Register Pair DE and returning the sixteen-bit hash in Register Pair HL. Since the two share the low nibble 4, the second is served from the copy the first loaded. Nothing else in the file loads an overlay, so SYS0 is resident throughout and every other external call is either ROM low core or a resident SYS0 vector.

ROM entry points used: 0033H the video driver, 0040H the line input routine, 0049H wait for a key, 0060H the delay loop and 01C9H the Level II clear-screen routine, the last of these only from inside the double-density boot sector image.

Resident SYS0 entry points used: @EXIT 402DH, @ABORT 4030H, @ERROR 4409H, @DSPLY 4467H, @DATE 4470H, @PARAM 4476H, @LOGOT 447BH, RDSECT 4777H, the Drive Code Table address calculator 47A5H and MULTEA 4B6CH. Resident variables read: TIMER$ 4040H, HIGH$ 4049H, SFLAG$ 430FH and MFLAG$ 442FH. The system buffer SBUFF$ 4200H receives the configuration sector.

The two boot sector images pin down how the Hash Index Table is ordered. FORMAT writes the BOOT/SYS record to sector 2 of the directory cylinder and the DIR/SYS record to sector 3, both in slot 0, while giving them Hash Index Table bytes 0 and 1. Both boot sectors then read sector 4 slot 0 and expect to find the resident system loader there. Directory record n is therefore slot 0 of sector 2 plus n for the first thirty-two records, which is why a DATA disk reserves two directory slots and a SYSTEM disk configured by BACKUP reserves fifteen in total, those two plus thirteen more for the /SYS overlays.

FORMAT is the writer of the two files that DOS maintains and never copies. The boot sector it lays down at cylinder 0 sector 0 is the subject of the BOOT/SYS disassembly; the two images carried here at 6B00H and 6C00H are that same program in its single-density and double-density forms, before SYSGEN or SOLE have had a chance to alter it.

6000H - Format Engine Entry and Interrupt Lock-Out

The front end reaches this point with a JP from 71EBH. Register Pair IY holds 6564H, the ten-byte working copy of the target drive's Drive Code Table entry. Everything the operator asked for has already been resolved into that copy: DCT+03H carries the density and side bits, DCT+04H the double-sided and unit bits, DCT+05H the current cylinder, DCT+06H the highest cylinder to be written and DCT+07H with DCT+08H the geometry that matches the chosen template.

6013H - Track Image Expander

This block turns one of the four packed templates into the literal byte stream the WD1771 Write Track command lays on the surface. It writes the track image upward from 6E00H, over the front end that has just finished running, and at the same time writes a table of DEFW pointers at 6D00H recording where in that image every sector identifier field starts. The SYSTEM path re-enters here from 61C1H, which is why the entry is a section of its own.

6095H - Cylinder Format Loop

The track image is complete apart from the three bytes of every sector identifier field that carry the cylinder, the side and the sector number. This block fills those in, writes the track, repeats both for side 1 when the disk is two sided, applies the skew and steps the head in one cylinder. Register Pair BC is the running pointer into the sector interleave table and is deliberately carried from cylinder to cylinder, so the interleave keeps rotating instead of restarting.

60D6H - Write The Track, Change Sides and Step In

Nothing here seeks. FORMAT positions the head only with Restore and Step In, so DCT+05H in the working copy is both the cylinder being written and the value planted in the WD1771 track register by the write engine. Register D must therefore carry the cylinder into the driver and Register Pair HL the buffer.

612EH - Verify and Lock-Out Pass

Every cylinder has been written. This pass reads every sector of every cylinder back and marks the ones that will not read in the map at 6A00H, one byte per cylinder, which later becomes both the granule allocation table and the lock-out table inside the Granule Allocation Table sector. The expected sector numbers come from the list the template carries behind its end of template escape, whose address the expander saved into the operand at 6156H.

61E3H - Verify Failure: Lock Out the Cylinder

Reached from 615FH when the Verify Sector operation returns an error. The read and verify path of the resident engine builds its error code as base 01H plus the position of the lowest set bit of the masked WD1771 status, so a CRC error in bit 3 becomes 04H and a record not found in bit 4 becomes 05H. Those two mean the medium under the head is bad. Anything else, such as not ready in bit 7 or write protected in bit 6, is a fault with the drive rather than the diskette and is reported instead.

61FCH - Rigid Drive Confirmation and the SYSTEM Path

Reached by the JP at 6004H when DCT+04H bit 4 marks the unit as something other than an ordinary floppy, and also by falling through from the SYSTEM branch. Nothing on this path writes a track. A rigid drive has already been low level formatted by its own utility, and the SYSTEM parameter on a floppy means the surface is already good, so all that is wanted is the system information: the boot sectors, the Granule Allocation Table, the Hash Index Table and the two directory records.

6241H - Directory Cylinder Selection

The directory has to live on a cylinder that is entirely readable, and by preference near the middle of the disk so that the average seek to it is short. The DIR parameter overrides the choice outright. Otherwise the search starts at the middle cylinder and works outward in alternating steps of one, two, three and so on, taking the first cylinder whose byte in the granule allocation map at 6A00H is not 0FFH. This code is also the landing point for the ordinary format path, which arrives at 624AH from 61E1H.

629EH - Boot Sector Patching and Cylinder 0

Two complete boot sectors are carried in the image at 6B00H and 6C00H, both assembled to run at 4200H where the Model I boot ROM places cylinder 0 sector 0. Each has to be told which cylinder the directory landed on and how fast to step, so two bytes in each are patched before it is written. Cylinder 0 sector 0 takes the single density copy and sector 1 the double density copy, and the granule allocation map is marked to keep files off the boot area and the directory cylinder.

62FFH - Granule Allocation Table Construction

The Granule Allocation Table image occupies 6A00H to 6AFFH and its offsets are the offsets of the GAT sector itself: 00H the granule allocation map, 60H the lock-out map, CCH and CDH the configuration word, CEH the master password hash, D0H the diskette name and D8H the date. The maps and the hash are already in place; this block builds the configuration word out of the drive geometry and writes the whole image to cylinder 0 sector 3, then initialises the configuration sector at cylinder 0 sector 2.

6364H - Directory Cylinder: GAT, HIT and the Directory Records

Every sector of the directory cylinder is written with a DELETED data address mark, which is what marks a cylinder as the directory. The local stub at 647FH issues that write and the helper at 6497H checks it, and because a deleted mark reads back as status error 06H that helper treats 06H as success and a clean read as failure. Sector 0 takes the Granule Allocation Table, sector 1 the Hash Index Table, sector 2 the BOOT/SYS record, sector 3 the DIR/SYS record and every remaining sector an empty directory sector.

641AH - Normal Exit

The diskette is complete. The machine state taken over at 6007H is handed back, the two closing messages are put out and control returns to the DOS through @EXIT with a success code. The second message is not decoration: the whole format ran with a RET planted over the interrupt vector, so the real time clock has lost every tick that fell in that period.

642FH - Progress Dot, Abort and Machine State Restore

Three short routines that everything else in the engine leans on. 6434H is the common abort, 6437H a second entry for callers that already have their own message in Register Pair HL, and 6440H undoes the interrupt lock-out taken at 6007H and, on drive 0, asks for the system diskette back before anything tries to read a SYS file again.

6460H - Local Disk Driver Call Stubs

FORMAT never goes through the resident disk primitives at 4750H to 478DH. Instead it reaches the drive's own driver directly, through the JP instruction that occupies DCT+00H to DCT+02H of the ten-byte working copy Register Pair IY points at. Eleven two-byte stubs load an operation code and fall into the common tail, which passes the operation in Register B and the drive in Register C. Working on a private copy of the table is what lets the engine flip the side select bit, rewrite the geometry bytes and count cylinders without the DOS ever seeing it.

6497H - Deleted Mark Verify, Error Exits and Small Helpers

6497H is the verify used after every directory sector write, and it is inverted with respect to the ordinary one: a directory sector is written with a DELETED data address mark, which reads back as status error 06H, so 06H is the only answer it accepts and a clean read is a failure. The rest of the block is the error exit, the decimal converter, the prompt and read routine, the two backspace cursor update, and the routine that applies a track format descriptor.

6524H - BOOT/SYS and DIR/SYS Directory Record Templates

Two 32-byte LDOS directory records held ready in the image. FORMAT copies each into the sector buffer at 6D00H and writes it to the directory cylinder, so these are the only two files that exist on a freshly formatted diskette. Both are marked system and invisible and both carry the same update password hash, which is why neither shows in an ordinary directory listing and neither can be killed by accident. Three fields of the DIR/SYS record are filled in at run time once the directory cylinder and the geometry are known.

6564H - Working Storage

Three small areas between the directory record templates and the track format descriptors. The ten bytes at 6564H are not loaded from the file because the front end fills them in from the drive's own Drive Code Table entry, and the two bytes at 656FH are not loaded because the track expander computes them.

6571H - Track Format Descriptors

Four six-byte descriptors, taken in pairs. 6F75H points Register Pair HL at 6571H and adds twelve when DCT+03H bit 5 says the drive is eight inch, so 6571H and 6577H serve five and a quarter inch drives while 657DH and 6583H serve eight inch drives. Within a pair the first is single density and the second double density, and 6F83H and 6F88H plant the two addresses into the operands at 6FEAH and 6FDAH so the density questions can switch between them.

6589H - The Four Packed Track Templates

Each template is a run-length stream that expands into the literal byte sequence the WD1771 Write Track command lays on the surface. Bytes 01H to 0F0H repeat the byte that follows them that many times, with a count of 00H meaning 256, and the five escapes 0F1H to 0F5H open and close the per-sector repeat block, mark an identifier field position, end the template and repeat a two byte pair. Behind each template sits the list of sector numbers the verify pass walks.

66D2H - Engine Message Block, Part 1

Every string the format engine displays. A 03H terminator leaves the cursor where it stands, which is what lets the progress dots and the two digit cylinder counter be written on the same line; a 0DH terminator ends the line. A leading 1DH is the video control code that returns the cursor to the start of the current line, so the verifying message writes straight over the formatting one.

6763H - Restore and Select Side 0

A six-instruction routine sitting inside the message block, called only from 61A3H when the SYSTEM parameter has sent the engine back to re-format cylinder 0 in single density. It brings the head home and puts the side select bit back to side 0, both of which have to be true before the single density pass starts.

676FH - Engine Message Block, Part 2

The remaining engine strings, ending with thirty-two unused bytes that round the block out. Two of these are worth reading together: the format runs with a RET planted over the interrupt vector at 4012H, so the clock stops for the whole of it, and the closing note is the honest consequence of that.

6900H - Boot Sector Step Rate Patch Addresses

Two DEFWs naming the byte inside each boot sector image that carries the WD1771 Seek command. 62B8H and 62E5H read them so that the two low bits of that command, which are the stepping rate, can be replaced with the rate the operator chose before the sector is written.

6ACBH - Granule Allocation Table Image Tail

The Granule Allocation Table image occupies 6A00H to 6AFFH and its offsets are the offsets of the GAT sector itself. Everything below 6ACBH is built at run time and is therefore not loaded from the file; from 6ACBH up the image ships with its fields already in place and only the configuration word, the password hash, the name and the date are filled in.

6B00H - Single Density Boot Sector Image

A complete boot program, assembled to run at 4200H because that is where the Model I boot ROM places cylinder 0 sector 0 before jumping to it. Every internal address in this block therefore reads 42xxH even though the bytes live at 6Bxxh in FORMAT's image; the links below point at the row that holds each byte. Its job is to find the resident system loader in the directory and stream it into memory as an LDOS load module. FORMAT patches two bytes of it before writing it: the directory cylinder at 4202H and the stepping rate in the Seek command at 42BCH. This is the program the BOOT/SYS page documents in its installed form.

6C00H - Double Density Boot Sector Image

The same program written for a double density diskette, and also assembled to run at 4200H. FORMAT writes it to cylinder 0 sector 1, where it sits unused until SOLE is applied; the manual's dual density system disk is a double density pack whose cylinder 0 has been laid down in single density by the SYSTEM parameter, so that the boot ROM can read sector 0 while this copy waits for the double density driver. The differences are all in the disk access: instead of working the WD1771 directly it goes through the Drive Code Table that Register Pair IY points at, it takes the geometry from that table rather than assuming ten sectors, and it reads the Granule Allocation Table first to learn how many sectors a cylinder holds.

6E00H - Front End Entry and the Configuration Sector

The transfer address. The DOS enters here with Register Pair HL addressing the rest of the command line. Before anything else FORMAT makes SYS2 resident, then reads cylinder 0 sector 2 of drive 0, the system configuration sector, and lifts out of it the default stepping rate and the default cylinder count for each of the eight units. MFLAG$ decides which of the two per-drive parameter blocks the sector carries, exactly as SYS7 SYSTEM and SYS6 RESET do.

6E3EH - Command Line: Drive Specification and Parameters

The drive comes first, as a colon followed by a digit below 8, and it is planted into the operand at 648CH where the driver call tail picks it up as Register C. Everything after it is handed to @PARAM with the keyword table at 72A8H, which writes each value straight into the operand field of the instruction that will read it. The five density, sides, cylinder and step cells are then ORed together, and the result becomes the flag that decides whether the operator is asked anything at all.

6E9BH - Defaults, the Working Drive Table Copy and the Drive Present Test

QUERY decides what an absent NAME or MPW means. The cell ships as 0FFFFH, which is what @PARAM also writes for a keyword given without a value, and 0FFFFH in either of those cells makes the code below ask the operator. Answering Q=N puts 0000H there instead, and 0000H means take the default silently. After that the drive's Drive Code Table entry is copied into 6564H and tested.

6EDBH - Diskette Name and Master Password

Both fields are collected the same way: 0000H in the result cell means take the shipped default, 0FFFFH means ask the operator, and anything else is the address of a string on the command line. The name is folded to upper case and written straight into the Granule Allocation Table image at 6AD0H, its GAT offset D0H; the password goes to 727DH and is validated and hashed into GAT offset CEH.

6F6EH - Track Format Descriptor Selection and the Density Question

The four descriptors at 6571H are taken in pairs by drive size, and within a pair by density. The default density is not a guess: DCT+04H bit 6 is the bit FDUBL sets on every unit it hooks, so a machine with no doubler installed is offered no density question at all and gets single density. Each question is skipped when the answer is already known, either because a parameter supplied it or because QUERY was turned off.

6FF3H - Sides and Cylinders

Two more questions, each of which is skipped when a parameter already answered it. The cylinder question is not asked at all for an eight inch drive, which always has 77, nor for a rigid one; that is the manual's rule that the cylinder prompt does not appear for eight inch drives.

704BH - Boot Stepping Rate and the Dual Density Check

The last question, and the only one whose answer is in milliseconds rather than a code. The two tables of acceptable replies differ because the WD1771 steps a five and a quarter inch drive at 6, 12, 20 or 30 to 40 milliseconds and an eight inch one at 3, 6, 10 or 15 to 20. The block ends by refusing SYSTEM on any format that could not produce a bootable dual density diskette.

70CFH - Seed the Granule Map and Call for the Target Diskette

The granule allocation map at 6A00H has to start life saying which granules exist on each cylinder before the verify pass can start taking them away. A cylinder that has n granules gets a byte with its low n bits clear and the rest set, and every cylinder beyond the end of the disk gets 0FFH so that the verify pass and the directory search both stop there. After that, a format on drive 0 asks the operator to change diskettes.