xzx(1)

NAME
xzx - an X11 Sinclair ZX Spectrum emulator

SYNOPSIS
xzx [options] [snaphot-file]

DESCRIPTION
xzx is a z80 emulator with reasonable support for the 48K Sinclair ZX Spectrum hardware. Although a usable Spectrum is emulated, a few features are missing; sound is only emulated on some hardware, for obvious reasons, and printer support is as yet absent.

OPTIONS
xzx accepts the following command line options. Options may also be specified as X Resources using the same spelling.

-help
    Print a synopsis of the accepted options and exit.

-version
    Display the version of this xzx and exit.

-romName filename
    Use filename as the file containing the Spectrum ROM image. This defaults to spectrum.rom.

-libDir path
    Use path as the colon-separated directory list to check when loading the Spectrum ROM and any snapshots specified. Directories are guaranteed to be searched in the order they're listed. Defaults to ".:/usr/local/lib/xzx".

-intStyle [signal|counter]
    Z80 interrupts are emulated in one of two ways with xzx - either by forcing an interrupt every few thousand instructions (count), or by getting the O/S to generate a signal every 20ms with the setitimer() library function (signal). signal-style interrupts are preferable, but are not guaranteed to work on every operating system, which is why counter-style interrupts are still supported.

-recalibrate <boolean>
    If counter-style interrupts are being used, xzx will attempt to keep the interrupt frequency at 50/second. If it ends spending a lot of time updating the screen (which may happen on a remote X server), there is a possibility that it will hang. If this happens, switch recalibration off with this option.

-mitshm <boolean>
    Attempt to use the MIT-SHM X extension for rapid image transfer. Defaults to true.

-mono
    Force xzx to use only Black and White. This is the default for monochrome X servers, or if xzx fails to allocate 16 colours on a colour X server. In this case, the foreground and background will contrast, e.g. blue on black will appear as white on black, and green on white will appear as black on white.

-private
    Force xzx to use a private colormap. This may be preferable to using monochrome if you run out of colours, but be warned, every other X client will go technicolor.

-flashing <boolean>
    Enable/disable flashing. If disabled any attribute bytes with the FLASH bit set will instead appear in inverse video. The FLASH implementation is not very optimal yet (i.e. slow :-), so you may want to disable flashing for action games.

-rrShm <n>
    This options specifies how often your screen is refreshed when running xzx with MITSHM active. The screen is refreshed every n interrupts, so a lower number means more frequent refreshes. Specifying it too low, however, could result in more time being spent in screen painting than in CPU emulation! Defaults to every 2 interrupts, you might get away with every interrupt if you're lucky.

-rrNoshm <n>
    Similar to above, but used when MITSHM is not active. This should be somewhat higher than the value used for rrShm. Defaults to every 4 interrupts - again, you may get away with lower values, or you may need to raise it slightly.

If xzx has been built with -DSLOWDOWN defined, it is possible to set and control xzx's speed. The following options apply:

-slowdown <n>
    Slow xzx down. A larger value of n slows xzx more. This is implemented by simply running n nop instructions for every instruction.

-keySlower <keysym>
    The key to dynamically slow xzx down. Defaults to KP_Add, i.e. the keypad Plus key.

-keyFaster <keysym>
    The key to dynamically speed xzx up. Defaults to KP_Subtract, i.e. the keypad Minus key.

It is possible to redefine keys to emulate a Kempston joystick. The following resources apply:

-kempstUp <keysym>
    The key to emulate moving the joystick forwards. Default is q.

-kempstDown <keysym>
    The key to emulate moving the joystick backwards. Default is a.

-kempstLeft <keysym>
    The key to emulate moving the joystick to the left. Default is o.

-kempstRight <keysym>
    The key to emulate moving the joystick to the right. Default is p.

-kempstFire <keysym>
    The key to emulate pressing the joystick fire button. Default is space.

Note that it's entirely possible for a key to emulate both a keyboard keypress and a joystick movement. No checks are made to ensure that the same key isn't mapped to two or more joystick directions. It's also possible to fool xzx into thinking that the joystick is being simultaneously moved in opposite directions!

If you're running xzx on Linux, and you've installed the joystick kernel patches (available from tsx-11.mit.edu and sunsite.unc.edu), then it's possible to use a PC analogue joystick to emulate a Kempston joystick. In this case, the following options also apply.

-joystick <boolean>
    Enable/disable joystick emulation. This is disabled by default. If emulation is enabled, you'll be asked to calibrate your joystick when xzx starts up. Move the joystick to the lower right and press either Fire button, then centre your joystick and press either fire button.

-joyDev <path>
    This is the device that xzx uses to read the joystick status, /dev/js0 by default. You may want to use /dev/js1, depending on how your system is setup.

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

If you're running xzx on a machine with Sun Sparc /dev/audio style sound support, then it's possible to get (fairly inaccurate) sound emulation. This option will also work on Linux with the kernel sound drivers (tested with a SoundBlaster Pro - quality is poor), and on the NEC EWS 4800/330 workstation (works very well, but with a 150MHz Mips R4400, it ought to :-). Alternatively, if you're on Linux, and xzx is compiled with -DPCSPKR_AUDIO, you can get Spectrum sound from the PC Speaker. This works much better than /dev/audio style sound on Linux. No extra kernel support is necessary for this, but xzx must be run with root privileges. The following options apply:

-sound <boolean>
    Enable/disable sound. Sound is disabled by default.

-audioDev <path>
    Specifies the audio device that xzx uses. By default, this is /dev/audio; you shouldn't need to change this, unless your system is set up very oddly, or you're on an EWS 4800/330, in which case, use /dev/audio/audio. This doesn't apply if you use Linux PC Speaker audio.

If you have compiled in the ZX Microdrive emulation you can use .MDR files as Microdrive cartridges. The following options apply:

-if1 <boolean>
    Enable or disable the Interface 1. Enabled by default. Turn it off if you want to work without extended basic / microdrive support.

-if1Rom <path>
    Specify the path to load an image of the 8K Interface 1 ROM. The current directory and the lib directory (see above) are searched for the file if1.rom by default.

-crlf <boolean>
    Enable translation of carriage returns to linefeeds on RS232 output and vice versa on RS232 input. This is useful if you're transferring textual data between Unix and your Spectrum. Don't use it if you want to transfer binary data. See the 'Extensions and Alterations' section below for more details on RS232 I/O.

-m<n> <path>
    Load a cartridge file into an emulated Microdrive (n is 1-8). A blank, unformatted cartridge file can be created by a command such as dd if=/dev/zero of=test.mdr bs=137923 count=1. A shell script, mkcart has also been provided to do this. You can then format it with the Sinclair BASIC FORMAT command as normal. Do not load the same file into more than one drive!

RUNNING THE EMULATOR
If xzx is started with no snapshot file as a command-line argument, it will reset the machine and enter Sinclair BASIC, displaying the "(c) 1982 Sinclair Research Ltd". If exactly one argument is given (not counting options), xzx will try to find that file first in the current directory and then in its library directory. xzx is able to read and write .SNA format snapshots, and is able to read 48K .Z80 format snapshots. If the file to be read has a .z80 extension, then it will attempt to read it in Z80 format. Not very clever, but it works.

Once the emulator is up and running, the following keys have special meanings:

F1/F2
    Cause a CPU reset, dropping you back into Sinclair BASIC.

F3  You will be prompted on the command-line for the name of a snapshot file to dump. This saves the current state of the machine for later use.

F4  You will be prompted on the command-line for the name of a snapshot file to load.

F5  This key only has an effect if xzx has sound support. Pressing it will toggle sound on and off.

F8  Pressing this generates an NMI.

F10/F12
    Pressing either of these keys immediately exits the emulator.

Support for the original Spectrum keyboard is emulated as follows: both Shift and Control emulate Caps Shift, Alt emulates Symbol Shift, Return emulates Enter, Backspace and Delete emulate CapsShift-0 (Rubout), the cursor keys emulate CapsShift-5 to 8, and Escape emulates CapsShift-1 (Edit). These are the only keys which are guaranteed to be emulated correctly; other keys on your keyboard may work, but since keyboards vary so much, it'll be a matter of experimentation.

EXTENSIONS AND ALTERATIONS TO THE BASIC

If xzx has been compiled with the -DPSEUDO_IO define, it will be possible to read characters from stdin and write characters to stdout and stderr using I/O ports. By default the ports are as follows: reading port 48896 will read a character from stdin, returning 255 if no input is pending; writing port 48897 will send a character to stdout; and writing port 48898 will send a character to stderr. These port numbers can be overriden at compile-time by changing the definitions in spectrum.c. This isn't particularly useful interactively, but has certain possibilities as an unusual filtering shelltool.

If xzx has been compiled with the -DLOAD_SAVE_1 or LOAD_SAVE_2 define, the BASIC LOAD and SAVE commands will behave differently. Instead of trying to read or write data to a tape, SAVE will immediately dump data to a file on disk, and LOAD will try and read data from a file on disk. The filename used when saving is the string passed to SAVE with a file extension of .zxf. It is possible to SAVE BASIC programs, blocks of memory (CODE), and arrays. When LOADing, the filename used will be the string passed to LOAD plus either .sna or .zxf appended.

If xzx as been compiled with the -DZX_IF1 define the emulator behaves as though an Interface 1 is attached in terms of paging the shadow ROM in and out, allowing the use of extended basic commands and emulating the Microdrive hardware.

The cartridge file format used is the .MDR format used by several other Spectrum emulators.

When the IF1 emulation is active the RS232 channels are connected to stdio so listings and blocks of code can be obtained and transferred by appropriate redirections. For example: xzx > listing.bas, followed by the BASIC commands to xzx: OPEN #4, 'T': LIST #4: CLOSE #4. Channel 'T' is a text channel; BASIC keywords are expanded and end-of-line is converted to CR/LF. Channel 'B' is a binary channel; no conversion is performed.

BUGS AND DEFICIENCIES
Probably loads. xzx does not run all of the snapshots I have tried, but I don't know whether the emulator is at fault 100% of the time. The snapshot loading and saving mechanism is awkward and clunky (ok, it was a quick hack to get something together :-), and will be replaced in a later version. Hardware support is limited, but this is slowly improving. Loading snaps on the fly doesn't always seem to work. Z80 snapshot support doesn't seem to work properly.

AUTHOR
Des Herriott <dnh@mfltd.co.uk>, and plenty others. See the README and ChangeLog files.