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-1997 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-1997 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 sample snapshot file `demo.sna', and other files included in the original distribution of the Speccylator program which are not covered by the above, have 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 totally system-friendly. It requires at least release 2.0 of the Amiga operating system, and about 435 kByte of available RAM. It requires no particular hardware beyond that of a standard Amiga 500. At startup, the program attempts to load a file containing an image of the 16 kByte Sinclair ZX Spectrum ROM. (By default, this file is called `Spectrum.ROM'. See Tool Types, the `ROMFILE' Tool Type.) The file included in the Speccylator distribution is copyright (C) Amstrad. See Distribution, for details. The current version (1.0) 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 (see 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 without interlacing. The program can allocate up to two audio channels, if available, for its sound generation; at most one left channel and one right channel. Both channels will receive the same output data. 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 and setting Tool Type values.) 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 Usage from CLI.) Booleans can be specified as `TRUE', `YES' or `ON', and `FALSE', `NO' or `OFF' respectively; these keywords are not case-dependent. If no valid right-hand value is found for a Tool Type, its original setting is unchanged. `AUDIOCHANS' `AC' (String.) `BOTH', `RIGHT', `LEFT', `ANY', `NONE', or any disjunction of these; e.g., `RIGHT|LEFT' equals `BOTH'. `BOTH' overrides `LEFT' and `RIGHT'. `BOTH', `LEFT' and `RIGHT' override `ANY'. All of them override `NONE'. (Default `BOTH'.) `DEBUG' (Boolean.) Only available if the program was compiled with the compilation option `DEBUG' (not in the standard distribution), 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 current directory is used. `EMULPRI' `PRI' (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.* `GAMEPORTUNIT' `GU' (Integer.) Amiga game port unit number for joystick use; see the `JOYSTICK' Tool Type. (The default value is 1.) `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. (The default value is 1.) `JOYSTICK' `JOY' (Boolean.) If `TRUE', the Amiga game port selected by the `GAMEPORTUNIT' Tool Type is activated, if it is available. (The default unit is 1, the normal port for joysticks; the system generally uses unit 0 for the mouse.) This only has effect on the emulation if a ZX Spectrum joystick interface (such as `KEMPSTON') is also selected. (Default `FALSE'.) `KEMPSTON' `KI' (Boolean.) If `TRUE', a Kempston joystick interface attached to the extension port of the ZX Spectrum is emulated. If a game port on the Amiga is activated by the `JOYSTICK' Tool Type, a joystick connected to that port will appear to be connected to the emulated interface. (Default `FALSE'.) `ROMFILE' `ROM' (String.) The name (relative to the current directory) of the file containing the 16 kByte ROM image to be read into the the ZX Spectrum memory at address 0 before emulation starts. If not specified, a file `Spectrum.ROM' is searched for, first in the current directory and then in the directory containing the program. `SAVEICONS' `SI' (Boolean.) If `TRUE', the current settings are automatically saved as the project's default settings when snapshots are saved, and icons are automatically created where none previously exist. See Project settings. (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. (The default value is 1.) `TITLEBAR' `TB' (Boolean.) If `TRUE', the title bar of the custom screen will be visible. (Default `TRUE'.) `VERIFYACTIONS' `VA' (Boolean.) If `TRUE', selecting any potentially harmful user action, 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 (see 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 Default program settings. If the `Create Icons' menu option (see The Settings menu) is turned on, project settings are automatically saved when saving a snapshot. Usage from the Command Line Interface ===================================== The program has the following CLI template: SNAPSHOT, AC=AUDIOCHANS/K, DEBUG/S, NODEBUG/S, DIR=DIRECTORY/K, PRI=EMULPRI/N, GU=GAMEPORTUNIT/N, IP=INTPERIOD/N, JOY=JOYSTICK/S, NJOY=NOJOYSTICK/S, KI=KEMPSTON/S, NKI=NOKEMPSTON/S, ROM=ROMFILE/K, SI=SAVEICONS/S, NSI=NOSAVEICONS/S, SP=SCREENPERIOD/N, TB=TITLEBAR/S, NTB=NOTITLEBAR/S, VA=VERIFYACTIONS/S, NVA=NOVERIFYACTIONS/S, VS=VERIFYSIGNALS/S, NVS=NOVERIFYSIGNALS/S Most options have abbreviations, and every boolean option has a corresponding negated form, whose name is `NO' (or `N' for the abbreviations) appended with the name of the positive form. The negated and abbreviated forms can only be used when running from the CLI. See Tool Types, for descriptions of the effects of these options. Options specified on the command line override any default settings. For instance, entering: Speccylator JetPac.sna PRI -1 AC ANY JOYSTICK NTB KEMPSTON the Speccylator would attempt to load a snapshot (project) file named `JetPac.sna', and execute with Z80 emulation task priority -1, allocating a single audio channel, the joystick enabled (in the default joystick port), the titlebar hidden, and Kempston interface emulated. (This is unless the CLI options are overridden by project settings. See Project settings.) 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 Keyboard layout). The menus --------- The Project menu ................ `Open Snapshot...' Opens a file requester for selecting a project snapshot file to be loaded. If the `DIRECTORY' Tool Type (see Tool Types) has been specified, the requester will show that directory (if it exists); otherwise, the program's current directory is shown. `Save Snapshot...' Like `Open Snapshot...', but a Save requester is opened instead. The Z80 emulation is automatically halted during the whole of the operation. If the `Create Icons' menu option is turned on (see The Settings menu), the current settings are automatically saved in the project icon file. See Project settings. `Reload Project' Reloads the current project, without reloading settings. `Save Screen...' Opens a Save requester for writing the current contents of the screen to a file, in IFF ILBM format. The Z80 emulation is automatically halted during the whole of the operation. No icon is created for the image file. `Save Settings' Saves the current settings as the project's default settings. See Project settings. `Reload Settings' Loads settings from the project's icon file (if it exists). `Save Defaults' Saves the current settings as the defaults. See Default program settings. `Reload Defaults' Loads settings from the program'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. See Tool Types, the `TITLEBAR' Tool Type. `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 none already exist. See Project settings. Also Tool Types, the `SAVEICONS' Tool Type. `Verifications' If turned on, the program asks for verification before executing any potentially harmful user action. See Tool Types, the `VERIFYACTIONS' Tool Type. `Audio' Selects the audio channels to be used (if available): `Both', `Right', `Left', `Any' (a single channel) or `No Audio'. The `No Audio' submenu item can be toggled, in which case the setting prior to the first selection is restored. See Tool Types, the `AUDIOCHANS' Tool Type. `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 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 Tool Types. The Emulation menu .................. `Pause' When selected, all emulation (processor, interrupts, screen updating, etc.) is halted. When deselected, everything is turned on again. All functions are affected, even if some have been individually enabled or disabled. `Joystick' If turned on, the Amiga game port selected by the `GAMEPORTUNIT' Tool Type is activated, if it is available. (Default unit is 1, the normal joystick port.) See Tool Types, the `JOYSTICK' Tool Type. `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. 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 `INTPERIOD' Tool Type. See Tool Types. `Interfaces' `Kempston' If turned on, a Kempston joystick interface attached to the extension port of the ZX Spectrum is emulated. If a game port on the Amiga is activated (see the `Joystick' menu option above), a joystick connected to that port will appear to be connected to the emulated interface. See Tool Types, the `KEMPSTON' Tool Type. The Processor menu .................. `Halt' If turned on, the Z80 emulation is halted (but other functions of the emulation remain unaffected). `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.