xtrs(1)                                                                xtrs(1)



[1mName[0m
       xtrs - TRS-80 Model I/III/4/4P emulator for the X Window System

[1mSyntax[0m
       [1mxtrs [-model m] [-diskdir d] [-debug] [4m[22m[other[24m [4moptions][0m

[1mDescription[0m
       [1mxtrs [22mis built on top of a Z-80 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.

       [1mxtrs  [22msupports 48K of RAM in Model I or Model III mode, 128K in Model 4
       or Model 4P mode.  Floppy disks and hard disks are emulated using files
       to store the data; or under Linux only, real floppy drives can be used.
       A printer is emulated by sending its  output  to  standard  output.   A
       serial  port is emulated using a Unix tty device.  Cassette I/O is emu-
       lated 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 Orches-
       tra-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  mod-
       els.   The  Alpha  Products joystick is emulated using the PC's numeric
       keypad.

       Because [1mxtrs [22memulates 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  Z-80 emulator has a debugger called zbx.  You can enter the debug-
       ger either by starting [1mxtrs [22mwith the -debug  flag  or  by  pressing  F9
       while [1mxtrs [22mis running.  The debugger runs in the X terminal window that
       you started [1mxtrs [22mfrom.  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 Z-80  program  when  it
       tries to read from the keyboard memory by pattern-matching its stack.

[1mKeys[0m
       The following keys have special meanings to [1mxtrs[22m:

       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, Clear, or LeftAlt is the Clear key.  Control is the Model 4
       Ctrl  key  (address  bit 7, data bit 2).  RightAlt is equivalent to the
       shifted down arrow key (used as a control key with  some  TRS-80  soft-
       ware).

       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 disk change in the emulated floppy drives (see below).  F8 exits
       the program.  F9 enters the debugger (zbx).  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 keyboard matrix (address bit  3,  data  bits  3-7).   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 is reversed from what it should be; if you press [ but
       { is displayed instead (etc.),  see  the  -shiftbracket  and  -noshift-
       bracket  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.

       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 argument.

       Pressing  a key on a PC numeric keypad with NumLock disengaged emulates
       the Alpha Products joystick.   Keys  2,  4,  6,  8  (KP_Down,  KP_Left,
       KP_Right,  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 acti-
       vating  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
       pressed.  If you have this problem, you can use the xmodmap program  to
       remap your numeric pad, and use the xev program to debug it.

[1mEmulated cassette[0m
       To  control the emulated cassette, a file called ".cassette.ctl" in the
       current directory keeps track of what file is currently loaded  as  the
       cassette  tape  and  the  current  position within that file.  The [1mcas-[0m
       [1msette[22m(1) shell script provides a way to manipulate this file.  You  may
       use  this  script to load and position cassette tape files.  The opera-
       tion works very much like an actual tape recorder.   See  the  [1mcassette[0m
       man  page  for more information about the cassette shell script and the
       cassette file formats that are supported.

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

[1mEmulated floppy disks[0m
       In  Model  I mode, [1mxtrs [22memulates 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"  (newer  versions of LDOS), or
       "PDUBL" or "RDUBL" (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 emu-
       late only one with a command line option; see below.

       In Model III, 4, or 4P mode, [1mxtrs [22memulates 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 [1mmkdisk[22m(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 hit function key F7 in the emulator.

       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), [1mxtrs [22memulates 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 [1mxtrs [22malways 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  [1mxtrs  [22mregardless  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 density, single sided, with directory on track
       17.  Sectors must be 256 bytes long.  Use FORMAT (DIR=17) if  you  want
       to format JV1 disks with more (or less) than 35 tracks under LDOS.

       JV3  is much more flexible, though it still does not support everything
       the real controllers could do.  It is probably best to use JV3 for  all
       the  disk images you create, since it is the most widely implemented by
       other emulators, unless you have a special reason to  use  one  of  the
       others.   A  JV3 disk can be formatted with 128, 256, 512, or 1024-byte
       sectors, 1 or 2 sides, single or double density, with either  FB  (nor-
       mal)  or  F8 (deleted) data address mark on any sector.  In single den-
       sity the nonstandard data address marks FA and F9 are  also  available.
       You  cannot format a sector with an incorrect track number or head num-
       ber.  You can format a sector with an intentional CRC error in the data
       field.  [1mxtrs [22msupports 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 [1mxtrs [22mmay 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 the LIMITATIONS section
       below.

       The program [1mmkdisk[22m(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
       [1mmkdisk [22mman page for more information.

       Early  Model  I  operating systems used an FA data address mark for the
       directory on single density disks, while later ones wrote F8 but  would
       accept either upon reading.  The change was needed because FA is a non-
       standard 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 FA and FB (which is used  for  non-directory
       sectors)  upon  reading, and cannot write FA.  To deal nicely with this
       problem, [1mxtrs [22mimplements the following kludge.  On  writing  in  single
       density, an F8 data address mark is recorded as FA.  On reading with an
       emulated WD1771 (available in Model I mode only), FA is returned as FA;
       on  reading  with a WD179x, FA is returned as F8.  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  [1mxtrs [22mdoes not emulate instructions at the same speed as the
       original machines. This works because [1mxtrs [22mkeeps a virtual clock (tech-
       nically,  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.

[1mEmulated 8-inch floppy disks[0m
       In addition to the four standard 5.25-inch drives, [1mxtrs  [22malso  emulates
       four  8-inch floppy drives.  There is no widely-accepted standard hard-
       ware interface for 8-inch floppies on the TRS-80, so  [1mxtrs  [22memulates  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 number (1, 3, 4, or 4p) and U is a 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 [4mutil-[0m
       [4mity.dsk[24m.   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  [4mutility.dsk[24m 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 [4md[24m is the LDOS drive number
       you want to use for the 8-inch drive and [4mu[24m is the unit number you chose
       when  naming the file.  Most likely you will choose [4md[24m and [4mu[24m to be equal
       to reduce confusion.

           SYSTEM (DRIVE=[4md[24m,DRIVER="XTRS8",ENABLE)
           Enter unit number ([4]-7): [4mu[0m

       You can repeat these steps with different values of [4md[24m  and  [4mu[24m  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.)

[1mReal floppy disks[0m
       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 PCs should  be
       able to read and write TRS-80 compatible floppies in this way.  Many PC
       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, 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 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.

       The  nonstandard  FA and F9 data address marks available in single den-
       sity on a real Model I with the WD1771  controller  also  need  special
       handling.  A PC-style 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 PC even if
       your PC otherwise supports single density.  In particular, Model I TRS-
       DOS  2.3 directory tracks will be unreadable.  (2) On writing in single
       density, [1mxtrs [22msilently records a F9 or FA DAM as F8.  (3) On reading in
       single  density  with  an  emulated  WD1771  (Model I mode only), F8 is
       returned as FA.  If you need more accurate behavior, the -truedam  flag
       will turn on error messages on attempts to write F9 or FA DAMs and will
       turn off translation of F8 to FA on reading.

       Hint: Be sure to set the drive type correctly in your PC's BIOS.  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 plugging  one  into  a  PC.)   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 a PC (this requires a 50-pin
       to 34-pin adaptor cable), tell your BIOS that it is a  5.25-inch  1.2MB
       drive.

[1mEmulated hard disks[0m
       [1mxtrs [22mcan 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.

       [1mUsing XTRSHARD/DCT[0m

       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 [1mxtrs[22m.
       The hard disk format was designed by Matthew Reed for his  Model  I/III
       and  Model  4  emulators;  [1mxtrs [22mduplicates the format so that users can
       exchange hard drive images across the emulators.

       To use XTRSHARD/DCT, first run the [1mmkdisk [22mprogram under Unix to  create
       a  blank  hard  drive  (.hdv)  file.  Typical usage would be: [4mmkdisk[24m [4m-h[0m
       [4mmydisk.hdv[24m.  See the [1mmkdisk[22m(1) man page for other options.

       Second, link the file to an appropriate name.  XTRSHARD/DCT supports 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 Model 4P also uses M=4) and U is
       a unit number from 0 to 7.  It looks for these files in the same direc-
       tory 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  [4mutility.dsk[24m 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 [4mPATCH[24m [4mFORMAT/CMD.UTILITY[24m [4mM1FOR-[0m
       [4mMAT/FIX[24m.  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 [4md[24m is the LDOS drive number
       you want to use for the hard drive (a typical choice would be 4) and  [4mu[0m
       is the unit number you chose when naming the file (most likely 0).

           SYSTEM (DRIVE=[4md[24m,DRIVER="XTRSHARD",ENABLE)
           Enter unit number ([0]-7): [4mu[0m
           FORMAT [4md[24m (DIR=1)

       Answer  the questions asked by FORMAT as you prefer.  The [4mDIR=1[24m parame-
       ter 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 [4md[24m and [4mu[24m 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
       different drive number or (if you renamed the hard disk file) a differ-
       ent unit number.

       The F7 key currently doesn't allow XTRSHARD/DCT disk changes to be rec-
       ognized,  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 Z-80  program  that  implements
       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  [1mxtrs  [22mthat  allows Z-80 programs to open, close, read, and
       write Unix files directly.  This support is described  further  in  the
       "Data import and export" section below.

       [1mUsing native hard disk drivers[0m

       Beginning  in version 4.1, [1mxtrs [22malso 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 (.hdv) file format that XTRSHARD/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 [1mmkdisk [22mprogram under Unix to create a blank
       hard drive (.hdv) file.  Typical usage would be: [4mmkdisk[24m [4m-h[24m  [4mmydisk.hdv[24m.
       See the [1mmkdisk[22m(1) man page for other options.

       Second,  link  the  file  to an appropriate name.  The WD1010 emulation
       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 from 0 to
       3.  It looks for these files in the same directory as the  floppy  disk
       files  diskM-U.  If no such files are present, [1mxtrs [22mdisables 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 support 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.

[1mData import and export[0m
       Several  Z-80  programs  for data import and export from various TRS-80
       operating systems are included with [1mxtrs [22mon 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 [4mutility.dsk[24m contains some programs for transferring
       data  between  the  emulator  and  ordinary  Unix  files.   IMPORT/CMD,
       IMPORT/BAS, EXPORT/CMD, EXPORT/BAS, and SETTIME/CMD run on the emulator
       under  Model I/III TRSDOS, 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 oper-
       ating  systems.   Model III TRSDOS users will have to use TRSDOS's CON-
       VERT command to read utility.dsk.

       IMPORT/CMD imports a Unix file and  writes  it  to  an  emulated  disk.
       Usage: [4mIMPORT[24m [4m[-ln][24m [4munixfile[24m [4m[trsfile][24m.  The -n flag converts Unix new-
       lines (\n) to TRS-80 newlines (\r).  The  -l  flag  converts  the  Unix
       filename to lower case, to compensate for TRS-80 operating systems such
       as Newdos/80 that convert all command line  arguments  to  upper  case.
       When using the -l flag, you can put a [ or up-arrow in front of a char-
       acter to keep it in upper case.  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.

       IMPORT/BAS is a much slower program that performs the same function  as
       IMPORT/CMD  but  may  work under more operating systems.  Simply run it
       under Disk Basic and answer the prompts.

       EXPORT/CMD reads a file from an emulated disk and exports it to a  Unix
       file.  Usage:  [4mEXPORT[24m  [4m[-ln][24m  [4mtrsfile[24m [4m[unixfile][24m.  The -n flag converts
       TRS-80 newlines (\r) to Unix newlines (\n).  The -l flag  converts  the
       Unix  filename  to lower case.  When using the -l flag, you can put a [
       or up-arrow in front of a character to keep it in upper case.   If  the
       destination  file is omitted, EXPORT uses the TRS-80 filename, but with
       any "/" changed to "." to match Unix file extension syntax.

       EXPORT/BAS is a much slower program that performs the same function  as
       EXPORT/CMD  but  may  work under more operating systems.  Simply run it
       under Disk Basic and answer the prompts.

       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 Unix working directory.   Usage:  [4mCD[0m
       [4m[-l][24m  [4munixdir[24m.   The  -l flag converts the Unix directory name to lower
       case.  When using the -l flag, you can put a [ or up-arrow in front  of
       a  character  to keep it in upper case.  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.

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

       UNIX/CMD  (or  UNIX6/CMD)  runs a Unix shell command.  Usage: [4mUNIX[24m [4m[-l][0m
       [4munix[24m [4mcommand[24m [4mline[24m.  The -l flag converts the Unix command line to lower
       case.   When using the -l flag, you can put a [ or up-arrow in front of
       a character to keep it in upper case.  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.

       MOUNT/CMD (or MOUNT6/CMD) is a convenience program that  switches  emu-
       lated  floppy  disks in the drives.  Usage: [4mMOUNT[24m [4m[-l][24m [4mfilename[24m [4mU[24m.  The
       -l flag converts the Unix filename to lower case.  When  using  the  -l
       flag, you can put a [ or up-arrow in front of a character to keep it in
       upper case.  The filename is any Unix filename; U is a single digit,  0
       through 7.  The command deletes the file diskM-U (where M is the TRS-80
       model) from the disk directory (see -diskdir option), replaces it  with
       a symbolic link to the given filename, and signals a disk change (as if
       F7 had been pressed).

       UMOUNT/CMD (or UMOUNT6/CMD) is a convenience program  that  removes  an
       emulated  floppy  disk  from  a drive.  Usage: [4mUMOUNT[24m [4mU[24m.  U is a single
       digit, 0 through 7.  The command deletes the file diskM-U (where  M  is
       the  TRS-80  model)  from  the disk directory (see -diskdir option) and
       signals a disk change (as if F7 had been pressed).

       The emulated floppy [4mcpmutil.dsk[24m 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 track, not 80), or  you  will  have  confusing
       problems  reading  this  disk.   Source code is included on the floppy;
       please pass  any  improvements  you  make  back  to  the  author.   See
       http://www.rkga.com.au/~roland/trs-80/cpm-xtrs/,  where  you will some-
       times find a newer version of the utilities than is included with xtrs.

       IMPORT.COM  imports a Unix file and writes it to an emulated CP/M disk.
       Usage: [4mIMPORT[24m [4m[-n][24m [4m[unixfile[24m [4m[cpmfile]][24m.  The  -n  flag  converts  Unix
       newlines (\n) to CP/M newlines (\r\n).  If the second filename is omit-
       ted, it is taken to be the same as the first. If both names  are  omit-
       ted,  the  program  prompts for filenames.  Note that the CP/M CCP con-
       verts all command line arguments to upper case, which  is  inconvenient
       if  your Unix file names are in lower case; in that case you'll need to
       let the program prompt for the filenames.

       EXPORT.COM reads a file from an emulated CP/M disk and exports it to  a
       Unix  file.  Usage: [4mEXPORT[24m [4mcpmfile[24m [4m[$[T][L]][24m.  The cpmfile name can use
       ? and * as wildcard characters.  The $T  flag  converts  CP/M  newlines
       (\r\n)  to  Unix newlines (\n).  The $L flag converts the CP/M filename
       to lowercase to form the Unix filename; note that the CP/M CCP converts
       all  command  line  arguments to upper case, so you need $L even if you
       typed the CP/M name in lower case.

       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.  The Basic programs
       import.bas and export.bas should not be used as  a  basis  for  further
       development,  however;  they use an old, slow mechanism in the emulator
       that may be removed in a future release rather than the emulator traps.

[1mInterrupts[0m
       The  emulator supports only interrupt mode 1.  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.  The
       emulator approximates this rather well even on  a  system  where  clock
       ticks  come at some frequency that isn't divisible by the emulated fre-
       quency (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 Intel
       Linux you'd see this pattern: (tick, 30ms, tick, 20ms,...)  instead  of
       seeing ticks every 25ms.

[1mProcessor speed selection[0m
       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's  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.

[1mSound[0m
       Sound  support  uses the Open Sound System /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 ver-
       sion of Unix, you'll need to define the symbol HAVE_OSS in  your  Make-
       file  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  automatically  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.

[1mMouse[0m
       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.  [1mxtrs [22mdoes 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 [1mxtrs[22m.  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 pro-
       grams.)

       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 using the syntax "XTRSMOUS (LOW)".

[1mTime of day clock[0m
       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.   [1mxtrs  [22mcurrently 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 unknown what their
       driver software will do in the year 2000 and beyond.  If you have soft-
       ware that works with one of them, please send email to report what hap-
       pens when it is used with [1mxtrs[22m.

       Also see SETTIME/CMD in the "Data import and export" section above  for
       another  way  to get the correct time into a Z-80 operating system run-
       ning under [1mxtrs[22m.

       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, [1mxtrs [22mdumps 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.

[1mJoystick[0m
       Pressing a key on a PC numeric keypad with NumLock disengaged  emulates
       the  Alpha  Products joystick.  See the Keys section above for details.
       The emulated joystick is mapped only at port 0, to avoid conflicts with
       other  devices.  The joystick emulation could be made to work with real
       joysticks using the X input extension, but this is not implemented yet.

[1mRunning games[0m
       Some  games  run rather well under [1mxtrs [22mnow, 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 Soft-
       ware 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".

[1mOptions[0m
       Defaults for all options can be specified using the standard X resource
       mechanism, and the class name for [1mxtrs [22mis "Xtrs".

       [1m-display [4m[22mdisplay[0m
              Set your X display to [4mdisplay[24m. The default is to use the DISPLAY
              environment variable.

       [1m-iconic[0m
              Start with the [1mxtrs [22mwindow iconified.

       [1m-background [4m[22mcolor[0m
       [1m-bg [4m[22mcolor[0m
              Specifies the background color of the [1mxtrs [22mwindow.

       [1m-foreground [4m[22mcolor[0m
       [1m-fg [4m[22mcolor[0m
              Specifies the foreground color of the [1mxtrs [22mwindow.

       [1m-title [4m[22mtitletext[0m
              Use [4mtitletext[24m in the window title bar  instead  of  the  program
              name.

       [1m-borderwidth [4m[22mwidth[0m
              Put  a  border  of  [4mwidth[24m pixels around the TRS-80 display.  The
              default is 2.

       [1m-scale [4m[22mxfac[,yfac][0m
              Multiply the horizontal and vertical window  size  by  [4mxfac[24m  and
              [4myfac[24m,  respectively.   Possible values are integers in the range
              [1,4] for [4mxfac[24m and [1,8] for  [4myfac[24m.   Defaults  are  [4mxfac[24m=1  and
              [4myfac[24m=2*[4mxfac[24m.

       [1m-resize[0m
              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.

       [1m-noresize[0m
              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.

       [1m-charset [4m[22mname[0m
              Select among several sets of built-in character bitmaps.

              In Model I mode, five sets are available. The default, [4mwider[24m, 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. [4mlcmod[24m is the char-
              acter set in the replacement character generator that  was  sup-
              plied  with  the  Radio  Shack lower case modification.  (It was
              reconstructed partly from memory and may  have  some  minor  bit
              errors.)  [4mstock[24m is the character set in the stock character gen-
              erator supplied with most upper case only machines.  Since  [4mxtrs[0m
              currently always emulates the extra bit of display memory needed
              to support lower case, this character set gives you the  authen-
              tic,  unpleasant  effect  that  real Model I users saw when they
              tried to do homebrew lower case modifications without  replacing
              the  character generator: lower case letters appear at an incon-
              sistent height, and if you are using the Level II BASIC ROM dis-
              play driver, upper case letters are replaced by meaningless sym-
              bols.  [4mearly[24m is the same as stock, but with the  standard  ASCII
              characters  [, \, ], and ^ in the positions where most Model I's
              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,  [4mgerman[24m  or [4mgenie[24m 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.

              In Model III,  4,  and  4P  modes,  three  sets  are  available:
              [4mkatakana[24m  (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's.  [4minterna-[0m
              [4mtional[24m (the default for Model 4 and 4P) is a later Model  4  set
              with accented Roman letters in the alternate positions.  [4mbold[24m is
              a bold set from a character generator ROM  found  in  one  Model
              III, origin uncertain.

       [1m-usefont[0m
              Use X fonts instead of the built-in character bitmaps.

       [1m-nofont[0m
              Use  the  built-in character bitmaps, not a X font.  This is the
              default.

       [1m-font [4m[22mfontname[0m
              If -usefont is also given, use the specified X font  for  normal
              width characters.  The default uses a common X fixed-width font:
              "-misc-fixed-medium-r-normal--20-200-75-75-*-100-iso8859-1".

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

       [1m-nomicrolabs[0m
              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 now the default.

       [1m-microlabs[0m
              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.

       [1m-debug [22mEnter zbx, the z80 debugger.

       [1m-romfile [4m[22mfilename[0m
       [1m-romfile3 [4m[22mfilename3[0m
       [1m-romfile4p [4m[22mfilename4p[0m
              Use the romfile specified by [4mfilename[24m in Model I mode, the  rom-
              file  specified  by  [4mfilename3[24m in Model III and Model 4 mode, or
              the romfile specified by [4mfilename4p[24m in Model 4P mode, A  romfile
              can be either a raw binary dump, Intel hex format, or TRS-80 cmd
              format (for example, a 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 Makefile.local  for  instruc-
              tions on compiling in default romfiles or default romfile names.

       [1m-model [4m[22mm[0m
              Specifies which TRS-80 model to emulate.  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.

       [1m-delay [4m[22md[0m
              A crude speed control.  After each Z-80 instruction, xtrs  busy-
              waits  for  [4md[24m 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  you compile xtrs with too high an
              optimization level.  The default delay is 0.

       [1m-autodelay[0m
              Dynamically adjusts the value of -delay 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.

       [1m-noautodelay[0m
              Turn off -autodelay. This is the default.

       [1m-keystretch [4m[22mcycles[0m
              Fine-tune the keyboard behavior.   To  prevent  keystrokes  from
              being  lost,  xtrs "stretches" the intervals between key transi-
              tions, so that the Z-80 program has time to see each  transition
              before the next one occurs.  Whenever the Z-80 program reads the
              keyboard matrix and sees an emulated key go  up  or  down,  xtrs
              waits  [4mcycles[24m  Z-80 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 Z-80 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.

       [1m-shiftbracket[0m
              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.

       [1m-noshiftbracket[0m
              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.

       [1m-diskdir [4m[22mdir[0m
              Specify the directory containing floppy and  hard  disk  images.
              If  the  value starts with "~/" (or is just "~"), it is relative
              to your home directory.  The default value is ".".

       [1m-doubler [4m[22mtype[0m
              Specify what type of double density adaptor to emulate (Model  I
              mode  only).   The  [4mtype[24m  may  be [4mpercom[24m, [4mradioshack[24m (or [4mtandy[24m),
              [4mboth[24m, or [4mnone[24m. The type may be  abbreviated  to  one  character.
              The  default  is  [4mboth[24m,  which causes the double density adaptor
              emulation to respond to the special commands of both the  Percom
              and Radio Shack cards.

       [1m-doublestep[0m
              Make  all  real  floppy  drives  double-step, allowing access to
              35-track or 40-track media in an 80-track  drive.   Linux  only.
              See the Floppy Disks section for limitations.

       [1m-nodoublestep[0m
              Turn  off  double-step  mode  for all real floppy drives.  Linux
              only.  This is the default.

       [1m-stepmap s0,s1,s2,s3,s4,s5,s6,s7[0m
              Selectively set double-step  mode  for  individual  real  floppy
              drives.   If [4msU[24m is 2 and [4mdiskM-U[24m is a real drive, the drive will
              be double-stepped; if [4msU[24m is 1, it will be  single-stepped.   You
              can  omit values from the end of the list; those drives will get
              the default value set by -doublestep or -nodoublestep.

       [1m-sizemap z0,z1,z2,z3,z4,z5,z6,z7[0m
              Selectively set whether drives are emulated as 5-inch or 8-inch;
              see  the section "Emulated 8-inch floppy disks" above.  If [4mzU[24m is
              5, the drive will appear to Z-80 software as 5-inch;  if  8,  as
              8-inch.   The default setting (as reflected in the documentation
              above) 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.

       [1m-truedam[0m
              Turn off the single density data address mark remapping  kludges
              described in the "Emulated floppy disks" and "Real floppy disks"
              sections above.  With this option given, the distinction between
              F8  and FA data address marks is strictly observed on both writ-
              ing 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",  available  at http://www.tim-
              mann.org/trs80/dskspec.html.

       [1m-notruedam[0m
              The opposite of -truedam.  This setting is the default.

       [1m-samplerate [4m[22mrate[0m
              Set the sample rate for new cassette wav files, direct  cassette
              I/O  to the sound card, and game sound output to the sound card.
              Existing wav files will be read or modified using their original
              sample  rate regardless of this flag.  The default is 44,100 Hz.
              See also the cassette(1) man page.

       [1m-serial [4m[22mttyname[0m
              Set the tty device to be used for I/O  to  the  TRS-80's  serial
              port.   The  default is /dev/ttyS0 on Linux, /dev/tty00 on other
              versions of Unix.  Setting the name to  be  empty  (-serial  "")
              emulates having no serial port.

       [1m-switches [4m[22mvalue[0m
              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.

[1mAdditional resources[0m
       There  are  many other TRS-80 resources available on the Web, including
       shareware and freeware emulators that run under MSDOS and other operat-
       ing  systems, software for converting TRS-80 physical media to the emu-
       lator'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.

[1mBugs and limitations[0m
       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  tty  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.

       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  imple-
       mented.  Read  Track is implemented only for DMK emulated floppies. The
       multiple-sector flags in Read and Write are not implemented.  The  tim-
       ing  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, [1mxtrs [22mwill 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;  however,  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 [1mxtrs [22mneeds.  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  PC-style floppy disk controllers, when formatting a physical
       floppy under [1mxtrs[22m, 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, [1mxtrs [22mcan 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 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.

       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.

[1mAuthors and acknowledgements[0m
       [1mxtrs  [22m1.0  was  written  by David Gingold and Alec Wolman.  The current
       version was revised and much extended by Timothy Mann (see  http://tim-
       mann.org/).   See  README  and README.tpm for additional notes from the
       authors.

       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 MSDOS-based TRS-80 emulators.  The DMK format was designed by David
       Keil  for  his  MSDOS-based TRS-80 emulator.  The hard disk file format
       was designed by Matthew Reed for his MSDOS-based TRS-80 emulators.   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 utilities to Newdos/80,
       and contributed the HRG1B emulation.   Branden  Robinson  supplied  the
       first version of the cassette man page, fixed Makefile bugs, and trans-
       lated cassette to the Bourne shell.  Mark McDougall provided documenta-
       tion  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.
       Denis Leconte contributed part of the -scale implementation.



                                                                       xtrs(1)
