Sinclair ZX Spectrum Emulator 'Z80' v3.03 - 29/12/94 - by G.A. Lunter Contents: 1. INTRODUCTION, REGISTRATION, GENERAL INFORMATION 1.1 Some general remarks 1.2 Registering - sounds interesting! 1.3 Other emulators 1.4 Acknowledgements 1.5 Disclaimers 1.6 Copyright notices 2. THE EMULATOR 2.1 Starting the emulator 2.2 Using the emulator 2.3 Keyboard emulation 2.4 Screen emulation 2.5 Sound emulation 2.6 Loading programs from tape 2.7 Using .TAP files 2.8 Using .VOC files 2.9 Multi-load games 2.10 Using the Microdrive 2.11 Using the Disciple and Plus D interfaces 2.12 Using the Multiface 2.13 Using the RS232 channel 2.14 On joysticks and mice 2.15 The utility ConvZ80 2.16 Converting file formats - the utility CONVERT 2.17 The utilities Z802TAP, TAP2TAPE and TAP2VOC 2.18 The utility OUT2VOC - and how to make .OUT files 2.19 Quick overview of command line switches, and features 2.20 Miscellaneous remarks 3. THE SAMRAM 3.1 Basic extensions 3.2 NMI software 3.3 The built-in monitor 4. THE SPECTRUM 4.1 The Spectrum 4.2 The Interface I 4.3 The DISCiPLE and Plus D Interfaces - Introduction 4.4 The DISCiPLE and Plus D Interfaces - Basic commands 4.5 The DISCiPLE and Plus D Interfaces - More advanced commands 4.6 The DISCiPLE and Plus D Interfaces - The snapshot button 4.7 The Spectrum 128 5. TECHNICAL INFORMATION 5.1 The Spectrum 5.2 The Interface I 5.3 The SamRam 5.4 The Z80 microprocessor 5.5 File formats 1. INTRODUCTION, REGISTRATION, GENERAL INFORMATION 1.1 Some general remarks This is the documentation for 'Z80', a Sinclair ZX Spectrum 48/128 emulator. The program turns your PC into a Spectrum. Its features in a (largish) nut-shell: - Emulates ZX Spectrum 48K model 2 or 3, and Spectrum 128K. - Best compatibility of current Spectrum emulators. - Emulates Interface I and Microdrive (cartridge in cartridge file), Disciple and Plus D disk interfaces, Multiface 128. - Full tape support: loads both normal and turbo-saved programs using either tape interface on LPT port, SoundBlaster AD converter or .VOC sound sample files; can also use .TAP binary tape image files by trapping ROM save/load routines. Saving back to tape is also possible, either directly to tape or to a .VOC sound sample file. - Full emulation of Spectrum screen, including all colour effects. Border, and timing-sensitive border and attribute effects are also emulated. - Emulation of ZX Printer, for Epson and HP Laserjet compatible printers. - Emulation of beeper through PC beeper, and of 128K sound through either PC beeper or AdLib (SoundBlaster) compatible cards - A program is included which makes .VOC or raw sound sample files of sounds produces by the Spectrum, either by the beeper, the soundchip of the Spectrum 128, or the MIC port. - OUTs to any port can be logged, and stored in a log file with timing information. - Supports digital and analogue joysticks, and mouse, controlling Cursor, Sinclair, Kempston or user-defined joystick. - Emulates Spectrum AMS Mouse interface (used by e.g. Art Studio) - Runs on any PC (but needs 640K base memory if no EMS is present). - Emulator runs just above 100% of actual Spectrum speed on 20 MHz 286 and 25 MHz 386SX; can be slowed down on faster machines. - Z80 emulation includes emulation of R register, all unofficial instruction codes, and unofficial flags; interrupts once every 1/50th emulated second; I have tried to make each instruction execute in a time proportional to the time taken on a real Z80. - Registered package includes all source files. - Interface I and Spectrum 128's "p" channel input/output can be re-routed to LPT or COM port, or to a file. - Includes several utilities; to convert from and to other snapshot and tape file formats, to convert snapshots into tape files, tape files into sound sample files, to display contents of snapshot files, to convert screen snapshots to .PCX and .GIF files, to read .VOC sound sample files from the LPT tape interface or SoundBlaster. - Multi-level support as in XZX 0.5.2 - Emulator can set a breakpoint, invisible to the running program. - Emulator can load and save blocks of Spectrum memory to disk directly. - Emulator can run under Windows. - Supports VGA, EGA, CGA, Hercules and Plantronics video adapters including mono VGA. There is quite a lot to explain in this documentation. First of all the emulator itself requires some of your PC's resources. It is not really a demanding program, but there are some things that need attention. These technicalities are dealt with in section 2.1. Some general things about the emulator are explained in section 2.2. If you read 2.1 and 2.2, you will know most of the basic stuff. The details can be found in subsequent sections. The Spectrum has a number of ways to communicate with the outside world, like the obvious keyboard and the screen, but also the microdrives, the DISCiPLE/Plus D disk interfaces, the tape interface, the beeper, the sound chip of the Spectrum 128, the Kempston joystick, the AMS Mouse, the ZX Printer interface, and the RS232 channel of the Interface I and Spectrum 128 can be used to communicate with PC channels in some way. For instance, the keyboard is connected to the PC keyboard (sounds obvious) and the tape I/O can be routed to a file, as well as to a physical tape recorder, or it can come from a .VOC sound sample file. All these things are explained in the rest of chapter 2. For our own Spectrums Johan Muizelaar and I built a piece of hardware we called the SamRam (which has nothing to do with the SAM Coupe, by the way!). It contains a monitor program and software to make snapshots of programs. It's still very useful and I still use it a lot. An explanation of its functions is to be found in chapter 3. Some things peculiar to the Spectrum or its interfaces, not specific to this program but useful to know, are collected in chapter 4. It contains for instance a table of Spectrum keywords and the key combination to get them; unfortunately this information is not printed on standard PC keyboards! More importantly, in this chapter it is explained how to use the Microdrive and DISCiPLE interfaces, both of which are probably unfamiliar to many former Spectrum users. There are some interesting technical facts about the Spectrum that I discovered while debugging the emulator. As much as I could think of is contained in the final chapter. You don't need to read this chapter to use the emulator. A specification of the file formats used by the emulator is also included. For Spectrum software, utilities, other emulators for PC's as well as other computers, and other Spectrum related software, you can call the Spectrum Emulator support BBS in Groningen: Tatort BBS Groningen 050-264840 (+31-50-264840) 300-14400 baud At the time of writing the BBS is open 24 hours a day, but this is subject to change. Please try calling between 22:00 and 9:00 local time first. A number of interesting Internet addresses are FTP ftp.nvg.unit.no /pub/spectrum FTP wuarchive.wustl.edu /systems/sinclair FTP ftp.ijs.si /pub/zx GOPHER gopher.nvg.unit.no WWW www.nvg.unit.no http://www.nvg.unit.no/ /Sinclair/Spectrum (The Internet addresses above were taken from the FAQ list maintained by Marat Fayzullin). Usenet, often offered with Internet access, has Newsgroups like comp.sys.sinclair, comp.emulators.announce and comp.emulators.misc which can be sources of useful information; for instance, you can get the FAQ list mentioned above there. If you want to get in touch with me, my email address is gerton@rcondw.rug.nl. 1.2 Registering - sounds interesting! 'Z80' is a shareware program. The program is not completely functional, and the parts which are left out are included when you register. You are encouraged to give this demo version to friends, but DO NOT change the original archive in any way, please. The shareware version of the emulator consists of the Z80-303.ZIP archive file, which should contain the following 11 files: Z80.EXE - The emulator Z80.INI - Default initialisation file Z80.PIF - Program Info File to run 'Z80' under Windows 3.1 Z80.ICO - Windows icon Z80.DOC - This documentation file Z80FAQ.DOC - Frequently asked questions - and answers! REGISTER.DOC - Information on how to register for 'Z80' NEW.DOC - The What's New file ROMS.BIN - Various ROM images LAYOUT.SCR - Keyboard lay-out help screen DIAGRAM.Z80 - Circuit diagram for tape interface, and calibration The shareware version of the emulator differs from the registered version in the following respects: it cannot be slowed down, it cannot load from or save to tape, and it does not emulate the DISCiPLE and the Plus D interfaces. Everything else works as in the registered version. If you register, you get the fully working version, and the following utilities: CONVERT - a general conversion program: can list out BASIC and tranlate it back, produce .GIF or .PCX files from screen dumps, translate Spectrum ASCII (CR) to PC ASCII (CR/LF), and some other things. CONVZ80 - Translates various snapshot and tape formats of other Spectrum emulators into each other. Can handle the familiar .SNA format use by several emulators (JPP, XZX,...), and also Pedro Gimeno's (VGASPEC and SPECTRUM) .SP format and Kevin J. Phairs' (SPECEM) .PRG format. It can also handle tape files of SPECEM and L. Rindt and E. Brukner's emulator ZX. DISCIPLE - Reads DISCiPLE and Plus D diskettes, both 3.5'' and 5.25''. It translates the 48K and 128K snapshot files to .Z80 snapshots, and ordinary files and screen snapshots to .TAP tape files. (Not necessary for the fully registered version, but handy for the cheaper one.) Z802TAP - Converts a .Z80 snapshot, 48K or 128K, to a .TAP file which can be loaded into the emulator and saved to tape by the next utility: TAP2TAPE - Saves the contents of a .TAP file back to tape, to load it into an ordinary Spectrum. TAP2VOC - Converts a .TAP file to a .VOC sound sample file, to write to tape, or to load into the emulator. READVOC - Reads in a long, 'digital' .VOC sound sample, to be used as input to the emulator, from the LPT tape interface or a SoundBlaster. OUT2VOC - Converts .OUT log files into .VOC or raw sound sample files, so that you can easily extract music samples from Spectrum/Spectrum 128 games, or SAVE directly to a .VOC or raw sample file. Z80DUMP - Shows the header and the contents of a .Z80 file. You will also receive the source files of the emulator, the above utilities and the SamRam, and you will be kept informed about future updates. You can also choose to register for the emulator without DISCiPLE and Plus D emulation, if you are not interested in those parts. The registration fee is a bit lower then, and you will receive everything stated above (including the DISCIPLE program), the only difference being that you get a version of the emulator that will not emulate the M.G.T. interfaces. There are several registration sites, the main one being B.G. Services in the U.K. You can also register with me in the Netherlands, or with Jimaz in the Czech Republic, with Sinclair Freakeren in Denmark, David Pomeroy in New Zealand and with FriendWare in Spain, whichever is most convenient. Details follow: B G Services, U.K. ------------------ The registration fee is BP 20 or BP 15 for the version with or without DISCiPLE/Plus D emulation respectively. Payment can be by sterling (Euro)cheques or postal order made payable to B G Services. You can also transfer directly to the Giro account 324.82.16 (B G Services). The address is: B G Services 64 Roebuck Road Chessington Surrey KT9 1JX Telephone enquiries on (0181) 287 4180, Fax (0181) 391 0744, or from abroad: +44 181 287 4180 and +44 181 391 0744 respectively. B G Services can also supply ready built tape interfaces for BP 11.50. These are proffessional quality items built into 25W 'D' connectors. Myself, The Netherlands ----------------------- Registration fee is BP 20/BP 15, US$ 30/US$ 23, HFL 50/HFL 35, or equivalent amounts in your local (convertible) currency, for the version with or without DISCiPLE/Plus D emulation respectively. From the Netherlands, you can most conveniently transfer the fee to my Giro account 59.45.263, G.A. Lunter, Groningen. From every other country, I prefer bank notes or international postal money orders. From Europe, you can sometimes use a Eurocheque. Please fill it in completely, including the number at the back, and please write it out in DUTCH currency. Eurocheques written out in foreign currency cost HFL 20 to cash. I discourage using any other cheques. If you have no other option available, please add the equivalent of HFL 20 for drawing the cheque, and specify whether you want the version with or without DISCiPLE/+D emulation. The address is: Gerton Lunter P.O. Box 2535 NL-9704 CM Groningen The Netherlands You'll get the files on a 3.5'' HD disk by default, but you can also get it on DD or 5.25 inch disks if you want. Jimaz, Czech Republic --------------------- For registrations in the Czech Republic, you can contact Jimaz. JIMAZ s.r.o. Hermanova 37 170 00 Praha 7 phone: +42 2 379 498 fax: +42 2 378 103 Email: vondrack@cslab.felk.cvut.cs Registration fee is 500 and 650 Czech crowns. Sinclair Freakren, Denmark -------------------------- For registrations in Denmark, you can register with Sinclair Freakren Leif Mortensen Bryggervangen 29 DK-7120 Vejle /Ost Denmark Registration fee is (150) 200 DKr for the (un)discipled version. David Pomeroy, New Zealand and Australia ---------------------------------------- For registrations in New Zealand and Australia, contact David Pomeroy P O Box 2939 Shortland Street Auckland New Zealand Phone: (09) 627-9618 Email: davidpom@iconz.co.nz The registration fee is 40/50 NZ$, or 30/40 AUS$. Friendware, Spain ----------------- In Spain, you can register with Friendware. The address is Friendware C/Miguel Angel, 6 2nd 5 28010 Madrid SPAIN Phone: (91) 308 3446 Fax: (91) 308 5297 CompuServe: 100413, 1667 Email: 100413.1667@CompuServe.COM Registration fee is 3500 and 4700 Pts, respectively. 1.3 Other emulators There are several other Spectrum emulators, both for the PC and other computers. The list below ia mostly from Carlo Delhez (the QL emulators) and partly copied from Arnt Gulbrandsen's documentation of his JPP. I don't think the list is complete, so if you know more Spectrum emulators, for any computer, please let me know. For PC's: o WARAJEVO, by Zeljco Juric and Samir Ribic. Written, in Sarajevo, in bad conditions during the Bosnian war. A very thorough program; clean sounds, automatic R-register and 'LDIR'-emulation when needed, fast operation when not, traps on some RST's to speed up BASIC, good emulation of unofficial opcodes, well-organised tape file system, machine code monitor, ZX Printer emulation, sneaky software detecting some speed-loaders by their code and feeding regular tape files to them (!), partial 128K emulation. o JPP, by Arnt Gulbrandsen (Norway). Faster than mine (but according to an OUTLET review slower on some boards), by using a very smart decoding technique, but requires a 80386 or '486 processor. Is less compatible than Z80. Uses the .SNA snapshot format. Needs VGA. Not many extra features. o VGASPEC, by Alberto Olloqui (Spain). Needs VGA and 80286. Quite slow, and crashes on quite a lot of programs. Uses the .SP snapshot format. Allows ROM pokes. This program is an illegal pre-release of SPECTRUM, by Pedro Gimeno. o SPECTRUM, by Pedro Gimeno (Spain). Uses another .SP snapshot format. Has a tape interface. Also quite slow. Allows changing the rom. o SP, by J. Swiatek and K. Makowski (Poland). Cannot load or save snapshots, but can load programs using LOAD "" via a file called TAPE_ZX.SPC. Crashes many programs; even basic behaves weird sometimes. Has a built-in monitor, but no documentation. No border. o SPECEM, by Kevin J. Phair (Ireland). Also allows rom changes. Displays the registers on screen. Can save and load directly from disk using LOAD/SAVE "filename" in BASIC. Loads .PRG snapshots, but cannot save them. Emulates a Multiface I. o ZX, by L. Rindt and E. Brukner (Czech Republic). Haven't tested its compatibility thoroughly, but one of the games supplied didn't respond well to the keyboard, while it did work on Z80 after conversion. Good tape file support including headerless files, almost identical to the multiple .TAP file mode of Z80. Somewhat slower than Z80. Includes program to load from tape and convert to tape file. No documentation at all. For the Sinclair QL: o SPECTATOR by Carlo Delhez, The Netherlands; shareware; supports tape-files, Microdrives, RS232, Z80 snapshots, MBF snapshots and Disciple (SNP) snapshots; utilities to convert Disciple, Beta and Opus disks enclosed. o ZM-1/2/3/4, ZM-HT by Ergon Development, Italy; ZM-1 is shareware, others are commercial. They all support tape-files and Z80 snapshots, some support Microdrives and RS232; contain a utility to transfer programs from tape via a Spectrum to the QL. Seem to be real good and fast. o ZX by Andew Lavrov, CIS; shareware; supports tape-files, MBF snapshots en Z80 snapshots; utility to read from Spectrum tapes (and write them). For the Amiga: o Spectrum, by Peter McGavin. Very good, JPP is based to a large extent on it. Needs about a 25MHz machine to run at full speed. Has tape support. o KGB. I haven't seen it. A bit slower than Peter's, and the version Peter saw wouldn't work on the Amiga 3000. o An Italian emulator which I don't know the name of. Excellent compatibility, rather fast. May be shareware. o Several unreleased emulators. Peter knows more about them. For the Atari ST/TT: o One, called Spectrum. Don't know anything about it, but the doc file is written in quite the worst English I've seen. [This is Arnt speaking --- I've seen worse! GAL] Available by anonymous ftp from terminator.cc.umich.edu. o There's another one in the make, to be released very soon as one of the programmers told me, written by Markus Oberhumer and other(s). For the Acorn Archimedes: o A good emulator written by Carsten Witt (Rostocker Str. 5, 45739 Oer-Erkenschwick, Germany), written in ARM code, RISC OS Desktop compatible, multitasking, loading and saving to disk or tape via RS432, understands .Z80 snapshots and others, emulates microdrives. Seems to be the best one around for the Archimedes at the moment. (Information supplied by Mr. G. Oeing-Hanhoff) o A company called Arxe wrote one, intended to be commercial but never released because Amstrad wouldn't permit Arxe to enclose the ROM. o Someone called D. Lawrence wrote another, or maybe the same. This one is floating around but nobody has any documentation. I don't know what its status is. Runs at about 70% of Spectrum speed on an ARM2, not quite perfect graphics emulation. For the Commodore 64: o The Whitby Software Spectrum simulator is a rewrite of the Spectrum Basic. It will not run machine-code programs. I don't know whether it's PD, shareware, or commercial. Quite good. (Responds nicely to a POKE 23659,0) For the Amstrad CPC o Spectator - I believe this appeared on a cover tape on a now dead magazine. All emulators for PC, and some for the Atari, Amiga and QL are available on the support BBS. There are also emulators available for the ZX81. Carlo Delhez, who also wrote a Spectrum emulator for the QL, wrote the ZX81 emulators XTricator (for the QL) and XTender (for PC's). These programs can also be downloaded from the support BBS. 1.4 Acknowledgements From the very first beginning in november 1988, when I wrote the first lines of the emulator, Johan Muizelaar has been a very demanding and critical user, being only satisfied when it was perfect. Besides, there are quite a few things I would never have started working on if he hadn't insisted that I would! I have also profited much from the fine cooperation with Brian Gaff, who, besides handling the UK registrations, also generates a continual stream of suggestions, remarks and bug reports. He also brought me into contact with many people that contributed to the emulator in several ways. A major part of the things new to version 3 of the emulator have been written by Hugh McLenaghan. He wrote all code for the Disciple/Plus D emulation, and for the ZX Printer emulation (where I subsequently introduced bugs...) Also, Hugh wrote much of the documentation for the Disciple and Plus D interfaces in this file. Finally, thanks are due to o Carlo Delhez for information on the '128 and several other things, o Andre Mostert for some more '128 info and info on EMS memory, o Walter Prins for many '128 programs, o Marco Holmer for making the program such a big hit at the HCC dagen, o Henk de Groot, for finding a solution to a bug in A86 v3.22, o Arnt Gulbrandsen for a suggestion which made the emulator faster, and information on a group of unofficial Z80 opcodes, o Ruud Zandbergen for his digital joystick interface, o Jan Garnier for providing the chips to reanimate my real Spectrum, o Ettore de Simone for finding a noisy bug, o Rudy Biesma and Tonnie Stap for providing info on the DISCiPLE disk formats, o Burkhard Taige for various bug reports on it, o Ian Cull for enhancing the DISCiPLE program and two bugfixes, o Bert Lenaerts for information on the AZERTY keyboard, o Chris Lemon for fixing a bug in the CALL instruction, and many more not mentioned! 1.5 Disclaimers Of course the software is not guaranteed to work as it is supposed to do. It is more than probable that the program contains some as yet unknown bugs. But, the program as it is now also contains some _known_ bugs! It looked as if it would have taken another few weeks to remove these bugs, and if Hugh and I would have been too perfectionistic, the program would never be released. So here it is, complete with the following bugs: - FORMATting a Disciple/+D disk on a PC does not always work. - Saving a Snapshot to Disciple/+D disk using the built-in Disciple/+D snapshot software only works the first time it is used. Subsequent use of the snapshot button overwrites the first snapshot. It is recommended that you make backups of important Disciple/+D disks before writing to them (especially snapshots). Reading disks is safe. 1.6 Copyrights etc. Amstrad holds the copyright on the 48K and 128K rom. However, they have allowed free use of them. The Disciple ROM is (c) Bruce Gordon / Format Publications. The Plus D ROM is copyright Datel / Format Publications. Multiface and Lifeguard are registered trademarks of Romantic Robot. They are licensed from Romantic Robot for use in Z80. The registered version of the Spectrum emulator 'Z80', and the version distributed with PC Format, may NOT be further distributed. The source codes, which are part of the registered package, may NOT be used in other Spectrum emulators running on PC's. In principle, it is okay to use the Z80 emulator code in an emulator for another Z80-based computer; however, please do contact me if you want to use it. 2. THE EMULATOR 2.1 Starting the emulator The emulator will work on any PC with at least 640K memory, with a VGA, EGA, Hercules, CGA or Plantronics video adapter. If available, it will also use EMS memory, an Adlib compatible soundcard, the SoundBlaster card, a mouse, and an analogue or digital joystick. The emulator will first read in the switches that are given in the Z80.INI file. You can enter switches there just like you do on the command line. Lines starting with a % sign are ignored; they are used for comments. After any switches, you may specify a snapshot file on the command line. This file will then be loaded and executed directly. The extension .Z80 is not necessary. The emulator will also read .SNA files (the snapshot format of, amongst others, Arnt Gulbrandsen's JPP); you don't have to convert them to .Z80 files (but you may want to to save disk space). The emulator tries to figure out what hardware is available, and uses things as it finds them. Most of the time this will work without you having to tell it anything, but if you have to, you can override the defaults by putting switches on the command line. Switches that you use often can be put in the Z80.INI file. If you give a switch a second time, for instance if it is also in the Z80.INI file, it will disable it again. If you're using a Trident VGA with version 3 BIOS, you may see the picture compressed at the top of the screen, while the bottom half contains vertical white lines. This is due to a bug in the Trident VGA Bios. Start the emulator with the switch -xv to get a full picture. Some black-and-white VGA monitors only display one of the three RGB colours (green most of the times), resulting in several Spectrum colours becoming indistinguishable. Use -xb to use grey tones instead of colours. If you are using Hercules, try starting the emulator with -xh on the command line. The emulator will use a non-standard Hercules mode to display a full-screen Spectrum picture. You may need to calibrate your monitor to make the image steady. If you're using Plantronics, try -p and -q to see which gives the best result. If you haven't got EMS memory, the page swapping of the Spectrum 128 cannot be emulated exactly, and, more seriously, it is extremely slow. Although most programs will work, they will be too slow to be of any use. Also, the emulator needs lots of base memory if no EMS memory is present; if you don't have enough, try specifying -xt on the command line to make the emulator use as little memory as possible (by shrinking several buffers). The emulator uses 332K or 572K of base memory (with and without EMS memory respectively), and 47K less in both cases if -xt is specified. If this is still not enough, try to use -xu, which saves 83K, but then Hi Resolution Color emulation does not work anymore. On 386 and 486 machines you can emulate EMS by software using EMM386 for instance. The speed of the EMS emulator determines in part the emulation speed of Spectrum 128K programs, so it may be wise to try a few for the best results. I use QEMM, which seems to be faster than EMM386. The Spectrum 128 has a built-in sound chip. If you have an Adlib compatible soundcard installed, the Spectrum 128 sound will be played through the Adlib card. If you haven't, the loudest of the three sound channels will be played through the internal PC speaker. Sometimes the effect is quite nice, sometimes it is horrible, but it's all I can do on a standard PC. If you don't want to have the Spectrum 128 sound played through the internal speaker, use the switch -xi. If you don't want the Adlib card to be used (for instance to hear the sound through the internal speaker) use -xa. If you're using the Pro-Audio Spectrum 16 sound card, do not install the resident FM.EXE program; it causes problems with the emulator. Do make sure that MVSOUND.SYS is installed in your CONFIG.SYS file, to make the Pro-Audio Spectrum 16 Adlib compatible. The noise channels of the Spectrum 128 sound chip can work on different frequencies, whereas the FM chips of the Adlib card cannot. However, if your Soundblaster is equipped with CMS chips, the noise frequency can be programmed. Specify -xc to use the CMS chips. (These chips are not available on Soundblaster Pro cards, and neither on most Soundblaster clones). If you're living in Belgium or France, you are probably using an AZERTY keyboard. Specifying -xz on the command line will make all letter keys and many punctuation keys work in the right way. If the emulator erroneously detects an analogue or digital joystick, use the switch -kk. The emulator can now also be run under Windows 3.1! However, you cannot use the tape interface, Real mode doesn't work anymore, and the keyboard is not emulated as well as usual, because I have to scan it using BIOS calls. Be sure not to set the keyboard repeat rate too low; an initial delay of 250 ms followed by 10 keys a second will do, but don't make it slower. Some key combinations may not work, such as ALT 4 for $. So if you want to use the emulator seriously then you shouldn't run it under Windows, but it's nice to see three Spectrums run simultaneously... If you let the emulator run full-screen you may use EGA or VGA, if you want to run it windowed you'll probably have to use CGA, because the virtual video display driver of Windows cannot handle the VGA mode I use (although it's only a standard text mode!). You'll probably want other default settings of some parameters (such as the video mode) if you run the emulator under Windows; the emulator will always use the .INI file in the directory of the Z80.EXE file so the other switches must be put on the command line or in a .PIF file. An example .PIF file (which runs the emulator in windowed CGA mode) and a .ICO icon file are supplied Since the execution speed of a program running under Windows heavily depends on other processes, the emulator doesn't try to measure how fast it is running under Windows. It says it runs at 100%, and you can slow it down in the usual way, but the percentage is now relative to the maximum speed, and has nothing to do with the actual execution speed. The emulator will automatically detect whether Windows is running, and act appropriately. To run the emulator in Windows compatibility mode in a normal DOS environment, use -xw. When running the emulator under Desqview, use -e for EGA mode display. At present running under OS/2 is not a good idea as it will crash if the speed is altered! These are the most important switches that you have to specify when you start the emulator. Most of the other switches are used to select default values for various things which can also be changed when the emulator is running. Some useful things to select are default directories for .Z80, .TAP and .MDR files; these will be explained below. 2.2 Using the emulator In this section, the basic functions of the emulator, residing under the function keys F1-F10, are explained. When the emulator starts, you'll see the usual Spectrum copyright message appear on screen. Pressing F1 will pop up a small help screen that explains the function of the function keys and various other special keys. By pressing F10, you enter the main menu of the emulator. Most of the menu options can be chosen directly by pressing another function key; a small help screen pops up if you press F1. If you're somewhere deep in the menu structure from the main menu, pressing ESC will get you one level higher most of the time. Pressing F10 will get you back to the main menu. The 'Select Hardware' menu option sits under function key F9. There are seven major configuration to choose from: Spectrum 48K Spectrum 48K + Interface I Spectrum 48K + SamRam + Interface I Spectrum 48K + M.G.T. Interface (i.e. DISCiPLE or Plus D) Spectrum 128K Spectrum 128K + Interface I Spectrum 128K + M.G.T. This menu also allows to choose the M.G.T. type, +D, Disciple with a pre-loaded operating system supporting graphics output using the Epson format, and one supporting HP-PCL format graphics output. In all configurations except the one with SamRam, the Multiface 128 can be emulated too. The Multiface 128 software is aware of, and can read and write to, the Microdrive of the Interface I and the Disciple and +D disk drive. After a change has been made, pressing ENTER switches to that mode and resets the Spectrum. If you don't want the Spectrum to reset, pressing CTRL-ENTER will switch to the new mode while preserving as much of the runninge program as possible. Switching from 128K mode to 48K mode will almost always crash the program, except if you enter the SPECTRUM command before switching. To use SamRam's monitor on a 128 program, switch the hardware from the main menu, and generate an NMI (Extra functions - N) before returning to the emulator. This will often work, but you can't return to the program without crashing it. On a real Spectrum 128, the menu bar of the startup screen is moved using the cursor keys on the '128 keyboard. These keys simultaneously press a normal cursor key (5,6,7 or 8) and shift. So you can shift the menu bar with shift-6 and shift-7. It is possible to use the PC cursor keys for this; you have to select Cursor joystick emulation (which is selected by default) and press Num-Lock once to have the PC-cursor keys press the Spectrum Shift key too. You could also specify -xs on the command line (or put it in the Z80.INI file) to make the PC cursor keys by default press shift for you in '128 mode; see also the Miscellaneous remarks section. The Save and Load Program options (F2 and F3) will save the whole state of the Spectrum and some of the emulators' settings to a .Z80 snapshot file. It will pack the data somewhat, so that the length of the file varies. The amount of memory saved depends on the current hardware mode; 48K for normal Spectrum, 80K for SamRam, and 128K for Spectrum 128. (Note that the RAM contents of the M.G.T. interface or the Multiface 128 are not saved.) The settings that are saved are those that are program dependent, for instance which joystick emulation is used, and more technical settings like those of the R register, LDIR and Issue 2 emulation, double interrupt frequency and video synchronisation. These are explained below. Loading a .Z80 file will cause several settings to be changed. Resetting the Spectrum will not reset these settings to their default values! Especially the joystick emulation setting change can be confusing, so keep track of that. All settings can be checked and changed in the Change Settings menu, which pops up if you press F4. You can do many things here. explain them all now. The I and O options can be used to redirect the RS232 output; see section 2.13 for information on this. R - R register emulation, and L - LDIR emulation are usually only necessary when loading programs; for remarks on these options see section 2.6, and section 5.1 for more technical details. Other settings and switches are: H - Hi color resolution emulation. To eliminate flickering of moving characters, and to see some color effects otherwise not visible. See section 2.4 for more information. 2 - Issue 2 emulation will turn the emulated Spectrum in an Issue 2 Spectrum. (This option also works, but is out of place, in Spectrum 128 mode). Some very old programs (Blue Ribband, Spinads) will not respond to the keyboard properly on Issue 3 Spectrums, and for these programs this option was added. Seldom needed. S - sound enables you to turn off all sound, useful for late-night playing. D - double interrupt frequency is useful for slow machines, as some programs will run faster when this option is on. If you're typing in a BASIC program on a slow machine, always turn this on, since the keyboard, which is polled by an interrupt routine, will respond much better. On the other hand, some programs will crash with this option active. V - video synchronisation is used to remove the flickering of moving characters in some programs. You can choose between Normal, High and Low. Normal works well for almost all programs; Ghosts and Goblins and Zynaps look much better when this is turned to High. If you see characters not moving smoothly or flicker, or a background not moving as a whole, experiment a little bit with this setting, and re-save the snapshot when you've found the best setting. On fast computers, try to use Hi Color Resolution emulation instead. (For a more detailed discussion of this option see section 2.4 and section 5.1) J - joystick emulation specifies which Spectrum joystick the PC cursor keys (and mouse, and analogue or digital joystick, if available) control. You can choose from Cursor (default), Kempston, Interface 2 and user-defined. As already said above, if Cursor joystick is chosen, the Num-Lock key controls whether Shift is pressed too with a joystick movement. (Since the shift and number keys are pressed exactly simultaneously, it is possible that the Spectrum has already read the Shift key, but not yet the others, when you press both keys down. Sometimes you will therefore get the number 5,6,7 or 8 instead of a cursor movement. If you have used a +3 or +2A Spectrum, you will be familiar with this!) Finally, C - Change speed lets you control the speed of the emulator. As a side effect, slowing down the emulator makes the timing of the various opcodes correspond more exactly to the actual timing on a real processor. (Remember this is not possible on slow PCs!) That concludes the discussion of the F4-'change settings' menu. Let's continue with the other function keys. F5 generates an NMI. This is used to activate the Samram, Multiface 128, or start the Disciple/+D Snapshot facility. If none of these are active it may reset the Spectrum or do nothing. ALT-F5 or CTRL-F5 resets the Spectrum. F6 turns on Real Mode. Try this when the emulator is playing a tune and sounds a little harsh. This mode is needed when you want to load turbo-saved games from tape; see below for more information. F7 and F8 activate the tape and Microdrive/M.G.T. menus. Again, see below for more information. Resetting the Spectrum, or generating an NMI can be done from the main menu too, in the X - Extra Functions menu. This is useful if you want to activate the NMI software of the SamRam for instance just after loading a snapshot file, or just after you changed the hardware mode. In this menu it is also possible to save or load a memory block or screen snapshot; to set a breakpoint or to temporarily shell to DOS. Furthermore, here you can find another sub-menu for the OUT logging feature. If port FE is logged, such a log file can be translated into a .VOC sound sample file. When you're typing BASIC-programs in 48K mode, you'll probably have to look up some Spectrum keywords. Further down in this documentation there is an alphabetical list of all keywords and their key-combination. For 'on-line' help, press ALT-F1 to see the Spectrum keyboard layout. 2.3 Keyboard emulation The keyboard. Letter keys are mapped to the Spectrum's letter keys. The ALT and CTRL keys can both be used for Symbol Shift. Then, there are a lot of keys on the PC keyboard which don't exist on the Spectrum keyboard. Many of them are used, to make things easier: The function keys have several special functions. See the previous section. CTRL-Break and CTRL-ALT-DEL quit the emulator. Better use F10-Q-Y though. The punctuation keys - = ; ' , . / and their shifts: _ + : " < > ? have the effect of pressing Symbol Shift and the corresponding letter key, so you can use these in the straightforward way. The ESC key presses Shift-1, EDIT, used as a sort of ESC key in many Spectrum programs. The Backspace key presses Shift-0, the Delete of the Spectrum. CapsLock presses Shift-2, Spectrum's capslock key. The PC-cursor keys and the numeric keypad keys 8,4,6 and 2 control the Cursor, Interface 2, Kempston or user-defined joystick. The TAB key, and 0,5 and ./DEL on the numeric keypad control the fire button. If the Cursor joystick is selected, you can select whether Shift should also be pressed with the NumLock key (but see the discussion above of the -xs switch). If you're running the emulator on a slow computer, try selecting double interrupt frequency. Most programs poll the keyboard by interrupt, in any case the ROM does, and doubling the frequency with which this happens will make the emulated Spectrum react much more quickly on your keystrokes. If you've got an AZERTY keyboard, the standard mappings of the keys won't work at all properly. Include the switch -xz in your Z80.INI file in this case; many punctuation keys will now also work properly. There is no support for other non-US keyboard layouts; sorry! 2.4 Screen emulation There are two different ways the emulator can emulate the screen. The standard way, in which 50 times an emulated second the screen is checked for changes, and they are subsequently displayed on the monitor. This works fine, and was the only mode available in previous versions. It works basically the same with all video modes; however, some are much slower than others. EGA is notoriously slow, due to the ugly way it has to be addressed. VGA is definetely the fastest. EGA and VGA are the only video modes in which the colour of the overscan can be controlled; in these modes, some emulation of border effects (loading stripes, for example) can be done. You don't see these effects in the other video modes. Changing the overscan colour results in 'snow' lines appearing on the screen. It is possible to eliminate these by waiting until the video adapter is in horizontal retrace. This takes some time, therefore the emulator doesn't do this in Real Mode. Real time loading requires minimum delay, so the screen does not update. You can select the update option, but you risk Tape Loading errors! In the standard mode, the point (relative to the 50 Hz interrupt) at which the screen is displayed can be controlled by setting the 'Video Synchronisation Mode' to normal, high or low. If you see moving characters flickering excessively, try changing this setting. For instance, BC's Quest for Tires won't look at all good with a wrong setting; many programs display subtle differences in different modes. In the Hercules, CGA and Plantronics modes not all colours can be displayed. In EGA mode, all colours can be displayed, but some colours have the same intensity in Bright 1 as in in Bright 0. Only in VGA mode the colours resemble closely the Spectrum originals. The other video emulation mode is called Hi-resolution colour emulation mode (HCR mode). In this mode great care is taken to display each video line at exactly the right time, and also the precise times the border colour is changed is used to build the border pattern. In this mode, every hi-resolution colour effect is visible; all flickering problems are also eliminated (provided they weren't already there on a real Spectrum!), so no need to adjust the Video Synchronisation Mode. The drawback of using this mode is that it is much slower, since the emulator has to keep track of the number of T states passed, and also has to grab a line from screen memory and put it in a buffer 192 times, 50 times a second. But on fast computers, 486's and up, the emulator can still easily emulate at 100%. HCR mode only works with a VGA video adapter. Writing those routines also for CGA and Hercules seems silly; and I don't even want to think about rewriting them for EGA boards. Finally, when loading turbo-saved programs in Real mode, screen updates are suspended because they take too much time (even on fast computers). You can refresh the screen by pressing U - Update in Real mode, but you should do this only if you're sure that the emulated program is not loading a block, for pressing U during loading is a sure way to get a tape loading error. 2.5 Sound emulation The Spectrum beeper is emulated by the PC's internal beeper. Because every 1/50th of a second the screen has to be updated, and this takes a little time even if there are no changes, the sound is a bit harsh. If you select real mode, the emulator won't update the screen and music will sound good. If you select HCR mode, the sound will be even harsher than it does in normal mode. The sound of the Spectrum 128's sound chip is played through the Adlib card; if you haven't got such a card some notes are played through the internal speaker. That sound will be turned off, however, as soon as the program makes a sound through the normal speaker of the Spectrum. Some Spectrum 128 programs use the sound chip and the beeper at the same time, and this won't work properly without an Adlib card. 2.6 Loading programs from tape This emulator can load programs that are saved to tape in the usual way, but also turbo-saved programs can be loaded. Furthermore, you can make a disk file act as an 'emulated tape', so that the normal SAVE and LOAD commands can be used to transfer data to and from disk easily. The emulator can load programs from .VOC sound sample files. 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. How to use .VOC files is described in section 2.8 below. The current section is about loading programs directly from tape. First of all, you need an interface to connect the tape recorder to the PC. There are two ways of doing this. You can use a tape interface on the LPT port. A circuit diagram is in the DIAGRAM.Z80 program, or you can obtain a ready-made interface from B G Services, see section 1.2 for more details. Version 3 can also use the SoundBlaster for tape input. This is easier since no additional interface is needed. The LPT tape interface however is more robust in loading. When using the SoundBlaster, you have to be careful not to put the volume level too high, since otherwise the SoundBlaster will clip, which is a sure way to producing tape loading errors. The LPT tape interface is not sensitive to this. If you want to save programs back to tape, you have to use the LPT interface; it is not possible to use the SoundBlaster for this. (There is a way to save programs in standard format to tape though; put them in a .TAP file - see below - convert it to a .VOC file and play this sample to a tape. Use a good sample player, one that doesn't halt for half a millisecond between blocks!) In the program DIAGRAM.Z80 a tape tester is present. The LPT tape interface has to be calibrated, and this program can also be used to check the volume level when using the SoundBlaster as input device. The variable resistor of the LPT tape interface has to be adjusted so that the bar, which should go to 0% when the volume is down, points just below 50% at normal volume. In the case of the SoundBlaster, when the volume is turned up, the bar first goes from 0% to 50% and over, and after that drops below 50% again. The volume has to be set such that it is below 50% before the maximum. You have to tell the emulator which LPT port you use for tape I/O. Use command line switch -b2 for example to select LPT2 for tape input (or put it in the Z80.INI file). Use -xo to select the SoundBlaster for tape input. It uses base address 0220 by default; if this is not correct, use for instance -xq 0240 to specify address 0240. The emulator does not use the SoundBlaster interrupts. There are two ways to load programs: in 'real' or normal mode. In real mode, the emulator doesn't update the screen or scan the keyboard, so that the emulated Spectrum program can run smoothly. The emulator has to run at about 100%, but then you're able to load everything a normal Spectrum would load, including turbo-saved programs. The only thing you see on screen are the loading bars in the border (on EGA or VGA screens). Real mode is selected by pressing F6. Saving programs in real mode is a bit useless but it works; enter the SAVE command, press a key to start saving and quickly press F6 when the saving starts. It will continue in real mode. If your computer is just fast enough, don't slow the emulator down too much. Because the IN instruction is relatively slow, the emulator has to run at about 110% for the best results. If your computer is really fast, you can best slow it down to exactly 100%. If your computer is just a bit too slow, you can try to make your tape recorder run slower too (usually you can do this by adjusting a little screw at the back of the motor), I successfully loaded several speed-saved programs at 90%. In normal mode, the standard ROM loading and saving routines are 'trapped' (at addresses 04d8 and 056a) when they're about to start saving or loading. A routine in the emulator itself then takes over, and loads or saves a block to tape (or a disk file, see below). When you enter LOAD "", the emulator starts loading using its internal loading routine. You'll see a blue window appear. Pressing F6 now will switch to Real mode, and the emulated Spectrum program will continue the loading process (if it is running at 100%). Every time a block is loaded or saved, a window contiaining some information of the block to be loaded or saved appears. If you don't want this, for example because you want to enjoy the loading screen, specify -tx on the command line. Using these SAVE and LOAD routines has a great advantage as well as a disadvantage compared to using the Spectrum's own routines in real mode. The advantage is that the internal routines work on every machine, no matter how slow or fast, without having to make the emulator run at 100%. The disadvantage at using them is that they obviously won't understand turbo-saved files. For normal use, these internal routines work much easier, and real mode loading is only necessary for turbo-saved and well protected programs. Today, most programs are protected. The emulation of the Z80 processor has to be exactly right, or those strange decoding routines that use all features of the processor the programmer could think of, will definitely crash. It is most important to switch the R-register and LDIR emulation on, as virtually all protected programs use at least the R register. Sometimes programs are real sensitive to the timing of the interrupts; if programs refuse to load, try sampling the first few blocks in a .VOC file (see below) and load it from there (of course with R register and LDIR emulation on); when loading from VOC files, interrupt timings are exact. 2.7 Using .TAP files The emulator uses files with the extension .TAP to hold a piece of 'tape', with several blocks on it. Each block is usually either a header or a data block; a normal file thus consists of two blocks. There are two modes of operation when loading and saving to disk files, single and multiple .TAP file mode. In single .TAP file mode, each block saved is appended to the end of the .TAP file, like what would happen if you were actually saving to tape. In the same way, when loading in single file mode, each time the ROM wants to load a block, it is presented the next block in the .TAP file. 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. So, entering LOAD "rubbish" will show all headers in the .TAP file, just as an actual Spectrum would show all headers on the tape if you left the tape running. If the last block is loaded, the file pointer is moved to the start again. So a .TAP file can be considered to be an infinite tape. Single .TAP file mode is useful to save whole programs to disk, or for multi-load games that need to load in levels as you play. A sort of 'random access' file management is also useful, for instance when you're developing a program and need to save several pieces of data to disk and later load back a specific one. This can be done in single .TAP file mode (by positioning the file pointer using the Browse function), but there's a different mode of operation that makes things easier: multiple .TAP file mode. In fact, by default the emulator is in this mode. When the emulator is in multiple .TAP file mode, it will read all blocks from all .TAP files in a specified directory, one after the other. When it has finished reading the last one, it will start all over again. When saving, the emulator will put the two blocks of a normal file, the header and the data block, in one .TAP file with a unique name made up of the printable letters of the file name and a two-digit number. The name of the .TAP file is irrelevant to the emulator, but to have it resemble the name of the actual Spectrum file you saved is simply convenient. If the Spectrum program saves a data block to tape without first saving a header, the .TAP file produced will contain only this data block, and the DOS file name will be HDRLES, with a two-digit number appended to make it unique. The format of the .TAP files saved in multiple .TAP file mode is exactly the same as the format used in single .TAP file mode. You can easily string together .TAP files; for instance a number of .TAP files created in multiple .TAP file mode can be put into one big .TAP file simply by concatenating them, e.g. COPY /B FILE1.TAP + FILE2.TAP ALL.TAP. Now you know what you can do, but how to get the emulator to do it? That's what the final section is about: the tape menu. Press F7 to enter the tape menu. Pressing S will select or de-select single file mode. As a default, multiple .TAP file mode is selected. In this mode there are three other possible choices in the menu. First of all, D selects a tape-file directory where the .TAP files will be saved into and loaded from. A default directory can be selected by putting the -xs switch on the command line or in the Z80.INI file; for example -xs c:\spectrum\taps. The I and O options are used to select the source and destination of the saving and loading: the LPT port (in/out) or SoundBlaster port (only input) for a physical tape recorder, or 'disk' for disk files. Input and output are directed to disk by default if a default tape file directory is given by means of a switch on the command line or .INI file. If Single .TAP file mode is selected, different and more menu options appear. With R and W, the input and output tape files can be selected. They may be the same. If a specified output file already exists, you may choose to append to or overwrite this old file. Saving is always at the end of the file; loading always starts at the beginning of the .TAP file. With the B option - Browse - the position of the file pointer into the input .TAP file can be changed. If you, for instance, type LOAD"" instead of LOAD "" CODE, the first header is read, and you would have to read all other headers before trying to load the file again. With the browse option you can conveniently change the file pointer. Of every header (that is, every block with flag byte 0 and length exactly 17) the name and type, and of every data block the length is shown. The option B can also be used to delete specific blocks from a .TAP file. Make sure you do not only delete a data block or a header, or the ROM may get confused. (Double data blocks will be skipped, but double headers can generate Tape Loading errors). As in multiple .TAP file mode, I and O are used to specify the source and destination for saving and loading. If you enter a .TAP file name with R or W, this will automatically be set correctly. You can then always reset the input or output back to physical i/o again, of course. Finally, in Single .TAP file mode you can use 'tape mirroring': loading programs from tape (in normal mode, i.e. not using Real mode) and at the same time saving a copy of each block loaded into a .TAP file. This .TAP file can later be used to load the program again, in case something goes wrong. There are two ways of mirroring: normal mirroring and exact mirroring. The last one must be used only in exceptional cases; it will always make a copy of a block, even if it had a tape error (the corresponding block in the .TAP file will also have a tape error). This causes ticks in leader tones to make 0-byte blocks, so the .TAP file may get messy. Do not use exact mirroring if you don't really have to; I think normal mirroring will always work in practice. If you try to leave the tape menu when for instance tape mirroring is selected, and no output filename is given, the emulator will warn you and will insist that the error be corrected. Yes, it's stubborn! One final point about multiple .TAP file mode. If you select a directory that contains no .TAP files at all, and try to load from the directory, the emulator will reset itself to physical tape I/O. Select a different directory and try again. Note that simply putting a .TAP file in the directory does not reset the emulator to multiple .TAP file mode, as it will not look in the directory again as soon as it uses physical tape I/O. 2.8 Using .VOC files .VOC files contain sound samples, so they can also contain the sound of a computer tape. The emulator can load programs from these sound sample files, by keeping track of exactly how much time elapses during the emulation of a program, and every time the emulated Spectrum program reads the EAR port, supplying it with the right sample. Via an intermediate file, a .OUT log file, the emulator can also SAVE and produce a .VOC file with the right sounds in it. In this section .VOC file playback is discussed. For a discussion of how to SAVE to a .VOC file, or how to produce a .VOC file of Spectrum-generated music, please read section 2.18 about the OUT2VOC utility. 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 (by a factor of two, roughly) 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 that even slow computers can load turbo-saved programs, provided that they can read samples. And on fast computers, the emulator can be set at the maximum speed, to load programs much faster than usual. Using .VOC files is sensible for instance when you have a multi level game, where subsequent levels are saved in a non-standard format, so that they cannot be stored in .TAP files. The higher levels can be stored in .VOC files, and loaded when needed, without having to re-install the cassette player. 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. The problem with a lot of sampler programs is that they leave a small gap between subsequent blocks within the .VOC file. This gap is usually inaudible, but it causes tape loading errors. It is very important that the sample is taken without any gaps. The READVOC program reads samples from the LPT tape interface or the SoundBlaster, and can take long continuous samples without gaps. Because the emulator converts the 8-bit sample to a simple High or Low value, READVOC also uses only two values for the signal height. This results in highly compressible .VOC files; compression factors of about 25 are no exception. It is also possible to convert .TAP files to .VOC files, with the utility TAP2VOC. This was useful to test the .VOC playback feature, and also makes it possible to write .TAP files back to tape using a sample player. To play back a VOC file, press F7 to go to the tape menu, and press P to select the VOC file playback menu, and enter the name of the VOC file to be played. The VOC file is now in stand-by. Just for convenience, the emulator starts playing back the VOC file as soon as the ROM loading routine is hit; that is, as soon as you type LOAD "" and ENTER. 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!). When the end is reached, it will alert the user, and switch back to normal emulation mode. 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. It is also possible to start play-back without LOAD "", which is necessary for instance when the VOC file consists of a turbo-saved block. And finally, it is possible to wind and re-wind the VOC file, as if it were a tape. The position is displayed in minutes, seconds and hundreds of seconds. 2.9 Multi-load games Some games have several levels saved on the tape, to be loaded when a previous level is completed. There are several ways to handle these programs. First, simply playing it, and loading next levels using a real tape-recorder seems a good solution. If the data blocks in which the level data is saved are written to tape in the standard format, you can convert them to .TAP files. It is most likely that the program uses the usual ROM routine to load the blocks, and this routine is trapped by the emulator, so that instead of loading from tape, the blocks can be loaded from these .TAP files. To convert the blocks to .TAP file, use a standard tape-to-tape copy program and, in the Tape menu (F7), specify that tape output should go to some file. If the blocks are just code blocks with header, simply enabling the Tape Mirroring option and loading the blocks at 16384 (ignore the crashes that most probably result; just reset the emulator and continue) will do the trick. If the blocks are headerless, then go to the SamRam, press NMI (F5), D for Disassembler, and L:4000 (with tape mirroring enabled) to load and mirror each block. Here also, ignore possible crashes which result if the block is too long. A general method is to store the level data blocks in .VOC sample files. These files are huge, lengths of several megabytes are common, but they can be compressed very tightly (if you used READVOC to make them). Then, if you need a block, simply shell to DOS, decompress it, and load it. Finally, if you want to hack into the program, you can also try to find the routine that is responsible for the loading of a level. At the appropriate point, enter an ED F6 instruction, with A containing the level number, and HL the address at which the block is to be loaded. The emulator will then look for the relevant file and load it. The name of this file is the name of the snapshot last loaded, where the level number (in decimal) is appended to the end. If this results in more than 8 characters, the shapshot name is made shorter. The extension of these files is always .DAT. If the file is not found, the user is informed of the level number, and given the opportunity to specify a name. This ED F6 feature first appeared in XZX 0.5.2, and was devised by Russel Marks. 2.10 Using the microdrive Compared to the tape, this is really simple. Cartridges are emulated by files of 137923 bytes. These files have the extension .MDR, and can contain up to 126K of data. The emulator emulates 8 microdrives, the maximum amount the Interface I software can handle, and each of these cartridge files can be inserted in any of the 8 microdrives. (Do not insert one file into more than one microdrive; this will cause problems with the buffering done by the emulator as well as the Interface I, and might result in data loss). Press F8 to enter the microdrive menu. Press 1 to 8 to select a microdrive, and I to insert a microdrive cartridge. You can select an existing one, or type a new name. If the cartridge file isn't found, the emulator asks whether it should create it. When created, you'll have to format it first; if you don't, you'll get a 'microdrive not present' error when you try to read it, just as happens with real unformatted cartridges. To format a cartridge, type FORMAT "m";1;"name" After this the cartridge should have 126K of free space. The cartridge can be write protected; see the menu option in the F8 menu. This is a characteristic of the cartridge, and the write protect tab information is therefore stored in the cartridge file. As on the real Spectrum, you'll have to be careful with OUT's if a cartridge is inserted. Try OUT 239,0 (on a real Spectrum, this turns on the microdrive motor) and wait a few seconds; most of your data will be lost! You can stop the microdrive motor by typing STOP (or, more generally, generate an error). The microdrives are emulated at IN/OUT level. This means that every utility or program that uses microdrives ought to work on the emulator. Most utilities use hook codes, and these will certainly work. The GAP line is emulated; this signal is activated if the interface I senses a piece of tape with no data on it. If the checksum of the first header block of a microdrive header or data block is not correct, that block is considered to be a GAP. This will only happen if some utility writes a bad block to microdrive deliberately, if the file is newly created and unformatted, or when you type OUT 239,0. To try the microdrive, load a Spectrum program, switch to Spectrum 48K+If.1 mode if necessary, and turn on Multiface 128 emulation. Press F8, I(nsert cartridge), enter some file name and create an unformatted cartridge, return to the Spectrum and press F5 (NMI), S(ave), enter some name, choose M(icrodrive), choose F(ormat) and wait a few seconds, then choose S(ave). Then reset the Spectrum, and type LOAD *"m";1;"name" to re-load the snapshot you just made. Alternatively, switch to SamRam mode, make sure a formatted cartridge is present, press F5, S, M, S, name, and press ENTER twice to have the SamRam save a snapshot to microdrive. This snapshot can only be loaded in SamRam mode. 2.11 Using the DISCiPLE and Plus D interfaces For an explanation of the commands of the DISCiPLE and Plus D interfaces, see the relevant sections in chapter 4. The ROM of the DISCiPLE is supplied with the emulator, together with two version of the D.O.S. pre-loaded in RAM. The ROM of the Plus D interface is not supplied, for copyright reasons. The emulator will only emulate a Plus D interface if it can find a file PLUSDROM.BIN in the emulator's own directory. If you have a Plus D yourself, you can transfer the ROM in the following way. Load the operating system from a Plus D system diskette, and save the entire ROM, together with the operating system, to disk by entering SAVE d1"rom" CODE 0,16384. Then, start the emulator and choose hardware mode Spectrum 48K + Disciple (not Plus D of course), then type LOAD d1"rom" CODE 32768. Finally, press F10, X, S for Save Data block, set start address and length to 8000 and 4000 (hexadecimal) respectively, and save the ROM under the name PLUSDROM.BIN. If you re-start the emulator now, it will emulate the Plus D too. The emulation of the DISCiPLE or Plus D interfaces in turned on simply by choosing the right hardware mode in the F9 menu. Changing the M.G.T. type will result in a Spectrum reset (unless you change with CTRL-ENTER), since a different ROM is switched in. By default, disks 1 and 2 refer to drives A: and B: respectively, but this can be changed in the F8 menu. 2.12 Using the Multiface 128 The following is an excerpt from the original Multiface 128 documentation: MULTIFACE is a registered trademark af RORANTIC ROBOT. Multiface 128 is a true multi-purpose interface with 1) fully universal and 100% automatic back-up facility for tape, microdrive, Discovery, Plus D or Disciple (although the Discovery is not emulated, so that that feature is not usable), 2) 8K RAM extension - suitable for GENIE, LIFEGUARD, or as a buffer, 3) MULTI TOOLKIT to study/modify/develop programs, POKE infinite lives, etc. Multiface 128 works on the Spectrum 48/128. It can be used any time in any mode; it is immaterial what is inside the Spectrum at that moment or how or from what source (tape, disk, cartridge) it has been loaded (or typed in, etc.). Multiface does not save programs, but computer contents (compressed RAM image). Upon returning from the M128 or upon re-loading, the programs continue as if never frozen. To use the M128: 1) Push the NMI key (F5) 2) Select the required option from the menu The MAIN MENU options are: Exit: to abandon the Multiface and exit to BASIC (provided BASIC is present). By using exit, you come out of the Multiface entirely. All efforts are made to preserve the current program in the Spectrum intact. The main condition is the existence of standard system variables - without these the Spectrum crashes. A successful exit gives you full access to the program. To restart it, if needed, you must know the starting line or address. Exit is impossible in the 128K mode when the edit ROM is paged and Spectrum ROM is off; in such cases it does not appear on the menu at all. All in all, you can only exit to BASIC if it exists - it is like jumping into a pool: a joy if it's full of water, a crash if there is none. Return: to continue the program. Save: to proceed to the SAVE routines: a) input the name of the program. Up to 9 characters (or just press ENTER to the input RUN automatically as a default) b) save to: Tape, Microdrive, Opus [does nothing], Disciple (use D for Plus D too). You can save the entire program (including the screen), or the screen only. Programs are compressed to take the minimal room possible and to load faster. Screens saved on their own are left intact as standard Spectrum screens. c) Format microdrive cartridges. Cartridges are automatically named after the programs to be saved. Tool: to access the MULTI TOOLKIT routines. quit - to return to the main menu Enter - to PEEK and scroll through addresses or to POKE Space - to allow you to type in a new address hex - to toggle between hexadecimal and decimal display format reg - to point to the Z80 registers as they were when the program was frozen window - to open a window with full on-screen editing using the cursor keys. The flashing window address corresponds to the address in the bottom edit line. The window display is by default in hex, but you can change it to text - to see the 128 bytes in the window as ASCII text. select - to inspect RAM banks 0-7 in 128K mode. Press s + the bank number Print - to dump screen to printer. For printer interfaces using COPY command. You can POKE address 8200 (decimal) with the following values, if you wish to 113 to turn the line feed on (cr+lf) 112 to turn the line feed off (cr) 17 to dump screen as text with the line feed on 16 to dump screen as text with the line feed off Jump - not to return, but jump to another address. Strictly for machine code users only. Enter the address to jump at 8192/3 (low/hi). You can jump to Spectrum ROM/RAM and to M128 8K RAM. As the M128 overshadows the ZX ROM (8192-16383), address 8194 determines the paging status: if it is 0, the M128 RAM remains paged, 1 pages out the RAM and any other value disables the jump command completely. [Note: if it is 0, also the M128 ROM (0-8191) remains paged.] You can jump from the main menu, and you can also pre-program M128 to jump directly upon NMI (F5) and by-pass the M128 ROM software entirely. To program the direct jump, POKE 8192-3 with the jump address, and then also 8195-7 with a special identification word RUN (i.e. 82,85,87). Whenever you press NMI now, you will jump to the predefined address and not see the M128 menu. To return from your program to the program you stopped, use RST 0. To revert back to the Multiface normal operation, press NMI and BREAK (shift+space) simultaneously. This also cancels the code word RUN. In standard mode M128 uses 8192-11144 as a buffer (8192-13496 once you proceed to SAVE) and overwrites anything in there. Using direct jump, you have 8257-16338 available. Clear - to clear the extra 64K RAM bank (in 128K mode only!). You can clear any time, but it is only useful with 48K programs in 128K mode. However, you should save 48K programs in 48K mode anyway. Also, for obvious reasons, clearing the banks in 128K programs is not a good idea. The actual M128 has a software on/off switch, so that it could be made completely invisible to programs until the NMI switch was pressed. This software switch is not emulated. The M128 could be turned off by pressing 'O' in the main menu; this does not work on the emulator. You can turn off the M128 in the Select Hardware (F9) menu. Using the extra 8K RAM - M128 has an 8K Rom containing its own software, and an 8K RAM used as a buffer. You can use the 8K RAM for your own mcode routines or for data (but not for BASIC). The RAM must be paged in machine code to be accessed: use IN A,(191) to page in, and IN A,(63) to page out. The BASIC In and Out commands can not be used here (they work, but result in a crash). The 8K RAM overshadows the Spectrum ROM and thus anything contained in the M128 RAM cannot make any calls to the Spectrum ROM, as they both occupy the same area. The M128 RAM routines should therefore be self-contained, independent of the Spectrum ROM. Poking infinite lives - To POKE, say 31000,0, first load the program as usual. When it's loaded, press NMI (F5) and select the tool by pressing T. When the toolkit menu appears, press SPACE and type 31000. Once you type 5 digits the cursor automatically moves to the value field (no need to press ENTER), so type 0 (value is 1-3 digits long) and this time press ENTER. Finally press Q to quit the toolkit and R to return to the program. The Multiface 128 was designed by Romantic Robot UK Ltd, 54 Deanscroft Avenue, London NW9 8EN, tel. 081-200 8870. 2.13 Using the RS232 channel This was the only Spectrum i/o channel that could be used in the early versions of the emulator. Using .TAP files instead of the RS232 channel is often easier, but sometimes using the RS232 channel can be very useful too, for instance if you've got a null-modem lead that connects a Spectrum with interface I to the PC you can use it to transfer data and programs easily. Furthermore, the RS232 channel is the easiest way to let the emulator communicate with a PC printer. Several things send their output to the channel designated as 'RS232 output channel'. First of all the ordinary Interface I RS232 "B" and "T" channels. Secondly the 128K printer "P" channel. Thirdly, ZX Printer output is converted to a format appropriate for Epson or HP PCL printers (works for most dot matrix, and most laser/inkjet printers respectively) and also sent to this channel. Input from the 'RS232 input channel' is sent to the Interface I's "B" and "T" channels. The Interface I RS232 port, the "B" or "T" channel, behave slightly differently. The first, binary, channel is the raw channel. It will let all data go through unchanged. The "T" channel won't let all control codes through and will expand any keyword; useful for LISTing a program but otherwise annoying. The Spectrum 128 has its own RS232 port; it is called the "P" channel. Output to either the Interface I's or Spectrum 128's own RS232 port will all be processed as 'RS232 output'. The output to the RS232 channel can be routed to an LPT port, to a COM port or to a file on disk. Input can come from either a file or a COM port. If you want to use the RS232 channel for printing using LPRINT and LLIST (shorthand for PRINT #3 and LIST #3), be sure to open that channel for output to RS232; by default it sends its output to the ZX Printer, which is not supported. You can open the channel by typing OPEN #3,"B" (or "T" for listings, or "P" on a Spectrum 128). Input and output are buffered. This is important to remember when you're transferring files using the SAVE and LOAD *"b" commands of the Interface I. If the header is missed, for instance if you try to load the wrong file type, re-sending the file will not directly work because there will still be bytes in the buffer. You have to clear the input buffer before re-sending the file. When inputting from a disk file, the file pointer can be reset to point to the start of the file again to re-read the header. When inputting from or outputting to a disk file, the read or write position is displayed as a byte-count. An sign will appear if an input file is read completely through to the end. The RS232 redirection options are in the Change Settings (F4) menu. When using a COM port, make sure you have initialised it before starting the emulator with the Dos MODE command, for instance MODE com1:96,n,8,1 initialises COM1 to send and receive at 9600 baud, no parity, 8 data bits and 1 stop bit, the default for the Interface I. Here is how to transfer programs from a Spectrum to the PC using the RS232 lead. First, you need a null-modem lead. I myself use the following cable: Spectrum 'AT' 'PC' (9 pins) (9 pins) (25 pins) 3 TxD ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ RxD 2 3 4 DSR ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ DTR 4 20 ÚÄÄÄÄ CTS 7 4 ÀÄÄÄÄ RTS 8 5 7 GND ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ GND 5 7 (so CTS and RTS have to be connected!) This is not a full null-modem lead; you can only send data from the Spectrum to a PC. If you have an Interface I, you can use the LOAD *"b" and SAVE *"b" commands on both your real Spectrum and the emulator to transfer programs and data. It's best to first type LOAD *"b" and then SAVE instead of the other way around. If you have problems with transferring data, try to lower the baud rate to 4800 or 2400 baud; this sometimes helps. If you don't have an Interface I, but do have a printer interface using RS232 leads, then you can transfer data using LPRINT on the Spectrum side, and INKEY$ #3 on the emulator side. It needs a little bit of programming. 2.14 On joysticks and mice The emulator support several joysticks and the Microsoft mouse, to control several Spectrum joystick interfaces, and the AMS Mouse interface. First, joysticks are discussed. As was already said in the introduction, the emulated Spectrum joystick (Cursor, Interface 2, Kempston or user defined) is controlled by the PC cursor keys and 5/0/. on the numeric keypad and TAB as fire keys. The emulated joystick can also be controlled by a mouse, or by a real joystick, either analogue (PC standard) or digital. The analogue joystick support is rather straightforward. If you've got one, it works - it couldn't be simpler. The digital joystick support is less obvious, since PC's don't support these. To use digital joysticks, Ruud Zandbergen has made a device that uses the two inputs of a normal analogue joystickinterface to connect a digital joystick to a PC. Here's the circuit diagram: 15 pins male (pc) 9 pins male (joystick) 1+9 <ÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄ> 7 (5V) ÚÁ¿ ÚÁ¿ ÚÁ¿ ÚÁ¿ 4 x 1 kê ³ ³ ¬ Watt ³ ³ ³ ³ ³ ³ ÀÂÙ ÀÂÙ ÀÂÙ ÀÂÙ 3 <ÄÄÄÄÄÄÄÄÄÁÄÄ> 4 (up) ³ ³ ³ ³ ³ ³ 6 <ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄ> 3 (dwn) ³ ³ ³ ³ 13 <ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄ> 1 (rght) ³ ³ 11 <ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄ> 2 (lft) ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 2 <ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ 47 ê ¬ Watt ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ> 6 (fire) ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ 4+5+14 <ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ> 8 (0V) 4+5+14 means: connect pins 4, 5 and 14. The same applies for pins 1 and 9. Here's the list of ingredients: 1 x 9 pins D plug, male 1 x 15 pins D plug, male 4 x 1kê , ¬ Watt resistors 1 x 47 ê, ¬ Watt resistor piece of 7-wire flatcable Everything can be fitted into the 15-pins plug. Make sure the resistors don't touch the other blank connections! This interface can be used for all usual digital joysticks, with or without auto fire (that is every joystick that work with a Kempston joystick interface, or that work on a Commodore 64/Amiga or Atari). The joysticks for the Spectrum +2/+3 will not work, however the pin layout is easy to change. This joystick interface needs an analogue PC-joystick interface on which you can connect TWO analogue joysticks (on one plug!). Most cards can do this, but some multi-I/O cards support only one joystick. Check the documentation of your I/O card to see whether your joystickinterface is suitable. The soundblaster joystick interface works fine. A number of PC games will behave strangely when the digital joystick interface is connected; they run very slow or crash. When this happens, remove the joystick interface (not only the joystick!). With version 3, the Spectrum joystick (Cursor, Kempston, Sinclair 2 or user defined) can not only be controlled by the cursor keys or a real joystick, but also by a mouse. Specify -km on the command line to have the mouse control the joystick too. (By default, this switch is already in the Z80.INI file.) Finally, the Microsoft mouse can control the AMS Mouse interface, as supported for example by Art Studio. Specify -ka on the command line to select this option. The mouse will not control the joystick anymore. Because of I/O address clashes, the AMS Mouse does not work with SamRam or an M.G.T. interface enabled. Also, since the AMS interface must be initialized, and the state of the AMS interface is not saved in the .Z80 snapshot file, it may be necessary to make the snapshot before the point at which the Spectrum program initializes the AMS interface. The program Art Studio re-initializes the AMS interface regularly, however, so with this program you don't have to worry about it. 2.15 The utility ConvZ80 This program converts between various snapshot formats, and it can also convert various tape file formats to .TAP files. Currently it supports .SNA format (used in various emulators, such as JPP, Peter McGavin's emulator on the Amiga, and XZX), the .SP format of VGASPEC and SPECTRUM, the .PRG format of SpecEm, and all old .Z80 file formats. If conversion is to a .Z80 file, the old (v1.45) format will be used. This is still supported by the emulator, and some other programs do not support the new format. Note that, because of this, ConvZ80 will not convert .Z80 files containing snapshots of 128K or SamRam programs. CONVZ80 recognizes what it should do by the extension of the files you enter on the command line; to distinguish between VGASPEC's and SPECTRUM's .SP formats you can use the switch -o. If the extension consists of digits only, it is taken to be a ZX tape file, and if it contains non-digits and is none of .SP, .Z80, .SNA, .PRG or .TAP it is regarded as a SpecEm tape file. SpecEm can load .PRG snapshot files, but cannot save them. However, it emulates the Multiface I, which can save snapshots to tape. SpecEm will save these blocks as tape files to disk. If you convert these to a .TAP file (in the correct order!), you can load them into Z80 and save the program as a .Z80 file. 2.16 Converting file formats - the utility CONVERT This section is about the utility CONVERT, which can convert some of the Spectrum's own format into each other, and also converts some of the emulator's formats into others. It is not about converting files from other emulators; read section 2.15 if you want to know about that. CONVERT was useful when the emulator could only communicate with snapshot files and the RS232 link. It has become less useful now, with .TAP files and the possibility to load and save blocks directly into and from Spectrum memory, but it still has some useful features. It can read three types of input files: pure ASCII, pure bytes (for instance a .SCR screen dump), and files produced by a SAVE *"b" command. Output is pure bytes, ASCII with either CR (Spectrum standard) or CR/LF (PC standard) for line breaks, SAVE *"b" files containing a Basic or code file, a .PCX or a .GIF file. So what can you do? Main uses are adding LF (10 hex) bytes to a text file produced by the Spectrum; converting a code block into a SAVE *"b" to load it into the Spectrum using LOAD *"b" (and the reverse of course: converting a SAVE *"b" file to pure bytes), and converting a screen dump to .PCX or .GIF graphics files. Less useful, but possible: LISTing a program (SAVE *"b" file) to produce readable ASCII, and the reverse: converting an ASCII listing to executable Basic again. If you want to make a .PCX or a .GIF file, input should be a SAVE *"b" file of a screen (length 6921 bytes exactly) or a bare .SCR screendump (length 6912 bytes). You can make screendumps by selecting the X-Extra functions menu from the main menu. 2.17 The utilities Z802TAP, TAP2TAPE and TAP2VOC The SamRam has built in it some snapshot software. Using this software you can save any 48K Spectrum program to tape or to a .TAP file, as is explained in section 3.2 below. But the SamRam software cannot handle a 128K program. The Multiface 128 can also write a snapshot to tape, but in some cases it is still preferrable to use TAP2TAPE, since the latter produces less and shorter blocks, and doesn't corrupt the screen as much as the Multiface code does (on Spectrums without Multiface). The utility that can convert a 128K snapshot (and 48K ones for that matter) to a .TAP file is called Z802TAP. The .TAP file includes a basic loader, and a loading screen if you want. Z802TAP compresses the blocks it writes (using a better method than used in compressing .Z80 files) to save loading time. If you don't want it to compress the blocks, for instance when you want to take a look at the ram pages of the Spectrum 128, specify -u when you run Z802TAP. You can load the converted program simply by executing Z80 -ti tapefile and typing LOAD "" (for a 48K program) or changing the hardware mode to Spectrum 128 and choose 'Tape Loader' in the menu. Of course you could also use Multiface 128 or the SamRam to convert a snapshot to a .TAP file. The program TAP2TAPE writes .TAP files back to tape. The program consists of a batch file TAP2TAPE.BAT, which executes the TAP2TAPE.Z80 file using the emulator. The .TAP file is written to tape exactly as it is, so that if a block contains a tape error, it won't load correctly from tape either. If the entire .TAP file has been saved the emulator will start loading from tape. At that point, press space once to return to DOS. The TAP2VOC program converts the tape block in a .TAP file to the corresponding bips and clicks. The resulting .VOC file will be rather large. It can be loaded back into the emulator, which is rather silly since using the original .TAP file is better in all respects, or you can write the program to tape using a sample player. 2.18 The utility OUT2VOC - and how to make .OUT files The emulator can log OUTs to any I/O port. These OUTs are logged in a .OUT file, in which is stored what was written to which port at what time. These log files are used for recording sounds the emulated Spectrum produces. The OUTs to port FE, which controls the internal beeper, and those to ports BFFD and FFFD, which control the soundchip of the Spectrum 128, are translated into a sample file by OUT2VOC. There are a number of command line switches. The sample frequency can be chosen by specifying "-f frequency" on the command line. By default a sampling frequency of 10 kHz is used. Ordinarily the OUT2VOC program filters out all frequencies above half the sampling frequency, so that no aliasing occurs when the signal is stored as a sequence of samples in a .VOC sample file. For sample files containing tape data, these aliasing effects are not important. For these sample files you can use -d to produce 'digital' sample files, containing only 'high' and 'low' sample values, and nothing in between. These sample files can also be compressed much better. By default, the OUT2VOC program listens to the EAR output only. Specify -m to have it listen to the MIC output (only), and -a to have it listen to the AY-3-8912 soundchip of the Spectrum 128. If you specify for example -e -a, the program will listen to both corresponding channels. Usually, not all registers of the AY soundchip are updated continually. Some registers are initialised and left at that. So usually it is necessary to supply the initial values of the soundchip registers. Do this by specifying '-i file', where 'file' is the snapshot taken just before the OUTs were recorded. Some Spectrum programs use extremely many OUTs to produce sounds. Fairlight for example OUTs about 70000 times a second, thereby indeed producing one of the finest music I've every heard coming out of an ordinary Spectrum. The OUT2VOC program takes quite some time to compute the .VOC file from the raw .OUT output. Use -q for a quick and little less precise conversion. The difference seems to be barely audible. This switch has no effect when converting '128 music. If you specify -s, silences of longer than 1 second will be truncated to 1 second. Finally, use -r to produce a raw sample file, without any header or length info. To record a sample, go to the Extra Functions menu (F10, X), and select O. Select the ports you want to log (by default only FE is logged) and enter a name for the log file. OUTs will be logged until you specify an illegal name, or press ENTER on an empty line here. To save a block of data to a .OUT file, simply type the right SAVE command or use any (turbo-save) program to save it to tape. Note that .OUT files tend to grow fast; one bit on the tape corresponds to two OUTs and therefore two 5-byte entries in the .OUT file; an 48K file will produce a .OUT file of at least 4 Megabytes. If you give a 16 bit address for an I/O port, only OUTs to this address will be logged. If you give an address smaller than 100 hex, all addresses whose low byte equal this number are logged. Note that it is not possible to log all OUTs to, say, an even port. Although the MIC and EAR ports respond to all even port addresses, virtually no program uses a port different from FE, so this will be no problem in practice. Note that whereas the 'official' addresses of the register and value-port of the AY soundchip are FFFD and BFFD respectively, some programs use other ports that work too. One particular program uses BEFD, heaven knows why. For these programs, specify FD (or 00FD) as OUT port to log; this will ensure that all OUTs to any address with low byte FD is logged (which, alas, includes the much-used port 7FFD). 2.19 Quick overview of command line switches, and features In this section I will briefly explain all command line switches. It is useful to at least once read this section carefully; there are a few small handy features that will otherwise be readily overlooked. Starred switches are by default put in the Z80.INI file. -h Hercules graphics -xh Extended Hercules graphics -p Plantronics graphics -q Plantronics, different palette -c CGA graphics -e EGA graphics -v VGA graphics Usually the emulator will by itself correctly determine which mode to use. VGA mode is by far the best: it is the only mode in which all colours are correct (including the bright hues), and it is also the fastest mode. On old computers with only an Hercules adapter, extended Hercules will usually give much better results. -xv 400-line VGA (for some Tridents) -xb Black-and-white VGA The black-and-white switch is useful on black-and-white monitors; sometimes those only display one component of the RGB signal instead of a weighted average, so that some colours become indistinguishable grey tones. Some Trident video adapters, as well as some others, have a bug in their video BIOS: they don't want to be put in 200-line mode. To get around this, when -xv is specified 400-line mode is used with a double amount of lines. -n Emulate Spectrum without Interface I -s Emulate Spectrum with SamRam -1[28] Emulate Spectrum 128 (can be used with -n) -xk Emulate Multiface 128 interface (can't be used with SamRam) -9 Default to M.G.T. interface instead of Interface I -0d M.G.T. = DISCiPLE ROM (default) -0p M.G.T. = Plus D These switches select the default start-up hardware configuration of the emulator. This can all be changed in the Change Hardware menu under function key F9. * -znnn.n Emulate the Spectrum at speed nnn.n% The most sensible setting for this is -z100. By default this is done in the Z80.INI file. -xx Hi-resolution colour emulation This selects hi-res colour emulation by default, so that border effects and hi-res colour effects are visible. This setting can be changed in the F4 menu. -r Emulate the R register This is usually necessary in turbo loaders and otherwise protected programs, since they almost invariably use the R register to decode things. The R register has to be updated every instruction, so that enabling the emulation of it reduces the emulation speed considerably, by some 30%. Don't do it unless it proves to be necessary. I don't know of any program that uses it on the run. If the R register is not emulated, the R register acts as a random generator. * -l Better (but slower) LDIR/LDDR emulation Normally a 8086 MOVSB is used to emulate an LDIR or LDDR. This is a fast instruction. Programs that use them a lot, most notably Jetset Willy and Manic Miner, run very fast. On slow computers these programs are the only ones that are really playable. On fast computers they run much too fast, so it is a wise thing to use -l on fast computers. Secondly, without -l the LDIR instruction is not emulated correctly when it overwrites itself; with -l it is. -yl, -yh Low, high video synchronization mode These switches control the phase between the 50 Hz interrupt and the screen refresh. Some programs need a different setting in order to remove flickering of moving characters. Enabling hi-resolution color emulation also eliminates these problems. -2 Emulate an Issue-2 Spectrum Make the EAR line 1 when there's no signal, instead of 0 as it is on Issue 3 Spectrum's. Some old programs need it (Spinads for example). -d Double interrupt frequency (100 Hz) On slow computers this may help to get the keyboard to respond better. -aN Redirect Spectrum RS232 output to LPTn -oN Redirect Spectrum RS232 output to COMn -uF Redirect file F to Spectrum RS232 input -iN Redirect COMn to Spectrum RS232 input -wF Redirect Spectrum RS232 output to file F All output to, and reading from, the Interface I's RS232 channel (channels "b" and "t"), the 128K printer channel (channel "p") will be sent to, respectively read from, the appropriate device. Furthermore, output to the ZX Printer will be converted in a format suited for Epson matrix printers or HP Laserjet printers and also be sent to the 'RS232 output' device or file. -g No sound -xa Do NOT use AdLib for 128 sound -xc Use SoundBlaster CMS chips for noise -xi Do NOT use internal PC speaker for '128 sound If no AdLib compatible card is detected, 128K sound output will be sent, as far as is possible, to the internal PC speaker. Use -xa to hear 128K sound through the PC speaker when there is an AdLib card present. Without CMS chips, the 128K soundchip's noise cannot be faithfully reproduced. If you have CMS chips installed, use -xc to use them. If the SoundBlaster is on a different base address than 0220, use -xq to select it. * -km Use MS Mouse to control Spectrum joystick -ka Emulate Spectrum AMS mouse interface controlled by MS Mouse -kz Use digital Zandbergen joystick -kk Do not look for analogue or Zandbergen joystick The emulated joystick (Cursor, Kempston, Sinclair 2 or user defined) is controlled by the arrow keys and TAB, 5, INS (0) on the PC keyboard, and optionally also by a digital joystick, and analogue IBM joystick or a mouse. Use -kk if the emulator erroneously detects either joystick. If -ka is specified, the PC mouse controls the emulated AMS mouse interface. Because of I/O address clashes, this only works with SamRam and the M.G.T. interfaces disabled. The AMS mouse is supported by e.g. Art Studio. -jc Emulate Cursor joystick (default) -jk Emulate Kempston joystick -j2 Emulate Sinclair joystick 2 (keys 6,7,8,9 and 0) -ju User defined joystick Also quite clear I think. For instance, -juipqzm makes the joystick control the i,p,q,z and m keys, for instance to play those lovely Horace games. Special characters are [ for shift, ] for symbol shift, / for enter and \ for space. * -xs Default to shifted cursor keys (NumLock) in '128 mode By default, the PC arrow keys control the cursor keys 5,6,7,8 and 0 of the Spectrum. The Spectrum 128 had its arrow keys press the cursor keys plus shift, and the menu bar of the reset screen of the '128 only responds to shift+cursor key. -bN Use LPTn for tape I/O -xo Use SoundBlaster's A/D Converter for tape input -xq adr Set base IO address for SoundBlaster (default 0220) Either the LPT tape interface of the SoundBlaster is used for tape input. Only the LPT tape interface can be used for tape (MIC) output. -tv F Play .VOC file F to 'ear' input -m N F Insert cartridge file F{.MDR} into microdrive N -xm D Select default directory D for .MDR files -td D Select directory D for Multiple .TAP File mode -ts D Specify default directory for Single .TAP File mode -ti F Use F{.TAP} as tape input -to F Use F{.TAP} as tape output (if exists, append) -tm Mirror tape input to disk (Do also specify output file!) -te Mirror tape input to disk in EXACT mode -tw Don't wrap load pointer of tapefile at end All quite clear I think. If -tv is used, the VOC file starts playing immediately, so be sure there's an appropriate snapshot running to do something with the signal. -tw makes the emulator load from physical tape when a .TAP file has been read to the end, instead of starting again from the beginning. -0e Epson printer (for ZX PRINTER & M.G.T.) -0h HP PCL printer (for ZX PRINTER & M.G.T.) Output to the ZX Printer will be converted into graphic data in Epson or HP PCL format and sent to the 'RS232 output'. Use one of these switches to select which format to use. Also, this selects the default DISCiPLE ROM to be used; the two ROMs have different screen dump routines pre-loaded. -0i Disable Disciple interrupt Normally the Disciple and Plus D have their own interrupt routine being executed 50 times a second. Because this involves many page swaps, this is quite slow on the emulator. Since the interrupt is not really necessary anyway, it is reduced to once every two seconds. On some computers this may still be too much, in which case -0i completely disables the Disciple and Plus D interrupts. Do not try this in Unidos! (which is not emulated [yet].) -xp D Select default directory D for .Z80 snapshot files Clear. -xz Assume AZERTY keyboard layout Assumes the Belgian and French AZERTY keyboard layout. -xr F Use file F as standard Spectrum rom The ROM will be used in 48K modes only, and must be exactly 16K long. -xt Use as little memory as possible with full functionality -xu Use as little memory as possible; disable HCR emulation With -xt, all unnecessary buffers used for efficiency purposes only are reduced to minimum size. Saves 47K, but can make all the difference sometimes. With -xu, 83K is saved, but Hi Color Resolution emulation won't work anymore. -tx Do not display tape info window when loading or saving Some people really seem to hate it. Don't know why. -xe Do not use expanded memory Specifying this switch will result in the emulator using 240K more base memory (making a grand total of 571K). Furthermore, all page swapping will be much slower, so especially the 128K emulation gets verrry slow. -xg Log all outs to FE in OUT log file -xy Dump trace of program in .OUT file By default, OUTs to port #FE that do not change the state of either MIC or EAR are not saved to the log file, to save disk space. If, for some reason, you want all OUTs to be logged, -xg will do the trick. The -xy option can be used for producing a somewhat crude trace; see section 5.5 on the .OUT format for more details. -xw Run in Windows compatibility mode In this mode, neither the timer interrupt nor the keyboard interrupt are re-routed. The emulator counts T states to see when an interrupt has to be generated (so emulation will be slower), and uses the BIOS keyboard routines to read the keyboard. Since the BIOS doesn't tell when a key is released, and since not all key combinations are mapped to an (extended) ASCII value, keyboard emulation is inferior to the emulation in normal mode. This mode is selected automatically when the emulator is run under Windows; use this mode only when there's a conflict with some other program, or operating system. -xf Switch full 16K of Interface I ROM Useless. 2.20 Miscellaneous remarks 1. Problems at the Rom/Ram boundary There are a few Spectrum programs that have an odd stack pointer, and run over the ram/rom boundary, for instance Deep Strike, and Elite. This crashed version 1.45 of the emulator; the problem was circumvented somewhat in version 2.01, and has been removed in version 3: in most cases, a word read from or written to FFFF will be read or written as two bytes. You can check this by typing CLEAR 65535: POKE 65535,0: RETURN in BASIC; this will lock up version 1.45 of the emulator, it will lock up version 2.01 if the 80386 is in virtual mode, and it will only crash the emulated Spectrum (as it should) on version 3. The check on FFFF is not done at every potentially problematic op-code, because this would make the emulator noticeably slower. It is therefore still possible to 'hang' the emulator. Not going to tell you how, though. All existing programs seem to work okay now. 2. Critical timings A few programs (the only examples known to me are Fireman and Thing, but there are more) are quite sensitive to the relative actual execution speed of emulated Z80 instructions, and crash if it isn't right. They rely on this-or-that amount of instruction to be executed between interrupts. If you slow down the emulator, these program will run fine, because then individual instructions are more carefully timed. When running in Windows compatibility mode, loading .VOC files or when the Hi-Res Color emulation is switched on, these problems disappear completely as the emulator is then counting off the exact number of T states to elapse between interrupts. 3. Shifted cursor keys It may be annoying to have to press Num-Lock every time you use the Spectrum 128 (because otherwise you'll have to use Shift with the cursor keys to move the menu bar). To make the emulator press shift by default every time you use the PC cursor keys in '128 mode, use the switch -xs. If you press Num-Lock now (in '128 mode), the shift-key won't be pressed. The 48K modes are not affected by this switch. 4. Running non-standard ROMs To run the emulator with a different rom than the standard one, you can specify a rom image file on the command line. Use the switch -xr file, where 'file' is the name of the image file. This file should be exactly 16384 bytes long. It will of course not be used in Spectrum 128 or SamRam mode. The emulator 'ZX' by Rindt and Bruckner comes with several roms, stored in their tape format. You can convert these files to .TAP files, and then load them in the normal way (in RAM), and then save the 16K image from RAM directly. You can also extract it from the files directly by using the DOS debug utility: C:\>debug rom.000 (or other rom file (of 16406 bytes)) -m 115 L 4000,100 (move the rom down, overwrite header) -rcx (new length of exactly 16K bytes) CX 4016 4000 -n rom000.bin (or some other name) -w (write it) Writing 04000 bytes -q (and quit) 5. Printing with DISCiPLE and Plus D If, emulating a DISCiPLE/+D and by entering POKE @11,0 the parallel printer output has been selected, going back to a hardware mode without M.G.T. interface causes problems with printing to the ZX Printer, since the output addresses of the "p" channel have been changed by the M.G.T. ROM. Use the "b" channel of the Interface I instead. You can reset the channel to the ZX Printer by entering POKE @11,1 while still emulating the M.G.T. interface. Although by default channel #3 prints to the ZX Printer, in all hardware modes, if a DISCiPLE/+D is emulated output to the ZX Printer is ignored, as these interfaces use the ZX Printer I/O ports for their own purposes. 6. ZX Printing When converting ZX Printer output for either Epson or HP-PCL printers, the emulator does not check whether the printer is on-line or not; this is left to the BIOS. The result is that, when it is off-line (or when there is no printer connected at all to the specified port) the emulator may seem to hang. Make sure to have specified the right output port with -xl N, and the right output format with either -0h or -0e. See the default Z80.INI file. 3. THE SAMRAM 3.1 Basic extensions The SamRam is a hardware device Johan and I built for our Spectrums. It consists of a 32K static RAM chip which contains a modified copy of the normal Basic ROM and a number of other useful routines, like a monitor and snapshot software. You can compare it to a Multiface I interface, but it's more versatile. Another useful feature was a simple hardware switch which allowed use of the shadow 32K Ram, present at 8000-FFFF in most Spectrums, but hardly ever actually used. For more details on the low-level hardware features of the SamRam read chapter 5. In this chapter I'll explain the software features of the SamRam software, somewhat bombastically called the 'SamRam 32 Software System' or the 'Sam Operating System'. By the way, all similarity between existing computers is in fact purely coincidental and has in no way been intended. Really! The SamRam offers a few new Basic commands, and a lot of useful routines that are activated by an NMI, i.e. by pressing F5. First I'll discuss the Basic extension. Select the SamRam by starting the emulator with the -s switch, or by selecting it from the F9 menu. Normal Basic functions as usual; the character set is different from the original one. There are four new commands: *RS, *MOVE, *SAVE and *SPECTRUM, and two new functions, DEC and HEX, which have replaced ASN and ACS. DEC takes a string argument containing a hexadecimal number, and returns the decimal value of it. HEX is the inverse of the DEC function, and yields a four-character string. *RS sends its arguments directly to the RS232 channel. You don't have to open a "b" or "t" channel first. You're right, it's of limited use. Example: *RS 13,10 *MOVE is useful: it moves a block of memory to another place. Example: *MOVE 50000,16384,6912 moves a screen-sized block from 50000 to the start of the screen memory. *SAVE works like *MOVE, except that it activates the shadow SamRam ROM before moving. I used this command to update the shadow ROM, but on the emulator you can use it to move the shadow ROM to a convenient place in Ram where you can take a look at it, for instance by executing *SAVE 0,32768,16384. *SPECTRUM resets the SamRam Spectrum to a normal one. You lose all data in memory. By resetting the emulator by pressing ALT-F5, the SamRam is activated again. Not very useful either. Then there's the Ramdisk, which is, like the Spectrum 128 ramdisk, accessed via the SAVE!, LOAD!, CAT!, ERASE! and FORMAT!. The syntax is straightforward. FORMAT! and CAT! need no parameters; ERASE! only needs a name. If a file is not found, the SamRam will respond with a 5-End of File error. The Ramdisk has a capacity of 25K. 3.2 The NMI software Select the SamRam (F9-3), and press F5. A menu with eight icons pops up. You can select each icon by moving the arrow to it (using the cursor keys or the Kempston joystick), and pressing '0' or fire. The icons can also be selected by pressing the appropriate letter key. The eight icons are two arrows with N and E within them, a magnifying glass with the letters 'mc' in it (activated by pressing D), two screens (identified by 1 and 2), a printer (P), a cassette (S) and a box saying 'overig'. The 'D' activates the monitor or disassembler; read section 3.3 for information on this program. Pressing N or E returns you to the Spectrum. If you pressed N, the normal Spectrum rom will be selected when the NMI software returns; if you press E, the Rom with the Basic extensions will be selected. Some games may crash if they see a different rom than the standard Spectrum one. Pressing 1 selects the tiny screen editor. You can move a '+' shaped cursor about the screen using the cursor keys. The following commands are available: H: Get the current ATTR color from the screen at the cursor's current position, and store it in memory. This color will be used by the next command: Z: Put the color on the screen G: Get a character from the screen P: Put the character on the screen R: Remove all screen data that is invisible by the ATTR color L: Take a look at the bitmap below the ATTR color codes T: Return to the main menu. You can also return by pressing EDIT, or ESC in the emulator. B: Change border color V: Clear the whole screen If you press 0, you can edit the current 8x8 character block at pixel level. Again you control the cursor with the cursor keys. Now 0 toggles a pixel. In this mode there are two commands: C clears the whole block, and I inverts it. Pressing EDIT (ESC) returns you to the big screen again. The SamRam has two screen buffers. Buffer 1 is used to hold the screen which was visible when you pressed NMI, to be able to restore it when returning. This is the screen you edit with '1'. The second screen buffer can be used to hold a screen for some time; it is not touched by the NMI software directly, and will not even be destroyed by a Reset. If you press '2', a menu appears with four Dutch entries: 1: Scherm 1 opslaan (Store screen 1 into buffer 2) 2: Scherm 2 veranderen (Edit screen 2) 3: Schermen verwisselen (Swap screens) 4: Scherm 2 weghalen (Remove screen 2) These four functions are rather obvious, I believe. Pressing 'P' pops up the printer menu. The screendump program is written specifically for my printer, a Star SG-10. It will probably work on some other printers, but not on most. The output is sent to the RS232 channel, so you have to redirect it to an LPT output. Skipping the most interesting, 'S', for a moment, let's first discuss the final menu, 'O' for 'Overig', Dutch for miscellaneous. There are five menu options, of which three are not useful. The first gives a directory of the cartridge currently in Microdrive 1. The last, 'E', returns you to Basic if this is anywhere possible: it resets some crucial system variables and generates a Break into Program. You can use this for instance to break in a BEEP, or crack a not-so-very-well- protected program. The three other options select normal or speed- save, and store the current setting in CMOS Ram. Speed-save won't work properly on the emulator, because the speed-save routine toggles the upper 32K ram bank regularly, and this takes too much time on the emulator. The setting is not important if you use the internal save routine (which will be used by default, unless you select Real Mode). Finally, the 'S' option. This option allows you to save a snapshot to tape or microdrive. I used it a lot on my real Spectrum, and it works just as well on the emulator. It is very useful is you want to load a .Z80 program back into a real Spectrum again. There are three 'switches' you can toggle. The active choice is indicated by a bright green box, inactive boxes are non-bright. You have to use EGA or VGA to be able to see it... The first switch lets you select whether the SamRam rom should be active if the program loads or not. This is only meaningful is you load it back in a SamRam again. Usually I want the SamRam rom to be active because I like the character set better. The second switch indicates whether the SamRam should save a 'loading screen', which it takes from screen buffer 2. If screen buffer 2 contains a screen, this switch will by default be on. Finally, the last switch lets you select the output media, tape or cartridge. If the program is loaded back into the SamRam, the only bytes that have been corrupted are four bytes down on the stack; this will virtually never be any problem. If the program is loaded back to a normal Spectrum, these four bytes will also be corrupted, and the bottom two pixel lines of the screen will be filled with data. (This is considerably less than any other snapshotter I've seen: for instance the Multiface I uses more than 35% of the screen!) The Microdrive BASIC loader needs code in the SamRam rom to start the program (the RANDOMIZE USR 43 calls it). It won't be very difficult to write a standard BASIC loader that doesn't need this code, but I don't think many people desperately need it... Anyway, using the Multiface 128 you can write a compressed snapshot to cartridge which doesn't need the Multiface. 3.3 The built-in monitor This is a really very convenient part of the emulator, and I use it a lot. It is very MONS-like in its commands and visual appearance. It cannot single-step however, but on the positive side it has some features MONS hasn't. It is a part of the SamRam, and cannot therefore be used with Spectrum 128 programs. If you want to take a look at a Spectrum 128 program, press F10, then change the hardware to SamRam without resetting, and finally generate an NMI in the Extra Functions menu. You won't probably be able to continue to run the program, but at least you're able to see what it was doing. Press F5 for NMI, and D to enter the monitor/disassembler. The first eight lines are the first eight instructions, starting at the Memory Pointer, from here on abbreviated by MP. At first, MP is zero. The disassembler knows all official instructions, and the SLL instruction. If another inofficial instruction (i.e. starting with DD, FD or ED) is encountered, the first byte is displayed on a blank line. The four lines below these display the value of PC and SP, the first nine words on the stack (including AF and the program counter, which have been pushed during NMI), and three MP-memories. These can be used for temporary storage of the MP, for instance when you take a look at the body of a CALL, and want to return to the main procedure later. The bottom part of the screen displays 24 bytes around the memory pointer. Commands are one letter long; no ENTER needs to be given. If one or more operands are needed, a colon will appear. By default the monitor accepts hexadecimal input. A leading $ denotes that the number is to be regarded as decimal. If you give the # command, the default will toggle to decimal, and you need to explicitly put a # in front of a number which is to be interpreted as a hex number. Also, after the # command all addresses on screen will be decimal. A single character preceded by the " symbol evaluates to its ASCII code, and the single character M will evaluate to the current value of the memory pointer. The monitor commands: Q: Decrease the memory pointer by one. You effectively shift one byte up. A: Increase the memory pointer, shifting one byte down. ENTER: Shift one instruction down: the memory pointer is increased by the length of first instruction displayed on screen. M: Change the value of the memory pointer. For instance, M:M won't change it. P: Put. The word operand supplied will be stored in the first MP memory, and the others will shift on place to the right. Usually, you'll want to store the memory pointer by P:M G: Get. Typing G:1, G:2 or G:3 moves the value of one of the MP memories to the MP. B: Byte. This command needs a byte operand; it will be poked into memory, and the memory pointer will move one up. I: Insert. The same as B, except that you can poke more than one byte. It continues to ask for bytes to poke until you type Enter on a blank line. #: Toggles the default number base between hexadecimal and decimal. F: Find. You can enter up to ten bytes, which will be searched through memory. Searching will stop at address 0, because since the search string is stored in shadow Ram, searching would otherwise not always terminate. Typing Enter on a blank line starts the search. Byte operands are entered as usual, but: - If a number bigger than 256 decimal is entered, it is treated as a word in the standard LSB/MSB format. So, 1234 will search for 34,12 hex in that order. Note that 0012 will search for 12, not 12,00. - A line starting with " decodes into the string of characters (up to ten) behind it. Normally this would only be the first character. So instead of typing "M "Y "N "A "M "E (space=enter here) you type "MYNAME. Note that any terminating " will also be searched for! - An x is treated as a wildcard. So if you search for CD x 80 any call to a subroutine in the block 8000-80FF is a hit. If you search for x 8000, you'll see every one-byte instruction that has the address 8000 as operand. N: Continues the search started by F from the current MP. $: Displays one page of disassembly on screen. In this mode, the following commands are possible: $: Back to the main screen 7: [Shift 7 also works, cursor up]: Go to the previous page. The monitor stores the addresses of the previous eight pages only. Q: Go back one byte (decrease MP by one) A: Go one byte forward (increase MP by one) Z: Dump this screen to the printer, in ASCII format. Redirect the RS232 output to a file, and run CONVERT on it to convert the CR's into CR/LF's before printing (or tell your printer to do the conversion). Every other key displays the next page of disassembly. K: List. The same mode as with $ is entered, but instead of a disassembly the bytes with their ASCII characters are displayed. Useful to look for text. C: Clear. Fills blocks of memory with a specified value. The monitor prompts with 'First', 'Last' and 'With'. The 'Last' address is inclusive! D: Dump. Prompts with 'First' and 'Last', and dumps a disassembly of the block between these addresses to the printer. See remark at $-Z. The 'Last' address is again inclusive. R: Registers. If you press Enter after R, an overview of the registers contents is displayed. If you type one of A,B,C,D, E,H,L,A',B',C',D',E',H',L',I,R,AF,BC,DE,HL,AF',BC',DE',HL', IX,IY,SP or PC, you can change the value of it. Changing the value of SP also changes the PC and AF values by the way. You cannot change the Interrupt mode or IFF. V: Verplaats. (Move). Prompts with 'From', 'To' and 'Length'. Obvious. S: Save. Enter the start of the block you wish to save first. The monitor then prompts with 'Length'. The block is saved without a header, as a normal data block (A, the flagbyte, is 0FF) L: Load. Loads a block of data from tape, at the specified address. Normal data blocks, headers and blocks with non- standard flag bytes can be loaded. The first byte in memory will contain the flag byte. If the checksum isn't 0 after loading, indicating a tape error, you'll hear a beep. H: Header read. Loads headers and displays the contents on screen. As you're reading this part, I assume you know something of machine code. Probably you would be interested in peeking into the software of the SamRam, the Interface I, the Spectrum 128, the Disciple or the Multiface 128. You'll first have to move these roms in ram to be able to look at them with the monitor. The Interface I rom can be moved into ram by saving it to microdrive or to the "b" channel, with SAVE *"m";1;"rom" CODE 0,8192 or SAVE *"b" CODE 0,8192, and loading it back again at 32768 for instance. You can also put this small machine code routine at 23296 and run it: F3 21 0C 5B E5 21 00 00 E5 C3 08 00 21 00 00 11 00 80 01 00 20 ED B0 FB C3 00 07. The two SamRam roms are easy. The first you don't need to transfer; the monitor looks at the extended basic rom by default. The second rom can be moved to 32768 by typing *SAVE 0,32768,16384. (The SAVE is not the keyword SAVE!) The first '128 rom, the one which is active at reset and contains most of the new code, is moved up by typing SAVE!"rom"CODE 0,16384, then LOAD!"rom"CODE 32768. The other rom is most conveniently moved by saving it to a .TAP file and loading it back again in ram. To select the SamRam type SPECTRUM first, and then switch the hardware without resetting. The Disciple and Plus D roms can be transferred to RAM by simply saving them to disk and loading them back at say 32768. The Multiface ROM is paged by an IN from 191, and paged out again by INning from address 63. Don't forget to disable interrupts in between, I'm not sure whether the M128 has a well-behaved interrupt routine. ROM is from 0-8191, RAM on top of that. 4. THE SPECTRUM 4.1 The Spectrum This emulator supports the Interface I, the Multiface 128, the DISCiPLE and Plus D interfaces, and the Spectrum 128. Many Spectrum users will have no experience with them, so some comments may be useful. On the other hand, I don't think this is the right place to describe the Spectrum Basic in full detail. If you want to know it all, read the official manuals! Information on the Multiface 128 can be found in section 2.12. If you want to use Spectrum Basic, you will need the keywords. You could by the way now also use the Spectrum 128 Basic where you can type the keywords in by full. If you press ALT-F1 in the emulator, the Spectrum keyboard layout will appear. For completeness I include an alphabetical list of all keywords and their key-combination. In the list below, K stands for Keyword mode, E for E-mode (type Shift-Alt of Shift-Ctrl to select E-mode), S for Symbol Shift, and SE for Symbol Shifted (Alt/Ctrl) E-mode: select E mode and type the letter while depressing Symbol Shift. Keyw. Code | Keyw. Code | Keyw. Code | Keyw. Code ABS E g DRAW K w MERGE SE t SAVE K s ACS SE w ERASE SE 7 MOVE SE 6 SCREEN$ SE k AND S y EXP E x NEW K a SGN E f ASN SE q FLASH SE v NEXT K n SIN E q AT S i FN SE 2 NOT S s SQR E h ATN SE e FOR K f OPEN # SE 4 STEP S d ATTR SE l FORMAT SE 0 OR S u STOP S a BEEP SE z GO SUB K h OUT SE o STR$ E y BIN E b GO TO K g OVER SE n TAB E p BORDER K b IF K u PAPER SE c TAN E e BRIGHT SE b IN SE i PAUSE K m THEN S g CAT SE 9 INK SE x PEEK E o TO S f CHR$ E u INKEY$ E n PI E m USR E l CIRCLE SE h INPUT K i PLOT K q VAL E j CLEAR K x INT E r POINT SE 8 VAL$ SE j CLOSE # SE 5 INVERSE SE m POKE K o VERIFY SE r CLS K v LEN E k PRINT K p <= S q CODE E i LET K l RANDOMIZE K t >= S e CONTINUE K c LIST K k READ E a <> S w COPY K z LINE SE 3 REM K e COS E w LLIST E v RESTORE E s DEC SE q DATA E d LN E z RETURN K y HEX SE w DEF FN SE 1 LOAD K j RND E t DIM K d LPRINT E c RUN K r Character Spectrum kbrd On PC keyboard & S 6 ALT (or CTRL) 6 ' S 7 ALT 7 or '/" ( S 8 ALT 8 ) S 9 ALT 9 _ S 0 ALT 0 or SHFT _/- < S r ALT r or SHFT S t ALT t or SHFT >/, ; S o ALT o or :/; " S p ALT p or SHFT "/' ^ S h ALT h - S j ALT j or _/- + S k ALT k or SHFT +/= or GREY + = S l ALT l or +/= : S z ALT z or SFHT :/; ? S c ALT c or SHFT ?// / S v ALT v or ?// * S b ALT b or GREY PRTSC/* , S n ALT n or /. 4.2 The Interface I If you want to use the microdrive, you'll need cartridge files. The emulator can create an empty cartridge file for you. You have to format it before you can use it. Type FORMAT "m";1;"name" to format the cartridge currently in Microdrive 1 giving it the name 'name'. Next, type CAT 1 to get a catalogue of the files on it (none of course) and the number of kilobytes free. You can save a file by typing for instance SAVE *"m";1;"screen"SCREEN$ Instead of SCREEN$ you can use all other expressions that are permitted also when saving to tape, like LINE nnnn or CODE x,y etcetera. To load a file back from cartridge, you type (you guessed it) LOAD *"m";1;"screen"SCREEN$ If the file doesn't exist or is of the wrong type you'll get the appropriate error message. To erase a file, type for instance ERASE "m";1;"screen" Note that no * is needed (or even permitted), and that only the name should be given. There's another way to create a file on a cartridge, and that is by using a command like OPEN #3;"m";1;"name", and printing to that stream. You can use MOVE to move data from stream to stream, but I'll not go into that --- it's not very much used anyway. Instead of to the microdrive, you can also 'save to the RS232 link'. For instance, type SAVE *"b"SCREEN$ (note: there's no name!) to save a screen. On the emulator you can send the output to the RS232 channel to a printer (then SAVE *"b" is useless), to a file (can be useful) or to the COM port (very useful if you connect a real Spectrum to the PC's COM port!). You can load the data back by typing LOAD *"b"SCREEN$ and making sure the RS232 channel is fed with the right input (from a COM port or a file). See also section 2.13. If you want to use the RS232 channel for printing, open stream 3 for output to that channel by typing OPEN #3,"b" or OPEN #3,"t" The first will simply copy everything you send to stream 3 (using for instance LPRINT or LLIST) to the RS232 channel; the second converts CR's into CR/LF's, breaks off lines at 80 characters and translates keywords into character sequences. "t" is useful for LLISTings, but not for anything else. Useful extra commands: CLS #, to clear the screen and reset the attributes to their reset defaults, and CLEAR # to do a CLS # and close all currently open streams (discarding all data that may still be buffered!) The Interface I uses its own system variables. At the first error message you make (or RASP, or flashing question mark) and at the first Interface I statement you execute, it inserts them automatically. Some programs will not run when the Interface I has inserted its system variables. So if you load a game from tape, reset the Spectrum first and don't make an error typing LOAD "". With a bit of exercise you should be able to do this. 4.3 The DISCiPLE and Plus D Interfaces - Introduction The DISCiPLE and Plus D were two disk interfaces for the spectrum designed by M.G.T. (Miles Gordon Technology). The first of these interfaces was the DISCiPLE, this interface consisted of a disk interface, microdrive network compatible interface, parallel printer interface, 2 joystick ports (emulating kempston, cursor, and Sinclair 1 and 2). The unit also had an inhibit button which disabled the interface hardware (except the joystick ports), and finally a snapshot button which when pressed stopped the computer to allow the program to be saved to disk or the screen to be printed. This was made by Rockfort. The Plus D was the second of the interfaces, this was a cut-down version of the DISCiPLE, this interface only had a disk interface, parallel printer interface and a snapshot button. Both interfaces had a D.O.S. (Disk Operating System) which was partly ROM (8K) and partly RAM (8K). When the spectrum was turned on, the ROM part of the D.O.S. was in control and whenever the command RUN was issued the ROM tries to load up the RAM part of the D.O.S. from floppy disk. The advantage of this is that the D.O.S. can be upgraded without having to change chips over (unless of course it was a major upgrade!). Another advantage was that D.O.S. extensions could be incorporated or replace other systems (see later). With both interfaces, they extended the BASIC commands, but unlike the microdrives and several other types of drives available, the DISCiPLE and Plus D took up none of the spectrum's RAM, therefore it was the most invisible of the disk systems available, not only that, but the DISCiPLE and Plus D used the same type of disk drives as the BBC micro, therefore disk drives were both cheap and widely available, also the disks themselves were also standard, ie 5.25" (800K DS/DD), then later 3.5" (800K DS/DD). The ROM of the DISCiPLE is supplied with the emulator, together with two version of the D.O.S. pre-loaded in RAM. The ROM of the Plus D interface is not supplied, for copyright reasons. The emulator will only emulate a Plus D interface if it can find a file PLUSDROM.BIN in the emulator's own directory. If you have a Plus D yourself, you can transfer the ROM in the following way. Load the operating system from a Plus D system diskette, and save the entire ROM, together with the operating system, to disk by entering SAVE d1"rom" CODE 0,16384. Then, start the emulator and choose hardware mode Spectrum 48K + Disciple (not Plus D of course), then type LOAD d1"rom" CODE 32768. Finally, press F10, X, S for Save Data block, set start address and length to 8000 and 4000 (hexadecimal) respectively, and save the ROM under the name PLUSDROM.BIN. If you re-start the emulator now, it will emulate the Plus D too. 4.4 The DISCiPLE and Plus D Interfaces - The basic commands There are several levels of commands that can be used, these range from the most straightforward everyday use, to the more advanced, programmer type commands. I will first explain the most common commands, so that you can quickly and easily access DISCiPLE and Plus D disks. Where a 1 is used in the following commands 2 could be used instead. These commands are:- RUN - when no D.O.S. (system file) is loaded it will cause this to be loaded. Otherwise it will just run the BASIC PROGRAM. Please note that with the emulator the system file is already loaded, therefore this command is not required, although I have explained it for completeness. CAT 1 - will display a longhand catalogue of the disk drive selected. The form of this catalogue is as follows:- program no., program name, sectors used, file type, file size CAT * - will display a longhand catalogue of the currently selected disk drive in the same form as described above. CAT 1! - displays a shorthand catalogue of the disk drive selected. This catalogue consists of a 3 column list of the filename of the programs. CAT *! - displays a shorthand catalogue of the current disk drive. LOAD pn - p - letter p, n - number between 1 & 80. This is the program number of the file on the disk, the program number is the number printed before the name in the longhand catalogue. LOAD d1"name" - load from drive 1 the program called name LOAD d*"name" - load from the current drive the program called name LOAD d1"name" S - load an 48K snapshot from drive 1 called name LOAD d1"name" K - load an 128K snapshot from drive 1 called name LOAD d1;a$ - load from drive 1 the program whose name is held in the string a$ LOAD d*;a$ - load from the current drive the program whose name is held in the string a$ FORMAT d1 - format the disk in drive 1 4.5 The DISCiPLE and Plus D Interfaces - More advanced commands In the previous section I explained enough of the commands so that you could get to use the floppy disks with DISCiPLE/Plus D software on. Now I am going to explain the commands that the more experienced user and those who want to do just a little bit more than just load the programs. First of all comes the simple commands of SAVE, MERGE, VERIFY and LOAD. All of these commands are the same as rge tape versions except that you have d1, d2 or d* after the LOAD, SAVE etc. There are only two exceptions to this rule, the first is when you have a string for the filename, in this case the command becomes:- LOAD d1;n$ ....... etc LOAD d*;n$ ....... etc The second exception is actually an extension. When you save a code block, you can actually get it to autorun when it is loaded by adding a third parameter to the SAVE command, e.g. if you had a code block from 40000 to 45000 and the run address was 41023 and you wanted it to be called testcode to drive 1, you would save it as:- SAVE d1"testcode"CODE 40000,5001,41023 Now for the extensions. Any sector on the disk may be loaded to any area of RAM from 16384 to 65535-512. The sector may also be loaded into the RAM of the interface, however caution should be used at all times when doing this, as you may destroy the operating system or cause it to behave irrationally. The syntax of the command is:- LOAD @n,tr,sec,add Where:- n = drive number, ie 1 or 2, note * may not be used! tr = track number => 0->79=side 0, 128->207=side 1 sec = sector number => 1->10 normally, may not be 0! If you try and load a sector that is sector 0, then the operating system will crash! You may also save to disk in the same way, so if you wanted to write to Track 5, Side 0, Sector 3 with code from 32768 to 33279 to drive 1 you would type:- SAVE @1,5,3,32768 To format a disk all you need to type is:- FORMAT d1 or FORMAT d2 This is not however as simple as it seems! Although a disk formatted on the DISCiPLE/Plus D will work with the PC it does not work the other way round, i.e. a disk formatted on the PC with this emulator will not necessarily work on the DISCiPLE/Plus D. This is because of differences of the floppy disk controller chips. With the PC, it puts a special byte at the beginning of each track to tell the controller whether the disk is Double Density or High Density, and the spectrum floppy disk controller does not understand this byte and therefore will not read the track! If you find this otherwise, then please write and let us know about it. You can set some of the D.O.S. system variables using an extended POKE command. The syntax is:- POKE @address,value The address is the BASE address of the system variables of the interface concerned, the BASE address for each of the interfaces is different, but the address you use in the POKE command is the same. 4.6 The DISCiPLE and Plus D Interfaces - The snapshot button The snapshot button is a button which is used to stop the processor from executing instructions and making it do something else. In the case of the DISCiPLE/PLUS D the button can do 5 different tasks initially. Later on I'll discuss how the fuctions can be altered so that it can do other tasks. Once these tasks are carried out, the processor is returned to it's original state and the program continues from where it left off from. There are 5 functions that can be carried out with the initial system file. To use the button, first you must get to a point in the program that you want to use the button at, then press the button on the emulator the snapshot button is F5 (NMI). Once you do this the program will stop and the border of the computer will flash, this may also be accompanied with a buzzing noise on the speaker. This is to tell you that the snapshot button has been activated. The following functions can then be carried out:- 1 - Print screen to printer in black/white screen size 2 - Print screen to printer in grey scale A4 size 3 - Snapshot screen to disk in SCREEN$ format 4 - Snapshot program to disk in 48K SNAP format 5 - Snapshot program to disk in 128K SNAP format SPACE - go back to program (ie if F5 was pressed by mistake) The printer options will print out to EPSON compatible printers, however the DISCiPLE code has been changed and it is now possible to print to HPGL printers (e.g. Deskjet and Laserjet printers). The Snapshot screen and snapshot 48K are very self explanatory and easy to use. The Snapshot 128K is slightly more complicated. Once you select this option the disk drive will start up then after a slight pause the screen display may/may not change. The border flashes again and you have to press y or n depending on whether the screen display changed or not. If the screen stayed the same then press n, but if the screen changed type y. This is because the 128K spectrum has 2 screens, and there is no way for the computer to determine which is being used by itself, therefore it needs the user's help. After you press y or n the program will be saved onto disk. Seeing it is possible for you to load programs into the DISCiPLE/PLUS D RAM area it is possible to have these interfaces carry out other tasks. The snapshot button code is located in RAM, so you can therefore load a program into this part of the RAM and as soon as you press the snapshot button it will execute the new program. There is one problem however, which is that the program must be written in assembly language and must also be compiled for running in that part of RAM, also it must take care of what it does because the SPECTRUM ROM is not paged in, therefore ROM calls are not easily carried out. There are several different commercial programs which use the snapshot button to carry out different tasks, some of these are:- Snapshot compressing programs Debugging tools Cheat finders for games Programs to allow snapshots back onto tape The list is endless, and if you are capable of writing a machine-code program and have the relevant information, then you too could write your own programs. 4.7 The Spectrum 128 The main new features of the Spectrum 128 are its larger memory, that can be used as a Ram drive in Basic, and music capabilities. The Ram drive is accessed via the LOAD!, SAVE!, ERASE! and CAT! commands. They work as you would expect. Examples: SAVE !"name"SCREEN$ CAT! LOAD !"name"SCREEN$ ERASE !"name" The 3 channel sound chip of the Spectrum 128 can be used in Basic with the PLAY command. Example: PLAY "cde","efg","gAB" plays three chords. You can program complex effects, melodies and rhythms with the play command; they require many commands in the three voice strings which I won't explain... They are explained in the Spectrum 128's user guide. 5. TECHNICAL INFORMATION 5.1 The Spectrum In this section, the hardware of the 48K Spectrum is discussed. At the end, a discussion on the video timings of the 128K Spectrum is also included. In this section, 'Spectrum' by itself refers to the 48K machine. The Spectrum is at the hardware level a very simple machine. There's the 16K ROM which occupies the lowest part of the address space, and 48K of RAM which fills up the rest. An ULA which reads the lowest 6912 bytes of RAM to display the screen, and contains the logic for just one I/O port completes the machine, from a software point of view at least. Every even I/O address will address the ULA, but to avoid problems with other I/O devices only port FE should be used. If this port is written to, bits have the following meaning: Bit 7 6 5 4 3 2 1 0 ÚÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄ¿ ³ ³ ³ ³ E ³ M ³ Border ³ ÀÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÙ The lowest three bits specify the border colour; a zero in bit 3 activates the MIC output, and a one in bit 4 activates the EAR output (which sounds the internal speaker). The real Spectrum also activates the MIC when the ear is written to; the emulator doesn't. This is no problem; MIC is only used for saving, and when saving the Spectrum never sounds the internal speaker. The upper three bits are unused. If port FE is read from, the highest eight address lines are important too. A zero on one of these lines selects a particular half-row of five keys: IN: Reads keys (bit 0 to bit 4 inclusive, in that order) #FEFE SHIFT, Z, X, C, V #EFFE 0, 9, 8, 7, 6 #FDFE A, S, D, F, G #DFFE P, O, I, U, Y #FBFE Q, W, E, R, T #BFFE ENTER, L, K, J, H #F7FE 1, 2, 3, 4, 5 #7FFE SPACE, SYM SHFT, M, N, A zero in one of the five lowest bits means that the corresponding key is being pressed. If more than one address line is made low, the result is the logical AND of all single inputs, so a zero in a bit means that at least one of the corresponding keys are pressed. For example, only if each of the five lowest bits of the result from reading from port 00FE (for instance by XOR A/IN A,(FE)) is one, no key is pressed. A final remark about the keyboard. It is connected in a matrix-like fashion, with 8 rows of 5 columns, as is obvious from the above remarks. Any two keys pressed simultaneously can be uniquely decoded by reading from the IN ports; however, if more than two keys are pressed decoding may not be uniquely possible. For instance, if you press Caps shift, B and V, the Spectrum will think also the Space key is pressed, and react by giving the 'Break into Program' report. This matrix behaviour is also emulated - without it, Zynaps for instance won't pause when you press 5,6,7,8 and 0 simultaneously. Bit 5 (value 64) of IN-port FE is the ear input bit. When the line is silent, its value is zero, except in the early Model 2 of the Spectrum, where it was one. When there is a signal, this bit toggles. The Spectrum loading software is not sensitive to the polarity of this bit (which it definitely should not be, not only because of this model difference, but also because you cannot be sure the tape recorder doesn't change the polarity of the signal recorded!) Some old programs rely on the fact that bit 5 is always one (for instance Spinads); for these programs the emulator can mimic a Model 2 Spectrum. Bits 6 and 7 are always one. The ULA with the lower 16K of RAM, and the processor with the upper 32K RAM and 16K ROM are working independently of each other. The data and address buses of the Z80 and the ULA are connected by small resistors; normally, these do effectively decouple the buses. However, if the Z80 wants to read of write the lower 16K, the ULA halts the processor if it is busy reading, and after it's finished it lets the processor access lower memory through the resistors. A very fast, cheap and neat design indeed! If you run a program in the lower 16K of RAM, or read or write in that memory, the processor is halted sometimes. This part of memory is therefore somewhat slower than the upper 32K block. This is also the reason that you cannot write a sound- or save-routine in lower memory; the timing won't be exact, and the music will sound harsh. Also, INning from port FE will halt the processor, because the ULA has to supply the result. Therefore, INning from port FE is a tiny bit slower on average than INning from other ports; whilst normally an IN A,(nn) instruction would take 11 T states, it takes 12.15 T states on average if nn=FE. See below for more exact information. If the processor reads from a non-existing IN port, for instance FF, the ULA won't stop, but nothing will put anything on the data bus. Therefore, you'll read a mixture of FF's (idle bus), and screen and ATTR data bytes (the latter being very scarce, by the way). This will only happen when the ULA is reading the screen memory, 61.5% (192/312) of the 1/50th second time slice in which a frame is generated. The other 38.5% of the time the ULA is building the border or generating a vertical retrace. This behaviour is actually used in some programs, for instance by Arkanoid, and Z80 also emulates this. Finally, there is an interesting bug in the ULA which also has to do with this split bus. After each instruction fetch cycle of the processor, the processor puts the I-R register 'pair' (not the 8 bit internal Instruction Register, but the Interrupt and R registers) on the address bus. The lowest 7 bits, the R register, are used for memory refresh. However, the ULA gets confused if I is in the range 64-127, because it thinks the processor wants to read from lower 16K ram very, very often. The ULA can't cope with this read-frequency, and regularly misses a screen byte. Instead of the actual byte, the byte previously read is used to build up the video signal. The screen seems to be filled with 'snow'; however, the Spectrum won't crash, and program will continue to run normally. There's one program I know of that uses this to generate a nice effect: Vectron. (which has very nice music too by the way). This effect has not been implemented however - it's a bit useless (but maybe I'll include it in the future). The processor has three interrupt modes, selected by the instructions IM 0, IM 1 and IM 2. In mode 1, the processor simply executes a RST #38 instruction if an interrupt is requested. This is the mode the Spectrum is normally in. The other mode that is commonly used is IM 2. If an interrupt is requested, the processor first builds a 16 bit address by combining the I register (as the high byte) with whatever the interrupting device places on the data bus. The processor then fetches the 16-bit address at this interrupt table entry, and finally CALLs the subroutine at that address. Rodnay Zaks in his book 'Programming the Z80' states that only even bytes are allowed as low index byte, but that isn't true. The normal Spectrum contains no hardware to place a byte on the bus, and the bus will therefore always read FF (because the ULA also doesn't read the screen if it generates an interrupt), so the resulting index address is 256*I+0FF. However, some not-so-neat hardware devices put things on the data bus when they shouldn't, so later programs didn't assume the low index byte was 0FF. These programs contain a 257 byte table of equal bytes starting at 256*I, and the interrupt routine is placed at an address that is a multiple of 257. A useful but not so much used trick is to make the table contain FF's (or use the ROM for this) and put a byte 18 hex, the opcode for JR, at FFFF. The first byte of the ROM is a DI, F3 hex, so the JR will jump to FFF4, where a long JP to the actual interrupt routine is put. In interrupt mode 0, the processor executes the instruction that the interrupting device places on the data bus. On a standard Spectrum this will be the byte FF, coincidentally (...) the opcode for RST #38. But for the same reasons as above, this is not really reliable. The 50 Hz interrupt is synchronized with the video signal generation by the ULA; both the interrupt and the video signal are generated by it. Many programs use the interrupt to synchronize with the frame cycle. Some use it to generate fantastic effects, such as full-screen characters, full-screen horizon (Aquaplane) or pixel colour (Uridium for instance). Many modern programs use the fact that the screen is 'written' (or 'fired') to the CRT in a finite time to do as much time-consuming screen calculations as possible without causing character flickering: although the ULA has started displaying the screen for this frame already, the electron beam will for a moment not 'pass' this-or-that part of the screen so it's safe to change something there. So the exact time in the 1/50 second time-slice at which the screen is updated is very important. Normally the emulator updates the entire screen at once (50 times a second), and no best solution can be given as to when exactly the screen should be updated. The user can select one of three possibilities (low, normal and high video synchronisation, corresponding to a screen update after 1/200, 2/200 or 3/200 of a (relative) second after a Z80 interrupt) to try to get the best results. Try for instance Zynaps; with normal video synchronisation the top four or five lines of the background move out-of-phase with the rest, and your space-ship flickers in that region. With low video synchronisation the background moves smoothly but the sprites flicker in all parts of the screen. Only with high video sync everything moves smoothly and doesn't flicker. In Hi-resolution color emulation mode, however, the emulator makes a copy of every screen- and attribute-line in a buffer at the exact time the ULA would display it. Also, the exact times the border colour is changed is stored. Using this information the emulator builds the screen; in this way, what you see on your PC monitor is exactly what a real Spectrum would display on a television. Remember Aquaplane, with its full-width horizon? Each line takes exactly 224 T states. After an interrupt occurs, 64 line times pass before the byte 16384 is displayed. At least the last 48 of these are actual border-lines. I could not determine whether my monitor didn't display the others or whether it was in vertical retrace, but luckily that's not really important. Then the 192 screen+border lines are displayed, followed by 56 border lines again. This makes a total of 312 lines of 224 T states, or 69888 T states, which is, at 3.5 MHz, very nearly 1/50th of a second. Now for the timings of each line itself. I define a screen line to start with 256 screen pixels, then border, then horizontal retrace, and then border again. All this takes 224 T states. Every half T state a pixel is written to the CRT, so if the ULA is reading bytes it does so each 4 T states (and then it reads two: a screen and an ATTR byte). The border is 48 pixels wide at each side. A video screen line is therefore timed as follows: 128 T states of screen, 24 T states of right border, 48 T states of horizontal retrace and 24 T states of left border. When an interrupt occurs, the running instruction has to be completed first. The Z80 samples the state of its interrupt request line at the start of the last T state of each instruction. The Z80 starts to act upon an interrupt request at least 1, and at most 1+23 T states after it is made active, as the slowest instructions (e.g. INC (IX+d), RL (IX+d), EX (SP),IX) take 23 T states. This difference, which may be hard to control, is sometimes significant in practice for hi-resolution color effects. In interrupt mode 0, the processor takes 2 more T states for executing the opcode supplied than the normal value; if RST #38 is supplied (#FF), it takes 13 T states. In interrupt mode 1, my reference gives two values (12 and 13 T states) for the timing of a mode 1 interrupt. I would put my money on 12 T states. A mode 2 interrupt takes 19 T states. Finally, a Non Maskable interrupt is fastest: it takes only 11 T states. The ZX81 hardware generates a WAIT only 16 T states before it generates an NMI, which, by some combined hardware and software wizardry, generates one scanline on the television screen. It seems therefore that by executing a whole lot of slow instructions in a block, it is possible to jam the horizontal synchonisation of the ZX81 video signal. Has this ever been tried? Now when to OUT to the border to change it at the place you want? First of all, you cannot change the border within a 'byte', an 8-pixel chunk. If we forget about the screen for a moment, if you OUT to port FE after 14326 to 14329 T states (including the OUT) from the start of the IM 2 interrupt routine, the border will change at exactly the position of byte 16384 of the screen. The other positions can be computed by remembering that 8 pixels take 4 T states, and a line takes 224 T states. You would think that OUTing after 14322 to 14325 T states, the border would change at 8 pixels left of the upper left corner of the screen. This is right for 14322, 14323 and 14324 T states, but if you wait 14325 T states the ULA happens to be reading byte 16384 (or 22528, or both) and will halt the processor for a while, thereby making you miss the 8 pixels. This exception happens again after 224 T states, and again after 448, an so forth. These 192 exceptions left of the actual screen rectangle are the only ones; similar things don't happen at the right edge because the ULA don't need to read things there - it has just finished! As noted above, reading or writing in low ram (or OUTing to the ULA!) causes the ULA to halt the processor. When and how much? The processor is halted each time you want to access the ULA or low memory and the ULA is busy reading. Of the 312 'lines' the ULA generates, only 192 contain actual screen pixels, and the ULA will only read bytes during 128 of the 224 T states of each screen line. But if it does, the processor seems to be halted for 64 T states. It is not clear to me when, and for how long exactly, the ULA halts the processor. Sometimes the ULA even stops the processor when it is not interfering with it (when it is busy making the border left or right of the screen rectangle). Finally, the 128K timings. These are slightly different from the 48K video timings, causing for instance the loading bars in the border to move differently (which can be seen most clearly when saving). The really important difference of the 128K with respect to the video is that the 128K ULA is more relaxed in giving the Z80 access to (screen) memory. This allows programs to make hi-resolution color effects not only in the border, but also on the screen itself. Many 128K programs use this effect. Note however that, although the 128K ULA is more relaxed towards memory access, it does still halt the Z80 occasionally. Partly for this reason it is impossible to have hi-res color effect over the entire screen; there is only time to change approximately half of it. The basic video timings, with the Z80 out of the way, are as follows. Each video line takes 228 T states, 4 T states more than on the 48K Spectrum. It starts with 128 T states of screen pixels (or border). Then there's border, horizontal retrace and border again, of 100 T states. A complete '50 Hz' frame consists of 311 video lines (of which a few are vertical retraces), that is, 1 less than for 48K models. A complete frame is 311 x 228 = 70908 T states long. I don't know whether the 128K model uses a different crystal. If not, one frame on the Spectrum 128K is 1.5% longer than a 48K frame. Directly after an interrupt is generated by the ULA (so slightly before the Z80 acts upon it), 63 video lines are written to the CRT. A first few may be verical retraces; this is difficult to find out without an oscilloscope, but it isn't useful information either. Then 192 screen lines are written, and then 56 border lines and (possibly) vertical retrace lines. The first screen byte is written to the screen 14364 T states after the interrupt was generated. 5.2 The Interface I The Interface I is quite complicated. It uses three different I/O ports, and contains logic to page and unpage an 8K ROM if new commands are used. I won't be very detailed here; you could refer to the source code of the emulator if you want to know some details, or read the 'Spectrum Shadow ROM Disassembly' by Gianlura Carri, published by Melbourne House - but don't expect the same level of detail as of Ian Logan and Frank O'Hara in their Rom disassembly book. The ROM is paged if the processor executes the instruction at ROM address 0008 or 1708 hexadecimal, the error and close# routines. It is inactivated when the Z80 executes the RET at address 0700. I/O Port E7 is used to send or receive data to and from the microdrive. Accessing this port will halt the Z80 until the Interface I has collected 8 bits from the microdrive head; therefore, it the microdrive motor isn't running, or there is no formatted cartridge in the microdrive, the Spectrum hangs. This is the famous 'IN 0 crash'. Port EF is used for several things: Bit 7 6 5 4 3 2 1 0 ÚÄÄÄÂÄÄÄÂÄÄÄÄÂÄÄÄÄÂÄÄÄÄÄÂÄÄÄÂÄÄÄÄÄÂÄÄÄÄÄ¿ READ³ ³ ³ ³busy³ dtr ³gap³ sync³write³ ³ ³ ³ ³ ³ ³ ³ ³prot.³ ÃÄÄÄÅÄÄÄÅÄÄÄÄÅÄÄÄÄÅÄÄÄÄÄÅÄÄÄÅÄÄÄÄÄÅÄÄÄÄÄ´ WRITE³ ³ ³wait³ cts³erase³r/w³comms³comms³ ³ ³ ³ ³ ³ ³ ³ clk ³ data³ ÀÄÄÄÁÄÄÄÁÄÄÄÄÁÄÄÄÄÁÄÄÄÄÄÁÄÄÄÁÄÄÄÄÄÁÄÄÄÄÄÙ Bits DTR and CTS are used by the RS232 interface. The WAIT bit is used by the Network to synchronise, GAP, SYNC, WR_PROT, ERASE, R/_W, COMMS CLK and COMMS DATA are used by the microdrive system. If the microdrive is not being used, the COMMS DATA output selects the function of bit 0 of out-port F7: Bit 7 6 5 4 3 2 1 0 ÚÄÄÄÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄ¿ READ³txdata³ ³ ³ ³ ³ ³ ³ net ³ ³ ³ ³ ³ ³ ³ ³ ³ input ³ ÃÄÄÄÄÄÄÅÄÄÄÅÄÄÄÅÄÄÄÅÄÄÄÅÄÄÄÅÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄ´ WRITE³ ³ ³ ³ ³ ³ ³ ³net output/³ ³ ³ ³ ³ ³ ³ ³ ³ rxdata ³ ÀÄÄÄÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÙ TXDATA and RXDATA are the input and output of the RS232 port. COMMS DATA determines whether bit 0 of F7 is output for the RS232 or the network. 5.3 The SamRam The SamRam contains a 32K static CMOS Ram chip, and some I/O logic for port 31. If this port is read, it returns the position of the joystick, as a normal Kempston joystickinterface would. If written to, the port controls a programmable latch chip (the 74LS259) which contains 8 latches: Bit 7 6 5 4 3 2 1 0 ÚÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄ¿ WRITE³ ³ ³ ³ ³ address ³bit³ ÀÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÙ The address selects on of the eight latches; bit 0 is the new state of the latch. The 16 different possibilities are collected in the diagram below: OUT 31, ³ Latch ³ Result ÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 0 ³ 0 ³ Switch on write protect of CMOS RAM 1 ³ " ³ Writes to CMOS RAM allowed 2 ³ 1 ³ turn on CMOS RAM (see also 6/7) 3 ³ " ³ turn off CMOS RAM (standard Spec. ROM) 4 ³ 2 ³ - 5 ³ " ³ Ignore all OUT's to 31 hereafter 6 ³ 3 ³ Select CMOS bank 0 (Basic ROM) 7 ³ " ³ Select CMOS bank 1 (Monitor,...) 8 ³ 4 ³ Select interface 1 9 ³ " ³ Turn off IF 1 (IF1 rom won't be paged) 10 ³ 5 ³ Select 32K ram bank 0 (32768-65535) 11 ³ " ³ Select 32K ram bank 1 (32768-65535) 12 ³ 6 ³ Turn off beeper 13 ³ " ³ Turn on beeper 14 ³ 7 ³ - 15 ³ " ³ - At reset, all latches are 0. If an OUT 31,5 is issued, only a reset will give you control over the latches again. The write protect latch is not emulated; you're never able to write the emulated CMOS ram in the emulator. Latch 4 will pull up the M1 output of the Z80. The Interface I won't page the ROM anymore then. 5.4 The Z80 microprocessor The Z80 processor is quite straightforward, and contains to my knowledge no interesting bugs or quirks. However, it has some undocumented features. Some of these are quite useful, and some are not, but since many programs use the useful ones, and a few programs use the weird ones, I tried to figure them out and emulate them as best as I could. There is a Z80 emulator around, intended as a CP/M emulator, which halts the program if an undocumented opcode is encountered. I don't think this makes sense. ZiLOG doesn't dictate the law, the programs which use the processor's features do! In section 5.1 there is some information on Z80 interrupt timings in different modes. Most Z80 opcodes are one byte long, not counting a possible byte or word operand. The four opcodes CB, DD, ED and FD are 'shift' opcodes: they change the meaning of the opcode following them. There are 248 different CB opcodes. The block CB 30 to CB 37 is missing from the official list. These instructions, usually denoted by the mnemonic SLL, Shift Left Logical, shift left the operand and make bit 0 always one. Bounder and Enduro Racer use them, to name just two. The SamRam monitor can disassemble these and uses the mnemonic SLL. These instructions are quite commonly used. The DD and FD opcodes precede instructions using the IX and IY registers. If you look at the instructions carefully, you see how they work: 2A nn LD HL,(nn) DD 2A nn LD IX,(nn) 7E LD A,(HL) DD 7E d LD A,(IX+d) A DD opcode simply changes the meaning of HL in the next instruction. If a memory byte is addressed indirectly via HL, as in the second example, a displacement byte is added. Otherwise the instruction simply acts on IX instead of HL. (A notational awkwardness, that will only bother assembler and disassembler writers: JP (HL) is not indirect; it should have been denoted by JP HL) If a DD opcode precedes an instruction that doesn't use the HL register pair at all, the instruction is executed as usual. However, if the instruction uses the H or L register, it will now use the high or low halves of the IX register! Example: 44 LD B,H FD 44 LD B,IYh These types of inofficial instructions are used in many programs. By the way, many DD or FD opcodes after each other will effectively be NOPs, doing nothing except repeatedly setting the flag 'treat HL as IX' (or IY) and taking up 4 T states. (But try to let MONS disassemble such a block.) The doubly-shifted opcodes that start with DD CB and DD ED behave differently. If a DD or FD precedes an ED instruction, the DD or FD is ignored. ED instructions never operate on the IX or IY register, and are executed normally instead. With CB instructions, the situation is more interesting. Within an 8-instruction block, every DD CB instruction works as the official one, but also copies the result to the specified register (except when it is (HL)). For example, CB CE SET 0,(HL) CB C0 SET 0,B DD CB nn CE SET 0,(IX+nn) DD CB nn C0 SET 0,(IX+nn) ; copy result to B (The information about the inofficial CB instructions was given to me by Arnt Gulbrandsen, and originated from David Librik.) There are a number of inofficial ED instructions, but none of them are very useful. The ED opcodes in the range 00-3F and 80-FF (except for the block instructions of course) do nothing at all but taking up 8 T states and incrementing the R register by 2. Most of the unlisted opcodes in the range 40-7F do have an effect, however. The complete list: (* = not official) ED40 IN B,(C) ED60 IN H,(C) ED41 OUT (C),B ED61 OUT (C),H ED42 SBC HL,BC ED62 SBC HL,HL ED43 LD (nn),BC ED63 * LD (nn),HL ED44 NEG ED64 * NEG ED45 RETN ED65 * RET ED46 IM 0 ED66 * IM 0 ED47 LD I,A ED67 RRD ED48 IN C,(C) ED68 IN L,(C) ED49 OUT (C),C ED69 OUT (C),L ED4A ADC HL,BC ED6A ADC HL,HL ED4B LD BC,(nn) ED6B * LD HL,(nn) ED4C * NEG ED6C * NEG ED4D RETI ED6D * RET ED4E * IM 0 ED6E * IM 0 ED4F LD R,A ED6F RLD ED50 IN D,(C) ED70 * IN (C) ED51 OUT (C),D ED71 * OUT (C),0 ED52 SBC HL,DE ED72 SBC HL,SP ED53 LD (nn),DE ED73 LD (nn),SP ED54 * NEG ED74 * NEG ED55 * RET ED75 * RET ED56 IM 1 ED76 * IM 1 ED57 LD A,I ED77 * NOP ED58 IN E,(C) ED78 IN A,(C) ED59 OUT (C),E ED79 OUT (C),A ED5A ADC HL,DE ED7A ADC HL,SP ED5B LD DE,(nn) ED7B LD SP,(nn) ED5C * NEG ED7C * NEG ED5D * RET ED7D * RET ED5E IM 2 ED7E * IM 2 ED5F LD A,R ED7F * NOP The ED70 instruction reads from port (C), just like the other instructions, but throws away the result. It does change the flags in the same way as the other IN instructions, however. The ED71 instruction OUTs a byte zero to port (C), interestingly. These instructions 'should', by regularity of the instruction set, use (HL) as operand, but since from the processor's point of view accessing memory or accessing I/O devices is almost the same thing, and since the Z80 cannot access memory twice in one instruction (disregarding instruction fetch of course) it can't fetch or store the data byte. (A hint in this direction is that, even though the NOP-synonyms LD B,B, LD C,C etcetera do exist, LD (HL),(HL) is absent and replaced by the HALT instruction.) The instructions ED 4E and ED 6E are IM 0 equivalents: when FF was put on the bus at interrupt time, the Spectrum continued to execute normally, whereas when an EF (RST #28) was put on the bus it crashed, just as it does in that case when the Z80 is in the official interrupt mode 0. In IM 1 the Z80 just executes a RST #38 (opcode FF) no matter what is on the bus. The RETI instruction is functionally exactly equivalent to the RET instruction. It is used only to signify the end of an interrupt routine to an external hardware device (read: the Z80 PIO). The RETN however is different from RET in that it resets IFF1 to the current value of IFF2. Now IFF1 and IFF2 are usually equal (and become equal after DI and EI and after a maskable interrupt has been accepted). They're different only if an NMI occurs when interrupts are enabled; then IFF1 is off, and IFF2, holding the previous state of the interrupt flip flop, is on, signifying that interrupts were enabled before the non-maskable interrupt. Since the state of IFF2 can be read by using LD A,R and LD A,I, the RETN instruction is not used much in Spectrum ROM software, and it is utterly useless in normal software. In other words, I have not tried to figure out whether the unofficial RET's are RETI's or RETN's. About the R register. This is not really an undocumented feature, although I have never seen any thorough description of it anywhere. The R register is a counter that is updated every instruction, where DD, FD, ED and CB are to be regarded as separate instructions. So shifted instructions will increase R by two. There's an interesting exception: doubly-shifted opcodes, the DDCB and FDCB ones, increase R by two too. LDI increases R by two, LDIR increases it by 2 times BC, as does LDDR etcetera. The sequence LD R,A / LD A,R increases A by two. The highest bit of the R register is never changed (except possibly by LD R,A of course). This is because in the old days everyone used 16 Kbit chips. Inside the chip the bits where grouped in a 128x128 matrix, needing a 7 bit refresh cycle. Therefore ZiLOG decided to count only the lowest 7 bits. If the R register emulation is switched on the R register will behave as is does on a real Spectrum; if it is off it will (except for the upper bit) act as a random generator. You can easily check that the R register is really crucial to memory refresh. Assemble this program: ORG 32768 DI LD B,0 L1 XOR A LD R,A DEC HL LD A,H OR L JR NZ,L1 DJNZ L1 EI RET It will take about three minutes to run. Look at the upper 32K of memory, for instance the UDG graphics. It will have faded. Only the first few bytes of each 256 byte block will still contain zeros, because they were refreshed during the execution of the loop. The ULA took care of the refreshing of the lower 16K. (This example won't work on the emulator of course!) Then there's one other dark corner of the Z80 which has its effect on programs like Sabre Wulf, Ghosts'n Goblins and Speedlock. The Mystery of the Undocumented Flags! Bit 3 and 5 of the F register are not used. They can contain information, as you can readily figure out by using PUSH AF and POP AF. Furthermore, sometimes their values change. I found the following empirical rule: The values of bit 7, 5 and 3 follow the values of the corresponding bits of the last 8 bit result of an instruction that changed the usual flags. For instance, after an ADD A,B those bits will be identical to the bits of the A register. (Bit 7 of F is the sign flag, and fits the rule exactly). An exception is the CP x instruction (x=register, (HL) or direct argument). In that case the bits are copied from the argument. If the instruction is one that operates on a 16 bit word, the 8 bits of the rule are the highest 8 bits of the 16 bit result - that was to be expected since the S flag is extracted from bit 15. Ghosts'n Goblins use the undocumented flag due to a programming error. The rhino in Sabre Wulf walks backward or keeps running in little circles in a corner, if the (in this case undocumented) behaviour of the sign flag in the BIT instruction isn't right. I quote: AD86 DD CB 06 7E BIT 7,(IX+6) AD8A F2 8F AD JP P,#AD8F An amazing piece of code! Speedlock does so many weird things that everything must be exactly right for it to run. Finally, the '128 rom uses the AF register to hold the return address of a subroutine for a while. To keep all programs happy, and still have a fast emulator, I had to make a compromise. The undocumented flags are not always emulated right, but they are most of the time. Not telling you when not. Now for the emulated Z80. I have added eight instructions, to speed up the RS232 input and output of the Interface I and several things of the SamRam. These opcodes, ED F8 to ED FE are of little use to any other program. ED FF is a nice one: it returns you to DOS immediately. I used it for debugging purposes, and it is also used in TAP2TAPE and SAMLIST. The opcode ED F6, which is used by the SamRam, is now also used to use multi-load games on the emulator. If the emulator encounters the opcode ED F6 in RAM (above 16384), it loads a block of code into memory at address HL. The name of the file to be loaded is the name of the snapshot file currently run, with the decimal value of the A register attached to it. The extension is .DAT. If such a file is not found, the user is informed of the value of the A register and allowed to supply a file name himself (no sexual prejudice implied). 5.5 File formats This section describes the format of the files used by the emulator. ROMS.BIN: --------- 00000-03fff Ordinary Spectrum rom 04000-05fff Interface I rom (8K) 06000-09fff First SamRam rom (contains BASIC) 0a000-0dfff Second SamRam rom (contains monitor,...) 0e000-11fff First Spectrum 128K rom (active at RESET) 12000-15fff Second Spectrum 128K rom (contains BASIC) 16000-19fff Disciple rom, system file 3b, Epson printer code 1a000-1dfff Disciple rom, system file 3b, HP printer code 1e000-1ffff Multiface rom (8K) The ordinary rom has not been modified. The Interface I rom has undergone some modifications, to speed up the RS232 input/output routines. If you don't like this, or want to use another version of the Interface I, you could put that code at the right place in the ROMS.BIN file. The interface I should work properly, although the RS232 will be slower (always FORMAT the "b" or "t" channel at 19200 baud, by the way, if you replace the rom code, there's no point in waiting for nothing.) The microdrive routines have not been modified in any way. Here are the changes of the Interface I rom: Address: Old: New: Address: Old: New: 0B9E ED ED 0D20 FB 00 0B9F 5B FC 0D2A 37 ED 0BA0 C3 F5 0D2B F3 FD 0BA1 5C C3 0D2C CE 18 0BA2 21 34 0D2D 00 10 0BA3 20 0C 0D4C FB 00 These changes are not likely to cause problems; there are several versions of the Interface I rom around, and program developers know this. It is also a bit pointless to check whether the Interface I rom hasn't been modified; who would put his snapshot software in there anyway, and that's what those people are afraid of. The first and second SamRam rom have been modified more extensively. The biggest problem was that switching the upper 32K ram bank is very fast in reality, but on the PC two blocks of 32K bytes had to be REP MOVSWded (or the EMS emulator be called). But since no programs know of the SamRam code anyway, this won't cause any more problems it wouldn't already cause either. The two Spectrum 128 roms have not been modified, and neither have the Disciple roms or the Multiface rom. The Disciple roms, as they appear in the ROMS.BIN file, do have system files pre-loaded however. .TAP FILES: ----------- The .TAP files contain blocks of tape-saved data. All blocks start with two bytes specifying how many bytes will follow (not counting the two length bytes). Then raw tape data follows, including the flag and checksum bytes. The checksum is the bitwise XOR of all bytes including the flag byte. For example, when you execute the line SAVE "ROM" CODE 0,2 this will result: |------ Spectrum-generated data -------| |---------| 13 00 00 03 52 4f 4d 7x20 02 00 00 00 00 80 f1 04 00 ff f3 af a3 ^^^^^...... first block is 19 bytes (17 bytes+flag+checksum) ^^... flag byte (A reg, 00 for headers, ff for data blocks) ^^ first byte of header, indicating a code block file name ..^^^^^^^^^^^^^ header info ..............^^^^^^^^^^^^^^^^^ checksum of header .........................^^ length of second block ........................^^^^^ flag byte ............................................^^ first two bytes of rom .................................^^^^^ checksum (checkbittoggle would be a better name!).............^^ The emulator will always start reading bytes at the beginning of a block. If less bytes are loaded than are available, the other bytes are skipped, and the last byte loaded is used as checksum. If more bytes are asked for than exist in the block, the loading routine will terminate with the usual tape-loading-error flags set, leaving the error handling to the calling Z80 program. Note that it is possible to join .TAP files by simply stringing them together, for example COPY /B FILE1.TAP + FILE2.TAP ALL.TAP For completeness, I'll include the structure of a tape header. A header always consists of 17 bytes: Byte Length Description 0 1 Type (0,1,2 or 3) 1 10 Filename (padded with blanks) 11 2 Length of data block 13 2 Parameter 1 15 2 Parameter 2 The type is 0,1,2 or 3 for a Program, Number array, Character array or Code file. A screen$ file is regarded as a Code file with start address 16384 and length 6912 decimal. If the file is a Program file, parameter 1 holds the autostart line number (or a number >=32768 if no LINE parameter was given) and parameter 2 holds the start of the variable area relative to the start of the program. If it's a Code file, parameter 1 holds the start of the code block when saved, and parameter 2 holds 32768. For data files finally, the byte at position 14 decimal holds the variable name. .MDR FILES: ----------- The emulator uses a cartridge file format identical to the 'Microdrive File' format of Carlo Delhez' Spectrum emulator Spectator for the QL, who devised the format. This format is now also supported by XZX of Des Harriot. The following information is adapted from Carlo's documentation. It can also be found in the 'Spectrum Microdrive Book', by Ian Logan (co-writer of the excellent 'Complete Spectrum ROM Disassembly'). A cartridge file contains 254 'sectors' of 543 bytes each, and a final byte flag which is non-zero is the cartridge is write protected, so the total length is 137923 bytes. On the cartridge tape, after a GAP of some time the Interface I writes 10 zeros and 2 FF bytes (the preamble), and then a fifteen byte header-block-with-checksum. After another GAP, it writes a preamble again, with a 15-byte record- descriptor-with-checksum (which has a structure very much like the header block), immediately followed by the data block of 512 bytes, and a final checksum of those 512 bytes. The preamble is used by the Interface I hardware to synchronise, and is not explicitly used by the software. The preamble is not saved to the microdrive file: offset length name contents 0 1 HDFLAG Value 1, to indicate header block 1 1 HDNUMB sector number (values 254 down to 1) 2 2 not used 4 10 HDNAME microdrive cartridge name (blank padded) 14 1 HDCHK header checksum (of first 14 bytes) 15 1 RECFLG - bit 0: always 0 to indicate record block - bit 1: set for the EOF block - bit 2: reset for a PRINT file - bits 3-7: not used (value 0) 16 1 RECNUM data block sequence number (value starts at 0) 17 2 RECLEN data block length (<=512, LSB first) 19 10 RECNAM filename (blank padded) 29 1 DESCHK record descriptor checksum (of previous 14 bytes) 30 512 data block 542 1 DCHK data block checksum (of all 512 bytes of data block, even when not all bytes are used) --------- 254 times (Actually, this information is 'transparent' to the emulator. All it does is store 2 times 254 blocks in the .MDR file as it is OUTed, alternatingly of length 15 and 528 bytes. The emulator does check checksums, see below; the other fields are dealt with by the emulated Interface I software.) A used record block is either an EOF block (bit 1 of RECFLG is 1) or contains 512 bytes of data (RECLEN=512, i.e. bit 1 of MSB is 1). An empty record block has a zero in bit 1 of RECFLG and also RECLEN=0. An unusable block (as determined by the FORMAT command) is an EOF block with RECLEN=0. The three checksums are calculated by adding all the bytes together modulo 255; this will never produce a checksum of 255. Possibly, this is the value that is read by the Interface I if there's no or bad data on the tape. In normal operation, all first-fifteen-byte blocks of each header or record block will have the right checksum. If the checksum is not right, the block will be treated as a GAP. For instance, if you type OUT 239,0 on a normal Spectrum with interface I, the microdrive motor starts running and the cartridge will be erased completely in 7 seconds. CAT 1 will respond with 'microdrive not ready'. Try it on the emulator... .OUT FILES: ----------- These files are produced when logging OUTs; see menu option O in the Extra Functions menu. For the specified I/O ports, all OUTs to these ports are recorded in the .OUT file, together with the exact time at which the OUTs were executed. An .OUT file consists of a string of 5-byte blocks. The first word is the timing word; it has a value between 0 and 17471 inclusive (or between 0 and 17726 inclusive when a 128K Spectrum was emulated), and a unit value corresponds to 1 T state (=1/3494400 s). After this, the OUT port that was written to follows, then the value OUTed itself: Offset Length Description 0 2 Time (0-17471 or 0-17726) 2 2 Port address 4 1 Value Every 1/200th of an emulated second, that is, every 69888/4=17472 T states (or 70908/4=17727 T states on 128K Spectrums), a time-wraparound block is written to the .OUT file: Offset Length Description 0 2 Flag word #FFFF indicating wraparound-block 2 2 Length of preceding block (17472 or 17727 T) 4 1 Not used So even when the Spectrum does not OUT to the logged ports at all, 1000 bytes get written to the log file every second. By default, an OUT to an even I/O address which does not change the state of the MIC and EAR outputs is not written to the .OUT file, to save disk space when recording music. If you want all OUTs, specify -xg on the command line. The .OUT files are also used to make a simple trace of a running Spectrum program. Specify -xy on the command line; as soon as you activate OUT logging, a trace is dumped also. For each instruction encountered during emulation, the following block is written to the .OUT file: Offset Length Description 0 2 Flag word (#FFFE) 2 2 Program counter 5 1 A register Furthermore, no time-wraparound blocks are written to the .OUT file when tracing. HALT instructions (118 decimal) are special in that they do not generate a block in the log file; this is to make comparisons between different logs of the same program easier. Admittedly, this is a very crude way of tracing a program, but it's better than nothing, and very useful very occasionally. .SCR FILES: ----------- .SCR files are memory dumps of the first 6912 bytes of the Spectrum memory. A coordinate (x,y), x between 0 and 255 and y between 0 and 192, (0,0) being the upper left corner of the screen, corresponds to the pixel address 16384+INT (x/8)+1792*INT (y/64)-2016*INT (y/8)+256*y I admit this is not quite the clearest way to explain the organization of Spectrum's video memory, but with a bit or (hard) thinking you can extract from above formula all information you need... The lowest three bits of x determine which bit of this address corresponds to the pixel (x,y). This bit-map constitutes the larger part of the screen memory, 256*192/8=6144 bytes. The final 768 bytes are attribute bytes. The address of the attribute byte corresponding to pixel (x,y) is 22528+INT (x/8)+32*INT (y/8) The lowest three bits of the attribute byte control the foreground color (the color of the pixel if the corresponding bit in the bitmap is set), bits 3-5 control the background color, bit 6 is the bright bit and bit 7 is the flash bit - if it is set, every 16/50th of a second the ULA effectively flips the foreground and background colours. .Z80 FILES: ----------- The old .Z80 snapshot format (for version 1.45 and below) looks like this: Offset Length Description 0 1 A register 1 1 F register 2 2 BC register pair (LSB, i.e. C, first) 4 2 HL register pair 6 2 Program counter 8 2 Stack pointer 10 1 Interrupt register 11 1 Refresh register (Bit 7 is not significant!) 12 1 Bit 0 : Bit 7 of the R-register Bit 1-3: Border colour Bit 4 : 1=Basic SamRom switched in Bit 5 : 1=Block of data is compressed Bit 6-7: No meaning 13 2 DE register pair 15 2 BC' register pair 17 2 DE' register pair 19 2 HL' register pair 21 1 A' register 22 1 F' register 23 2 IY register (Again LSB first) 25 2 IX register 27 1 Interrupt flipflop, 0=DI, otherwise EI 28 1 IFF2 (not particularly important...) 29 1 Bit 0-1: Interrupt mode (0, 1 or 2) Bit 2 : 1=Issue 2 emulation Bit 3 : 1=Double interrupt frequency Bit 4-5: 1=High video synchronisation 3=Low video synchronisation 0,2=Normal Bit 6-7: 0=Cursor/Protek/AGF joystick 1=Kempston joystick 2=Sinclair 2 Left joystick (or user defined, for version 3 .Z80 files) 3=Sinclair 2 Right joystick Because of compatibility, if byte 12 is 255, it has to be regarded as being 1. After this header block of 30 bytes the 48K bytes of Spectrum memory follows in a compressed format (if bit 5 of byte 12 is one). The compression method is very simple: it replaces repetitions of at least five equal bytes by a four-byte code ED ED xx yy, which stands for "byte yy repeated xx times". Only sequences of length at least 5 are coded. The exception is sequences consisting of ED's; if they are encountered, even two ED's are encoded into ED ED 02 ED. Finally, every byte directly following a single ED is not taken into a block, for example ED 6*00 is not encoded into ED ED ED 06 00 but into ED 00 ED ED 05 00. The block is terminated by an end marker, 00 ED ED 00. That's the format of .Z80 files as used by versions up to 1.45. Starting from version 2.0, a different format is used, since from then on also 128K snapshots had to be supported. This new format is used for all snapshots, either 48K or 128K. However, the emulator still understands the old format. Also note that, although old .Z80 file formats are still understood, the emulator will never procude an old format .Z80 file, and also 48K snapshots are written in the new format. But, then again, new .Z80 file formats can be translated back to the old one (provided that it is an 48K snapshot of course) by using ConvZ80. Version 2.01 and 3.0 .Z80 files start with the same 30 byte header as old .Z80 files used. Bit 4 and 5 of the flag byte have no meaning anymore, and the program counter (byte 6 and 7) are zero to signal a version 2.01 or version 3.0 snapshot file. After the first 30 bytes, the additional header follows: Offset Length Description * 30 2 Length of additional header block (see below) * 32 2 Program counter * 34 1 Hardware mode (see below) * 35 1 If in SamRam mode, bitwise state of 74ls259. For example, bit 6=1 after an OUT 31,13 (=2*6+1) If in 128 mode, contains last OUT to 7ffd * 36 1 Contains 0FF if Interface I rom paged * 37 1 Bit 0: 1 if R register emulation on Bit 1: 1 if LDIR emulation on * 38 1 Last OUT to fffd (soundchip register number) * 39 16 Contents of the sound chip registers 55 2 Low T state counter 57 1 Hi T state counter 58 1 Flag byte used by Spectator (QL spec. emulator) Ignored by Z80 when loading, zero when saving 59 1 0FF if MGT Rom paged 60 1 0FF if Multiface Rom paged. Should always be 0. 61 1 0FF if 0-8191 is RAM 62 1 0FF if 8192-16383 is RAM 63 10 5x keyboard mappings for user defined joystick 73 10 5x ascii word: keys corresponding to mappings above 83 1 MGT type: 0=Disciple+Epson,1=Discipls+HP,16=Plus D 84 1 Disciple inhibit button status: 0=out, 0ff=in 85 1 Disciple inhibit flag: 0=rom pageable, 0ff=not The value of the word at position 30 is 23 for version 2.01 files, and 54 for version 3.0 files. The starred fields are the ones that constitute the version 2.01 header, and their interpretation has remained unchanged except for byte 34: Value: Meaning in v2.01 Meaning in v3.0 0 48k 48k 1 48k + If.1 48k + If.1 2 SamRam 48k + M.G.T. 3 128k SamRam 4 128k + If.1 128k 5 - 128k + If.1 6 - 128k + M.G.T. The hi T state counter counts up modulo 4. Just after the ULA generates its once-in-every-20-ms interrupt, it is 3, and is increased by one every 5 emulated milliseconds. In these 1/200s intervals, the low T state counter counts down from 17472 to 0, which make a total of 69888 T states per frame. The 5 ascii words (high byte always 0) at 73-82 are the keys corresponding to the joystick directions left, right, down (!), up (!), fire respectively. Shift, Symbol Shift, Enter and Space are denoted by [,],/,\ respectively. The ascii values are used only to display the joystick keys; the information in the 5 keyboard mapping words determine which key is actually pressed (and should correspond to the ascii values). The low byte is in the range 0-7 and determines the keyboard row. The high byte is a mask byte and determines the column. Enter for example is stored as 0x0106 (row 6 and column 1) and 'g' as 0x1001 (row 1 and column 4). Byte 60 must be zero, because the contents of the Multiface RAM is not saved in the snapshot file. If the Multiface was paged when the snapshot was saved, the emulated program will most probably crash when loaded back. Bytes 61 and 62 are a function of the other flags, such as byte 34, 59, 60 and 83. Hereafter a number of memory blocks follow, each containing the compressed data of a 16K block. The compression is according to the old scheme, except for the end-marker, which is now absent. The structure of a memory block is: Byte Length Description 0 2 Length of data (without this 3-byte header) 2 1 Page number of block 3 [0] Compressed data The pages are numbered, depending on the hardware mode, in the following way: Page In '48 mode In '128 mode In SamRam mode 0 48K rom rom (basic) 48K rom 1 Interface I, Disciple or Plus D rom, according to setting 2 - rom (reset) samram rom (basic) 3 - page 0 samram rom (monitor,..) 4 8000-bfff page 1 Normal 8000-bfff 5 c000-ffff page 2 Normal c000-ffff 6 - page 3 Shadow 8000-bfff 7 - page 4 Shadow c000-ffff 8 4000-7fff page 5 4000-7fff 9 - page 6 - 10 - page 7 - 11 Multiface rom Multiface rom - In 48K mode, pages 4,5 and 8 are saved. In SamRam mode, pages 4 to 8 are saved. In '128 mode, all pages from 3 to 10 are saved. This version saves the pages in numerical order. There is no end marker.