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

SYS0/SYS

Other Navigation

NEWDOS/80 v2.0 SYS0/SYS Disassembly - the Resident DOS (Model I)

SYS0/SYS is the resident part of NEWDOS/80: it stays in memory from 4000H to 4CFFH while the DOS runs. It holds the DOS entry vectors, the sector level disk I/O, the drive selection, the FCB routines for reading, writing and positioning files, the directory sector routines, the RST 28H dispatcher that loads and calls the overlays SYS1-SYS21, the program loader, the interrupt handler with the clock and the timer routine chain, a keyboard and a display driver, and the ROUTE hook. Its file also carries the reset code (4D00H-4FA7H), which runs once and is then overwritten by the overlays.

The file has eight load blocks: 400CH-4014H, 402DH-4035H, 403EH-405CH, 4063H-407FH, 4308H-4317H, 4368H-43A8H, 43B2H-43DFH and 4400H-51DAH (3,752 bytes), with 4D00H as the transfer address. BOOT/SYS loads it at every reset and jumps to 4D01H after checking that 4D00H holds A5H. The file on the system diskette has the mandatory zaps applied (see Zaps). The page shows every loaded byte once, in address order; the areas between the load blocks are shown as DEFS rows without a byte column.

Memory Map

RST 28H Codes and the Overlays

SYSTEM Options

PDRIVE Records

FCB Layout

Error Codes Returned by SYS0

Zaps

The documented entry points are the vectors at 4400H. The overlays and several utilities also call these routines directly:

4000H - RST Vectors

The Model I ROM sends every RST instruction from 0008H to 0038H through a jump in RAM. The ROM sets up 4000H-400BH itself (RST 08H to RST 20H, used by BASIC). SYS0's file starts at 400CH and replaces the three vectors that belong to the DOS: RST 28H, RST 30H and RST 38H.

402DH - DOS Exits

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

403EH - Clock, Date and Memory Size

Variables of the resident DOS. The time and date are binary values.

4053H - Disk Interrupt Check

Added by zap 060. The interrupt handler calls it with bit 7 of Register A holding the disk controller's interrupt bit. The controller's status is read only when that bit is set, which clears the disk interrupt.

4063H - Convert DE or A to Hexadecimal Text

Two entry points used by DEBUG, SYSTEM and other overlays. 4063H stores Register Pair DE as four hexadecimal digits at HL, 4068H stores Register A as two. HL is left pointing after the digits.

407CH - Clock Limits

The highest value of each clock byte, used by the once-a-second clock routine at 44CDH.

4308H - Drive Selection and Overlay Variables

The state of the current drive, the BREAK key hook and the number of the overlay in 4D00H-51FFH.

4368H - System Flags, Options and the PDRIVE Table

Most of these bytes are filled in at reset from the system data sector (sector 2 of the system diskette) by the code at 4D4CH.

43B2H - ROUTE Entries and the System File FCB

Four seven-byte ROUTE entries, then the FCB used to load system files. A ROUTE entry holds the address of the device control block it serves (+0), a copy of that block's original type byte (+2), the address of the next entry for the same device (+3, 0000H at the end) and the address of the device control block the I/O is sent to (+5). The list is searched by 4B17H; the entries are managed by the ROUTE command (SYS14).

4400H - DOS Entry Vectors

The fixed entry points documented in chapter 3 of the manual. Most of them load an RST 28H code into Register A and execute RST 28H: the dispatcher at 4BC2H throws away the RST's own return address, loads the overlay if needed and calls it, so the overlay returns straight to the program that called the vector. The code's bits 0-2 are the directory sector minus 2, bits 3-4 the file in that sector, and bits 5-7 the function number.

4480H - The DOS FCB

A 32-byte FCB that overlays use for their own files (SYS1 puts filespecs here). As loaded it is already open and addresses sector 2 of the diskette in drive 0 with buffer 4200H, so that the reset code can read the system data sector with one call of 4436H (4D3BH). See FCB Layout.

44A7H - Convert the Time or Date to Text

446DH and 4470H come here. Three binary bytes, read downward from DE, are stored at HL as two decimal digits each, separated by Register B. On exit HL points after the last digit.

44C9H - Once-a-Second Clock Routine

The first entry of the timer routine chain, whose head is the operand of the instruction at 461CH. It runs once a second.

44EBH - Cursor Routine

The second entry of the timer routine chain, run every half second. It shows the cursor character, and when blinking is on (SYSTEM option BH, or the BLINK command) it alternates the cursor and the character under it.

4505H - Display Driver

Put into the display's control block (401EH) at reset when SYSTEM option AJ is Y (4E31H). The ROM's dispatcher at 03C2H enters a driver with IX pointing to the control block, Register C holding the character, and the flags of CP 02H on the request type: the CARRY FLAG set for input (reading the character at the cursor), clear for output. As loaded, everything goes to the ROM's driver. With the lower case driver on (SYSTEM option BF, or the LCDVR command in SYS3), 4505H becomes JR C,4513H and characters 20H-7FH are put on the screen by the ROM's store routine, so lower case letters are not changed to upper case.

4516H - Keyboard Driver

Put into the keyboard's control block (4016H) at reset when SYSTEM option AJ is Y, unless the up-arrow key is held (4E31H). It scans the keyboard like the ROM's driver but adds the repeat key (options AU and AV), the debounce (option AC), a CLEAR key filter (option AQ), the key combinations D-F-G, 1-2-3 and J-K-L (45BFH) and, with the lower case driver on, the letter case handling at 4594H. It returns the key in Register A, or 00H for none.

4594H - Letter Case Handling

Reached from 4593H only while the lower case driver is on, with the character in Registers A and C. Letters have their case flipped, so that an unshifted letter gives lower case, and SHIFT-0 switches upper case only mode on and off. When the upper case only mode is on (45B4H holds a NOP), letters are converted to upper case instead.

45B5H - Convert Lower Case to Upper Case

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

45BEH - Check for D-F-G, 1-2-3 and J-K-L

Called by the timer interrupt (4600H) and by the keyboard driver (4589H). D-F-G enters MINI-DOS, 1-2-3 enters DEBUG, J-K-L prints the screen. Each combination is off until the reset code turns it on from SYSTEM options AF, AE and AD, by changing an unconditional JR into JR NZ. On return, Register A holds Register D (the keyboard driver's character).

45F2H - Interrupt Handler

The RST 38H vector at 4012H jumps here on every interrupt. The interrupt latch at 37E0H tells which: bit 7 the 25 ms clock, bit 6 the disk controller.

4609H - Enter DEBUG

Reached through RST 30H (400FH) and through 440DH.

4610H - Timer Tick

Called for every clock interrupt, every 25 ms. Counts the ticks, counts down the repeat key delay and walks the chain of timer routines. The chain is the one the manual describes in section 3.8: each routine starts with a two-byte chain pointer, its interval and its countdown, and its code follows at byte 4.

4630H - Read or Write a Sector

The sector level disk I/O. DE = the sector number on the diskette (counted from 0 across all tracks), HL = the 256-byte buffer, the drive is the current drive (4308H). On exit the Z FLAG is set if all went well; otherwise Register A holds the DOS error code. BC is preserved. Entry points: 4630H read, 4634H verify read, 463CH write with the directory mark, 4640H write.

4747H - Issue a Seek Type Command and Wait

Register C holds a Restore (08H), Seek (18H) or Step In (58H) command. The current drive's stepping rate is added, the command is issued, and the routine waits until the controller is no longer busy, reselecting the drive meanwhile so that its motor keeps running. Used by SYS6 as well.

4762H - Keep the Drives Rotating

4416H comes here (manual 3.10). If the drives are rotating, the current drive is reselected. 4767H writes the select latch.

476EH - Select a Drive

Enter at 476EH for the drive of the FCB at IX, at 4773H for the current drive, or at 4776H with the drive in Register A (445BH, manual 3.29). The drive becomes the current drive: its PDRIVE record is copied to 430AH-4311H, the controller's track and sector registers are set for it, and its motor is started. A motor that was stopped gets a half second to come up to speed. On exit the Z FLAG is set, or the NZ FLAG with error code 20H (ILLEGAL OR MISSING DRIVE #). HL, DE and BC are preserved.

47E3H - 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. 47E8H only reads it.

47ECH - Test for a Mounted Diskette

445EH comes here (manual 3.30). Selects the drive in Register A, then waits for the index pulse bit to change, which shows that a diskette is in the drive and turning. On exit the Z FLAG is set, or the NZ FLAG with error code 08H (DEVICE NOT AVAILABLE) or 20H.

4809H - Allocate, and Find the Sector for NEXT

444BH comes here (manual 3.26). The part from 4810H 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 to allocate more (a read gets error 3EH instead). On exit DE = the sector number, HL = the FCB's buffer and the Z FLAG is set; errors leave through 49CDH.

48F3H - Read a Directory Sector

Enter at 490AH to read directory sector A (0 = GAT, 1 = HIT, 2 and up = FDE sectors) of the current drive into 4200H, or at 48FDH 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). DE and BC are preserved.

491FH - Write a Directory Sector

Enter at 491FH to write back the directory sector now in 4200H, or at 4922H 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).

492FH - 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). 492FH reads the sector only if it is not already in 4200H, 4936H always reads it, 4933H always reads the sector of the FCB's DEC (FCB+7). On exit HL points to the entry in 4200H and the Z FLAG is set.

494BH - 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 HL points to the entry and the Z FLAG is set, or the NZ FLAG with Register A = the error (2DH BAD FCB DATA).

4968H - Compare NEXT with EOF

Loads Register C with NEXT's low byte and 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.

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

Every FCB routine starts with CALL 4980H, 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 IX = the FCB and IY = 4380H, and the stack pointer is saved at 49CEH so that any error can leave through 49CDH from any depth. On return all registers except AF are as they were on entry (the caller's AF ends up in AF').

49B7H - Check the Access Level

The access level (FCB+1 bits 0-2) must be below Register B: 5 for a write (entry 49B7H), 6 for a read (entry 49B9H with B = 6). Otherwise the DOS function ends with error 25H (ILLEGAL ACCESS TRIED TO PROTECTED FILE).

49CDH - Leave a DOS Function with an Error

Register A holds the error code. The stack pointer saved by 4980H is restored, which throws away everything the function pushed, and the function returns to its caller with the NZ FLAG set. SYS2 and SYS3 jump here too.

49DEH - 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 HL and the file, through the byte routine at 4AEDH, and the DOS function returns from here.

49FCH - 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.

4A32H - WRITE

443CH (write with verify, manual 3.21) enters at 4A32H and 4439H (WRITE, manual 3.20) at 4A36H. 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.

4A98H - Write a Byte to a File

The write half of the byte routine at 4AEDH, 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 with verify, and EOF is brought up to NEXT.

4AB8H - Write a Sector, Verify and Retry

DE = the sector number, HL = the buffer. Register A non-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.

4ADBH - 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 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.

4B17H - Search the ROUTE List

HL points to a ROUTE entry, 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 03D4H (which does CP 02H and jumps to the driver named at IX+1). An output goes to every target; an input returns the first character received. This version is from zap 020.

4B47H - 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.

4BA6H - Display or Print a Message

4467H (display, manual 3.33) enters at 4BA6H and 446AH (print, manual 3.34) at 4BBCH. The message at 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. HL and DE are preserved.

4BC2H - 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 4312H. 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 43CEH; a system file that cannot be found gives error 2EH (SYSTEM PROGRAM NOT FOUND), or a HALT if the missing file is SYS4, the error message module. The overlay is then called at its transfer address (4D00H for all of them) with 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.

4C28H - Load a Program File

Loads the load module file of the open FCB at HL into memory and returns its transfer address in HL with the Z FLAG set. The file is read a sector at a time into 4200H. 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.

4C74H - Sector Number of a Directory Sector

Register A holds a directory sector (0 = GAT). It is stored at 4930H as the sector now in 4200H, and 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. HL is set to 4200H. 4C7CH is the general entry, used by 4850H: Register L holds a lump, Register E a granule in the lump and Register A a sector in the granule.

4C92H - Multiply and Divide

4C92H: HL = L x A. 4C94H: HL x A, with the result in A (high byte), H and L. 4C9DH: HL x A with the result in H (high), L and C (low), used for record x LRL. 4CB2H divides HL by 5 and 4CB4H by Register A: the quotient in HL, the remainder in Register A. Used by several overlays.

4CC5H - Compare a Keyword and Step Over Separators

4CC5H compares the 00H-terminated string at BC with the text at HL: on a match it returns the Z FLAG with HL after the text, otherwise the NZ FLAG, Register A = 34H and HL unchanged. 4CD5H returns the Z FLAG if HL points to 0DH (the end of the command line). 4CD9H 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 HL unchanged. Register A is 34H (ILLEGAL KEYWORD OR SEPARATOR OR TERMINATOR) whenever the Z FLAG is not set.

4CEDH - Delay

Waits about B x 256 passes of the ROM's delay loop at 0060H (14.66 microseconds each on a standard Model I), repeated SYSTEM option BJ times. Used for the motor start and head settle delays, and by SYS5 and SYS6.