XZX-Pro An X11-based ZX Spectrum emulator by Erik Kunze based on XZX 1.0.2 by Des Herriott and many others $Id: README,v 4.56 2005/01/02 21:58:12 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 1, 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, o screen dumps in .SCR or .XPM format and o audio files in .PSG or .WAV 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 Built-in VNC server for multiplayer games. o Supports analogue joystick on PCs with a joystick device 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 writes screen dumps to .XPM files, o writes audio files to .PSG or .WAV files, o supports full screen mode, o built-in VNC server for multiplayer games, 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 30. 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). It can be found at http://www.sinclairfaq.com/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 , 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//.Xdefaults- #include "/home//.xzxrc" Replace with your login name and 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. 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 on systems with an 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 # 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.