


xtrs(1)                                                               xtrs(1)



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

Syntax
  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]

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

  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.  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 output is also available if you have an OSS-compatible
  sound driver.  In Model 4/4P mode, a hi-res graphics card is emulated; you
  can select either the Radio Shack card or the Micro Labs Grafyx Solution
  card.  There is also a mouse driver for Model 4/4P mode.

  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, MultiDOS, and TRS-80 CP/M.  However, the emu-
  lator also includes some extensions to the standard hardware, and the spe-
  cial drivers, utilities, and instructions needed for these are not always
  provided for all systems. In particular, the hard disk emulation currently
  works only with LDOS/LS-DOS.

  The Z-80 emulator has a debugger called zbx.  It works sort of like dbx.
  If you run with debugging turned on (see the options section for how to do
  this), you'll enter the debugger, and you can type "help" for more informa-
  tion.

  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.

Keys
  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.  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 requests
  entry to the debugger if it is active.  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 Home key activates the position in
  the TRS-80 keyboard matrix that corresponds to the Model III/4/4P right
  shift key (address bit 7, data bit 1) 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).  These keys map to the
  corresponding ASCII characters under some TRS-80 keyboard drivers; under
  others, they do nothing.  The Insert key is equivalent to underscore
  (address bit 3, data bit 7), so that a shifted underscore can be obtained;
  this maps to ASCII code 0x7f under some TRS-80 keyboard drivers.  Note:
  Common Model 4 keyboard drivers seem to reverse the shift state of these
  keys, so you may need to press Shift+Insert to get an underscore, etc.

  On a German keyboard, the umlaut and "ess-tzet" 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.

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 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 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, xxttrrss emulates a Radio Shack Expansion Interface with the
  Percom Doubler or Radio Shack Doubler installed.  The Doubler provided
  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 Dou-
  bler 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, xxttrrss emulates the stock floppy controller,
  which used 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
  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 with no file named diskM-0 (that is, no disk in drive
  0), xxttrrss emulates having no 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.

  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 emu-
  lator 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 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 emula-
  tors, 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.  xxttrrss supports at most 96
  cylinders and 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 sec-
  tor 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 for-
  mats.  However, a few protected disks still may not work with xtrs due to
  limitations in xtrs's floppy disk controller emulation rather than limita-
  tions 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 direc-
  tory 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, xxttrrss 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 though xxttrrss does not emulate instructions at the same speed as the
  original machines. This works because xxttrrss keeps a virtual clock (techni-
  cally, 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.

Emulated 8-inch floppy disks
  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 inter-
  face 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 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.  Con-
  sider 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 emulated 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
  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 res-
  tart 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 sys-
  tem, 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 con-
  trollers 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 den-
  sity, 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 sup-
  ports 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 translation of F8 to FA
  on reading.

Emulated hard disks
  xxttrrss can emulate a hard disk in a file with the aid of a special LDOS
  driver called XTRSHARD/DCT.  This 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 the hard disk emulation, 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.  xxttrrss 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 _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
  command 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.  If you are curious
  about the _D_I_R=_1 parameter to FORMAT, see mmkkddiisskk(1).  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 hard 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 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 next section.
  Because xxttrrss does not emulate real hard drive controller hardware, hard
  disk drivers other than XTRSHARD/DCT will not work with it.

Data import and export
  Several Z-80 programs for data import and export from various 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 exter-
  nal 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 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:
  _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 component
  of the Unix pathname, but with any "." changed to "/" to match TRS-80 DOS
  file extension syntax.

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

  EXPORT/CMD reads a file from an emulated disk and exports it to a Unix
  file. Usage: _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, IMPORT uses the TRS-80 filename, but with any "/" changed
  to "." to match Unix file extension syntax.

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

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

  The next several programs were written in Misosys C and exist in two ver-
  sions 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: _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 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: _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 com-
  mand 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 emu-
  lated 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 emulated 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 new-
  lines (\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 pro-
  gram 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 [-_n] [_c_p_m_f_i_l_e [_u_n_i_x_f_i_l_e]].  The -n flag converts CP/M
  newlines (\r\n) to Unix newlines (\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.

  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 exist-
  ing programs is supplied in xtrshard.z, import.z, export.z, and settime.z.
  You can also write programs that use the traps in Misosys C, using the
  files xtrsemt.h and xtrsemt.ccc as an interface; a simple example is in
  settime.ccc.  The Basic programs import.bas and export.bas should not be
  used as a basis for further development, however; they use an old, slow
  mechanism in the emulator that may be removed in a future release rather
  than the emulator traps.

Interrupts
  The emulator supports only interrupt mode 1.  It will complain if your pro-
  gram enables interrupts after powerup without executing an IM 1 instruction
  first.  All Model I/III/4/4P software does this, as the built-in peri-
  pherals 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 emu-
  lated 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, run-
  ning in Model I mode on Intel Linux you'd see this pattern: (tick, 30ms,
  tick, 20ms,...) instead of seeing ticks every 25ms.

Sound
  Sound support has been completely rewritten in xtrs 3.7 and now 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.

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.  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 pro-
  grams 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)".

Running games
  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 particu-
  larly good.  (It's even better in xtrs 3.7 with the improved sound sup-
  port!) You will usually want to turn on autodelay, and you'll often need to
  tweak the keystretch setting. Running your X server in 8-bit/pixel mode
  also seems to help in some cases. Sample command lines:

      startx -- -bpp 8
      xtrs -keystretch 2,1,2 -autodelay

  If the keyboard seems to miss keystrokes entirely, you may need to increase
  the first number in the keystretch setting.  If you get an unwanted type-
  ahead effect, where keys that you hit after one screen is finished show up
  on the next screen, try reducing the first number, and set the last number
  equal to the first number.  See -keystretch below for more information.
  This aspect of the emulator seems to need a bit more work.

  Games with audio output may sound better if you increase the sample rate
  from the default 11,025 Hz.  Try "-samplerate 44100".  The title screen to
  "Talking Adventure 1: Forbidden Planet" by Fantastic Software seems to work
  a lot better at the higher sample rate.  On the other hand, raising the
  sample rate will make the sound break up if your machine isn't fast enough
  to generate samples at that rate.

Options
  Defaults for all options can be specified using the standard 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.

  --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 display.  The default
       is 2.

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

  --rreessiizzee
       In Model 4/4P mode, resize the X window whenever the emulated display
       mode changes between 64x16 and 80x24.

  --nnoorreessiizzee
       In Model 4/4P mode, always keep the X window large enough for 80x24
       characters, putting a blank margin around the outside when the emu-
       lated display mode is 64x16.  This is the default.

  --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 modern 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 authen-
       tic, unpleasant effect that real Model I users saw when they tried to
       do homebrew lower case modifications without replacing the character
       generator: lower case letters appear at an inconsistent height, and if
       you are using the Level II BASIC ROM display driver, upper case
       letters are replaced by meaningless symbols.  _e_a_r_l_y is the same as
       stock, but with the standard ASCII characters [, \, ], and ^ in the
       positions where most Model I's had directional arrows.  This was the
       default programming 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 dou-
       ble 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-normal--20-200-
       75-75-*-200-iso8859-1".

  --mmiiccrroollaabbss
       In Model 4/4P mode, emulate the Micro Labs Grafyx Solution hi-res
       graphics card.  This is the default.

  --nnoommiiccrroollaabbss
       In Model 4/4P mode, emulate the Radio Shack hi-res card.

  --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 correspond-
       ing X resource, a default established at compile time is used (if
       any); see Makefile.local for instructions on compiling in default rom-
       files 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 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.

  --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 _a_m_o_u_n_t,_p_o_l_l,_h_e_a_r_t_b_e_a_t
       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 an emulated key goes up or down, xtrs sets a counter
       to _a_m_o_u_n_t.  While the counter is greater than zero, (1) any further
       key transitions are held in a queue instead of being passed immedi-
       ately to the Z-80, (2) whenever the Z-80 program reads from the key-
       board matrix, the counter is decremented by _p_o_l_l, and (3) whenever a
       TRS-80 heartbeat interrupt is scheduled to occur (even if interrupts
       are disabled), the counter is decremented by _h_e_a_r_t_b_e_a_t.  The default
       setting is "16,1,1"; this seems to work well with ordinary keyboard
       drivers, but you may want to experiment with different values for
       games if keyboard response seem sluggish.

  --ddoouubblleerr _t_y_p_e
       Specify what type of double density adaptor to emulate (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 emulation 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 values
       from the end of the list; those drives will get the default value set
       by -doublestep or -nodoublestep.

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

  --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" sec-
       tions above.  With this option given, the distinction between F8 and
       FA data address marks is strictly observed on both writing and read-
       ing.  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.research.digital.com/SRC/personal/Tim_Mann/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 default 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 origi-
       nal sample rate regardless of this flag.  The default is 11,025 Hz.
       See also the cassette(1) man page.

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.research.digital.com/SRC/personal/Tim_Mann/trs80.html.

Bugs and limitations
  Some of the more bizarre undocumented Z-80 instructions are not imple-
  mented.

  Cassette emulation is much improved in this version of xtrs, but a better
  signal processing algorithm is still needed to read real cassettes reli-
  ably, especially at 1500bps.

  Serial ports are not emulated.

  Some features of the 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 sec-
  tors is emulated only for the Read Address command, and not very accurately
  for JV1 or JV3.  Partially reformatting 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 a limitation of PC-
  style floppy disk controllers, xxttrrss does not support mixing sectors of dif-
  ferent sizes on the same track when formatting a physical floppy.  However,
  xxttrrss can read and write to such floppies if they are already formatted
  (perhaps by a real TRS-80).  Switching densities while formatting a physi-
  cal floppy track does not work, nor does partially reformatting a track.

  The emulator arbitrarily limits both JV1 and JV3 disk images to 96 tracks.
  The limit could easily be increased to 255, but that would probably not be
  useful with existing TRS-80 operating systems, which don't expect floppies
  to have so many tracks.  For example, LDOS 5.3.1 allows at most 95 tracks
  on a floppy, though it allows more on hard drives.  255 tracks is an abso-
  lute maximum for the TRS-80 floppy disk controller and for the JV3 format.

  The extended JV3 limit of 5802 sectors is somewhat arbitrary as well.  It
  could be raised by generalizing the code to permit more than two blocks of
  2901.  Again, 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.

  xxttrrsshhaarrdd 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 misidenti-
  fied as being in a different format.  This is rather unlikely to occur, as
  ROMs typically begin with 0xF3, the DI instruction.

  If you discover other bugs, or write fixes for any of these, please let us
  know.  We expect to incorporate fixes into future releases.

Authors and acknowledgements
  xxttrrss was written by David Gingold <gingold@think.com> of Thinking Machines
  Corporation, Alec Wolman <wolman@crl.dec.com> of Digital Equipment Corpora-
  tion, and Timothy Mann <mann@pa.dec.com> of Digital Equipment Corporation.
  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 Petrof-
  sky and Todd P. Cromwell III supplied font data.  Roland Gerlach contri-
  buted 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 and ported the import, export, and settime utilities to Newdos/80.
  Branden Robinson supplied the first version of the cassette man page and
  fixed Makefile bugs.  Mark McDougall provided documentation for the Micro
  Labs Grafyx Solution card.  Jenz Guenther added the -title option and con-
  tributed code to emulate the GENIE (German Model I clone).





























































