TRSDOS Commented

written by Matthew Reed

There were many popular books published back in the late 1970’s and early 1980’s that examined the TRS-80 Model I in detail. But there were far fewer books that served the same purpose for the TRS-80 Model III.

TRSDOS Commented, published by Soft Sector Marketing with “decoding and data entry” by Rick Papo, was one of those few. The book’s cover described it as “a must for every Mod III owner.” It included a complete disassembly for the code comprising Model III TRSDOS (minus Disk BASIC) in much the same way as the IJG book TRSDOS 2.3 Decoded and Other Mysteries did for Model I TRSDOS. One notable difference was that the disassembled listings in TRSDOS 2.3 Decoded and Other Mysteries were published with full permission from Tandy Corporation. Soft Sector Marketing had no such permission and included this disclaimer at the beginning of TRSDOS Commented:

Soft Sector Marketing, Inc. is in no way attempting to infringe upon the proprietary rights of the Tandy Corporation by this publication. The expressed purpose of TRSDOS Commented is to aid users of MOD III microcomputers in using and understanding their machines.

Here is the description of the TRSDOS Commented from the book’s introduction:

This book is intended to show moderately experienced programmers the organization and inner workings of a typical Z80 disk operating system. Every function of the operating system has been decoded and explained, not to bit-by-bit detail, which would be a monstrous task, but rather at an instruction-by-instruction level. Many not-documented features of the system have been found, as well as a few errors. Hopefully, the techniques shown in the system coding will be useful as a guide to programmers interested in systems programming at an assembler level.

TRSDOS Commented consists of five parts:

1. A list of useful but undocumented TRSDOS routines.
2. Descriptions of some internal TRSDOS structures, both documented and undocumented.
3. Three “useful patches” to TRSDOS to change floppy stepping speed, disable passwords, and alter the number of tracks per disk.
4. A complete disassembly of Model III TRSDOS, including all commands and overlays except for Disk BASIC.
5. A reproduction of the data sheet for the Western Digital disk controller used in the Model III.

The TRSDOS disassembly comprises the bulk of the book and is very heavily commented. Like most books of this type, it shows all the instructions but omits the machine language hexadecimal bytes.

There are two slightly odd things about the disassembled listing. Some of the disassembled instructions shown are slightly non-standard, with implied operands always listed. For example, the instruction is given as CP A,A instead of the standard CP A.

A more unusual detail is the treatment of self-modifying code. Like most complicated Z80 programs, Model III TRSDOS sometimes directly changes its own instruction codes to save code space or for speed. Self-modifying code tends to obscure a disassembled code listing.

To help make this clearer, TRSDOS Commented deals with self-modifying code by showing what the instruction actually does rather than the actual instruction. As an example (taken from the book’s introduction), here is the actual instruction at address 5060H:

5060>   LD A,00H        GET DISK DRIVE NUMBER

TRSDOS alters the value at 5061H at another point in the code to change the drive number. This isn’t reflected in a normal disassembly. Here is how TRSDOS Commented shows the instruction:

5060>   LD A,(5061H)        GET DISK DRIVE NUMBER

This isn’t strictly correct, but it does show that the instruction operand is being altered elsewhere in the code.

As far as I know, there was only one printing of TRSDOS Commented in April 1982. Soft Sector Marketing went out of business in July 1983 and their books, including Alien Defense Commented, MOD III Commented, and TRSDOS Commented (in particular) became unavailable. The limited printing gave TRSDOS Commented the distinction of being generally regarded as the rarest major TRS-80 book ever published.