Speccy Documentation

# Speccy
version 1.7

### by Marat Fayzullin

## Contents

- New in This Version
- Introduction
- Keyboard Assignments
- Command Line Options
- Frequently Asked Questions
- History

## New in This Version

- Fixed WD1793 READ-ADDRESS command so that it no longer sets NOT-READY status bit.
- Added .Z80 file saving/loading for Scorpion and Pentagon.
- Added "Green CRT" palette selection.
- Made built-in configuration menu accept mouse input.
- Ported Speccy to Maemo5 (aka Fremantle).
- Added accelerometer based tilt controls to Speccy-Maemo5.
- Added Maemo-specific configuration menu to Speccy-Maemo5.
- Added customizable key mappings to Speccy-Maemo5.
- Added fast-forwarding with [Ctrl]+[Space] to Speccy-Maemo5.
- Added fast-forwarding with unused screen corners to Speccy-Maemo.
- Multiple other small fixes and additions to Speccy-Maemo.

# Introduction

Speccy emulates once popular Sinclair ZX Spectrum home computer, its upgraded versions, and its clones. As Speccy is written in a portable C programming language, it may run on many different platforms, such as desktops, palmtops, cell phones, set-top boxes, newer videogame consoles, DVD players, and even digital cameras. Currently available are Speccy binaries for Windows and MSDOS, with ports to more platforms coming soon. You can always get the latest Speccy binaries and support files from

http://fms.komkon.org/Speccy/

Although I had done some ZX-related work in the past and even maintained comp.sys.sinclair FAQ at some point, for many years I abstained from writing a Sinclair ZX Spectrum emulator. It was mostly due to the fact that there were so many other Spectrum emulators around, so writing another one seemed redundant. On the other hand, the lack of a Speccy emulator felt like a gaping hole on my resume :). So, here it is, yet another Spectrum emulator, trivially named Speccy. Currently, Speccy is not a commercial project but rather a test bed to try out different things before introducing them into my other emulators. Thus, feel free to use it as you wish (as long as it is not commercial). If you find a bug, have an idea on the further Speccy development, or would like to port Speccy to a new platform, please, let me know either by email, or by using the EMUL8 discussion group.

Since its creation, Speccy has been ported to Windows, MSDOS, and Symbian platforms. The latter works on Nokia's phones running the 3rd edition of the S60 software. For more information on Speccy-Symbian and my other Symbian projects, see

http://fms.komkon.org/EmuSymbian/

The current version of Speccy has the following features:

- Platforms
  - Sinclair ZX Spectrum 16kB
  - Sinclair ZX Spectrum 48kB
  - Sinclair ZX Spectrum 128kB
  - Sinclair ZX Spectrum +2
  - Sinclair ZX Spectrum +2A
  - Sinclair ZX Spectrum +3
  - Timex Sinclair TC2048
  - Timex Sinclair TS2068
  - Pentagon (unfinished)
- Input File Formats
  - .SNA Spectrum Snapshots (48kB and 128kB)
  - .Z80 Spectrum Snapshots (versions 1 through 3)
  - .TAP Tape Images
  - .TZX Tape Images
  - .FDI Disk Images
  - .DSK Disk Images (CPCEMU format)
  - .TRD Disk Images
  - .SCL Disk Images
  - .SCR Screen Dumps
  - .POK Cheat Files
- Output File Formats
  - .SNA Spectrum Snapshots (48kB and 128kB)
  - .Z80 Spectrum Snapshots (versions 1 through 3)
  - .FDI Disk Images
  - .TRD Disk Images
  - .SCL Disk Images
  - .SCR Screen Dumps
  - .MID MIDI Soundtracks (both PSG and beeper are saved)
- Input Devices
  - CapsShift+Cursor
  - Cursor/Protek/AGF Joystick
  - Kempston Joystick
  - Fuller Joystick
  - Sinclair Interface II Joysticks
  - Kempston Mouse
  - AMX Mouse (unfinished)
- Printers
  Printers are emulated by writing each dot as a character into a text file. This creates large text "canvases" that you can scale in a word processor by changing their font size, then print them on a real printer.
  - ZX Printer
  - Timex TS2040
  - Alphacom32
- Audio
  - ZX128-compatible AY8910 PSG
  - Fuller AY8910 PSG
- Other Devices
  Some of these are unfinished, but being worked on.
  - Multiface
  - BetaDisk/TR-DOS
  - Sinclair Interface I (unfinished)
  - DISCiPLE (unfinished)
  - PlusD (unfinished)
- Other
  - Built-in debugger.
  - Built-in configuration menu
  - Beeper output conversion to melodic tones.
  - Soundtrack logging into MIDI files.
  - Automatic fire for joysticks.
  - Emulation state saving and loading.
  - Network multiplayer mode (Windows, Symbian).
  - Simulated TV scanlines (Windows, MSDOS, Symbian).
  - Video image interpolation (Windows, MSDOS, Symbian).
  - Optional pause when window becomes inactive (Windows).
  - Scanline effect simulation (Windows).
  - Resizable window (Windows).
  - Full-screen mode (Windows, MSDOS, Symbian).
  - Virtual keyboard (Symbian).
  - Configurable screen orientation (Symbian).
  - Configurable backlight control (Symbian).

# Keyboard Assignments

      [LCONTROL]     - SYMBOL SHIFT key
      [LSHIFT]       - CAPS SHIFT key
      [ALT]          - Joystick FIRE button
      [TAB]          - "Magic button" (NMI) when applicable
      [PGUP]         - Fast-forward emulation (also: [F9])
      [ESC]          - Quit emulation (also: [F12])
      [F1]           - Go into built-in debugger
      [F2]           - Turn soundtrack log on/off
      [F3]           - Toggle joystick autofire on/off
      [F4]           - Rewind and start tape
      [F5]           - Invoke runtime configuration menu
      [F6]           - Quickly load emulation state from DEFAULT.Z80
      [F7]           - Quickly save emulation state to DEFAULT.Z80
      [F8]           - Toggle scanline simulation on/off
      [ALT]+[F8]     - Toggle screen softening on/off
      [F9]           - Fast-forward emulation (also: [PGUP])
      [F11]          - Reset hardware
      [F12]          - Quit emulation (also: [ESC])
      [ALT]+[PGUP]   - Volume up
      [ALT]+[PGDOWN] - Volume down
      [ALT]+[ENTER]  - Switch to full screen (Windows)

# Command Line Options

    Usage: speccy [-option1 [-option2...]] [filename]

    [filename] = Name of the file to load [DEFAULT.Z80]

     [-option] =
      -verbose <level>    - Select debugging messages [1]
                            0 - Silent          1 - Startup messages
                            2 - Disk I/O        4 - Illegal Z80 opcodes
                            8 - Memory mapper  16 - Illegal memory accesses
      -skip <percent>     - Percentage of frames to skip [0]
      -home <dirname>     - Set directory with system ROM files [off]
      -help               - Print this help page
      -16/-48/-128        - Emulate 16kB/48kB/128kB ZX Spectrum [-48]
      -2+/-2a+/-3+        - Emulate 128kB ZX Spectrum +2/+2A/+3 [-48]
      -ts2048/-tc2048     - Emulate Timex TS2048/TC2048 [-48]
      -ts2068/-tc2068     - Emulate Timex TS2068/TC2068 [-48]
      -didaktik           - Emulate Czech Didaktik Gama [-48]
      -scorpion           - Emulate Russian Scorpion 256kB [-48]
      -pentagon           - Emulate Russian Pentagon 256kB [-48]
      -psg/-nopsg         - Emulate AY8910 PSG [-psg]
      -drums/-nodrums     - Use MIDI drums for PSG noise [-nodrums]
      -melodic/-wave      - Use melodic/waveform beeper sound [-wave]
      -tapesnd/-notapesnd - Emulate tape sounds [-notapesnd]
      -kmouse             - Emulate Kempston mouse
      -kempston           - Emulate Kempston joystick
      -fuller             - Emulate Fuller joystick and PSG
      -cursor             - Emulate Cursor joystick (keys [5]-[8],[0])
      -cscursor           - Emulate cursor keys + CapsShift
      -if2                - Emulate InterfaceII joystick (keys [6]-[0])
      -auto/-noauto       - Autofire for joystick fire button [-noauto]
      -zxprinter          - Emulate ZX Printer [-zxprinter]
      -ts2040             - Emulate Timex TS2040 printer [-zxprinter]
      -alphacom32         - Emulate Alphacom 32 printer [-zxprinter]

      When compiled with #define JUMPZ80:
      -disciple           - Emulate DISCiPLE disk interface
      -plusd              - Emulate MGT +D disk interface
      -if1                - Emulate Sinclair InterfaceI
      -mf                 - Emulate Multiface 1/128/+3

      When compiled with #define DEBUG:
      -trap <address>     - Trap execution when PC reaches address [5800h]
                            (when keyword 'now' is used in place of the
                            <address>, execution will trap immediately)

      When compiled with #define SOUND:
      -sound [<quality>]  - Sound emulation sampling frequency [22050]
      -nosound            - Same as '-sound 0', turns sound off

      With #define UNIX:
      -sync <frequency>   - Sync screen updates to <frequency> [60]
      -nosync             - Same as '-sync 0'
      -saver/-nosaver     - Save/don't save CPU when inactive [-saver]
      -scale <factor>     - Scale window by <factor> [2]
      -tv/-notv           - Simulate/Don't simulate scanlines [-notv]
      -soft/-nosoft       - Scale and soften display [-nosoft]

      When compiled with #define MSDOS:
      -sync <frequency>   - Sync screen updates to <frequency> [-vsync]
      -nosync             - Same as '-sync 0'
      -vsync              - Sync screen updates to VGA VBlanks [-vsync]
      -tv/-notv           - Simulate/Don't simulate scanlines [-notv]
      -soft/-nosoft       - Scale display with softening [-nosoft]

# Frequently Asked Questions

1. How do I load programs from tape?

   To load a program from tape, load the tape into the emulator, then either select the TAPE LOADER in the 128kB mode or press `[J], [CTRL]+[P], [CTRL]+[P], [ENTER]` in the 48kB mode. Your Spectrum is now ready to load a program from tape. To start the tape, press `[F5]` or go to the builtin menu (`[F4]`) and check the TAPE RUNNING option. The loading process will start.

2. How do I speed up tape loading?

   Tape loading happens at the same speed it would happen on a real Spectrum. To speed it up, press the fast-forwarding button (`[PgUp]` or `[F9]`).

# History

## New in Version 1.6

- Created Speccy-Unix port, currently available in binary form for Ubuntu Linux.
- Extended Speccy-Symbian port to support UIQ3 phones from Sony Ericsson and Motorola. As I only have a key-operated Motorola Z8, testers with pen-based SE phones are badly needed.
- Added support for Russian Pentagon 256 computer, including RAM mapper, TURBO mode, HiColor, HiRes, and 16Color graphics modes.
- Added support for Czech Didaktik Gama computer.
- Added support for Scorpion TURBO mode.
- Added RealSpectrum and monochrome color palettes.
- Added palette selection to built-in menu.
- Fixed exit from Scorpion MONITOR menu.
- Fixed Spectrum +2 support (was loading the wrong ROM file).
- Changed Scorpion port mappings to <NNx1xxxxxxxx1101>.
- Fixed a bug that made all hardware other than ULA ignore accesses to <xxxxxxxxxxxxxxx0> ports.
- Added emulation for the 128kB/+2 Spectrum bug where reading from port 0x7FFD made hardware write the floating bus value into this port.
- Made 0x8000..0xFFFF address space return 0xFFs in 16kB Spectrum mode.
- Moved NMI and REWIND button handling inside the core Speccy code.
- Improved Symbian sound code, although sound problems still persist on some UIQ3 phones.
- Split Speccy-Symbian/S60 configuration menu into four tabs, making "Video" and "Audio" settings separate.
- Added "Audio Latency", "Skip Frames", and "Sync Updates" settings to Speccy-Symbian.
- Added to Speccy-Symbian ability to use Nokia E61/E62 [FUNC] key in the built-in menu.
- Fixed a Speccy-Symbian bug where pieces of virtual keyboard remained on screen after closing it.
- Pressing [8] key on Speccy-Symbian now invokes virtual keyboard, if enabled, for the phones which do not have the [EDIT] key.

## New in Version 1.5

- Added network play option to Speccy-Windows and Speccy-Symbian!
- Added support for "EXTENDED CPC DISK" .DSK files (ZX Spectrum +3).
- Added `-verbose` bit for illegal memory accesses.
- Now polling joystick once per screen update to save on CPU cycles and network traffic.
- Fixed a bug in Z80 OUTDR/OUTD/etc. opcodes where B register was decremented after performing OUT operation. ZX Spectrum +3 disk writes work now.
- Fixed uPD765 IRQ-STATUS command to return "invalid command" when no IRQs pending. CP/M-80 now boots on Spectrum +3.
- In ZX Spectrum 128kB mode, only paging in TR-DOS from BASIC, but not from BIOS.
- Made [BACKSPACE] key generate [CSHIFT]+[0], i.e. Spectrum key combination to delete a character.
- Continued working on the DISCiPLE/+D disk drive support.
- Added new, much better, scanline simulation and video softening effects to Speccy-Windows.
- Speccy-Windows full-screen mode now runs in 640x480 resolution.
- Added "Scorpion 256kB" option to the Speccy-Windows menu.
- Added `-sync/-nosync` option to Speccy-MSDOS to sync screen updates to the timer (use `-vsync` for VBlanks).
- Added `-zoom/-nozoom` option to Speccy-MSDOS that will zoom Spectrum display to fill the whole screen, using image softening algorithm.
- Speccy-MSDOS now runs in 640x480x15bpp VESA screen mode when `-zoom` or `-tv` options used, otherwise it runs in 320x200x15bpp screen mode.
- Switched Speccy-MSDOS from outdated DOS4GW to more up-to-date DOS32a extender.
- Added [CONTROL]+[F8] key combination to Speccy-MSDOS to toggle display zoom on/off.
- Added new "Fill & Soften" zoom mode to Speccy-Symbian. It is rather slow though.
- Added ability to use virtual keyboard in Speccy-Symbian to enter filename when saving a snapshot from the built-in menu.
- Added Spectrum +2 and +3 ROMs to Speccy-Symbian installation.
- Fixed problem with gameplay being too fast in Speccy-Symbian.
- Fixed possible source of instabilities in the S60 open file dialog in Speccy-Symbian.
- Fixed exit via Symbian-specific menu.
- Fixed premature termination of the emulation thread when exiting Speccy-Symbian, soundtrack recording and config saving work again.
- The [C] ("Clear") key is not longer used to toggle sound in Speccy-Symbian. It acts as [BACKSPACE] instead.

## New in Version 1.4

- Added support for uPD765-based disk drives found in ZX Spectrum +3. Speccy will now accept .DSK disk images in the CPCEMU format.
- Added support for POKE files (.POK) usually containing game cheats. Speccy will automatically try loading a corresponding .POK file for every .Z80 or .SNA snapshot.
- Added a built-in menu options to load and manage game cheats.
- Built-in menu now shows and loads GZIPped disk images.
- Added virtual keyboard to Speccy-Symbian, invoked by pressing `[EDIT]` or left `[SHIFT]` key. The keyboard can work in three modes: "Off", "Single Key Entry", and "Multiple Keys Entry".
- Added configurable display orientation and backlight control to Speccy-Symbian.
- Finally fixed opendir() problem on Symbian. All built-in file dialogs work now!

## New in Version 1.3

- Inlined WrZ80() for better performance.
- Added support for multiple disk drives.
- Improved support for DISCiPLE and +D interfaces (still incomplete).
- DISCiPLE/+D and ZX Printer can't be used at the same time.
- Split disk image handling from the FDC emulation.
- Added support for GZIPped disk images.
- Now freeing floppy disk buffers on exit.
- Now setting NOT-READY WD1793 flag when the disk drive is empty.
- Improved file type detection.
- Added menu options to save .MGT and .IMG disk images.
- Further extended and optimized Symbian screen rendering routines.
- Fixed and optimized TV scanline simulation in Speccy-Symbian.
- Made scanline effect stronger in Speccy-Symbian.
- Added frame rate display option to Speccy-Symbian.
- Added "fill screen" zoom option to Speccy-Symbian.
- Added MIDI soundtrack logging to Speccy-Symbian (saved into E:\Sounds and can be used as ringtones).

## New in Version 1.2

- Changed the way Z80 NMI interrupt works to comply with the standard.
- Changed Z80 HALT instruction to always terminate on an IRQ request, even when interrupts are disabled.
- Fixed several bugs in the ExecZ80() function (thanks go to Martin Fiedler).
- Added working WD1793 emulation (TR-DOS now works).
- WD1793 I/O ports are only enabled when the TR-DOS ROM is paged in.
- Kempston and other I/O ports interfering with WD1793 are now disabled when the TR-DOS ROM is paged in.
- In Scorpion mode, setting upper kempston port bits to ones.
- Fixed DISCiPLE/+D trapdoor mechanism.
- Added support for .TRD, .SCL, .FDI, and .$ (Hobeta) disk images.
- Added builtin menu options to save .TRD, .SCL, and .FDI disk images.
- Split "Input Devices" menu from the "Peripherals" menu.
- Now resetting Spectrum when a trapdoor addon like Multiface or TR-DOS has been enabled or disabled.
- Now trying to load ZXS128TR.ROM BIOS file when both 128kB and TR-DOS options are enabled.
- With TR-DOS enabled, Speccy will now automatically start in TR-DOS mode.
- Added more debugging message options (-verbose).
- Added error messages to Speccy-Windows.
- Added key remapping configuration to the Speccy-Symbian application menu.
- Speccy-Symbian application menu is now split into three pages.
- Speccy-Symbian now saves settings on exit.
- Extended this documentation.

## New in Version 1.1

- Added Timex Sinclair HiRes and HiColor modes (HiRes currently downscaled to 256 pixels).
- Fixed Timex Sinclair PSG-based joystick interface.
- Added an option for playing tape sounds.
- Added Windows joystick support.
- Added joystick button configuration.
- Inlined RdZ80() function for better performance.
- Replaced "updates per VBlank" (`-uperiod`) with "percentage of skipped frames" option (`-skip`).
- StretchBlt() slowdown problem in Windows 2000/XP solved.
- [ALT]+[F4] now quits application in Windows, as it should.
- Properly saving CPU time when inactive, waiting for a key or display sync.
- Properly checking sound track logging menu option on [F2].

## New in Version 1.0

- Emulating 16k, 48k, 128k, +2, +2A, and +3 Spectrums, Timex TC2048 and TS2068. Incomplete Pentagon emulation (no disks yet).
- Loading and saving 48k and 128k .SNA files.
- Loading and saving .Z80 files versions 1..3, with or without compression.
- Loading .TAP and .TZX tape images.
- Loading and saving .SCR screenshots.
- Emulating Cursor/Protek/AGF, Kempston, Fuller, and Interface II joysticks.
- Emulating Kempston mouse. AMX mouse support isn't finished yet.
- Emulating AY8910 PSG, both in 128k-compatible mode and Fuller mode.
- Emulating ZX Printer, Timex TS2040 printer, and Alphacom32 with ASCII art written to a file.
- Emulating some Centronix ports, output written to the same file as ZX Printer output.
- Emulating Multiface, Multiface 128, and Multiface +3, depending on the Spectrum model selected.
- Incomplete emulation for DISCiPLE, +D, Betadisk (aka TR-DOS), Sinclair Interface I (no disks, serial ports, or microdrives yet).
- Beeper sounds can now be automatically converted to melodic tones and saved to a MIDI file, together with PSG soundtrack.
- Moved both Windows and MSDOS versions to a new framework.
- Added framebuffer-based runtime menu which should work on all platforms.
- Added new framebuffer-based Z80 debugger which should work on all platforms.

© Copyright by Marat Fayzullin (marat [AT] komkon [DOT] org)