XZX

		       An X11-based ZX Spectrum emulator

		   by Erik Kunze <Erik.Kunze@fantasy.muc.de>
		      based on XZX 1.0.2 by Des Herriott
				and many others


Contents
--------
 1.    Introduction
 1.1.  Registration
 1.2.  Distribution
 1.3.  Reporting bugs
 1.4.  Credits
 2.    Using the emulator
 2.1.  Setting up your environment
 2.2.  Starting the emulator
 2.3.  Options
 2.4.  Configuration file
 2.5.  On-Screen-Dialogs
 2.6.  Offix drag and drop support
 3.    Hardware emulation
 3.1.  Z80 emulation
 3.2.  Keyboard emulation
 3.3.  Screen emulation
 3.4.  Sound emulation
 3.5.  Tape emulation
 3.6.  Microdrive emulation
 3.7.  RS232 emulation
 3.8.  Floppy disk emulation
 3.9.  Multiface 128 emulation
 3.10. Multiface 3 emulation
 3.11. Joystick emulation
 4.    Using the built-in debugger
 4.1.  Debugger panel
 4.2.  Arguments of commands
 4.3.  Commands
 5.    Notes on the emulator internals


1. Introduction
---------------
Please, carefully read this manual and the man page.  Do not write me email
with questions answered in here, as such letters are going to be ignored:
I have too many other things to do to answer the same questions over and over
again.

XZX is a portable emulator of Sinclair ZX Spectrum 48K/128K/+3 (8-bit home
computers made by Sir Clive Sinclair) and Pentagon/Scorpion, Spectrum clones
made in Russia, for machines running Unix and the X Window system.  XZX is
completely written in C and based on XZX 1.0.2 by Des Herriott.

XZX emulates

 o Spectrum 48K, 128K, +2 and +3, Pentagon and Scorpion,
 o Interface I with up to 8 microdrives,
 o Multiface 128 and Multiface 3 (if you have the ROM images),
 o BetaDisk 128 interface by Technology Research Ltd with 4 disk drives,
 o +D interface by Miles Gordon Technology with 2 disk drives,
 o Kempston mouse,
 o Kempston joystick and
 o built-in machinecode monitor.

XZX loads from

 o snapshots in .SNA, .Z80, .SLT or .DAT format,
 o tape images in .TAP, .TZX, or .VOC format,
 o microdrive cartridge images in .MDR format,
 o disk images in .DSK, .TRD, .FDI, .SCL, HOBETA, .MGT or .IMG format,
 o screen dumps in .SCR format and
 o poke instructions in .POK format.

XZX saves to

 o snapshots in .SNA, .Z80 or .SLT format,
 o tape images in .TAP format,
 o microdrive cartridge images in .MDR format,
 o disk images in .DSK, .TRD, .MGT or .IMG format and
 o screen dumps in .SCR format.


1.1. Registration
-----------------
Since version 2.2.0 XZX is a shareware program.  The program is not completely
functional, and the parts which are left out are included when you register.
You are encouraged to give this demo version to anybody if you do not change,
or remove anything from the package.

The registered version of the emulator differs from the shareware version in
the following respects:

 o supports loading from .VOC files,
 o emulates the +3 floppy controller chip at Z80 IN/OUT level,
 o supports disk images in Pentagon/Scorpion mode,
 o supports printing through the +3 CENTRONICS port,
 o emulates the BetaDisk 128 interface with 4 disk drives,
 o emulates the +D interface with 2 disk drives,
 o has an enhanced built-in debugger,
 o uses Motif for the user interface and
 o many more.

If you register, you get the fully working version, and the following utilties:

 o TAP2VOC  - Converts a .TAP file into a .VOC sound sample file, to write to
              tape, or to load into the emulator.
 o TAP2TZX  - Converts a .TAP file into a .TZX file to load into the emulator.
 o TZXINFO  - Displays informations on a .TZX file including block types, flow
              control and messages etc.
 o EMPTYTRD - Creates empty .TRD disk images.
 o HOB2TRD  - Copies Hobeta files to .TRD disk images.
 o TRD2HOB  - Extracts Hobeta files from .TRD disk images.
 o HOB2SCL  - Copies Hobeta files to .SCL files.
 o TRD2SCL  - Converts .TRD disk images into .SCL files.

You will also receive the complete source of the emulator and the above
utilities, and you will be kept informed about future updates.

You can register for the actual release and the next two updates.  They will be
sent by email.  The registration fee is EUR 25, USD 25.  German customers can
transfer DEM 40 to my giro account (request the number by email).  Foreign
customers can send money in cash to the following address:

  Erik Kunze
  Nebelhornstrasse 30
  D-82223 Eichenau
  Germany

Cheques (Deutsch Mark on a german bank, or Eurocheques) can also be accepted.
Please do not use other currencies than Deutsch Mark (DEM), and do not fill in
the place you live (leave it blank).

When sending registrations, please either print your order and address or use
block capitals to aid readability.  If you use a direct transfer, please try
also to send me an email with details of the payment etc.

If you registered XZX, please do not give your copy to anybody.  And I do mean
anybody.  If I find your personalized copy of XZX being spread around, your
registration gets automatically cancelled, which means no support and no more
updates.

Beside the registration every donation is welcome.  If you want to send me
spare Spectrum parts please contact me by email.  At the moment of writing
(March 1999) my email address is Erik.Kunze@fantasy.muc.de.


1.2. Distribution
-----------------
The FTP sites where you can look for to fetch XZX are the following and their
mirrors.  The newest version (or any of them) is not necessarily on each of
these sites.

  ftp://sunsite.unc.edu/pub/Linux/system/emulators/zx/
  ftp://ftp.void.jump.org/pub/sinclair/emulators/unix/
  ftp://ftp.nvg.unit.no/pub/spectrum/emulators/spectrum/unix/

The latest news and files are always available from XZX's homepage.  This page
gets updated at least every week, sometimes even every day.

  http://www.philosys.de/~kunze/xzx/

There is by now a great lot of Spectrum-related information and software
available on the net.  A good starting point is the FAQ (Frequently Asked
Questions) maintained by Philip Kendall.  It can be found at

  http://www.kendalls.demon.co.uk/cssfaq/index.html

If you have access to internet newsgroups, take a look at comp.sys.sinclair,
where many Sinclair enthousiasts meet and share thoughts.  You will find lots
of well-informed people there.


1.3. Reporting bugs
-------------------
You are welcome to send notes/bug-reports to me.  But please check if not
already in the list (TODO), or if it was not just a misunderstanding -
otherwise, I may probably not find time to do anything else than reading mails
in the future :-)

To report a bug send an email to xzx-bug@fantasy.muc.de.  Be sure to include a
short description of your system and the output from the following commands
'xzx -version', 'xzx -help' and 'ident xzx' together with the bug report
itself.


1.4. Credits
------------
Thanks are due to lots of people, including:

  Des Herriott, the author of the original emulator;

  Nic Percival <nmp@mfltd.co.uk>, who provided innumerable useful ideas,
  and spotted quite a few bugs;

  The authors of xtrs, a TRS-80 emulator, for inspiration on dealing with
  BCD arithmetic, and letting me use their disassembler module;

  Gerton Lunter for his excellent hardware (and .Z80 format) description
  from Z80 2.01, his MS-DOS Spectrum emulator and for giving me the
  permission to use the keyboard layout picture from his emulator.

  Arnt Gulbrandsen (author of JPP, another MS-DOS Spectrum emulator) for
  some good ideas, and letting me use his FTP site;

  Razvan Surdulescu for the on-screen-dialogs;

  Anders Hallstroem, who provided innumerable ideas and source code for the
  video emulation and spotted quite a few bugs;

  Derik van Zuetphen for giving me the permission to distribute his program
  CPCFS together with XZX.

  All those who alpha tested the program and sent fixes/updates etc. -
  too numerous to mention here - see the ChangeLog for major contributors.

  The following reference materials were used during the construction
  of the emulator:
    The Complete Spectrum ROM Disassembly - Melbourne House;
    Programming the Z80 - Rodney Zaks.


2. Using the emulator
---------------------

2.1. Setting up your environment
--------------------------------
To select the default X server to connect to:

  DISPLAY=:0; export DISPLAY	(sh)

  setenv DISPLAY ":0"		(csh)

For remote server, use the terminal name instead.  Also, use xauth(1) or
xhost(1) to give the server needed permissions to make connection.


2.2. Starting the emulator
--------------------------
If you followed the instructions given in the INSTALL file carefully, you can
start the emulator by typing 'xzx'.  If the emulator is started with no
snapshot file as a command line argument, it will reset the machine and start
either Sinclair BASIC (48K mode), or display the start-up menu (128K and +3
modes).  If exactly one argument is passed (not counting options), the emulator
assumes that it is a valid snapshot and tries to load and start it.

The emulator requires ROM images in order to run programs.  Every emulated
hardware (Spectrum models and additional interfaces) requires its own ROM set.

  Hardware           Filename         Size     Included

  Spectrum 48K       spectrum.rom     16K      yes
  Spectrum 128K      128.rom          32K      yes
  Spectrum +2        plus2.rom        32K      yes
  Spectrum +3        plus3.rom        64K      yes

  Pentagon           pentagon.rom     48K      no
  Scorpion           scorpion.rom     64K      no

  Interface I v1     if1-v2.rom        8K      yes
  Interface I v2     if1-v2.rom        8K      yes

  Multiface 128      mf128.rom         8K      no
  Multiface 3        mf3.rom           8K      no

Amstrad, who own the copyright for the Spectrum ROMs, allow free distribution
of ROMs for emulation purposes.  Other copyright holders do not!  Please do not
make illegal copies of the ROM software.

I have neither sought nor received permission from anybody to distribute copies
of the ROM software.  I discourage your making illegal copies of this or any
software.  I will not accept any sort of responsibility if you illegaly copy
the ROM software.  I am not a lawyer, and am in no position to advise you on
what is legal.


2.3. Options
------------
Options are specified as X Resources and can be overwritten by the command line
options.  They use the same spelling.  Note that the shortest unique spelling
of a resource/option is acceptable, e.g. 'xzx -ma 128' is equivalent to
'xzx -machine 128'.

An almost complete list of all valid options is available from the man page.
However, the emulator prints out a short list when started with the option
'-help'.


2.4. Configuration file
-----------------------
Since version 2.6.1 the emulator saves the current active settings on exit. The
file is named <.xzxrc> and is located in the user's home directory.  To load
this file into the emulator, add a line to your display specific X resources
file.

  $ cat /home/<user>/.Xdefaults-<display>

    #include "/home/<user>/.xzxrc"

Replace <user> with your login name and <display> with the hostname of your X
display.  Here is an example:

  $ cat /home/erik/.Xdefaults-fantasy.muc.de

    #include "/home/erik/.xzxrc"


2.5. On-Screen-Dialogs
----------------------
Throughout this chapter, we will refer to the On-Screen-Dialogs as "OSD".

At any point in the emulator, you can hit F1 to pop up the OSD's.  Other keys
might work as well, but will place the cursor on different lines of the dialog.

You can use the UP/DOWN arrows to move the cursor UP/DOWN.  ESC will leave the
current dialog and return to the upper level dialog or back to the Spectrum.
ENTER will select the option next to the cursor.

If there is a shortcut key listed next to any option on the current dialog
screen, you can hit that shortcut key (typically, a Function Key) and it will
place the cursor on the appropriate line (this in fact is the reason why when
you hit F1 it enters the dialogs and places the cursor on the line that says
"Keyboard layout ... F1").

In the file selector dialog (for loading/saving snaps/taps etc.), you can also
hit TAB to toggle between selecting a file using the cursor and the "input box"
which allows you to type in the name of a file or directory.  The file selector
works much like any regular GUI file selector : hitting ENTER on a directory
will chdir to that directory; hitting ENTER on the name of a file will load
that file.

In the "input box" you can type a file or directory name of up to 256
characters (the input field scrolls the file name left/right if it does not fit
in the space alloted).  You do not need to specify an extension to the file,
unless you want to; by default the right extension is always choosen (".tap"
for tape files, ".z80" for snaps etc.)

Unfortunately, there are currently no editing facilities whatsoever in the
input box.  Hit TAB twice to clear it.

The menus:

 Keyboard Layout
	Displays a picture of the way the keyboard is laid out on the real
	Spectrum 48.  Useful if you can not remember that one key combination
	for getting "CHR$" :-)

 Save snapshot
	Pops up a file selector for saving a snapshot of the memory of the
	Spectrum in whatever current mode it is in.  The format is either .SNA,
	.Z80 (compatible with Gerton Lunter's Z80 emulator version 3.05+) or
	.SLT.  See description above on how the file selector works.

	If the file you are trying to save already exists then you will be
	given the message "Overwrite file ? [y/n]".  You can reply 'y' to
	overwrite, any other key to abort.

	If you are saving a .SLT file, then the level data will be appended to
	the newly saved file.

	This option is good for cheating at games.

 Load snapshot
	Ditto for loading snapshots.  If you get a snapshot file with other
	files called .DAT then these will be dealt with automatically.  Just
	load the snapshot and if the filenames of the .DAT files are wrong the
	file selector will appear and you have to select the correct .DAT, or
	press ESCAPE.  If the snapshot is in .SLT format then emulator deals
	with it automatically.

	Note that any hardware like SamRam or MGT will be stripped off and
	ignored, if that piece of hardware was paged in at the time the
	snapshot was saved, then it might not work.

 Save screenshot
	Produce a .SCR file containing a screenshot of the screen of the
	emulator in the current state.

 Tape Options
   Select inputfile
	Pops up a file selector for choosing a tape file.  The file has to be
	in .TAP (the Z80 emulator compatible files, not the Warajevo emulator)
	or .TZX format and will be used for LOADing.

	To load the file you must either use the 128K/+3 BASIC tape loader
	(just press return) or type in 'LOAD""' at the BASIC prompt.

   Close inputfile
	Close inputfile.

   Browse through inputfile
	The position of the file pointer into the inputfile can be changed.
	If you, for instance, type 'LOAD""' instead of 'LOAD"" CODE', the first
	header is read, and you would have to read all other headers before
	prompting for selection of a tape file again.  With this option you can
	change the file pointer.

	As long as the virtual tape player is playing back a .TZX file,
	browsing through the inputfile is disabled!

   Playback inputfile
	Start and stop the virtual tape player.  See chapter "Tape emulation".

   Quick loading
	The emulator loads TAP blocks and TZX blocks of ID 0x10 in one block,
	rather than bit by bit, if the LD_BYTES routine in the ROM is used.
	Turn this off if the tape file does not load properly.

   Loading noise
	If set to 'N', then no sound while loading, otherwise you get an
	approximation of the sound depending on how many reads from ULA are
	happening.  Having it switched on will require more CPU time.

   Select outputfile
   Close outputfile
	Ditto for SAVEing.

 Reset
	Resets the Spectrum in whatever current mode it is in.

 NMI
	Generates an NMI.  If you have enabled the Multiface, it will enter the
	Multiface.  If you can get the file Genie 128 software then you have a
	push button disassembler on your hands.

 Debugger
	Calls the built-in debugger, which contains some options interesting
	even to those who has no interest in machine code programming.  The
	monitor is explained in detail in the chapter "Using the built-in
	debugger".

 Generic options
   Speed
	Controls the emulation speed.  The default setting is 100, which causes
	the emulation to never run faster than the real machine.  A higher
	value makes the emulator faster, a lower one makes it slower.  The
	setting 0 means to run as fast as possible, without limiting speed.

   Fast mode
	Enables special speed mode.  If this mode is enabled, it will cause the
	emulator to disable any speed limit, turn sound emulation off and use a
	1/10 refresh rate, so that it will run at the maximum possible speed.

   Refresh rate
	How often do we update the screen (a value of 2 here means that we draw
	the screen every 2 frames).  Change this if you have games with
	flickering sprites.

   Video cache
	Enables a video cache that can speed up the emulation when little
	graphics activity is going on; it is especially useful when you	run the
	emulator on a networked X terminal, as it can reduce the amount	of
	bandwidth required.

   Use XSync()
	Causes the emulator to call the X11 function XSync() before updating
	the emulation window: this might be necessary on low-end systems to
	prevent it from stealing so many system resources that it would become
	impossible for the user to interact with it.

   Grab pointer
	This option actively grabs control of the pointer.  Further pointer
	events are reported only to the emulator.  The pointer is restricted to
	stay contained in that window.

   Issue
	Emulate the specified keyboard issue.  Issue 3 is by far the most
	common.  Occasionally a program will need this option to be set to 2
	(usually an old program for instance Spinads) otherwise the keys will
	not respond.  Note that all 128K Spectrums were issue 3 and some 48K
	Spectrums issue 2, but not that many.

	A .Z80/.SLT file will change this value when you load it!

   Debug
	Debug level : you should not have any reason to mess with this one.  It
	just allows developers to type in a "debug level number" and display
	debug information depending on what the debug level is.

 Sound options
   Speaker
	Enable/disable the speaker sound (see chapter "Sound emulation").

   AY 8912
	Enable/disable the AY sound (see chapter "Sound emulation").

   BEEP
	Enable/disable the BEEP sound (see chapter "Sound emulation").

 Joystick Options
   Up, Down, Left, Right, Fire
        Select the keyboard keys that are used for the Kempston emulation.
	This does not affect the real joystick on Linux/FreeBSD.

	Press ENTER to activate the selection and then press the key you want
	to map to the joystick key.  Theoretically you can choose every key on
	your keyboard but some of them are already mapped to other functions
	(for example the function keys).

   Analogue joystick
	Turn on/off the ussage of the analogue joystick.

   Tolerance
	This specifies how far from centre your joystick must be displaced
	before it registers with the emulator as being moved.  The default
	displacement tolerance is 20.  You may have to experiment with this to
	get the best response for your joystick.

   Autofire
	This specifies how many times in a second the pressing of the fire
	button should be simulated.

   L-R Juggle
	This specifies how many times in a second the pressing of the left and
	right direction	button should be simulated.  See also section 'Joystick
	emulation'.

 Interface I/+3 Options
   Select microdrive
	The emulator emulates 8 microdrives, the maximum amount the Interface I
	software can handle.  Select the microdrive which will be used by the
	next three menu items.

   Insert cartridge
	Pops up a file selector for selecting a microdrive cartridge file and
	inserts it in the drive.  Do not insert one file into more than one
	microdrive; this will cause problems with the buffering done by the
	emulator as well as the Interface I, and might result in data loss.

   Take cartridge out
	Remove a cartridge from a drive.

   Translate NL
	If set to to "Y", the emulator converts linefeeds (ASCII 10) to
	carriage returns (ASCII 13) on RS232 input, and vice versa on RS232
	output.  This is necessary if you are transferring textual data from
	Unix to the emulator, since the Spectrum expects to see a carriage
	return as end-of-line, and Unix uses linefeeds.  Do not use it if you
	want to transfer binary data.

   Strip CR
	If set to "Y", the emulator will strip carriage returns on RS232
	output.  This is only useful when listing BASIC programs to the
	Interface I "T" channel.

   Select drive
	A Spectrum +3 can have 2 disk drives which are named "A" and "B".
	Select a drive the next two menu items act on.

   Insert disk
	Pops up a file selector for selecting a disk image file and inserts it
	into the drive.

   Take disk out
	Remove a disk from a drive.

 Choose architecture
   Spectrum 48/128/+3/Pentagon/Scorpion (reset/no reset)
	Should be self explanatory : choose a certain architecture for the
	Spectrum emulation and do or do not perform a reset upon exiting the
	OSD's.

   Interface I
   Multiface
	Enable/disable emulation of those two extensions.

 Quit
	Back to the shell.


2.6. Offix drag and drop support
--------------------------------
I'm supposing you understand what "drag and drop" means. It is an intuitive way
to exchange data between programs.  The emulator optionally supports the OffiX
DND protocol.  OffiX is a free implementation of drag and drop for X which is
gaining popularity on Linux at least.

You can drag a file from other Offix-enabled programs and drop it on the
emulator window, whereupon the emulator will try to load it as a snapshot.

See http://leb.net/OffiX for more details.


3. Hardware emulation
---------------------

3.1. Z80 emulation
------------------
The emulator provides an accurate Z80 core emulation, with emulation of all the
opcodes (both documented and undocumented ones) and accurate timing.  Unlike
other emulators, the emulation of all the chips is cycle accurate, and tries to
emulate timings as precisely as possible while trying to use as little
processor power as possible.


3.2. Keyboard emulation
-----------------------
Those of you that have at some time used a Spectrum know, that the keyboard of
this little computer is something very strange, with a lot of keywords and
symbols on and around each key.  If you have not seen this keyboard (or have
somehow managed to forget some bit of information that is on it) there is a
copy of it available from the online help.

Support for the original Spectrum keyboard is emulated as follows:

Left Shift emulates Caps Shift and this is guaranteed to work (only) for the
basic Spectrum keys, that is letters, numbers and Space.  Alt/Meta emulates
Symbol Shift, Control emulates Extend mode.  Also guaranteed for basic Spectrum
keys.  Return emulates Enter, Backspace and Delete emulate CapsShift-0
(Rubout).  The cursor keys emulate CapsShift-5 to 8, or plain 5 to 8 (Cursor
Joystick).  The Tab key toggles between the two.  Escape emulates CapsShift-1
(Edit).  Right Shift and other local modifier keys(*) work locally: The
character printed on your key is emulated wherever possible.  This actually
goes for all "non-Spectrum" keys with or without local shift.

The keyboard emulation is not perfect and it can get confused at times.  If you
think this has happened, try presssing Bar or Backslash which clears all
Spectrum input ports.

The emulator turns keyboard autorepeat off when the mouse pointer is in the XZX
window.

(*) like some "Alt" keys that are used to get extra characters.  On both DEC
and Sun (when I tried), this key is not decoded as Alt or Meta but as
Mode_switch.


3.3. Screen emulation
---------------------
The emulator draws the picture like a real Spectrum, so any programs which
synchronize with the TV beam do perfectly work.  Multicolour effects emulated
as well.  However, correct working of all of the multicolour effects needs
exact emulation of the delay introduced by interaction between the Z80
processor and the Spectrum ULA chip; which is a very hard task.


3.4. Sound emulation
--------------------
The Spectrum beeper and 128K's sound chip is played through the audio device
and looks very well and clear.  Due to precise timing, even very time-depended
sound routines (for example, 'Wham the music box') work quite good.  Many
other polyphonic tones sound excellently, for example in 'Vectron'.

All sound chip effects are implemented, such as changing of noise pseudo-
frequency, digital sound effects and speech synthesis.

On systems without an audio driver the BASIC BEEP is emulated through X
server's bell.


3.5. Tape emulation
-------------------
The direct loading from tape in the emulator is not possible.  Instead it, the
emulator uses files with the extension .TAP or .TZX for tape emulation (in
further called tapes).  The tapes are organized on flexible way that allows
different tapes for saving and loading blocks.  The tape format is compatible
with Gerton Lunter's Z80 emulator.

The loading and saving are realized by classic LOAD and SAVE commands, as on
real Spectrum.  If LOAD, for any reason, fails the consequences are the same
as on original Spectrum, which in conventional cases results in "R Tape loading
error", but with headerless files this need not be the case.

Every time the ROM wants to load a block, it is presented the next block on the
tape.  It is handled as it would if the block was loaded from tape, so that if
the ROM needs a header and is presented a data block, it will skip it. The
header will however be considered to be read.

Each saved block is appended to the end of the tape, like it would if you were
actually saving to real tape.


3.6. Microdrive emulation
-------------------------
Principally, microdrive emulation needs less describing than tape system
emulation.  The emulator uses files with extension .MDR (in further called
cartridges) for emulation of real microdrive cartridges.

A sample cartridge file MDRTEST.MDR is supplied which contains a short test
program to exercise the microdrives.  Here is how to make it go.

First create a scratch cartridge file with a command such as:

  dd if=/dev/zero of=SCRATCH.MDR bs=137923 count=1

Alternatively, there is a shell script, mkcart, to do this; just type

  mkcart SCRATCH.MDR

Start the emulator with the additional options '-m1 MDRTEST.MDR -m2
SCRATCH.MDR'

Now type RUN and hit enter.  You will be prompted for a source drive, type '1'.
You are then prompted for a scratch drive, type '2'.  The cartridge in drive 2
will be formatted and various operations carried out on it to prove that the
thing works.

If all goes well you will get an "Ok - Phew!" message at the top of the screen.

Microdrive emulation is very fast, typically much faster than on real
Spectrum.  However, some operations which use intensively ROM switching (for
example, MOVE) may be much slower than on original machine.


3.7. RS232 emulation
--------------------
The Interface I "B" and "T" RS232 streams are connected to stdin and stdout of
the emulator.  So to get your listings printed on a PostScript printer a
pipeline such as:

  xzx | dos2unix | mp | lpr -Pps

should work; dos2unix allows for Interface I "T" streams turning end of line
into CRLF.  If you do not have dos2unix, you can use 'tr -d \015'.  And if you
are using a SYSV-ish machine, you are more likely to have lp than lpr.  Check
your manual pages.  There are also two run-time options, '-crlf' & '-strcr',
which alter the behaviour of RS232 I/O.  Read the manual page for a full
description of what they do.

Inside the emulator you can type in or LOAD a BASIC program then do something
like 'OPEN#n,"T": LIST #n: CLOSE #n' to send the program to stdout.

Note that this works by trapping the Interface I ROM and will not work if you
substitute a modified ROM image.

128K RS232 emulation does not work, since I do not have any documentation on
the 128K ROMs.  If anyone out there does, feel free to add the emulation.


3.8. Floppy disk emulation
--------------------------
As of release 0.7, XZX has been able to emulate a Spectrum +3, with partial
support for +3DOS, the floppy disk operating system.  At release 0.7, the disk
operations CAT, COPY, MOVE, ERASE, LOAD & SAVE are usable.  FORMAT is not yet
available.  The disk format used is identical to that used by Marco Vieth's
Amstrad CPC emulator, so disk images should be interchangable.

An extra program, ddtrans has been supplied, with which you can translate
Amstrad CPC (and Spectrum +3) disks to formats usable by XZX and Marco Vieth's
Amstrad CPC emulator.  It performs a very similar task to Marco's CPCTRANS
program.  It should be possible to read CPC/+3/PCW format disks with the Unix
dd command and use ddtrans like so:

  $ dd if=/dev/fd0 of=image bs=727280

    # or whatever Unix device your FD is on

  $ ddtrans

    # option 1: set 'dd' file to <image>
    # option 3: copy 'dd' file -> Image

This will create a file named <default.dsk> which the emulator will be able to
read.  Play with ddtrans; it is menu-driven and pretty straightforward to use,
though documentation is lacking at the moment.

In this manner, you can transfer all your old Spectrum +3 disks for use with
XZX, although you will need a +3 with a 3.5" disk drive to do this...

ddtrans can also be used to create blank, formatted disks for use with XZX;
select option 5 from ddtrans' main menu.  You will be presented with a variety
of formats readable by +3DOS; choose whichever suits you best.


3.9. Multiface 128 emulation
----------------------------
Multiface 128 works on any Spectrum 48/128 in any mode.  It can be activated
anytime; it is immaterial what program is inside the Spectrum at that moment
or how and what from it was loaded. Multiface does not save programs, but
computer contents (compressed RAM image).  To use it, trigger a NMI and then
select function by pressing the relevant key (inversely printed) of the
displayed command.

  o exit - to exit to BASIC

    To either

      o leave the program and Multiface 128 entirely
      o study/alter/customize the program

    All efforts are made to preserve the program intact.  The main pre-
    condition is the existence of standard system variables or else the
    Spectrum will crash. Successful exit gives full access to a program.  To
    restart it, if needed, you need to know starting line or address.  By re-
    activating the Multiface, a program can then be saved, etc.  EXIT is
    sometimes impossible in 128k (when Edit ROM is paged on and Spectrum ROM
    is off) and in such case it does not appear on the menu at all.

  o return - to continue the program

  o save - to proceed to SAVE routines:

    o Input the name of the program - up to 9 characters or just press ENTER
      to input RUN automatically;
    o Save to: tape, hyper-tape, cartridge, disc You can save program or
      screen only by pressing _p_ or _s_.  Programs are automatically
      compressed to take minimal room possible and to load faster.  Screens
      saved on their own are not compressed.
    o FORMAT option - you should be able to format microdrive cartridges to
      100+ K. You can chage the format density by poking H2009 (8201 dec.);

        1 - default aiming at 101K or more
        2 - 96K
        3 - 91K
        4 - 86K
        5 - 82Ketc.

      Cartridges are named as programs to be SAVED.

  o tool - to access MULTI TOOLKIT routines

    o quit - to return to the opening menu

    o ENTER - to PEEK and scroll through addresses or to POKE any value to any
      address

    o SPACE - to allow you to type in a new address

    o hex - to toggle between hex and decimal display

    o reg - to show Z80 registers at time of stopping starting from the program
      counter (PC-low, hi)

    o window - to display 128 bytes at a time with full on-screen editting by
      cursor keys.

      The flashing window address corresponds to the bottom one and both can be
      changed by ENTER/SPACE keys.  Window display is in hex, but you can
      change it to

        o text - to see bytes in the window as text (in ASCII)

        o select - to inspect additional RAM banks 0-7 on 128K RAM models only

          - follow s by number 0-7

  o print - to dump screen to printer;

    For interfaces with COPY command like Kempston E or Lprint III.  By poking
    address H2008 (decimal 8200), you can turn linefeed

      o on - poke H71 (CR + LF)(default)
      o off - poke H70 (CR only)

    dump screens as text (text copy)

      o H11 (CR + LF)
      o H10 (CR only)

    on the above interfaces in EPSON default.

  o jump - not to return but jump to another address.

    Enter the address to jump at 8192/3 (low/hi).  You can jump to Spectrum
    ROM/RAM and to M128 RAM.  As Multiface RAM overshadows ZX ROM (8192-16383),
    address 8194 determines paging status: if 0, 8K RAM remains paged, poking
    1 unpages the RAM; any other value disables the jump command entirely.

    You can not only jump from here, from the main menu, you can actually
    pre-program Multiface to jump directly upon pressing the red button and
    by-pass Multiface operational system entirely.  To program direct jump
    POKE 8192-3 with the jump address and 8195-7 with a special identification
    code RUN (82, 85, 87 dec.).  Whenever you push the button you will jump to
    the predefined address and not to Multiface menu.  To return to the program
    you stopped, just use RST 0.  To revert back to Multiface normal menu and
    operation, press the red button and BREAK key simultaneously - this also
    cancels the direct jump identification code _RUN_.

    In standard mode Multiface uses 8192-11144 as a buffer (8192-13496 once you
    proceed to SAVE) and overwrites anything in there.  Using direct jump you
    have 8257-16338 of RAM available - plus all of Spectrum RAM, to which you
    can also jump to.

  o clear - to clear the extra 64K memory banks (in 128K mode only)

    You can clear anytime but it's only useful in 48K programs if extra banks
    were used previously and machine was not switched off; you should save 48K
    programs in 48K mode anyway.

In most cases - except for tape back-ups saved at hyper speed - Multiface 128
needs not to be attached to re-load programs it saved.  The only limitation if
absent is a distortion in the top part of the screen which is usually restored
during running of program.  A screen is always saved as part of program to
allow you to run programs without Multiface 128 attached.

Multiface has a software switch making it invisible.  It can prevent possible
clashes with other hardware/ software.  It is also vital to enable load
programs saved with any version of Multiface ONE, as they all can load when
Multiface is absent - or switched OFF.  As a rule, Multiface 128 can always be
activated, no matter if previously set ON or OFF.  Upon powering up the
Multiface is automatically OFF - thus loading a program saved by Multiface will
leave a corrupted screen and hyper tape back-ups will not load at all.  To
switch Multiface ON, just press its red button, which both activates the
Multiface and switches it on.  Upon _returning the Multiface will remain on.
You can switch it OFF by pressing 'o' when you are in the main Multiface menu
- 'o' toggles between ON/OFF, as shown.

Multiface has 8K ROM for its own software and 8K RAM as a buffer.  You can use
the RAM for your own m/c or data, but not for BASIC.  The RAM must be paged to
be accessed.  Paging must be done in m/code.  IN and OUT in BASIC can not be
used.  The 8K RAM overshadows Spectrum ROM - thus anything contained in M128
RAM can't make calls to anything in the ROM, as they both occupy the same area.
Any m/c routine to be RUN in M128 RAM must be totally self-contained and
independent on the Spectrum ROM.  You can in fact make ROM calls if you jump
out of M128 RAM into Spectrum RAM, page the M128 RAM/ROM off, call a Spectrum
ROM routine, page the M128 ROM/RAM and jump back to your M128 routine.  There
are other ways and possibilities, but all in all the use of M128 RAM requires
fair knowledge of m/c.


3.10. Multiface 3 emulation
---------------------------
As of release 2.7.0, XZX has been able to emulate a Multiface 3.  Multiface 3
works on Spectrum +3 only.  It can be activated anytime; it is immaterial
what program is inside the Spectrum at that moment or how and what from it was
loaded.


3.11. Joystick emulation
------------------------
The emulator supports Kempston joystick. The emulated joystick is controlled
by the keyboard keys, which are defined to "q", "a", "o", "p" and "space" by
default.  They can be changed during runtime of the emulator.  How this can be
done is described in chapter "On-Screen-Dialogs".

The emulated joystick can also be controlled by a real joystick.  The analogue
joystick support is only possible under Linux/Intel and FreeBSD with the
appropriate joystick driver.

If the connected joystick has more than one fire button, buttons 2, 3, 6 and 7
have special meanings to the emulator.

Button 2 simulates a sequence of fire button presses and releases.  This is
known as autofire.  The resource 'autofire' controls the frequence.

Button 3 simulates a sequence of left and right button presses and releases.
This is often used in sports simulation like Daley Thompson's Supertest.  The
resource 'juggle' controls the frequence.

Button 6 and 7 allow the control of particular emulator settings from the
joystick.  Button 6 decreases, button 7 increases the value.

If button 6 or 7 is pressed alone it changes the emulator speed.  If it is
pressed with button 2 it changes the autofire speed.  If it is pressed with
button 3 is changes the L-R juggle speed.


4. Using the built-in debugger
------------------------------
The debugger is one of the most interesting features of XZX.  It is started by
pressing F7, and it is fully transparent for Z80 programs.


4.1. Debugger panel
-------------------

	3683  CB6E      bit  5,(hl)

	AF*1D7C   AF' 0044      SZXHXVPC
	BC 0100   BC' 0A1A   F  01111100
	DE 2F6F   DE' 0007   F' 01000100
	HL 5C3B   HL' FFFF
	IX FD6C              IM 1 2 RMVL
	IY FD6C   IR  0055    1 1 1 0750
	PC 3683
	SP 5BFB

	FFF4 00   FFFC 00   0004 0B
	FFF5 00   FFFD 00   0005 78
	FFF6 00   FFFE 00   0006 B1
	FFF7 00   FFFF 00   0007 20
	FFF8 00  >0000 F3<  0008 FB
	FFF9 00   0001 01   0009 C3
	FFFA 00   0002 2B   000A C7
	FFFB 00   0003 69   000B 00

	>_

Shown above is a fairly typical debugger panel display.  It contains:

 o The instruction at the program counter (PC);
 o The values of all registers (AF, BC, DE, HL, IX, IY, SP , PC, AF', BC', DE',
   HL', IR, F, F');
 o The interrupt mode, and flip-flops IFF1 and IFF2;
 o The memory banks (128K/+3 mode only) and state of the lock bit;
 o The memory around the memory pointer.

The program counter (PC) shows the current instructions.  At the top of the
screen the program counter, values at this address and the mnemonic of the
current instruction are displayed.

The Values of the registers are displayed as sixteen-bit values.  One register
is active, and it is marked with a sign "*".  Registers F and F' are displayed
in binary form too, showing the value of each bit.

The interrupt mode is displayed below the sign "IM".  Two Z80 interrupt
flip-flops IFF1 and IFF2 are displayed below the signs "1" and "2".

The number under the letter "R" shows currently active ROM.  Fields "M", "V"
and "L" are meaningful only in 128K/+3 mode, and shows active RAM page, active
video page and status of 48K lock bit.  When in 48K mode it displays "-"
instead.

Finally, you can see the memory bytes around the memory pointer.  The memory
pointer is a default value for many instructions.  It is a sixteen-bit value
too.

The bottom line is used for entering commands and error messages.  The display
is updated after each command is processed.

All values are displayed in hexadecimal form.


4.2. Arguments of commands
--------------------------
Arguments may be numerical or string.  Numerical arguments may be entered in
a binary, octal, decimal or hexadecimal system.  There are several commands
to change the number base for the numerical arguments; see "Commands".

String arguments are, in fact, packed numeric argument.

Arguments are separated with at least one space.


4.3. Commands
-------------
The following commands are available from within the debugger.  The symbol
<word> stands for a sixteen-bit value, and <byte> for an eight-bit value.
Square brackets have the meaning of optional argument.

 r[eg]
	Move register pointer to the next register.

 r[eg] <word>
	Set the currently marked register to <word>.

 + [<word>]
	Increment the memory pointer by one or by <word>.

 - [<word>]
	Decrement the memory pointer by one or by <word>.

 = [<word>]
	Set the memory pointer to specified address <word>.  If the value is
	omitted, the assumed value is marked register.  The memory display of
	the debugger panel changes accordingly.

 <byte>
 <word>
	The contents of the address given by the memory pointer may be modified
	by entering a number followed by 'ENTER'.

 ay [<num>]
	Show the contents of ay register <num> or all.

 ay <num> <byte>
	Set ay register <num> to value <byte>.  Register number ranges from 0
	to 15.

 base
	Query number base for inputs.

 base <2|8|10|16>
	Set number base for inputs.

 bp add <num> <word>
	Set a breakpoint at address <word> in RAM page <num>.  The first byte
	of the instruction at address <word> will be replaced with #C7, a Z80
	code of instruction RST 0.  Then, when you leave the monitor and
	continue executing of the program, incoming of this instruction will
	return you to the monitor.

 bp rem[ove] [<num>]
	Remove breakpoint <num> or all.  The original instructions will be
	restored.

 bp show [<num>]
	Show informations on breakpoint <num> or all.

 copy <word1> <word2> <word3>
	This is used to copy a block of memory from one location to another -
	it is intelligent in that the block of memory may be copied to
	locations where it would overlap its previous location.  Copies <word3>
	bytes from address <word1> to address <word2>.

 dis [<word>]
	Display a page of disassembly starting from the address held in the
	program counter (PC) or from address <word>.  Useful to look ahead on
	your current position to see what instructions are coming up.  Hit
	'ESCAPE' to return to the debugger panel display or another key to get
	a further page of disassembly.

 fill <word1> <word2> [<byte>]
	Fill memory between specified limits with zero or a specified <byte>.

 go [<word>]
	Execute code from a specified address.  It can be either the current
	value of the program counter (PC) or <word>.  Once this is entered, the
	debugger returns and execution is transferred to the specified address.
	If you wish to return to the debugger panel after executing code then
	set a breakpoint at the point where you wish to return to the debugger.

 im <0|1|2>
	Set Z80 interrupt mode.

 iff1 <0|1>
	Set interrupt flip-flop IFF1 to value.

 iff2 <0|1>
	Set interrupt flip-flop IFF2 to value.

 q[uit]
	Leave the debugger.


5. Notes on the emulator internals
----------------------------------
You are not supposed to make changes according to the copyright.  However if
you are planning to add or modify XZX, contact me by email.

I recommend reading the rest of this section.  There are a couple of points
worth keeping in mind.

XZX is built on top of a (mostly) full Z80 emulator, with added routines to
support keyboard and video I/O through an X Windows interface.  The hardware
emulation is based on the Spectrum models design.

The Z80 emulator is written to be portable to most C environments.  It is
possible to build a faster emulator by sacrificing this portability (such
emulators have been built for 80x86 and 680x0 machines), but that was not the
goal.  Memory accesses are handled through a function call interface, allowing
to cleanly emulate memory-mapped devices.

Since XZX uses a segmented memory model, you should use the calls
Machine->readMem() and Machine->writeMem() to access memory.  It is also
possible to get to the memory directly by using RealMemory[ROM0..3] and
RealMemory[RAM0..7], which are 16K pages, but make sure you know what you are
doing.

If you need to report errors/messages, there is a function to do this:
Msg().  Call it like this:

  Msg(int sev, char *fmt, ...);

where <sev> can be one of M_INFO, M_WARN, M_ERR, M_FATAL or M_DEBUG and <fmt>
is a printf-style format string.  If <sev> is M_FATAL, the emulator will shut
itself down with an exit code of 1.

Several unused Z80 instruction have special meaning to XZX:

  C7    - Calls the the built-in debugger.

  ED FB - Activates the level loader trap.  Used in hacked-up multiload games.

  ED FC - Activates the tape loader trap.
  ED FD - Activates the tape saver trap.

  ED FE - Activates RS232 input.  A byte read from stdin is placed in the
          accumulator.
  ED FF - Activates RS232 output.  The accumulator is written to stdout.