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

BACKUP/CMD

Other Navigation

TRSDOS v2.3 BACKUP/CMD Disassembly - The Diskette Copy Utility (Model I)

BACKUP/CMD copies a TRSDOS 2.3 diskette track by track, on two drives or on one drive with diskette changes. It asks for (or takes from the command line) the source and destination drives and the backup date, checks both drives, formats the destination when it cannot be read, refuses a readable destination whose pack ID differs from the source's, copies every track that holds data, reads each sector back, and writes the source's allocation table with the new date to the destination. It then shows BACKUP COMPLETE and halts the computer: the copy routines are moved over SYS0/SYS at 4200H, so there is no TRSDOS left to return to.

The file is 3,840 bytes: a name record (BACKUP), a 169-byte copyright comment record, 14 load records and a transfer record (5200H), then 616 bytes of E5H. The load records hold 2,985 bytes: 5200H-5AA3H, 5AAEH-5AAFH and 5F9BH-629DH. At 52CAH the program copies 559BH-609AH to 4200H-4CFFH; the code and messages at 559BH-5AAFH run there, at their file address minus 139BH. On this page those rows 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\BACKUP.CMD and its listing.

Memory Map

After 52CAH:

How BACKUP Works

BACKUP refuses to run when bit 5 of the system flags at 430FH is set, with SINGLE DRIVE BACKUP INVALID DURING PROGRAM CHAINING!, before it knows the drives. The drives may be given as BACKUP :s :d (anything between the two drive numbers is skipped); otherwise, or when 4030H holds C7H (the value the ROM itself puts there, not TRSDOS's error exit), they are asked for. The date comes from SYS0/SYS (4470H) when its month byte is not 0, else it is asked for: eight characters with slashes in the third and sixth places.

The two drive numbers become select bits (01H, 02H, 04H, 08H) stored in the copy code. When they are the same, BACKUP works on one drive and asks for INSERT SOURCE DISK or INSERT DESTINATION DISK each time it needs the other diskette; the prompt blinks until ENTER is pressed. On one drive every diskette inserted is checked: the source by its boot sector's first byte (00H) and its pack ID, the destination by the 76H that BACKUP writes as the first byte of its boot sector at the start of the copy.

Both drives are restored to track 0; NOT READY or a head not on track 0 stops BACKUP with a message. The source's boot sector gives the directory track (byte 2), whose sector 0, the allocation table, is read to 4900H. When the destination's boot sector cannot be read, the destination is formatted. When it can, its allocation table must have the same bytes CEH-D7H as the source's (the master password hash and the diskette name, which BACKUP calls the pack ID); a different diskette is refused, so BACKUP only writes over blank diskettes or earlier backups of the same diskette.

Formatting the Destination

BACKUP first times the index pulses of the destination: a pulse that does not end means no diskette, a pulse that does not come means the door is open, and pulses too close together mean a hard-sectored diskette. Each of the 35 tracks is then built at 6300H (ten sectors of 256 E5H bytes, in the order 0, 5, 1, 6, 2, 7, 3, 8, 4, 9, with the FAH data mark on the directory track and FBH elsewhere) and written with WRITE TRACK. The number of bytes the controller took is checked: fewer than 0BEDH gives MOTOR SPEED TOO SLOW, 0C69H or more MOTOR SPEED TOO FAST. Every sector is then read; a track with a sector not found or with a CRC error is locked out (FFH in the table at 4A00H). Finally every granule the source uses must lie on a destination track that is not locked out.

The Copy

The copy marks the destination's boot sector with 76H, then works in passes. A load pass reads, from track 0 up, every track whose allocation byte shows a granule in use (and not locked out on the source) into memory from 4D00H, showing LOADING TRACK tt, SECTOR ss; it stops after one track on two drives, or when the tracks that fit (4713H) are loaded on one drive. The write pass writes those tracks to the destination at the same track and sector, showing COPYING, with the data mark the source's sector 9 had, and reads each sector back (VERIFYING). Tracks without data are neither read nor written. At the end the source's allocation table, with the backup date at bytes D8H-DFH, is written to the destination's directory track, the boot sector gets its real first byte back, and BACKUP COMPLETE is shown.

Errors end BACKUP the same way as success: the message, HIT 'ENTER' TO CONTINUE, and HALT after ENTER. The read and write routines try each sector twice; the read accepts the FAH data mark of directory sectors.

Notes from the Code

• The refusal at 520CH tests only bit 5 of 430FH, but its message speaks of a single drive backup: the drives have not been read yet.
• The format's byte count 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 (54DFH) and MOTOR SPEED TOO FAST for a high one (54E9H).
• 54A3H calls 54A7H a second time when it returns the NZ FLAG, but 54A7H returns only with the Z FLAG of the BIT at 54CEH (it halts on every error), so each track is written once.
• The destination's allocation table is the source's with the new date (434FH-4368H): the lockout table the format made, with the tracks it locked out, is not written to it, and 4A00H, which 42C4H fills during the copy, is never used.
• Every sector of a track is written with the data mark of the source's sector 9 (4284H, 42F5H-42FEH).
• The read back after each write checks only that the sector can be read; the data read is not compared with the data written.
• 5507H loads the track into Register A and 5508H replaces it with the sector at once.
• RESTORE (441AH) and the waits for BUSY have no time limit.

Variables and Changed Operands

Addresses Outside BACKUP/CMD

5200H - BACKUP Starts: Title and Source Drive

SYS1/SYS loads BACKUP/CMD at 5200H and jumps here with Register Pair HL = the command line after the name. BACKUP takes the source and destination drive numbers from the command line (each after a colon) or asks for them, and takes the backup date from SYS0/SYS's date or asks for it. When the byte at 4030H is C7H (RST 00H, the value the ROM's own start-up puts there) instead of TRSDOS's exit after an error, the command line and the date are not used and everything is asked for. Until 52CAH the program uses SYS0/SYS's message routines; after that it overwrites 4200H-4CFFH and works alone.

521CH - Title, then the Source Drive

Shows the title, then reads the source drive number: from the command line when it starts with a colon, else by asking SOURCE DRIVE NUMBER ?. A digit 0-3 is turned into a SET n,A instruction whose result is the drive's select bit, stored in the relocated code at 442BH.

5294H - The Backup Date

Takes SYS0/SYS's date (MM/DD/YY through 4470H) when TRSDOS is present and its month byte at 4046H is not 0; otherwise asks BACKUP DATE (MM/DD/YY) ? and accepts any eight characters with slashes in the third and sixth places. The date goes to 5AA5H-5AACH, which 52CAH moves to 470AH-4711H; it becomes the date of the backup's allocation table (434FH).

52CAH - Move the Copy Code to 4200H and Check the Diskettes

Copies 0B00H bytes from 559BH to 4200H-4CFFH: the copy routines (559BH-5AAFH, which run at 4200H-4714H) and, after them, memory BACKUP uses as work tables. From here SYS0/SYS is gone and BACKUP drives the controller itself. Then the source drive is restored to track 0 and checked, its boot sector gives the directory track, its allocation table goes to 4900H; the destination drive is checked; when its boot sector can be read, its allocation table must carry the same pack ID (bytes CEH-D7H: the master password hash and the diskette name) as the source, else the backup is refused; when it cannot be read, the destination is formatted (5386H).

5386H - Format the Destination: the Lockout Table

Reached when the destination's boot sector cannot be read. Fills 4A00H-4A22H, one byte per track, with FCH (both granules usable) and 4A23H-4ACAH with FFH; the format's verify (54EDH) puts FFH for each track that fails. Then checks the drive's index pulses (539CH), formats the 35 tracks (53F7H) and verifies them (54EDH).

539CH - Format: Check the Index Pulses

The failed read left the controller with FORCE INTERRUPT (4578H), so bit 1 of its status is the index pulse. BACKUP waits for the pulse to end (NO DISKETTE IN DESTINATION DRIVE! when it does not), waits for the next one to start (DOOR NOT CLOSED ON DESTINATION DRIVE! when none comes), then counts the loop turns of one whole pulse and gap in Register Pair DE. Fewer than 1535H turns means the pulses come too often: DESTINATION DISKETTE UNUSABLE! HARD-SECTORED!.

53F7H - Format: Build and Write Each Track

For each track 0-34, shows FORMATTING TRACK tt, builds the track's image at 6300H (gaps, ten ID fields with the sectors in the order of the table at 6293H, ten data fields of 256 E5H bytes with the data mark FAH on the directory track and FBH elsewhere), writes it with WRITE TRACK (54A3H), and steps the head in.

54A3H - Format: Write One Track

Calls 54A7H, and calls it a second time when it returns the NZ FLAG; 54A7H can only return with the Z FLAG (it halts on the errors it finds), so the second call never runs. 54A7H selects the destination (on one drive, asking for its diskette), sends WRITE TRACK and feeds the image at 6300H to the data register until the controller is done. 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.

54EDH - Format: Verify the Tracks

Reads every sector of every track not yet locked out, showing VERIFYING TRACK tt, SECTOR ss. RECORD NOT FOUND or a CRC error shows its message and locks the track out (43F5H puts FFH in its byte at 4A00H) and goes on with the next track; lost data halts. The finished table is copied to 4A60H, the lockout table's place in an allocation table.

5553H - Check the Destination's Flaws and Size the Buffer

For each track, the granules the source uses (allocation byte at 4900H, without the granules its own lockout table at 4960H marks) must not fall on a locked out track of the destination (4A60H): BACKUP REJECTED DUE TO FLAWS ON DESTINATION DISK! otherwise. On two drives the copy starts at once. On one drive BACKUP finds the top of memory in 4K steps from FFFFH down and works out how many whole tracks (ten 256-byte pages each) fit from 4D00H up to the start of the top 256-byte page found; that number goes to 4713H.

4200H - The Copy (Runs at 4200H, Loaded at 559BH)

The rows from here to 4714H show the bytes the file loads at 559BH-5AAFH, at the addresses they run at after 52CAH has copied them to 4200H: file address = address shown plus 139BH. The copy first marks the destination's boot sector by writing 76H (HALT) as its first byte, so a destination left half copied does not start; the real first byte is written back at the end (438CH). Then, pass by pass, tracks that hold data are read from the source into memory from 4D00H (one track per pass on two drives, as many as fit on one drive), written to the destination and read back.

42A9H - The Copy: Write and Verify the Tracks Loaded

Puts back the track register value saved at 4237H, then for each track of the pass that holds data: selects the destination (on one drive asking for its diskette and checking the 76H mark), writes the ten sectors from the buffer with the data mark saved at 4800H plus the track, and reads them back into the same buffer to check that they can be read. The data read back is not compared with what was written.

434FH - The Copy: Finish

Puts the backup date into the source's allocation table (bytes D8H-DFH of the copy at 4900H) and writes that table to the destination's directory track, sector 0, with the FAH data mark; reads it back; reads the destination's boot sector and writes it again with its real first byte (saved at 42D4H) in place of the 76H mark. The destination's allocation table is therefore the source's with the new date: the lockout table it carries is the source's, not the one the format made. Then RESTORE and BACKUP COMPLETE.

43A3H - Show a Message and Halt

Every end of BACKUP comes here, 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. SYS0/SYS was overwritten at 52CAH, so there is nothing to go back to.

43B3H - Write a Sector

Register A = the write command, Register Pair BC = the data, Register D = track, Register E = sector. Tries 43BEH twice. 43BEH selects the drive (4527H), 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. Register Pair BC comes back past the sector after a success.

43F5H - Format Verify: Lock a Track Out

Reached from 5522H or 552AH 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 4A00H and goes on with the next track at 553CH.

4402H - 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.

440FH - Store Bytes into the Track Image

440FH stores Register B bytes of FFH, 4411H stores Register B bytes of Register C (256 when Register B is 00H), 4417H stores one byte of Register C; each at (HL), moving Register Pair HL on.

441AH - Restore

Sends RESTORE to the controller (the selected drive's head goes to track 0) and waits until BUSY clears; there is no time limit.

442AH - Select the Source Drive

Register A = the source's select bit (the operand at 442BH stored at 5257H) with bit 7 set, the mark of the source; 44E7H asks for the source diskette on one drive when it is not the one in place, and selects the drive.

4437H - Make Sure the Source Diskette Is In

When the source is the diskette in place (bit 7 of 44E8H) it is only selected. Otherwise the source is asked for (one drive) and selected; on two drives that is all. On one drive the diskette inserted is checked: its boot sector must start with 00H (a destination started by BACKUP starts with 76H) and its allocation table must carry the source's pack ID (bytes CEH-D7H); a different diskette shows W A K E U P !!! THAT'S NOT THE SAME SOURCE DISK ! and the source is asked for again.

449CH - Select the Destination Drive

Register A = the destination's select bit (the operand at 449DH stored at 5291H) with bit 6 set, the mark of the destination; 44E7H asks for the destination diskette on one drive when it is not the one in place, and selects the drive. The status is then tested for WRITE PROTECT.

44B4H - Make Sure the Destination Diskette Is In

When the destination is the diskette in place (bit 6 of 44E8H) it is only selected. Otherwise it is asked for (one drive) and selected; on one drive the diskette inserted must have the 76H mark that 4217H wrote in its boot sector, else it is asked for again.

44E7H - Ask for a Diskette and Select the Drive

Register A = the drive's select bit with bit 7 (source) or bit 6 (destination), Register Pair HL = the prompt. When Register A equals 44E8H, the diskette wanted is in place and the drive is only selected (4527H). Otherwise Register A is stored in 44E8H; on two drives the drive is selected; on one drive the prompt is shown and BACKUP waits for ENTER, blinking the prompt: it is shown, ENTER is awaited for 4000H loop turns, the line is erased and after a pause the prompt is shown again.

4527H - Select the Drive

Writes 44E8H (the drive's select bit, with the source or destination mark in bit 7 or 6) to the drive select latch at 37E1H. When the controller's status had bit 7 (NOT READY) set before the select, waits with the ROM's 0060H and Register Pair BC = 0000H, its longest delay, for the motor to come up to speed.

453CH - Read a Sector

Register Pair BC = the buffer, Register D = track, Register E = sector. Tries 4544H twice. 4544H selects the drive, seeks the track, sends READ SECTOR and stores each byte the controller offers; it returns the Z FLAG when the status AND 5CH is 0 (an FAH data mark is accepted, an F9H or F8H mark is an error) and Register Pair BC past the sector. On an error it sends FORCE INTERRUPT and returns the NZ FLAG with Register A = the status AND 5CH.

457BH - Display a Message

Register Pair HL = the text. Shows each character through the ROM's 0033H until 03H (not shown) or 0DH (shown). Register Pair HL is returned unchanged.