XZX(1)

NAME
XZX - an Sinclair ZX Spectrum emulator

SYNOPSIS
xzx [options] [snaphot-file]

DESCRIPTION
XZX is a Z80 emulator with reasonable support for the 48K, 128K and +3 Sinclair ZX Spectrum machines. 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.

OPTIONS
XZX accepts the following command line options. Options may also be specified as X Resources using the same spelling. Note that the shortest unique spelling of a resource is acceptable, e.g. xzx -ma 128 is equivalent to xzx -machine 128.

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

-version
    Display the version of this XZX and exit.

-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 are listed. Defaults to
     ".:/usr/local/lib/xzx".

-display <displayname>
    Specifies the X display to connect to.

-geometry <geomspec>
    An X11 geometry specification. The width and height field will be ignored; only the positioning fields count.

-pixmap <boolean>
    Force to use pixmap rather then X image. This is very slow! Using pixmaps can be the only way to run XZX on X servers where the XZX's image routines do not work. Defaults to false.

-mono
    Force XZX to use only Black and White. This is the default for monochrome X servers. 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 is the default if XZX fails to get all the colours it needs, but be warned, every other window on your display is likely to go technicolor.

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

-debug <n>
    If XZX has been built with -DDEBUG defined, specifies the level for debuging. 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. Defaults to 0.

-machine <48|128|3>
    Specifies the memory model to emulate. Defaults to 48K operation (48).

-cycles <n>
    A "cycle" is a number of clock ticks taken by the processor to execute certain instructions. Every so often (after a certain number of cycles), a line on the screen gets updated. Some games rely on the fact that lines on the screen get updated at certain times, in order to do efficient drawing of sprites etc.
    Change this number if you can't see the sprites or they    flicker heavily.
    Try to stay within range of 69888, which is the default setting for Spectrum 48K.

-ms <n>
    How many time elapses beetween frames displayed on the screen. You should not have reasons to change this setting. Defaults to 20.

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_Subtract, i.e.the keypad Minus key.

-keyFaster <keysym>
    The key to dynamically speed XZX up. Defaults to KP_Add, i.e. the keypad Plus key.

A full list of keysyms can be obtained by viewing the file <X11/keysymdef.h>, and removing the XK_ prefix from the definitions listed there.

-scale <n>
    Specify the Spectrum to X11 pixel magnification. Valid values are 1, 2 and 3. Defaults to 1.

-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 (i.e. slow :-), so you may want to disable flashing for action games. Defaults to true.

-border <boolean>
    Toggles "border" emulation on/off. At this point, XZX does not
    emulate    the border exactly as it's done in the real spectrum (drawing it
    line by line); rather it updates the "X-window" surrounding the main window of the speccy. 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. Defaults to true.

-rrShm <n>
    This option 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 3 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 6 interrupts - again, you may get away with lower values, or you may need to raise it slightly.

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

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

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

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

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

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

Note that it's 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 or FreeBSD, 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 AY-3-8912 sound chip is emulated under OSS (aka VoxelWare) via the /dev/dsp. 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 strangely, 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.

-rom48 <filename>
    Use filename as the file containing the 48K Spectrum ROM image. This defaults to spectrum.rom.

-issue <2|3>
    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 won't respond. Note that all 128K Spectrums were issue 3 and some Spectrum 48K were issue 2, but not that many. Defaults to 3.

-kbdlayout <filename>
    Use filename as the file containing an picture of the Spectrum keyboard. The file must be in .SCR format an exactly 6912 bytes long. This defaults to keyboard.scr.

-rom1280 <filename>
    Specify the 128K ROM0 image. Defaults to 128-0.rom.

-rom1281 <filename>
    Specify the 128K ROM1 image. Defaults to 128-1.rom.

-rompl30 <filename>
    Specify the +3 ROM0 image. Defaults to pl3-0.rom.

-rompl31 <filename>
    Specify the +3 ROM1 image. Defaults to pl3-1.rom.

-rompl32 <filename>
    Specify the +3 ROM2 image. Defaults to pl3-2.rom.

-rompl33 <filename>
    Specify the +3 ROM3 image. Defaults to pl3-3.rom.

-fda <filename>
    In +3 emulation mode, specifies the filename of the A: disk image.

-fdb <filename>
    In +3 emulation mode, specifies the filename of the B: disk image.

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 Interface 1 ROM. The current directory and the lib directory (see above) are searched for the file if1.rom by default.

-crlf <boolean>
    If set to to true, XZX converts linefeeds (ASCII 10) to carriage returns (ASCII 13) on RS232 input, and vice versa on RS232 output. This is necessary if you're transferring textual data from Unix to XZX, since the Spectrum expects to see a carriage return as end-of-line, and Unix uses linefeeds. 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. Default to false.

-strcr <boolean>
    If set to true, XZX will strip carriage returns on RS232 output. This is only useful when listing BASIC programs to the IF1 'T' channel. Defaults to false.

-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. Defaults to MDR<n>. If you like keeping your Microdrive data intact, don't load the same file into more than one drive!

If you have compiled in the Multiface 128 emulation, the following options apply:

-mf128 <boolean>
    Enable or disable the Multiface 128. Disabled by default.

-mf128 <path>
    Specify the path to load an image of the Multiface 128 ROM. The current directory and the lib directory (see above) are searched for the file mf128.rom by default. NOTE: The ROM image is not distributed with XZX.

RUNNING THE EMULATOR
If XZX 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), XZX will search each directory in turn on its libDir resource. XZX is able to read and write format .Z80 snapshots will be written.

The method used to decide whether to read snapshots in .SNA or .Z80 format is as follows: first, the filename to be loaded is checked to see if the last characters are either "=z" or "=s", in which .Z80 or .SNA format, respectively, is forced (these characters are not part of the filename actually used and are stripped by XZX). Otherwise, the format read depends on the file extension: if there is a .z80 extension, then .Z80 snapshots are read, otherwise .SNA snapshots are read.

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

F1  Display HELP screen, that gives meaning of all function keys and the layout of the Spectrum keyboard.

F2  Pops up a file selector for saving a snapshot of the memory of the Spectrum in whatever current mode it's in. The format is either .SNA or .Z80 (compatible with Gerton Lunter's Z80 emulator version 2.01). If XZX is in 128K or +3 mode, a .Z80 format snapshot will be dumped no matter what filename is given. If XZX is in 48K mode, the decision is the same as for reading snapshots as described above.

F3  Ditto for loading snapshots.

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

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

F6  Pressing this generates an NMI. With the default ROMs, this has the effect of resetting the machine, but some contributed ROMs have hooks for extensions on receipt of an NMI. With the Multiface 128 in use this will enter the Multiface.

F9  Choose a certain architecture for the Spectrum emulation and does or does not perform a reset.

F10 Shuts down the emulator cleanly.

Support for the original Spectrum keyboard is emulated as follows: Shift emulates Caps Shift, Control emulates Shift-SymbolShift (Extended Mode) and 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 (apart from the alphanumerics) which are guaranteed to be emulated correctly; other keys on your keyboard might work, but since keyboards vary so much, there's no guarantee.

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 0x00bf (191) will read a character from stdin, returning 255 if no input is pending; writing port 0x01bf (447) will send a character to stdout; and writing port 0x02bf (703) will send a character to stderr. These port numbers can be overriden at compile-time by changing the definitions in io.h. This isn't particularly useful interactively, especially if the Interface I is active, but has possibilities as an unusual filtering shelltool.

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.

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 microdrive 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 -crlf yes > 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. Channel 'T' is only really useful for listing BASIC programs to the RS232 port, as above.

XZX tries to emulate RS232 I/O as sensibly as possible, but please note that piping input to XZX simply does not work well. Reading input from terminals & special devices (using the Unix file redirection mechanism) does work, as does reading from files.

The +3 floppy disk format used is identical to that of Marco Vieth's Amstrad CPC emulator. Disk images should therefore be compatible between the two emulators, though I haven't tested this personally.

BUGS AND DEFICIENCIES
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.

AUTHOR
Erik Kunze <Erik.Kunze@fantasy.muc.de>, Des Herriott, and plenty others. See the README and ChangeLog files.