Atari Forever



power without the price


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 INSTALLATIONIn 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/HOMEExcept 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 like9. 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 12 (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 SpectrumC: 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) +24The 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 '12' 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 UNDOThe 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".



 
© marko latvanen / atari forever 1999-2006