TRS-80 DOS - TRSDOS v2.3 - Disassembled

TRSDOS was the DOS which Tandy supplied when a Model I user bought a Drive 0 kit. While there are a few different DOS's available for the Model I, TRSDOS was the first and, as a result, the most simplistic. It required a minimum of 32K of RAM and at least one disk drive, although four disk drives were supported.

TRSDOS v2.3 is broken into two types of programs: The nucleus and overlays/user programs.

• The nucleus, SYS0/SYS, stays in memory. Its jump vectors and variables are loaded at 400CH-405CH and 4300H-44AFH and its code at 4398H-4CFFH; it keeps sector buffers at 4200H-42FFH and 4D00H-4DFFH. It contains the DOS entry points, the overlay loader, the file read, write and positioning routines, the disk driver, the TRACE and time displays, the interrupt handler with its timer tasks and the clock. Its start-up code at 4E00H-4F28H runs once and is then overwritten by the overlays. See the SYS0/SYS disassembly.
• The remainder of TRSDOS v2.3 is overlay modules and user programs which are loaded on demand. To make the most of the little RAM available, only the nucleus stays in memory. In general, overlays load from 4E00H-5200H and utility programs load from 5200H.

TRSDOS v2.3 services the clock interrupt from the moment it starts: the clock task in timer slot 7 keeps the time and date at 4041H-4046H. The library functions TRACE and CLOCK add display tasks to the same list (slots 11 and 6).

TRSDOS is a single-user, disk-resident operating system. It is composed of a core-resident nucleus and disk-resident system overlays and utilities. The minimum configuration required for TRSDOS is 32K bytes of memory, and one disk drive which must be addressable as drive zero. In order to properly run, TRSDOS requires a system diskette to be mounted in drive zero at all times. TRSDOS supports any memory size from 32K to 48K bytes of memory and up to four, 35-track, single-sided, single-density, 5-1/4 floppy disk drives.

TRSDOS is loaded by a bootstrap program which is read from disk by LEVEL II. The portion of TRSDOS initially loaded is called the nucleus.

The nucleus is loaded in pieces between 400CH and 4CFFH: jump vectors, variables and the DOS entry point table at 400CH-405CH and 4300H-44AFH, code from 4398H to 4CFFH. Its system initialization code is loaded at 4E00H-4F28H and runs immediately after the system has been loaded.

The bulk of TRSDOS resides on the system disk. The disk resident portion consists of overlay modules and system utility programs.

Overlay modules are loaded on a demand basis by the nucleus. They contain code for system functions which need not be permanently core-resident. Exam pl es of these functions are: the command line processor; OPEN and CLOSE routines plus select system commands, such as DEBUG, TRACE and BASIC 2.

The overlay area begins at the end of the nucleus (4E00) and ends at the start of the utility load area (5200). Only one overlay is loaded at a time. Overlays could be constructed which call secondary overlays; however, this is not a standard practice in TRSDOS.

System utility programs such as BACKUP and FORMAT are loaded at address 5200. SYS6, which is technically an overlay module, is also loaded at 5200. It contains code for the DOS commands AUTO, KILL, DATE and TIME, to name a few. Utility programs may make nucleus calls which result in an overlay being loaded; thus, they must reside in separate areas of memory.

The system utility programs and overlays exist as files on the system diskette. Since they are assigned the invisible attributes, "SEE TRSDOS MANUAL," they are not displayed when the DIR command is used unless the 'I' (invisible) parameter is specified.

Overlay files have a SYS suffix, while utility program files have a CMD suffix. The exception is SYS6/SYS, which is loaded into the utility area.

SYS6 is also the only module in the system with multiple entry points. The editor/assembler and loader used by TRSDOS do not support relocatable code, multiple entry points or symbolic external references. SYS6 does not have multiple entry points in the traditional sense of the word, but it achieves the same effect by being called with a command index value, which specifies which of its nineteen commands is to be executed.

A command index is passed to SYS6 in the C register by the program that requested it to be loaded. In the usual case, the command line interpreter (SYS1/SYS) is the caller.

Utility programs fetch their parameters from the command line used to call the utility. Upon entry, the HL register points to the first character after the command specification in the command line buffer.

TRSDOS is not an interrupt driven system; however, it does support interrupts. A clock interrupt is generated every 25 milliseconds on systems with an expansion interface. This interrupt, plus any spurious interrupts, are fielded by a general purpose service routine in TRSDOS.

Upon detection of a clock interrupt, the clock interrupt processor is entered. This processor executes sub-tasks indicated by an interrupt task list of twelve entries. At start-up only the clock task is in it (slot 7). The CLOCK and TRACE commands use two more entries (slots 6 and 11).

The remainder of the entries in the list are unused. Subroutines in the nucleus are defined, which will add or delete entries to this list. This means some sort of scheduling or multi-tasking function could easily be added as an application program.

The nucleus contains other useful subroutines which can be called from users programs. The complete list of nucleus entry points is in the SYS0/SYS disassembly.

The major features of TRSDOS are its file management system, the disk space manager, the file loader, the overlay loader, interrupt service routines and the various command processors. Each of those features is discussed in detail in subsequent sections. The following descriptions of some of these features is very general and is intended to acquaint the reader with the external characteristics of these features.

Disk services in TRSDOS support the file management system. They create and delete directory entries, allocate disk space, translate relative record numbers into absolute track and sector addresses, rewind files, position files to specified records, test for end of file conditions, and call the disk driver to perform data transfers. The disk management system does not support: file overflow from one device to another, any sector size other than 256 (dee.) bytes, or the ability to bypass irrecoverable errors.

Embedded in the disk services is an elementary record manager. It provides record movement between the user and system data areas, as well as packing and unpacking services. Two record types are supported. They are: fixed-length physical records (always one sector), and logical records. Logical records can vary in size from 1to255 bytes in length. All logical records in a file must be the same length except for DISK BASIC files. DISK BASIC supports variable length logical records because it has its own record management routines.

Disk space is allocated on an as-needed basis in units called granules where 1 granule equals 5 consecutive sectors. A permanent record of the assigned and available granules is maintained in a special sector of the disk directory. Each file entry in the directory has a list of assigned granules. When a file is purged (KILL'ed in TRSDOS nomenclature), the granules assigned to the file are returned to the list of available granules.

The HIT lets SYS2/SYS find a file without reading every directory sector. Every directory entry has a locator, a byte whose bits 5-7 give the entry's place in its sector and bits 0-4 the sector minus 2. The HIT byte at the offset of that locator is 00H when the entry is free, and otherwise the one-byte hash of the file name in it.

• Opening a file: SYS2/SYS hashes the eleven characters of the name and extension, reads the HIT and walks it for bytes equal to the hash. The offset of each matching byte is the locator of a candidate entry; that directory sector is read and the eleven name bytes compared, because two names can share a hash.
• Creating a file: SYS2/SYS searches the HIT for a 00H byte, starting at a place taken from the clock so new files spread through the directory, stores the name's hash there and writes the HIT back.
• Continuation entries: a continuation entry is given the same hash as the file's primary entry; its attribute bit 7 makes the open skip it.

Space is allocated in granules of five sectors, two to a track (sectors 0-4 and 5-9). GAT byte t belongs to track t: bit 0 set means granule 0 is in use, bit 1 granule 1, and FFH marks a track with no free granule. Bytes E0H-FFH of the GAT sector hold the AUTO command.

A directory entry is 32 bytes:

• Byte 0: attributes. Bits 0-2 are the access level; bit 7 is set on a continuation entry (90H).
• Byte 1: on a continuation entry, the locator of the file's primary entry.
• Byte 3: the end-of-file byte, the offset after the last byte in the last sector (00H for a full sector).
• Byte 4: the logical record length.
• Bytes 5-15: the eight-character name and three-character extension, padded with spaces.
• Bytes 16-19: the owner and user password hashes.
• Bytes 20-21: the ending record number, the count of sectors in the file.
• Bytes 22-31: five extents of two bytes. The first is the track; in the second, bits 5-7 are the first granule and bits 0-4 one less than the number of granules. A track of FEH means the file goes on in the entry whose locator follows; FFH ends the list.

• Disables interrupts, sets the Stack Pointer to 41FCH and clears the screen.
• Selects drive 0 and reads sector 4 of the directory track into 4D00H. Entry 0 of that sector is the entry of SYS0/SYS (locator 02H); when it is not in use, NO SYSTEM is shown.
• Takes the first extent of the entry (track and first granule), and reads the sectors of SYS0/SYS one after the other from there into 4D00H, going on to the next track after sector 9.
• Works through the load records: type 01H blocks are stored at their addresses (SYS0/SYS fills 400CH-4F28H in parts, nothing at 4200H-42FFH or 4D00H-4DFFH), other types are skipped, and the type 02H record gives the transfer address, 4E00H, SYS0/SYS's start-up code, which it jumps to with interrupts still disabled.
• A sector that cannot be read in two tries shows DISK ERROR. After either message the code waits for ENTER and halts.

FORMAT/CMD writes the directory entry of BOOT/SYS with the attribute byte 5EH: a system file, in use, invisible, access level 6. As an invisible file it is not shown by DIR unless invisible files are asked for.

SYS0/SYS is the nucleus, the part of TRSDOS 2.3 that stays in memory. It holds the DOS entry point table at 4400H-4478H, the RST 28H overlay loader, the file routines (read, write, position, rewind, back up a record, position to the end), the conversion of a record number into a track and sector with the search of the file's extents and the allocation of granules, the WD1771 disk driver, the program loader, the interrupt handler with twelve timer task slots, the clock, the keyboard scan with debounce, and the TRACE and time displays. Two 256-byte sector buffers are used: 4200H-42FFH for directory sectors and 4D00H-4DFFH for loading and for the allocation table.

All system command processors and utility programs are disk resident. The overlays SYS1/SYS-SYS5/SYS are loaded at 4E00H by RST 28H, whose code names the overlay and the function in it; utilities and SYS6/SYS are loaded at 5200H.

As soon as SYS0/SYS is loaded into RAM by BOOT/SYS, its start-up code at 4E00H does the following:

1. Disables interrupts and selects interrupt mode 1.
2. Sets the stack to 41FCH and stores 5200H in 4047H.
3. Finds the top of memory and stores it in 4049H.
4. Puts the keyboard scan at 43D8H into the keyboard control block (4016H).
5. Stores the keyboard, video and printer driver addresses at 43B8H-43BDH and builds the device list (KI, DO, PR) at 43C0H-43CCH.
6. Copies the keyboard control block to 4358H-435FH, followed by eight 00H bytes and sixteen FFH bytes.
7. Disarms the BREAK vector at 4315H, sets the RST 38H vector at 4012H to JP 4518H, and enables the clock routine (4560H, vector 405BH) and the disk interrupt routine (4669H, vector 4059H) in the mask at 404CH.
8. Sets the system flags at 430FH to 01H (DEBUG off) and puts the clock task 45AFH into timer slot 7.
9. Displays the TRSDOS banner.
10. If ENTER is down, or the allocation table sector holds no AUTO command, goes to DOS READY; otherwise runs the AUTO command.

When the system is brought up or RESET is activated, control passes to LEVEL II. LEVEL II immediately determines if the system has disks. If it does, a special program called a boot loader is read from disk. The boot loader is used to load the nucleus for the disk operating system.

There are several aspects of the boot program that make it unique. Like the rest of the system programs, it exists as a named file. But because the space in LEVEL II used for reading the boot is restriced, it is assumed to exist at track 0, sector 0. Furthermore, it is an absolute core image program, one sector long. Thus it can be read directly into memory and executed.

The boot is the only core image program in TRSDOS. Binary modules produced by the editor assembler have embedded control codes indicating the load address, length of string to be loaded and a execution address. The core image of the boot was created by writing a section of memory containing the boot to disk

Control is passed to the boot after it has been read into locations 4200 - 42FF. Notice that this is one of the sector buffer address for the nucleus, so there is no conflict between the addresses for the boot and those of the nucleus. The boot then finds the disk address of SYSO/SYS (the nucleus), and loads it into memory. Since SYSO/SYS is not a core image program, the boot must be able to interpret the loader codes, and it must contain its own disk 1/0 routines, as well as a sector buffer. The sector buffer address is 4DOO - 4DFF; again there is no conflict with code in the nucleus because it has a sector buffer at the same address.

The boot has a limited facility for interpreting the granule allocation pairs in the directory describing the disk addresses for the nucleus. Therefore, it cannot have more than one granule allocation pair.

The initialization code at 4E00H runs once; it sits at the start of the overlay area, so the first overlay loaded overwrites it.

4E00H-4E1DH disable interrupts, select interrupt mode 1, set the stack to 41FCH, store 5200H in 4047H and find the top of memory: starting at FFFFH and going down 1K at a time, the first address that keeps a written value is stored in 4049H.

4E20H jumps to 4F20H, which stores 43D8H (the keyboard scan with debounce) into the keyboard control block at 4016H. Back at 4E23H the driver addresses of the keyboard, video and printer control blocks are stored at 43B8H-43BDH and, with the two-letter names from bytes 6-7 of each control block, in the device list at 43C0H-43CBH; 43CCH is set to 00H to end the list. The SYS6/SYS routine at 531DH lists the names.

4E57H-4E70H copy the keyboard control block to 4358H-435FH and store eight 00H and sixteen FFH bytes after it. The JR NZ instructions at 4E53H and 4E74H have a displacement of 00H, so the loops they belong to run only once.

4E76H-4E9DH read the disk status register, store 00H at 4315H (BREAK vector off) and at 404CH (no interrupt enabled), make 4012H a JP 4518H, put 4560H (clock) at 405BH and 4669H (disk) at 4059H, and set bits 7 and 6 of 404CH.

4E9FH-4EA9H set 430FH to 01H and put the clock task control block 45AFH into timer slot 7. Slot 7 runs once every eight clock ticks; the task counts five runs and then adds one second to the time at 4041H-4043H, carrying into the date at 4044H-4046H.

4EACH-4EB8H display the banner, stored as negated characters at 4EEDH. 4EBAH scans the keyboard once: with ENTER down the code goes to 4400H (DOS READY). Otherwise 4EC2H-4ECBH read sector 0 of track 11H, the granule allocation table sector, into 4200H; a read error goes to 4409H. If its byte at 42E0H is a carriage return no AUTO command is set and the code goes to 4400H; otherwise the 32 bytes at 42E0H-42FFH are copied to the command line buffer at 4318H, displayed, and run through 4405H (SYS1/SYS).

The nucleus contains code for interrupt processing, the timer tasks and the clock, disk and file services, the program loader, the overlay loader, the TRACE and time displays and the keyboard scan. Its data structures include the DOS entry point table, the per-drive track and directory track tables at 4300H-4307H, the command line buffer at 4318H, the overlay FCB at 44A0H and the interrupt vectors at 404DH-405CH. The SYS0/SYS disassembly has the details.

A disassembly of SYS0/SYS can be found here.

Bits 4-6 of the RST 28H code select the function. SYS0/SYS's fixed entry points supply the codes:

• 93H (10H) and A3H (20H): DOS READY. 402DH and 4400H use 93H; 4030H, the exit after an error, uses A3H. Interrupts are enabled, the stack is set to 41FCH, the prompt is displayed and a line is read with the ROM's 0040H.
• B3H (30H), from 4405H: run the command line at Register Pair HL. This is how the typed line is run, and how AUTO and BASIC/CMD hand a command to TRSDOS 2.3.
• C3H (40H), from 441CH: parse the filespec at Register Pair HL into the FCB at Register Pair DE: up to 8 characters of name, then optionally a slash and 3 characters of extension, a period and 8 characters of password, a colon and a 1-character drive, with 03H after the last field. A name starting with an asterisk is a device name. The words TO, ON and OVER are passed over.
• D3H (50H), from 4473H: add the three-character extension at Register Pair HL to the filespec in the FCB at Register Pair DE when it has none, moving the rest of the filespec up four bytes to make room for the slash and the extension.
• E3H (60H), from 4476H: parse a parameter list (NAME=value,...) at Register Pair HL using the table at Register Pair DE. Values can be X'hex digits', a decimal number, or YES, NO, ON or OFF; a name with no value stores FFFFH.

1. Push 402DH, the DOS READY exit, as the return address of the command.
2. Parse the first word as a filespec into the command FCB at 4480H; a word that is not a filespec, or a device name, displays WHAT?.
3. Look the name up in the first table: BASIC2, DEBUG and TRACE are carried out inside SYS1/SYS.
4. Look the name up in the second table: the nineteen library commands APPEND, ATTRIB, AUTO, CLOCK, COPY, DATE, DEVICE, DIR, DUMP, FREE, KILL, LIB, LIST, LOAD, PRINT, PROT, RENAME, TIME and VERIFY are passed to SYS6/SYS at 5200H with their number (1-19) in Register C. SYS6/SYS is loaded through RST 28H code 88H unless bit 4 of the system flags at 430FH shows it is still in memory.
5. Otherwise add /CMD when the name has no extension, clear bit 4 of 430FH, and load and run the program through SYS0/SYS's 4433H with Register Pair HL at the rest of the command line.

• BASIC2 copies the ROM's initial values back to 4000H-4035H, clears 4036H-405CH and jumps to the ROM's 0075H, leaving TRSDOS 2.3 for Level II BASIC.
• DEBUG (or DEBUG (ON)) sets bit 7 of 430FH and makes both the BREAK vector at 4315H and the error exit at 4030H go to the RST 30H vector at 400FH, the DEBUG entry. DEBUG (OFF) undoes this.
• TRACE (or TRACE (ON)) puts the task at 4CD9H, which shows the interrupted program counter at the top of the screen, into timer slot 11; TRACE (OFF) removes it.