


xtrs(1)                                                   xtrs(1)


NNaammee
       xtrs  -  TRS-80 Model I/III/4/4P emulator for the X Window
       System

SSyynnttaaxx
       xxttrrss [[--mmooddeell mm]] [[--ddiisskkddiirr dd]] [[--ddeebbuugg]] _[_o_t_h_e_r _o_p_t_i_o_n_s_]

DDeessccrriippttiioonn
       xxttrrss 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.

       xxttrrss  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 xxttrrss 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 xxttrrss with the -debug
       flag or by pressing F9 while xxttrrss is running.  The  debug
       ger  runs  in  the X terminal window that you started xxttrrss
       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.


KKeeyyss
       The following keys have special meanings to xxttrrss:

       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.

EEmmuullaatteedd ccaasssseettttee
       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  ccaasssseettttee(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 ccaasssseettttee man page for more  information
       about the cassette shell script and the cassette file for
       mats that are supported.

PPrriinntteerr
       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.

EEmmuullaatteedd ffllooppppyy ddiisskkss
       In Model I mode, xxttrrss 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, xxttrrss 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 mmkkddiisskk(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),  xxttrrss
       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 xxttrrss 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 xxttrrss 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.  xxttrrss 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 xxttrrss
       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 mmkkddiisskk(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 mmkkddiisskk 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,  xxttrrss  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 xxttrrss does not emu
       late instructions  at  the  same  speed  as  the  original
       machines.  This  works  because xxttrrss 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.

EEmmuullaatteedd 88--iinncchh ffllooppppyy ddiisskkss
       In  addition  to  the four standard 5.25-inch drives, xxttrrss
       also emulates four 8-inch  floppy  drives.   There  is  no
       widely-accepted  standard  hardware  interface  for 8-inch
       floppies on the TRS-80, so xxttrrss 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.)

RReeaall ffllooppppyy ddiisskkss
       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
       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  TRSDOS 2.3 directory tracks will be
       unreadable.   (2)  On  writing  in  single  density,  xxttrrss
       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.

EEmmuullaatteedd hhaarrdd ddiisskkss
       xxttrrss 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.

       UUssiinngg XXTTRRSSHHAARRDD//DDCCTT

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

       To use XTRSHARD/DCT, first run the  mmkkddiisskk  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  mmkkddiisskk(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  xxttrrss
       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.

       UUssiinngg nnaattiivvee hhaarrdd ddiisskk ddrriivveerrss

       Beginning  in  version  4.1,  xxttrrss 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 mmkkddiisskk 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 mmkkddiisskk(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, xxttrrss 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.

DDaattaa iimmppoorrtt aanndd eexxppoorrtt
       Several Z-80 programs for data import and export from var
       ious  TRS-80  operating  systems are included with xxttrrss 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.

IInntteerrrruuppttss
       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.

PPrroocceessssoorr ssppeeeedd sseelleeccttiioonn
       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.

SSoouunndd
       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.

MMoouussee
       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.  xxttrrss 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 xxttrrss.
       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)".

TTiimmee ooff ddaayy cclloocckk
       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.   xxttrrss  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 xxttrrss.

       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 xxttrrss.

       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,  xxttrrss
       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.

JJooyyssttiicckk
       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.

RRuunnnniinngg ggaammeess
       Some games run rather well under xxttrrss 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".

OOppttiioonnss
       Defaults  for all options can be specified using the stan
       dard X resource mechanism, and the class name for xxttrrss  is
       "Xtrs".

       --ddiissppllaayy _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.

       --bbaacckkggrroouunndd _c_o_l_o_r
       --bbgg _c_o_l_o_r
              Specifies the background color of the xxttrrss  window.

       --ffoorreeggrroouunndd _c_o_l_o_r
       --ffgg _c_o_l_o_r
              Specifies  the foreground color of the xxttrrss window.

       --ttiittllee _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.

       --bboorrddeerrwwiiddtthh _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.

       --ssccaallee _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.

       --rreessiizzee
              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.

       --nnoorreessiizzee
              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.

       --cchhaarrsseett _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  inconsis
              tent  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.

       --uusseeffoonntt
              Use X  fonts  instead  of  the  built-in  character
              bitmaps.

       --nnooffoonntt
              Use  the  built-in character bitmaps, not a X font.
              This is the default.

       --ffoonntt _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".

       --wwiiddeeffoonntt _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".

       --nnoommiiccrroollaabbss
              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.

       --mmiiccrroollaabbss
              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.

       --ddeebbuugg Enter zbx, the z80 debugger.

       --rroommffiillee _f_i_l_e_n_a_m_e
       --rroommffiillee33 _f_i_l_e_n_a_m_e_3
       --rroommffiillee44pp _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.

       --mmooddeell _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.

       --ddeellaayy _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.

       --aauuttooddeellaayy
              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.

       --nnooaauuttooddeellaayy
              Turn off -autodelay. This is the default.

       --kkeeyyssttrreettcchh _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.

       --sshhiiffttbbrraacckkeett
              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.

       --nnoosshhiiffttbbrraacckkeett
              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.

       --ddiisskkddiirr _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 ".".

       --ddoouubblleerr _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.

       --ddoouubblleesstteepp
              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.

       --nnooddoouubblleesstteepp
              Turn off  double-step  mode  for  all  real  floppy
              drives.  Linux only.  This is the default.

       --sstteeppmmaapp ss00,,ss11,,ss22,,ss33,,ss44,,ss55,,ss66,,ss77
              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.

       --ssiizzeemmaapp zz00,,zz11,,zz22,,zz33,,zz44,,zz55,,zz66,,zz77
              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.

       --ttrruueeddaamm
              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.

       --nnoottrruueeddaamm
              The  opposite  of  -truedam.   This  setting is the
              default.

       --ssaammpplleerraattee _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.

       --sseerriiaall _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.


       --sswwiittcchheess _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.

AAddddiittiioonnaall rreessoouurrcceess
       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.

BBuuggss aanndd lliimmiittaattiioonnss
       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,  xxttrrss  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 xxttrrss 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 xxttrrss, 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, xxttrrss 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.

AAuutthhoorrss aanndd aacckknnoowwlleeddggeemmeennttss
       xxttrrss  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.



                                                                1










