                                    XZX-Pro

                       An X11-based ZX Spectrum emulator

                    by Erik Kunze <xzx-pro@zx-spectrum.net>
                      based on XZX 1.0.2 by Des Herriott
                                and many others

              $Id: README,v 4.49 2003/03/26 21:44:47 erik Rel $


Contents
--------
 1.      Introduction
 1.1.    Purchase
 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.    Emulator window
 2.6.    Fileselector

 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.    Joystick emulation
 3.7.    Interface I emulation
 3.8.    +3 floppy disk emulation
 3.9.    Beta 128 emulation
 3.10.   +D emulation

 4.      Pokes (cheats)


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-Pro is a portable emulator of Sinclair ZX Spectrum 48K/128K/+3 (8-bit home
computers made by Sir Clive Sinclair) and Spectrum clones for machines
running Unix and the X Window system.  XZX-Pro is completely written in C. It
initially was based on XZX 1.0.2 by Des Herriott, but has been completely
rewritten since then.

XZX-Pro emulates

 o ZX Spectrum 48K, 128K, +2 and +3, Pentagon and Scorpion, Didaktik
 o Interface I with up to 8 microdrives,
 o Multiface 128 and Multiface 3 by Romantic Robot Ltd
 o Beta 128 disk interface by Technology Research Ltd with 4 disk drives,
 o +D disk interface by Miles Gordon Technology with 2 disk drives,
 o D80 disk interface with 2 disk drives,
 o ZX Printer,
 o Kempston mouse,
 o Sinclair, Cursor and Kempston joysticks,
 o Fuller Audio Box and
 o built-in machine code monitor.

XZX-Pro 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, .IMG or .D80 format,
 o screen dumps in .SCR format and
 o poke instructions in .POK or .TZX format.

XZX-Pro saves to

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

Additional features:

 o Emulates Spectrum's speaker and AY-3-8912 chip on workstations with audio
   hardware.
 o Supports colour (8,15,16,24,32bpp) and monochrome displays, where contrasting
   colours are displayed with the darker colour in black and the lighter colour
   in white, which works reasonably well.
 o Supports full screen mode on X servers with the XF86VidMode extension.
 o Supports analogue joystick on PCs with a joystick device (Linux, FreeBSD and
   NetBSD).
 o Redirects Spectrum's printer output to file or command (pipe).
 o Connect Interface I's RS232 to the workstation's serial device.


1.1. Purchase
-------------
The evaluation version is not completely functional, and the parts which are
left out are included when you purchase the full version. You are encouraged to
give this evaluation version to anybody if you do not change, or remove anything
from the package.

The full version differs from the evaluation version in the following respects:

 o supports disk images in Pentagon/Scorpion mode,
 o emulates the Didaktik Kompakt 128K computer,
 o emulates the Beta 128 disk interface with 4 disk drives,
 o emulates the +D disk interface with 2 disk drives,
 o emulates the D80 interface with 2 disk drives,
 o emulates the ZX Printer,
 o reads poke instructions from .POK and .TZX files,
 o loads from and saves to .VOC files,
 o supports full screen mode,
 o redirects Spectrum's printer output to file or command (pipe) and
 o many more.

If you purchase, you get the fully working version, and the following utilities:

 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 TZX2TAP   - Converts a .TZX file into a .TAP 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 EXPANDTRD - Expands shortened .TRD disk images to their full size.
 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 SCL2HOB   - Extracts HOBETA files from .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 via Email, and you will be kept informed about future updates.

You can purchase online and pay by credit card (Visa, Eurocard/Mastercard,
American Express, Diners Club), wire transfer, check or cash. The registration
fee is EUR 25, USD 25.

  http://www.zx-spectrum.net/xzx/buy.html
  https://secure.element5.com/register.html?productid=139459&language=English

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


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

  http://www.ibiblio.org/pub/Linux/system/emulators/zx/
  ftp://ftp.worldofspectrum.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-Pro's home page.  This
page gets updated at least every week, sometimes even every day.

  http://www.zx-spectrum.net/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.ast.cam.ac.uk/~pak/cssfaq/index.html

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


1.3. Reporting bugs
-------------------
You are welcome to send notes and 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-pro@zx-spectrum.net.  Be sure to include a
short description of your system and the output from the following commands
'xzx -version' 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 xzx;

  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;

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

  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 and Didaktik modes), or display the start-up menu
(128K, +3, Pentagon and Scorpion 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 128       pentagon.rom     48K      no
  Scorpion 256       scorpion.rom     64K      no

  Didaktik-Kompakt   didaktik.rom     32K      no

XZX-Pro will also work perfectly with different versions of the ROM files, just
specify the new filenames in the X Resources or select them directly at the
command line. For example, you may wish to use a v4.1 ROM for +2A/+3 or an old
Interface I v1 ROM, special Pentagon/Scorpion systems, and so on.

  Peripheral         Filename         Size     Included

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

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

  Beta 128           trdos.rom        16K      no
  +D                 plusd.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 illegally 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.


2.4. Configuration file
-----------------------
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 host name of your X
display.  Here is an example:

  $ cat /home/erik/.Xdefaults-zx-spectrum.net

    #include "/home/erik/.xzxrc"


2.5. Emulator window
--------------------
When the emulator is run, the screen of the emulated machine is displayed in a
standard X Window which we will call the emulation window.  This window will be
updated in real time, displaying the same contents that a real monitor or TV set
would.

Below the emulation window there is an area which is used to display information
about the state of the emulator; we will call this area the status bar.

On the extreme left of the status bar, there is a performance meter. This
displays the current relative speed of the emulator (as a percentage) and the
update frequency (in frames per second).  All the machines emulated are PAL, so
the update frequency will be 50 frames per second if your system is fast enough
to allow emulation at the speed of the real machine.

On the extreme right of the status bar, there is a drive status indicator.  This
is only visible if any disk interface is emulated.  In that case, the drive
status indicator will contain a rectangle emulating the drive LED.


2.6. Fileselector
-----------------
In those situations where it is necessary to specify a file name, the emulator
will pop up a file selector window allowing you to select or specify a file
interactively.

To the left of the file selector, there is a list of ancestor directories: by
clicking on them, you can ascend the directory tree.  To the right, there is a
list of the files in the current directory; files can be selected by clicking on
them.  If you click on a directory, that directory becomes the current one; if
you click on an ordinary file, it becomes the active selection.

At the top, there is a filter box, with the complete path of the current
directory.

At the bottom there are two buttons: "OK" confirms the selected file and
"Cancel" abandons the file selector without cancelling the operation.


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

3.1. Z80 emulation
------------------
XZX-Pro 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 pressing Bar or Backslash which clears all
Spectrum input ports.

The emulator turns keyboard autorepeat off when the mouse pointer is in the
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
---------------------
XZX-Pro 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.

XZX-Pro can produce sound in many configurations: 8-bit, mono or stereo and at
any sample rate supported by your soundcard.  The recommended configuration is
8-bit stereo at 44100 Hz.


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 header less 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.

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, start the tape manager and select a VOC file as input
file.  The VOC file is now in stand-by until you start the virtual tape player.
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.


3.6. Joystick emulation
-----------------------
XZX-Pro supports Sinclair, Cursor/Protek/AGF and Kempston joysticks. 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.

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

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

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.


3.7 Interface I 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 '-if1Drive1 MDRTEST.MDR
-if1Drive2 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.8. +3 floppy disk emulation
--------------------------
XZX-Pro emulates a Spectrum +3, with partial support for +3DOS, the floppy disk
operating system.  At the moment the floppy disk interface code does not
implement the WRITE TRACK commands and hence FORMAT will not work.  The disk
format used is identical to that used by Marco Vieth's Amstrad CPC emulator, so
disk images should be interchangeable.

An extra program, 'ddtrans' has been supplied, with which you can translate
Amstrad CPC (and Spectrum +3) disks to formats usable by XZX-Pro 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-Pro, 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 the
emulator; select option 5 from the main menu.  You will be presented with a
variety of formats readable by +3DOS; choose whichever suits you best.


3.9. Beta 128 emulation
-----------------------
In Pentagon or Scorpion mode or when Beta 128 disk interface is active, XZX-Pro
emulates the floppy controller, which used a WD1793 chip (software-compatible
with the WD1791) to provide both single and double density.

Four 3.5-inch floppy drives are emulated, with storage in files.  If the user
does not have write permission for a floppy file, a write-protect tab is
emulated.

Emulated floppy image files can be of either of two types: TRD, a raw dump
of sectors; or FDI, a raw dump of all floppy informations.  Both types work in
XZX-Pro regardless of what model it is emulating.

The program 'emptytrd' makes a blank emulated floppy or "bulk erases" an
existing one.  By default, 'emptytrd' makes a TRD floppy with 80 tracks, double
sided.  See the 'emptytrd' help for more information.

Spectrum programs that attempt to measure the rotational speed of their floppy
disk drives using timing loops will get the answers they expect, even though
the emulator makes no attempt to emulate instructions at the same speed as the
original machines.  This works because the emulator keeps a virtual clock
(technically, a T-state counter), which measures how much time it should have
taken to execute the instruction stream on a real machine, and it ties the
emulation of floppy disk index holes to this clock.

Some features of the disk controller are not currently emulated.  Certain errors
(such as LOST DATA) cannot occur, which makes disk diagnostic programs that try
to generate them on purpose unhappy.


3.10. +D emulation
------------------
The +D interface supports up to two double density, double face floppy disks,
usually 80 track x 10 sectors of 512 bytes each (800K total).  In order to able
to use them, you need the ROM files 'plusd.rom, which must be placed in the
same directory where Spectrum ROMs are.  Then you need a boot disk containing
the DOS (a file called "sys*" or "+sys*" respectively).

DOS extends the BASIC to provide support for disk operations.  When you switch
the Spectrum on, you must initialize the system; to do so, insert a disk
containing the operating system file into the first drive and then enter "RUN".


4. Pokes (cheats)
-----------------
At the good old times, lots of cheat modes and trainers were available for many
games, typically printed as POKES in the magazines.  With XZX-Pro there are two
ways to enter such pokes: you can enable the Multiface and then use its menu to
insert the poke, or you can use the Poke Browser which is accessed from the
menus.

The Poke Browser loads cheat instructions from .TZX or .POK files. The latter
are produced by the popular SGD (Spectrum Games Database) utility by Martijn van
der Heide.

Each trainer can be activated and disabled with the right mouse button.
Sometimes it is possible to specify a number as the value of a trainer, for
example the number of lives; in this case you can alter the number which is
shown when the trainer is active.
