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.

• Since some rudimentary disk support is hard coded into the Level II ROM, part of the nucleus (otherwise known as SYS0/SYS) loads into 4000H-4200H. This portion contains the jumps that were implemented in the ROM itself as well as an overlay loader, disk I/O services, the disk driver, TRACE and TIME displays, the interrupt service routine, all core resident data structures, 2 sector buffers and system initialization code. The actual program portion of the nucleus loads into RAM from 4200H-4E00H.
• 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 is NOT interrupt driven. It performs all of its tasks on demand. There are two library functions TRACE and CLOCK which do, however, make use of interrupts if invoked.

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 occupies memory from 4200-4E00. Portions of it are also loaded into the 4000 - 4200 region, and the system initialization code is loaded at 4EOO. The code loaded into the 4000 - 4200 region consists of jump vectors used for calling various nucleus functions, data structures and storage areas used by the nucleus and the remainder of the system. The system initialization code loaded at 4EOO is executed 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 (SYSl/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. Initially, the task list is empty. System commands for the CLOCK and TRACE functions require use of two of twelve entries in this list.

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. They will not be detailed here, but a complete list of nucleus entry points can be found in Section 3.4.14.

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 is the system's primary mechanism for speed. Rather than performing a slow, linear text search through every filename in the directory, TRSDOS uses a mathematical "hash" to jump to the correct entry.

• Hash Computation: When a file is opened (via SYS2/SYS), the system runs a routine to convert the ASCII filename into a single-byte hash code.
• Fast Lookup: The HIT contains a list of these hash codes. The system compares the calculated hash against the HIT; if a match is found, the HIT provides a pointer to the actual Directory Entry for that file.
• Collision Handling: If two different filenames result in the same hash code, the system will check the full filename in the directory entry to ensure it has found the correct file.

The GAT is the master map of the disk's physical space. It tracks which parts of the disk are in use and which are free.

• Granules: TRSDOS divides the disk into "granules" (typically 5 sectors each in a 35-track system). The GAT represents each of these granules with specific bits.
• Space Tracking: When a file is created or grows, the system consults the GAT to find a "free" bit, marks it as "in-use," and assigns that granule to the file.
• The FREE Command: When you run the FREE command, the system is essentially scanning the GAT to count the remaining "unassigned" bits to report how much space is left.

While the HIT finds the file and the GAT manages the disk, the Directory Entry itself stores the specific details of a file:

• Filename and Extension: The 8-character name and 3-character extension.
• Password and Protection: Security attributes that determine who can read, write, or execute the file.
• Extents (The GAP): Because files may be non-contiguous (scattered in different parts of the disk), the directory entry contains a Granule Allocation Pointer (GAP) chain. This is a list of exactly which granules on the disk belong to that specific file.
• End-of-File (EOF) Pointers: These track the exact byte where a file ends, ensuring that the system doesn't read past the actual data into empty sector space.

In TRSDOS 2.3, BOOT/SYS is the specialized system file responsible for the initial loading and configuration of the operating system after the hardware has been initialized. It serves as the bridge between the computer's basic ROM-resident state (Level II BASIC) and the full Disk Operating System environment.

The execution of BOOT/SYS is the final stage of a multi-step hardware and software hand-off:

• Hardware Initialization: When the TRS-80 Model I is powered on or reset, it automatically enters the Level II ROM at address 0000H (Power On) or 0066H (Reset).
• Disk Detection: The Level II initialization code performs a check to determine if a disk controller is physically present in the system.
• Primary Bootstrap: If a controller is detected, Level II reads a very small, primitive bootstrap program from the first sector of the disk in drive zero and executes it.
• Loading BOOT/SYS: This primary program then locates and loads the BOOT/SYS file, which contains the sophisticated logic required to bring the core TRSDOS components into memory.

Once BOOT/SYS takes control, it performs the critical tasks of establishing the TRSDOS environment:

• Loading the Nucleus: It loads the TRSDOS nucleus into memory, primarily occupying the region from 4200H to 4E00H.
• Vector and Data Setup: It populates the 4000H to 4200H RAM region with vital jump vectors used for calling nucleus functions, as well as data structures and storage areas required by the system.
• Initialization Code: It loads a specific block of system initialization code at address 4E00H. This code is executed immediately after the loading process finishes to finalize the system's operational state.
• Handover: After the core modules are resident and initialized, BOOT/SYS passes control to the TRSDOS nucleus, completing the "boot" of the computer.

As a critical system file, BOOT/SYS is typically assigned invisible attributes. This means it will not appear in a standard DIR (directory) listing unless the user specifically includes the "I" (invisible) parameter in the command.

TRSDOS is a disk resident, overlaid system. A small part of it (called the nucleus), is core resident, while the remainder resides on disk. The nucleus contains: an overlay loader, disk I/O services, the disk driver, TRACE and TIME displays, the interrupt service routine, all core resident data structures, 2 sector buffers and system initialization code.

All system command processors and utility programs are disk resident. The command processors are loaded as overlays above the nucleus (but below the utility load area). Utilities are loaded at 5200, which is considered the first available area of memory for user programs.

All system modules, including the nucleus and the overlays, exist on the disk as named files. The nucleus is named SYSO/SYS; The command overlays are named SYS1/SYS ... SYS6/SYS.

As soon as SYS0/SYS is loaded into RAM by BOOT/SYS, it does the following:

1. Disables interrupts.
2. Selects interrupt "mode 1" (meaning that when interrupts are enabled, all interrupts will be vectored to 0038H).
3. Initializes 5200H (the memory location used by user called programs).
4. Calculates the memory size and puts that into 4049H.
5. Initializes the device address table of 43B8H-43BFH.
6. Initializes the device mnemonic table of 43C0H-43CCH.
7. Loads an alternate keyboard driver into 43D8H-43FBH.
8. Sets up a keyboard buffer.
9. Copies the video driver address, video ram buffer address, printer driver address, and printer buffer into the device tables.
10. Copies the keyboard DCB to 4358H-435FH.
11. Puts the clock interrupt routine location and the disk interrupt routine location into the interrupt scan list at 405B and 4059, and then tells the interrupt controller that these exist.
12. Sets DEBUG to DISABLED and sets up the clock interrupts.
13. Displays the TRSDOS Banner.
14. Checks for an ENTER key and either processes AUTO if none or loads SYS1/SYS to wait for a 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.

System initialization is performed immediately after the nucleus has been loaded. Operations performed during this stage consist of the following: initializing the 4300 region, setting up the system stack pointer, determining memory size, initializing the device driver tables, and executing any procedure file created with the AUTO command.

Since this code is executed only once, the space it occupies can be used for other purposes after the initialization process has completed. In this case, the code begins at 4EOO, which is also the start of the nucleus overlay area. Because this code resides in the overlay area, it would be impossible to execute a nucleus overlay as part of the stytem start up initialization.

Beginning at 4E00, interrupts are disabled, and interrupt mode 1 is selected. Selection of interrupt mode 1 means that when interrupts are enabled, all interrupts will be vectored through location 0038. Next, the utility load address is initialized to 5200, and the memory size is computed by the loop at 4E0F-4E1B. When the highest RAM adddress is found, it is saved in 4049.

The code from 4E20-4E55 initializes the device address table (43B8-43BF) and the device mnemonic table (43C0-43CC). These tables are used by the DEVICE command to report the device configuration and the driver addresses for all devices listed in the table.

Starting at 4E20, the address of the replacement keyboard driver ( 43D8 - 43FB) replaces the address of the ROM driver in the keyboard DCB, as well as being stored in both device tables. Next, the keyboard RAM buffer address is saved in the device driver table.

Continuing at 4E2F, the video driver address and the video RAM buffer are both copied to the device tables. Next, the printer driver address and its buffer address are copied to the device tables. Finally, the list of driver and buffer addresses is terminated with a zero byte.

Beginning at 4E57, the keyboard DCB is copied to 4358 - 435F, then a loop is executed which zeros the 8 bytes after the DCB. A second loop starting at 4E6A stores 16 FF's after the 8 bytes of zeros. The reas6n for this initialization is not known.

There is some unused code in the section just described. The INC, JR, and LD instructions at 4E52 - 4E55, as well as the PUSH at 4E52 and the POP, DEC, and JR at 4E72 -4E75 serve no useful purpose. For that matter, neither does the LD instruction which begins the next section to be described.

Starting at 4E79, 4015 (the first byte of the keyboard DCB) is set to zero, and the interrupt mask control byte is zeroed. Zeroing the interrupt mask byte will cause any interrupts which might slip in (very unlikely since interrupts are inhibited) to be discarded.

Continuing at 4E81, a JP 4518 instruction is synthesized and stored into 4012. This replaces a DI/RET sequence placed there by the LEVEL II ROM code prior to the loading of the nucleus. This causes control to pass to 4518 when an interrupt is recieved. Next, the address of the clock interrupt routine (4560), and the disk interrupt routine 45F7 are stored in the interrupt scan list at 405B and 4059, respectively.

Following that, the interrupt mask control byte at 404C is updated to indicate interrupt routines exist for both clock and disk interrupts.

At 4E9F, the DEBUG control byte is initialized to a positive value (DEBUG not active), and 45AF (address of the clock maintenance code) is stored in the interrupt task list by calling a system service routine at 4410. The maintenance routine will be executed evey 200 milliseconds under the control of the interrupt processor. It updates the binary clock values maintained in 4041 - 4043; however, the clock value will only be displayed if the CLOCK ON command is executed.

Upon return, the message 'TRSDOS 2.3 .... 'is displayed by the loop from 4EAF - 4EB8. This code is followed by a call to scan the keyboard. If the carriage return key is active, the AUTO procedure test is skipped, and control passes immediately to 4400, where a call to load and execute SYSl is performed. If the carriage return key is not active, the code at 4EC2 -4ECB is executed to read sector 1 of track 11 into the buffer at 4200. If an error occurs during the read, control goes to 4409, where SYS4 is called to display an error message.

Assuming no read error, the buffer is examined to determine if an AUTO procedure has been defined. A carriage return at 42EO (the EO'th byte of the sector) means no AUTO procedure file exists. In this case also, control passes to 4400, which causes SYSl (the command line processor) to be loaded and executed.

If 42E0 does not contain a carriage return, it is assumed to hold a 20-character command to be executed. This command is copied to the commmand line buffer by the code at 4ED9 - 4EE2, displayed on the video, and then SYSl is called to process the command.

When the initialization code completes, it exits by jumping to 4400 or 4405 to load and execute SYSl. At that time, SYSl will either wait for the next command or process the one in the command line buffer.

The nucleus is the core resident portion of TRSDOS. It contains code for the following functions: interrupt processing, disk services, a file loader, trace display, clock display and the keyboard driver. In addition, data structures used throughout the system are maintained in the nucleus. Those structures are: a jump table for nucleus funtions, the command line buffer, a disk track history table and interrupt processor addresses.

A disassembly of SYS0/SYS can be found here.

As the primary interface between the user and the operating system, SYS1/SYS performs several critical roles:

• Input Processing: It manages the "waiting for input" state of the operating system, reading characters from the keyboard into a command line buffer.
• Command Identification: It compares the user's input against a list of known system commands to determine the appropriate action.
• Parameter Parsing: It extracts parameters (such as filenames or options) from the command line and prepares them for the specific command processor.
• Execution Coordination: Depending on the command, SYS1/SYS may execute the code directly, load a secondary overlay, or call an external utility program located on the disk.

SYS1/SYS is organized around specific Request Codes that handle different aspects of command processing:

• Request Codes 10, 20, and 30: These are utilized for primary command line processing and initial validation of the input string .
• Request Code 40: This code handles specialized command routing and further interpretation of complex command structures.
• Request Code 50: Often used for managing system-level status checks or specific environmental transitions during command execution.
• Request Code 60: This section is involved in finalizing command processing or returning control to the main system loop after a command has completed.

SYS1/SYS does not work in isolation; it serves as a hub for other system components:

• Utility Interfacing: When an external utility (like BACKUP or FORMAT) is called, SYS1/SYS passes the HL register to the utility, pointing it to the first character after the command name in the buffer so the utility can parse its own arguments.
• Subroutine Provider: It contains essential subroutines that are frequently referenced by SYS6/SYS (the module containing the bulk of TRSDOS commands) to assist in command execution.
• Overlay Management: Because it is an overlay itself, it resides in the memory region starting at 4E00H and is loaded on a demand basis by the nucleus.

To conserve RAM, SYS1/SYS is only resident in memory when the system is waiting for a command or actively parsing one. Once a large utility program is loaded at 5200H, or if another overlay is required, SYS1/SYS may be overwritten and reloaded later when the system returns to the TRSDOS READY prompt.

10 and 20: Read and process next command from the keyboard.

1. Enable interrupts.
2. Initialize an empty stack pointer to 41FEH.
3. Test the system conditions flags (LEVEL II or TRSDOS, RUN active or not active, SYS6 loaded or not loaded, Chaining active or inactive, PROT allowed or disallowed, and DEBUG inactive or active).
4. Display DOS READY and process the keyboard entry and 63 character keyboard buffer.
5. If an ENTER key is pressed, jump to option 30.

30: Interpret the command in the command line buffer.

1. Copy the command line to the system DCB at 4480H.
2. Compare the command to a list Library commands embedded in SYS1/SYS and process if found.
3. Compare the command to a list Library commands embedded in SYS6/SYS and process if found.
4. Add a CMD suffix to the command line in the system DCB, and call the nucleus to load and execute it.

40: Move a string to the DCB and validate as a filename.

DE points to the DCB and HL the address of the command line buffer. 8 characters are read, and if a "/" is next, then 3 characters and if a "." is next, then 8 characters, and if a ":" is next, then 1 character. A 03H delimiter is put at the end.

50: Add a suffix to a command that is missing a suffix.

DE points to the DCB and HL the address of the 3 character extension. 9 characters are tested, including for the possibility of a /, ., or : or a terminator. If / is found, then there is already an extension and the routine exits. If not, a 4 character hole is punched in the middle of the filename and "/CMD" is added.

60: Parse whatever parameters may come after the filename.

Checks for parenthesis, commas, spaces, and a hex delimiter.