Provided by: xtrs_4.9c-3.5ubuntu1_amd64 bug

Name

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

Syntax

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

Description

       xtrs is built on top of a Z-80 emulator, with added routines to support keyboard and video
       I/O through an X interface.  The hardware emulation can operate as a TRS-80 Model I, Model
       III, Model 4, or Model 4P.

       xtrs  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 supported if you have  an  OSS-compatible  sound  driver;  sound  output  though  the
       cassette  port, through the Model 4 sound option, and through the optional Orchestra-85/90
       music synthesizer card are all emulated.  In Model I mode,  the  HRG1B  graphics  card  is
       emulated.   In  Model  III  and 4/4P mode, you can select whether the Radio Shack graphics
       card or Micro Labs Grafyx Solution is emulated.  There is also a mouse  driver  for  Model
       4/4P  mode.  Several common time-of-day clock cards are emulated on all models.  The Alpha
       Products joystick is emulated using the PC's numeric keypad.

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

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

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

Keys

       The following keys have special meanings to xtrs:

       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.

       F11 (or Shift+F1 on some systems) toggles an overlay window  which  summarizes  the  above
       information.

       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 others, they do nothing.  In some cases you
       may find the shift state is reversed from what it should be; if  you  press  [  but  {  is
       displayed  instead  (etc.),  see  the  -shiftbracket  and -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 useful
       together with the "-charset genie" command line argument.

       Pressing a key on a PC numeric keypad with NumLock disengaged emulates the Alpha  Products
       joystick.   Keys  2,  4, 6, 8 (KP_Down, KP_Left, KP_Right, KP_Up) are the main directions;
       keys 1, 3,  7,  and  9  (KP_End,  KP_Page_Down,  KP_Home,  KP_Page_Up)  work  as  diagonal
       directions  by  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.

Emulated cassette

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

Printer

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

Emulated floppy disks

       In  Model  I mode, xtrs emulates a Radio Shack Expansion Interface with the Percom Doubler
       or Radio Shack Doubler installed.  The Doubler  provides  double-density  disk  access  by
       allowing  either  the  stock WD1771 FDC chip or a WD1791 chip to be selected under program
       control.  At powerup the 1771 is selected, so operating systems with no Doubler driver see
       a  stock  system.   By  default, the emulator pretends to be both a Percom and Radio Shack
       Doubler at the same time -- 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 command line option; see below.

       In Model III, 4, or 4P mode, xtrs emulates the  stock  floppy  controller,  which  uses  a
       WD1793  chip  (software-compatible  with  the  WD1791)  to  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-protect tab is emulated.   Use  the  mkdisk(1)
       program  to  turn  the  write  protect  flag on or off.  To change floppies in an emulated
       drive, rename the existing file for the drive (if any), rename the new floppy file to  the
       proper name, and 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), xtrs emulates having no floppy disk controller.  The behavior of a  real
       machine  with  a  disk controller in this case didn't seem useful to emulate faithfully: A
       real Model I hangs with a screen full of garbage; a real Model III or 4 goes into a  retry
       loop  printing  "Diskette?"  on  the screen and rechecking whether you've inserted one.  A
       real Model 4P always has a floppy controller, however, so xtrs always emulates one.

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

       Emulated floppy image files can be of any  of  three  types:  JV1,  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 xtrs regardless of what model it
       is emulating.  A heuristic is used to decide which type of image is in a drive, as none of
       the types has a magic number or signature.

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

       JV3  is  much  more  flexible,  though  it  still  does  not  support  everything the real
       controllers could do.  It is probably best to use JV3 for all the disk images you  create,
       since  it  is  the  most  widely implemented by other emulators, unless you have a special
       reason to use one of the others.  A JV3 disk can be  formatted  with  128,  256,  512,  or
       1024-byte  sectors,  1 or 2 sides, single or double density, with either FB (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 cannot format a sector with an incorrect track
       number or head number.  You can format a sector with an intentional CRC error in the  data
       field.  xtrs supports at most 5802 total sectors on a JV3 image.

       The  original Vavasour JV3 format supported only 256-byte sectors, and had a limit of 2901
       total sectors.  If you use sector sizes other than 256 bytes  or  format  more  than  2901
       sectors on a disk image, emulators other than xtrs may be unable to read it.  Note that an
       80 track, 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 (discussed below).

       The DMK format is the most flexible.  It supports essentially 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 limitations in xtrs's floppy disk controller emulation
       rather than limitations of the DMK format; see the LIMITATIONS section below.

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

       Early  Model  I operating systems used an 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 controller used in the Model I; the controllers in the Model III and 4  cannot
       distinguish  between FA and FB (which is used for non-directory sectors) upon reading, and
       cannot write FA.  To deal nicely with this problem, xtrs implements 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 xtrs does not emulate
       instructions at the same speed as the original machines. This works because xtrs  keeps  a
       virtual  clock  (technically,  a  T-state counter), which measures how much time it should
       have taken to execute the instruction stream on a real machine, and it ties the  emulation
       of floppy disk index holes to this clock, not to real time.

Emulated 8-inch floppy disks

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

       Storage for the emulated 8-inch disks is in files named diskM-U, where  M  is  the  TRS-80
       model number (1, 3, 4, or 4p) and U is a unit number (4, 5, 6, or 7).  The only difference
       between 5.25-inch and 8-inch 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 initially put it into a 5.25-inch  or  8-inch  emulated
       drive.   A new DMK floppy, however, must be created with the -8 flag to mkdisk in order to
       be large enough for use in an 8-inch emulated drive.   JV1  floppies  cannot  be  used  in
       8-inch  drives.   Be careful not to put an emulated floppy into a 5.25-inch emulated drive
       after it has been formatted in an 8-inch emulated drive or vice  versa;  the  results  are
       likely  to be confusing.  Consider using different file extensions for the two types; say,
       .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 utility.dsk.  This driver is a very
       simple  wrapper  around  the  native  LDOS/LS-DOS  floppy  driver.   Here   are   detailed
       instructions.

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

       Second,  type the following commands.  Here d is the LDOS drive number you want to use for
       the 8-inch drive and u is the unit number you chose when naming the file.  Most likely you
       will choose d and u to be equal to reduce confusion.

           SYSTEM (DRIVE=d,DRIVER="XTRS8",ENABLE)
           Enter unit number ([4]-7): u

       You  can  repeat these steps with different values of d and u to have more than one 8-inch
       drive.  You might want to repeat four times using 4, 5, 6, and 7, or  you  might  want  to
       save some drive numbers for hard drives (see below).

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

       In  case  you  want to write your own driver for another TRS-80 operating system, here are
       details on the emulated pseudo-hardware.  The  8-inch  drives  are  accessed  through  the
       normal  floppy  disk controller, exactly like 5.25-inch drives.  The four 5.25-inch drives
       have hardware select codes 1, 2, 4, and 8, corresponding respectively  to  files  diskM-0,
       -1,  -2,  and  -3.   The  four  8-inch  drives  have hardware select codes 3, 5, 6, and 7,
       corresponding respectively to files diskM-4, -5, -6,  and  -7.   (See  also  the  -sizemap
       option below, however.)

Real floppy disks

       Under  Linux  only,  any  diskM-U file can be a symbolic link to a real floppy disk drive,
       typically /dev/fd0 or /dev/fd1.  Most  PCs  should  be  able  to  read  and  write  TRS-80
       compatible floppies in this way.  Many PC floppy controllers cannot handle single density,
       however, and some may have problems even with double  density  disks  written  on  a  real
       TRS-80, especially disks formatted by older TRS-80 operating systems.  Use the -doublestep
       flag if you need to read 35-track or 40-track media in an 80-track drive.  If you need  to
       write  35-track  or  40-track  media  in an 80-track drive, bulk-erase the media first and
       format it in the 80-track drive.  Don't write to a disk in an 80-track  drive  if  it  has
       ever  been  written  to  in a 40-track drive.  The narrower head used in an 80-track drive
       cannot erase the full track width written by the head in a 40-track drive.

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

       If  you  link  one  of  the 8-inch floppy files (diskM-4 through diskM-7) to a real floppy
       drive, TRS-80 programs will see it as an  8-inch  drive.   Again,  you  need  to  use  the
       XTRS8/DCT  driver  described  above  to enable LDOS/LS-DOS to access an 8-inch drive.  The
       real drive can be either 3.5-inch, 5.25-inch, or 8-inch.  A 3.5-inch  or  5.25-inch  drive
       will  be  operated in high-density mode, using MFM recording if the TRS-80 is trying to do
       double density, FM recording if the TRS-80 is trying to do single density.  In this  mode,
       these  drives  can  hold as much data as a standard 8-inch drive.  In fact, a 5.25-inch HD
       drive holds exactly the same number of bits per track as an 8-inch drive;  a  3.5-inch  HD
       drive  can  hold  20%  more,  but  we waste that space when using one to emulate an 8-inch
       drive.  In both cases we also waste the top three tracks, since an 8-inch drive  has  only
       77 tracks, not 80.

       The nonstandard FA and F9 data address marks available in single 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, xtrs 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 translation of F8 to
       FA on reading.

       Hint: Be sure to set the drive type correctly in your PC's BIOS.  Linux and xtrs  rely  on
       this information to know how fast your drives are spinning and hence what data rate to use
       when reading and writing.  All 3.5-inch drives spin at 300  RPM.   Newer  5.25-inch  high-
       density  capable  drives  ("1.2MB"  drives) normally always spin at 360 RPM.  (Some can be
       jumpered to slow down to 300 RPM when in double-density mode, but you should not  do  that
       when  plugging  one  into  a  PC.)   Older  5.25-inch  drives  that cannot do high density
       ("180KB", "360KB" or "720KB" 5.25-inch drives) always spin at 300 RPM.  All 8-inch  drives
       spin  at 360 RPM.  If you plug an 8-inch drive into a PC (this requires a 50-pin to 34-pin
       adaptor cable), tell your BIOS that it is a 5.25-inch 1.2MB drive.

Emulated hard disks

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

       Using XTRSHARD/DCT

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

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

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

       Third,  make  sure  an  appropriate version of LDOS is in emulated floppy drive 0, and the
       supplied file utility.dsk is in another emulated floppy drive.  Boot  LDOS.   If  you  are
       using   Model  I  LDOS  5.3.1,  patch  a  bug  in  the  FORMAT  command  by  typing  PATCH
       FORMAT/CMD.UTILITY M1FORMAT/FIX.  You need to apply this patch only once.  It must not  be
       applied to Model III or Model 4/4P LDOS.

       Fourth,  type the following commands.  Here d is the LDOS drive number you want to use for
       the hard drive (a typical choice would be 4) and u is  the  unit  number  you  chose  when
       naming the file (most likely 0).

           SYSTEM (DRIVE=d,DRIVER="XTRSHARD",ENABLE)
           Enter unit number ([0]-7): u
           FORMAT d (DIR=1)

       Answer  the  questions  asked  by  FORMAT as you prefer.  The DIR=1 parameter to FORMAT is
       optional; it causes the hard drive's directory to be on track 1, making the  initial  size
       of the image smaller.  You can repeat these steps with different values of d and u to have
       more than one hard drive.

       Finally, it's a good idea to give the SYSTEM (SYSGEN)  command  (Model  I/III)  or  SYSGEN
       command  (Model  4/4P).   This  command  saves  the  SYSTEM settings, so the drive will be
       available again the next time you reboot or restart the emulator.  If you need  to  access
       the  hard  disk file after booting from a floppy that hasn't been SYSGENed, simply use the
       same SYSTEM command(s) again, but don't FORMAT.  You can  freely  use  a  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 different hard disk file for the same unit by renaming  files  as  needed  and
       rebooting LDOS.

       Technical  note:  XTRSHARD/DCT  is  a  small Z-80 program that implements all the required
       functions of an LDOS disk driver.  Instead of talking to a real (or  emulated)  hard  disk
       controller,  however,  it  uses special support in xtrs 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.

       Using native hard disk drivers

       Beginning  in  version 4.1, xtrs also emulates the Radio Shack hard disk controller (based
       on the Western Digital WD1010) and will work with the native drivers  for  this  hardware.
       This  emulation  uses the same hard drive (.hdv) file format that XTRSHARD/DCT does.  With
       LDOS/LS-DOS, the RSHARDx/DCT and TRSHD/DCT drivers are known to work.  With Montezuma CP/M
       2.2,  the  optional  Montezuma hard disk drivers are known to work.  The hard disk drivers
       for NEWDOS/80 and for Radio Shack CP/M 3.0 should work, but they have not yet been  tested
       at this writing.  Any bugs should be reported.

       To  get  started,  run  the  mkdisk program under Unix to create a blank hard drive (.hdv)
       file.  Typical usage would be: mkdisk -h mydisk.hdv.  See the mkdisk(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,  xtrs  disables  the  WD1010
       emulation.

       Note  that  if hard drive unit 0 is present on a Model 4P (file hard4p-0), the Radio Shack
       boot ROM will always try to boot from it, even if the operating system  does  not  support
       booting from a hard drive.  If you have this problem, either hold down F2 while booting to
       force the ROM to boot from floppy, or simply avoid using unit number 0.  Stock  TRSDOS/LS-
       DOS  6  systems do not support booting from a hard drive; M.A.D. Software's HBUILD6 add-on
       to LS-DOS for hard drive booting should work, but is untested.  Montezuma  CP/M  2.2  does
       boot from the emulated hard drive.

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

Data import and export

       Several Z-80 programs for data import and export from various TRS-80 operating systems are
       included with xtrs on two emulated floppy images.  These programs use special  support  in
       the  emulator  to read and write external Unix files, discussed further at the end of this
       section.

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

       IMPORT/CMD imports a Unix file and writes it to an emulated disk.   Usage:  IMPORT  [-lne]
       unixfile [trsfile].  The -n flag converts Unix newlines (\n) to TRS-80 newlines (\r).  The
       -l flag converts the Unix filename to 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.   Give the -e flag if your TRS-80 operating system uses the Newdos/80 convention for
       representing the ending record number in an open  file  control  block.   This  should  be
       detected  automatically  for  Newdos/80 itself and for TRSDOS 1.3, but you'll need to give
       the flag for DOSPLUS and possibly other non-LDOS operating systems.  If you need the  flag
       but  don't give it (or vice versa), imported files will come out the wrong length.  If the
       destination file is omitted, IMPORT uses the last component of the Unix pathname, but with
       any "." changed to "/" to match TRS-80 DOS file extension syntax.

       EXPORT/CMD reads a file from an emulated disk and exports it to a Unix file. Usage: EXPORT
       [-lne] trsfile [unixfile].  The -n flag converts TRS-80 newlines  (\r)  to  Unix  newlines
       (\n).   The -l flag converts the Unix filename to 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.   Give  the  -e
       flag  if  your  TRS-80 operating system uses the Newdos/80 convention for representing the
       ending record number in an open file control block.  This should be detected automatically
       for  Newdos/80 itself and for TRSDOS 1.3, but you'll need to give the flag for DOSPLUS and
       possibly other non-LDOS operating systems.  If you need the flag but  don't  give  it  (or
       vice  versa),  exported  files will come out the wrong length.  If the destination file is
       omitted, EXPORT uses the TRS-80 filename, but with any "/" changed to "."  to  match  Unix
       file extension syntax.

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

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

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

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

       UNIX/CMD  (or  UNIX6/CMD)  runs a Unix shell command.  Usage: UNIX [-l] unix command line.
       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: MOUNT [-l] filename 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 directory (see -diskdir option), replaces it  with  a  symbolic  link  to  the  given
       filename, and signals a disk change (as if F7 had been pressed).

       UMOUNT/CMD  (or UMOUNT6/CMD) is a convenience program that removes an emulated floppy disk
       from a drive.  Usage: UMOUNT 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 cpmutil.dsk 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.  Documentation is included in the file cpmutil.html and source
       code     in     the     file     cpmutil.tgz     (a    gzipped    tar    archive).     See
       http://members.optusnet.com.au/~rgerlach/trs-80/cpmutil.html where you will sometimes find
       a newer version of the utilities than is included with xtrs.

       The  emulator  implements  a  set of pseudo-instructions (emulator traps) that give TRS-80
       programs access to Unix files.  The programs listed above use them.  If you would like  to
       write  your  own  such  programs,  the  traps  are  documented  in the file trs_imp_exp.h.
       Assembler source code for the existing  programs  is  supplied  in  xtrshard.z,  import.z,
       export.z,  and  settime.z.   You  can also write programs that use the traps in Misosys C,
       using the files xtrsemt.h and  xtrsemt.ccc  as  an  interface;  a  simple  example  is  in
       settime.ccc.

Interrupts

       The  emulator  supports  only  interrupt mode 1.  It will complain if your program enables
       interrupts after  powerup  without  executing  an  IM  1  instruction  first.   All  Model
       I/III/4/4P  software does this, as the built-in peripherals in these machines support only
       IM 1.

       The Model I has a 40 Hz heartbeat clock interrupt, while the Model III uses 30 Hz, and the
       Model  4/4P  can run at either 30 Hz or 60 Hz.  The emulator approximates this rather well
       even on a system where clock ticks come at some frequency  that  isn't  divisible  by  the
       emulated  frequency  (e.g.,  100  Hz on Intel Linux), as long as the true frequency is not
       slower than the emulated frequency.  The emulator has a notion of  the  absolute  time  at
       which each tick is supposed to occur, and it asks the host system to wake it up at each of
       those times.  The net result is that some ticks may be late,  but  there  are  always  the
       proper  number  of  ticks per second.  For example, running in Model I mode on Intel Linux
       you'd see this pattern: (tick, 30ms, tick, 20ms,...) instead of seeing ticks every 25ms.

Processor speed selection

       A standard Model 4 has a software-controlled switch to select operation at either  4.05504
       MHz  (with heartbeat clock at 60 Hz) or 2.02752 MHz (with heartbeat clock at 30 Hz).  xtrs
       emulates this feature.

       Model I's were often modified to operate at higher speeds than the standard  1.77408  MHz.
       With  one  common modification, writing a 1 to port 0xFE would double the speed to 3.54816
       MHz, while writing a 0 would set the speed back to normal.  The heartbeat clock runs at 40
       Hz in either case.  xtrs emulates this feature as well.

Sound

       Sound  support uses the Open Sound System /dev/dsp device, standard on Linux and available
       on many other Unix versions as well.  This support is compiled in automatically on  Linux;
       if  you  have OSS on another 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
       anyway.  If your sound has gaps, you can try reducing the sample rate with the -samplerate
       flag.

       The Orchestra-85 music synthesis software will run under xtrs's Model I emulation, and the
       Orchestra-90 software will run with Model III 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 disable sequence 3E00D3FE; this will
       let the software run twice as fast as on an unmodified Model I and generate better  sound.
       There is no need to use xtrs's -autodelay flag when running Orchestra-85/90, but you might
       want to specify a small fixed delay to keep from getting excessive key repeat.

Mouse

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

Time of day clock

       Several  battery-backed  time  of  day  clocks  were  sold  for the various TRS-80 models,
       including the TimeDate80, TChron1, TRSWatch, and T-Timer.  They are  essentially  all  the
       same hardware, but reside at a few different port ranges.  xtrs currently emulates them at
       port ranges 0x70-0x7C and 0xB0-0xBC.  The T-Timer port range at 0xC0-0xCC  conflicts  with
       the Radio Shack hard drive controller and is not emulated.

       These clocks return only a 2-digit year, and it is 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 xtrs.

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

       Finally, you might notice that LDOS/LS-DOS always magically knows the  correct  date  when
       you  boot  it (but not the time).  When you first power up the emulated TRS-80, xtrs 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.

Joystick

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

Running games

       Some games run rather well under xtrs 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 sample
       rate.  Running your X server in 8-bit/pixel mode also seems to help in some cases. Example
       command lines:

           startx -- -bpp 8
           xtrs -autodelay

       If  you  have  a slow machine and the sound breaks up, it is possible that your machine is
       not fast enough to generate samples at the default rate of 44,100 Hz.  If you  think  this
       may be happening, try "-samplerate 11025" or even "-samplerate 8000".

Options

       Defaults for all options can be specified using the standard X resource mechanism, and the
       class name for xtrs is "Xtrs".

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

       -iconic
              Start with the xtrs window iconified.

       -background color
       -bg color
              Specifies the background color of the xtrs window.

       -foreground color
       -fg color
              Specifies the foreground color of the xtrs window.

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

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

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

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

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

       -charset name
              Select among several sets of built-in character bitmaps.

              In  Model  I mode, five sets are available. The default, wider, is a modified Model
              III set with characters 8 pixels wide; it looks better on a modern computer  screen
              with  square pixels than the real Model I fonts, which were 6 pixels wide. lcmod is
              the character set in the replacement character generator that was supplied with the
              Radio  Shack lower case modification.  (It was reconstructed partly from memory and
              may have some minor bit errors.)  stock is the character set in the stock character
              generator  supplied with most upper case only machines. Since xtrs 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  generator:  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.  early is the same as stock, but with the standard
              ASCII characters [, \, ],  and  ^  in  the  positions  where  most  Model  I's  had
              directional  arrows.   This  was  the default programming in the Motorola character
              generator ROM that Radio Shack used, and a few early machines were actually shipped
              with  this  ROM.   Finally,  german  or genie gives an approximate emulation of the
              GENIE, a German Model I clone.  Characters are 8 pixels wide, and double  width  is
              supported even though later GENIE models did not include it.

              In  Model III, 4, and 4P modes, three sets are available: katakana (the default for
              Model III) is the original Model III set with Japanese Katakana characters  in  the
              alternate  character  positions.  This  set  was  also  used  in  early  Model 4's.
              international (the default for Model 4 and 4P) is a later Model 4 set with accented
              Roman  letters  in  the  alternate  positions.  bold is a bold set from a character
              generator ROM found in one Model III, origin uncertain.

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

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

       -font fontname
              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".

       -widefont fontname
              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-normal--20-200-75-75-*-200-iso8859-1".

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

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

       -debug Enter zbx, the z80 debugger.

       -romfile filename
       -romfile3 filename3
       -romfile4p filename4p
              Use  the  romfile  specified  by filename in Model I mode, the romfile specified by
              filename3 in Model III and Model 4 mode, or the romfile specified by filename4p  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 instructions  on  compiling  in  default  romfiles  or
              default romfile names.

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

       -delay d
              A  crude  speed  control.   After  each  Z-80  instruction,  xtrs  busy-waits for d
              iterations around an empty loop.  A really smart C optimizer might delete this loop
              entirely, so it's possible that this option won't work if you compile xtrs with too
              high an optimization level.  The default delay is 0.

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

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

       -keystretch cycles
              Fine-tune the keyboard behavior.  To  prevent  keystrokes  from  being  lost,  xtrs
              "stretches"  the  intervals  between  key 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 cycles
              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.

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

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

       -diskdir dir
              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 ".".

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

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

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

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

       -sizemap z0,z1,z2,z3,z4,z5,z6,z7
              Selectively set whether drives are emulated as 5-inch or 8-inch;  see  the  section
              "Emulated  8-inch  floppy  disks" above.  If zU is 5, the drive will appear to Z-80
              software as 5-inch; if 8, as 8-inch.  The default  setting  (as  reflected  in  the
              documentation  above)  is 5,5,5,5,8,8,8,8.  You can omit values from the end of the
              list; those drives will get the default values.  Setting one or more of  the  first
              four  drives to 8-inch may be useful for CP/M software that supports 8-inch drives.
              You can also use XTRS8/DCT with 8-inch drives in the  first  four  positions;  even
              though  the  prompt suggests the unit number must be 4-7, numbers 0-3 are accepted.
              XTRS8 does not check whether the unit you've selected is really being  emulated  as
              an  8-inch  drive,  however; you'll simply get errors during FORMAT if you get this
              wrong.

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

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

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

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

       -switches value
              Set  the sense switches on the Model I serial port card.  This option is meaningful
              only in Model I mode, and only when the -serial option  is  not  set  to  "".   The
              default value is 0x6f, which Radio Shack software conventionally interprets as 9600
              bps, 8 bits/word, no parity, 1 stop bit.

       -emtsafe
              Disable emulator traps (see "Data import and export")  that  could  write  to  host
              files other than disk images in the original diskdir.

       -noemtsafe
              The opposite of -emtsafe.  This setting is the default.

Additional resources

       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
       converting  TRS-80  physical  media  to  the  emulator's disk file format, ROM images, and
       TRS-80 software that has  already  been  converted.   For  pointers,  see  http://www.tim-
       mann.org/trs80.html.

Bugs and limitations

       The emulated serial port's modem status and control signals are not tied to the signals on
       the real serial port, because the real signals are not available to software  through  the
       Unix  tty  device interface.  The ability to check for parity, framing, and overrun errors
       and receive an interrupt when one occurs is not emulated.  Unix  does  not  support  2000,
       3600,  or  7200  baud, so these TRS-80 data rates are remapped to 38400, 57600, and 115200
       baud respectively.

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

       Some  features  of  the floppy disk controller are not currently emulated: Force Interrupt
       with condition bits 0x01, 0x02, or 0x04 is not implemented. Read Track is implemented only
       for  DMK  emulated  floppies.  The  multiple-sector  flags  in  Read  and  Write  are  not
       implemented.  The timing of returned  sectors  is  emulated  only  for  the  Read  Address
       command,  and not very accurately for JV1 or JV3.  If a disk has more than one sector with
       the same number on a track, xtrs will always see the first (counting from the index  hole)
       when  reading  or  writing;  a  real machine would see the next one to come under the head
       depending on the current rotational position of the disk.  Partially reformatting a  track
       (which  TRS-80  programs  like  HyperZap  and  Model  I  Super Utility do to achieve mixed
       density) is supported for DMK but not JV3; 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  xtrs  needs.
       There  are  some  limitations even under Linux: Index holes are faked, not detected on the
       real disk, and the timing of returned  sectors  is  not  emulated  at  all.   Due  to  the
       limitations  of  PC-style floppy disk controllers, when formatting a physical floppy under
       xtrs, you cannot mix sectors of different sizes on the same track, switch densities in the
       middle  of a track, or reformat only part of a track.  However, xtrs can read and write to
       physical floppies that have already been formatted  in  these  ways  (perhaps  by  a  real
       TRS-80).

       The  extended  JV3  limit  of  5802  sectors is somewhat arbitrary.  It could be raised by
       generalizing the code to permit more than two blocks of 2901, but this does not  seem  too
       useful.   5802  sectors  is  already  enough  for a 3.5-inch HD (1.44MB) floppy, which the
       TRS-80 didn't support anyway.  If you need more space, use emulated hard drives instead of
       emulated floppies with huge numbers of tracks.

       XTRSHARD/DCT  ignores  the  internal write-protected flag in hard drive images, but a hard
       drive image can still be effectively  write  protected  by  turning  off  its  Unix  write
       permission bits.

       The emulator uses a heuristic to decide what format a ROM file is in.  If a raw binary ROM
       image starts with 0x01, 0x05, or 0x22, it can be misidentified as  being  in  a  different
       format.   This  is  rather  unlikely  to  occur, as ROMs typically begin with 0xF3, the DI
       instruction.

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

       If  you discover other bugs, write fixes for any of these, or make any other enhancements,
       please let us know so that we can incorporate the changes into future releases.

Authors and acknowledgements

       xtrs 1.0 was written by David Gingold and Alec Wolman.  The current  version  was  revised
       and  much  extended by Timothy Mann (see http://tim-mann.org/).  See README and README.tpm
       for additional notes from the authors.

       We also thank the following people for their help.  The  JV1  and  JV3  floppy  disk  file
       formats  were  designed by Jeff Vavasour, originally for his MSDOS-based TRS-80 emulators.
       The DMK format was designed by David Keil for his MSDOS-based TRS-80 emulator.   The  hard
       disk  file  format  was designed by Matthew Reed for his MSDOS-based TRS-80 emulators.  Al
       Petrofsky and Todd P. Cromwell III supplied font data.   Roland  Gerlach  contributed  the
       CP/M  import and export programs as well as several bug reports and fixes for the emulator
       itself.  Ulrich Mueller added the -borderwidth option, improved the -scale option and  the
       bitmap  font  scaling,  ported the import, export, and settime utilities to Newdos/80, and
       contributed the HRG1B emulation.  Branden Robinson  supplied  the  first  version  of  the
       cassette  man  page,  fixed  Makefile  bugs,  translated cassette to the Bourne shell, and
       implemented watchpoints in zbx.  Mark McDougall provided documentation for the Micro  Labs
       Grafyx  Solution  card.   Jenz  Guenther  added  the -title option and contributed code to
       emulate the GENIE (German Model I clone).  Joe Peterson contributed code  to  emulate  the
       TimeDate80  and  the  -emtsafe  feature.   Denis  Leconte  contributed  part of the -scale
       implementation.

                                                                                          xtrs(1)