                                  xzx  

                     An X11-based ZX Spectrum emulator

                     by Des Herriott <dnh@mfltd.co.uk>
                            and many others

                             Version 0.5.0


Introduction
------------
Included are instructions on how to build the emulator, some docs
on how the internals work (partly for my benefit - this project
becomes more complicated every time I look at it :-), a few other
notes which may or may not be useful, and a list of the people to
whom credit is due.


Requirements
------------
o An X11R4 or R5 server.  R3 might work, but I haven't tried it.

o The MIT-SHM extensions is *strongly* recommended.  It'll work
  without it, but will be SLOW.

o An ANSI C compiler.  gcc works fine.


Installing
----------
An Imakefile is provided.  I haven't included a Makefile; if people
scream loudly enough for one, or someone wants to provide one, fair
enough; otherwise it's imake only.

To install the emulator, do the following:

  0) Check the Imakefile for a few tweakable defines; descriptions
     of what each definition does appear in the Imakefile.

  1) Create a Makefile with 'xmkmf'

  2) Create dependencies with 'make depend'

  3) Build the emulator with 'make'

  4) You can test the emulator at this point by typing 'xzx'.  This
     should start Sinclair BASIC and give you the familiar "(c) 1982
     Sinclair Research Ltd" message.  If it doesn't, something's wrong.

  5) You can now install the emulator by typing 'make install';
	 the manual page can be installed by typing 'make install.man'

xzx is known to work on the following machines/operating systems:

	Sparc            - Solaris 2.2 & 2.3, SunOS 4.x
	Intel            - SVR4, Linux, SCO
	Mips             - SVR4, DEC Ultrix, SGI Irix
	IBM RS6000       - AIX v3.2.x
	Hewlett Packard  - HP/UX
	DEC Alpha        - OSF/1

xzx will work with monochrome displays; contrasting colours are 
displayed with the darker colour in black and the lighter colour
in white.  This seems to work fairly well.  Halftoning is used if
the scaling factor is increased.

If and when you succeed in getting xzx working on other platforms,
please let me know.  Any diffs or descriptions of changes you made
to make it work are welcome.


Testing Microdrive Emulation
----------------------------
A sample cartridge file MDRTEST.MDR is supplied which contains a short test
program to exercise the microdrives.  Here's 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 the damn
thing works.

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


RS232 Emulation
---------------
The Interface 1 '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 IF 1 'T' streams turning end of line
into CRLF.  If you don't have dos2unix, you can use 'tr -d \015'.
And if you're using a SYSV-ish machine, you're more likely to have lp
than lpr.  Check your manual pages.  There's also a run-time option,
'crlf', which makes xzx do its own translation of carriage returns to
newlines and vice versa.  Use this option if you're transferring text,
but not binary data.

Inside xzx you can then do something like OPEN #n,'T': LIST #n: CLOSE
#n to get the printouts.

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


Installing Setuid
-----------------
If you build xzx on Linux with PC Speaker support, xzx controls the
PC Speaker using direct inb and outb calls.  To do this xzx must 
either be run by root or setuid root.  Uncomment the InstallXzxSetUID
definition in the Imakefile to achieve this.  xzx will throw away
its root permissions as soon as it gets permission to write to the
speaker port, so there shouldn't be any security problems.


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

  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;

  D'Arcy JM Cain for his getline() function, which will probably go away
  soon anyway, but it's come in useful for the moment :-)

  Gerton Lunter for his excellent hardware description in Z80.DOC;

  Arnt Gulbrandsen for some good ideas, and letting me use his FTP site;

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

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

