Amiga Format 95/af095sub.adf/Speccylator.LZX/Speccylator/Docs/Speccylator.doc

Text File | 1997-01-15 | 20KB | 472 lines

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.