TRS-80 DOS - NEWDOS/80 v2.0 for the Model III - SYS0/SYS Disassembled

SYS0/SYS

Other Navigation

NEWDOS/80 v2.0 SYS0/SYS Disassembly - The Resident DOS (Model III)

SYS0/SYS is the part of NEWDOS/80 v2.0 that stays in memory. The ROM's boot loader reads the boot sector into 4300H, the boot sector loads SYS0/SYS from the system diskette, checks that the byte at its transfer address 4D00H is A5H and jumps to 4D01H. The file holds 3,723 bytes in 23 load records between 400CH and 51EBH (with a record of type 1FH, the text ALIGNMENT FILLER, which the loader skips). The records skip the areas the ROM owns. The reset code at 4D00H-4F95H and its data up to 51EBH run once and are then overwritten, because 4D00H-51FFH is where the system overlays are loaded.

The resident part gives NEWDOS/80 its fixed entry points at 4400H-447FH and 402DH-4033H, the RST 28H overlay dispatcher, the RST 30H DEBUG entry, a keyboard driver with a clock driven repeat key, the clock routine that turns the Model III's 30 (or 25) clock interrupts a second into 40 ticks of 25 ms for the timer routines, the D-F-G, 1-2-3 and J-K-L key combinations, the sector I/O through the 1793 controller (ended by an NMI), drive selection, and all of the file input and output: read, write, position, the conversion of NEXT into a sector of the diskette through the extents in the FCB and the directory, the program loader and ROUTE. Opening, closing, the commands, the error messages and DEBUG live in the overlays and are reached through RST 28H.

Every byte of the file is shown once on this page, in address order, checked against S:\1\SYS0.SYS and its listing. The areas between the load records are shown as DEFS rows without bytes, with what is kept there.

Memory Map

RST 28H and the System Overlays

A function code in Register A names a system file by its directory slot (bits 0-4) and a function in it (bits 5-7). Slot 02H is SYS0/SYS, 03H SYS1/SYS, and so on: slot = 3 + the SYS number. Bits 0-2 of the slot are the directory sector minus 2 that holds the file's entry and bits 3-4 its entry in that sector (4B86H-4B94H). Codes below 20H are BREAK requests from the ROM's keyboard routine and go to 4478H. The dispatcher at 4B67H loads the file through the FCB at 44C0H if it is not the overlay already in memory (4288H), then calls its transfer address. It drops the return address of the RST, so CALL 4982H (an RST 28H) calls an overlay function and comes back.

Sector I/O on the Model III

The controller is reached through ports F0H-F3H and the drive through port F4H (drive bit, side, write precompensation, wait states, density; the byte is kept at 427FH). A sector number on the diskette is divided by the sectors per track into a track and a sector (4612H); the PDRIVE flags then add 1 to the track or the sector, double the track for double stepping, split a two-sided track into two sides and set the density and precompensation bits. After a Seek, the track register is loaded with the number written in the sector headers, the NMI vector at 4049H is set to JP 46B6H, the NMI is enabled for the controller's interrupt request (port E4H) and the command is issued. The 256 bytes are moved with INI or OUTI on port F3H while the wait state bit of port F4H holds the CPU until each byte is ready, and the CPU then waits at 46A9H for the NMI. 46B6H resets the stack, makes the NMI vector a RETN, reads the status, puts the physical track back and retries errors as option AM allows.

The File Control Block

Error Codes Returned by SYS0/SYS

Notes from the Code

• The DOS does not take over RST 38H: the vector at 4012H stays JP 3018H, and the DOS hooks the ROM's real-time clock vector at 4046H instead (4D27H). Its clock routine runs the ROM's clock first, then adds one third (or 0.6 with option BB) of a tick per interrupt, so that the timer routines get 40 ticks a second, sometimes two in one interrupt (manual 3.8).
• The vector at 4410H is a RET; the timer routines are enqueued through 447BH. 4411H-4412H hold HIMEM, 4478H is the BREAK hook (C3H = BREAK gives 00H, C9H = BREAK is the key 01H).
• The bytes after the RST 28H instructions in the vector table are never executed: 4403H-4404H hold the entry address of the last program loaded, 441FH is the tick counter.
• The sector routine changes its own transfer loop: INI for a read, OUTI for a write (46ABH), and the first byte of a write is followed by a delay of 150 DJNZ passes (469FH). The end of the command arrives as an NMI; afterwards the NMI vector is left as RETN.
• With option AP above the top of memory, the reset stores the top of memory minus option AP as HIMEM (4DCDH).
• The date and time answers are stored before they are range-checked (4F7BH); an invalid answer can leave some clock bytes changed until the question is answered again. After a power-on either option AY or option AZ asks for the date and time (4ECDH).
• If SYS4/SYS (the error messages) cannot be loaded, the dispatcher executes HALT (4BBDH).

Resident Variables

Self-Modifying Code

Addresses Outside SYS0/SYS

4000H - RST Vectors

The Model III ROM sends every RST instruction from 0008H to 0038H through a three-byte jump in RAM at 4000H-4014H. The ROM sets up 4000H-400BH itself; SYS0/SYS loads only the RST 28H, RST 30H and RST 38H vectors.

402DH - DOS Exits

The two fixed exits of every program (manual sections 3.2 and 3.3) and the ROM's device dispatch hook.

4052H - Zero Bytes

Loaded by SYS0/SYS as 46 bytes of 00H. Nothing in SYS0/SYS reads or writes them; SYS5/SYS (DEBUG) refers to 4052H.

41FDH - Keyboard Scan Bytes

Two bytes of the ROM's keyboard scan that SYS0/SYS loads with values of its own: the keyboard driver at 44EBH uses them to find the key that is held down.

4203H - Disk Error and BREAK Vector

The ROM's cassette routines jump to 4203H on BREAK (3362H, 3677H, 3699H).

4275H - Marker Byte

A single byte loaded by SYS0/SYS.

427EH - Drive Selection Variables

The state of the current drive. 4723H fills these at every drive change.

4288H - Overlay and System Flags

The overlay number, the system flags and the copies of the option bytes of the system data sector.

4291H - PDRIVE Table

Ten bytes for each of drives 0-3, copied at reset from the system data sector for every drive below option AL (4DE3H-4DEFH). A drive's first eight bytes are copied to 4280H-4287H when it is selected (475CH).

42BBH - Option Values and Work Bytes

Bytes filled from the system data sector at reset, and bytes used by the overlays.

42D2H - ROUTE Entries

Four bytes used by SYS14/SYS, then six seven-byte ROUTE entries. An entry holds the address of the control block that is routed (+0), its original type byte (+2), the link to the next entry (+3, 0000H = the last) and the control block the I/O goes to (+5). 4A80H walks the list from the head stored in its operand at 4A81H.

4400H - DOS Entry Vectors

The fixed entry points of chapter 3 of the manual. Most load an RST 28H function code into Register A and execute RST 28H. The dispatcher at 4B67H drops the return address of the RST, so the bytes that follow an RST 28H here are never executed and serve as data.

4480H - The DOS FCB

A 32-byte FCB used by SYS0/SYS and the overlays for their own files. As loaded it is open, its buffer is 4300H, and FCB+0 bit 1 makes NEXT a sector number of the whole diskette: NEXT = 000200H, sector 2, the system data sector, which the reset reads with one call to 4436H (4D4AH).

44C0H - The System File FCB

The FCB through which the dispatcher (4BA8H) loads the overlays and the other system files. Its buffer is 4300H, it reads drive 0, its EOF is 64 sectors so that no read of a system file stops early, and only its first extent is filled in (44CEH, by 4BA4H): a system file has to be one extent.

44D2H - Convert to Hexadecimal Text

Two entry points used by the overlays. 44D2H stores Register Pair DE as four hexadecimal characters at Register Pair HL; 44D7H stores Register A as two. Register Pair HL is left pointing after the last character.

44EBH - Keyboard Driver

Put into the keyboard's control block (4016H) at reset when SYSTEM option AJ is Y and the up-arrow key is not held (4E31H-4E3FH). It gives chain file keys first, runs the ROM's own keyboard routine (3024H), adds the clock driven repeat key of option AU, checks the key combinations (459DH) and filters the CLEAR key unless option AQ is Y. It returns the key in Register A (00H = none).

4548H - Convert Lower Case to Upper Case

Converts a lower case letter in Register A to upper case; any other value is returned unchanged.

4551H - Clock Routine

The reset puts 4551H in the real-time clock vector at 4046H (4D27H-4D30H), so the ROM's interrupt handler calls it at every clock interrupt (30 a second, or 25 with option BB). It first runs the clock routine the vector held before, keeps a copy of the clock for a later reset, then turns the interrupt into one or two 25 ms ticks: 40 ticks a second in both cases. Each tick counts 441FH, counts down the repeat delay and runs the timer routine chain (manual 3.8); then it falls into the key combination check.

459CH - Check for D-F-G, 1-2-3 and J-K-L

Entered by falling out of the clock routine (from the interrupt) and by the keyboard driver at 453DH with the key in Register D. D-F-G enters MINI-DOS (option AF), 1-2-3 enters DEBUG (option AE), J-K-L sends the screen to the printer (option AD). Each test is a plain jump past the action until the reset turns it into a conditional one. Returns with Register A = Register D.

45D4H - Enter DEBUG

The RST 30H vector (400FH) and 440DH come here; 45C8H enters at 45D5H with Register Pair AF already on the stack.

45D8H - Run a Timer Routine

Called from 4593H with Register Pair HL pointing to the fourth byte (the countdown) of a timer routine entry and Register B = its interval (the third byte).

45DBH - Read or Write a Sector

The sector level disk I/O. Register Pair DE = the sector number on the diskette (counted from 0 across all tracks and sides), Register Pair HL = the 256-byte buffer, the drive = the current drive (427EH). 45DBH reads, 45DFH reads without keeping the data (a verify), 45E7H writes with the deleted data mark F8H (the mark of a directory sector), 45EBH writes normally. The sector is converted to a track, side and sector, the head is moved with a Seek, and the 256 bytes are moved with INI or OUTI while the controller's wait states pace the CPU; the end of the command arrives as an NMI that jumps to 46B6H. Errors are retried (option AM) and returned as an error code in Register A with the NZ FLAG; the Z FLAG means success.

46ABH - Patch the Transfer Loop

Called once per read or write (4601H) with Register A = the first byte count and Register B = A2H (INI) or A3H (OUTI).

46B6H - End of a Read or Write (NMI)

The controller's interrupt request at the end of the command causes an NMI; the ROM's handler (3039H) jumps through the vector at 4049H to here. The stack is reset to the level saved at 4672H, the NMI vector is turned into RETN, and the status is checked: errors other than a deleted data mark or write protection are retried.

46F2H - Restore or Seek and Wait

46F2H restores the head to track 0 when Register B (the tries left) is odd. 46F7H issues the Type I command in Register C (08H Restore, 18H Seek) with the drive's stepping rate and waits until the controller is not busy; if the drive is not ready the command is ended with a Force Interrupt. Register A returns the status.

4711H - Keep the Drives Rotating

4416H comes here (manual 3.10). If the drive is turning (the status' not-ready bit is clear), the current drive is selected again, which restarts the drives' motor timer. 4715H only writes the select byte to port F4H.

471BH - Select a Drive

Enter at 471BH for the drive of the FCB at Index Register IX, at 4720H for the current drive, or at 4723H (445BH) with the drive in Register A. A drive number not below option AL gives the NZ FLAG with Register A = 20H. Otherwise the old drive's track register is saved, the new drive becomes current, its PDRIVE bytes are copied to 4280H-4287H, the controller's sector and track registers are loaded for it and the drive is selected; motor start and head settle delays are added when needed. Returns the Z FLAG with Register A = 00H. Registers BC, DE and HL are preserved.

4789H - Short Delay and Read the Status

Waits a few microseconds (the controller needs time after a command before its status is valid), then reads the status into Register A.

4791H - Test for a Mounted Diskette

445EH comes here (manual 3.30). Selects the drive in Register A, then waits for the index bit of the status to change, which proves that a diskette is in the drive and turning. Returns the Z FLAG with Register A = 00H, or the NZ FLAG with Register A = 08H (DEVICE NOT AVAILABLE) or 20H (no such drive).

47AEH - Allocate, and Find the Sector for NEXT

444BH comes here (manual 3.26). The part from 47B5H is used by every read and write: it turns the FCB's NEXT position into a sector number on the diskette. It looks through the extents kept in the FCB, then through the file's directory entries (FPDE and FXDEs), and when the sector lies past the file's last granule it calls SYS2/SYS to allocate more (a read gets error 3EH instead). On exit Register Pair DE = the sector number, Register Pair HL = the FCB's buffer, Register A = 00H and the Z FLAG is set; errors leave through 4972H.

488EH - Subtract an Extent's Granule Count

Entered with Register A = the extent's second byte, Register Pair DE = the granules to go and Register Pair HL = the extent pointer. Returns Register Pair BC = the extent's granule count, Register Pair HL = the granules to go minus that count, Register Pair DE = the extent pointer, and the CARRY FLAG set if the granule lies in this extent.

4898H - Read a Directory Sector

Enter at 48AFH to read directory sector A (0 = GAT, 1 = HIT, 2 and up = FDE sectors) of the current drive into 4300H, or at 48A2H for one attempt. Directory sectors carry the directory mark, so a good read returns controller error 06H; a sector without it gives error 31H (WRONG DISKETTE RECORD TYPE). If the read fails, the boot sector is read to find where the directory is (byte 2, the directory's lump), the drive's PDRIVE record is updated and the read is tried again. On exit the Z FLAG is set, or the NZ FLAG with error 11H (DIRECTORY READ ERROR). Register Pairs DE and BC are preserved.

48C4H - Write a Directory Sector

Enter at 48C4H to write back the directory sector now in 4300H, or at 48C7H with its number in Register A. The sector is written with the directory mark and the verify read. On exit the Z FLAG is set, or the NZ FLAG with error 12H (DIRECTORY WRITE ERROR).

48D4H - Read the Directory Sector of an Entry

Register A holds a DEC (bits 0-4 the FDE sector minus 2, bits 5-7 the entry in the sector). 48D4H reads the sector only if it is not already in 4300H, 48DBH always reads it, 48D8H always reads the sector of the FCB's DEC (FCB+7). On exit Register Pair HL points to the entry, Register A = its offset in the sector, and the Z FLAG is set.

48F0H - Read the FPDE of an Open FCB

Selects the FCB's drive and reads the directory entry of FCB+7. The entry must still belong to the file: it must be an FPDE in use, and its first extent must match the FCB's (unless the FCB has none yet). On exit Register Pair HL points to the entry and the Z FLAG is set, or the NZ FLAG with Register A = the error (2DH BAD FCB DATA).

490DH - Compare NEXT with EOF

Loads Register C with NEXT's low byte and Register Pair HL with NEXT's middle and high bytes, and compares NEXT with EOF, highest byte first. The CARRY FLAG is set if NEXT is below EOF and the Z FLAG if they are equal.

4925H - Run the Rest of a Routine as a DOS Function

Every FCB routine starts with CALL 4925H, Register Pair DE pointing to the FCB. If the FCB is not open, the routine returns at once with error 26H (FILE NOT OPEN). Otherwise the code after the CALL runs as a subroutine with Index Register IX = the FCB and Index Register IY = 4280H, and the Stack Pointer is saved at 4973H so that any error can leave through 4972H from any depth. On return Register A and the flags hold the result, Register Pairs BC, DE, HL, AF', IX and IY are as they were on entry, and the return goes to the caller of the routine.

495CH - Check the Access Level

The access level (FCB+1 bits 0-2) must be below Register B: 5 for a write (entry 495CH), 6 for a read (entry 495EH with Register B = 6). Otherwise the DOS function ends with error 25H (ILLEGAL ACCESS TRIED TO PROTECTED FILE). 4969H checks NEXT against EOF.

4972H - Leave a DOS Function with an Error

Register A holds the error code. The Stack Pointer saved by 4925H is restored, which throws away everything the function pushed, and the function returns to its caller with the NZ FLAG set. SYS2/SYS and SYS3/SYS jump here too. 4978H-4982H serve the overlays that call another overlay and come back.

4983H - Move a Logical Record

Called at the start of the READ (with the CARRY FLAG set) and WRITE (CARRY FLAG clear) routines. In sector mode (FCB+1 bit 7 clear) it returns at once. In record mode it replaces the rest of the routine: LRL bytes (0 = 256) are moved one by one between the caller's buffer at Register Pair HL and the file, through the byte routine at 4A92H, and the DOS function returns from here.

49A1H - READ

4436H comes here (manual 3.19). In sector mode the sector at NEXT is read into the FCB's buffer and NEXT is advanced by 256, also after error 06H (the sector has the directory mark), which is still returned.

49D7H - WRITE

443CH (write with verify, manual 3.21) enters at 49D7H and 4439H (WRITE, manual 3.20) at 49DBH. In sector mode the FCB's buffer is written to the sector at NEXT, NEXT is advanced by 256 when its low byte is 0, and EOF is set to NEXT if NEXT is past EOF or if FCB+1 bit 6 is clear.

4A3DH - Write a Byte to a File

The write half of the byte routine at 4A92H, entered with the byte in Register C and the Z FLAG set if the FCB's buffer holds the sector at NEXT. The sector is read in first unless NEXT is at EOF on a sector boundary. The byte is stored at NEXT and NEXT is advanced; when the buffer is full it is written, and EOF is brought up to NEXT.

4A5DH - Write a Sector, Verify and Retry

Register Pair DE = the sector number, Register Pair HL = the buffer. Register A not zero asks for a verify read after the write, and the NZ FLAG asks for the directory mark. When the verify read fails, the write is repeated up to SYSTEM option AW times. On exit the Z FLAG is set or Register A holds the error.

4A80H - Device I/O Through ROUTE or an FCB

Reached through 4033H when the ROM's dispatcher finds that the type byte of the control block at Register Pair DE does not match the request in Register B (01H input, 02H output). A type byte of C0H marks a device that ROUTE has redirected: the ROUTE list is searched for it. Anything else is taken to be an FCB, and one byte is read from or written to the file (manual 3.38 and 3.39); this is how 0013H and 001BH work with disk files.

4ABCH - Search the ROUTE List

Register Pair HL points to a ROUTE entry, Register Pair DE to the control block the I/O was aimed at, Register B holds the request and Register C the output character. Every entry for this control block gets the request: each is passed to the target device's driver through the ROM at 068BH (part of the ROM's driver entry 0674H: it compares Register A with 02H and jumps to the driver whose address is at IX+1). An output goes to every target; an input returns the first character received.

4AECH - Position an FCB

The positioning vectors of the manual (sections 3.22-3.27) come here. Each works out a new NEXT in Registers H (high), L (middle) and C (low). If the new NEXT is in another sector, the buffer is written first if it has changes waiting and is marked empty. Except for 443FH and 4448H, FCB+1 bit 6 is set, so that later writes do not pull EOF back.

4B4BH - Display or Print a Message

4467H (display, manual 3.33) enters at 4B4BH and 446AH (print, manual 3.34) at 4B61H. The message at Register Pair HL is sent through the ROM's output routine at 001BH up to and including a 0DH, or up to but not including a 03H. Register Pairs HL and DE are preserved.

4B67H - RST 28H Dispatcher

RST 28H comes here through 400CH with a function code in Register A. Codes below 20H (function 0) are sent to the BREAK hook at 4478H. Any other code names a system file by its directory slot (bits 0-4) and a function in it (bits 5-7). If that file is not the overlay now in 4D00H-51FFH, its directory entry is read from drive 0, and it is loaded through the FCB at 44C0H; a system file that cannot be found gives error 2EH (SYSTEM PROGRAM NOT FOUND), or a HALT if the missing file is SYS4/SYS, the error message module. The overlay is then called at its transfer address with Register Pairs AF, BC, DE and HL as they were at the RST. The return address the RST pushed is thrown away, so the overlay returns to whoever called the routine that executed the RST.

4BCDH - Load a Program File

Loads the load module file of the open FCB at Register Pair HL into memory and returns its transfer address in Register Pair HL with the Z FLAG set. The file is read a sector at a time into 4300H, so the FCB's buffer must be 4300H. Record type 01H is a load block (length, two address bytes, data), 02H is the transfer address (it ends the load), and any other type up to 1FH is skipped. Errors: 22H (LOAD FILE FORMAT ERROR) for a type above 1FH, 24H (TRIED TO LOAD READ ONLY MEMORY) if a loaded byte does not read back, or the read error. Also called by SYS2/SYS.

4C19H - Sector Number of a Directory Sector

Register A holds a directory sector (0 = GAT). It is stored at 48D5H as the sector now in 4300H, and Register Pair DE is loaded with its sector number on the current drive's diskette: (the directory's lump x granules per lump) x 5 + Register A. Register Pair HL is set to 4300H. 4C21H is the general entry, used by 47F5H: Register Pair HL points to a lump byte, Register E holds a granule in the lump and Register A a sector in the granule.

4C37H - Multiply and Divide

4C37H: Register Pair HL = Register L x Register A. 4C39H: Register Pair HL x Register A, with the result in Register A (high byte), Register H and Register L. 4C42H: Register Pair HL x Register A with the result in Register H (high), Register L and Register C (low), used for record x LRL. 4C57H divides Register Pair HL by 5 and 4C59H by Register A: the quotient in Register Pair HL, the remainder in Register A. Used by several overlays.

4C6AH - Compare a Keyword and Step Over Separators

4C6AH compares the 00H-terminated string at Register Pair BC with the text at Register Pair HL: on a match it returns the Z FLAG with Register Pair HL after the text, otherwise the NZ FLAG, Register A = 34H and Register Pair HL unchanged. 4C7AH returns the Z FLAG if Register Pair HL points to 0DH (the end of the command line). 4C7EH steps over a comma or over spaces and returns the NZ and NO CARRY flags; for any other character it returns the CARRY FLAG with Register Pair HL unchanged. Register A is 34H (ILLEGAL KEYWORD OR SEPARATOR OR TERMINATOR) whenever the Z FLAG is not set.

4C92H - Delay

Waits Register B x 256 passes of the ROM's delay loop at 0060H (plus the passes in Register C), repeated SYSTEM option BJ times. Used for the motor start and head settle delays, and by SYS5/SYS and SYS6/SYS.

4CA4H - Half the Track Count

Called by the sector routine at 4634H to find the first track that is written with precompensation.

4CAAH - Zero Bytes

86 bytes of 00H at the end of the resident DOS.

4D00H - Reset: Memory Size and Clock

The ROM's boot loader reads the boot sector (BOOT/SYS) into 4300H, and the boot sector loads SYS0/SYS and checks that the byte at its transfer address 4D00H is A5H before jumping to 4D01H. The reset code runs once from here and is overwritten afterwards: 4D00H-51FFH is the overlay area. This part finds the top of memory, restores the clock after a reset while the DOS was active, and hooks the clock interrupt.

4D33H - Reset: Read the System Data Sector

The boot sector is still in 4300H. Its bytes FDH-FFH describe the system diskette in drive 0, and they are put into drive 0's PDRIVE entry so that the DOS can read that diskette. Then the system data sector (sector 2 of drive 0) is read, its mark A5H checked, and the option values are stored where the DOS uses them. A bad value gives error 27H.

4E02H - Reset: Apply the Yes/No Options

Changes the resident code according to the options in bytes F8H, F9H and F0H of the system data sector: Register C holds byte F8H, Register B byte F9H, Register E byte F0H.

4E83H - Reset: Screen, Banner, Date and Time

Clears the screen, routes the display to NL if option BA is Y, adjusts the clock routine for option BB, shows the banner and, depending on options AY and AZ, asks for the date and time. Then the date and time are displayed, the GAT of drive 0 is read and its AUTO command is run unless ENTER is held (option BD).

4F2BH - Ask for the Date and Time

Each question is repeated until the answer is valid. The answer is typed into the command buffer at 4225H through the ROM's line input at 0040H and checked by 4F5DH against the limits at 508CH or 5092H. The values go straight into the ROM's clock bytes.

4F5DH - Check and Store a Date or Time

Register Pair HL points to the typed answer, Register Pair DE to the first of three clock bytes (stored downward), Register Pair BC to three pairs of limits (the lowest value, then the number of values allowed) and Register A to the separator. Each value must be two digits within its limits, the values must be separated by the separator, and the answer must end there. Returns the Z FLAG if it was valid.

4F96H - Reset Messages (Data)

The messages displayed by the reset code. The banner draws NEWDOS/80 in large letters, three text lines high, with the block graphics characters 80H-BFH (bits 0-5 are the six dots of a character cell, 80H is an empty cell); the text Apparat, Inc., Version 2.0 and Model III follows on the three lines.

504BH - Reset Data

The copy of the system data sector's bytes F8H-FFH, the date and time questions, the date and time line, and the limits used to check the answers.

5098H - Rest of the File (Data)

The file continues to 51EBH with bytes of 00H that nothing refers to. The overlays load over them.