This document describes the use and distribution permissions of the program Speccylator, a Sinclair ZX Spectrum emulator. The program and this document are copyrighted (C) 1993-1996 Richard Carlsson. This document (the original Texinfo file, or any representation generated from it) may be reproduced and distributed in any form or processed in any way, provided no literal content, and in particular the above copyright notice and this notice of permission, is lost in the resulting product. Speccylator Documentation ************************* The Speccylator program emulates a Sinclair ZX Spectrum computer. It is available for Motorola MC680x0-based Amiga computers only and is copyrighted (C) 1993-1996 Richard Carlsson. Distribution ============ The Speccylator program itself may be distributed freely under the conditions that no fee is charged above the costs of distribution and media, and that the program is not modified in any way. The file `Spectrum.ROM' contains an image of the 16 kByte Sinclair ZX Spectrum ROM and it is copyright (C) Amstrad. Cliff Lawson of Amstrad (CompuServe 75300,1517) has given special permission for emulator authors to use the Spectrum's ROM code. (1) This documentation (the original Texinfo file, or any representation generated from it) may be reproduced and distributed in any form or processed in any way, provided no literal content, and in particular the above copyright notices and this notice of permission, is lost in the resulting product. The included sample snapshot file `demo.sna' has no restrictions whatsoever on distribution or use. ---------- Footnotes ---------- (1) This paragraph is basically a quote from the documentation of Spectrum Emulator 1.7 by Peter McGavin. Introduction ============ The "Speccylator" is a program that emulates the Sinclair ZX Spectrum computer. It is written for Amiga computers as an application of a generic Z80 emulator core for the Motorola M68000 family of processors. It is fast, completely multitasking and system-friendly. It requires at least release 2.0 of the Amiga operating system, and about 450 kByte of available memory. It requires no particular hardware beyond that of a standard Amiga 500. The current version (1.0 beta) of the program emulates only the 48k model of the ZX Spectrum. It reads and writes so-called "snapshot" project files on the common `.sna' format (*note Snapshot Files::.). The emulator uses a custom screen for the ZX Spectrum display; nothing else would be practical. The allocated custom screen has a depth of 4 bitplanes and uses Lo-res resolution with no interlace. On startup, the program attempts to allocate two audio channels; one left channel and one right channel. If this fails, it will settle for a single channel, either left or right. If no channel is available, the program will abort. This behaviour is likely to change in future versions. Usage from Workbench ==================== The Speccylator program can be run from the Amiga Workbench, and may be passed a single snapshot file as argument. (See the `Amiga User's Manual' for details about passing arguments from the Workbench.) Simplest, this is done by double-clicking on the program's icon, or by similarly activating a project icon that has the Speccylator program as its default tool. Tool Types ---------- The following Tool Types affect the behaviour of the program. (Where they exist, abbreviations are given in addition to the standard name; however, these can only be used when running the program from the Command Line Interface; see *Note Usage from CLI::.) Booleans can be specified as `TRUE', `YES' or `ON', and `FALSE', `NO' or `OFF' respectively; the names are not case-dependent.: `DEBUG' (Boolean.) Only available if the program was compiled with the compilation option DEBUG, this flag makes the program run in debugging mode, which causes the user interface to be handled by a separately launched process, while the Z80 emulation is done by the original process. (Default `FALSE'.) `DIRECTORY' `DIR' (String.) Specifies the directory in which to look for snapshot files. If not given, the program's current directory is used. `EMULPRI' `PR' (Integer.) The priority (-128-127) of the task running the Z80 emulation. If not specified, the spawned task runs at the same priority as the original process. (The priority of the latter can be specified from Workbench using the standard `TOOLPRI' Tool Type, or from CLI with the `ChangeTaskPri' command.) *The recommended value is -1 or lower.* `INTPERIOD' `IP' (Integer.) The period (a nonnegative number), in number of vertical blankings (50/s for PAL, 60/s for NTSC), of the maskable interrupt (an `INT' signal). A zero value turns the periodic interrupt triggering off; even then, single maskable interrupts can still be triggered manually. `SAVEICONS' `I' (Boolean.) If `TRUE', icons are automatically created when snapshots are saved. (Default `TRUE'.) `SCREENPERIOD' `SP' (Integer.) The period (a nonnegative number), in number of vertical blankings (50/s for PAL, 60/s for NTSC), of the Spectrum screen refresh. A zero value turns the periodic screen updating off. `TITLEBAR' `T' (Boolean.) If `TRUE', the title bar of the custom screen will be visible. (Default `TRUE'.) `VERIFYACTIONS' `VA' (Boolean.) If `TRUE', any potentially harmful user actions, like quitting the program, will first ask for verification before being executed. (Default `TRUE'.) `VERIFYSIGNALS' `VS' (Boolean.) If `TRUE', commands to trigger processor signals like `RES' will first ask the user for verification before being executed. (Default `TRUE'.) Default Program Settings ------------------------ Default program settings are saved as Tool Types in the Speccylator program icon (the `.info' file associated with the program). If no such file exists when defaults are saved, a new `.info' file will be created, using the built-in image for the program. If the file already existed, only its Tool Types are affected, and of these only the ones pertaining to the Speccylator program (*note Tool Types::.) are modified. Project Settings ---------------- Settings particular to individual projects override any default settings or settings specified on the command line. They are stored as Tool Types in the project icon (the `.info' file associated with the project file). If no such file exists when project settings are saved, a new `.info' file will be created analogously to the case of saving default settings; see *Note Default Program Settings::. Usage from the Command Line Interface ===================================== The program has the following CLI template: SNAPSHOT, PR=EMULPRI/N, DIR=DIRECTORY/K, T=TITLEBAR/S, NT=NOTITLEBAR/S, I=SAVEICONS/S, NI=NOSAVEICONS/S, SP=SCREENPERIOD/N, IP=INTPERIOD/N, VA=VERIFYACTIONS/S, NVA=NOVERIFYACTIONS/S, VS=VERIFYSIGNALS/S, NVS=NOVERIFYSIGNALS/S, DEBUG/S, NODEBUG/S Options specified on the command line override any default settings. Most options have abbreviations, and every boolean option has a corresponding negated form, whose name is `NO' (or merely `N' for the abbreviations) prepended to the name of the positive form. The negated and abbreviated forms can only be used when running from the CLI; otherwise, for a description of the effects of these options, see *Note Tool Types::. Program Operation ================= The program is controlled via menus or corresponding short-cut keys (where such exist, they are shown in the menus). Keypresses which are not intercepted by the system or the graphical user interface are interpreted by the ZX Spectrum keyboard emulation; see *Note Keyboard Layout::. The Project Menu ---------------- `Open Snapshot...' Opens a file requester for selecting a project snapshot file to be loaded. If the `DIRECTORY' Tool Type has been specified, the requester will show that directory (if it exists); otherwise, the program's current directory is shown. *Note Tool Types::. `Save Snapshot...' Like `Open Snapshot...', but a Save requester is opened instead. If the `Create Icons' option is turned on, the current settings are automatically saved in the project icon file. *Note Project Settings::. `Save Screen...' Opens a Save requester for selecting a file name to which to write the current contents of the screen, in IFF ILBM format. The Z80 emulation is automatically halted before the requester is opened, and resumes when the operation has completed or been cancelled. No icon is created for the image file. `Save Settings' Saves the current settings as the project's default settings; see *Note Project Settings::. `Reload Settings' Loads settings from the project's icon file (if it exists). `Quit' Terminates the Speccylator program. The Settings Menu ----------------- `Title Bar' If turned on, the title bar of the custom screen is visible. `Create Icons' If turned on, the current settings are automatically saved as the project's default settings when a snapshot is saved, and new project icons are created where necessary. *Note Project Settings::. `Verifications' If turned on, the program asks for verification before executing any potentially harmful user action. `Screen Updating' Sets the refresh frequency of the ZX Spectrum screen, in percent of the vertical blanking frequency (50 Hz for PAL, 60 Hz for NTSC), or turns it off completely. The `Off' submenu item can be toggled, in which case the setting prior to the first selection is restored. Values other than those in the submenu can be set using the `SCREENPERIOD' Tool Type; see *Note Tool Types::. `INT Frequency' Sets the frequency of the periodic maskable interrupt signal, in percent of the vertical blanking frequency (50 Hz for PAL, 60 Hz for NTSC), or turns it off completely. Values other than those in the submenu can be set using the `INTPERIOD' Tool Type; see *Note Tool Types::. `Task Priority' Sets the priority of the task running the Z80 emulation. Values other than those in the submenu can be set using the `EMULPRI' Tool Type; see *Note Tool Types::. `Save Defaults' Saves the current settings as the defaults; see *Note Default Program Settings::. `Reload Defaults' Loads settings from the program's icon file (if it exists). The Processor Menu ------------------ `Pause' If turned on, halts the Z80 emulation until the option is turned off again. `Verifications' If turned on, the program asks for verification before executing any command to trigger a processor signal, like `RES'. `INT' Triggers the Z80's `INT' (maskable interrupt) signal. `NMI' Triggers the Z80's `NMI' (nonmaskable interrupt) signal. `RES' Triggers the Z80's `RES' (reset) signal. Keyboard Layout *************** The basic correspondence between the Amiga keyboard and that of the ZX Spectrum is simple: the alphanumerical Amiga keys (`A'-`Z' and `0'-`9') map directly to the same keys on the ZX Spectrum keyboard, and the Space bar to the Spectrum's Space key. Both Shift keys map to the Spectrum's Caps Shift key, and both Alt keys to the Symbol Shift key. When the Amiga Caps Lock is activated, the effect is that of keeping the Spectrum's Caps Shift key pressed down; when Caps Lock is turned off again, it corresponds to releasing Caps Shift. The Numeric pad works similarly; Enter maps to the Spectrum's Enter key, and the keys `0'-`9' map to the corresponding Spectrum keys. The Help key, the function keys (`F1'-`F10'), the Ctrl key and the two Amiga keys have no effect on the ZX Spectrum keyboard emulation. All remaining keys are mapped to sequences of keypresses on the ZX Spectrum keyboard, rather than to particular keys or symbols. Some of them can be modified by holding down a Shift key, but not all. The keys are interpreted according to the standard American keyboard (since it seems likely that most people are more or less familiar with that layout), and produce keypress sequences that yield the corresponding symbol or effect if initiated in the normal editing mode of the ZX Spectrum BASIC line editor. In particular, the following keys are of interest: * Esc: Go into E-mode. * Back Space and Del: Delete (Caps Shift + `0'). * Left Arrow, Down Arrow, Up Arrow and Right Arrow: Cursor keys (Caps Shift + `5', `6', `7' and `8', respectively). Snapshot Files ************** A "snapshot file" is a complete machine state dump of a 48 kByte Sinclair ZX Spectrum--the RAM memory contents and the processor state. The format is also called the Mirage Microdrive format, after the piece of hardware from which it originates. Snapshot file names are usually suffixed with `.sna' or `.snapshot'. A publicly available program named "spconv", written by Henk de Groot, can be used to convert such files to and from other snapshot formats, such as the common `.Z80' format. The Snapshot Format ------------------- A snapshot reflects the state of the machine after the occurrence of a non-maskable interrupt. Thus, the 2 bytes on top of the stack (the address pointed to by the saved stack pointer, and the next higher address) form the address to which the program counter was pointing when the interrupt occurred--this is always the address of the instruction which was to be executed next. The lower stack address contains the least significant byte (bits 0-7) of the program counter, and the higher address the most significant byte (bits 8-15); this is how 16-bit words are always handled in the Z80. The first 27 bytes of the snapshot file hold the saved processor and hardware state, at the following offsets (16-bit registers stored with the least significant byte first; for e.g. the register pair `HL', this is the 8-bit register `L'): Offset Name Comment 0: I (8-bit register) 1: H'L' (16-bit register pair) 3: D'E' (16-bit register pair) 5: B'C' (16-bit register pair) 7: A'F' (16-bit register pair) 9: HL (16-bit register pair) 11: DE (16-bit register pair) 13: BC (16-bit register pair) 15: IY (16-bit register) 17: IX (16-bit register) 19: --- (8 bits) Bit 2 set if maskable interrupts are enabled. 20: R (8-bit register) 21: AF (16-bit register) 23: SP (16-bit register) The stack pointer 25: --- (8 bits) Interrupt mode: 0, 1 or 2. 26: --- (8 bits) Border colour (0--7) in bits 0--2. Directly after this (at offset 27 from the start of the file) follow the contents of the 48 kByte RAM (located at addresses 16384-65535) of the machine at the time the nonmaskable interrupt occurred.