MAN page from Mandrake Other xtrs-3.1-1.i386.rpm
xtrs
Section: User Commands (1)
Index Name
xtrs - TRS-80 Model I/III/4 emulator for the X Window System
Syntax
xtrs [-model m] [-diskdir d] [-debug][other options] Description
xtrs is built on top of a Z-80 emulator, with added routines to supportkeyboard 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 48K of RAM in Model I or Model III mode,128K 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 bysending its output to standard output. There is also a rudimentary emulation of cassette I/Othat uses files for cassette tapes (Model I mode only).Crude sound support is available under Linux if you have SoundBlaster-compatible hardware.In Model 4/4P mode, a hi-res graphics card is emulated; you can select eitherthe Radio Shack card or the Micro Labs Grafyx Solution card.There is also a mouse driver for Model 4/4P mode.
Because xtrs emulates the hardware, all known TRS-80 ModelI/III/4/4P operating systems should run on it, including all flavorsof TRSDOS, LDOS/LS-DOS, NEWDOS, DOSPLUS, MultiDOS, and TRS-80 CP/M.However, the emulator also includes some extensions to the standardhardware, and the special drivers, utilities, and instructions neededfor these are not always provided for all systems. In particular, thehard disk emulation currently works only with LDOS/LS-DOS.
The Z-80 emulator has a debugger called zbx. It works sort oflike dbx. If you run with debugging turned on (see the options section forhow to do this), you'll enter the debugger, andyou can type ``help'' for more information.
Special support in the emulator allows the program to block whenwaiting for information from the keyboard. This will work only forprograms that wait for keyboard input using the standard Model I/IIIROM call; the emulator decides whether to block the Z-80 program whenit tries to read from the keyboard memory by pattern-matching itsstack.
Keys
The following keys have special meanings to
xtrs:
LeftArrow, Backspace, or Delete is the TRS-80 left arrow key.RightArrow or Tab is the right arrow key. UpArrow is the up arrowkey. DownArrow or Linefeed is the down arrow key. Esc or Break isthe Break key. Clear or LeftAlt is the Clear key. Control isthe Model 4 Ctrl key (address bit 7, data bit 2). RightAlt isequivalent to the shifted down arrow key (used as a control key withsome TRS-80 software).
F1, F2, and F3 are the Model 4/4P function keys (address bit 7, data bits4, 5, and 6). F1 is also the Model I Electric Pencil control key thatsome users added to their machines. F4 is the Model 4 Caps Lock key(address bit 7, data bit 3). F5, Compose, or ScrollLock is equivalentto the @ key (so that @ can be used as a modifier key). F6 isequivalent to the 0 key (so that a shifted 0 can be obtained). F7signals a disk change in the emulated floppy drives (see below). F8exits the program. F9 requests entry to the debugger if it is active.F10 is the reset button.
In Model III, 4, and 4P modes, the left and right shift keys are distinct; inModel I mode, they are the same. The Home key activates theposition in the TRS-80 keyboard matrix that corresponds to the ModelIII/4/4P right shift key (address bit 7, data bit 1) 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 (addressbit 3, data bits 3-7). These keys map to the corresponding ASCIIcharacters under some TRS-80 keyboard drivers; under others, they donothing. The Insert key is equivalent to underscore (address bit 3,data bit 7), so that a shifted underscore can be obtained; this mapsto ASCII code 0x7f under some TRS-80 keyboard drivers. Note: Common Model 4keyboard drivers seem to reverse the shift state of these keys, so you mayneed to press Shift+Insert to get an underscore, etc.
Emulated cassette
To control the emulated cassette, a file called ``.cassette.ctl'' in thecurrent directory keeps track of what file is currently loaded asthe cassette tape and the current position within that file. The
cassette shell script provides a way to manipulate this file; typing``help'' shows its commands. You may use this script to load andposition cassette tape files. The operation works very much like anactual tape recorder. The cassette emulation works only in Model I mode.
Printer
For printer support, any text sent to the TRS-80's printer (using LPRINTor LLIST, for example) is sent to the standard output.
Emulated floppy disks
In Model I mode,
xtrs emulates a Radio Shack Expansion Interfacewith the Percom Doubler or Radio Shack Doubler installed. The Doublerprovided double-density disk access by allowing either the stockWD1771 FDC chip or a WD1791 chip to be selected under program control.At powerup the 1771 is selected, so operating systems with no Doublerdriver see a stock system. By default, the emulator pretends to beboth a Percom and Radio Shack Doubler at the same time -- it respondsto the special commands of both -- so a driver for either should work.Under LDOS, use the command ``FDUBL'' (newer versions of LDOS), or``PDUBL'' or ``RDUBL'' (older versions) to install the driver. Software thattries to detect which doubler you have (such as Super Utility) may beconfused by the emulation of both at once, so you can choose to emulateonly one with a command line option; see below.
In Model III, 4, or 4P mode, xtrs emulates the stock floppycontroller, which used a WD1793 chip (software-compatible with theWD1791) to provide both single and double density.
Four 5.25-inch floppy drives are emulated, with storage in files nameddiskM-U, where M is the TRS-80 model (1, 3, 4, or 4p) and U is the driveunit number (0, 1, 2, or 3). If a file of the required name is notfound, a drive with no disk in it is emulated (but see below). If theuser does not have write permission for a floppy file, a write-protecttab is emulated. To change floppies in an emulated drive, rename theexisting file for the drive (if any), rename the new floppy file tothe proper name, and hit function key F7 in the emulator.
If you try to boot with no file named diskM-0 (that is, no disk indrive 0), xtrs emulates having no disk controller. The behavior of areal machine with a disk controller in this case didn't seem useful toemulate faithfully: A real Model I hangs with a screen full ofgarbage; a real Model III or 4 goes into a retry loop printing``Diskette?'' on the screen and rechecking whether you've inserted one.
Due to a limitation of the original Model I hardware, drive :3 cannotbe double-sided in Model I mode. In the original Model I, you couldnot have a drive :3 at all if any drive in the system wasdouble-sided, but the emulator is able to be more forgiving.
Emulated floppy image files can be of either of two types: JV1,compatible with Jeff Vavasour's popular freeware Model I emulator forthe PC; or JV3, a compatible extension of a format first used inVavasour's commercial Model III/4 emulator. Both types work inxtrs regardless of what model it is emulating. A heuristic isused to decide which type of image is in a drive, as neither type hasa magic number or signature.
JV1 supports only single density, single sided, with directory ontrack 17. Sectors must be 256 bytes long. Use FORMAT (DIR=17) if youwant to format JV1 disks with more (or less) than 35 tracks underLDOS.
JV3 is much more flexible, though it still does not support everythingthe real controllers could do. It is best to use JV3 for all the diskimages you create, unless you need to exchange images with someone whois using the Vavasour Model I emulator. A JV3 disk can be formattedwith 128, 256, 512, or 1024-byte sectors, 1 or 2 sides, single ordouble density, with either FB (normal) or F8 (deleted) data addressmark on any sector. You cannot format a sector with an incorrecttrack number or head number. You can format a sector with anintentional CRC error in the data field. xtrs supports at most96 cylinders and at most 5802 total sectors on a JV3 image.
The original Vavasour JV3 format supported only 256-byte sectors, andhad a limit of 2901 total sectors. If you use sector sizes otherthan 256 bytes or format more than 2901 sectors on a disk image,emulators other than xtrs may be unable to read it. Note thatan 80 track, double-sided, double-density (18 sector) 5.25-inch floppywill fit within the original 2901 sector limit; the extension to 5802is primarily for emulation of 8-inch drives (discussed below).
The program mkdisk(1) makes a blank emulated floppy or ``bulkerases'' an existing one. By default, mkdisk makes a JV3 floppy, butwith the -1 flag it makes a JV1 floppy. See the mkdisk man pagefor more information.
Early Model I operating systems used an FA data address mark for thedirectory (a nonstandard value supported only by the WD1771, but notthe WD1791/3), while later ones wrote F8 (for Model III/4/4P compatibility)but could read either. To deal nicely with this problem, xtrsimplements the following kludge. On writing, any data address markother than FB is recorded as F8. On reading in single density withthe emulated WD1771 (available in Model I mode only), F8 is returnedas FA. In all other modes, F8 is returned as F8. This trick makesthe different operating systems perfectly compatible with each other,which is better than on a real Model I!
TRS-80 programs that attempt to measure the rotationalspeed of their floppy disk drives using timing loops will get theanswers they expect, even though xtrs does notemulate instructions at the same speed as the originalmachines. This works because xtrs keeps a virtual clock (technically, a T-state counter),which measures how much time it should have taken to execute theinstruction stream on a real machine, and it ties the emulation offloppy disk index holes to this clock.
Emulated 8-inch floppy disks
In addition to the four standard 5.25-inch drives,
xtrs alsoemulates four 8-inch floppy drives. There is no widely-acceptedstandard hardware interface for 8-inch floppies on the TRS-80, so
xtrsemulates a pseudo-hardware interface of its own and provides an LDOS/LS-DOSdriver for it.
Storage for the emulated 8-inch disks is in files named diskM-U, whereM is the TRS-80 model number (1, 3, 4, or 4P) and U is a unit number (4,5, 6, or 7). These files are in exactly the same JV3 format as 5.25-inchfloppy files. A new JV3 floppy can be formatted as either 5.25-inch or8-inch depending on whether you initially put it into a 5.25-inch or8-inch emulated drive. The only difference between 5.25-inch and 8-inchemulated drives is that the emulator allows you to format more sectorsper track in the latter. Be careful not to put a 5.25-inch formattedemulated floppy into an 8-inch emulated drive or vice versa; theresults are likely to be confusing. Consider using different fileextensions for the two types; say, .dsk for 5.25-inch and .8in for 8-inch.
To use the emulated 8-inch drives, you'll need a driver. Under LDOSor LS-DOS, use the program XTRS8/DCT supplied on the emulated floppyutility.dsk. This driver is a very simple wrapper around thenative LDOS/LS-DOS floppy driver. Here are detailed instructions.
First, make sure an appropriate version of LDOS is in emulated floppydrive 0, and the supplied file utility.dsk is in anotheremulated floppy drive. Boot LDOS. If you are using Model I LDOS, besure FDUBL is running.
Second, type the following commands. Here d is the LDOS drivenumber you want to use for the 8-inch drive and u is theunit number you chose when naming the file. Most likely you willchoose d and u to be equal to reduce confusion.
SYSTEM (DRIVE=d,DRIVER="XTRS8",ENABLE) Enter unit number ([4]-7): u
You can repeat these steps with different values of d andu to have more than one 8-inch drive. You might want to repeatfour times using 4, 5, 6, and 7, or you might want to save some drivenumbers for hard drives (see below).
Finally, it's a good idea to give the SYSTEM (SYSGEN) command (ModelI/III) or SYSGEN command (Model 4/4P). This command saves the SYSTEMsettings, so the 8-inch drives will be available again the next timeyou reboot or restart the emulator. If you need to access an 8-inchdrive after booting from a disk that hasn't been SYSGENed, simply usethe same SYSTEM command again.
In case you want to write your own driver for another TRS-80 operatingsystem, here are details on the emulated pseudo-hardware. The 8-inchdrives are accessed through the normal floppy disk controller, exactlylike 5.25-inch drives. The four 5.25-inch drives have hardware select codes1, 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 realfloppy disk drive, typically /dev/fd0 or /dev/fd1. Most PCs should beable to read and write TRS-80 compatible floppies in this way. ManyPC floppy controllers cannot handle single density, however, and somemay have problems even with double density disks written on a realTRS-80, especially disks formatted by older TRS-80 operating systems.Use the -doublestep flag if you need to read 35-track or 40-trackmedia in an 80-track drive. If you need to write 35-track or 40-trackmedia in an 80-track drive, bulk-erase the media first and format itin the 80-track drive. Don't write to a disk in an 80-track drive if ithas ever been written to in a 40-track drive. The narrower head usedin an 80-track drive cannot erase the full track width written by thehead in a 40-track drive.
If you link one of the 5.25-inch floppy files (diskM-0 throughdiskM-3) to a real floppy drive, TRS-80 programs will see it as a5.25-inch drive, but the actual drive can be either 3.5-inch or5.25-inch. The drive will be operated in double density (or singledensity), 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-inchdrive. Again, you need to use the XTRS8/DCT driver described above toenable LDOS/LS-DOS to access an 8-inch drive. The real drive can beeither 3.5-inch, 5.25-inch, or 8-inch. A 3.5-inch or 5.25-inch drivewill be operated in high-density mode, using MFM recording if theTRS-80 is trying to do double density, FM recording if the TRS-80 istrying to do single density. In this mode, these drives can hold asmuch data as a standard 8-inch drive. In fact, a 5.25-inch HD driveholds exactly the same number of bits per track as an 8-inch drive; a3.5-inch HD drive can hold 20% more, but we waste that space whenusing one to emulate an 8-inch drive. In both cases we also waste thetop three tracks, since an 8-inch drive has only 77 tracks, not 80.
If you try to access a real floppy drive with no disk in it,xtrs will print an error message, and the Z-80 program will geta somewhat different error than it should. After inserting a disk,you must press F7 to clear the error condition.
Emulated hard disks
xtrs can emulate a hard disk in a file with the aid of a specialLDOS driver called XTRSHARD/DCT. This driver has been tested andworks under both LDOS 5.3.1 for Model I or III and TRSDOS/LS-DOS 6.3.1for Model 4/4P. It may or may not work under earlier LDOS versions. Itdefinitely will not work under other TRS-80 operating systems or withemulators other than
xtrs. The hard disk format was designed byMatthew Reed for his Model I/III and Model 4 emulators;
xtrsduplicates the format so that users can exchange hard drive imagesacross the emulators.
To use the hard disk emulation, first run the mkdisk programunder Unix to create a blank hard drive (.hdv) file. Typical usagewould be: mkdisk -h mydisk.hdv. See the mkdisk(1) manpage for other options.
Second, link the file to an appropriate name. xtrs supports upto eight hard drives, with names of the form hardM-U, where M is theTRS-80 model (1, 3, or 4; in this case Model 4P also uses M=4) and Uis a unit number from 0 to 7. It looks for these files in the samedirectory as the floppy disk files diskM-U.
Third, make sure an appropriate version of LDOS is in emulated floppydrive 0, and the supplied file utility.dsk is in anotheremulated floppy drive. Boot LDOS. If you are using Model I LDOS5.3.1, patch a bug in the FORMAT command by typing PATCHFORMAT/CMD.UTILITY M1FORMAT/FIX. You need to apply this patch onlyonce. It must not be applied to Model III or Model 4/4P LDOS.
Fourth, type the following commands. Here d is the LDOS drive numberyou want to use for the hard drive (a typical choice would be 4) and uis the unit number you chose when naming the file (most likely 0).
SYSTEM (DRIVE=d,DRIVER="XTRSHARD",ENABLE) Enter unit number ([0]-7): u FORMAT d (DIR=1)
Answer the questions asked by FORMAT as you prefer. If you arecurious about the DIR=1 parameter to FORMAT, seemkdisk(1). You can repeat these steps with different values ofd and u to have more than one hard drive.
Finally, it's a good idea to give the SYSTEM (SYSGEN) command (ModelI/III) or SYSGEN command (Model 4/4P). This command saves the SYSTEMsettings, so the drive will be available again the next time youreboot or restart the emulator. If you need to access the hard diskfile after booting from a floppy that hasn't been SYSGENed, simply usethe same SYSTEM command(s) again, but don't FORMAT. You can freelyuse a different drive number or (if you renamed the hard disk file) adifferent unit number.
The F7 key currently doesn't allow hard disk changes to be recognized,but you can change to a different hard disk file for the same unit byrenaming files as needed and rebooting LDOS.
Technical note: XTRSHARD/DCT is a small Z-80 program that implementsall the required functions of an LDOS disk driver. Instead of talkingto a real (or emulated) hard disk controller, however, it uses specialsupport in xtrs that allows Z-80 programs to open, close, read,and write Unix files directly. This support is described further inthe next section. Because xtrs does not emulate real hard drivecontroller hardware, hard disk drivers other than XTRSHARD/DCT willnot work with it.
Data import and export
Several Z-80 programs for data import and export from various TRS-80operating systems are included with
xtrs on two emulated floppyimages. These programs use special support in the emulator to readand write external Unix files, discussed further at the end of this section.
The emulated floppy utility.dsk contains some programs fortransferring data between the emulator and ordinary Unix files. Allthese programs run on the emulator under Model I/III LDOS, Model I/IIINewdos/80, and Model 4/4P TRSDOS/LS-DOS 6; they may also work under otherTRS-80 operating systems.
IMPORT/CMD imports a Unix file and writes it to an emulated disk.Usage: IMPORT [-ln] unixfile [trsfile]. The -n flag convertsUnix newlines (\n) to TRS-80 newlines (\r). The -l flag convertsthe Unix filename to lower case, to compensate for TRS-80 operatingsystems such as Newdos/80 that convert all command line arguments toupper case. If the destination file is omitted, IMPORT uses the lastcomponent of the Unix pathname, but with any "." changed to "/" tomatch TRS-80 DOS file extension syntax.
IMPORT/BAS is a much slower program that performs the same function asIMPORT/CMD but may work under more operating systems. Simply run itunder Disk Basic and answer the prompts.
EXPORT/CMD reads a file from an emulated disk and exports it to a Unixfile. Usage: EXPORT [-ln] trsfile [unixfile]. The -n flagconverts TRS-80 newlines (\r) to Unix newlines (\n). The -l flagconverts the Unix filename to lower case, to compensate for TRS-80operating systems such as Newdos/80 that convert all command linearguments to upper case. If the destination file is omitted, IMPORTuses the TRS-80 filename, but with any "/" changed to "." to matchUnix file extension syntax.
EXPORT/BAS is a much slower program that performs the same function asEXPORT/CMD but may work under more operating systems. Simply run itunder Disk Basic and answer the prompts.
SETTIME/CMD reads the date and time from Unix and sets the TRS-80DOS's date and time accordingly.
CD/CMD (or CD6/CMD) changes xtrs's Unix working directory. Thiswill change the interpretation of any relative pathnames given toIMPORT or EXPORT. (It will also change the interpretation of disknames at the next disk change, unless you specified an absolutepathname for xtrs's -diskdir parameter.) CD/CMD runs on LDOS 5.x,CD6/CMD on LS-DOS 6.x. They have not been tested on other TRS-80operating systems.
PWD/CMD (or PWD6/CMD) prints xtrs's Unix working directory.PWD/CMD runs on LDOS 5.x, PWD6/CMD on LS-DOS 6.x. They have notbeen tested on other TRS-80 operating systems.
UNIX/CMD (or UNIX6/CMD) runs a Unix shell command. Standard I/O forthe command uses the xtrs program's standard I/O descriptors; it doesnot go to the TRS-80 screen or come from the TRS-80 keyboard. UNIX/CMDruns on LDOS 5.x, UNIX6/CMD on LS-DOS 6.x. They have not been testedon other TRS-80 operating systems.
MOUNT/CMD (or MOUNT6/CMD) is a convenience program that switchesemulated floppy disks in the drives. Usage: OUNT filename U.The filename is any Unix filename; U is a single digit, 0 through 7.The command deletes the file diskM-U (where M is the TRS-80 model)from the disk directory (see -diskdir option), replaces it with asymbolic link to the given filename, and signals a disk change (as ifF7 had been pressed). MOUNT/CMD runs on LDOS 5.x, MOUNT6/CMD onLS-DOS 6.x. They have not been tested on other TRS-80 operatingsystems.
UMOUNT/CMD (or UMOUNT6/CMD) is a convenience program that removes anemulated floppy disk from a drive. Usage: MOUNT U. U is asingle digit, 0 through 7. The command deletes the file diskM-U(where M is the TRS-80 model) from the disk directory (see -diskdiroption) and signals a disk change (as if F7 had been pressed).UMOUNT/CMD runs on LDOS 5.x, UMOUNT6/CMD on LS-DOS 6.x. They have notbeen tested on other TRS-80 operating systems.
The emulated floppy cpmutil.dsk contains import and exportprograms for Montezuma CP/M, written by Roland Gerlach. It wasformatted as a ``Montezuma Micro Standard DATA disk (40T, SS, DD,200K),'' with 512-byte sectors. Be careful to configure your CP/M tothe proper disk format and drive parameters (40 track, not 80), or youwill have confusing problems reading this disk. Source code isincluded on the floppy; please pass any improvements you make back tothe author.
IMPORT.COM imports a Unix file and writes it to an emulated CP/M disk.Usage: IMPORT [-n] [unixfile [cpmfile]]. The -n flag convertsUnix newlines (\n) to CP/M newlines (\r\n). If the second filenameis omitted, it is taken to be the same as the first. If both names areomitted, the program prompts for filenames. Note that the CP/M CCPconverts all command line arguments to upper case, which isinconvenient if your Unix file names are in lower case; in that caseyou'll need to let the program prompt for the filenames.
EXPORT.COM reads a file from an emulated CP/M disk and exports it to aUnix file. Usage: EXPORT [-n] [cpmfile [unixfile]]. The -nflag converts CP/M newlines (\r\n) to Unix newlines (\n). If thesecond filename is omitted, it is taken to be the same as thefirst. If both names are omitted, the program prompts for filenames.Note that the CP/M CCP converts all command line arguments to uppercase, which is inconvenient if your Unix file names are in lower case;in that case you'll need to let the program prompt for the filenames.
The emulator implements a set of pseudo-instructions (emulator traps)that give TRS-80 programs access to Unix files. The programs listedabove use them. If you would like to write your own such programs,the traps are documented in the file trs_imp_exp.h. Assemblersource code for the existing programs is supplied in xtrshard.z,import.z, export.z, and settime.z. You can also write programs thatuse the traps in Misosys C, using the files xtrsemt.h and xtrsemt.cccas an interface; a simple example is in settime.ccc. The Basicprograms import.bas and export.bas should not be used as a basis forfurther development, however; they use an old, slow mechanism in theemulator that may be removed in a future release rather than theemulator traps.
Interrupts
The emulator supports only interrupt mode 1. It will complain if yourprogram enables interrupts after powerup without executing an IM 1instruction first. All Model I/III/4/4P software does this, as thebuilt-in peripherals in these machines supported only IM 1.
The Model I has a 40 Hz heartbeat clock interrupt, while the ModelIII used 30 Hz, and the Model 4/4P could run at either 30 Hz or 60 Hz.The emulator approximates this rather well even on a system whereclock ticks come at some frequency that isn't divisible by theemulated frequency (e.g., 100 Hz on Intel Linux), as long as the truefrequency is not slower than the emulated frequency. The emulator hasa notion of the absolute time at which each tick is supposed to occur,and it asks the host system to wake it up at each of those times. Thenet result is that some ticks may be late, but there are always theproper number of ticks per second. For example, running in Model Imode on Intel Linux you'd see this pattern: (tick, 30ms, tick,20ms,...) instead of seeing ticks every 25ms.
Sound
Crude sound support is available on Linux. Unfortunately, the Linuxsound drivers do not provide sufficiently low-level functionality, sothe emulator must write directly to the hardware. Thus in order forthe sound support to work, you must have a trueSoundBlaster-compatible sound card, and you must start
xtrs asroot. (If you make
xtrs setuid to root, it will disable itsroot privileges immediately after sound initialization.)
Sound support is off by default, but can be turned on with the -sboption described below. When sound support is on, any data written tothe TRS-80 cassette port when the cassette motor is off, and any datawritten to the Model 4/4P optional sound port, is copied to theSoundBlaster. TRS-80 sound depends on timing loops, so the pitcheswill be wildly wrong unless you use the -autodelay option describedbelow. Even with -autodelay, don't expect pitches to be accurate or stable.
Mouse
A few Model 4 programs could use a mouse, such as the shareware hi-resdrawing program MDRAW-II. The program XTRSMOUS/CMD on the utility disk(utility.dsk) is a mouse driver for Model 4/4P mode that should workwith most such programs.
xtrs does not emulate the actual mousehardware (a serial mouse plugged into the Model 4 RS-232 port), so theoriginal mouse drivers will not work under
xtrs. Instead,XTRSMOUS accesses the X mouse pointer using an emulator trap.XTRSMOUS implements the same TRSDOS/LS-DOS 6 SVC interface as theDavid Goben and Matthew Reed mouse drivers. (It does not implement theinterface of the older Scott McBurney mouse driver, which may berequired by some older programs.)
By default XTRSMOUS installs itself in high memory. This is donebecause MDRAW-II tests for the presence of a mouse bylooking to see whether the mouse SVC is vectored to high memory. If thedriver is installed in low memory, MDRAW thinks it is not there atall. If you use mouse-aware programs that don't have this bug, or ifyou edit the first line of MDRAW to remove the test, you can installXTRSMOUS in low memory using the syntax ``XTRSMOUS (LOW)''.
Running games
Some games run rather well under
xtrs now, provided that yourmachine is fast enough to run the emulation in real time and that youchoose the right command line options. Galaxy Invaders Plus by Big 5 Software is particularly good.You will usually want to turn on sound support and autodelay, andyou'll often need to tweak the keystretch setting. Running your X server in 8-bit/pixel mode also seems to help. Sample command lines:
startx -- -bpp 8 xtrs -sb 0x220,60 -keystretch 2,1,2 -autodelay
If the keyboard seems to miss keystrokes entirely, you may need toincrease the first number in the keystretch setting. If you get anunwanted type-ahead effect, where keys that you hit after one screenis finished show up on the next screen, try reducing the first number,and set the last number equal to the first number.See -keystretch below for more information. This aspect of theemulator seems to need a bit more work.
Options
Defaults for all options can be specified using the standard X resourcemechanism, and the class name for
xtrs is ``Xtrs''.
- -display display
- Set your X display to display. The default is touse the DISPLAY environment variable.
- -background color
- -bg color
- Specifies the background color of the xtrs window.
- -foreground color
- -fg color
- Specifies the foreground color of the xtrs window.
- -borderwidth width
- Put a border of width pixelsaround the TRS-80 display. The default is 2.
- -resize
- In Model 4/4P mode, resize the X window whenever the emulated displaymode changes between 64x16 and 80x24.
- -noresize
- In Model 4/4P mode, always keep the X window large enough for 80x24characters, putting a blank margin around the outside when the emulateddisplay mode is 64x16. This is the default.
- -charset name
- Select among several sets of built-in character bitmaps.
In Model I mode, four sets are available. The default, wider, isa modified Model III set with characters 8 pixels wide; it looksbetter on a modern computer screen with square pixels than the realModel I fonts, which were 6 pixels wide. lcmod is the characterset in the replacement character generator that was supplied with theRadio Shack lower case modification. (It was reconstructed partlyfrom memory and may have some minor bit errors.) stock is thecharacter set in the stock character generator supplied with mostupper case only machines. Since xtrs currently always emulatesthe extra bit of display memory needed to support lower case, thischaracter set gives you the authentic, unpleasant effect that realModel I users saw when they tried to do homebrew lower casemodifications without replacing the character generator: lower caseletters appear at an inconsistent height, and if you are using theLevel II BASIC ROM display driver, upper case letters are replaced bymeaningless symbols. Finally, early is the same as stock, butwith the standard ASCII characters [, \, ], and ^ in the positionswhere most Model I's had directional arrows. This was the defaultprogramming in the Motorola character generator ROM that Radio Shackused, and a few early machines were actually shipped with this ROM.
In Model III, 4, and 4P modes, three sets are available:katakana is an early set with Japanese Katakana characters inthe alternate character positions. international (the default) isa later set with accented Roman letters in the alternate positions.bold is a bold set from a character generator ROM found in oneModel III, origin uncertain.
- -usefont
- Use X fonts instead of the built-in character bitmaps.
- -nofont
- Use the built-in character bitmaps, not a X font. This is the default.
- -font fontname
- If -usefont is also given,use the specified X font for normal width characters.The default uses a common X fixed-width font:"-misc-fixed-medium-r-normal--20-200-75-75-*-100-iso8859-1".
- -widefont fontname
- If -usefont is also given,use the specified X font for double width characters.The default uses a common X fixed-width font, scaled to double width:"-misc-fixed-medium-r-normal--20-200-75-75-*-200-iso8859-1".
- -microlabs
- In Model 4/4P mode, emulate the Micro Labs Grafyx Solution hi-resgraphics card. This is the default.
- -nomicrolabs
- In Model 4/4P mode, emulate the Radio Shack hi-res card.
- -debug
- Enter zbx, the z80 debugger.
- -romfile filename
- -romfile3 filename3
- -romfile4p filename4p
- Use the romfile specified by filename in Model I mode, theromfile specified by filename3 in Model III and Model 4 mode,or the romfile specified by filename4p in Model 4P mode,A romfile can be either a raw binary dump, Intel hex format, orTRS-80 cmd format (for example, a modela/iii file).If you do not set this option or the corresponding X resource, a defaultestablished at compile time is used (if any); see Makefile.local forinstructions on compiling in default romfiles or default romfile names.
- -model m
- Specifies which TRS-80 model to emulate. Values accepted are 1 or I (ModelI), 3 or III (Model III), 4 or IV (Model 4), and 4P or IVP (Model 4P).Model I is the default.
- -delay d
- A crude speed control. After each Z-80 instruction, xtrs busy-waitsfor d iterations around an empty loop. A really smart C optimizermight delete this loop entirely, so it's possible that this optionwon't work if you compile xtrs with too high an optimization level.The default delay is 0.
- -autodelay
- Dynamically adjusts the value of -delay to run instructions at roughlythe same rate as a real machine. The tracking is only approximate,but it can be useful for running games and playing sounds.
- -autodelay
- Turn off -autodelay. This is the default.
- -keystretch amount,poll,heartbeat
- Fine-tune the keyboard behavior. To prevent keystrokes from beinglost, xtrs ``stretches'' the intervals between key transitions, so thatthe Z-80 program has time to see each transition before the next oneoccurs. Whenever an emulated key goes up or down, xtrs sets a counterto amount. While the counter is greater than zero, (1) anyfurther key transitions are held in a queue instead of being passedimmediately to the Z-80, (2) whenever the Z-80 program reads from thekeyboard matrix, the counter is decremented by poll, and (3)whenever a TRS-80 heartbeat interrupt is scheduled to occur (even ifinterrupts are disabled), the counter is decremented byheartbeat. The default setting is ``16,1,1''; this seems to workwell with ordinary keyboard drivers, but you may want to experimentwith different values for games if keyboard response seem sluggish.
- -doubler type
- Specify what type of double density adaptor to emulate (Model I mode only).The type may be percom, radioshack (or tandy),both, or none. The type may be abbreviated to one character.The default is both, which causes the double density adaptor emulationto respond to the special commands of both the Percom and Radio Shack cards.
- -doublestep
- Make all real floppy drives double-step, allowing access to 35-track or40-track media in an 80-track drive. Linux only. See the Floppy Diskssection for limitations.
- -nodoublestep
- Turn off double-step mode for all real floppy drives. Linux only. This is the default.
- -stepmap s0,s1,s2,s3,s4,s5,s6,s7
- Selectively set double-step mode for individual real floppy drives.If sU is 2 and diskM-U is a real drive, the drive willbe double-stepped; if sU is 1, it will be single-stepped.You can omit values from the end of the list; those drives will get thedefault value set by -doublestep or -nodoublestep.
- -sizemap z0,z1,z2,z3,z4,z5,z6,z7
- Selectively set whether drives are emulated as 5-inch or 8-inch; seethe section ``Emulated 8-inch floppy disks'' above. If zU is 5,the drive will appear to Z-80 software as 5-inch; if 8, as 8-inch.The default setting (as reflected in the documentation above) is5,5,5,5,8,8,8,8. You can omit values from the end of the list; thosedrives will get the default values. Setting one or more of the firstfour drives to 8-inch may be useful for CP/M software that supports8-inch drives. You can also use XTRS8/DCT with 8-inch drives in thefirst four positions; even though the prompt suggests the unit numbermust be 4-7, numbers 0-3 are accepted. XTRS8 does not check whetherthe unit you've selected is really being emulated as an 8-inch drive,however; you'll simply get errors during FORMAT if you get this wrong.
- -sb portbase,vol
- Enable sound support, using a SoundBlaster with I/O port base at portbase, and playing sounds at vol percent of maximumvolume. A typical setting would be -sb 0x220,30.
Additional resources
There are many other TRS-80 resources available on the Web, includingshareware and freeware emulators that run under MSDOS and otheroperating systems, software for converting TRS-80 physical media tothe emulator's disk file format, ROM images, and TRS-80 software thathas already been converted. For pointers, see
http://www.research.digital.com/SRC/personal/Tim_Mann/trs80.html. Bugs and limitations
Some of the more bizarre undocumented Z-80 instructionsare not implemented.
Cassette emulation works only in Model I mode, and only for programsthat use the Level II ROM routines to access the cassette; theemulator looks for access to the cassette port from specific PC valuesto activate the feature. If someone wants to disassemble the ModelIII ROM and figure out what PC values to look for, cassette emulationcould be made to work there too.
Serial ports are not emulated.
Some features of the disk controller are not currently emulated: ForceInterrupt with condition bits 0x01, 0x02, or 0x04 is notimplemented. Read Track is not implemented. The multiple-sector flagsin Read and Write are not implemented. Certain errors (such as LostData) cannot occur, which makes disk diagnostic programs that try togenerate them on purpose unhappy.
Real physical floppy disks are supported only under Linux, becauseUnix does not provide a portable interface to the low-level floppycontroller functionality that xtrs needs. There are somelimitations even under Linux: Index holes are faked, not detected onthe real disk. Attempts to access a real drive with no disk in it aredealt with awkwardly (as documented above). Due to a limitation ofPC-style floppy disk controllers, xtrs does not support mixingsectors of different sizes on the same track when formatting a realfloppy. However, xtrs can read and write to such floppies ifthey are already formatted (perhaps by a real TRS-80).
The emulator arbitrarily limits both JV1 and JV3 disk images to 96tracks. The limit could easily be increased to 255, butthat would probably not be useful with existing TRS-80 operatingsystems, which don't expect floppies to have so many tracks. Forexample, LDOS 5.3.1 allows at most 95 tracks on a floppy, though itallows more on hard drives. 255 tracks is an absolute maximum for theTRS-80 floppy disk controller and for the JV3 format.
The extended JV3 limit of 5802 sectors is somewhat arbitrary as well.It could be raised by generalizing the code to permit more than twoblocks of 2901. Again, this does not seem too useful. 5802 sectorsis already enough for a 3.5-inch HD (1.44MB) floppy, which the TRS-80 didn'tsupport anyway.
The emulator uses a heuristic to decide what format a ROM file is in.If a raw binary ROM image starts with 0x01, 0x05, or 0x22, it can bemisidentified as being in a different format. This is rather unlikelyto occur, as ROMs typically begin with 0xF3, the DI instruction.
If you discover other bugs, or write fixes for any of these, please letus know. We expect to incorporate fixes into future releases.
Authors and acknowledgements
xtrs was written by David Gingold <gingoldAATTthink.com> ofThinking Machines Corporation, Alec Wolman <wolmanAATTcrl.dec.com> ofDigital Equipment Corporation, and Timothy Mann <mannAATTpa.dec.com> ofDigital Equipment Corporation. See README and README.tpm foradditional notes from the authors.
We also thank the following people for their help. The floppy diskfile formats were designed by Jeff Vavasour, originally for hisMSDOS-based TRS-80 emulators. The hard disk file format was designedby Matthew Reed for his MSDOS-based TRS-80 emulators. Al Petrofskyand Todd P. Cromwell III supplied font data. Roland Gerlachcontributed the CP/M import and export programs as well as several bugreports and fixes for the emulator itself. Fabio Ferrari contributedthe sound support. Ulrich Mueller added the -borderwidth option andported the import, export, and settime utilities to Newdos/80.Branden Robinson supplied the cassette man page and fixed Makefilebugs. Mark McDougall provided documentation for the Micro Labs GrafyxSolution card.
Index
- Name
- Syntax
- Description
- Keys
- Emulated cassette
- Printer
- Emulated floppy disks
- Emulated 8-inch floppy disks
- Real floppy disks
- Emulated hard disks
- Data import and export
- Interrupts
- Sound
- Mouse
- Running games
- Options
- Additional resources
- Bugs and limitations
- Authors and acknowledgements
This document was created byman2html,using the manual pages.
