xtrs(1)                     General Commands Manual                    xtrs(1)

Name
       xtrs - TRS-80 Model I/III/4/4P emulator for the X Window System

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

Description
       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 oper-
       ate as a TRS-80 Model I, Model III, Model 4, or Model 4P.

       xtrs  supports 48kiB of RAM in Model I or Model III mode, and 128kiB in
       Model 4 or Model 4P mode.  Floppy disks and  hard  disks  are  emulated
       using  files to store the data; or under Linux only, real floppy drives
       can be used.  A printer is emulated by sending its output to the  stan-
       dard  output.   A serial port is emulated using a Unix terminal device.
       Cassette I/O is emulated using files to store the cassette  data;  real
       cassettes  can  also  be  read  or written (with luck), either directly
       through your sound card (on Linux and other systems with OSS-compatible
       sound  drivers),  or  via  .wav files.  Game sound and music output are
       also supported if you have an OSS-compatible sound driver; sound output
       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  emu-
       lated on all models.  The Alpha Products joystick is emulated using the
       keyboard's numeric keypad.

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

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

       for more information.

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

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

       F11 toggles onscreen help on the keyboard mappings.

       LeftArrow, Backspace, or Delete is the TRS-80 left arrow key.  RightAr-
       row  or Tab is the right arrow key.  UpArrow is the up arrow key.  Dow-
       nArrow or Linefeed is the down arrow key.  Esc or Break  is  the  Break
       key.   Home or Clear is the Clear key.  Control is the Model 4 Ctrl key
       (address bit 7, data bit 2).

       F1, F2, and F3 are the Model 4/4P function keys (address  bit  7,  data
       bits  4, 5, and 6).  F1 is also the Model I Electric Pencil control key
       that some users added to their machines.  F4 is the Model 4  Caps  Lock
       key (address bit 7, data bit 3).  F5, Compose, or ScrollLock is equiva-
       lent to the @ key (so that @ can be used as a  modifier  key).   F6  is
       equivalent to the 0 key (so that a shifted 0 can be obtained).  F7 sig-
       nals a floppy disk change (see Emulated floppy disks, below).  F8 exits
       the program.  F9 enters the zbx debugger.  F10 is the reset button.

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

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

       On a German keyboard, the umlaut and 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 -charset genie command-
       line option.

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

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

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

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

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

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

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

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

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

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

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

       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 xtrs may be unable to read it.  Note that an 80 track, dou-
       ble-sided, double-density (18 sector) 5.25-inch floppy will fit  within
       the  original 2901 sector limit; the extension to 5802 is primarily for
       emulation of 8-inch drives (discussed below).

       The DMK format is the most flexible.  It  supports  essentially  every-
       thing  that  the  original hardware could do, including all "protected"
       disk formats.  However, a few protected disks still may not  work  with
       xtrs  due  to  limitations  in  xtrs's floppy disk controller emulation
       rather than limitations of the DMK format; see  Bugs  and  limitations,
       below.

       The program mkdisk(1) makes a blank emulated floppy or "bulk erases" an
       existing one.  By default, mkdisk makes a JV3 floppy, but with  the  -1
       flag  it makes a JV1 floppy, or with the -k flag a DMK floppy.  See the
       mkdisk man page for more information.

       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, 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  WD179x,  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 -truedam flag to turn off this kludge if you
       need to; in that case the original hardware is emulated exactly.

       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 xtrs does not emulate instructions at the same speed  as  the
       original  machines.   This  works  because  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.

   Emulated 8-inch floppy disks
       In  addition  to the four standard 5.25-inch drives, xtrs also emulates
       four 8-inch floppy drives.  There is no widely-accepted standard  hard-
       ware  interface  for  8-inch floppies on the TRS-80, so xtrs emulates a
       pseudo-hardware interface of its own and provides an LDOS/LS-DOS driver
       for it.

       Storage  for the emulated 8-inch disks is in files named diskM-U, where
       M is the TRS-80 model (1, 3, 4, or 4p) and U is the drive  unit  number
       (4, 5, 6, or 7).  The only difference between 5.25-inch and 8-inch emu-
       lated 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.25-inch or 8-inch depending on whether you initially put  it  into  a
       5.25-inch or 8-inch emulated drive.  A new DMK floppy, however, must be
       created with the -8 flag to 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.25-inch emu-
       lated  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, .dsk for 5.25-inch
       and .8in for 8-inch.

       To use the emulated 8-inch drives, you'll need a driver.  Under LDOS or
       LS-DOS, use the program XTRS8/DCT supplied on the emulated floppy util-
       ity.dsk.  This driver is  a  very  simple  wrapper  around  the  native
       LDOS/LS-DOS floppy driver.  Here are detailed instructions.

       First,  make  sure an appropriate version of LDOS is in emulated floppy
       drive 0, and the supplied  file  utility.dsk  is  in  another  emulated
       floppy drive.  Boot LDOS.  If you are using Model I LDOS, be sure FDUBL
       is running.

       Second, type the following commands.  Here d is the LDOS  drive  number
       you want to use for the 8-inch drive and u is the unit number you chose
       when naming the file.  Most likely you will choose 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 and u to have
       more than one 8-inch drive.  You might want to repeat four times  using
       4,  5,  6, and 7, or you might want to save some drive numbers for hard
       drives (see below).

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

       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.25-inch drives.  The four 5.25-inch drives have hardware  select
       codes  1, 2, 4, and 8, corresponding respectively to files diskM-0, -1,
       -2, and -3.  The four 8-inch drives have hardware select codes 3, 5, 6,
       and  7,  corresponding  respectively  to files diskM-4, -5, -6, and -7.
       (See also the -sizemap option below, however.)

   Real floppy disks
       Under Linux only, any diskM-U file can be a symbolic  link  to  a  real
       floppy  disk drive, typically /dev/fd0 or /dev/fd1.  Most machines with
       "legacy" (ISA bus) floppy drive support should  be  able  to  read  and
       write  TRS-80-compatible floppies 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 -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.

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

       If you link one of the 8-inch floppy files (diskM-4 through diskM-7) to
       a  real  floppy  drive, TRS-80 programs will see it as an 8-inch drive.
       Again, you need to use the XTRS8/DCT driver described above  to  enable
       LDOS/LS-DOS  to  access  an 8-inch drive.  The real drive can be either
       3.5-inch, 5.25-inch, or 8-inch.  A 3.5-inch or 5.25-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.25-inch HD drive  holds  exactly
       the  same  number  of  bits per track as an 8-inch drive; a 3.5-inch HD
       drive can hold 20% more, but we waste that space when using one to emu-
       late  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.

       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.

       1.     It will be impossible for you to read some Model I disks on your
              machine even if it otherwise supports single density.   In  par-
              ticular, Model I TRSDOS 2.3 directory tracks will be unreadable.

       2.     On  writing  in  single density, xtrs silently records a 0xF9 or
              0xFA DAM as 0xF8.

       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 -truedam flag  will  turn  on  error  messages  on
              attempts  to  write 0xF9 or 0xFA DAMs and will turn off transla-
              tion of 0xF8 to 0xFA on reading.

       Hint: Be sure to  set  the  drive  type  correctly  in  your  machine's
       firmware.   Linux  and  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.5-inch  drives spin at 300 rpm.  Newer 5.25-inch
       high-density capable drives ("1.2MB" 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.25-inch
       drives that cannot  do  high  density  ("180kB",  "360kB",  or  "720kB"
       5.25-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  con-
       troller--this  requires  a  50-pin  to  34-pin adaptor cable--tell your
       firmware that it is a 5.25-inch 1.2MiB drive.

   Emulated hard disks
       xtrs can emulate a hard disk in a file in one of two ways: it can use a
       special,  xtrs-specific LDOS driver called XTRSHARD/DCT, or it can emu-
       late the Radio Shack hard drive controller (based on the Western  Digi-
       tal WD1010) and use the native drivers for the original hardware.

       Using XTRSHARD/DCT
              The  XTRSHARD/DCT  driver  has  been tested and works under both
              LDOS 5.3.1 for Model I or III and TRSDOS/LS-DOS 6.3.1 for  Model
              4/4P.   It  may or may not work under earlier LDOS versions.  It
              definitely will not work under other TRS-80 operating systems or
              with  emulators  other  than  xtrs.   The  hard  disk format was
              designed by Matthew Reed for his Model I/III and Model 4  emula-
              tors; xtrs duplicates the format so that users can exchange hard
              drive images across the emulators.

              To use XTRSHARD/DCT, first run the mkdisk(1) program to create a
              blank  hard  drive (.hdv) file.  A typical usage would be mkdisk
              -h myhd.hdv.  See the mkdisk man page for other options.

              Second, link the file to an appropriate name.  XTRSHARD/DCT sup-
              ports  up  to eight hard drives, with names of the form hardM-U,
              where M is the TRS-80 model (1, 3, or 4; in this case the  Model
              4P  also  uses M=4) and U is a unit number in the range 0-7.  It
              looks for these files in the same directory as the  floppy  disk
              files diskM-U.

              Third,  make  sure an appropriate version of LDOS is in emulated
              floppy drive 0, and the supplied file utility.dsk is in  another
              emulated  floppy  drive.   Boot  LDOS.  If you are using Model I
              LDOS 5.3.1, patch a bug in the FORMAT command  by  typing  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
              LDOS.

              Fourth,  type  the following commands.  Here d is the LDOS drive
              number you want to use for the  hard  drive  (a  typical  choice
              would  be  4) and u is 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.   The  DIR=1
              parameter  to  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 d
              and u to have more than one hard drive.

              Finally, it's a good idea to give the  SYSTEM  (SYSGEN)  command
              (Model  I/III)  or  SYSGEN  command  (Model 4/4P).  This command
              saves the SYSTEM settings, so the drive will be available  again
              the next time you reboot or restart the emulator.

              If  you  need  to access the hard disk file after booting from a
              floppy that hasn't been SYSGENed, simply  use  the  same  SYSTEM
              command(s)  again,  but don't FORMAT.  You can freely use a dif-
              ferent drive number or (if you renamed the  hard  disk  file)  a
              different unit number.

              The  F7 key currently doesn't allow 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
              LDOS.

              Technical note: XTRSHARD/DCT is a small Z80 program that  imple-
              ments  all  the  required  functions  of  an  LDOS  disk driver.
              Instead of talking to a real (or emulated) hard disk controller,
              however,  it  uses  special support in xtrs that allows Z80 pro-
              grams to open, close, read, and write Unix files directly.  This
              support is described further in Data import and export, below.

       Using native hard disk drivers
              Beginning  in  version  4.1,  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 emu-
              lation uses the same hard drive (.hdv)  file  format  that  XTR-
              SHARD/DCT does.  With LDOS/LS-DOS, the RSHARDx/DCT and TRSHD/DCT
              drivers are  known  to  work.   With  Montezuma  CP/M  2.2,  the
              optional  Montezuma  hard  disk  drivers are known to work.  The
              hard disk drivers for NEWDOS/80 and for  Radio  Shack  CP/M  3.0
              should  work, but they have not yet been tested at this writing.
              Any bugs should be reported.

              To get started, run the mkdisk(1) program to create a blank hard
              drive (.hdv) file.  A typical usage would be mkdisk -h myhd.hdv.
              See the mkdisk man page for other options.

              Second, link the file to an appropriate name.  The WD1010 emula-
              tion supports up to four hard drives, with  names  of  the  form
              hardM-U, where M is the TRS-80 model (1, 3, 4, or 4p) and U is a
              unit number in the range 0-3.  It looks for these files  in  the
              same  directory  as  the  floppy disk files diskM-U.  If no such
              files are present, xtrs disables the WD1010 emulation.

              Note that if hard drive unit 0 is present on a  Model  4P  (file
              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 F2 while
              booting to force the ROM to boot from floppy,  or  simply  avoid
              using  unit number 0.  Stock TRSDOS/LS-DOS 6 systems do not sup-
              port booting from a hard drive; M.A.D. Software's HBUILD6 add-on
              to  LS-DOS  for hard drive booting should work, but is untested.
              Montezuma CP/M 2.2 does boot from the emulated hard drive.

              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.

   Data import and export
       Several  Z80  programs  for  data import and export from various TRS-80
       operating systems are included with 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.

       The emulated floppy utility.dsk contains some programs for transferring
       data  between  the  emulator  and  ordinary  Unix  files.   IMPORT/CMD,
       EXPORT/CMD, and SETTIME/CMD run on the emulator under Model I/III  TRS-
       DOS, Model I/III LDOS, Model I/III NEWDOS/80, and Model 4/4P TRSDOS/LS-
       DOS 6; they may also work under other TRS-80 operating systems.   Model
       III  TRSDOS  users  will  have  to use TRSDOS's CONVERT command to read
       utility.dsk.

       IMPORT/CMD
              imports a Unix file and writes it to an emulated disk.

              Usage: IMPORT [-lne] unixfile [trsfile]

              The -n flag converts Unix newlines (\n) to TRS-80 newlines (\r).
              The  -l flag converts the Unix filename to lowercase, to compen-
              sate for TRS-80 operating systems such as NEWDOS/80 that convert
              all  command-line  arguments  to  uppercase.   When using the -l
              flag, you can put a [ or up-arrow in front  of  a  character  to
              keep it in uppercase.  Give the -e flag if your TRS-80 operating
              system uses the NEWDOS/80 convention for representing the ending
              record  number  in  an  open file control block.  This should be
              detected automatically for NEWDOS/80 itself and for TRSDOS  1.3,
              but  you'll need to give the flag for DOSPLUS and possibly other
              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,  IMPORT  uses  the
              last component of the Unix pathname, but with any "." changed to
              "/" to match TRS-80 DOS file extension syntax.

       EXPORT/CMD
              reads a file from an emulated disk and  exports  it  to  a  Unix
              file.

              Usage: EXPORT [-lne] trsfile [unixfile]

              The -n flag converts TRS-80 newlines (\r) to Unix newlines (\n).
              The -l flag converts the Unix filename to lowercase.  When using
              the -l flag, you can put a [ or up-arrow in front of a character
              to keep it in uppercase.  Give the -e flag if your TRS-80  oper-
              ating  system uses the NEWDOS/80 convention for representing the
              ending record number in an open file control block.  This should
              be  detected  automatically  for NEWDOS/80 itself and for TRSDOS
              1.3, but you'll need to give the flag for DOSPLUS  and  possibly
              other  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, EXPORT uses
              the TRS-80 filename, but with any "/" changed to  "."  to  match
              Unix file extension syntax.

              Note:  The  export  of  files from xtrs may be prohibited by the
              -emtsafe flag; see Options, below.

       SETTIME/CMD
              reads the date and time from Unix and sets the TRS-80 DOS's date
              and time accordingly.

       The  next  several  programs were written in Misosys C and exist in two
       versions on utility.dsk.  The one whose name ends in "6" runs on  Model
       4  TRSDOS/LS-DOS  6.x;  the other runs on LDOS 5.x and most other Model
       I/III operating systems.

       CD/CMD (or CD6/CMD) changes  xtrs's  current  working  directory  under
              Unix.

              Usage: CD [-l] unixdir

              The -l flag converts the Unix directory name to lowercase.  When
              using the -l flag, you can put a [ or up-arrow  in  front  of  a
              character  to  keep it in uppercase.  Running CD/CMD will change
              the interpretation of any relative pathnames given to IMPORT  or
              EXPORT.  It will also change the interpretation of disk names at
              the next disk change, unless you specified an absolute  pathname
              for xtrs's -diskdir parameter.

              Note: The change of xtrs's current working directory may be pro-
              hibited by the -emtsafe flag; see Options, below.

       PWD/CMD
              (or PWD6/CMD) prints  xtrs's  current  working  directory  under
              Unix.

       UNIX/CMD
              (or UNIX6/CMD) runs a Unix shell command.

              Usage: UNIX [-l] unix-command-line

              The  -l  flag converts the Unix command line to lowercase.  When
              using the -l flag, you can put a [ or up-arrow  in  front  of  a
              character to keep it in uppercase.  Standard I/O for the command
              uses the xtrs program's standard I/O descriptors; it does not go
              to the TRS-80 screen or come from the TRS-80 keyboard.

              Note:  The execution of Unix shell commands may be prohibited by
              the -emtsafe flag; see Options, below.

       MOUNT/CMD
              (or MOUNT6/CMD) is a convenience program that switches  emulated
              floppy disks in the drives.

              Usage: MOUNT [-l] unixfile unit-number

              The  -l  flag converts unixfile to lowercase.  When using the -l
              flag, you can put a [ or up-arrow in front  of  a  character  to
              keep  it in uppercase.  unixfile is any Unix filename; unit-num-
              ber is a single digit, 0 through 7.   The  command  deletes  the
              file  diskM-U  (where  M  is the TRS-80 model and U is the given
              unit-number) from the disk directory (see  the  -diskdir  option
              below),  replaces it with a symbolic link to the given filename,
              and signals a disk change (as if F7 had been pressed).

              Note: The mounting of a Unix file as a disk image may be prohib-
              ited by the -emtsafe flag; see Options, below.

       UMOUNT/CMD
              (or  UMOUNT6/CMD)  is a convenience program that removes an emu-
              lated floppy disk from a drive.

              Usage: UMOUNT unit-number

              unit-number is a single digit, 0 through 7.  The command deletes
              the file diskM-U (where M is the TRS-80 model and U is the given
              unit-number) from the disk directory (see  the  -diskdir  option
              below), and signals a disk change (as if F7 had been pressed).

              Note:  The unmounting of a Unix file as a disk image by deleting
              it on the host may be  prohibited  by  the  -emtsafe  flag;  see
              Options, below.

       The emulated floppy cpmutil.dsk contains import and export programs for
       Montezuma CP/M, written by Roland Gerlach.  It was formatted as a "Mon-
       tezuma  Micro  Standard  DATA  disk (40T, SS, DD, 200K)", with 512-byte
       sectors.  Be careful to configure your 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
       cpmutil.html and source code in the file cpmutil.tgz (a gzipped tar ar-
       chive) in the xtrs source distribution.

       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 trs imp exp.h.  Assembler source code
       for  the  existing  programs  is  supplied  in  xtrshard.z,   import.z,
       export.z,  and  settime.z.   You  can  also write programs that use the
       traps in Misosys C, using the files xtrsemt.h  and  xtrsemt.ccc  as  an
       interface;  a simple example is in settime.ccc.  All of these files are
       available in the xtrs source distribution.

   Interrupts
       The emulator supports only interrupt mode 1 of the Z80.  It  will  com-
       plain  if your program enables interrupts after powerup without execut-
       ing 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.  The
       emulator has a notion of the absolute time at which each tick  is  sup-
       posed  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.

   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).  xtrs emulates this feature.

       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.  xtrs emulates this feature as well.

   Sound
       Sound support uses the Open Sound System (OSS) /dev/dsp  device,  stan-
       dard  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 HAVE OSS in
       the source distribution's Makefile  or  in  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 xtrs opens /dev/dsp.  It auto-
       matically closes the device again after a few seconds of silence.

       If you are playing a game with sound, you'll want to use the -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.

       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 -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 -samplerate flag.

       The Orchestra-85 music synthesis software will run under xtrs's Model I
       emulation,  and the Orchestra-90 software will run with Model III oper-
       ating systems under 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 gener-
       ate  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 xtrs's -autodelay flag when running Orches-
       tra-85/90, but you might want to specify a small fixed  delay  to  keep
       from getting excessive key repeat.

   Mouse
       A  few Model 4 programs could use a mouse, such as the shareware hi-res
       drawing program MDRAW-II.  The program XTRSMOUS/CMD on the utility disk
       (utility.dsk)  is  a  mouse driver for Model 4/4P mode that should work
       with most such programs.  xtrs does not emulate the actual mouse  hard-
       ware  (a  serial  mouse  plugged  into the Model 4 RS-232 port), so the
       original mouse drivers will not work  under  xtrs.   Instead,  XTRSMOUS
       accesses  the  X mouse pointer using an emulator trap.  XTRSMOUS imple-
       ments the same 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.)

       By  default  XTRSMOUS  installs  itself  in  high memory.  This is done
       because 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, 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 MDRAW to remove the test, you can install XTRSMOUS in low
       memory under TRSDOS/LS-DOS 6 using the syntax XTRSMOUS (LOW).

   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.  xtrs currently emulates  them  at  port  ranges
       0x70-0x7C and 0xB0-0xBC.  The T-Timer port range at 0xC0-0xCC conflicts
       with the Radio Shack hard drive controller and is not emulated.

       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 soft-
       ware that works with one of them, please contact  the  author  <http://
       www.tim-mann.org/> to report what happens when it is used with xtrs.

       Also  see SETTIME/CMD in Data import and export, above, for another way
       to get the correct time into a Z80 operating system running under xtrs.

       Note that Model I TRSDOS and VTOS 4.0 have a "year 1988"  problem,  and
       LDOS/LS-DOS  has  a  "year 2012" problem; see LDOS and LS-DOS: 2012 and
       Beyond  --  Technical  information  <http://www.trs-80.org/ldos-and-ls-
       dos-2012-and-beyond-technical-information/> by Matthew Reed.

   Joystick
       Pressing  a key on a PC-keyboard-style numeric keypad with NumLock dis-
       engaged emulates the Alpha Products joystick.   See  Keys,  above,  for
       details.  The emulated joystick is mapped only at port 0, to avoid con-
       flicts with other devices.

   Running games
       Some games run rather well under xtrs provided  that  your  machine  is
       fast  enough  to run the emulation in real time and that you choose the
       right command-line options.  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:
              $ startx -- -bpp 8
              $ xtrs -autodelay

       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  -samplerate
       11025 or even -samplerate 8000.

Options
       Defaults for all options can be specified using the standard X resource
       mechanism; see the Resource Manager Functions  chapter  of  Xlib  --  C
       Language  X  Interface  <ftp://www.x.org/pub/current/doc/libX11/libX11/
       libX11.html#Resource Manager Functions> by Jim Gettys, Robert W. Schei-
       fler, et al.  The class name for xtrs is Xtrs.

       -display x-display
              Set your X display to x-display.  The default is to use the DIS-
              PLAY environment variable.

       -iconic
              Start with the xtrs window iconified.

       -background color
       -bg color
              Set the background color of the xtrs window to color.

       -foreground color
       -fg color
              Set the foreground color of the xtrs window to color.

       -title title-text
              Use title-text in the window title bar instead  of  the  program
              name.

       -borderwidth width
              Put  a  border  of  width pixels around the TRS-80 display.  The
              default is 2.

       -scale xfac[,yfac]
              Multiply the horizontal and vertical window  size  by  xfac  and
              yfac,  respectively.   Possible values are integers in the range
              [1,4] for xfac and [1,8] for  yfac.   Defaults  are  xfac=1  and
              yfac=2xxfac.  Ignored if -usefont is given.

       -resize
              In Model III or 4/4P mode, resize the X window whenever the emu-
              lated display mode changes between 64x16 text (or 512x192 graph-
              ics)  and 80x24 text (or 640x240 graphics).  This is the default
              in Model III mode, since 80x24 text is  not  available  and  the
              640x240 graphics add-on card is seldom used.

       -noresize
              In Model III or 4/4P mode, always keep the X window large enough
              for 80x24 text or  640x240  graphics,  putting  a  blank  margin
              around  the outside when the emulated display mode is 64x16 text
              or 512x192 graphics.  This is the default in  Model  4/4P  mode,
              since  otherwise  there  is an annoying size switch during every
              reboot.

       -charset charset-name
              Select among several sets of built-in character bitmaps.   Valid
              values  of  charset-name  depend  on the TRS-80 model being emu-
              lated.

              In Model I mode, five sets are available.  The  default,  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.  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.)  stock is the character set in the stock character gen-
              erator supplied with most uppercase-only machines.   Since  xtrs
              currently always emulates the extra bit of display memory needed
              to support lowercase, this character set gives you  the  authen-
              tic,  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 incon-
              sistent height, and if you are using the Level II BASIC ROM dis-
              play  driver, uppercase letters are replaced by meaningless sym-
              bols.  early is the same as stock, but with the  standard  ASCII
              characters  [,  \,  ], and ^ in the positions where most Model I
              machines had directional arrows.  This was the default  program-
              ming  in  the  Motorola character generator ROM that Radio Shack
              used, and a few early machines were actually shipped  with  this
              ROM.  Finally, german or 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 mod-
              els did not include it.

              In Model III,  4,  and  4P  modes,  three  sets  are  available:
              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.
              international (the default for Model 4 and 4P) is a later  Model
              4  set  with  accented Roman letters in the alternate positions.
              bold is a boldface set from a character generator ROM  found  in
              one Model III--origin uncertain.

       -usefont
              Use X fonts instead of the built-in character bitmaps.

       -nofont
              Use  the built-in character bitmaps, not an X font.  This is the
              default.

       -font font-name
              If -usefont is also given, use the X font 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".

       -widefont font-name
              If -usefont is also given, use the X font font-name for  double-
              width characters.  The default uses a common X fixed-width font,
              scaled    to    double     width:     "-misc-fixed-medium-r-nor-
              mal--20-200-75-75-*-200-iso8859-1".

       -nomicrolabs
              In Model I mode, emulate the HRG1B 384x192 hi-res graphics card.
              In Model III mode or Model 4/4P mode, emulate  the  Radio  Shack
              hi-res card.  This is the default.

       -microlabs
              In  Model  III or 4/4P mode, emulate the Micro Labs Grafyx Solu-
              tion hi-res graphics card.  Note that the Model  III  and  Model
              4/4P cards from Micro Labs are very different from one another.

       -debug Enter zbx, the Z80 debugger.

       -romfile filename
       -romfile3 filename3
       -romfile4p filename4p
              Use the ROM image file specified by filename in Model I mode, by
              filename3 in Model III and Model 4 mode,  or  by  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  MOD-
              ELA/III file).  If you do not set this option or the correspond-
              ing X resource, a default established at compile  time  is  used
              (if any); see Makefile.local in the xtrs source distribution for
              instructions on compiling in default ROM image files or  default
              ROM image filenames.

       -model m
              Emulate a TRS-80 Model m.  Values accepted are 1 or I (Model I),
              3 or III (Model III), 4 or IV (Model 4), and 4P  or  IVP  (Model
              4P).  Model I is the default.

       -delay d
              Tune  the  emulator's  (crude)  speed  control.   After each Z80
              instruction, xtrs busy-waits for 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  xtrs
              is  compiled  with  too high an optimization level.  The default
              delay is 0.

       -autodelay
              Dynamically adjust the value of the speed control  described  in
              -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.

       -noautodelay
              Turn off -autodelay.  This is the default.

       -keystretch cycles
              Fine-tune  the  keyboard  behavior.   To prevent keystrokes from
              being lost, xtrs "stretches" the intervals between  key  transi-
              tions,  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, xtrs
              waits 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 neces-
              sary to change it.

       -shiftbracket
              Emulate  [, \, ], ^ and   as shifted keys, and {, |, }, and ~ as
              unshifted.  This is the default in Model 4 and 4P modes, and  it
              works well with the keyboard driver in Model 4 TRSDOS/LS-DOS 6.

       -noshiftbracket
              Emulate  [,  \, ], ^ and   as unshifted keys, and {, |, }, and ~
              as shifted.  This is the default in Model I and III  modes,  and
              it works well with many TRS-80 keyboard drivers.  With some key-
              board drivers these keys do not work at all, however.

       -diskdir dir
              Set the search directory for floppy and hard disk images to dir.
              If  the  value starts with "~/" (or is just "~"), it is relative
              to your home directory (as determined by  the  HOME  environment
              variable).  The default value is ".".

       -doubler doubler-type
              (Model I mode only) Set the double-density adaptor to emulate to
              doubler-type.  The  parameter  may  be  percom,  radioshack  (or
              tandy),  both,  or none.  doubler-type may be abbreviated to one
              character.  The default is both, which causes the double density
              adaptor emulation to respond to the special commands of both the
              Percom and Radio Shack cards.

       -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
              Bugs and limitations, below.

       -nodoublestep
              (Linux only) Turn off  double-step  mode  for  all  real  floppy
              drives.  This is the default.

       -stepmap s0[,s1[,s2[,s3[,s4[,s5[,s6[,s7]]]]]]]
              (Linux  only)  Selectively  set  double-step mode for individual
              real floppy drives.  Each comma-delimited parameter  corresponds
              to  a drive unit number; see Real floppy disks, above.  If sU is
              1 and diskM-U is a (symbolic link to) a real drive, where  M  is
              the TRS-80 model (1, 3, 4, or 4p) and U is the drive unit number
              (a digit in the range 0-7), the drive will be single-stepped; if
              sU  is  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 -doublestep or -nodoublestep.

              Example:  -model  1  -stepmap  2,1,2  double-steps  disk1-0  and
              disk1-2, and single-steps disk1-1.

       -sizemap z0[,z1[,z2[,z3[,z4[,z5[,z6[,z7]]]]]]]
              Selectively set whether drives  are  emulated  as  5.25-inch  or
              8-inch;  see  Emulated  8-inch floppy disks, above.  If zU is 5,
              the drive will appear to Z80 software as  5.25-inch;  if  8,  as
              8-inch.   The default setting (as reflected in the documentation
              above) is 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
              CP/M  software  that  supports  8-inch drives.  You can also use
              XTRS8/DCT with 8-inch drives in the first four  positions;  even
              though  the prompt suggests the unit number must be 4-7, numbers
              0-3 are accepted.  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 FORMAT if you get this wrong.

       -truedam
              Turn off the single density data address mark remapping  kludges
              described in Emulated floppy disks and 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  Common  File  Formats  for
              Emulated  TRS-80  Floppy  Disks  <http://www.tim-mann.org/trs80/
              dskspec.html>.

       -notruedam
              The opposite of -truedam.  This setting is the default.

       -samplerate 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  origi-
              nal  sample rate regardless of this flag.  The default is 44,100
              Hz.  See also cassette(1).

       -serial terminal-name
              Set the terminal device to be  used  for  I/O  to  the  TRS-80's
              serial  port  to  terminal-name.   The  default is /dev/ttyS0 on
              Linux, and /dev/tty00 on other versions of  Unix.   Setting  the
              name to be empty (-serial "") emulates having no serial port.

       -switches 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
              -serial  option  is  not  set to "".  The default value is 0x6F,
              which Radio Shack software  conventionally  interprets  as  9600
              bps, 8 bits/word, no parity, 1 stop bit.

       -emtsafe
              Disable  emulator traps (see 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.

       -noemtsafe
              The opposite of -emtsafe.

Exit status
       xtrs primarily uses diagnostic messages to indicate trouble.

       0      Successful operation; normal or expected exit.

       1      Fatal error; includes usage errors such as unrecognized command-
              line arguments.

       -1, 255
              Unable to open X display.

Environment
       xtrs reads a couple of environment variables.

       DISPLAY
              is  read  indirectly  via  XOpenDisplay(3),  and specifies the X
              server to which xtrs (an X client) should connect.

       HOME   is used at startup to (1) locate .Xdefaults and Xtrs files spec-
              ifying  defaults  for  command-line  options and (2) resolve the
              argument to the -diskdir option; and sometimes when the emulator
              trap  to  change  xtrs's current working directory is activated;
              see Data import and export, above.

Files
       xtrs may access files as described under HOME in Environment, above, as
       well  as  floppy  drive, digital signal processor (sound), and terminal
       device files; see Real floppy disks and Sound, above, and -serial under
       Options, above.

       If the -emtsafe flag is not in effect, then through the use of emulator
       traps (see Data import and export, above) arbitrary files on the system
       may  be  read,  written,  or  deleted from within the emulator with the
       privileges of the user invoking xtrs.

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  inter-
       face.  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.

       A better signal processing algorithm might  help  read  real  cassettes
       more reliably, especially at 1500bps.

       Some features of the floppy disk controller are not currently emulated.

       +      Force  Interrupt  with condition bits 0x01, 0x02, or 0x04 is not
              implemented.

       +      Read Track is implemented only for DMK emulated floppies.

       +      The multiple-sector flags in Read and Write are not implemented.

       +      The timing of returned sectors is emulated  only  for  the  Read
              Address command, and not very accurately for JV1 or JV3.

       +      If  a  disk  has  more than one sector with the same number on a
              track, 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 HyperZap and Model I Super  Utility  do  to
              achieve  mixed  density)  is supported for DMK but not JV3; how-
              ever, switching densities while formatting (which Model III  and
              4 Super Utility do) works on both DMK and JV3.

       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  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 limita-
       tions of ISA-bus floppy disk controllers, when  formatting  a  physical
       floppy  under  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, xtrs can read and write to physical floppies
       that have already been formatted in  these  ways  (perhaps  by  a  real
       TRS-80).

       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.5-inch HD (1.44MB) floppy, which the TRS-80 didn't  sup-
       port  anyway.  If you need more space, use emulated hard drives instead
       of emulated floppies with huge numbers of tracks.

       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.

       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 instruc-
       tion.

       The joystick emulation could be made to work with real joysticks  using
       the X Input extension, but this is not implemented yet.

       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.

Authors and acknowledgements
       xtrs  1.0  was  written  by David Gingold and Alec Wolman.  The current
       version was revised and much extended by  Timothy  Mann  (see  <http://
       www.tim-mann.org/>).   See  README  in the xtrs source distribution for
       additional notes from the authors; a (compressed) copy may  be  locally
       available with your xtrs installation at /usr/share/doc/xtrs/README.gz.

       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  MS-DOS-based  TRS-80  emulators.   The  DMK format was designed by
       David Keil for his MS-DOS-based TRS-80 emulator.  The  hard  disk  file
       format  was designed by Matthew Reed for his MS-DOS-based TRS-80 emula-
       tors.  Al Petrofsky and  Todd  P.  Cromwell  III  supplied  font  data.
       Roland  Gerlach contributed the CP/M import and export programs as well
       as several bug reports and  fixes  for  the  emulator  itself.   Ulrich
       Mueller  added  the -borderwidth option, improved the -scale option and
       the bitmap font scaling, ported the IMPORT, EXPORT, and SETTIME  utili-
       ties to NEWDOS/80, and contributed the HRG1B emulation.  Branden Robin-
       son supplied the first version of the cassette man page, fixed Makefile
       bugs,  translated  cassette to the Bourne shell, and implemented watch-
       points in zbx.  Mark McDougall provided  documentation  for  the  Micro
       Labs  Grafyx  Solution card.  Jenz Guenther added the -title option and
       contributed code to emulate the GENIE  (German  Model  I  clone).   Joe
       Peterson  contributed  code  to emulate the TimeDate80 and the -emtsafe
       feature.  Denis Leconte contributed part of the -scale implementation.

See also
       cmddump(1), hex2cmd(1), cassette(1), mkdisk(1)

       There are many other TRS-80 resources available on the  Web,  including
       shareware  and freeware emulators that run under MS-DOS and other oper-
       ating 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  <http://www.tim-mann.org/
       trs80.html>.

xtrs                              2017-04-16                           xtrs(1)