TRS-80 DOS - TRSDOS v2.3 for the Model I - FORMAT/CMD Disassembled

FORMAT/CMD

Other Navigation

TRSDOS v2.3 FORMAT/CMD Disassembly - The Diskette Formatter (Model I)

FORMAT/CMD prepares a blank TRSDOS 2.3 data diskette. It asks for the drive, the diskette name, the creation date, the master password and any tracks to lock out, checks the drive and the diskette, writes all 35 tracks with ten sectors each, reads every sector back, and writes the system information: the boot sector, the allocation table, the hash index table and the directory with the entries of BOOT/SYS and DIR/SYS. It then shows FORMATTING COMPLETE and halts the computer; every other ending (an error, or a diskette the person chose not to format) halts the same way.

The file is 3,840 bytes: a name record (FORMAT), a 169-byte copyright comment record, 14 load records and a transfer record (5200H), then 788 bytes of E5H. The load records hold 2,813 bytes: 5200H-5B9BH, 5CCBH-5CFFH, 5E00H-5EFEH and, last, 5B9CH-5BC8H. At 5225H the program copies 5E00H-5EFFH to 4200H-42FFH: that block is the boot sector FORMAT writes to track 0, sector 0, and FORMAT also calls its display routine (429AH) and its sector read routine (42AAH). On this page the rows of that block show the address they run at, with the file address under it; every other row shows its file address. Every loaded byte is on one row, checked against S:\1\FORMAT.CMD and its listing.

Memory Map

After 5225H:

How FORMAT Works

FORMAT refuses to run when bit 5 of the system flags at 430FH is set, with FORMAT INVALID DURING PROGRAM CHAINING!, unless 4030H holds C7H (the value the ROM itself puts there). The command line is not looked at. The drive number (0-3) becomes a select bit stored at 5768H; the drive is selected and restored, and NOT READY or a head that is not on track 0 afterwards stops FORMAT. The diskette name (one to eight characters, padded with spaces), the creation date (eight characters with slashes in the third and sixth places; the digits are not checked) and the master password (one to eight characters, padded with spaces and hashed by 52F6H, the same calculation as SYS2/SYS's 50D1H) go straight into the allocation table being built at 5C00H.

The lockout table at 5C00H-5C22H starts as FCH for each track. To DO YOU WANT TO LOCK OUT ANY TRACKS ? a Y leads to WHICH TRACKS (1-34) ?, answered with a list such as 5,9-11; each track named gets FFH. The answer to FORMAT THE LOCKED OUT TRACKS? is stored at 548DH.

The diskette is then checked: not ready, no head on track 0, write protected, then the index pulses are timed (no diskette, door open, hard-sectored). When track 0, sector 0 can be read, DISKETTE CONTAINS DATA, FORMAT OR NOT ? asks for Y or N. The directory track is the free track closest to 17: 17, 18, 16, 19, 15 and on outward; it goes into byte 2 of the boot sector (4202H) and is shown in DIRECTORY WILL BE PLACED ON TRACK tt.

Each of tracks 0-34 is built at 5F00H (a gap, then ten sectors in the order 0, 5, 1, 6, 2, 7, 3, 8, 4, 9, each with its ID field and 256 E5H bytes, with the data mark FAH on the directory track and FBH elsewhere) and written with WRITE TRACK, showing FORMATTING TRACK tt. The number of bytes the controller took must be from 0BEDH to 0C68H. Every sector of every track not locked out is then read, showing VERIFYING TRACK tt, SECTOR ss; a sector not found or with a CRC error locks its track out. When the directory track itself is locked out, FORMAT stops with CAN'T FORMAT, DIRECTORY TRACK FLAWED!.

The System Information Written

The table at 5C00H becomes the allocation table: 5C00H-5C22H are copied to 5C60H-5C82H as the lockout table, track 0's byte gets bit 0 set (granule 0, the boot sector, in use) and the directory track's byte becomes FFH. Each sector below is written and read back into 5D00H, and the data mark read must be the one written:

The Boot Sector

The 256 bytes at 4200H are what the ROM loads from track 0, sector 0 when the computer starts and jumps to at 4200H. The code clears the screen, selects drive 0, reads directory sector 4 (entry 0 there is locator 02H, the entry of SYS0/SYS) into 4D00H, and shows NO SYSTEM when that entry is not in use. Otherwise it takes the first extent of the entry, reads the sectors one after the other from the start of that extent, and works through the load records: type 01H blocks are stored at their load address, type 02H gives the transfer address, which it jumps to, and other types are skipped. A sector that cannot be read in two tries gives DISK ERROR. Both messages wait for ENTER and halt.

FORMAT's copy differs from BOOT/SYS's sector 0 in two bytes: byte 02H, the directory track (11H in BOOT/SYS, the track chosen here), and byte 7DH, the low byte of the address the boot code stores 01H to before each sector it reads (E1H in BOOT/SYS, the drive select latch 37E1H; B6H here, 37B6H). A diskette fresh from FORMAT has no SYS0/SYS entry, so its boot stops at NO SYSTEM before that store is reached.

Notes from the Code

• 5483H was meant to look up the lockout byte of the track being formatted, but Register A still holds the directory track there, whose byte is FCH. Every track is formatted with the FBH mark, locked out or not, and the answer to FORMAT THE LOCKED OUT TRACKS? (548DH) is never read.
• The byte count of WRITE TRACK is low when the diskette turns fast (a shorter revolution takes fewer bytes) and high when it turns slowly, but the code shows MOTOR SPEED TOO SLOW for a low count (555DH) and MOTOR SPEED TOO FAST for a high one (5567H).
• 551FH calls 5523H a second time when it returns the NZ FLAG, but 5523H returns only with the Z FLAG of the BIT at 554CH (it halts on every error), so each track is written once.
• With all eight characters of the master password typed, the pad loop at 52E9H starts with Register B = 00H and writes 256 spaces, over 5D08H-5E07H; the boot sector there has already been copied to 4200H.
• The boot code's loader takes a load record length of 02H as no data bytes, 00H as 254 and 01H as 255.
• 5EFFH is not in the file, so the last byte of the boot sector written (42FFH) is whatever memory held there.
• 5585H loads the track into Register A and the call to 5767H replaces it at once.
• RESTORE (5754H) and the waits for BUSY have no time limit.

Variables and Changed Operands

5200H - FORMAT Starts: Boot Sector, Title, Drive, Name, Date, Password

SYS1/SYS loads FORMAT/CMD at 5200H and jumps here. FORMAT refuses to run while bit 5 of the system flags at 430FH is set (unless 4030H holds C7H, the value the ROM itself puts there). It copies the boot sector image at 5E00H-5EFFH to 4200H, where its display routine (429AH) and sector read routine (42AAH) are used by FORMAT too, and it is written to track 0, sector 0 at the end. The command line is not looked at: the drive, the diskette name, the creation date and the master password are always asked for.

52F6H - Hash a Password

Register Pair DE = the eight-byte password. Combines the bytes, from the last to the first, into a sixteen-bit value in Register Pair HL. It is the same calculation as SYS2/SYS's 50D1H, so the master password typed here can be checked by PROT.

5322H - The Lockout Table and the Tracks to Lock Out

Fills 5C00H-5C22H, one byte per track, with FCH (both granules usable) and 5C23H-5CCAH with FFH. The table at 5C00H serves as the lockout table during the format and becomes the allocation table later (55C4H copies it to 5C60H, its lockout part). Then asks whether tracks are to be locked out; a list such as 5,9-11 sets FFH for those tracks. Track 0 cannot be locked out and the highest is 34.

539EH - Check the Drive and the Diskette

Selects the drive and waits, then stops with a message when the drive is not ready, has no head on track 0, or holds a write protected diskette. The index pulses are timed as BACKUP/CMD does: a pulse that does not end means no diskette, a pulse that does not come means an open door, pulses less than 1535H loop turns apart mean a hard-sectored diskette. When track 0, sector 0 can be read the diskette holds data, and 5B9CH asks whether to go on. Then the directory track is chosen.

542FH - Choose the Directory Track

Tries track 17 (11H) first, then 18, 16, 19, 15 and so on outward, taking the first track whose byte in the lockout table is FCH. Tracks 1-34 are all tried; when none is free, CAN'T FORMAT, NO TRACKS AVAILABLE FOR DIRECTORY!. The track chosen goes into byte 2 of the boot sector at 4202H, where SYS0/SYS's 4B35H and the boot code find it.

5467H - Format Each Track

For each track 0-34: shows FORMATTING TRACK tt, picks the data mark (FAH on the directory track, FBH elsewhere), builds the track image at 5F00H (gaps, ten ID fields with the sectors in the order of the table at 576DH, ten data fields of 256 E5H bytes) and writes it with WRITE TRACK (551FH), then steps the head in. 5483H was meant to treat a locked out track (FFH in its table byte) by the answer to FORMAT THE LOCKED OUT TRACKS?: skip it for an answer other than Y, else give it the F9H data mark. It reads the byte of the directory track instead of the track being formatted (Register A still holds the directory track), which is always FCH, so every track is formatted with FBH and the answer has no effect.

551FH - Write One Track

Calls 5523H, and calls it a second time when it returns the NZ FLAG; 5523H returns only with the Z FLAG (it halts on the errors it finds), so the second call never runs. 5523H selects the drive, sends WRITE TRACK and feeds the image at 5F00H to the data register until the controller is done, then sends FORCE INTERRUPT. Lost data halts with CAN'T FORMAT, DISK TRANSFER RATE TOO FAST!; then the number of bytes taken is checked: fewer than 0BEDH gives CAN'T FORMAT, MOTOR SPEED TOO SLOW! and 0C69H or more gives CAN'T FORMAT, MOTOR SPEED TOO FAST!. The image holds 0C21H bytes.

556BH - Verify the Tracks

Reads every sector of every track not locked out, showing VERIFYING TRACK tt, SECTOR ss. RECORD NOT FOUND or a CRC error shows its message, locks the track out (5719H puts FFH in its byte at 5C00H) and goes on with the next track; lost data halts.

55C4H - Write the System Information

Copies the lockout table to 5C60H (bytes 60H-82H of the allocation table) and turns 5C00H-5CFFH into the allocation table: track 0 granule 0 used (the boot sector), the directory track fully used (FFH), the name, the date and the master password hash already in place. The directory track must not have been locked out by the verify. Then it writes the boot sector (track 0, sector 0, FBH mark), the allocation table (directory track, sector 0, FAH), the hash index table with the bytes of BOOT/SYS and DIR/SYS (sector 1), the directory entries of BOOT/SYS (sector 2) and DIR/SYS (sector 3), and zeros in sectors 4-9. Each is read back (56BDH) and its data mark checked: FBH for the boot sector, FAH for the others.

56ADH - Show a Message and Halt

Every end of FORMAT comes here (56B0H for a diskette the person chose not to format), the successful one included, with Register Pair HL = the message. Shows it, shows HIT 'ENTER' TO CONTINUE, waits until ENTER is pressed and executes HALT with interrupts disabled: the processor stops until RESET is pressed. 4200H-42FFH now hold the boot sector, so SYS0/SYS's buffer there is not what TRSDOS left.

56BDH - Write a Sector and Read It Back

Register A = the write command, Register Pair BC = the data, Register D = track, Register E = sector. Writes the sector (56D7H, two tries) and reads it back into 5D00H with the boot sector's 42AAH; either failing shows CAN'T INITIALIZE SYSTEM INFORMATION and halts. Returns the Z FLAG with the controller's status, data mark bits included, from the read back.

56D7H - Write a Sector

Register A = the write command, Register Pair BC = the data, Register D = track, Register E = sector. Tries 56E2H twice. 56E2H selects the drive (5767H), seeks the track, sends the command and gives the controller each byte it asks for, then returns the Z FLAG when the status AND 7CH is 0; on an error it sends FORCE INTERRUPT and returns the NZ FLAG.

5719H - Verify: Lock a Track Out

Reached from 55A3H or 55ABH with Register Pair HL = the message and Register D = the track. Shows the message (: NOT FOUND! or : CRC ERROR! TRACK LOCKED OUT!), puts FFH in the track's byte at 5C00H and goes on with the next track at 55BDH.

5726H - Two Decimal Digits

Register A = a number 0-99. Returns Register C = the tens digit and Register B = the units digit as characters, so that LD (nn),BC stores them in reading order.

5733H - Read a Decimal Number

Register Pair HL = the text. Reads digits into Register E (number times 10 plus the digit, kept to 8 bits) until a character that is not a digit; returns that character in Register A with Register Pair HL past it. No digit at all gives Register E = 0.

5749H - Store Bytes into the Track Image

5749H stores Register B bytes of FFH, 574BH stores Register B bytes of Register C (256 when Register B is 00H), 5751H stores one byte of Register C; each at (HL), moving Register Pair HL on.

5754H - Select and Restore

Selects the drive, sends RESTORE (the head goes to track 0) and waits until BUSY clears; there is no time limit.

5767H - Select the Drive

Writes the drive's select bit to the drive select latch at 37E1H; there is no wait for the motor here.

576DH - Tables and Directory Entries

The sector order of a formatted track, eight spaces for clearing the name, and the two directory entries FORMAT writes: BOOT/SYS (directory sector 2, entry 0) and DIR/SYS (sector 3, entry 0).

57C0H - Messages

The texts FORMAT shows. Prompts end with 03H so the answer follows on the line; the progress lines start with 1DH (cursor to the start of the line), so each is written over the last; their digits are filled in through 5726H.

5B9CH - A Diskette That Holds Data

Called by 5429H when track 0, sector 0 of the diskette can be read. Asks DISKETTE CONTAINS DATA, FORMAT OR NOT ?: N ends FORMAT (after a short pause, with HIT 'ENTER' TO CONTINUE and the HALT); Y selects the drive again, waits and returns to format; anything else asks again.

5BC9H - The Allocation Table Being Built and the Buffers

5C00H-5CFFH becomes the new diskette's granule allocation table; 5C00H-5CCAH are not in the file and are filled at 5322H, while 5CCBH-5CFFH come from the file with the name, date and AUTO fields ready for the answers. 5D00H-5DFFH is the input and sector buffer; 5E00H-5EFFH holds the boot sector image.

4200H - The Boot Sector (Runs at 4200H, Loaded at 5E00H)

The rows from here to 42FEH show the bytes the file loads at 5E00H-5EFEH, at the addresses they run at after 5225H has copied them to 4200H: file address = address shown plus 1C00H. This is the sector FORMAT writes to track 0, sector 0 at 55F4H. When the computer is started, the ROM reads track 0, sector 0 of drive 0 into 4200H and jumps to 4200H; this code then finds SYS0/SYS through the directory and loads it. While FORMAT runs, it uses two routines of this sector itself: 429AH to display text and 42AAH to read a sector.

4275H - Fetch the Next Byte of SYS0/SYS

Returns the next byte of the file in Register A. The read position is kept in the alternate registers: Register Pair BC' = the buffer pointer, Register D' = the track, Register E' = the sector. When the buffer is used up the next sector is read into 4D00H, and the sector number runs on to the next track after sector 9.

4290H - Show an Error and Halt

4290H shows DISK ERROR; 4293H shows the message at Register Pair HL (NO SYSTEM from 4228H). Then waits for ENTER and halts.

429AH - Display Text

Register Pair HL = the text. Shows each character through the ROM up to and including 0DH, or up to 03H without showing it, and returns with Register Pair HL unchanged.

42AAH - Read a Sector

Register D = track, Register E = sector, Register Pair BC = the buffer. Seeks to the track and reads the sector, trying twice. Returns the Z FLAG when read, or the NZ FLAG with Register A = the status AND 5CH.

42E2H - The Texts of the Boot Sector

The screen clear and the two messages, shown through 429AH.