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.  On-Screen-Dialogs
 2.5.  Offix drag and drop support
 3.    Hardware emulation
 3.1.  Keyboard emulation
 3.2.  Screen emulation
 3.3.  Sound emulation
 3.4.  Tape emulation
 3.5.  Microdrive emulation
 3.6.  RS232 emulation
 3.7.  Floppy disk emulation
 3.8.  Multiface 128 emulation
 3.9.  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) 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 either a Spectrum 48K, 128K or +3, Interface I with up to
8 microdrives, Multiface 128 (if you have the ROM image) and Kempston joystick.
XZX loads from .SNA, .Z80, .SLT, .DAT, .TAP, .TZX, .VOC, .MDR and .DSK files
and saves to .SNA, .Z80, .SLT, .TAP, .MDR, .DSK and .SCR files.

Although a usable Spectrum is emulated, a few features are missing; sound is
only emulated on some hardware, for obvious reasons, and ZX printer support is
absent.


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 draws border and screen line-by-line,
 o emulates the +3 floppy controller chip at Z80 IN/OUT level,
 o supports printing through the +3 CENTRONICS port,
 o has an enhanced built-in debugger,
 o uses Motif for the user interface,
 o allows window scaling without restarting 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.

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 DEM 40, US$ 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
(April 1997) 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://ftp.gns.getronics.nl/pub/os/sinclair/emulators/unix/
  ftp://ftp.nvg.unit.no/pub/spectrum/emulators/spectrum/unix
  ftp://sunsite.unc.edu/pub/Linux/system/emulators

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 Damien Burke.  It can be found at

  http://www.jetman.demon.co.uk/speccy/faq/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 Hallstrm, who provided innumerable ideas and source code for the
  video emulation and spotted quite a few bugs;

  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.


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. 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.  The sharware version lets
	you select .VOC files too.

	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 input .TAP 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".

   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 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
   Flashing
	Toggles "flash" emulation on/off.

   Border
	Toggles "border" emulation on/off.  At this point, the emulator does
	not emulate the border exactly as it is done in the real spectrum
	(drawing it line by line); rather it updates the "X window" surrounding
	the main window of the Spectrum.  Consequently, if you have a game that
	tries to do fancy things with the border (like Sentinel or Aquaplane),
	the emulator will go into a coma because it tries to reupdate the
	entire border window time and again.

	To make the story short : turn this off if you get a game that makes
	the border flicker really fast and makes the emulator REALLY
	unresponsive to keypresses.

   Ms/frame
	On the Spectrum, an interrupt occurs 50 times a second (every 20 ms).
	The window between two interrupts we call a frame.  During each frame,
	one new picture field is sent to the TV.  During each frame, the Z80
	CPU manages to do some amount of processing (including servicing the
	interrupt).

	The minimum real time in milliseconds that elapses beetween interrupts,
	that is the minimum number of milliseconds in a frame. Defaults to
	20 ms.

	Raise this value to make the emulation "slower than life".  This is
	more CPU friendly than the slowdown option since the emulator process
	spends the spare time halted (waiting for a timer signal).  If you have
	a powerful machine with a high-resolution timer, then you can run the
	emulation extra fast by lowering this value.

   Fast
        Normaly the emulator tries to run at the speed a real Spectrum runs.
        However it may be useful to run the emulator as fast as possible.

   Slowdown
	Increase this number if the emulator runs too fast on your machine.
	This just tells the emulator to insert a "nop" after each instruction
	executed to slow down the emulation.  You will just get stuck if you
	set it too high.

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

   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").  If
	you run the emulator under SunOS/Solaris you can not have Speaker and
	AY sound at the same time.  Activating the speaker sound will
	automatically turn off the AY sound and the other way around.

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

   Volume
	Change the volume of the XBell used for Spectrum system beeps.  This
	works for speaker emulation under SunOS/Solaris too.

 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.

	This option applies to analogue joystick only.

   Calibrate
	Calibrate the analogue joystick.  You always have to call this before
	you can use the joystick.  It is not called automatically at the
	startup of the emulator anymore.

 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 (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 128
	Enable/disable emulation of those two extensions.

 Quit
	Back to the shell.


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

If you are running the emulator on a slow computer, try doubling the interrupt
frequency (switch '-ms').  Most programs poll the keyboard by interrupt, in any
case the ROM does, and doubling the frequency with wich this happens will make
the emulated Spectrum react much more quickly to your keystrokes.

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

If XZX was compiled with X terminal support, then the the keyboard emulation
works slightly differently.  When you are actually using an X terminal, you
will in fact need to have keyboard autorepeat activated.

(*) 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.2. Screen emulation
---------------------
The screen is checked for changes 50 times an emulated second, and they are
subsequently displayed on the monitor.  At this point, the emulator does not
emulate the border exactly as it is done in the real spectrum (drawing it line
by line); rather it updates the "X window" surrounding the main window of the
Spectrum.

See also the refresh options in chapter "On-Screen-Dialogs".


3.3. Sound emulation
--------------------
The Spectrum beeper is emulated on PC's by the internal speaker and on Sparc
style systems by the audio device.  Because every 1/50th of a second the screen
has to be updated, and this takes a little time even if there are no changes,
the sound is a bit harsh.

The sound of the Spectrum 128K's sound chip is only played through the audio
device.  Some programs use the sound chip and the beeper at the same time,
and this will not work properly on Sparc style systems.


3.4. Tape emulation
-------------------
The direct loading from tape in the emulator is not possible.  Instead it, the
emulator uses files with the extension .TAP 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.

The emulator can load programs from sound sample files if they are in Creative
Labs' VOC format.  This is very useful for multi level games; the levels on
the tape can be put in VOC samples, and loaded when needed without having to
re-install the tape recorder.  The emulator keeps track of exactly how much
time elapses during the emulation of a program, and every time the emulated
Spectrum program reads the EAR port, supplies it with the right sample.

Because the emulator has to keep track of the emulated time, and also has to do
some calculation every time the EAR port is read (which a program does rather
often when loading), the emulation speed drops considerably when playing back
VOC sample files.  So loading programs using VOC files may take longer than
loading them directly.  On the other hand, it is not at all necessary to have
the emulator run at 100% now, so you can turn on fast mode (see chapter
"On-Screen-Dialogs").

You can take a sample with any sampler program.  The emulator supports most VOC
block types.  It does not support compressed blocks, though; use full 8 bit
samples.

To play back a VOC file, go to the file options, and select a VOC file as input
file.  The VOC file is now in stand-by until you start the virtual tape player
("Playback inputfile").  The emulator will now play the VOC file to the end
(irrespective of what the emulated Spectrum program is doing with the sound
supplied to the EAR port!).

It is possible to pause the play-back at any time.  Do not do this while
loading, since it will immediately result in a tape loading error.

Newer versions of the emulator can also load from files in ZX Tape format (TZX).


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


3.6. 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.7. 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.8. Multiface 128 emulation
----------------------------
XZX emulates a Multiface 128 but does not supply the Multiface 128 ROM because
it is copyrighted.  You can extract the ROM from the ROMS.BIN file that comes
with Z80 (a Spectrum emulator for the PC); all you need to know is in the
TECHINFO.DOC file that comes with Z80.  Note that I do not condone any possible
breach of copyright; your use of this ROM is only permitted if you own a real
Multiface 128.  You would be in breach of Romantic Robot's copyright if you
were to extract the ROM without owning the real thing.

An exerpt from the original Multiface 128 documentation comes with Gerton
Lunter's Z80 emulator.


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


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

 c[opy] <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.

 f[ill] <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.

 q[uit]
	Leave the debugger.

 base
	Query number base for inputs.
 bin
	Set number base for inputs to 2.
 oct
	Set number base for inputs to 8.
 dec
	Set number base for inputs to 10.
 hex
	Set number base for inputs to 16.

 im <0|1|2>
	Sets Z80 interrupt mode.
	
 iff1 <0|1>
	Set interrupt flip-flop IFF1 to value.

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


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.

 o Since XZX uses a segmented memory model, you should use the calls RD_BYTE(),
   WR_BYTE(), RD_WORD() and WR_WORD() 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.

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

 o Several unused Z80 instruction have special meaning to XZX:

   ED 00 - 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.