xtrs(1)

✨ NAME ✨

Bestie, meet xtrs(1) — a TRS-80 Model I/III/4/4P emulator for the X Window System. That's the whole vibe: retro 8-bit microcomputer glory, but make it modern X11. 💖

---

🦋 SYNOPSIS 🦋

xtrs [-model m] [-diskdir d] [-debug] [other-options]

---

💖 DESCRIPTION 💖

Okay so xtrs is an emulator for a series of 8-bit microcomputers manufactured by Tandy/Radio Shack in the 1970s and 1980s. The program is built on top of a Zilog Z80 emulator, with added routines to support keyboard and video I/O through an X interface. The hardware emulation can operate as a TRS-80 Model I, Model III, Model 4, or Model 4P.

xtrs supports 48kiB of RAM in Model I or Model III mode, and 128kiB in Model 4 or Model 4P mode. Floppy disks and hard disks are emulated using files to store the data; or under Linux only, real floppy drives can be used. A printer is emulated by sending its output to the standard output. A serial port is emulated using a Unix terminal device. Cassette I/O is emulated using files to store the cassette data; real cassettes can also be read or written (with luck), either directly through your sound card (on Linux and other systems with OSS-compatible sound drivers), or via .wav files. Game sound and music output are also supported if you have an OSS-compatible sound driver; sound output through the cassette port, through the Model 4 sound option, and through the optional Orchestra-85/90 music synthesizer card are all emulated. In Model I mode, the HRG1B graphics card is emulated. In Model III and 4/4P mode, you can select whether the Radio Shack graphics card or Micro Labs Grafyx Solution is emulated. There is also a mouse driver for Model 4/4P mode. Several common time-of-day clock cards are emulated on all models. The Alpha Products joystick is emulated using the keyboard's numeric keypad.

Because xtrs emulates the hardware, all known TRS-80 Model I/III/4/4P operating systems should run on it, including all flavors of TRSDOS, LDOS/LS-DOS, NEWDOS, DOSPLUS, MultiDOS, and TRS-80 CP/M. However, the emulator also includes some extensions to the standard hardware, and the special drivers, utilities, and instructions needed for these are not provided for all operating systems.

The Z80 emulator has a debugger called zbx. You can enter the debugger either by starting xtrs with the -debug flag or by pressing F9 while xtrs is running. The debugger runs in the X terminal window that you started xtrs from. Once you are in the debugger, type help for more information.

Special support in the emulator allows the program to block when waiting for information from the keyboard. This will work only for programs that wait for keyboard input using the standard Model I/III ROM call; the emulator decides whether to block the Z80 program when it tries to read from the keyboard memory by pattern-matching its stack.

🎹 Keys 🎹

The following keys on the host keyboard have special meanings to xtrs.

• F11 — toggles onscreen help on the keyboard mappings.
• LeftArrow, Backspace, or Delete — the TRS-80 left arrow key. RightArrow or Tab — the right arrow key. UpArrow — the up arrow key. DownArrow or Linefeed — the down arrow key. Esc or Break — the Break key. Home or Clear — the Clear key. Control — the Model 4 Ctrl key (address bit 7, data bit 2). F12 — equivalent to the shifted down arrow key (used as a control key with some TRS-80 software).
• F1, F2, and F3 — the Model 4/4P function keys (address bit 7, data bits 4, 5, and 6). F1 is also the Model I Electric Pencil control key that some users added to their machines. F4 — the Model 4 Caps Lock key (address bit 7, data bit 3). F5, Compose, or ScrollLock — equivalent to the @ key (so that @ can be used as a modifier key). F6 — equivalent to the 0 key (so that a shifted 0 can be obtained). F7 — signals a floppy disk change (see Emulated floppy disks, below). F8 — exits the program. F9 — enters the zbx debugger. F10 — the reset button.

In Model III, 4, and 4P modes, the left and right Shift keys are distinct; in Model I mode, they are the same. The PageUp and PageDown keys always activate the positions that correspond to the Model III/4/4P left and right shift keys (address bit 7, data bits 0 and 1 respectively), even in Model I mode. The End key activates an unused position in the keyboard matrix (address bit 7, data bit 7).

The keys [, \, ], ^, and _ also activate unused positions in the keyboard matrix (address bit 3, data bits 3–7), as do the ASCII-shifted counterparts of the first four ({, |, }, and ~); see above regarding Delete. With many TRS-80 keyboard drivers, these keys map to the corresponding ASCII characters; with others, they do nothing. In some cases you may find the shift state reversed from what you expect; if, for instance, you press [ but “{” is displayed instead, see -shiftbracket and -noshiftbracket in Options, below, to correct the problem. The Insert key maps to the same position as underscore (address bit 3, data bit 7), so that this key can be used both with and without shift pressed; with many TRS-80 keyboard drivers one of these maps to ASCII code 0x7f (DEL).

On a German keyboard, the ¨ and ß keys should activate the corresponding characters used in the GENIE, a German Model I clone. This feature is most useful together with the -charset genie command-line option.

Pressing a key on a PC-style keyboard's numeric keypad with NumLock disengaged emulates the Alpha Products joystick. Keys 2, 4, 6, and 8 (KP_Down, KP_Left, KP_Right, and KP_Up) are the main directions; keys 1, 3, 7, and 9 (KP_End, KP_Page_Down, KP_Home, KP_Page_Up) work as diagonal directions by activating two main directions at once; and key 0 (KP_Insert) or 5 (KP_Begin) is the fire button. Note that your X server may default to sending digits for the keys on the numeric pad even if NumLock is not active. If you have this problem, you can use xev(1) to determine the names of the X keysyms generated by your keystroke events. You may need to check or update your XKB configuration. Alternatively, you can use xmodmap(1) to remap your numeric pad.

📼 Emulated cassette 📼

To control the emulated cassette, a file called .cassette.ctl in the current working directory keeps track of what file is currently loaded as the cassette tape and the current position within that file. The cassette(1) shell script provides a way to manipulate this file. You may use this script to load and position cassette tape files. The operation works very much like an actual tape recorder. The cassette man page has more information about the shell script and the cassette file formats that are supported.

🖨️ Printer 🖨️

For printer support, any text sent to the TRS-80's printer (using LPRINT or LLIST, for example) is sent to the standard output.

💾 Emulated floppy disks 💾

In Model I mode, xtrs emulates a Radio Shack Expansion Interface with the Percom Doubler or Radio Shack Doubler installed. The Doubler provides double-density disk access by allowing either the stock WD1771 FDC chip or a WD1791 chip to be selected under program control. At powerup the 1771 is selected, so operating systems with no Doubler driver see a stock system. By default, the emulator pretends to be both a Percom and Radio Shack Doubler at the same time—it responds to the special commands of both—so a driver for either should work. Under LDOS use the command FDUBL (on newer versions of LDOS), or PDUBL or RDUBL (on older versions) to install the driver. Software that tries to detect which doubler you have (such as Super Utility) may be confused by the emulation of both at once, so you can choose to emulate only one with a command-line option; see Options below.

In Model III, 4, or 4P mode, xtrs emulates the stock floppy controller, which uses a WD1793 chip (software-compatible with the WD1791) to provide both single and double density.

Four 5¼-inch floppy drives are emulated, with storage in files named diskM-U, where M is the TRS-80 model (1, 3, 4, or 4p) and U is the drive unit number (0, 1, 2, or 3). If a file of the required name is not found, a drive with no disk in it is emulated (but see below). If the user does not have write permission for a floppy file, and/or the file has an internal write protect flag set, a write-protect tab is emulated. Use the mkdisk(1) program to turn the write protect flag on or off. To change floppies in an emulated drive, rename the existing file for the drive (if any), rename the new floppy file to the proper name, and press F7 (see Keys, above).

If you try to boot an emulated Model I, III, or 4 with no file named diskM-0 (that is, no disk in drive 0), xtrs emulates having no floppy disk controller. The behavior of a real machine with a disk controller in this case didn't seem useful to emulate faithfully: a real Model I hangs with a screen full of garbage; a real Model III or 4 goes into a retry loop printing "Diskette?" on the screen and rechecking whether you've inserted one. A real Model 4P always has a floppy controller, however, so xtrs always emulates one.

Due to a limitation of the original Model I hardware, drive :3 cannot be double-sided in Model I mode. In the original Model I, you could not have a drive :3 at all if any drive in the system was double-sided, but the emulator is able to be more forgiving.

Emulated floppy image files can be of any of three types: JV1, compatible with Jeff Vavasour's popular freeware Model I emulator for MS-DOS; JV3, a compatible extension of a format first used in Vavasour's commercial Model III/4 emulator; or DMK, compatible with David Keil's Model 4 emulator. All three types work in xtrs regardless of what model it is emulating. A heuristic is used to decide which type of image is in a drive, as none of the types has a magic number or signature.

JV1 supports only single-sided, single-density diskettes, with directory on track 17. Sectors must be 256 bytes long. Use FORMAT (DIR=17) if you want to format JV1 disks with more (or less) than 35 tracks under LDOS.

JV3 is much more flexible, though it still does not support everything the real controllers could do. It is probably best to use JV3 for all the disk images you create, since it is the most widely implemented by other emulators, unless you have a special reason to use one of the others. A JV3 disk can be formatted with 128, 256, 512, or 1024-byte sectors, 1 or 2 sides, single or double density, with either an 0xFB (normal) or 0xF8 (deleted) data address mark on any sector. On single-density JV3 disks, the nonstandard data address marks 0xFA and 0xF9 are also available. You cannot format a sector with an incorrect track number or head number. You can format a sector with an intentional CRC error in the data field. xtrs supports at most 5802 total sectors on a JV3 image.

okay so the original Vavasour JV3 format? bestie, it only ever supported 256-byte sectors, and it capped out at 2901 total sectors. so if you go using sector sizes that aren't 256 bytes, or you format more than 2901 sectors onto a disk image, emulators that aren't xtrs might straight-up not be able to read it 😭 no cap. but also, listen: an 80 track, double-sided, double-density (18 sector) 5¼-inch floppy fits inside that original 2901 sector limit, no problem. the extension to 5802 is mainly there for emulating 8-inch drives (we get to those below, hold on 🫶).

The DMK format is the most flexible, periodt. it supports essentially everything the original hardware could do, including every single "protected" disk format 👑. that said, a few protected disks still might not work with xtrs — and that's not DMK's fault, it's limitations in xtrs's own floppy disk controller emulation. see Bugs and limitations, below 💅.

The program mkdisk(1) makes a blank emulated floppy, or "bulk erases" one you already have. by default mkdisk makes a JV3 floppy, but with the -1 flag it makes a JV1 floppy, and with the -k flag it makes a DMK floppy. see the mkdisk man page for the details, iykyk ✨.

---

now for the absolute iconic data address mark drama 🎀. early Model I operating systems used an 0xFA data address mark (DAM) for the directory on single-density disks, while later ones wrote 0xF8 — but they'd accept either one when reading. why the change? because 0xFA is a nonstandard DAM, and it's only fully supported by the WD1771 floppy disk controller used in the Model I. the controllers in the Model III and 4 literally cannot tell 0xFA and 0xFB apart when reading (0xFB is what's used for non-directory sectors), and they can't write 0xFA at all. 💀

so to deal nicely with this whole mess, xtrs implements the following kludge:

• on writing in single density, an 0xF8 data address mark is recorded as 0xFA.
• on reading with an emulated WD1771 (only available in Model I mode), 0xFA is returned as 0xFA.
• on reading with a WD179x, 0xFA is returned as 0xF8.

and the result? this trick makes the different operating systems perfectly compatible with each other — which is honestly better than on a real Model I 😭✨. if you need to, you can use the -truedam flag to turn this kludge off; in that case the original hardware is emulated exactly. no vibes, just silicon.

---

TRS-80 programs that try to measure the rotational speed of their floppy disk drives using timing loops will get the answers they expect — even when xtrs doesn't emulate instructions at the same speed as the original machines 🔥. why does that work? because xtrs keeps a virtual clock (technically, a T-state counter) that measures how much time it should have taken to execute the instruction stream on a real machine, and it ties the emulation of floppy disk index holes to that clock — not to real time. main character scheduling energy fr fr 👑

🎀 Emulated 8-inch floppy disks 🎀

on top of the four standard 5¼-inch drives, xtrs also emulates four 8-inch floppy drives. there's no widely-accepted standard hardware interface for 8-inch floppies on the TRS-80, so xtrs just emulates a pseudo-hardware interface of its own and ships an LDOS/LS-DOS driver for it. we love a bespoke solution 💅.

storage for the emulated 8-inch disks lives in files named diskM-U, where M is the TRS-80 model (1, 3, 4, or 4p) and U is the drive unit number (4, 5, 6, or 7). the only difference between 5¼-inch and 8-inch emulated drives is that the emulator lets you format more bytes per track on the latter 🦋.

• a new JV3 floppy can be formatted as either 5¼-inch or 8-inch, depending on whether you initially put it into a 5¼-inch or an 8-inch emulated drive.
• a new DMK floppy, though, has to be created with the -8 flag to mkdisk so it's big enough for use in an 8-inch emulated drive.
• JV1 floppies cannot be used in 8-inch drives at all. nope. 🙈

be careful not to put an emulated floppy into a 5¼-inch emulated drive after it's been formatted in an 8-inch emulated drive, or vice versa — the results are likely to be confusing. consider using different file extensions for the two types; say, .dsk for 5¼-inch and .8in for 8-inch.

To use the emulated 8-inch drives, you'll need a driver. under LDOS or LS-DOS, use the program XTRS8/DCT supplied on the emulated floppy utility.dsk. this driver is a very simple wrapper around the native LDOS/LS-DOS floppy driver. here are detailed instructions 📝:

1. first, make sure an appropriate version of LDOS is in emulated floppy drive 0, and the supplied file utility.dsk is in another emulated floppy drive. boot LDOS. if you're using Model I LDOS, be sure FDUBL is running.
2. second, type the following commands. here d is the LDOS drive number you want to use for the 8-inch drive, and u is the unit number you chose when naming the file. most likely you'll choose d and u to be equal, just to reduce confusion.

SYSTEM (DRIVE=dd,DRIVER="XTRS8",ENABLE)
Enter unit number ([4]-7): u

you can repeat these steps with different values of d and u to have more than one 8-inch drive. you might want to repeat four times using 4, 5, 6, and 7, or you might want to save some drive numbers for hard drives (see below).

finally, it's a good idea to give the SYSTEM (SYSGEN) command (Model I/III) or SYSGEN command (Model 4/4P) ✨. this command saves the SYSTEM settings, so the 8-inch drives will be available again the next time you reboot or restart the emulator. and if you need to access an 8-inch drive after booting from a disk that hasn't been SYSGENed? simply use the same SYSTEM command again. easy 🫶.

in case you want to write your own driver for another TRS-80 operating system, here are details on the emulated pseudo-hardware:

• the 8-inch drives are accessed through the normal floppy disk controller, exactly like 5¼-inch drives.
• the four 5¼-inch drives have hardware select codes 1, 2, 4, and 8, corresponding respectively to files diskM-0, -1, -2, and -3.
• the four 8-inch drives have hardware select codes 3, 5, 6, and 7, corresponding respectively to files diskM-4, -5, -6, and -7.

(see also the -sizemap option below, however. 👀)

🌈 Real floppy disks 🌈

under Linux only, any diskM-U file can be a symbolic link to a real floppy disk drive — typically /dev/fd0 or /dev/fd1. most machines with "legacy" (ISA bus) floppy drive support should be able to read and write TRS-80-compatible floppies this way 💖. but, and this is a big but: many floppy controllers cannot handle single density, and some may have problems even with double-density disks written on a real TRS-80 — especially disks formatted by older TRS-80 operating systems 😬.

• use the -doublestep flag if you need to read 35-track or 40-track media in an 80-track drive.
• if you need to write 35-track or 40-track media in an 80-track drive, bulk-erase the media first and format it in the 80-track drive.

don't write to a disk in an 80-track drive if it has ever been written to in a 40-track drive. the narrower head used in an 80-track drive cannot erase the full track width written by the head in a 40-track drive. that's not a vibe, that's just physics 💀

if you link one of the 5¼-inch floppy files (diskM-0 through diskM-3) to a real floppy drive, TRS-80 programs will see it as a 5¼-inch drive — but the actual drive can be either 3½-inch or 5¼-inch. the drive will be operated in double density (or single density), not high density, so be sure to use the appropriate media ⭐.

if you link one of the 8-inch floppy files (diskM-4 through diskM-7) to a real floppy drive, TRS-80 programs will see it as an 8-inch drive. again, you need to use the XTRS8/DCT driver described above to enable LDOS/LS-DOS to access an 8-inch drive. the real drive can be either 3½-inch, 5¼-inch, or 8-inch 🔥. a 3½-inch or 5¼-inch drive will be operated in high-density mode, using MFM recording if the TRS-80 is trying to do double density, or FM recording if the TRS-80 is trying to do single density. in this mode, these drives can hold as much data as a standard 8-inch drive. in fact:

• a 5¼-inch HD drive holds exactly the same number of bits per track as an 8-inch drive.
• a 3½-inch HD drive can hold 20% more, but we waste that space when using one to emulate an 8-inch drive.

and in both cases we also waste the top three tracks, since an 8-inch drive has only 77 tracks, not 80. 🫠

the nonstandard 0xFA and 0xF9 data address marks available in single density on a real Model I with the WD1771 controller also need special handling. an ISA-bus floppy disk controller can neither read nor write sectors with such DAMs at all. this raises three issues.

---

💖 and that's the whole xtrs(1) page, bestie — source, version and date are all chillin' in the little footer at the bottom of the man page, go peek at it, it's giving citation energy 🎀 slay, go format a floppy 🦋✨