.\" This man page attempts to follow the conventions and recommendations found
.\" in Michael Kerrisk's man-pages(7) and GNU's groff_man(7), and groff(7).
.\"
.\" The following macro definitions come from groff's an-ext.tmac.
.\"
.\" Copyright (C) 2007-2014  Free Software Foundation, Inc.
.\"
.\" Written by Eric S. Raymond <esr@thyrsus.com>
.\"            Werner Lemberg <wl@gnu.org>
.\"
.\" You may freely use, modify and/or distribute this file.
.\"
.\" If _not_ GNU roff, define macros to handle synopsis and URLs.
.if !\n[.g] \{\
.\" Declare start of command synopsis.  Sets up hanging indentation.
.de SY
.  ie !\\n(mS \{\
.    nh
.    nr mS 1
.    nr mA \\n(.j
.    ad l
.    nr mI \\n(.i
.  \}
.  el \{\
.    br
.    ns
.  \}
.
.  nr mT \w'\fB\\$1\fP\ '
.  HP \\n(mTu
.  B "\\$1"
..
.
.
.\" End of command synopsis.  Restores adjustment.
.de YS
.  in \\n(mIu
.  ad \\n(mA
.  hy \\n(HY
.  nr mS 0
..
.
.
.\" Declare optional option.
.de OP
.  ie \\n(.$-1 \
.    RI "[\fB\\$1\fP" "\ \\$2" "]"
.  el \
.    RB "[" "\\$1" "]"
..
.
.
.\" Start URL.
.de UR
.  ds m1 \\$1\"
.  nh
.  if \\n(mH \{\
.    \" Start diversion in a new environment.
.    do ev URL-div
.    do di URL-div
.  \}
..
.
.
.\" End URL.
.de UE
.  ie \\n(mH \{\
.    br
.    di
.    ev
.
.    \" Has there been one or more input lines for the link text?
.    ie \\n(dn \{\
.      do HTML-NS "<a href=""\\*(m1"">"
.      \" Yes, strip off final newline of diversion and emit it.
.      do chop URL-div
.      do URL-div
\c
.      do HTML-NS </a>
.    \}
.    el \
.      do HTML-NS "<a href=""\\*(m1"">\\*(m1</a>"
\&\\$*\"
.  \}
.  el \
\\*(la\\*(m1\\*(ra\\$*\"
.
.  hy \\n(HY
..
.
.
.\" Start example.
.de EX
.  do ds mF \\n[.fam]
.  nr mE \\n(.f
.  nf
.  nh
.  do fam C
.  ft CW
..
.
.
.\" End example.
.de EE
.  do fam \\*(mF
.  ft \\n(mE
.  fi
.  hy \\n(HY
..
.
.
.\" Continuation line for .TP header.
.de TQ
.  br
.  ns
.  TP \\$1\" no doublequotes around argument!
..
.\} \" not GNU roff
.\" Copyright 1997 Timothy Mann
.\"
.\" This software may be copied, modified, and used for any purpose
.\" without fee, provided that (1) the above copyright notice is
.\" retained, and (2) modified versions are clearly marked as having
.\" been modified, with the modifier's name and the date included.
.\"
.\" Define macros for frequent references to floppy drive sizes requiring
.\" fractional units, because the standard character escapes for common
.\" ("vulgar") fractions degrade to ASCII poorly in context (e.g., 5\(14 renders
.\" as "51/4" in xtrs.txt).
.\"
.\" Usage note: These macros do _not_ have an ending word break; this is so that
.\" the "-inch" suffix can be appended where desired.  If you require a word
.\" break, the correct *roff way to get one is to put a single word space on a
.\" line by itself after the macro call.
.\"
.\" BEGIN EXAMPLE
.\" The drive can be eight inches or
.\" .5-1/4
.\"  \" ordinary space character (paddable by *roff)
.\" inches.
.\" END EXAMPLE
.de 3-1/2
3\c
.  ie '\*(.T'ascii' \&.5\c
.  el \(12\c
..
.de 5-1/4
5\c
.  ie '\*(.T'ascii' \&.25\c
.  el \(14\c
..
.\" Define macros to handle the GENIE's non-ASCII keycaps.
.de ess-tsett
.  ie '\*(.T'ascii' ess-tsett
.  el \(ss
..
.de umlaut
.  ie '\*(.T'ascii' umlaut
.  el \(ad
..
.\" The bold italic font is not accessible via the man macro package.
.de BOLD-ITALIC
.  ie d an-trap \
.    ie F BI \{\
.      itc 1 an-trap
.      ft BI
.      if \\n[.$] \&\\$*
.    \}
.    el \&\\$*
.  el \&\\$*
..
.TH xtrs 1 2017-04-16 xtrs
.\" Redefine TP macro to let us use \c and font-changing macros so we can have
.\" more than two fonts in a tagged paragraph's tag without using ugly font
.\" escapes.  (This was committed to groff upstream on 2017-04-28. --branden)
.\" This definition MUST follow TH because of the way groff's andoc.tmac works.
.if \n[.g] \{\
.de1 TP
.  sp \\n[PD]u
.  if \\n[.$] .nr an-prevailing-indent (n;\\$1)
.  itc 1 an-trap
.  in 0
.  if !\\n[an-div?] \{\
.    ll -\\n[an-margin]u
.    di an-div
.  \}
.  nr an-div? 1
.. \}
.SH Name
.B xtrs
\- TRS-80 Model I/III/4/4P emulator for the X Window System
.SH Synopsis
.SY xtrs
.OP \-model m
.OP \-diskdir d
.OP \-debug
.RI [ other-options ]
.YS
.SH Description
.B 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.
.PP
.B 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
.I .wav
files.
Game sound and music output are also supported if you have an OSS-compatible
sound driver; sound output though 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.
.PP
Because
.B xtrs
emulates the hardware, all known TRS-80 Model I/III/4/4P operating systems
should run on it, including all flavors of
.IR TRSDOS ,
.IR LDOS/LS-DOS ,
.IR NEWDOS ,
.IR DOSPLUS ,
.IR MultiDOS ,
and
TRS-80
.IR 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.
.PP
The Z80 emulator has a debugger called
.IR zbx .
You can enter the debugger either by starting
.B xtrs
with the
.B \-debug
flag or by pressing
.B F9
while
.B xtrs
is running.
The debugger runs in the X terminal window that you started
.B xtrs
from.
Once you are in the debugger, type
.if "\*(.T"ascii" "\c
.B help\c
.ie "\*(.T"ascii" "
 \" ordinary paddable space
for more information.
.PP
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.
.SS Keys
The following keys on the host keyboard have special meanings to
.BR xtrs .
.PP
.B F11
toggles onscreen help on the keyboard mappings.
.PP
.BR LeftArrow ,
.BR Backspace ,
or
.B Delete
is the TRS-80 left arrow key.
.B RightArrow
or
.B Tab
is the right arrow key.
.B UpArrow
is the up arrow key.
.B DownArrow
or
.B Linefeed
is the down arrow key.
.B Esc
or
.B Break
is the Break key.
.BR Home
or
.BR Clear
is the Clear key.
.B Control
is the Model 4 Ctrl key (address bit 7, data bit 2).
.B F12
is equivalent to the shifted down arrow key (used as a control key with some
TRS-80 software).
.PP
.BR F1 ,
.BR F2 ,
and
.B F3
are the Model 4/4P function keys (address bit 7, data bits 4, 5, and 6).
.B F1
is also the Model I Electric Pencil control key that some users added to their
machines.
.B F4
is the Model 4 Caps Lock key (address bit 7, data bit 3).
.BR F5 ,
.BR Compose ,
or
.B ScrollLock
is equivalent to the @ key (so that @ can be used as a modifier key).
.B F6
is equivalent to the 0 key (so that a shifted 0 can be obtained).
.B F7
signals a floppy disk change (see
.BR "Emulated floppy disks" ,
below).
.B F8
exits the program.
.B F9
enters the
.I zbx
debugger.
.B F10
is the reset button.
.PP
In Model III, 4, and 4P modes, the left and right
.B Shift
keys are distinct; in Model I mode, they are the same.
The
.B PageUp
and
.B 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
.B End
key activates an unused position in the keyboard matrix (address bit 7, data bit
7).
.PP
The keys
.BR [ ,
.BR \(rs ,
.BR ] ,
.BR \(ha ,
and
.B _
also activate unused positions
in the keyboard matrix (address bit 3, data bits 3\(en7), as do the
ASCII-shifted counterparts of the first four
.RB ( { ,
.BR | ,
.BR } ,
and
.BR \(ti );
see above regarding
.BR 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
.B [
but \(lq{\(rq is displayed instead, see
.B \-shiftbracket
and
.B \-noshiftbracket
in
.BR Options ,
below, to correct the problem.
The
.B 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).
.PP
On a German keyboard, the
.B
.umlaut
and
.B
.ess-tsett
keys should activate the corresponding characters used in the GENIE, a German
Model I clone.
This feature is most useful together with the
.B \-charset genie
command-line option.
.PP
Pressing a key on a PC-style keyboard's numeric keypad with
.B NumLock
disengaged emulates the Alpha Products joystick.
Keys 2, 4, 6, and 8
.RB ( KP_Down ,
.BR KP_Left ,
.BR KP_Right ,
and
.BR KP_Up )
are the main directions;
keys 1, 3, 7, and 9
.RB ( KP_End ,
.BR KP_Page_Down ,
.BR KP_Home ,
.BR KP_Page_Up )
work as diagonal directions by activating two main directions at once; and key 0
.RB ( KP_Insert )
or 5
.RB ( 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
.B NumLock
is not active.
If you have this problem, you can use
.BR 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
.BR xmodmap (1)
to remap your numeric pad.
.SS Emulated cassette
To control the emulated cassette, a file called
.I .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
.BR 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
.B cassette
man page has more information about the shell script and the cassette file
formats that are supported.
.SS 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.
.SS Emulated floppy disks
In Model I mode,
.B 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\(emit responds to the special commands of both\(emso a driver for
either should work.
Under
.IR LDOS
use the command
.I FDUBL
(on newer versions of
.IR LDOS ),
or
.I PDUBL
or
.I RDUBL
(on older versions) to install the driver.
Software that tries to detect which doubler you have (such as
.IR "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
.B Options
below.
.PP
In Model III, 4, or 4P mode,
.B xtrs
emulates the stock floppy controller, which uses a WD1793 chip
(software-compatible with the WD1791) to provide both single and double density.
.PP
Four
.5-1/4
-inch floppy drives are emulated, with storage in files named
.IR disk M \- U,
where
.I M
is the TRS-80 model
.RB ( 1 ,
.BR 3 ,
.BR 4 ,
or
.BR 4p )
and
.I U
is the
drive unit number
.RB ( 0 ,
.BR 1 ,
.BR 2 ,
or
.BR 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
.BR 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
.B F7
(see
.BR Keys,
above).
.PP
If you try to boot an emulated Model I, III, or 4 with no file named
.IR disk M \-0
(that is, no disk in drive 0),
.B 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
.B xtrs
always emulates one.
.PP
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.
.PP
Emulated floppy image files can be of any of three types: JV1, compatible with
Jeff Vavasour's popular freeware Model I emulator for
.IR 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
.B 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.
.PP
JV1 supports only single-sided, single-density diskettes, with directory on
track 17.
Sectors must be 256 bytes long.
Use
.B FORMAT (DIR=17)
if you want to format JV1 disks with more (or less) than 35 tracks under
.IR LDOS .
.PP
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
.I can
format a sector with an intentional CRC error in the data field.
.B xtrs
supports at most 5802 total sectors on a JV3 image.
.PP
The original Vavasour JV3 format supported only 256-byte sectors, and had a
limit of 2901 total sectors.
If you use sector sizes other than 256 bytes or format more than 2901 sectors on
a disk image, emulators other than
.B xtrs
may be unable to read it.
Note that an 80 track, double-sided, double-density (18 sector)
.5-1/4
-inch floppy
will fit within the original 2901 sector limit; the extension to 5802 is
primarily for emulation of 8-inch drives (discussed below).
.PP
The DMK format is the most flexible.
It supports essentially everything that the original hardware could do,
including all \(lqprotected\(rq disk formats.
However, a few protected disks still may
not work with
.B xtrs
due to limitations in
.BR xtrs 's
floppy disk controller emulation rather than limitations of the DMK format; see
.BR "Bugs and limitations" ,
below.
.PP
The program
.BR mkdisk (1)
makes a blank emulated floppy or \(lqbulk erases\(rq an existing one.
By default,
.B mkdisk
makes a JV3 floppy, but with the
.B \-1
flag it makes a JV1 floppy, or with the
.B \-k
flag a DMK
floppy.
See the
.B mkdisk
man page for more information.
.PP
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 would accept
either upon reading.
The change was needed because 0xFA is a nonstandard DAM that is fully supported
only by the WD1771 floppy disk controller used in the Model I; the controllers
in the Model III and 4 cannot distinguish between 0xFA and 0xFB (which is used
for non-directory sectors) upon reading, and cannot write 0xFA.
To deal nicely with this problem,
.B 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 (available in Model I mode only), 0xFA is
returned as 0xFA; on reading with a
.RI WD179 x ,
0xFA is returned as 0xF8.
This trick makes the different operating systems perfectly compatible with each
other, which is better than on a real Model I!
You can use the
.B \-truedam
flag to turn off this kludge if you need to; in that case the original hardware
is emulated exactly.
.PP
TRS-80 programs that attempt to measure the rotational speed of their floppy
disk drives using timing loops will get the answers they expect, even when
.B xtrs
does not emulate instructions at the same speed as the original machines.
This works because
.B xtrs
keeps a virtual clock (technically, a T-state counter), which 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 this clock, not to real
time.
.SS Emulated 8-inch floppy disks
In addition to the four standard
.5-1/4
-inch drives,
.B xtrs
also emulates four 8-inch floppy drives.
There is no widely-accepted standard hardware interface for 8-inch floppies on
the TRS-80, so
.B xtrs
emulates a pseudo-hardware interface of its own and provides an
.IR LDOS / LS-DOS
driver for it.
.PP
Storage for the emulated 8-inch disks is in files named
.IR disk M \- U,
where
.I M
is the TRS-80 model
.RB ( 1 ,
.BR 3 ,
.BR 4 ,
or
.BR 4p )
and
.I U
is the
drive unit number
.RB ( 4 ,
.BR 5 ,
.BR 6 ,
or
.BR 7 ).
The only difference between
.5-1/4
-inch and 8-inch emulated drives is that the emulator allows you to format more
bytes per track in the latter.
A new JV3 floppy can be formatted as either
.5-1/4
-inch or 8-inch depending on whether you initially put it into a
.5-1/4
-inch or 8-inch emulated drive.
A new DMK floppy, however, must be created with the
.B \-8
flag to
.B mkdisk
in order to be large enough for use in an 8-inch emulated drive.
JV1 floppies cannot be used in 8-inch drives.
Be careful not to put an emulated floppy into a
.5-1/4
-inch emulated drive after it has 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,
.I .dsk
for
.5-1/4
-inch and
.I .8in
for 8-inch.
.PP
To use the emulated 8-inch drives, you'll need a driver.
Under
.I LDOS
or
.IR LS-DOS ,
use the program
.I XTRS8/DCT
supplied on the emulated floppy
.IR utility.dsk .
This driver is a very simple wrapper around the native
.IR LDOS / LS-DOS
floppy driver.
Here are detailed instructions.
.PP
First, make sure an appropriate version of
.I LDOS
is in emulated floppy drive 0, and the supplied file
.I utility.dsk
is in another emulated floppy drive.
Boot
.IR LDOS .
If you are using Model I
.IR LDOS ,
be sure
.I FDUBL
is running.
.PP
Second, type the following commands.
Here
.I d
is the
.I LDOS
drive
number you want to use for the 8-inch drive and
.I u
is the unit number you chose when naming the file.
Most likely you will choose
.I d
and
.I u
to be equal to reduce confusion.
.RS
.EX
.B SYSTEM (DRIVE=\c
.BOLD-ITALIC d\c
.B ,DRIVER="XTRS8",ENABLE)
Enter unit number ([4]-7): \c
.BOLD-ITALIC u
.EE
.RE
You can repeat these steps with different values of
.I d
and
.I u
to have more than one 8-inch drive.
You might want to repeat four times using
.BR 4 ,
.BR 5 ,
.BR 6 ,
and
.BR 7 ,
or you might want to save some drive numbers for hard drives (see below).
.PP
Finally, it's a good idea to give the
.I SYSTEM (SYSGEN)
command (Model I/III) or
.I SYSGEN
command (Model 4/4P).
This command saves the
.I SYSTEM
settings, so the 8-inch drives will be available again the next time you reboot
or restart the emulator.
If you need to access an 8-inch drive after booting from a disk that hasn't been
.IR SYSGEN ed,
simply use the same
.I SYSTEM
command again.
.PP
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-1/4
-inch drives.
The four
.5-1/4
-inch drives have hardware select codes
1, 2, 4, and 8, corresponding respectively to files
.IR disk M \-0,
.IR \-1 ,
.IR \-2 ,
and
.IR \-3 .
The four 8-inch drives have hardware select codes 3, 5, 6, and 7, corresponding
respectively to files
.IR disk M \-4,
.IR \-5 ,
.IR \-6 ,
and
.IR \-7 .
(See also the
.B \-sizemap
option below, however.)
.SS Real floppy disks
Under Linux only, any
.IR disk M \- U
file can be a symbolic link to a real floppy disk drive, typically
.I /dev/fd0
or
.IR /dev/fd1 .
.\" XXX: Modern PC-compatibles with support fort legacy peripherals are getting
.\" scarce.  Has anyone tried these tricks with a USB floppy drive?
Most machines with \(lqlegacy\(rq (ISA bus) floppy drive support should be able
to read and write TRS-80-compatible floppies in this way.
Many floppy controllers cannot handle single density, however, 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
.B \-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.
.PP
If you link one of the
.5-1/4
-inch floppy files
.RI ( disk M \-0
through
.IR disk M \-3 )
to a real floppy drive, TRS-80 programs will see it as a
.5-1/4
-inch drive, but the actual drive can be either
.3-1/2
-inch or
.5-1/4
-inch.
The drive will be operated in double density (or single density), not high
density, so be sure to use the appropriate media.
.PP
If you link one of the 8-inch floppy files
.RI ( disk M \-4
through
.IR disk M \-7 )
to a real floppy drive, TRS-80 programs will see it as an 8-inch drive.
Again, you need to use the
.I XTRS8/DCT
driver described above to enable
.IR LDOS / LS-DOS
to access an 8-inch drive.
The real drive can be either
.3-1/2
-inch,
.5-1/4
-inch,
or 8-inch.
A
.3-1/2
-inch or
.5-1/4
-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-1/4
-inch HD drive holds exactly the same number of bits per track as an 8-inch
drive; a
.3-1/2
-inch HD drive can hold 20% more, but we waste that space when using one to
emulate an 8-inch drive.
In both cases we also waste the top three tracks, since an 8-inch drive has only
77 tracks, not 80.
.PP
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.
A ISA-bus floppy disk controller can neither read nor write sectors with such
DAMs at all.
This raises three issues.
.IP 1.
It will be impossible for you to read some Model I disks on your machine even if
it otherwise supports single density.
In particular, Model I
.I TRSDOS
2.3 directory tracks will be unreadable.
.IP 2.
On writing in
single density,
.B xtrs
silently records a 0xF9 or 0xFA DAM as 0xF8.
.IP 3.
On reading in single density with an emulated WD1771 (Model I mode only), 0xF8
is returned as 0xFA.
If you need more accurate behavior, the
.B \-truedam
flag will turn on error messages on attempts to write 0xF9 or 0xFA DAMs and will
turn off translation of 0xF8 to 0xFA on reading.
.PP
.I Hint:
Be sure to set the drive type correctly in your machine's firmware.
Linux and
.B
xtrs
rely on this information to know how fast your drives are spinning and hence
what data rate to use when reading and writing.
All
.3-1/2
-inch drives spin at 300 rpm.
Newer
.5-1/4
-inch high-density capable drives (\(lq1.2MB\(rq drives) normally always spin at
360 rpm.
(Some can be jumpered to slow down to 300 rpm when in double-density mode, but
you should not do that when connecting one to a floppy disk controller designed
for ISA-bus machines.
Older
.5-1/4
-inch drives that cannot do high density (\(lq180kB\(rq, \(lq360kB\(rq, or
\(lq720kB\(rq
.5-1/4
-inch drives) always spin at 300 rpm.
All 8-inch drives spin at 360 rpm.
If you plug an 8-inch drive into an ISA-bus floppy disk controller\(emthis
requires a 50-pin to 34-pin adaptor cable\(emtell your firmware that it is a
.5-1/4
-inch 1.2MiB drive.
.SS Emulated hard disks
.B xtrs
can emulate a hard disk in a file in one of two ways: it
can use a special,
.BR xtrs -specific
.I LDOS
driver called
.IR XTRSHARD/DCT ,
or it can emulate the Radio Shack hard drive controller (based on the Western
Digital WD1010) and use the native drivers for the original hardware.
.TP
.B Using \c
.BOLD-ITALIC XTRSHARD/DCT
The
.I XTRSHARD/DCT
driver has been tested and works under both
.I LDOS
5.3.1 for Model I or III and
.IR TRSDOS / LS-DOS
6.3.1 for Model 4/4P.
It may or may not work under earlier
.I LDOS
versions.
It definitely will not work under other TRS-80 operating systems or with
emulators other than
.BR xtrs .
The hard disk format was designed by Matthew Reed for his Model I/III and Model
4 emulators;
.B xtrs
duplicates the format so that users can exchange hard drive images across the
emulators.
.IP
To use
.IR XTRSHARD/DCT ,
first run the
.BR mkdisk (1)
program to create a blank hard drive
.RI ( .hdv )
file.
A typical usage
would be
.BR "mkdisk -h myhd.hdv" .
See the
.B mkdisk
man page for other options.
.IP
Second, link the file to an appropriate name.
.I XTRSHARD/DCT
supports up
to eight hard drives, with names of the form
.IR hard M \- U,
where
.I M
is the TRS-80 model
.RB ( 1 ,
.BR 3 ,
or
.BR 4 ;
in this case the Model 4P also uses
.IR M =4)
and
.I U
is a unit number in the range 0\(en7.
It looks for these files in the same directory as the floppy disk files
.IR disk M \- U.
.IP
Third, make sure an appropriate version of
.I LDOS
is in emulated floppy drive 0, and the supplied file
.I utility.dsk
is in another emulated floppy drive.
Boot
.IR LDOS .
If you are using Model I
.I LDOS
5.3.1, patch a bug in the
.I FORMAT
command by typing
.BR "PATCH FORMAT/CMD.UTILITY M1FORMAT/FIX" .
You need to apply this patch only once.
It must not be applied to Model III or Model 4/4P
.IR LDOS .
.IP
Fourth, type the following commands.
Here
.I d
is the
.I LDOS
drive number you want to use for the hard drive (a typical choice would be
.BR 4 )
and
.I u
is the unit number you chose when naming the file (most likely
.BR 0 ).
.\" XXX: The following ugliness is due to the fact that the .RS/.RE macros don't
.\" indent further within an .IP environment within an .SS environment.  Kludge
.\" around this by using low-level requests to manually indent.
.ie t .in +7n
.el   .in +7.2n
.EX
.B SYSTEM (DRIVE=\c
.BOLD-ITALIC d\c
.B ,DRIVER="XTRSHARD",ENABLE)
Enter unit number ([0]-7): \c
.BOLD-ITALIC u
.B FORMAT \c
.BOLD-ITALIC d \c
.B (DIR=1)
.EE
.br
.ie t .in -7n
.el   .in -7.2n
Answer the questions asked by
.I FORMAT
as you prefer.
The
.B DIR=1
parameter to
.I FORMAT
is optional; it causes the hard drive's directory to be on track 1, making the
initial size of the image smaller.
You can repeat these steps with different values of
.I d
and
.I u
to have more than one hard drive.
.IP
Finally, it's a good idea to give the
.I SYSTEM (SYSGEN)
command (Model I/III) or
.I SYSGEN
command (Model 4/4P).
This command saves the
.I SYSTEM
settings, so the drive will be available again the next time you reboot or
restart the emulator.
.IP
If you need to access the hard disk file after booting from a floppy that hasn't
been
.IR SYSGEN ed,
simply use the same
.I SYSTEM
command(s) again, but don't
.IR FORMAT .
You can freely use a different drive number or (if you renamed the hard disk
file) a different unit number.
.IP
The
.B F7
key currently doesn't allow
.I XTRSHARD/DCT
disk changes to be recognized, but you can change to a different hard disk file
for the same unit by renaming files as needed and rebooting
.IR LDOS .
.IP
.I Technical note:
.I XTRSHARD/DCT
is a small Z80 program that implements all the required functions of an
.I LDOS
disk driver.
Instead of talking to a real (or emulated) hard disk controller, however, it
uses special support in
.B xtrs
that allows Z80 programs to open, close, read, and write Unix files directly.
This support is described further in
.BR "Data import and export" ,
below.
.TP
.B Using native hard disk drivers
Beginning in version 4.1,
.B xtrs
also emulates the Radio Shack hard disk controller (based on the Western Digital
WD1010) and will work with the native drivers for this hardware.
This emulation uses the same hard drive
.RI ( .hdv )
file format that
.I XTRSHARD/DCT
does.
With
.IR LDOS / LS-DOS ,
the
.IR RSHARD x /DCT
and
.I TRSHD/DCT
drivers are known to work.
With Montezuma
.I CP/M
2.2, the optional Montezuma hard disk drivers are known to work.
The hard disk drivers for
.I NEWDOS/80
and for Radio Shack
.I CP/M
3.0 should work, but they have not yet been tested at this writing.
Any bugs should be reported.
.IP
To get started, run the
.BR mkdisk (1)
program to create a blank hard drive
.RI ( .hdv )
file.
A typical usage
would be
.BR "mkdisk -h myhd.hdv" .
See the
.B mkdisk
man page for other options.
.IP
Second, link the file to an appropriate name.
The WD1010 emulation supports up to four hard drives, with names of the form
.IR hard M \- U,
where
.I M
is the TRS-80 model
.RB ( 1 ,
.BR 3 ,
.BR 4 ,
or
.BR 4p )
and
.I U
is a unit number in the range 0\(en3.
It looks for these files in the same directory as the floppy disk files
.IR disk M \- U.
If no such files are present,
.B xtrs
disables the WD1010 emulation.
.IP
Note that if hard drive unit 0 is present on a Model 4P (file
.IR hard4p-0 ),
the Radio Shack boot ROM will always try to boot from it, even if the operating
system does not support booting from a hard drive.
If you have this problem, either hold down
.B F2
while booting to force the ROM to boot from floppy, or simply avoid using unit
number 0.
Stock
.IR TRSDOS / LS-DOS
6 systems do not support booting from a hard drive; M.A.D. Software's
.I HBUILD6
add-on to
.I LS-DOS
for hard drive booting should work, but is untested.
Montezuma
.I CP/M
2.2 does boot from the emulated hard drive.
.IP
Finally, obtain the correct driver for the operating system you will be using,
read its documentation, configure the driver, and format the drive.
Detailed instructions are beyond the scope of this manual page.
.SS Data import and export
Several Z80 programs for data import and export from various TRS-80 operating
systems are included with
.B xtrs
on two emulated floppy images.
These programs use special support in the emulator to read and write external
Unix files, discussed further at the end of this section.
.PP
The emulated floppy
.I utility.dsk
contains some programs for transferring data between the emulator and ordinary
Unix files.
.IR IMPORT/CMD ,
.IR EXPORT/CMD ,
and
.I SETTIME/CMD
run on
the emulator under Model I/III
.IR TRSDOS ,
Model I/III
.IR LDOS ,
Model I/III
.IR NEWDOS/80 ,
and Model 4/4P
.IR TRSDOS / LS-DOS
6; they may also work under other TRS-80 operating systems.
Model III
.I TRSDOS
users will have to
use
.IR TRSDOS 's
.I CONVERT
command to read
.IR utility.dsk .
.TP
.I IMPORT/CMD
imports a Unix file and writes it to an emulated disk.
.IP
Usage:
.B IMPORT
.RB [ \-lne ]
.I unixfile
.RI [ trsfile ]
.IP
The
.B \-n
flag converts
Unix newlines (\(rsn) to TRS-80 newlines (\(rsr).
The
.B \-l
flag converts the Unix filename to lowercase, to compensate for TRS-80
operating systems such as
.I NEWDOS/80
that convert all command-line arguments to uppercase.
When using the
.B \-l
flag, you can put a
.B [
or up-arrow in front of a character to keep it in uppercase.
Give the
.B \-e
flag if your TRS-80 operating system uses the
.I NEWDOS/80
convention for representing the ending record number in an open file control
block.
This should be detected automatically for
.I NEWDOS/80
itself and for
.I TRSDOS
1.3, but you'll need to give the flag for
.I DOSPLUS
and possibly
other
.RI non- LDOS
operating systems.
If you need the flag but don't give it (or vice versa), imported files will come
out the wrong length.
If the destination file is omitted,
.I IMPORT
uses the last component of the Unix pathname, but with any \(lq.\(rq changed to
\(lq/\(rq to match TRS-80 DOS file extension syntax.
.TP
.I EXPORT/CMD
reads a file from an emulated disk and exports it to a Unix file.
.IP
Usage:
.B EXPORT
.RB [ \-lne ]
.I trsfile
.RI [ unixfile ]
.IP
The
.B \-n
flag converts TRS-80 newlines (\(rsr) to Unix newlines (\(rsn).
The
.B \-l
flag converts the Unix filename to lowercase.
When using the
.B \-l
flag, you can put a
.B [
or up-arrow in front of a character to keep it in uppercase.
Give the
.B \-e
flag if your TRS-80 operating system uses the
.I NEWDOS/80
convention for representing the ending record number in an open file control
block.
This should be detected automatically for
.I NEWDOS/80
itself and for
.I TRSDOS
1.3, but you'll need to give the flag for
.I DOSPLUS
and possibly
other
.RI non- LDOS
operating systems.
If you need the flag but don't give it (or vice versa), imported files will come
out the wrong length.
If the destination file is omitted,
.I EXPORT
uses the TRS-80 filename, but with any \(lq/\(rq changed to \(lq.\(rq to match
Unix file extension syntax.
.IP
.I Note:
The export of files from
.B xtrs
may be prohibited by the
.B \-emtsafe
flag; see
.BR Options ,
below.
.TP
.I SETTIME/CMD
reads the date and time from Unix and sets the TRS-80 DOS's date and time
accordingly.
.PP
The next several programs were written in Misosys C and exist in two versions on
.IR utility.dsk .
The one whose name ends in \(lq6\(rq runs on Model 4
.IR TRSDOS / LS-DOS
.RI 6. x ;
the other runs on
.I LDOS
.RI 5. x
and most other Model I/III operating systems.
.TP
.I CD/CMD
(or
.IR CD6/CMD )
changes
.BR xtrs 's
current working directory under Unix.
.IP
Usage:
.B CD
.RB [ \-l ]
.I unixdir
.IP
The
.B \-l
flag converts the Unix directory name to lowercase.
When using the
.B \-l
flag, you can put a
.B [
or up-arrow in front of a character to keep it in uppercase.
Running
.I CD/CMD
will change the interpretation of any relative pathnames given to
.I IMPORT
or
.IR EXPORT .
It will also change the interpretation of disk names at the next disk change,
unless you specified an absolute pathname for
.BR xtrs 's
.B \-diskdir
parameter.
.IP
.I Note:
The change of
.BR xtrs 's
current working directory may be prohibited by the
.B \-emtsafe
flag; see
.BR Options ,
below.
.TP
.I PWD/CMD
(or
.IR PWD6/CMD )
prints
.BR xtrs 's
current working directory under Unix.
.TP
.I UNIX/CMD
(or
.IR UNIX6/CMD )
runs a Unix shell command.
.IP
Usage:
.B UNIX
.RB [ \-l ]
.I unix-command-line
.IP
The
.B \-l
flag converts the Unix command line to lowercase.
When using the
.B \-l
flag, you can put a
.B [
or up-arrow in front of a character to keep it in uppercase.
Standard I/O for
the command uses the
.B xtrs
program's standard I/O descriptors; it does not go to the TRS-80 screen or come
from the TRS-80 keyboard.
.IP
.I Note:
The execution of Unix shell commands may be prohibited by the
.B \-emtsafe
flag; see
.BR Options ,
below.
.TP
.I MOUNT/CMD
(or
.IR MOUNT6/CMD )
is a convenience program that switches emulated floppy disks in the drives.
.IP
Usage:
.B MOUNT
.RB [ \-l ]
.I unixfile unit-number
.IP
The
.B \-l
flag converts
.I unixfile
to lowercase.
When using the
.B \-l
flag, you can put a
.B [
or up-arrow in front of a character to keep it in uppercase.
.I unixfile
is any Unix filename;
.I unit-number
is a single digit, 0 through 7.
The command deletes the file
.IR disk M \- U
(where
.I M
is the TRS-80 model and
.I U
is the given
.IR unit-number )
from the disk directory (see the
.B \-diskdir
option below), replaces it with a symbolic link to the given filename, and
signals a disk change (as if
.B F7
had been pressed).
.IP
.I Note:
The mounting of a Unix file as a disk image may be prohibited by the
.B \-emtsafe
flag; see
.BR Options ,
below.
.TP
.I UMOUNT/CMD
(or
.IR UMOUNT6/CMD )
is a convenience program that removes an emulated floppy disk from a drive.
.IP
Usage:
.B UMOUNT
.I unit-number
.IP
.I unit-number
is a
single digit, 0 through 7.
The command deletes the file
.IR disk M \- U
(where
.I M
is the TRS-80 model and
.I U
is the given
.IR unit-number )
from the disk directory (see the
.B \-diskdir
option below), and signals a disk change (as if
.B F7
had been pressed).
.IP
.I Note:
The unmounting of a Unix file as a disk image by deleting it on the host may be
prohibited by the
.B \-emtsafe
flag; see
.BR Options ,
below.
.PP
The emulated floppy
.I cpmutil.dsk
contains import and export programs for Montezuma
.IR CP/M ,
written by Roland Gerlach.
It was formatted as a \(lqMontezuma Micro Standard DATA disk (40T, SS, DD,
200K)\(rq, with 512-byte sectors.
Be careful to configure your
.I CP/M
to the proper disk format and drive parameters (40 tracks, not 80), or you will
have confusing problems reading this disk.
Documentation is included in the file
.\" If outputting HTML, make the filename a clickable link.
.if '\*(.T'html' .UR file:///usr/share/doc/xtrs/cpmutil.html
.I cpmutil.html
.if '\*(.T'html' .UE
and source code in the file
.I cpmutil.tgz
(a gzipped tar archive) in the
.B xtrs
source distribution.
.\" Per the Internet Archive, Roland's site disappeared sometime between
.\" 2007-12-22 and 2015-05-20.
.\" See http://members.optusnet.com.au/~rgerlach/trs-80/cpmutil.html
.\" where you will sometimes find a newer version of the utilities
.\" than is included with xtrs.
.PP
The emulator implements a set of pseudo-instructions (emulator traps) that give
TRS-80 programs access to Unix files.
The programs listed above use them.
If you would like to write your own such programs, the traps are documented in
the file
.IR trs_imp_exp.h .
Assembler source code for the existing programs is supplied in
.IR xtrshard.z ,
.IR import.z ,
.IR export.z ,
and
.IR settime.z .
You can also write programs that use the traps in Misosys C, using the files
.I xtrsemt.h
and
.I xtrsemt.ccc
as an interface; a simple example is in
.IR settime.ccc .
All of these files are available in the
.B xtrs
source distribution.
.SS Interrupts
The emulator supports only interrupt mode 1 of the Z80.
It will complain if your program enables interrupts after powerup without
executing an IM 1 instruction first.
All Model I/III/4/4P software does this, as the built-in peripherals in these
machines support only IM 1.
The Model I has a 40 Hz heartbeat clock interrupt, while the Model III uses 30
Hz, and the Model 4/4P can run at either 30 Hz or 60 Hz.
.\" This discussion used to assume that HZ=100 on Intel Linux.  Much has changed
.\" since then.  In Linux 2.6.13, HZ changed to 250.  After that, the Linux
.\" kernel developed high-resolution timers and "tickless" behavior.
.\"
.\" Old language:
.\" The emulator approximates this rather well even on a system where clock
.\" ticks come at some frequency that isn't divisible by the emulated frequency
.\" (e.g., 100 Hz on Intel Linux), as long as the true frequency is not slower
.\" than the emulated frequency.
The emulator has a 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.
The net result is that some ticks may be late, but there are always the proper
number of ticks per second.
For example, running in Model I mode on a Linux kernel configured with HZ=100,
you'd see this pattern: (tick, 30ms, tick, 20ms, ...) instead of a tick every
25ms.
.SS Processor speed selection
A standard Model 4 has a software-controlled switch to select operation at
either 4.05504 MHz (with heartbeat clock at 60 Hz) or 2.02752 MHz (with
heartbeat clock at 30 Hz).
.B xtrs
emulates this feature.
.PP
Model I machines were often modified to operate at higher speeds than the
standard 1.77408 MHz.
With one common modification, writing a 1 to port 0xFE would double the speed to
3.54816 MHz, while writing a 0 would set the speed back to normal.
The heartbeat clock runs at 40 Hz in either case.
.B xtrs
emulates this feature as well.
.SS Sound
Sound support uses the Open Sound System (OSS)
.I /dev/dsp
device, standard on Linux and available on many other Unix versions as well.
This support is compiled in automatically on Linux; if you have OSS on another
version of Unix, you'll need to define the symbol
.B HAVE_OSS
in the source distribution's
.I Makefile
or in
.IR trs_cassette.c .
Any time TRS-80 software tries to write non-zero values to the cassette port (or
the Model 4/4P optional sound port) with the cassette motor off, it is assumed
to be trying to make sounds and
.B xtrs
opens
.IR /dev/dsp .
It automatically closes the device again after a few seconds of silence.
.PP
If you are playing a game with sound, you'll want to use the
.B \-autodelay
flag to slow down instruction emulation to approximately the speed of a real
TRS-80.
If you don't do this, sound will still play correctly, but the gameplay may be
way too fast and get ahead of the sound.
.PP
On the other hand, if your machine is a bit too slow, you'll hear gaps and pops
in the sound when the TRS-80 program lags behind the demand of the sound card
for more samples.
The
.B \-autodelay
feature includes a small speed boost whenever a sound starts to play to try to
prevent this, but if the boost is too much or too little, you might either find
that the game runs too fast when a lot of sound is playing, or that the sound
has gaps in it anyway.
If your sound has gaps, you can try reducing the sample rate with the
.B \-samplerate
flag.
.PP
The Orchestra-85 music synthesis software will run under
.BR xtrs 's
Model I emulation, and the Orchestra-90 software will run with Model III
operating systems under
.BR xtrs 's
Model III, 4, or 4P emulation.
For best results, use Orchestra-90 and the Model 4 emulation, as this lets the
software run at the highest emulated clock rate (4 MHz) and thus generate the
best sound.
If you want to run Orchestra-85 instead, you can tell it that you have a 3.5 MHz
clock speedup with enable sequence 3E01D3FE and disable sequence 3E00D3FE; this
will let the software run twice as fast as on an unmodified Model I and generate
better sound.
There is no need to use
.BR xtrs 's
.B \-autodelay
flag when running Orchestra-85/90, but you might want to specify a small fixed
delay to keep from getting excessive key repeat.
.SS Mouse
A few Model 4 programs could use a mouse, such as the shareware hi-res
drawing program
.IR MDRAW-II .
The program
.I XTRSMOUS/CMD
on the utility disk
.RI ( utility.dsk )
is a mouse driver for Model 4/4P mode that should work with most such programs.
.B xtrs
does not emulate the actual mouse hardware (a serial mouse plugged into the
Model 4 RS-232 port), so the original mouse drivers will not work under
.BR xtrs .
Instead,
.I XTRSMOUS
accesses the X mouse pointer using an emulator trap.
.I XTRSMOUS
implements the same
.IR TRSDOS / LS-DOS
6 SVC interface as the David Goben and Matthew Reed mouse drivers.
(It does not implement the interface of the older Scott McBurney mouse driver,
which may be required by some programs.)
.PP
By default
.I XTRSMOUS
installs itself in high memory.
This is done because
.I MDRAW-II
tests for the presence of a mouse by looking to see whether the mouse SVC is
vectored to high memory.
If the driver is installed in low memory,
.I MDRAW
thinks it is not there at all.
If you use mouse-aware programs that don't have this bug, or if you edit the
first line of
.I MDRAW
to remove the test, you can install
.I XTRSMOUS
in low memory under
.IR TRSDOS / LS-DOS
6 using the syntax
.BR "XTRSMOUS (LOW)" .
.SS Time-of-day clock
Several battery-backed time of day clocks were sold for the various TRS-80
models, including the TimeDate80, TChron1, TRSWatch, and T-Timer.
They are essentially all the same hardware, but reside at a few different port
ranges.
.B xtrs
currently emulates them at port ranges 0x70\(en0x7C and 0xB0\(en0xBC.
The T-Timer port range at 0xC0\(en0xCC conflicts with the Radio Shack hard drive
controller and is not emulated.
.PP
These clocks return only a 2-digit year, and it is not well-documented what
their driver software does since the year 2000.
If you have software that works with one of them, please contact the
.ie \n[.g] .UR http://\:www.tim-mann.org/
.el .UR http://www.tim-mann.org/
author
.UE
to report what happens when it is used with
.BR xtrs .
.PP
Also see
.I SETTIME/CMD
in
.BR "Data import and export" ,
above, for another way to get the correct time into a Z80 operating system
running under
.BR xtrs .
.PP
Note that Model I
.I TRSDOS
and
.I VTOS
4.0 have a \(lqyear 1988\(rq problem, and
.IR LDOS / LS-DOS
has a \(lqyear 2012\(rq problem; see
.\" If GNU roff, use hyphenless breakpoints.
.ie \n[.g] .UR http://\:www.trs-80.org/\
\:ldos-and-ls-dos-2012-and-beyond-technical-information/
.el .UR http://www.trs-80.org/\
ldos-and-ls-dos-2012-and-beyond-technical-information/
.I LDOS and LS-DOS: 2012 and Beyond \(em Technical information
.UE
by Matthew Reed.
.\" Finally, you might notice that LDOS/LS-DOS always magically knows the
.\" correct date when you boot it (but not the time).  When you first
.\" power up the emulated TRS-80, \fBxtrs\fP dumps the date into the
.\" places in memory where LDOS and LS-DOS normally save it across
.\" reboots, so it looks to the operating system as if you rebooted after
.\" setting the date.
.SS Joystick
Pressing a key on a PC-keyboard-style numeric keypad with
.B NumLock
disengaged emulates the Alpha Products joystick.
See
.BR Keys ,
above, for details.
The emulated joystick is mapped only at port 0, to avoid conflicts with other
devices.
.SS Running games
Some games run rather well under
.B xtrs
provided that your machine is fast enough to run the emulation in real time and
that you choose the right command-line options.
.I Galaxy Invaders Plus
by Big 5 Software is particularly good.
You will usually want to turn on autodelay, and if your machine is slow you may
need to reduce the sound sample rate.
Running your X server in 8-bit/pixel mode also seems to help in some cases.
Example command lines:
.RS
.EX
.RB "$ " "startx \-\- \-bpp 8"
.RB "$ " "xtrs \-autodelay"
.EE
.RE
.PP
If you have a slow machine and the sound breaks up, it is possible that your
machine is not fast enough to generate samples at the default rate of 44,100 Hz.
If you think this may be happening, try
.B \-samplerate 11025
or even
.BR "\-samplerate 8000" .
.SH Options
Defaults for all options can be specified using the standard X resource
mechanism; see the
.\" If GNU roff, use hyphenless breakpoints.
.ie \n[.g] .UR ftp://\:www.x.org/\:pub/\:current/\:doc/\:libX11/\:libX11/\
\:libX11.html#\:Resource_Manager_Functions
.el .UR ftp://www.x.org/pub/current/doc/libX11/libX11/libX11.html\
#Resource_Manager_Functions
Resource Manager Functions chapter of
.IR "Xlib \(em C Language X Interface"
.UE
by Jim Gettys, Robert W. Scheifler, et al.
The class name for
.B xtrs
is
.BR Xtrs .
.TP
.B \-display \c
.I x-display
Set your X display to
.IR x-display.
The default is to use the DISPLAY environment variable.
.TP
.B \-iconic
Start with the
.B xtrs
window iconified.
.TP
.B \-background \c
.I color
.TQ
.B \-bg \c
.I color
Set the background color of the
.B xtrs
window to
.IR color .
.TP
.B \-foreground \c
.I color
.TQ
.B \-fg \c
.I color
Set the foreground color of the
.B xtrs
window to
.IR color .
.TP
.B \-title \c
.I title-text
Use
.I title-text
in the window title bar instead of the program name.
.TP
.B \-borderwidth \c
.I width
Put a border of
.I width
pixels
around the TRS-80 display.
The default is 2.
.TP
.B \-scale \c
.IR xfac [\c
.BI , yfac\c
]
Multiply the horizontal and vertical window size by
.I xfac
and
.IR yfac ,
respectively.
Possible values are integers in the range
[1,4] for
.I xfac
and [1,8] for
.IR yfac .
Defaults are
.IR xfac =1
and
.IR yfac =2\(mu xfac .
Ignored if
.B \-usefont
is given.
.TP
.B \-resize
In Model III or 4/4P mode, resize the X window whenever the emulated display
mode changes between 64\(mu16 text (or 512\(mu192 graphics) and 80\(mu24 text
(or 640\(mu240 graphics).
This is the default in Model III mode, since 80\(mu24 text is not available and
the 640\(mu240 graphics add-on card is seldom used.
.TP
.B \-noresize
In Model III or 4/4P mode, always keep the X window large enough for 80\(mu24
text or 640\(mu240 graphics, putting a blank margin around the outside when the
emulated display mode is 64\(mu16 text or 512\(mu192 graphics.
This is the default in Model 4/4P mode, since otherwise there is an annoying
size switch during every reboot.
.TP
.B \-charset \c
.I charset-name
Select among several sets of built-in character bitmaps.
Valid values of
.I charset-name
depend on the TRS-80 model being emulated.
.IP
In Model I mode, five sets are available.
The default,
.BR wider ,
is a modified Model III set with characters 8 pixels wide; it looks better on a
modern computer screen with square pixels than the real Model I fonts, which
were 6 pixels wide.
.B lcmod
is the character set in the replacement character generator that was supplied
with the Radio Shack lowercase modification.
(It was reconstructed partly from memory and may have some minor bit errors.)
.B stock
is the character set in the stock character generator supplied with most
uppercase-only machines.
Since
.B xtrs
currently always emulates the extra bit of display memory needed to support
lowercase, this character set gives you the authentic, unpleasant effect that
real Model I users saw when they tried to do homebrew lowercase modifications
without replacing the character generator: lowercase letters appear at an
inconsistent height, and if you are using the Level II BASIC ROM display driver,
uppercase letters are replaced by meaningless symbols.
.B early
is the same as stock, but with the standard ASCII characters [, \(rs, ], and
\(ha in the positions where most Model I machines had directional arrows.
This was the default programming in the Motorola character generator ROM that
Radio Shack used, and a few early machines were actually shipped with this ROM.
Finally,
.B german
or
.B genie
gives an approximate emulation of the GENIE, a German Model I clone.
Characters are 8 pixels wide, and double width is supported even though later
GENIE models did not include it.
.IP
In Model III, 4, and 4P modes, three sets are available:
.B katakana
(the default for Model III) is the original Model III set with Japanese Katakana
characters in the alternate character positions.
This set was also used in early Model 4 machines.
.B international
(the default for Model 4 and 4P) is a later Model 4 set with accented Roman
letters in the alternate positions.
.B bold
is a boldface set from a character generator ROM found in one Model
III\(emorigin uncertain.
.TP
.B \-usefont
Use X fonts instead of the built-in character bitmaps.
.TP
.B \-nofont
Use the built-in character bitmaps, not an X font.
This is the default.
.TP
.B \-font \c
.I font-name
If
.B \-usefont
is also given, use the X font
.I font-name
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".
.TP
.B \-widefont \c
.I font-name
If
.B \-usefont
is also given, use the X font
.I font-name
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".
.TP
.B \-nomicrolabs
In Model I mode, emulate the HRG1B 384\(mu192 hi-res graphics card.
In Model III mode or Model 4/4P mode, emulate the Radio Shack hi-res card.
This is the default.
.TP
.B \-microlabs
In Model III or 4/4P mode, emulate the Micro Labs Grafyx Solution hi-res
graphics card.
Note that the Model III and Model 4/4P cards from Micro Labs are very different
from one another.
.TP
.B \-debug
Enter
.IR zbx ,
the Z80 debugger.
.TP
.B \-romfile \c
.I filename
.TQ
.B \-romfile3 \c
.I filename3
.TQ
.B \-romfile4p \c
.I filename4p
Use the ROM image file specified by
.I filename
in Model I mode,
by
.I filename3
in Model III and Model 4 mode,
or by
.I filename4p
in Model 4P mode.
A ROM image file can be either a raw binary dump in Intel hex format, or
TRS-80 CMD format (for example, a
.I MODELA/III
file).
If you do not set this option or the corresponding X resource, a default
established at compile time is used (if any); see
.I Makefile.local
in the
.B xtrs
source distribution
for instructions on compiling in default ROM image files or default ROM image
filenames.
.TP
.B \-model \c
.I m
Emulate a TRS-80 Model
.IR m .
Values accepted are
.B 1
or
.B I
(Model I),
.B 3
or
.B III
(Model III),
.B 4
or
.B IV
(Model 4), and
.B 4P
or
.B IVP
(Model 4P).
Model I is the default.
.TP
.B \-delay \c
.I d
Tune the emulator's (crude) speed control.
After each Z80 instruction,
.B xtrs
busy-waits for
.I d
iterations around an empty loop.
A really smart C optimizer might delete this loop entirely, so it's possible
that this option won't work if
.B xtrs
is compiled with too high an optimization level.
The default delay is 0.
.TP
.B \-autodelay
Dynamically adjust the value of the speed control described in
.B \-delay
above to run instructions at roughly the same rate as a real machine.
The tracking is only approximate, but it can be useful for running games.
.TP
.B \-noautodelay
Turn off
.BR \-autodelay .
This is the default.
.TP
.B \-keystretch \c
.I cycles
Fine-tune the keyboard behavior.
To prevent keystrokes from being lost,
.B xtrs
\(lqstretches\(rq the intervals between key transitions, so that the Z80 program
has time to see each transition before the next one occurs.
Whenever the Z80 program reads the keyboard matrix and sees an emulated key go
up or down,
.B xtrs
waits
.I cycles
Z80 clock cycles (T-states) before it allows the program to see another key
transition.
Key transitions that are received during the waiting period or when the Z80
program is not reading the keyboard are held in a queue.
The default stretch value is 4000 cycles; it should seldom if ever be necessary
to change it.
.TP
.B \-shiftbracket
Emulate [, \(rs, ], \(ha and _ as shifted keys, and {, |, }, and \(ti as
unshifted.
This is the default in Model 4 and 4P modes, and it works well with the keyboard
driver in Model 4
.IR TRSDOS / LS-DOS
6.
.TP
.B \-noshiftbracket
Emulate [, \(rs, ], \(ha and _ as unshifted keys, and {, |, }, and \(ti as
shifted.
This is the default in Model I and III modes, and it works well with many TRS-80
keyboard drivers.
With some keyboard drivers these keys do not work at all, however.
.TP
.B \-diskdir \c
.I dir
Set the search directory for floppy and hard disk images to
.IR dir .
If the value starts with \(lq\(ti/\(rq (or is just \(lq\(ti\(rq), it is relative
to your home directory (as determined by the
.B HOME
environment variable).
The default value is \(lq.\(rq.
.TP
.B \-doubler \c
.I doubler-type
(Model I mode only)
Set the double-density adaptor to emulate to
.IR doubler-type .
The parameter may be
.BR percom ,
.B radioshack
(or
.BR tandy ),
.BR both ,
or
.BR none .
.I doubler-type
may be abbreviated to one character.
The default is
.BR both ,
which causes the double density adaptor emulation to respond to the special
commands of both the Percom and Radio Shack cards.
.TP
.B \-doublestep
(Linux only)
Make all real floppy drives double-step, allowing access to 35-track or 40-track
media in an 80-track drive.
See
.BR "Bugs and limitations" ,
below.
.TP
.B \-nodoublestep
(Linux only)
Turn off double-step mode for all real floppy drives.
This is the default.
.TP
.B \-stepmap \c
.IR s0 [\c
.BI , s1\c
[\c
.BI , s2\c
[\c
.BI , s3\c
[\c
.BI , s4\c
[\c
.BI , s5\c
[\c
.BI , s6\c
[\c
.BI , s7\c
]]]]]]]
(Linux only)
Selectively set double-step mode for individual real floppy drives.
Each comma-delimited parameter corresponds to a drive unit number; see
.BR "Real floppy disks" ,
above.
If
.IR s U
is
.B 1
and
.IR disk M \- U
is a (symbolic link to) a real drive,
where
.I M
is the TRS-80 model
.RB ( 1 ,
.BR 3 ,
.BR 4 ,
or
.BR 4p )
and
.I U
is the drive unit number (a digit in the range 0\(en7), the drive will be
single-stepped; if
.IR s U
is
.BR 2 ,
it will be double-stepped.
You can omit values from the end of the list; those drives will get the
default value set by
.B \-doublestep
or
.BR \-nodoublestep .
.IP
Example:
.B \-model 1 \-stepmap 2,1,2
double-steps
.I disk1-0
and
.IR disk1-2 ,
and single-steps
.IR disk1-1 .
.TP
.B \-sizemap \c
.IR z0 [\c
.BI , z1\c
[\c
.BI , z2\c
[\c
.BI , z3\c
[\c
.BI , z4\c
[\c
.BI , z5\c
[\c
.BI , z6\c
[\c
.BI , z7\c
]]]]]]]
Selectively set whether drives are emulated as
.5-1/4
-inch or 8-inch; see
.BR "Emulated 8-inch floppy disks" ,
above.
If
.I zU
is
.BR 5 ,
the drive will appear to Z80 software as
.5-1/4
-inch; if
.BR 8 ,
as 8-inch.
The default setting (as reflected in the documentation above) is
.BR 5,5,5,5,8,8,8,8 .
You can omit values from the end of the list; those drives will get the default
values.
Setting one or more of the first four drives to 8-inch may be useful for
.I CP/M
software that supports 8-inch drives.
You can also use
.I XTRS8/DCT
with 8-inch drives in the first four positions; even though the prompt suggests
the unit number must be 4\(en7, numbers 0\(en3 are accepted.
.I XTRS8
does not check whether the unit you've selected is really being emulated as an
8-inch drive, however; you'll simply get errors during
.I FORMAT
if you get this wrong.
.TP
.B \-truedam
Turn off the single density data address mark remapping kludges
described in
.B Emulated floppy disks
and
.BR "Real floppy disks" ,
above.
With this option given, the distinction between 0xF8 and 0xFA data address marks
is strictly observed on both writing and reading.
This option is probably not useful unless you need to deal with Model I disks
that use the distinction as part of a copy-protection scheme.
See also
.\" If GNU roff, use hyphenless breakpoints.
.ie \n[.g] .UR http://\:www.tim-mann.org/\:trs80/\:dskspec.html
.el .UR http://www.tim-mann.org/trs80/dskspec.html
.I Common File Formats for Emulated TRS-80 Floppy Disks
.UE .
.TP
.B \-notruedam
The opposite of
.BR \-truedam .
This setting is the default.
.TP
.B \-samplerate \c
.I rate
Set the sample rate for new cassette WAVE files, direct cassette I/O to the
sound card, and game sound output to the sound card.
Existing WAVE files will be read or modified using their original sample rate
regardless of this flag.
The default is 44,100 Hz.
See also
.BR cassette (1).
.TP
.B \-serial \c
.I terminal-name
Set the terminal device to be used for I/O to the TRS-80's serial port to
.IR terminal-name.
The default is
.I /dev/ttyS0
on Linux, and
.I /dev/tty00
on other versions of Unix.
Setting the name to be empty
.RB ( "\-serial \(dq\(dq" )
emulates having no serial port.
.TP
.B \-switches \c
.I value
Set the sense switches on the Model I serial port card.
This option is meaningful only in Model I mode, and only when the
.B -serial
option is not set to \(dq\(dq.
The default value is 0x6F, which Radio Shack software conventionally interprets
as 9600 bps, 8 bits/word, no parity, 1 stop bit.
.TP
.B \-emtsafe
Disable emulator traps (see
.BR "Data import and export" ,
above) that could write to host files other than disk images in the original
emulated disk directory, or otherwise affect the host system (e.g., Unix shell
commands).
This setting is the default.
.TP
.B \-noemtsafe
The opposite of
.BR \-emtsafe .
.SH Exit status
.B
xtrs
primarily uses diagnostic messages to indicate trouble.
.TP
0
Successful operation; normal or expected exit.
.TP
1
Fatal error; includes usage errors such as unrecognized command-line arguments.
.TP
\-1, 255
Unable to open X display.
.SH Environment
.B
xtrs
reads a couple of environment variables.
.TP
.B DISPLAY
is read indirectly via
.BR XOpenDisplay (3),
and specifies the X server to which
.B xtrs
(an X client)
should connect.
.TP
.B HOME
is used at startup to (1) locate
.I .Xdefaults
and
.I Xtrs
files specifying defaults for command-line options and (2) resolve the argument
to the
.B \-diskdir
option;
and sometimes when the emulator trap to change
.BR xtrs 's
current working directory is activated; see
.BR "Data import and export" ,
above.
.SH Files
.B xtrs
may access files as described under
.B HOME
in
.BR Environment ,
above, as well as floppy drive, digital signal processor (sound), and terminal
device files; see
.B Real floppy disks
and
.BR Sound ,
above, and
.B \-serial
under
.BR Options ,
above.
.PP
If the
.B \-emtsafe
flag is not in effect, then through the use of emulator traps
(see
.BR "Data import and export" ,
above)
.I arbitrary
files on the system may be read, written, or deleted from within the emulator
with the privileges of the user invoking
.BR xtrs .
.SH Bugs and limitations
The emulated serial port's modem status and control signals are not tied to the
signals on the real serial port, because the real signals are not available to
software through the Unix terminal device interface.
The ability to check for parity, framing, and overrun errors and receive an
interrupt when one occurs is not emulated.
Unix does not support 2000, 3600, or 7200 baud, so these TRS-80 data rates are
remapped to 38400, 57600, and 115200 baud respectively.
.PP
A better signal processing algorithm might help read real cassettes more
reliably, especially at 1500bps.
.PP
Some features of the floppy disk controller are not currently emulated.
.IP \(bu
Force Interrupt with condition bits 0x01, 0x02, or 0x04 is not implemented.
.IP \(bu
Read Track is implemented only for DMK emulated floppies.
.IP \(bu
The multiple-sector flags in Read and Write are not implemented.
.IP \(bu
The timing of returned sectors is emulated only for the Read Address command,
and not very accurately for JV1 or JV3.
.IP \(bu
If a disk has more than one sector with the same number on a track,
.B xtrs
will always see the first (counting from the index hole) when reading or
writing; a real machine would see the next one to come under the head depending
on the current rotational position of the disk.
Partially reformatting a track (which TRS-80 programs like
.I HyperZap
and Model I
.I Super Utility
do to achieve mixed density) is supported for DMK but not JV3; however,
switching densities while formatting (which Model III and 4
.I Super Utility
do) works on both DMK and JV3.
.PP
Real physical floppy disks are supported only under Linux, because Unix does not
define a portable interface to the low-level floppy controller functionality
that
.B xtrs
needs.
There are some limitations even under Linux: index holes are faked, not detected
on the real disk, and the timing of returned sectors is not emulated at all.
Due to the limitations of ISA-bus floppy disk controllers, when formatting a
physical floppy under
.BR xtrs ,
you cannot mix sectors of different sizes on the same track, switch densities in
the middle of a track, or reformat only part of a track.
However,
.B xtrs
can read and write to physical floppies that have already been formatted in
these ways (perhaps by a real TRS-80).
.PP
The extended JV3 limit of 5802 sectors is somewhat arbitrary.
It could be raised by generalizing the code to permit more than two blocks of
2901, but this does not seem too useful.
5802 sectors is already enough for a
.3-1/2
-inch HD (1.44MB) floppy, which the TRS-80 didn't support anyway.
If you need more space, use emulated hard drives instead of emulated floppies
with huge numbers of tracks.
.PP
.I XTRSHARD/DCT
ignores the internal write-protected flag in hard drive images, but a hard drive
image can still be effectively write protected by turning off its Unix write
permission bits.
.PP
The emulator uses a heuristic to decide what format a ROM image file is in.
If a raw binary ROM image starts with 0x01, 0x05, or 0x22, it can be
misidentified as being in a different format.
This is rather unlikely to occur, as ROMs typically begin with 0xF3, the DI
instruction.
.PP
The joystick emulation could be made to work with real joysticks using the X
Input extension, but this is not implemented yet.
.PP
If you discover other bugs, write fixes for any of these, or make any other
enhancements, please let us know so that we can incorporate the changes into
future releases.
.SH Authors and acknowledgements
.B xtrs
1.0 was written by David Gingold and Alec Wolman.
The current version was revised and much extended by Timothy Mann
(see
.\" If GNU roff, use hyphenless breakpoints.
.ie \n[.g] .UR http://\:www.tim-mann.org/
.el .UR http://www.tim-mann.org/
.UE ).
See
.I README
in the
.B xtrs
source distribution for additional notes from the authors; a (compressed) copy
may be locally available with your
.B xtrs
installation at
.\" If outputting HTML, make the filename a clickable link.
.ie '\*(.T'html' \{\
.UR file:///usr/share/doc/xtrs/README.gz
.UE . \}
.el \{\
.IR /usr/share/doc/xtrs/README.gz . \}
.PP
We also thank the following people for their help.
The JV1 and JV3 floppy disk file formats were designed by Jeff Vavasour,
originally for his
.IR MS-DOS -based
TRS-80 emulators.
The DMK format was designed by David Keil for his
.IR MS-DOS -based
TRS-80 emulator.
The hard disk file format was designed by Matthew Reed for his
.IR MS-DOS -based
TRS-80 emulators.
Al Petrofsky and Todd P. Cromwell III supplied font data.
Roland Gerlach contributed the
.I CP/M
import and export programs as well as several bug reports and fixes for the
emulator itself.
Ulrich Mueller added the
.B \-borderwidth
option, improved the
.B \-scale
option and the bitmap font scaling, ported the
.IR IMPORT ,
.IR EXPORT ,
and
.I SETTIME
utilities to
.IR NEWDOS/80 ,
and contributed the HRG1B emulation.
Branden Robinson supplied the first version of the cassette man page, fixed
Makefile bugs, translated cassette to the Bourne shell, and implemented
watchpoints in
.IR zbx .
Mark McDougall provided documentation for the Micro Labs Grafyx Solution card.
Jenz Guenther added the
.B \-title
option and contributed code to emulate the GENIE (German Model I clone).
Joe Peterson contributed code to emulate the TimeDate80 and the
.B \-emtsafe
feature.
Denis Leconte contributed part of the
.B \-scale
implementation.
.SH See also
.BR cmddump (1),
.BR hex2cmd (1),
.BR cassette (1),
.BR mkdisk (1)
.PP
There are many other TRS-80 resources available on the Web, including shareware
and freeware emulators that run under
.I MS-DOS
and other operating systems,
software for converting TRS-80 physical media to the emulator's disk file
format, ROM images, and TRS-80 software that has already been converted.
For pointers, see
.\" If GNU roff, use hyphenless breakpoints.
.ie \n[.g] .UR http://\:www.tim-mann.org/\:trs80.html
.el .UR http://www.tim-mann.org/trs80.html
.UE .
.\" $Id: xtrs.man,v 1.69 2009/06/15 23:44:43 mann Exp $
.\" vim:set et ft=nroff tw=80: