xtrs(1)                                                   xtrs(1)



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

SSyynnttaaxx
       xxttrrss [[--mmooddeell mm]] [[--ddiisskkddiirr dd]] [[--ddeebbuugg]] _[_o_t_h_e_r _o_p_t_i_o_n_s_]

DDeessccrriippttiioonn
       xxttrrss is built on top of a Z-80 emulator, with  added  rou
       tines  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.

       xxttrrss  supports  48K  of  RAM in Model I or Model III mode,
       128K in Model 4 or Model 4P mode.  Floppy disks  and  hard
       disks are emulated using files to store the data; or under
       Linux only, real floppy drives can be used.  A printer  is
       emulated  by  sending  its  output  to standard output.  A
       serial port is emulated using a Unix tty 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 sup
       ported if you have an OSS-compatible sound  driver;  sound
       output though the cassette port, through the Model 4 sound
       option, and through  the  optional  Orchestra-85/90  music
       synthesizer  card  are all emulated.  In Model I mode, the
       HRG1B graphics card is emulated.  In Model  III  and  4/4P
       mode, you can select whether the Radio Shack graphics card
       or Micro Labs Grafyx Solution is emulated.  There is  also
       a  mouse driver for Model 4/4P mode.  Several common time-
       of-day clock cards are emulated on all models.  The  Alpha
       Products  joystick is emulated using the PC's numeric key
       pad.

       Because xxttrrss 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,  Mul
       tiDOS,  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 debugger either by starting xxttrrss with the -debug
       flag or by pressing F9 while xxttrrss is running.  The  debug
       ger  runs  in  the X terminal window that you started xxttrrss
       from.  Once you are in the debugger, type "help" for  more
       information.

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

KKeeyyss
       The following keys have special meanings to xxttrrss:

       LeftArrow,  Backspace,  or Delete is the TRS-80 left arrow
       key.  RightArrow or Tab is the right arrow  key.   UpArrow
       is  the  up  arrow key.  DownArrow 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 software).

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

       The  keys  [,  \,  ],  ^,  _, {, |, }, and ~ also activate
       unused positions in the keyboard matrix  (address  bit  3,
       data  bits 3-7).  With many TRS-80 keyboard drivers, these
       keys map to the corresponding ASCII characters; with  oth
       ers,  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 -shift
       bracket and -noshiftbracket 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 use
       ful together with the "-charset genie" command line  argu
       ment.

       Pressing  a key on a PC numeric keypad with NumLock disen
       gaged emulates the Alpha Products joystick.  Keys 2, 4, 6,
       8  (KP_Down, KP_Left, KP_Right, KP_Up) are the main direc
       tions; 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 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.

EEmmuullaatteedd ccaasssseettttee
       To  control  the  emulated  cassette, a file called ".cas
       sette.ctl" in the current directory keeps  track  of  what
       file is currently loaded as the cassette tape and the cur
       rent position within that  file.   The  ccaasssseettttee(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.  See the ccaasssseettttee man page for more  information
       about the cassette shell script and the cassette file for
       mats that are supported.

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

EEmmuullaatteedd ffllooppppyy ddiisskkss
       In Model I mode, xxttrrss emulates  a  Radio  Shack  Expansion
       Interface  with  the Percom Doubler or Radio Shack Doubler
       installed.   The  Doubler  provides  double-density   disk
       access  by  allowing either the stock WD1771 FDC chip or a
       WD1791 chip to be  selected  under  program  control.   At
       powerup the 1771 is selected, so operating systems with no
       Doubler driver see a stock system.  By default, the emula
       tor  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 emulate only one with a com
       mand line option; see below.

       In  Model  III,  4,  or  4P  mode, xxttrrss emulates the stock
       floppy controller, which uses a WD1793 chip (software-com
       patible with the WD1791) to provide 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-pro
       tect  tab  is emulated.  Use the mmkkddiisskk(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),  xxttrrss
       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 xxttrrss always
       emulates one.

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

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

       JV1 supports  only  single  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 sup
       port everything the real  controllers  could  do.   It  is
       probably  best to use JV3 for all the disk images you cre
       ate, since it is the most widely implemented by other emu
       lators, 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 den
       sity, with either FB (normal) or F8 (deleted) data address
       mark  on  any  sector.   In single density the nonstandard
       data address marks FA and F9 are also available.  You can
       not 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.  xxttrrss 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 xxttrrss
       may be unable to read it.  Note that an 80 track,  double-
       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 (dis
       cussed below).

       The DMK format is the most flexible.  It  supports  essen
       tially  everything  that  the  original hardware could do,
       including all "protected" disk formats.   However,  a  few
       protected  disks still may not work with xtrs due to limi
       tations in xtrs's floppy disk controller emulation  rather
       than  limitations  of  the DMK format; see the LIMITATIONS
       section below.

       The program mmkkddiisskk(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 mmkkddiisskk man 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 nonstandard DAM that
       is fully supported only by the  WD1771  floppy  disk  con
       troller  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,  xxttrrss  imple
       ments 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 xxttrrss does not emu
       late instructions  at  the  same  speed  as  the  original
       machines.  This  works  because xxttrrss 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.

EEmmuullaatteedd 88--iinncchh ffllooppppyy ddiisskkss
       In  addition  to  the four standard 5.25-inch drives, xxttrrss
       also emulates four 8-inch  floppy  drives.   There  is  no
       widely-accepted  standard  hardware  interface  for 8-inch
       floppies on the TRS-80, so xxttrrss 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 number (1, 3, 4, or
       4p) and U is a unit number (4, 5, 6, or 7).  The only dif
       ference  between  5.25-inch  and 8-inch emulated drives is
       that the emulator allows you  to  format  more  bytes  per
       track in the latter.  A new JV3 floppy can be formatted as
       either 5.25-inch or 8-inch depending on whether  you  ini
       tially  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 emulated drive after it has been  format
       ted 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 _u_t_i_l_i_t_y_._d_s_k.  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 emu
       lated floppy drive 0, and the supplied file _u_t_i_l_i_t_y_._d_s_k 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  con
       fusion.

           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) com
       mand  (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.)

RReeaall ffllooppppyy ddiisskkss
       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 oper
       ated in double density (or single density), not high  den
       sity, 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  density  on  a  real  Model I with the WD1771 con
       troller 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  TRSDOS 2.3 directory tracks will be
       unreadable.   (2)  On  writing  in  single  density,  xxttrrss
       silently  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 transla
       tion 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.

EEmmuullaatteedd hhaarrdd ddiisskkss
       xxttrrss 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 emulate the Radio Shack hard drive
       controller (based on the Western Digital WD1010)  and  use
       the native drivers for the original hardware.

       UUssiinngg XXTTRRSSHHAARRDD//DDCCTT

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

       To  use  XTRSHARD/DCT,  first run the mmkkddiisskk program under
       Unix to create a blank hard drive  (.hdv)  file.   Typical
       usage  would  be: _m_k_d_i_s_k _-_h _m_y_d_i_s_k_._h_d_v.  See the mmkkddiisskk(1)
       man page for other options.

       Second, link  the  file  to  an  appropriate  name.   XTR
       SHARD/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 num
       ber from 0 to 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 emu
       lated floppy drive 0, and the supplied file _u_t_i_l_i_t_y_._d_s_k is
       in  another emulated floppy drive.  Boot LDOS.  If you are
       using Model I LDOS 5.3.1, patch a bug in the  FORMAT  com
       mand by typing _P_A_T_C_H _F_O_R_M_A_T_/_C_M_D_._U_T_I_L_I_T_Y _M_1_F_O_R_M_A_T_/_F_I_X.  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
       _D_I_R_=_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) com
       mand (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 different unit number.

       The  F7  key  currently  doesn't  allow  XTRSHARD/DCT disk
       changes to be recognized, but you can change to a  differ
       ent  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 xxttrrss
       that 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.

       UUssiinngg nnaattiivvee hhaarrdd ddiisskk ddrriivveerrss

       Beginning in version 4.1, xxttrrss  also  emulates  the  Radio
       Shack  hard  disk controller (based on the Western Digital
       WD1010) and will work with the  native  drivers  for  this
       hardware.   This emulation uses the same hard drive (.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 NEW
       DOS/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 mmkkddiisskk program under Unix to  cre
       ate  a  blank hard drive (.hdv) file.  Typical usage would
       be: _m_k_d_i_s_k _-_h _m_y_d_i_s_k_._h_d_v.  See the mmkkddiisskk(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, xxttrrss 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 prob
       lem, 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.  Mon
       tezuma CP/M 2.2 does boot from the emulated hard drive.

       Finally, obtain the correct driver for the operating  sys
       tem  you  will be using, read its documentation, configure
       the driver, and format the drive.   Detailed  instructions
       are beyond the scope of this manual page.

DDaattaa iimmppoorrtt aanndd eexxppoorrtt
       Several Z-80 programs for data import and export from var
       ious TRS-80 operating systems are included  with  xxttrrss  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 _u_t_i_l_i_t_y_._d_s_k 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 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 emu
       lated disk.  Usage: _I_M_P_O_R_T _[_-_l_n_] _u_n_i_x_f_i_l_e _[_t_r_s_f_i_l_e_].   The
       -n  flag  converts  Unix  newlines (\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 character to keep it in upper case.  If  the
       destination  file  is omitted, IMPORT uses the last compo
       nent 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: _E_X_P_O_R_T _[_-_l_n_] _t_r_s_f_i_l_e _[_u_n_i_x_f_i_l_e_].
       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  file
       name,  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 sys
       tems.

       CD/CMD (or CD6/CMD) changes xtrs's Unix working directory.
       Usage:  _C_D  _[_-_l_]  _u_n_i_x_d_i_r.   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 interpreta
       tion  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  direc
       tory.

       UNIX/CMD (or UNIX6/CMD) runs a Unix shell command.  Usage:
       _U_N_I_X _[_-_l_] _u_n_i_x _c_o_m_m_a_n_d _l_i_n_e.  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  emulated  floppy  disks  in  the drives.  Usage:
       _M_O_U_N_T _[_-_l_] _f_i_l_e_n_a_m_e _U.  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 direc
       tory (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:
       _U_M_O_U_N_T _U.  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 _c_p_m_u_t_i_l_._d_s_k contains import and export
       programs for Montezuma CP/M, written  by  Roland  Gerlach.
       It  was formatted as a "Montezuma 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  sometimes find a newer version of the utilities than
       is included with xtrs.

       IMPORT.COM imports a Unix file and writes it  to  an  emu
       lated CP/M disk.  Usage: _I_M_P_O_R_T _[_-_n_] _[_u_n_i_x_f_i_l_e _[_c_p_m_f_i_l_e_]_].
       The -n flag converts Unix newlines (\n) to  CP/M  newlines
       (\r\n).  If the second filename is omitted, it is taken to
       be the same as the first. If both names are  omitted,  the
       program  prompts  for  filenames.   Note that the CP/M CCP
       converts 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:  _E_X_P_O_R_T   _c_p_m_f_i_l_e
       _[_$_[_T_]_[_L_]_].   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 file
       name 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 (emu
       lator 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  docu
       mented  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 exam
       ple 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.

IInntteerrrruuppttss
       The emulator supports only interrupt mode 1.  It will com
       plain  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.

PPrroocceessssoorr ssppeeeedd sseelleeccttiioonn
       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 modifica
       tion, 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.

SSoouunndd
       Sound  support uses the Open Sound System /dev/dsp device,
       standard on Linux and available on many  other  Unix  ver
       sions  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 your 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 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 any
       way.   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  operating  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 generate the best sound.   If  you  want  to  run
       Orchestra-85  instead, you can tell it that you have a 3.5
       MHz clock speedup with enable sequence 3E01D3FE  and  dis
       able  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 Orchestra-85/90, but you might  want  to
       specify a small fixed delay to keep from getting excessive
       key repeat.

MMoouussee
       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.  xxttrrss does not emulate the actual mouse hardware
       (a  serial mouse plugged into the Model 4 RS-232 port), so
       the original mouse  drivers  will  not  work  under  xxttrrss.
       Instead,  XTRSMOUS  accesses  the X mouse pointer using an
       emulator trap.  XTRSMOUS implements 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 using the syntax "XTRSMOUS
       (LOW)".

TTiimmee ooff ddaayy cclloocckk
       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.  xxttrrss  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  con
       troller 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 software that works with one of them,
       please send email to report what happens when it  is  used
       with xxttrrss.

       Also  see SETTIME/CMD in the "Data import and export" sec
       tion above for another way to get the correct time into  a
       Z-80 operating system running under xxttrrss.

       Finally,  you  might  notice that LDOS/LS-DOS always magi
       cally knows the correct date when you boot it (but not the
       time).   When you first power up the emulated TRS-80, xxttrrss
       dumps the date into the places in memory  where  LDOS  and
       LS-DOS normally save it across reboots, so it looks to the
       operating system as if  you  rebooted  after  setting  the
       date.

JJooyyssttiicckk
       Pressing  a key on a PC numeric keypad with NumLock disen
       gaged 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.

RRuunnnniinngg ggaammeess
       Some  games  run rather well under xxttrrss now, 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 sam
       ple  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".

OOppttiioonnss
       Defaults for all options can be specified using the  stan
       dard  X resource mechanism, and the class name for xxttrrss is
       "Xtrs".

       --ddiissppllaayy _d_i_s_p_l_a_y
              Set your X display to _d_i_s_p_l_a_y. The  default  is  to
              use the DISPLAY environment variable.

       --iiccoonniicc
              Start with the xxttrrss window iconified.

       --bbaacckkggrroouunndd _c_o_l_o_r
       --bbgg _c_o_l_o_r
              Specifies  the background color of the xxttrrss window.

       --ffoorreeggrroouunndd _c_o_l_o_r
       --ffgg _c_o_l_o_r
              Specifies the foreground color of the xxttrrss  window.

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

       --bboorrddeerrwwiiddtthh _w_i_d_t_h
              Put a border of _w_i_d_t_h pixels around the TRS-80 dis
              play.  The default is 2.

       --ssccaallee _x_f_a_c_[_,_y_f_a_c_]
              Multiply the horizontal and vertical window size by
              _x_f_a_c and _y_f_a_c, respectively.  Possible  values  are
              integers  in the range [1,4] for _x_f_a_c and [1,8] for
              _y_f_a_c.  Defaults are _x_f_a_c=1 and _y_f_a_c=2*_x_f_a_c.

       --rreessiizzee
              In Model III or 4/4P  mode,  resize  the  X  window
              whenever  the emulated display mode changes between
              64x16 text (or 512x192 graphics) 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.

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

       --cchhaarrsseett _n_a_m_e
              Select  among  several  sets  of built-in character
              bitmaps.

              In Model I  mode,  five  sets  are  available.  The
              default,  _w_i_d_e_r,  is  a modified Model III set with
              characters 8 pixels wide; it looks better on a mod
              ern  computer  screen  with  square pixels than the
              real Model I fonts, which were 6 pixels wide. _l_c_m_o_d
              is  the  character set in the replacement character
              generator that was supplied with  the  Radio  Shack
              lower  case  modification.   (It  was reconstructed
              partly from memory and  may  have  some  minor  bit
              errors.)   _s_t_o_c_k  is the character set in the stock
              character generator supplied with most  upper  case
              only machines. Since _x_t_r_s currently always emulates
              the extra bit of display memory needed  to  support
              lower  case,  this  character  set  gives  you  the
              authentic, unpleasant  effect  that  real  Model  I
              users saw when they tried to do homebrew lower case
              modifications without replacing the character  gen
              erator:   lower   case   letters   appear   at   an
              inconsistent height, and if you are using the Level
              II BASIC ROM display driver, upper case letters are
              replaced by meaningless symbols.  _e_a_r_l_y 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 pro
              gramming in the Motorola  character  generator  ROM
              that  Radio  Shack  used,  and a few early machines
              were actually shipped with this ROM.  Finally, _g_e_r_
              _m_a_n  or _g_e_n_i_e 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:  _k_a_t_a_k_a_n_a (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.   _i_n_t_e_r_
              _n_a_t_i_o_n_a_l  (the  default  for  Model  4 and 4P) is a
              later Model 4 set with accented  Roman  letters  in
              the alternate positions.  _b_o_l_d is a bold set from a
              character generator ROM found  in  one  Model  III,
              origin uncertain.

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

       --nnooffoonntt
              Use the built-in character bitmaps, not a  X  font.
              This is the default.

       --ffoonntt _f_o_n_t_n_a_m_e
              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".

       --wwiiddeeffoonntt _f_o_n_t_n_a_m_e
              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".

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

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

       --ddeebbuugg Enter zbx, the z80 debugger.

       --rroommffiillee _f_i_l_e_n_a_m_e
       --rroommffiillee33 _f_i_l_e_n_a_m_e_3
       --rroommffiillee44pp _f_i_l_e_n_a_m_e_4_p
              Use the romfile specified by _f_i_l_e_n_a_m_e  in  Model  I
              mode,  the  romfile specified by _f_i_l_e_n_a_m_e_3 in Model
              III and Model 4 mode, or the romfile  specified  by
              _f_i_l_e_n_a_m_e_4_p  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.

       --mmooddeell _m
              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.

       --ddeellaayy _d
              A  crude  speed  control.  After each Z-80 instruc
              tion, 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 you compile xtrs with too
              high an optimization level.  The default  delay  is
              0.

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

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

       --kkeeyyssttrreettcchh _c_y_c_l_e_s
              Fine-tune  the  keyboard  behavior.    To   prevent
              keystrokes  from  being  lost, xtrs "stretches" the
              intervals between key transitions, 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 _c_y_c_l_e_s 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 necessary to change it.

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

       --nnoosshhiiffttbbrraacckkeett
              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   keyboard
              drivers these keys do not work at all, however.

       --ddiisskkddiirr _d_i_r
              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 ".".

       --ddoouubblleerr _t_y_p_e
              Specify what type of double density adaptor to emu
              late  (Model I mode only).  The _t_y_p_e may be _p_e_r_c_o_m,
              _r_a_d_i_o_s_h_a_c_k (or _t_a_n_d_y), _b_o_t_h, or _n_o_n_e. The type  may
              be  abbreviated  to  one character.  The default is
              _b_o_t_h, which causes the double density adaptor  emu
              lation  to  respond to the special commands of both
              the Percom and Radio Shack cards.

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

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

       --sstteeppmmaapp ss00,,ss11,,ss22,,ss33,,ss44,,ss55,,ss66,,ss77
              Selectively set  double-step  mode  for  individual
              real  floppy  drives.   If _s_U is 2 and _d_i_s_k_M_-_U is a
              real drive, the drive will be double-stepped; if _s_U
              is 1, it will be single-stepped.  You can omit val
              ues from the end of the list; those drives will get
              the  default  value  set  by -doublestep or -nodou
              blestep.

       --ssiizzeemmaapp zz00,,zz11,,zz22,,zz33,,zz44,,zz55,,zz66,,zz77
              Selectively set  whether  drives  are  emulated  as
              5-inch  or 8-inch; see the section "Emulated 8-inch
              floppy disks" above.  If _z_U 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 documenta
              tion  above) is 5,5,5,5,8,8,8,8.  You can omit val
              ues 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.

       --ttrruueeddaamm
              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  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", available at
              http://www.tim-mann.org/trs80/dskspec.html.

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

       --ssaammpplleerraattee _r_a_t_e
              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  sam
              ple  rate  regardless of this flag.  The default is
              44,100 Hz.  See also the cassette(1) man page.

       --sseerriiaall _t_t_y_n_a_m_e
              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.   Set
              ting  the  name  to  be empty (-serial "") emulates
              having no serial port.

       --sswwiittcchheess _v_a_l_u_e
              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.

AAddddiittiioonnaall rreessoouurrcceess
       There  are  many  other  TRS-80 resources available on the
       Web, including shareware and freeware emulators  that  run
       under MSDOS and other operating systems, software for con
       verting 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.

BBuuggss aanndd lliimmiittaattiioonnss
       The  emulated  serial port's modem status and control sig
       nals 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  cur
       rently emulated: Force Interrupt with condition bits 0x01,
       0x02, or 0x04 is not implemented.  Read  Track  is  imple
       mented 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, xxttrrss 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 refor
       matting a track (which TRS-80 programs like  HyperZap  and
       Model I Super Utility do to achieve mixed density) is sup
       ported 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 xxttrrss needs.
       There  are  some limitations even under Linux: Index holes
       are faked, not detected on the real disk, and  the  timing
       of  returned  sectors  is not emulated at all.  Due to the
       limitations of PC-style floppy disk controllers, when for
       matting  a physical floppy under xxttrrss, you cannot mix sec
       tors of different sizes on the same track,  switch  densi
       ties  in the middle of a track, or reformat only part of a
       track.  However, xxttrrss can read and write to physical flop
       pies  that have already been formatted in these ways (per
       haps by a real TRS-80).

       The extended JV3 limit of 5802 sectors is  somewhat  arbi
       trary.   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  dif
       ferent  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.

AAuutthhoorrss aanndd aacckknnoowwlleeddggeemmeennttss
       xxttrrss 1.0 was written by David  Gingold  and  Alec  Wolman.
       The current version was revised and much extended by Timo
       thy Mann <tim@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 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  -bor
       derwidth option, improved the -scale option and the bitmap
       font scaling, ported the import, export, and settime util
       ities  to  Newdos/80, and contributed the HRG1B emulation.
       Branden Robinson supplied the first version  of  the  cas
       sette  man  page, fixed Makefile bugs, and translated cas
       sette to the Bourne shell.  Mark McDougall provided  docu
       mentation  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.