Crawly Crypt Collection 1

home *** CD-ROM | disk | FTP | other *** search

/ Crawly Crypt Collection 1 / crawlyvol1.bin / apps / misc / zx_sp207 / specci.doc < prev next >

Wrap

Text File | 1993-10-25 | 91KB | 1,648 lines

# @ # @@@@@@@@ @ @@@@@@@@ @@@@@@@@ @ @@@@@@@@ @ @@@@@@@@ @ @ @ @ @ @ @ @ @ @@@@@@@@ @ @ @ @ @ @@@@@@@@ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@ @ @ @ @@@@@@@@ @ @@@@@@@@ @ @ (TM) ZX-SPECTRUM EMULATOR V2.07 ========================== 1. INTRODUCTION This program emulates a SINCLAIR ZX-Spectrum/48 computer, a Z80-machine with integrated BASIC-interpreter, 48 KB ram, aquipped with joystick (Kempston, Interface 2) and optional Interface 1 with up to 8 microdrives (Sinclair-specific "mass"-storage devices). You need an Atari ST with at least 1 MB ram (2 are of advantage) and monochrome 640x400 display (ST hi-res) or color 320x200 display (ST low-res). A harddisk is not needed, but recommended. There are two versions of this program, one for 68000-machines (ST, (Mega-)STE) and one for 68030-machines (TT, Falcon). Atari-machines with only 8 MHz tend to be a little slow on emulation, so it will become somewhat boring. Nevertheless it is - by tuning with some emulation-switches - possible even on this machines to use some Spectrum-Programs or the BASIC in a way, that the typical "Sinclair"-feeling comes up. More interesting it gets at ST-models with 16 MHz+Cache, on which the term "emulation" is more appropriate. Some Spectrum programs will be running actually faster than the original with this machines, namely all those using a lot of LDIR/LDDR-instructions. The average speed is about 60%. On 68030-models a nearly exact-speed emulation is possible. Version 1.2 of this program is available since mid 1991 - this new version is extensivley enhanced and has been made more comfortable in usage and accurate in emulation. For the ones already knowing version 1.2 there follows a brief summary of the improvements since then - all others can continue reading at chapter 2. New in version 2.0: !! - Extensive Setup-Options, which allow the configuration - both from the desktop as amidst running emulation - of emulation-switches, paths, colour-palette etc. - Emulation is now about 10% faster and more compatible (IM2, keyboard) - Integrated Z80-monitor/disassembler, can be reached anytime via ESC-key - Loading and saving of SNA-files (Ram-snapshots), optionally provided with all emulation-switches, so each program can be saved and reloaded with the most suitable settings for it. - Emulator Shell-program, many tool-programs, interfacing to own programs, intergration of external screen-drivers... - generate NMI, use external ROM-files, save the screen to disk anytime,... So: a lot of changes! A more detailed description will be given starting with chapter 4. 2. THE HISTORY BEHIND Once upon a time the author was on a visit to London, when making a decision of grave consequece: he bought on of these neat little black boxes newly available, beeing labeled with "ZX81" and produced by a firm called "Sinclair Research". There had been wondrous tales beeing spread all over the world about it. Well, the story about the heroic fight with flickering TV-screens and the "rubout" foil-keyplate would be worth an own chapter, but as our topic is not the "ZX81", straight to the conclusion: the spirit of programming had taken over the poor author and he was full of fascination for the magic machine-language Z80. As soon as there where rumours of a successor-machine, named "ZX SPECTRUM", it became his own in no time. Fantastic features awaited the author: opulent BASIC-interpreter, 16 colours and sound-generation, 48 KB ram and four times the speed of the ZX81! The tape-interface - in contrary to its predesessor - beeing impressingly realiable and fast, removing the burdon of saving his work. And the best of all: a real graphic-mode with 256x192 dots resolution for "real-live" pictures... The reader will notice: this statements are meant somewhat ironical in respect to todays computer-power; but those days the Spectrum was a real manifastation of programming-power for the author. Soon there was also good development-software (editor, assembler) available, so the exploration into the depths of Z80 machine-language could be continued, resulting in some respectable own applications. In 1985 the Spectrum had to retire in favorite of the Atari ST, but the "first love" stayed always in the authors mind. So it was not a surprise when thoughts of rebirthing the old friend on the new machine came up. The first experiments doing so where somewhat unsuccessful in 1987 due to insufficient knowledege of the ST. Later the author grew more and more to an insider of the ST but the idea of the Spectrum-emulation had been fallen in oblivion meanwhile. Until there appeared a "ZX81"-emulator for the Atari ST in 1990 from Christoph Zwerschke! This program proved that it was possible to emulate a Z80-machine on the plain ST and brought back the lost ideas for the Spectrum-emulation. As experience now also was present it did not take long, until the first moments of success arrived. Then followed the long, stony way, which had to be overcome on the track of curious-spectacular totalcrashes and mysterous neurotic behaviour of the ZX-Atari or Atari-Spectrum. The matured result was presented as version 1.2 to the astonished public. This was in june 1991 after nearly one year of development. Meanwhile more than two years have passed giving the author - beeing inspired by suggestions of users and his own ideas - plenty of time to lay hand on the optimization, performance and user-friendliness of the emulator, till the whole thing has become quite a "round" affair. 3. WHAT THE URGENT USER NEEDS TO KNOW 3.1 INSTALLATION In order to squeeze as much as possible onto the emulator-disk, all files have been compressed with STZIP. Therefore an installation-program will do the whole job. All there needs to be done is to start "INSTALL.PRG" from the disk. It will query for the required information. If you install a floppy-disk version of the emulator you will need to prepare four formatted disks with 800kB each (10 sectors, double-sided). After successfull installation you will have the option to start the emulator-program immediatly or first call the setup-utility to customize the emulator to your personal needs. 3.2. PERFORMANCE-OVERVIEW As already mentioned the ZX-Spectrum is mimict fairly complete. Keyboard, Screen-Display including border, cassette-tape-interface and sound-generation - everything works as on the original. Also a joystick interface is emulated, so most Spectrum games will work with a joystick attached to the joystick-port of the Atari. There is an option to emulate the notorious interface-1 together with these microdrives. The ZX-printer is NOT emulated, as a compensation it is possible to route RS232-data from the emulated interface-1 to the printer-port of the Atari. The emulator needs - in its basic version - the low or the high ST-screen-resolution. In low resolution it will display all Spectrum colors, in high resolution suitable "greylevels" will be used, to distinguish the colors. Programmers have an option to implement (with some effort) via a built-in software-interface support for any screen-resolution (see appendix). 3.4 USAGE After starting the emulator-program you will see the normal Spectrum boot-process ending with the message "(c) 1982 Sinclair Research Ltd.". To this time the Atari has mutated completely to the ZX-Spectrum. The "Alternate"-key and the right Shift-key are installed as "Symbol-Shift" and the "Control"-Key simulates "EXTENDED-Mode". CapsLock and the left Shift-key work as expected. "Backspace" and "Delete" both give Delete on the Spectrum (CAPS-SHIFT+"0"). The BREAK-key-combination (Abort of BASIC-Program) - Caps-Shift+Space - has been put on the F10-key. All other keys are mapped like the original Spectrum-keyboard. This means fore example that the symbol "@" can be obtained pressing Symbol-Shift+"2" (i.e. Alternate+"2") and not the Atari way. An overview is given in the appendix. For all you "Non-Sinclair-Compatibles": the Spectrum is using a keyword-system for input of commands. When the cursor is displaying an inverse "K" the next pressed key will be interpreted as a keyword. For example pressing "S" will immediatly print out "SAVE" or pressing "P" will give "PRINT". The decision which time to generate keywords and which time to accept normal letters is done by the Spectrum automatically depending on the syntax. If you experience problems using this system, maybe the program "KEYWORS.PRG" can relieve you (see chapter 8). The following keys on the Atari are used for special emulator functions: ESC, F5, F6, F7, F8, HELP, UNDO, INSERT, CLR/HOME Except of F6 and F7 all these keys are principially free configurable i.e. they can be "connected" to certain programs, which the user could write himself. Some of these external programs are already supplied, so they must only be attached to the keys in order of personal preference. See chapters 7 and 8 for more. By default i.e when no own assignements are made, the following is set: ESC ....... calls the integrated Z80-monitor/disassembler F5 ........ calls the SNA-support selection-screen (Special Load and Save) F8 ........ does nothing HELP ...... does nothing (Help screen of version 1.2 has been removed) UNDO ...... switches between four sets of emulator-setups INSERT .... leads to the alert "DESKTOP|ZX-RESET|CONTINUE" CLR/HOME .. does nothing F6 ....... is "hard-wired" with a "RESET"-function, working exactly as a reset-switch on the real Spectrum. "Alternate" together with F6 generates an NMI (Non Maskable Interrupt), which at least with the standard rom leads to a reset too. "Shift-F6" quits the emulator immediately and returns to the desktop. F7 ....... is aquipped with a function to disable the sound-emulation, necessary for certain programs with nerving acoustics. It works as a tri-state-switch toggling between 'normal' emulation, 'Interrupt' and 'off' (see chapter 4.5 and 7). 3.5 LOADING AND SAVING OF PROGRAMS To load one of the supplied Spectrum-programs just key in: LOAD "" i.e. key "J" followed by two times "Symbol-Shift P" (Alternate P). More easily you can obtain the quote by using the "~"-key (the key right to the "Return"-key). A file-selector appears, displaying all available Spectrum-BASIC-programs. Should the list be empty you may start a "scan" for loadable programs with the "F2"-key. After selecting one item with the cursor-keys pressing "Return" will load it. If you know the name of the program you can of course enter LOAD "name" (instead of LOAD ""). To save a program you enter SAVE "name" or SAVE "name" CODE adr,len just as on the real Spectrum. There is another way too to load programs into the emulator: Snapshot-files. For the moment it will suffice to know, that pressing the "F5"-key will display a list of all loadable SNApshot-files from where you can select one and load it with "Return". 3.6 QUITTING THE EMULATOR The emulator is terminated pressing "Shift-F6". No safety-request will be given. Depending on the personal configuration there will be other ways to quit the emulator. With installed "SPSETUP.PRG" you may use the "QUIT"-button. The default-configuration will display an Alert-Box when pressing the "Insert"-key giving the option to return to desktop. 4. THE EMULATION IN DETAIL 4.1 THE CPU EMULATION The ZX-Spectrum is built around the Z80A micro-processor, which is clocked with 3.5 MHz and - beeing an 8-bit chip - has an adress space of 64k. The lower 32k it has to share with another chip, the so called ULA, which is responsible for all I/O processing (mostly screen-output). Therefore programs running in this area are noticable slower than in upper memory. Why I mention this? Because it must be pointed out, that the emulator does NOT emulate the Z80 in respect of speed-behaviour because the emulation even on the Atari TT (in average) is at maximum equal to the original, so it would make no sense (maybe on 68040-machines). Why, I'll try to explain here: The Z80-processor has very few in common with the 680xx. This starts with the reverse order 16-bit-quantities are stored in memory (Z80: low byte first, 680xx: low byte on higher adress), followed by the restriction of the 680xx to access the high byte of a word directly and ends with the fairly different treatment of the status-flags. All this put together results in quite an effort to simulate a single Z80-instruction using 680xx-instructions. Therefore it was necessary to make some simplifications to yield an acceptable emulation-speed. The emulator does not care about the N- and the H-flag (Half-carry) of the Z80. As a consequence the instruction DAA (a special instruction of the Z80 for addition and subtraction of BCD-numbers) does not work correctly. In the Spectrum rom this instruction is used only once and the emulator takes care that in this one case it works, but it is not possible to guarrantee this for other programs - in about 50% of the cases it will work, the other will for example result in "mad" counters, that do not run continiously but jump around up and down all the time or other effects.- Also the R-register of the Z80 is not emulated exactly because each instruction would have needed an additional "add", slowing down the emulator unnecessarily. In most cases the way the R-registers is simulated is completely sufficient. Last of all the parity-function of the P/V-flag is not emulated by similar reasons. But just a few programs use this flag (mostly copy-protection-mechanisms), so this is not really a worry. But now to the more pleasant things: all the Z80 opcodes are emulated even the "inofficial" ones using the halfs of the index-registers and the SLL-instructions. As far as own experiments have shown, also some the ED-instructions declared as unused yield results given by already existing ED-instructions. For example ED54 does the same as 'neg' (ED44) or ED55 the same as 'retn' (ED45). The emulator treats them this way but I think there is hardly one program using this behaviour of the Z80. The flag registers C, S, Z and V are emulated exactly for all instructions, also the unused bits of the flag-register (bits 3 and 5) are carried with. Simulation of the Z80 Interrupt-Mechanism ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 50 times a second the emulation-code (so to say the 'microcode' of the Z80) is interrupted and the emulated IFF (Interrupt-Flip-Flop) is tested to see if interrupts are enabled. If no, there is nothing to do, but if, the processing has to be stopped AFTER completion of the currently emulated instruction in order to branch into the Z80-interrupt-routine. Therefore an ILLEGAL-instruction of the 680xx is put at the end of the 'microcode' and processing continued normally. When the ILLEGAL is encountered at last the 680xx will generate an exception and jump to a routine, where the emulated Z80 program-counter is put on the Z80-stack and changed to the adress of the Z80-interrupt-routine (with regard to active interrupt-mode). Then the ILLEGAL is removed from the 'microcode' and the 680xx continues emulating the Z80. This process guarrentees an exact simulation of the Z80 interrupt-behaviour and also - beeing (680xx-)interrupt-driven - looses only very little of the precious processor-time. 4.2 THE VIDEO-EMULATION Whilst on the Spectrum the video-display is completely the job of an own ULA-chip (ULA = Uncommited-Logic-Array) i.e. the Z80 only needs to supply the video-ram with the picture data, the emulator in addition has to take care that these data get onto the Atari screen. Thats not too easy due to the odd way the Spectrums video-ram is organized - much transformation work has to be done. Especially this part of the emulation needed much fine-tuning and optimization in order to make the emulator usable. In the beginning I implemented the whole thing in the most straigthforward way: a VBL-task periodically refreshed the Atari-Screen from the Spectrums screen-data. Because this is a very time-consuming work I could not display a complete Spectrum-screen in a single VBL-interrupt, so only some lines could be drawn in each interrupt. Although totally optimized, drawing was only done when changes occurred, I never was satisfied with the results - it needed too long and the drawing "in portions" was notable quite badly. Also the 680xx spent most of its time working out if "something changed" in the Spectrums video-ram. So I decided to tackle the thing the other way round: the emulated Z80 already knows exactly when it writes a byte to the screen, so the emulator could display it immediatly too! This meant, that all opcodes of the Z80 that could write to ram had to be "trapped" for the case the target is the ZX video-ram. Then a special routine is activated at once to reflect the changes in Atari video-ram. Due to the fact that one byte change in ZX video-ram makes necessary up to 32 bytes change in Atari video-ram (with about 300 680xx-instructions) I included a test, if the new value is different to the one already in memory (for example: when the screen is cleared via CLS about 70% of it is already clear in most cases). This method worked outstandingly well and was also free from these "portions"-effects. The problem was only to "trap" all possible Z80-instructions. Some of these you never would expect to be used for writing into the video-ram, like the PUSH-instructions (stack-pointer within video-ram) or instructions setting bits or even CALL-instructions, that also perform an internal PUSH. Because I again didn't want to slow down the emulator unnecessarily I didn't trap all those opcodes that are (miss-)used maybe by 0.5% of all programs to make screen-displays (maybe a 68040-version could to this, should Atari ever bring out such a machine.- Would this not be an incentive, Atari?). The compromise was, that the common instructions are "trapped", the others left alone. So it may happen one or the other time, that the displays of a program doesn't get visible on the Atari. Just press UNDO a few times, this will redraw the whole screen. The Spectrum knows eight colours: black, blue, red, magenta, green, cyan, yellow and white each in two intensities (but "black" is "black" no matter what intensity) or brightlevels. Additionally there exists "blinking" (flashing) that periodically toggles background and foreground colour of an 8x8-Square on the screen. These attributes are exactly emulated. As an additional luxury there is the possibility to define the colour-palette with the setup-program yourself. On the monochrome screen colours are substituted by gray-patterns (2x2-grid), which give a suitable display. Emulation of "flashing" and the display of the colours (leaving black & white only) can be turned off also, which is only of interest to gain some speed on slow machines (see chapter 7). 4.2.1 BORDER The "border" is the region around the display, that can be changed in colour by programs. It is emulated low-level i.e. watching the OUT-instruction of the Z80, which makes the emulation principially exact. The big difference to the original is, that a border-change takes "no time" on the Spectrum because the ULA-chip displays it while building the picture. The emulator though has to change quite a lot of screen-bytes - for this time emulation of the Z80 naturally is suspended. Normally you will not notice this, but some programs use fast toggling of the border-colour to generate some "fun"-effects (stripes or even "pictures" in the border-region) and the emulator then will busily draw the border for half a minute. In order to cope with such situations, the method, how the border is drawn can be configured: either with each OUT-instruction immediatly (which may lead to the just mentioned problem) or interrupt-driven i.e. the emulator updates the border perodically each 1/10th to 1/2 second or the border-emulation can be turned off completely. 4.3 THE KEYBOARD-EMULATION The keyboard is emulated (basically spoken) using a table for each keycode of the Atari keyboard, that tells which bits to set or clear in the simulated I/O-portadresses. The decoding is then left to the keyboard-routine of the emulated Spectrum. There is one problem imposed by the Atari's keyboard-processor: it seems to be programmed not to accept more than two keys pressed simultanously, except for the Shift-Keys (Control, Alternate, Caps-Shift) and ESC and TAB. This means it will for example not notify the 680xx when an additional key is pressed after "A" and "S" are already pressed. So the emulator cannot notice that too, whilst on the Spectrum it is no problem to test, if three or more keys are pressed. Try for example 10 PRINT AT 1,1;IN 65022;" ";:GOTO 10. Pressing more than two keys in the row "A" to "G" will not change the output any more. But nevertheless this is not a big problem at all - hardly any program operates on that. 4.4 JOYSTICK-EMULATION The emulator has four joystick-emulations built in: Kempston-Joystick (using IN 31), the two Interface-2 joysticks (which simulate keypresses of "1" to "5" and "6" to "0" resp.) and Cursor joystick. Which joystick is emulated can be selected in the setup-program (Emulating more than one joystick to the same time has been dropped cause of problems with some programs, which get confused). When asked for the joystick-type in programs you should use KEMPSTON or Sinclair (Interface-2) type. Some very old programs will often support only the Cursor-keys, so you could use Cursor joystick in this case. 4.5 SOUND-EMULATION Sound is generated on the Spectrum by aid of a buzzer, which through rapidly turning on and off again is made to "sound" the desired frequency. The emulator does quite the same, but using the poor Atari soundchip (which really deserves better) volume on to maximum and off again. But as the emulator is not running at the correct speed the tone will most often sound too deep. It will fit better the more the emulator runs at 100% speed (on the TT). Using the function-key F7 you change between this modes: - Each OUT will go to the Atari soundchip - Interruptdriven polling of the sound - Turn off sound-emulation completly The interruptdriven method gives more constant, but less good results. But using it with a high scan-rate will slow down the emultor (which may be used as "brake" on very mast machines - but which??). 4.6 TAPE-SUPPORT-EMULATION The old Speccy was able to load or save its programs from or to a cassette-recorder onto standard music-tapes. The emulator supports this operations but automatically directs the data to floppy or harddisk. Some differences arise thereout: Filenames on the Spectrum may have up to 10 characters wheras TOS uses 8 charactes plus 3 characters "extension". So its best to restrict yourself to 8 characters for Spectrum filenames or use filenames with a period which in total are not more than 10 characters long. Also loading of the "next" file that comes on tape, using LOAD "", is certainly not possible for disks. In this case a special fileselector appears and the required file can be selected. This fileselector also shows information about the files, namely filesize (as seen for the Spectrum) and startadress (either in memory or startline of a BASIC-program) - something the author always missed on the Spectrum. So always when executing a LOAD "" this fileselector will be shown. It is a plain VT52-application, no GEM, having the advantage of ease of use. Use the cursor keys and "Enter" to select a file. There are seperate screens for each filetype of the Spectrum (Program, Code, Number arrays, Character arrays). So for example LOAD "" CODE will bring up the one for Code. The information is kept in a file "INHALT.INF" in the current directory. If no such file is found, a "scan" for loadable Spectrum-Files will start, which may take some time because each file in the directory must be examined. But normally you will not alter files too often. To start the "scan" manually you can press "F2". If using floppy-disks remove the write-protection-tab, as the file "INHALT.INF" is created. As there is an "INHALT.INF" for each directory you are in, changing to another directory will bring up the need to read the corresponding "INHALT.INF". This is done with "F1" after changing the path in the upper screenline. Using the tape-interface out of machinecode-programs will in most cases not enable the emulator to find out the filename wanted. So it tries to present all corresponding files (from the list), hoping that sooner or later the correct one is reached. You may interrupt pressing the "Alternate"-key, which will bring up the fileselector. Saving out of machincode-programs will normally not work. Pressing BREAK (key F10) during Load- or Save-operations is possible anytime as long as the application does not intercept this. FORMAT OF FILES The emulator builds its files exactly like the Spectrum does, first 17 bytes header, then data. Header and data are kept in a single file together. The header starts from the begin of the file and has the same layout as the tape-header: Byte 0 Typ of file: 0=BASIC, 1=Num.Array, 2=Char.Array, 3=Bytes Byte 1 - Byte 10 hold program-name, padded with blanks Byte 11 and Byte 12: Number of bytes in datablock (lo-hi) Byte 13 and Byte 14: Load-adress in memory or starting line in BASIC Byte 15 and Byte 16: BASIC only: Program-length minus Variables-length The program name matches the one you enter with the LOAD-command. The whole file will be created with this name as TOS-file. But remember that Spectrum filenames are case-sensitive i.e. SAVE "NAME" and SAVE "name" will create the same TOS-file, but you will still have to enter LOAD "NAME" or LOAD "name" to laod it! 4.7 INTERFACE-1 EMULATION The "Interface-1" is an addition-board from Sinclair, which adds a RS232 serial-interface and a network-interface to the Spectrum and also allows the connection of "Microdrives" as mass-storage-device (I will not comment them, because who doesn't know already, needs not know nowadays...). The network-interface is NOT emulated. The RS32-interface is supported, so you can receive files from an original Spectrum or send files to it. Also you could use it to send a listing of ZX-BASIC to a printer attached the the Atari. In the setup you can decide where the output will go: Atari RS232- and/or Atari Centronics-port. The BREAK-key can be used as normally to cancel the output. When receiving data always the serial port is used. RS232-settings are taken from the system i.e. the emulator doesn't change any RS232-parameters even when using the command FORMAT #"b";baudrate. I have received files from my Spectrum at 9600 baud without any problems, but the other direction did not work as well. I could not determine the exact reason for this (mainly because I have no real need to transfer data TO the Spectrum), but it seems that it is rather due to the cable-connections I use or lies within the Atari handling of the serial port. Anyhow the emulator uses only BIOS for operating the serial port and no own routines at all, so there will certainly be a way to make it work if you experiment a little. It must be noted, that emulation speed is notably slower when "activating" the Interface-1, because additional trap-code has to be executed and also the ROM-paging be performed (by copying 8192 bytes around in memory often several times in a single BASIC-instruction). You should use it only when really neccessary and turn it off otherwise. 4.8 MICRODRIVE EMULATION These cute little things are also emulated, but only for compatability to some existing programs, because it will not make too much sense to store own programs on it - emulator tapefiles are faster! The emulation is (like the RS232-emulation) based not on I/O-level, but on trapping the program-counter at certain rom-adresses. This means that programs using the official ways of access (either from BASIC or through the so called "hook"-codes) will work, but others that try to read or write the interface-1 ports will fail. But even in this case you could try to patch the offending code (for example: Art Studio has an incompatible routine for looking if a cartridge is present and will not load its overlay-files because it always reads a "not present" -dummying this routine makes everything work immedeatly) using the built-in Z80-monitor. Microdrives are implemented simply as files that are structured like a microdrive- cartridge. The names of these files (up to eight microdrives are supported) can be defined with the setup-program, numbers "1" to "8" are appended by the emulator automatically. If you really use microdrives with the emulator you will probably need to be able to change cartridges in a one drive. You could write yourself some program that allows to rename or copy these microdrive-files in an intellegible way and integrate it into the emulator. See chapter 8 if you want to know more about that. So - whoever wants to experience the feeling of satisfaction when the syntax-checker accepts commands like LOAD *"m";1;"name" should do the following: - Call up the setup-program and click the "MORE OPTIONS" button. Set the microdrive-path and filename for a microdrive in the field "MD-Path". Then click the button "CREATE.." and select the drives you want to use. The files will be created and (if wished) be "formatted" at the same time. - In the first setup-dialog mark the switch "IF1". Save settings. - Start the emulator. You should see the message "IF1 active!" for a short time in the top left corner. - You are now ready to use all microdrive- commands, as there are: FORMAT ( z.B. FORMAT "m";1;"cartr_1" ) CAT ( z.B. CAT 1) SAVE ( z.B. SAVE *"m";1;"program" LINE 1 ) LOAD ( z.B. LOAD *"m";1;"program" ) ERASE ( z.B. ERASE "m";1;"program" ) OPEN ( z.B. OPEN #4;"m";1;"seqfile" ) CLOSE ( z.B. CLOSE #4 ) INPUT ( z.B. INPUT #4;name$ ) PRINT ( z.B. PRINT #4;name$ ) 4.9 SUMMARY OF EMULATION RESTRICTIONS Let me finally give a short summary of all the above noted restrictions and minor deviations from perfect emulation. - The Z80 status-flags Half-Carry (H) and Subtraction (N) not emulated - R-register isn't implemented exactly, only basically - Screen-emulation does not trap all opcodes possible - Keyboard cannot be emulated exactly because of Atari firmware - Interface-1 is emulted not on hardware-level, only functionally - Timing and speed-behaviour (relative and absolute) not cared for - Undocumented behaviour of the "unused" flags is not emulated - Unused ports are not implemented correctly 5. SNAPSHOT-SUPPORT 5.1. THE STANDARD SNAPSHOT Well, it's time to confess: there are other Spectrum-emulators too. One of the first was written for the Commodore Amiga and it used a way for loading and saving Spectrum programs called SNApshot. It appears that it came from one of those "freezer" add-on's, which were brought on the market in later years of the Spectrum, enabling the user to break into any program by NMI-interrupt and dump the whole ram-contents to disk or microdrive. This was called "snapshot", because it actually made a snap of the momentary state of the Spectrum with all its Z80-register, status-flags and ram-contents, so that the saved program could afterwards be loaded again and continued from exactly the point, where it was saved. Another emulator for the PC, called "jpp", also used this format later, so it may be said that it is a sort of "standard" under Spectrum-emulators (sounds really crazy!). Therefore this emulator also supports snapshots. THE BUILT-IN SNAPSHOT-SUPPORT SCREEN In order not to let the emulator grow too large (so that users with 1 Mb only also can use it), the abilities of the internal user-interface for loading and saving snapshots are quite basically. All those with more ram should use the external program "ZXF", offering much more comfort (see chapter 8). But now I will discuss the internal function: Pressing the key "F5" anytime takes you to the "SNA-Support"-screen. It allows to input a filename of a snapshot file, that shall be loaded or saved to. If you enter just a filename (with no path) the current snapshot-path (as declared with the setup-program) will be used, otherwise the path entered is taken. After the name has been typed you have to press "Return" to load the file or press "F5" again to save the current program in memory to this file. If you enter no name (leave the field empty) the default-name "temp.sna" will be used. This has the advantage, that you can very quickly save a current game (for example to preserve a completed level) by hitting "F5" twice. To load it back again you just have to press "F5" and "Return". LOADING SNAPSHOTS FROM THE TAPE-FILESELECTOR I built in a recognition of snapshot files into the tape-selector lately. They will be shown within the program-type-files and you see them as files with length 49179 bytes. You can load them, entering the LOAD "" command just like a tapefile. As a feature the snapshot will not be run immedeatly but a branch to the internal Z80-monitor is taken after loading, so that you can inspect it or make patches. Just hit "Esc" to run it. 5.2 THE EXTENDED SNAPSHOT-FORMAT I used the opportunity to create an own snapshot-format, which I called "SNX"-format (SNApshot eXtended). It offers the advantage that it can store the current emulator-settings too, so that you can run each program with the best choice of settings right away. Also it does some compression to the data, in contrary to the standard snapshot, which always uses 49152 bytes, independend of how large the program really is. It's a very simple method of compaction, but efficient with small programs and quick to perform. If you want better compression you could write your own load- and save-programs by using the emulators ability to "connect" with external programs (see chapter 8). Snapshots in the "standard" format can be interchanged with other Spectrum-emulators with ease. 5.3 AUTO-STARTING A SNAPSHOT-FILE At the start of the emulator two things are checked: If there exists a snapshot "AUTO.SNA" (which can also be in extended format, but the extension has to be ".SNA") it will be executed immedeatly after the emulator has been started (or after a reset, if you like). This could be used to run a menu-program or some extension of the operating-system automatically. The check is done only, when the emulator-switch "AUTO" has been set in the configuration. If you pass a filename to the emulator by command-line, this file will be interpreted as snapshot and loaded immediatly. This makes it possible to declare the emulator as application for snapshot-files to the desktop. Clicking on a snapshot-file will then activate the emulator and execute the Spectrum-program. So, what about designing an icon for "Jet-Set-Willy" and try it? 5.4 CONVERSION PROGAMS FOR SNAPSHOTS In order to convert easily between the various formats three programs are supplied with this version of the emulator (in the SNA-folder): SNA2SNX.PRG Will convert a standard snapshot to the compressed SNX- format of this emulator. If it finds SPECCI.DAT then it will use the current settings of switches contained in it, otherwise it uses default values. SNX2SNA.PRG Converts and extended snapshot back to a normal one. The extended information is lost of course. Z802SNX.PRG Converts snapshots of one popular Spectrum emulator for MS-DOS PC's into SNX-snapshots for this emulator. It tries to translate as much information as possible from the Z80-settings (joystick emulation, double interrupt frequency, Interface-1 emulation, ...). All of this programs can handle the passing of a snapshot filename through the command line. If non is supplied you are prompted for a file to convert. 6. THE IN-BUILT Z80-MONITOR One keypress away - "Esc" by default - there slumbers a Z80-disassembler/ monitor waiting to be woken. It makes it fairly easy to sniffle into programs, search for byte-sequences and do patches. Its operation is made simple by using a "hot-keyboard"-technique. This means it will not be neccessary to press "Return" in most cases, but the monitor reacts instantly to keys. Numbers have to be input in hexadecimal throughout the program, after entering sufficient digits the input will be accepted automatically. Each command can be aborted by pressing "Esc" as long as its input is not finished. Numbers displayed will also be in Hex with the exception of ix/iy-offsets like 'ld a,(ix+11)', which are in decimal and binary operations (AND,OR,XOR) which will be in binary (dual) format (i.e. 'xor a,%10000000'). Monitor-Commands in Detail: --------------------------- ESC during command-input: cancels the command ESC when the '>'-prompt is showing: Quit the monitor WITHOUT setting of any changed registers (see 'X'-command). H Help. Shows a brief summary of commands. A adr Set start-adress for D,L,M,F-commands. D Disassemble from adr L Hexdump-Listing from adr. ZX-Codes are shown righthand. SPACE,Return Continue D or L, one line at each keypress. M B Modify memory from adr byte-wise. M W Modify memory from adr word-wise ($1234 will be stored as $3412 !) M A Modify memory from adr in ascii (text-input). M C Modify memory from adr with a constant value: Pressing <Return> will use the constant, otherwise the input value. F B v1 v2 .. Find a sequence of bytes starting search from adr. After 7 occurences a new line is used a <Return> must be pressed to continue or <ESC> to stop. F A text Find a text-string. R Show Z80-registers. X Change registers. The registers are displayed. Then each register can be changed in turn. Pressing <Return> will leave the current value and advance to the next register. <ESC> leaves the mask if no more registers shall be changed. When entering interrupt-mode only values 0 to 2 are allowed amd for the status '+' or '-'. G <adr> Go on emulation starting at adr. if adr is not specified, the current PC will be taken. U adr Go until adr. A breakpoint is set at adr and a G-command is executed. When the breakpoint is reached the monitor will show again. Should the program not encounter the breakpoint, it will be cleared automatically when the monitor is entered again. I Single-step one Z80 instruction (current PC). N H/D number Number conversion decimal <-> hexadecimal. Z Show the current ZX-screen. Press 'Z' again to return. S <name> Saves the Zx-screen in Spectrum-format (17 bytes header + 6912 bytes screen-data) under 'name'. If 'name' is not specified, the dafault 'zxsc' is used. If the name does not contain a path, saving will go to the current program-path. The saved screen can be laoded then from the emulator with LOAD "name". The external program 'ZX_BILD.PRG' allows to load ZX-screens and save them in Doodle- or Degas-format (see chapter 8.6). V Reset start-adress of disassembly to PC. 7. PERSONAL CONFIGURATION Using the program "SPSETUP.PRG" the emulator can be configured to the individual taste. The following settings may be done: Use other ROM-file ================== The button "ROM" must be activated. The line above contains the path to the ROM-file that shall be used. Clicking on this line will bring up the fileselector and a ROM-file can be selected. It must be a file of either 16384 bytes (main rom) or 16384+8192 bytes (main rom + Interface-1 rom) length. Define special keys and attach them to programs =============================================== The keys "Escape", "F5", "F8", "Home", "Help" and "Insert" can be routed to perform own functions. This im implemented in that way, that any other program can be started when pressing on of these keys. As described in chapter 8 there are quite complex ways to interact with the emulator. It is also possible to install this external programs resident in memory, so reloading will not be neccessary and one gets the impression of an in-built emulator-function. After clicking on the button "Config" a dialogue appears, where the keys can be attached to programs. The check-box on the left side of the program-name activates or de-activates the corresponding program. The name has to be keyed in manually, because a mouse-click on the name will open another box, where some settings for this program can be made: - Restore Colour-palette before activating the program: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: The system-palette as before the start of the emulator will during emulation be changed to the Spectrum "palette". This option decides whether the saved palette shall be restored before calling the program or if shall use the Spectrum colours. - Run program in ZX-mode i.e. with active emulator: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: During emulation some system-vectors are changed ore de- activated. Especially the keyboard-routine and the timers B and C are changed. Therefore this option should normally be disabled, but special programs could use it to interact more closely with the emulator. - Load program resident into memory: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: As already mentioned it is possible to load user-programs resident in memory. Use this switch to do it. Especially for floppy-disk users this may be of advantage. But programs must be designed to work in this mode, for example they must take care if their data (resources) are already initialized. - Use return-value from program: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Description: This switch tells the emulator to interpret the return of the program. Programs that supply a return-value must of course do it according to the requirements of the emulator. See appendix for a description. The check-boxes on the right side are used only for the "Shell-Mode" of the emulator, which means when it is called from a special Shell-Program. If a box for a key is checked, the emulator will return to the shell-program. All other settings have no meaning in this mode, but the Shell-Program has to decide what to do, when the emulator returns with key x. One could imagine the emulator to be only a subroutine to the shell, that by the way emulates a ZX-Spectrum computer and returns with defined values. Read the appendix for a more detailed description. Define four different Sets of configurations ============================================ For easy access of different emulator-settings there are four sets you can define and then switch in runtime with a keypress (default: UNDO). A set is selected by clicking at its number in the title. The one currently active is inverted. Description of the emulator-switches: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ IF1 Turns on interface-1 emulation. From version 2.07 on it is possible to change this switch in runtime. ULA Turns on the screen-emulation in the 50Hz-timesclice. This is mainly to reduce flickering of sprites with some games (for example Matchpoint). FLASH Turn flash-emulation on. If it is turned off, flash will only invert the character. Turn it off, whenever possible, if you have a slow machine. ATTRIBUTES Turns on emulation of the attribute-file. Should normally be on. If turned off only the pixel-data will be displayed. It is sometimes quite intersting to see, how the attributes are used to hide things on the screen, that are actually there. R-REGISTER Emulate (Simulate would be more accurate) the R-register. If turned off, the value of the R-register is left constant. This might be usefull sometimes, because programs then always will request the same pass-words if they rely on the changing value of the R-register. Turning it off, will gain no speed! X-SNA Turns on saving in extended format (SNX-format). If turned off saving will be done in the standard format (SNA-format). 100 INT/S Doubles the emulated interrupt-frequency. This often brings a much better control of the keyboard, especially on slow ST's. CHANGE Z-Y Who doesn't like, that the Z- and Y-keys (at least on a german keyboard) are different as on the Spectrum, can cure it here. RS232-OUTPUT Sets where RS232-output from the Interface-1 emulation will go to: serial port, parallel port, both or none. AUTO-SNA If set, the emulator will automatically try to load a snapshot named "AUTO.SNA" after start and/or an reset. SOUND Set method of sound-emulation (see chapter 4.5). If you set to "Interrupt" you can also change the scan-rate by clicking at the box named "INTERR.". BORDER Same as SOUND, but for the display of the border. Z80-ILLEGAL Sets the action, the emulator shall take, when encountering an illegal Z80-opcode. EMU-ERROR Sets the action, when an emulation-error occurs (680xx adress- or bus-error). This should not happen anyway. Setting the color-palette ========================= Under "MORE OPTIONS" you can enter your own values for the low-resolution colour-palette, in case you are not satisfied with the given ones. Clicking at the field "Color palette" a menu with some more or less usefull options assist you in experimenting. It's best to try from the running emulator, so you can see the effects immedeatly when returning to it. In high resolution a click in this field will invert the screen (toggle white/black). Define paths for Tapefiles, Snapshots and Microdrives ===================================================== In the same dialogue also all filepaths can be selected. You can either type them in or click on the fields and then use the fileselector. Set some hardware-values of the Spectrum ======================================== Also under "MORE OPTIONS" you can set the value that the Spectrum generates for the Interrupt-Mode-2 hardware-vector. The default $ff should in most cases be correct, but I made this value user-definable nevertheless. Different series of Spectrum-issues had a small incompatabilty with the level of Bit 6, the "EAR-bit" or input-value from the tape-interface. As the tape-interface didn't rely on the absolute value "0" or "1" but only on the change of state, this normally made no difference, but when reading the keyboard also the EAR-bit is read and some older programs do not mask it out when interpreting the key-value read. If the keyboard doesn't seem to work with some older program, try to change the value for the EAR-bit to "1". Last of all the type of joystick to be emulated can be set. Most Spectrum programs will have an option for "KEMPSTON"-joystick, which is emulated by default, the others will certainly offer an "Interface-2"-option. As all these values are stored in SNX-snapshots, you will have to change them only once for each program. PLEASE NOTE =========== Alle Settings in the "MORE OPTIONS" dialogue are only for the current active set. This has the advantage, that you can also toggle the colour-palette or the emulator-filepaths with a keypress, but requires on the other hand, that you do this settings for each other set as well. Other things the program "SPSETUP" can do: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The program is "runtime"-able i.e. you can define it as an external program itself, which gets executed by pressing (for example) "Insert" when the emulator is running. You must set the following parameters in it's configuration-box: Atari-mode (i.e. NOT Spectrum-mode), WITH return-value, the other options as you like. When it is called from the emulator it offers some other buttons, which replace the ROM-buttons: Generate NMI, Generate RESET, Load and Save Snapshots, Screen, any part of the memory and Quit the emulator. Also a button "SAVE SETS" in the lower part of the dialogue allows to save the whole settings of the emulator (in ram) permanently to the emulator-file "SPECCI.DAT". This is usefull when you are experimenting with different settings and want to preserve them at last, when satisfied. The title-line will show an additional set "T", which resembles the work-set, a copy of the current active set. Any changes done in the "T"-set will have no lasting effect, only till loading an SNX-snapshot or toggling sets with the defined toggle-key. So it can be used whenever you do not want to corrupt your sets. 8. THE ADD-ON PROGRAMS 8.1 GENERAL REMARKS TO THE INTEGRATION OF EXTERNAL PROGRAMS Most programs presented here are written in GFA-BASIC, which is my declared favourite-language besides assembler. A "quantum-leap" in comfort was the discovery of how to make programs resident in memory and how to start them from there as often as needed. A initial problem with the compiled GFA-programs could be overcome using a patch-procedure, which is incorporated into the program and executed at the first resident activation, so following executions will work. 8.2 KEYWORDS.PRG Ends the pity with searching for that dreaded keyword in ZX-BASIC. This program is thought to serve as resident replacement of (for example) the HELP-function. All characters and BASIC-token of the Spectrum are listed and can be scrolled through using the cursor-keys. Pressing "Return" will pass the character under the cursor to the emulator (it will actually be patched into the system variable LAST_K). The "F1"-key toggles the display sorting alphabetically or by code. "Esc" leaves without overtaking the character. Configuration in Setup: ~~~~~~~~~~~~~~~~~~~~~~~ Atari-Mode, WITHOUT return-value, resident & palette as you like You can start the program also from desktop (display only, of course). 8.3 SPSHELL.PRG Emulator-shell, which allows to get all of the add-on-programs under a GEM-menu and to use the accessories from out of the emulator. It needs the file "SPSETUP.INF", that contains the list of programs and parameters for them. See also appendix. 8.4 ZXF.PRG A replacement for the minimal-art fileselector for snapshots built into the emulator. Therefore it should be put onto the key "F5". If you make it resident too, you will think it is a natural part of the emulator-program. When called it will display all snapshot-files in the current directory. You will also see the other available disk-drives and directories on the current drive and are allowed to change to them. Using the cursor-keys, Space or Tab you can browse through the list and select a file or you can input a new filename for saving. When entering a filename the display will be updated with each key, to show all matching files. Pressing "Return" will load the snapshot, pressing "F5" will save to it. You do not need to enter an extension, this will be done automatically. If you want to create a file without an extension put a period at the end of the filename. There will be a warning if you try to overwrite an existing file. "HELP" will start a "scan" for for snapshot-files, that have not been recognised by their extension or filelength. "UNDO" will switch to full-screen display to show more files at once. "Insert" copies the name under the cursor to the input-line, "Clr" blanks the input-line. Escape leaves without action to the emulator. When started from the desktop ZXF allows to run the emulator automatically with a selected snapshot - a very convenient way to start the emulator. Configuration in Setup: ~~~~~~~~~~~~~~~~~~~~~~~ Atari-Mode, WITH return-value, resident & palette as you like. 8.5 ZX_TAST.PRG A nice display of the original ZX-keyboard. This version shows a fairly realistic picture at least in color-mode, but splitted into four parts there. It's contained in a GEM resource-file, that can be worked on using a resource-editor. 8.6 ZX_BILD.PRG A program to display ZX-screens (filelength 6912 bytes) in 640x400/2 and 320x200/16. Clicking with the mouse will bring up a menu that allows to save them in Degas- or Doodle-format. This program is not worked out completly - you could use it as a base for own developments. 8.7 ZXH.PRG This is the help-function of version 1.2, now as external program. It shows the ZX-keyboard - according to the screen-resolution maybe in several parts that can be moved through using the "HELP"-key. Any other key will end it. If resident in memory and used in ZX-mode it will pass the key to the emulator. Configuration in Setup: ~~~~~~~~~~~~~~~~~~~~~~~ resident, Atari or ZX-mode, WITHOUT return, do NOT restore palette. 8.8 ZXS.PRG A program to do the same job as the inbuilt function for toggling sets. It's single purpose is to free the "UNDO"-key for another function. Then you could assign this program to the key you would like to do switching of sets. Configuration in Setup: ~~~~~~~~~~~~~~~~~~~~~~~ resident, Atari-Mode, WITHOUT return-value, do NOT restore palette. 8.9 ZXM.PRG, ZXU.PRG This are sample-programs, to show how (easy) to interact with the emulator from external programs. Of course a profound knowledge of the ZX-Spectrum will not be a hindrance. Then there will be few limits for what can be done. "ZXU.GFA" will simulate a LOAD "" input to the emulator, to call the tape-fileselector with a single keypress. It does so, by changing some of the Spectrums system-variables to fool the Spectrum. "ZXM.GFA" demonstrates, how to obtain the values of the Z80-registers and how to change them (for doing a reset in this case). "ZXU.PRG" will be of some beneficial effect, whilst "ZXM.PRG" shall definitly only be an example, that can be studied. ZXU.PRG: resident, WITHOUT return, Atari-Mode, do NOT restore palette ZXM.PRG: resident, WITHOUT return, Atari-Mode, palette as you like 9. THE FINAL FRONTIER This documentation has grown somewhat lenghty, I fear. I only hope, not too dull to read. The appendix will give information to the one interested in writing own stuff around this emulator. There remain just a few points to mention: - How to get Spectrum-programs over to the emulator ? Well, beeing aquipped with a working Spectrum and Interface-1, it will be an easy job to transfer unprotected programs using a suitable cable. The format of the emulators "Tape"-files is identical to that of the Spectrum anyway. Ensure that the system-parameters for the RS232 interface are set to 9600 baud, no parity, 1 stopbit and RTS/CTS handshake and start the emulator with Interface-1 emulation turned on. Then you could receive programs or machine-code from the connected Spectrum by simply typing LOAD *b;"" or LOAD *b;"" CODE on the emulator and a corresponding SAVE *b;"name" or SAVE *b;"name" CODE start,len on the Spectrum. Once in memory save them to disk in the normal way. Copy-protected software will be hard to transfer for the non-hacker. The simplest way might be a modified Spectrum-ROM, which could be programmed to dump the whole ram-contents to the Atari when triggering an NMI on the Spectrum. I personally use this method, so I could give helping information if someone is interested in. Someone in England has developed a program, that can read original Spectrum-tapes from a tape-recorder connected to the Atari by a special cable on the printer-port. Though I have this program, I didn't try it, but it is claimed to work well. Of course only on unprotected tapes and only with 8 MHz Ataris (because of the timing-loops). Another way to get hold of programs in snapshot-format may be the "emulator"-section of various mailboxes. As there are at least three other Spectrum-emulators (one for Amiga and two for the PC) using the snapshot-format, you could load programs for them into this emulator too. Finally the author also has about 300 programs you could obtain. Send SAE for a list if interested. This leads to the next topic: - Queries, Questions and problem-curing: I am willing to answer any questions brought to my ears, BUT ONLY, if there arise no costs for me. This emulator is Public-Domain, so I cannot do a service-job for it. At least a compensation for postage and disks is expected. An additional "honouring" of time and work needed will be appreciated. I am also willing (in principle) to give away the emulator source-code, but not just for fun, only when beeing convinced that it is in "good" hands. Of course plain and honest notes of approbation to this program are welcome in any circumstance - that's what the author of a Public-Domain program is always (and only) hoping for (as a return to his laborous work). Last of all, some remarks to a topic I would rather like to byepass - the problematic chapter "copyright": The emulator contains a copy of the Spectrum rom and the Interface-1 rom. Certainly, it would have been the easiest way for me, to leave it to the user to get hold of these files and patch them into the emulator. But firstly it seemed unacceptable to assume, everybody interested in this emulator would have the means and the knowledge to obtain and transfer the rom-files to the Atari, secondly I do not distribute the rom-files on their own and this emulator is not a commercial product also. I think the age of the ZX-Spectrum is too long ago, as it could be an real infringement of copyright, in the contrary: it should be of interest to those in possession of the copyright for the Spectrum-rom (Armstrad company, I presume) to hold high the remniscence of the Spectrum. A person starting a Spectrum-emulator nowadays must be really a "nostalgic", and I didn't want to cut down this romantic feelings early with problems, how to get this or that file. So: Have fun and enjoy the emulator! Christian Gandler Paletzgasse 17/3/14 1160 Wien / Vienna ÖSTERREICH / AUSTRIA LONG LIVE SPECCI ! ( & ATARI !) Vienna, 25.10.93 ---------------------------------------------------------------------------- 10. APPENDIX A: SUMMARY OF EMULATOR-KEYS =========================== ST-Key(s) as pressed on ZX-SPECTRUM Comment ----------------------------------------------------------------------- Control Caps-Shift+Symbol-Shift EXTENDED-MODE Alternate,RShift Symbol-Shift for the red symbols F1 Caps-Shift+1 EDIT (Edit BASIC-line) F2,CapsLock Caps-Shift+2 CAPS LOCK F3,Tab Caps-Shift+3 TRUE VIDEO F4 Caps-Shift+4 INVERSE VIDEO Cursor left Caps-Shift+5 Move cursor left Cursor down Caps-Shift+6 Move cursor down Cursor up Caps-Shift+7 Move cursor up Cursor rechts Caps-Shift+8 Move cursor right F9 Caps-Shift+9 GRAPHICS-MODE Delete,BS Caps-Shift+0 DELETE F10 Caps-Shift+Space BREAK (Stop Program) < Symbol-Shift+O ; (Semicolon) ~ Symbol-Shift+P " (Quote) ß Symbol-Shift+C ? (Questionmark) ä Symbol-Shift+L = (Equates) ö Symbol-Shift+Z : (Colon) ü Symbol-Shift+2 @ (Absatz) Alternate-4 Symbol-Shift+4 $ (Dollar) Alternate-5 Symbol-Shift+5 % (Percent) Control-LShift-P EXTENDED-MODE-Shift-P © (Copyright) Emulator-Controlkeys (Default-Layout) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Key Action ----------------------------------------------------------------------- F5 Load or save Snapshot-File F6 Reset the Z80 Shift-F6 Quit the emulator Alternate-F6 Trigger NMI (Non-Maskable-Interrupt) F7 Toggle Sound-Mode F8 Return to Shell (in Shell-Mode) Esc Call Z80-Monitor/Disassembler Help Show Help-Screen Insert Break emulation, shows menu (Alert/Setup) Undo Switch emulation-sets Home (not used) B: SOME ZX-SPECTRUM INTERNALS ============================= memory layout (adressrange: 0-65535) -------------------------------------------------------------------------- 00000-16383 ROM 16384-22527 Display file (pixel data) 22528-23295 Attribut file (Colours and attributes per character) 23296-23551 Printer buffer (used as temporary memory often) 23552-23733 System variables (see below for examples) 23734-23754 Systemspace for I/O 23755- BASIC program memory + variables In high memory lie areas of systemspace, stacks and user-graphics. Interesting system variables: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Words are stored in low-high format!) adress length name description -------------------------------------------------------------------------- 23560 1 LAST_K Newly pressed key (if bit 5 of FLAGS is set) 23561 1 REPDEL Time in 1/50 seconds for key to repeat 23562 1 REPPER Delay in 1/50 seconds between key repeats 23606 2 CHARS Pointer to character set - 256. Can be patched to install own font. 23609 1 PIP Lenght of keyboard click (try for example 10) 23608 1 RASP Length of warning buzz. 23610 1 ERR_NR BASIC error number - 1. Starts off with 255 (-1). Register IY always points to this adress in BASIC 23611 1 FLAGS Flags controlling the BASIC system. 23613 2 ERR_SP Adress of item on stack used as error return for BASIC errors. 23624 1 BORDCR Border colour * 8; also contains the attributes for the lower part of screen( input area). 23627 2 VARS Points to variables area of BASIC program 23635 2 PROG Points to program area of BASIC (normally 23755) 23559 1 DF_SZ Number of lines in input area of screen. An often used simple method to crash the Spectrum when BREAKing into program: Set DF_SZ to 0. 23672 3 FRAMES 3 byte counter (low-high). Every 20 ms incremented 23692 1 SCRCT Number of scrolls of screen before the question "scroll?" is shown. 23728 2 NMI-ADD Adress to which NMI jumps to. This does not work in the original ROM, but it suffices to patch ROM on adress $006D from $20 to $28 to make it work. 23730 2 RAMTOP Adress of the last memory byte for BASIC 23732 2 P-RAMT Adress of the last physical byte in memory Interesting system calls: ~~~~~~~~~~~~~~~~~~~~~~~~~ RANDOMIZE USR 3280 Scroll up the screen by one line PRINT 65536-USR 7962 Show free memory RANDOMIZE USR 0 Soft reset of the Spectrum C: INFORMATION FOR PROGRAMMERS ============================== THE SNAPSHOT FORMAT ------------------- #Byte Contents Comment -------------------------------------------------------------------- 0 I register 1 L' register 2 H' register 3 E' register 4 D' register 5 C' register 6 B' register 7 F' register 8 A' register 9 L register 10 H register 11 E register 12 D register 13 C register 14 B register 15 IY lower byte 16 IY upper byte 17 IX lower byte 18 IX upper byte 19 Bit 2 contains IFF2 other bits are irrelevant 20 R register 21 Flag register 22 A register 23 SP lower byte 24 SP upper byte 25 Interrupt mode 0, 1 or 2 26 Border colour 0..7 27..49178 48 kB RAM dump After loading the registers the program must be started by executing a RETN instruction i.e. the program counter is on the stack (in RAM dump). THE EXTENDED SNAPSHOT FORMAT ---------------------------- #Byte Contents Comment -------------------------------------------------------------------- 0..3 "XSNA" Identification for emulator 4,5 Header lenght #Bytes in following header 6..32 Register as in SNA standard format 33..42 Emulator switches if1sw - im2hw of setup area ab 43: 2 Bytes count Number of bytes in block ***) 1 Byte Flag Mark if "compressed" block either (Flag = $ff): 1 Byte Fill value Byte to be repeated count times or (Flag = 0): Count bytes data without compression ***) Optimisation, if number of bytes in block <= 16 !!! The first byte of count contains a value >= $E0, that is to interpret in the following way: the lower nibble contains the byte count - 1, the upper nibble is $E for an uncompressed block, $F für a compressed block. The second count byte and the flag byte are not present in this case ! The blocks from byte 43 on are repeated for the whole ram dump. EMULATOR PATCH AREA FOR SPECTRUM ROM ------------------------------------ The Spectrum ROM is patched into the emulator file "SPECCI.DAT" from offset 34 on (length: 16384 bytes). Immedeatly behind follow the 8192 bytes for the interface-1 rom. HOW TO INSTALL AN OWN SCREEN DRIVER ----------------------------------- During initialization of the emulator after it has been started, it looks for a file named "ZXVID.TRB" in the emulator directory. If it is present, it will be interpreted as an external screen driver and loaded into memory. "ZXVID.TRB" has to be an executable program (just renamed) and also has to be completey position-independant i.e. must only use PC-relative adressing modes. It must have a header of the following scheme: { 28 bytes program header of an executable file } vdrv_hdr equ * bra.w v_install ; Installation +0 ds.l 1 ; De-Installation +4 ds.l 1 ; Screenbyte with attribute +8 ds.l 1 ; Screenbyte without attr. +12 ds.l 1 ; BORDER display +16 ds.l 1 ; Display of whole screen +20 ds.l 1 ; VBL task (during LOADing) +24 The first longword contains a branch to an installation procedure. This procedure will receive the following values from the emulator: a1 .... Pointer to ZX-screen within emulator ram (= data to display) a0 .... Pointer to a buffer, that the driver my freely use d0 .... Length of this buffer a4 .... Pointer to emulator variables beeing needed for display: 0(a4) contains a switch for attribute display (0=no) 1(a4) contains a switch for FLASH display (0=no) 2(a4) contains the momentary FLASH state (0=normal, $ff=invers) The installation routine has to save these values, do any neccessary initializations to it's data. Also it must complete the header by filling in the adresses of the procedures doing the appropriate tasks (display single screen byte with/without attribute, ...). A return value must be put into the register d0.w: 0 = ok, everything installed correctly 1 = wrong screen resolution All other values signal other errors Return to the emulator is done with a RTS instruction. No register must be saved by the initialization procedure. The runtime procedures must preserve all registers !!! An example-driver (for ST medium resolution, which of course is not too useful) is included as source file (MIDRES.S), where you could study the implementation of the above description in detail. START OF EMULATOR THROUGH EMULATOR SHELL ---------------------------------------- If the emulator finds a string "/s" in its command line, it tries to start a shell program. This shell program will then be able to control the emulator by using it just like a subroutine. By this way it would be possible to build a shell of any complexity around the emulator, for example an own desktop or a GEM window on the (Multi-TOS-)desktop controlling the emulator. The string "/s" can optionally be followed by the (path)name of the shell program, for example "/sG:\SPECCI\SPSHELL.PRG". If none is specified the name entered for the program for key "F8" in the configuration will be used. The supplied program "SPSHELL.PRG" is a good example, how such a shell program works. If called from the desktop, it enters the string "/s" followed by its own name, which it request through the function SHEL_READ, in a commandline and passes it to the emulator program via SHEL_WRITE. Then it ends itself. SHEL_WRITE will now start the emulator automatically, it will find the string "/sSPSHELL.PRG" in its commandline and will start the shell program on its own again. The shell program now realizes the situation and now starts its designed job as interface to the emulator. This whole procedure may sound somewhat irritating, but it functions very well. COMMUNICATION WITH EXTERNAL PROGRAMS ------------------------------------ The basis for communication with the emulator is the knowledge of certain adresses within the emulator program, where various informations are kept. These adresses will be supplied the external program by the commandline. #Byte Contents Comment -------------------------------------------------------------------- 0 '©' Special identification (called from emulator) 1 64 Number of bytes following 2..9 HHHHHHHH Adress setup data 10..17 HHHHHHHH Adress Z80 adress space within Atari 18..25 HHHHHHHH Adress emulator variables 26..33 HHHHHHHH Adress Atari screen buffer 34..41 HHHHHHHH Adress for return value 42..49 0000000H Number of active set 0..3 Thereby H is representing an hexadecimal character in ascii format i.e. "0" to "9" or "A" to "F". The "identificaton" in byte 0 serves to enable the program to detect, that it is called from the emulator, so it may behave differently as when called from the desktop. The pointer to the setup data... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ...points to the following structure: #Byte Contents Comment -------------------------------------------------------------------- 0..7 'ZXSP2.00' ID string, with emulator version number 8..807 800 Bytes Setup data as follows: 160 Bytes Data set #1 160 Bytes Data set #2 160 Bytes Data set #3 160 Bytes Data set #4 160 Bytes Data active set (working copy) Setup data contain the following values: Name Length Description ------------------------------------------------------------------------ prgpfad 35 Path for program files, null terminated mdrpfad 35 Path for microdrive data, null-terminated mdid 7 Filename microdrives (without number), null term. snapfad 35 path for SNA/SNA files, null terminated spalett 32 16 word colour palette for 320x200 illsw 1 switch Z80 Illegal: 0=Alert, 1=Monitor, 2=Ignore errsw 1 switch Emu error : 0=Alert, 1=Monitor, 2=Reset sna_sw 1 switch SNA format : 0=SNA, 1=SNX autosw 1 switch AUTO.SNA: Bit 0=at start, Bit 1=at RESET ulasw 1 switch ULA-compatible display: Bit 7 set=ON vblseq 1 Sequence pattern VBL display, bit-coded. Is not used in version 2.07 (earlier versions did). if1sw 1 switch Interface 1: 0=not emulated, 1=emulated flashsw 1 switch FLASH: 0=not emulated, 1=emulated attrsw 1 switch Attributes: 0=no attributes,1=attributes zy_sw 1 switch keys Z-Y: Bit 7=0 QWERTY, 1=QWERZ +joystick emulation Bit 0,1 00=Kempston 01=IF1/1 10=IF2/2 11=Cursor Bit 6 contains ULA-emulation from Version 2.07 on. (0=off, 1=on). r_sw 1 switch R-register:0=R not emulated, 1=R emulated Bit 7 is used as value for the EAR-bit. int_sw 1 switch interrupt frequency: 0=50Hz, 1=100Hz rs232sw 1 switch RS232 redirection: Bit 0=RS232, Bit 1=CENTR. sndsw 1 switch sound emulation: Lower nibble: 0=OFF,1=direct,2=Interrupt Higher nibble: frequency 0..4 for mode 2 bordsw 1 switch border emulation: 0=OFF,1=direkt,2=Interrupt im2hw 1 switch IM2 hardware vector 0..255 free 1 NOT USED rom_load 1 switch external ROM: 0=do not load, 1=load rom_pfad 36 path for external ROM file, null terminated cnfg_e 1 Configuration byte external programs: Bit 0: key ESC Bit 1: key F5 Bit 2: key F8 Bit 3: key CLR/HOME Bit 4: key INSERT Bit 5: key HELP Bit 6: key UNDO Bit 7: not used cnfg_s 1 Configuration byte shell mode (bits like cnfg_e) esc_prg 14 Name/Configuartion for program on key ESC Bytes 0..12 contain the name Byte 13 contains parameter for start: Bit 0: Restore colour palette Bit 1: Load resident Bit 2: Run in ZX-mode Bit 3: Evaluate return value Bit 7: Can be activated by left mouse click f5_prg: 14 Name/configuration for program on key F5 f8_prg 14 Name/configuration for program on key F8 clr_prg 14 Name/Configuration for program on key CLR/HOME ins_prg 14 Name/Configuration for program on key INSERT help_prg 14 Name/Configuration for program on key HELP undo_prg 14 Name/Configuration for program on key UNDO The pointer to the Z80 adress space... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ...points to the ram adress within the emulator, where the emulated adress space of the ZX-Spectrums Z80 processor starts. The first 16384 bytes are the ROM area. The pointer to the emulator variables... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ...points to a data area that contains besides various other values, the contents of the emulated Z80 registers: Offset Name Length Description -------------------------------------------------------------------- -14 request BYTE Request typ interruption (Scancode of key) By examining this value the external program may determine which key activated it. -13 shell BYTE Is 1 in Shell-mode, 0 in desktop mode -12 lstkey BYTE Last key pressed in Spectrum mode -11 SPECTRUM BYTE Spectrum mode: 0=OFF $ff=ON -10 zeropage LONG Pointer to Z80 adress space in Atari -6 fcount BYTE Counter for FLASH emulation -5 bcount BYTE Counter for BORDER emulation -4 attr_sw BYTE Runtime copy of attrsw-switch -3 flash_sw BYTE Runtime copy of flashsw-switch -2 fmode BYTE Flash cycle ($ff=INVERS) -1 BYTE (not used at the moment) -> 0 z80_regs 40 BY Emulated Z80 registers in this sequence: 0 _H BYTE H-register 1 _L BYTE L-register 2 _D BYTE D-register 3 _E BYTE E-register 4 _B BYTE B-register 5 _C BYTE C-register 6 _XH BYTE Upper byte IX-register 7 _XL BYTE Lower byte IX-register 8 _YH BYTE Upper byte IY-register 9 _YL BYTE Lower byte IY-register 10 _I BYTE I-register 11 _R BYTE R-register 12 _A BYTE Accumulator 13 _A' BYTE Alternative Accumulator 14 _H' BYTE Alternative H-register 15 _L' BYTE Alternative L-register 16 _D' BYTE Alternative D-register 17 _E' BYTE Alternative E-register 18 _B' BYTE Alternative B-register 19 _C' BYTE Alternative C-register 20 _SF BYTE S-bit (Sign) of status register 21 _ZF BYTE Z-bit (Zero) of status register 22 _U1F BYTE Unused bit of status registers 23 _HF BYTE H-bit (Half-Carry) des status registers 24 _U2F BYTE Unused bit des status registers 25 _VF BYTE V-bit (Overflow) des status registers 26 _NF BYTE N-bit of status registers 27 _CF BYTE C-bit (Carry) ofstatus registers 28 _SF' BYTE S-bit (Sign) of alt. status registers 29 _ZF' BYTE Z-bit (Zero) of alt. status registers 30 _U1F' BYTE Unused bit of alt. status registers 31 _HF' BYTE H-bit (Half-Carry) of alt. status registers 32 _U2F' BYTE Unused bit of alt. status registers 33 _VF' BYTE V-bit (Overflow) of alt. status registers 34 _NF' BYTE N-bit of alt. status registers 35 _CF' BYTE C-bit (Carry) of alt. status registers 36 _SP WORD SP-register (Stack pointer) HI-LO 38 _PC WORD PC-register (Program counter) HI-LO 40 iff WORD Z80 Interruptflipflop(s): 40 iff1 BYTE Interruptflipflop 1; $ff=enabled, $00=disabl. 41 iff2 BYTE Interruptflipflop 2; storage for iff1 42 intmode WORD Z80 Interruptmode: IM0=-1, IM1=0, IM2=1 44 akt_bc WORD Active border colour SHOULD BE 46 old_bc WORD Active border colour IS ACTUALLY 48 old_a7 LONG Internal storage for a7 52 brk_flg BYTE Flag breakpoint for monitor 53 mon_flg BYTE Monitor call: 0=User, 1=BREAK, 2=Illegal 54 r_bit7 BYTE Bit 7 of R-register 55 new_requ BYTE New request. By setting this value external programs can request activation of another program (scancode of key) after return (see -14 request). 56 ports 12 BY Soft ports of Z80: 56 WORD Filler, so that gets offset > 0! 58 port_b0 BYTE value for bit 0 of port adress 59 port_b1 BYTE Value for bit 1 of port adress 60 port_b2 BYTE Value for bit 2 of port adress 61 port_b3 BYTE Value for bit 3 of port adress 62 port_b4 BYTE Value for bit 4 of port adress 63 port_b5 BYTE Value for bit 5 of port adress 64 port_b6 BYTE Value for bit 6 of port adress 65 port_b7 BYTE Value for bit 7 of port adress 66 port_31 BYTE Value for port 31 (Kempston joystick) 67 port_xx BYTE unused (reserved) The pointer to the Atari screenbuffer... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ... points to a area of memory where the last shown Spectrm screen in Atari 32K-format has been put. Very practical for each external program that can use the Spectrum screen in any way (print hardcopy, store as IMG file, ..). The pointer to the return value... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ...serves for the communication with the emulator. By entering certain values into this adress, the emulator can be brought to perform specific actions, after it gained control again: (zx_ret.w) Action after return ------------------------------------------------------------------ 0 MUST NOT BE!! 1 Quit emulator (Desktop) 2 Perform ZX reset 3 Load snapshot, path must be at (screenbuffer). 4 Save snapshot, path must be at (screenbuffer). 5 Trigger NMI 99 Ignore all changes in set (CANCEL in SPSETUP) If an external program has been configured to return a value, it must in all instances put a non-zero value into (zx_ret.w) and the number for the active set into (zx_ret+2.w) because a zero-value will tell the emulator that activation failed. The value 99 can be used as "CANCEL"-value - in this case no return value will be evaluated and emulation continues immedeatly. Always when a return value other than 99 is entered there MUST also be entered the number of the active set into adress (zx_ret+2.w), which has to be a value between 0 and 4! Values from 0 to 3 will initiate a copy of the corresponding set into the work area (and setting of internal variables). The value 4 effects that the working set is left unchanged after return to the emulator. The number of the active set of switches... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ...for all programs, that rely on the knowledge, which set is currently active, like the program "SPSETUP.PRG".