Brotikasten/BROTCD01.iso/spectrum/z80.doc

Text File | 1994-12-28 | 212KB | 4,272 lines

Sinclair ZX Spectrum Emulator 'Z80' v3.03  -  29/12/94  -  by G.A. Lunter



Contents:

    1.    INTRODUCTION, REGISTRATION, GENERAL INFORMATION
    1.1   Some general remarks
    1.2   Registering - sounds interesting!
    1.3   Other emulators
    1.4   Acknowledgements
    1.5   Disclaimers
    1.6   Copyright notices

    2.    THE EMULATOR
    2.1   Starting the emulator
    2.2   Using the emulator
    2.3   Keyboard emulation
    2.4   Screen emulation
    2.5   Sound emulation
    2.6   Loading programs from tape
    2.7   Using .TAP files
    2.8   Using .VOC files
    2.9   Multi-load games
    2.10  Using the Microdrive
    2.11  Using the Disciple and Plus D interfaces
    2.12  Using the Multiface
    2.13  Using the RS232 channel
    2.14  On joysticks and mice
    2.15  The utility ConvZ80
    2.16  Converting file formats - the utility CONVERT
    2.17  The utilities Z802TAP, TAP2TAPE and TAP2VOC
    2.18  The utility OUT2VOC - and how to make .OUT files
    2.19  Quick overview of command line switches, and features
    2.20  Miscellaneous remarks

    3.    THE SAMRAM
    3.1   Basic extensions
    3.2   NMI software
    3.3   The built-in monitor

    4.    THE SPECTRUM
    4.1   The Spectrum
    4.2   The Interface I
    4.3   The DISCiPLE and Plus D Interfaces - Introduction
    4.4   The DISCiPLE and Plus D Interfaces - Basic commands
    4.5   The DISCiPLE and Plus D Interfaces - More advanced commands
    4.6   The DISCiPLE and Plus D Interfaces - The snapshot button
    4.7   The Spectrum 128

    5.    TECHNICAL INFORMATION
    5.1   The Spectrum
    5.2   The Interface I
    5.3   The SamRam
    5.4   The Z80 microprocessor
    5.5   File formats





1. INTRODUCTION, REGISTRATION, GENERAL INFORMATION




1.1  Some general remarks


    This is the documentation for 'Z80', a Sinclair ZX Spectrum 48/128
    emulator.  The program turns your PC into a Spectrum.  Its features in
    a (largish) nut-shell:

      - Emulates ZX Spectrum 48K model 2 or 3, and Spectrum 128K.
      - Best compatibility of current Spectrum emulators.
      - Emulates Interface I and Microdrive (cartridge in cartridge file),
        Disciple and Plus D disk interfaces, Multiface 128.
      - Full tape support: loads both normal and turbo-saved programs using
        either tape interface on LPT port, SoundBlaster AD converter or
        .VOC sound sample files; can also use .TAP binary tape image files
        by trapping ROM save/load routines.  Saving back to tape is also
        possible, either directly to tape or to a .VOC sound sample file.
      - Full emulation of Spectrum screen, including all colour effects.
        Border, and timing-sensitive border and attribute effects are also
        emulated.
      - Emulation of ZX Printer, for Epson and HP Laserjet compatible
        printers.
      - Emulation of beeper through PC beeper, and of 128K sound through
        either PC beeper or AdLib (SoundBlaster) compatible cards
      - A program is included which makes .VOC or raw sound sample files
        of sounds produces by the Spectrum, either by the beeper, the
        soundchip of the Spectrum 128, or the MIC port.
      - OUTs to any port can be logged, and stored in a log file with
        timing information.
      - Supports digital and analogue joysticks, and mouse, controlling
        Cursor, Sinclair, Kempston or user-defined joystick.
      - Emulates Spectrum AMS Mouse interface (used by e.g. Art Studio)
      - Runs on any PC (but needs 640K base memory if no EMS is present).
      - Emulator runs just above 100% of actual Spectrum speed on 20 MHz
        286 and 25 MHz 386SX; can be slowed down on faster machines.
      - Z80 emulation includes emulation of R register, all unofficial
        instruction codes, and unofficial flags; interrupts once every
        1/50th emulated second; I have tried to make each instruction
        execute in a time proportional to the time taken on a real Z80.
      - Registered package includes all source files.
      - Interface I and Spectrum 128's "p" channel input/output can be
        re-routed to LPT or COM port, or to a file.
      - Includes several utilities; to convert from and to other snapshot
        and tape file formats, to convert snapshots into tape files, tape
        files into sound sample files, to display contents of snapshot
        files, to convert screen snapshots to .PCX and .GIF files, to read
        .VOC sound sample files from the LPT tape interface or
        SoundBlaster.
      - Multi-level support as in XZX 0.5.2
      - Emulator can set a breakpoint, invisible to the running program.
      - Emulator can load and save blocks of Spectrum memory to disk
        directly.
      - Emulator can run under Windows.
      - Supports VGA, EGA, CGA, Hercules and Plantronics video adapters
        including mono VGA.

    There is quite a lot to explain in this documentation.  First of all
    the emulator itself requires some of your PC's resources.  It is not
    really a demanding program, but there are some things that need
    attention.  These technicalities are dealt with in section 2.1.

    Some general things about the emulator are explained in section 2.2. If
    you read 2.1 and 2.2, you will know most of the basic stuff.  The
    details can be found in subsequent sections.

    The Spectrum has a number of ways to communicate with the outside
    world, like the obvious keyboard and the screen, but also the
    microdrives, the DISCiPLE/Plus D disk interfaces, the tape interface,
    the beeper, the sound chip of the Spectrum 128, the Kempston joystick,
    the AMS Mouse, the ZX Printer interface, and the RS232 channel of the
    Interface I and Spectrum 128 can be used to communicate with PC
    channels in some way. For instance, the keyboard is connected to the PC
    keyboard (sounds obvious) and the tape I/O can be routed to a file, as
    well as to a physical tape recorder, or it can come from a .VOC sound
    sample file.  All these things are explained in the rest of chapter 2.

    For our own Spectrums Johan Muizelaar and I built a piece of hardware
    we called the SamRam (which has nothing to do with the SAM Coupe, by
    the way!).  It contains a monitor program and software to make
    snapshots of programs.  It's still very useful and I still use it a
    lot.  An explanation of its functions is to be found in chapter 3.

    Some things peculiar to the Spectrum or its interfaces, not specific to
    this program but useful to know, are collected in chapter 4.  It
    contains for instance a table of Spectrum keywords and the key
    combination to get them; unfortunately this information is not printed
    on standard PC keyboards! More importantly, in this chapter it is
    explained how to use the Microdrive and DISCiPLE interfaces, both of
    which are probably unfamiliar to many former Spectrum users.

    There are some interesting technical facts about the Spectrum that I
    discovered while debugging the emulator.  As much as I could think of
    is contained in the final chapter.  You don't need to read this chapter
    to use the emulator.  A specification of the file formats used by the
    emulator is also included.

    For Spectrum software, utilities, other emulators for PC's as well as
    other computers, and other Spectrum related software, you can call the
    Spectrum Emulator support BBS in Groningen:

        Tatort BBS Groningen
        050-264840
        ([phone])
        300-14400 baud

    At the time of writing the BBS is open 24 hours a day, but this is
    subject to change.  Please try calling between 22:00 and 9:00 local
    time first.

    A number of interesting Internet addresses are

        FTP      ftp.nvg.unit.no         /pub/spectrum
        FTP      wuarchive.wustl.edu     /systems/sinclair
        FTP      ftp.ijs.si              /pub/zx
        GOPHER   gopher.nvg.unit.no
        WWW      www.nvg.unit.no         http://www.nvg.unit.no/
                                               /Sinclair/Spectrum

    (The Internet addresses above were taken from the FAQ list maintained
    by Marat Fayzullin).

    Usenet, often offered with Internet access, has Newsgroups like
    comp.sys.sinclair, comp.emulators.announce and comp.emulators.misc
    which can be sources of useful information; for instance, you can get
    the FAQ list mentioned above there.

    If you want to get in touch with me, my email address is
    [e-mail].





1.2  Registering - sounds interesting!


    'Z80' is a shareware program.  The program is not completely
    functional, and the parts which are left out are included when you
    register.  You are encouraged to give this demo version to friends, but
    DO NOT change the original archive in any way, please.  The shareware
    version of the emulator consists of the Z80-303.ZIP archive file, which
    should contain the following 11 files:

        Z80.EXE      - The emulator
        Z80.INI      - Default initialisation file
        Z80.PIF      - Program Info File to run 'Z80' under Windows 3.1
        Z80.ICO      - Windows icon
        Z80.DOC      - This documentation file
        Z80FAQ.DOC   - Frequently asked questions - and answers!
        REGISTER.DOC - Information on how to register for 'Z80'
        NEW.DOC      - The What's New file
        ROMS.BIN     - Various ROM images
        LAYOUT.SCR   - Keyboard lay-out help screen
        DIAGRAM.Z80  - Circuit diagram for tape interface, and calibration

    The shareware version of the emulator differs from the registered
    version in the following respects: it cannot be slowed down, it cannot
    load from or save to tape, and it does not emulate the DISCiPLE and the
    Plus D interfaces.  Everything else works as in the registered version.

    If you register, you get the fully working version, and the following
    utilities:


        CONVERT  - a general conversion program: can list out BASIC and
                   tranlate it back, produce .GIF or .PCX files from
                   screen dumps, translate Spectrum ASCII (CR) to PC ASCII
                   (CR/LF), and some other things.
        CONVZ80  - Translates various snapshot and tape formats of other
                   Spectrum emulators into each other.  Can handle the
                   familiar .SNA format use by several emulators (JPP,
                   XZX,...), and also Pedro Gimeno's (VGASPEC and SPECTRUM)
                   .SP format and Kevin J. Phairs' (SPECEM) .PRG format.
                   It can also handle tape files of SPECEM and L. Rindt and
                   E. Brukner's emulator ZX.
        DISCIPLE - Reads DISCiPLE and Plus D diskettes, both 3.5'' and
                   5.25''.  It translates the 48K and 128K snapshot files
                   to .Z80 snapshots, and ordinary files and screen
                   snapshots to .TAP tape files. (Not necessary for the
                   fully registered version, but handy for the cheaper
                   one.)
        Z802TAP  - Converts a .Z80 snapshot, 48K or 128K, to a .TAP file
                   which can be loaded into the emulator and saved to tape
                   by the next utility:
        TAP2TAPE - Saves the contents of a .TAP file back to tape, to load
                   it into an ordinary Spectrum.
        TAP2VOC  - Converts a .TAP file to a .VOC sound sample file, to
                   write to tape, or to load into the emulator.
        READVOC  - Reads in a long, 'digital' .VOC sound sample, to be
                   used as input to the emulator, from the LPT tape
                   interface or a SoundBlaster.
        OUT2VOC  - Converts .OUT log files into .VOC or raw sound sample
                   files, so that you can easily extract music samples from
                   Spectrum/Spectrum 128 games, or SAVE directly to a .VOC
                   or raw sample file.
        Z80DUMP  - Shows the header and the contents of a .Z80 file.


    You will also receive the source files of the emulator, the above
    utilities and the SamRam, and you will be kept informed about future
    updates.

    You can also choose to register for the emulator without DISCiPLE and
    Plus D emulation, if you are not interested in those parts.  The
    registration fee is a bit lower then, and you will receive everything
    stated above (including the DISCIPLE program), the only difference
    being that you get a version of the emulator that will not emulate the
    M.G.T. interfaces.

    There are several registration sites, the main one being B.G. Services
    in the U.K.  You can also register with me in the Netherlands, or with
    Jimaz in the Czech Republic, with Sinclair Freakeren in Denmark, David
    Pomeroy in New Zealand and with FriendWare in Spain, whichever is most
    convenient.  Details follow:



    B G Services, U.K.
    ------------------

    The registration fee is BP 20 or BP 15 for the version with or without
    DISCiPLE/Plus D emulation respectively.  Payment can be by sterling
    (Euro)cheques or postal order made payable to B G Services.  You can
    also transfer directly to the Giro account 324.82.16 (B G Services).
    The address is:

                B G Services
                64 Roebuck Road
                Chessington
                Surrey KT9 1JX

    Telephone enquiries on [phone], Fax [phone], or from
    abroad: [phone] and [phone] respectively.

    B G Services can also supply ready built tape interfaces for BP 11.50.
    These are proffessional quality items built into 25W 'D' connectors.



    Myself, The Netherlands
    -----------------------

    Registration fee is BP 20/BP 15, US$ 30/US$ 23,  HFL 50/HFL 35,  or
    equivalent amounts in your local (convertible) currency, for the
    version with or without DISCiPLE/Plus D emulation respectively.

    From the Netherlands, you can most conveniently transfer the fee to my
    Giro account 59.45.263, G.A. Lunter, Groningen.

    From every other country, I prefer bank notes or international postal
    money orders.

    From Europe, you can sometimes use a Eurocheque.  Please fill it in
    completely, including the number at the back, and please write it out
    in DUTCH currency.  Eurocheques written out in foreign currency cost
    HFL 20 to cash.

    I discourage using any other cheques.  If you have no other option
    available, please add the equivalent of HFL 20 for drawing the cheque,
    and specify whether you want the version with or without DISCiPLE/+D
    emulation.

    The address is:

                Gerton Lunter
                P.O. Box 2535
                NL-9704 CM  Groningen
                The Netherlands

    You'll get the files on a 3.5'' HD disk by default, but you can also
    get it on DD or 5.25 inch disks if you want.



    Jimaz, Czech Republic
    ---------------------

    For registrations in the Czech Republic, you can contact Jimaz.

                JIMAZ s.r.o.
                Hermanova 37
                170 00 Praha 7
                phone: [phone]
                fax:   [phone]
                Email: [e-mail]

    Registration fee is 500 and 650 Czech crowns.



    Sinclair Freakren, Denmark
    --------------------------

    For registrations in Denmark, you can register with

                Sinclair Freakren
                Leif Mortensen
                Bryggervangen 29
                DK-7120 Vejle /Ost
                Denmark

    Registration fee is (150) 200 DKr for the (un)discipled version.



    David Pomeroy, New Zealand and Australia
    ----------------------------------------

    For registrations in New Zealand and Australia, contact

                David Pomeroy
                P O Box 2939
                Shortland Street
                Auckland
                New Zealand
                Phone: [phone]
                Email: [e-mail]


    The registration fee is 40/50 NZ$, or 30/40 AUS$.



    Friendware, Spain
    -----------------

    In Spain, you can register with Friendware.  The address is

                Friendware
                C/Miguel Angel, 6 2nd 5
                28010 Madrid
                SPAIN
                Phone: [phone]
                Fax:   [phone]
                CompuServe: 100413, 1667
                Email:  [e-mail]

    Registration fee is 3500 and 4700 Pts, respectively.




1.3  Other emulators


    There are several other Spectrum emulators, both for the PC and other
    computers.  The list below ia mostly from Carlo Delhez (the QL
    emulators) and partly copied from Arnt Gulbrandsen's documentation of
    his JPP.  I don't think the list is complete, so if you know more
    Spectrum emulators, for any computer, please let me know.


    For PC's:

    o WARAJEVO, by Zeljco Juric and Samir Ribic.  Written, in Sarajevo, in
      bad conditions during the Bosnian war.  A very thorough program;
      clean sounds, automatic R-register and 'LDIR'-emulation when needed,
      fast operation when not, traps on some RST's to speed up BASIC, good
      emulation of unofficial opcodes, well-organised tape file system,
      machine code monitor, ZX Printer emulation, sneaky software detecting
      some speed-loaders by their code and feeding regular tape files to
      them (!), partial 128K emulation.
    o JPP, by Arnt Gulbrandsen (Norway).  Faster than mine (but according
      to an OUTLET review slower on some boards), by using a very smart
      decoding technique, but requires a 80386 or '486 processor.  Is less
      compatible than Z80. Uses the .SNA snapshot format.  Needs VGA. Not
      many extra features. o VGASPEC, by Alberto Olloqui (Spain).  Needs
      VGA and 80286.  Quite slow, and crashes on quite a lot of programs.
      Uses the .SP snapshot format.  Allows ROM pokes.  This program is an
      illegal pre-release of SPECTRUM, by Pedro Gimeno.
    o SPECTRUM, by Pedro Gimeno (Spain).  Uses another .SP snapshot format.
      Has a tape interface.  Also quite slow. Allows changing the rom.
    o SP, by J. Swiatek and K. Makowski (Poland).  Cannot load or save
      snapshots, but can load programs using LOAD "" via a file called
      TAPE_ZX.SPC.  Crashes many programs; even basic behaves weird
      sometimes.  Has a built-in monitor, but no documentation.  No border.
    o SPECEM, by Kevin J. Phair (Ireland). Also allows rom changes.
      Displays the registers on screen.  Can save and load directly from
      disk using LOAD/SAVE "filename" in BASIC. Loads .PRG snapshots, but
      cannot save them.  Emulates a Multiface I.
    o ZX, by L. Rindt and E. Brukner (Czech Republic).  Haven't tested its
      compatibility thoroughly, but one of the games supplied didn't
      respond well to the keyboard, while it did work on Z80 after
      conversion.  Good tape file support including headerless files,
      almost identical to the multiple .TAP file mode of Z80.  Somewhat
      slower than Z80.  Includes program to load from tape and convert to
      tape file.  No documentation at all.


    For the Sinclair QL:

    o SPECTATOR by Carlo Delhez, The Netherlands; shareware; supports
      tape-files, Microdrives, RS232, Z80 snapshots, MBF snapshots and
      Disciple (SNP) snapshots; utilities to convert Disciple, Beta and
      Opus disks enclosed.
    o ZM-1/2/3/4, ZM-HT by Ergon Development, Italy; ZM-1 is shareware,
      others are commercial.  They all support tape-files and Z80
      snapshots, some support Microdrives and RS232; contain a utility to
      transfer programs from tape via a Spectrum to the QL.  Seem to be
      real good and fast.
    o ZX by Andew Lavrov, CIS; shareware; supports tape-files, MBF
      snapshots en Z80 snapshots; utility to read from Spectrum tapes (and
      write them).


    For the Amiga:

    o Spectrum, by Peter McGavin.  Very good, JPP is based to a large
      extent on it.  Needs about a 25MHz machine to run at full speed.
      Has tape support.
    o KGB.  I haven't seen it.  A bit slower than Peter's, and the
      version Peter saw wouldn't work on the Amiga 3000.
    o An Italian emulator which I don't know the name of.  Excellent
      compatibility, rather fast.  May be shareware.
    o Several unreleased emulators.  Peter knows more about them.


    For the Atari ST/TT:

    o One, called Spectrum.  Don't know anything about it, but the doc
      file is written in quite the worst English I've seen.  [This is
      Arnt speaking --- I've seen worse! GAL] Available by anonymous
      ftp from terminator.cc.umich.edu.
    o There's another one in the make, to be released very soon as one of
      the programmers told me, written by Markus Oberhumer and other(s).


    For the Acorn Archimedes:

    o A good emulator written by Carsten Witt (Rostocker Str. 5, 45739
      Oer-Erkenschwick, Germany), written in ARM code, RISC OS Desktop
      compatible, multitasking, loading and saving to disk or tape via
      RS432, understands .Z80 snapshots and others, emulates microdrives.
      Seems to be the best one around for the Archimedes at the moment.
      (Information supplied by Mr. G. Oeing-Hanhoff)
    o A company called Arxe wrote one, intended to be commercial but
      never released because Amstrad wouldn't permit Arxe to enclose the
      ROM.
    o Someone called D. Lawrence wrote another, or maybe the same.
      This one is floating around but nobody has any documentation.  I
      don't know what its status is.  Runs at about 70% of Spectrum speed on
      an ARM2, not quite perfect graphics emulation.


    For the Commodore 64:

    o The Whitby Software Spectrum simulator is a rewrite of the
      Spectrum Basic.  It will not run machine-code programs.  I don't
      know whether it's PD, shareware, or commercial.  Quite good.
      (Responds nicely to a POKE 23659,0)


    For the Amstrad CPC

    o Spectator - I believe this appeared on a cover tape on a
      now dead magazine.

    All emulators for PC, and some for the Atari, Amiga and QL are
    available on the support BBS.

    There are also emulators available for the ZX81.  Carlo Delhez, who
    also wrote a Spectrum emulator for the QL, wrote the ZX81 emulators
    XTricator (for the QL) and XTender (for PC's).  These programs can also
    be downloaded from the support BBS.




1.4  Acknowledgements


    From the very first beginning in november 1988, when I wrote the first
    lines of the emulator, Johan Muizelaar has been a very demanding and
    critical user, being only satisfied when it was perfect.  Besides,
    there are quite a few things I would never have started working on if
    he hadn't insisted that I would!

    I have also profited much from the fine cooperation with Brian Gaff,
    who, besides handling the UK registrations, also generates a continual
    stream of suggestions, remarks and bug reports.  He also brought me
    into contact with many people that contributed to the emulator in
    several ways.

    A major part of the things new to version 3 of the emulator have been
    written by Hugh McLenaghan.  He wrote all code for the Disciple/Plus D
    emulation, and for the ZX Printer emulation (where I subsequently
    introduced bugs...)  Also, Hugh wrote much of the documentation for the
    Disciple and Plus D interfaces in this file.


    Finally, thanks are due to

    o   Carlo Delhez for information on the '128 and several other things,
    o   Andre Mostert for some more '128 info and info on EMS memory,
    o   Walter Prins for many '128 programs,
    o   Marco Holmer for making the program such a big hit at the HCC dagen,
    o   Henk de Groot, for finding a solution to a bug in A86 v3.22,
    o   Arnt Gulbrandsen for a suggestion which made the emulator faster,
            and information on a group of unofficial Z80 opcodes,
    o   Ruud Zandbergen for his digital joystick interface,
    o   Jan Garnier for providing the chips to reanimate my real Spectrum,
    o   Ettore de Simone for finding a noisy bug,
    o   Rudy Biesma and Tonnie Stap for providing info on the DISCiPLE disk
            formats,
    o   Burkhard Taige for various bug reports on it,
    o   Ian Cull for enhancing the DISCiPLE program and two bugfixes,
    o   Bert Lenaerts for information on the AZERTY keyboard,
    o   Chris Lemon for fixing a bug in the CALL instruction,

    and many more not mentioned!




1.5  Disclaimers


    Of course the software is not guaranteed to work as it is supposed to
    do.  It is more than probable that the program contains some as yet
    unknown bugs.

    But, the program as it is now also contains some _known_ bugs!  It
    looked as if it would have taken another few weeks to remove these
    bugs, and if Hugh and I would have been too perfectionistic, the
    program would never be released.  So here it is, complete with the
    following bugs:

        - FORMATting a Disciple/+D disk on a PC does not always work.
        - Saving a Snapshot to Disciple/+D disk using the built-in
          Disciple/+D snapshot software only works the first time it is
          used.  Subsequent use of the snapshot button overwrites the
          first snapshot.

    It is recommended that you make backups of important Disciple/+D disks
    before writing to them (especially snapshots).  Reading disks is safe.




1.6  Copyrights etc.


    Amstrad holds the copyright on the 48K and 128K rom.  However, they
    have allowed free use of them.

    The Disciple ROM is (c) Bruce Gordon / Format Publications.

    The Plus D ROM is copyright Datel / Format Publications.

    Multiface and Lifeguard are registered trademarks of Romantic Robot.
    They are licensed from Romantic Robot for use in Z80.

    The registered version of the Spectrum emulator 'Z80', and the version
    distributed with PC Format, may NOT be further distributed.  The source
    codes, which are part of the registered package, may NOT be used in
    other Spectrum emulators running on PC's. In principle, it is okay to
    use the Z80 emulator code in an emulator for another Z80-based
    computer; however, please do contact me if you want to use it.






2.  THE EMULATOR




2.1  Starting the emulator


    The emulator will work on any PC with at least 640K memory, with a VGA,
    EGA, Hercules, CGA or Plantronics video adapter.  If available, it will
    also use EMS memory, an Adlib compatible soundcard, the SoundBlaster
    card, a mouse, and an analogue or digital joystick.

    The emulator will first read in the switches that are given in the
    Z80.INI file.  You can enter switches there just like you do on the
    command line.  Lines starting with a % sign are ignored; they are used
    for comments.

    After any switches, you may specify a snapshot file on the command
    line. This file will then be loaded and executed directly.  The
    extension .Z80 is not necessary.  The emulator will also read .SNA
    files (the snapshot format of, amongst others, Arnt Gulbrandsen's JPP);
    you don't have to convert them to .Z80 files (but you may want to to
    save disk space).

    The emulator tries to figure out what hardware is available, and uses
    things as it finds them.  Most of the time this will work without you
    having to tell it anything, but if you have to, you can override the
    defaults by putting switches on the command line.  Switches that you
    use often can be put in the Z80.INI file.  If you give a switch a
    second time, for instance if it is also in the Z80.INI file, it will
    disable it again.

    If you're using a Trident VGA with version 3 BIOS, you may see the
    picture compressed at the top of the screen, while the bottom half
    contains vertical white lines.  This is due to a bug in the Trident VGA
    Bios.  Start the emulator with the switch -xv to get a full picture.

    Some black-and-white VGA monitors only display one of the three RGB
    colours (green most of the times), resulting in several Spectrum
    colours becoming indistinguishable.  Use -xb to use grey tones instead
    of colours.

    If you are using Hercules, try starting the emulator with -xh on the
    command line.  The emulator will use a non-standard Hercules mode to
    display a full-screen Spectrum picture.  You may need to calibrate your
    monitor to make the image steady.

    If you're using Plantronics, try -p and -q to see which gives the best
    result.

    If you haven't got EMS memory, the page swapping of the Spectrum 128
    cannot be emulated exactly, and, more seriously, it is extremely slow.
    Although most programs will work, they will be too slow to be of any
    use.  Also, the emulator needs lots of base memory if no EMS memory is
    present; if you don't have enough, try specifying -xt on the command
    line to make the emulator use as little memory as possible (by
    shrinking several buffers).  The emulator uses 332K or 572K of base
    memory (with and without EMS memory respectively), and 47K less in both
    cases if -xt is specified.  If this is still not enough, try to use
    -xu, which saves 83K, but then Hi Resolution Color emulation does not
    work anymore.

    On 386 and 486 machines you can emulate EMS by software using EMM386
    for instance.  The speed of the EMS emulator determines in part the
    emulation speed of Spectrum 128K programs, so it may be wise to try a
    few for the best results.  I use QEMM, which seems to be faster than
    EMM386.

    The Spectrum 128 has a built-in sound chip.  If you have an Adlib
    compatible soundcard installed, the Spectrum 128 sound will be played
    through the Adlib card.  If you haven't, the loudest of the three sound
    channels will be played through the internal PC speaker.  Sometimes the
    effect is quite nice, sometimes it is horrible, but it's all I can do
    on a standard PC.  If you don't want to have the Spectrum 128 sound
    played through the internal speaker, use the switch -xi.  If you don't
    want the Adlib card to be used (for instance to hear the sound through
    the internal speaker) use -xa.

    If you're using the Pro-Audio Spectrum 16 sound card, do not install
    the resident FM.EXE program; it causes problems with the emulator. Do
    make sure that MVSOUND.SYS is installed in your CONFIG.SYS file, to
    make the Pro-Audio Spectrum 16 Adlib compatible.

    The noise channels of the Spectrum 128 sound chip can work on different
    frequencies, whereas the FM chips of the Adlib card cannot.  However,
    if your Soundblaster is equipped with CMS chips, the noise frequency
    can be programmed.  Specify -xc to use the CMS chips.  (These chips are
    not available on Soundblaster Pro cards, and neither on most
    Soundblaster clones).

    If you're living in Belgium or France, you are probably using an AZERTY
    keyboard.  Specifying -xz on the command line will make all letter keys
    and many punctuation keys work in the right way.

    If the emulator erroneously detects an analogue or digital joystick,
    use the switch -kk.

    The emulator can now also be run under Windows 3.1!  However, you
    cannot use the tape interface, Real mode doesn't work anymore, and the
    keyboard is not emulated as well as usual, because I have to scan it
    using BIOS calls.  Be sure not to set the keyboard repeat rate too low;
    an initial delay of 250 ms followed by 10 keys a second will do, but
    don't make it slower.  Some key combinations may not work, such as ALT
    4 for $.  So if you want to use the emulator seriously then you
    shouldn't run it under Windows, but it's nice to see three Spectrums
    run simultaneously...  If you let the emulator run full-screen you may
    use EGA or VGA, if you want to run it windowed you'll probably have to
    use CGA, because the virtual video display driver of Windows cannot
    handle the VGA mode I use (although it's only a standard text mode!).
    You'll probably want other default settings of some parameters (such as
    the video mode) if you run the emulator under Windows; the emulator
    will always use the .INI file in the directory of the Z80.EXE file so
    the other switches must be put on the command line or in a .PIF file.
    An example .PIF file (which runs the emulator in windowed CGA mode) and
    a .ICO icon file are supplied

    Since the execution speed of a program running under Windows heavily
    depends on other processes, the emulator doesn't try to measure how
    fast it is running under Windows.  It says it runs at 100%, and you can
    slow it down in the usual way, but the percentage is now relative to
    the maximum speed, and has nothing to do with the actual execution
    speed.

    The emulator will automatically detect whether Windows is running, and
    act appropriately.  To run the emulator in Windows compatibility mode
    in a normal DOS environment, use -xw.

    When running the emulator under Desqview, use -e for EGA mode display.

    At present running under OS/2 is not a good idea as it will crash if
    the speed is altered!

    These are the most important switches that you have to specify when you
    start the emulator.  Most of the other switches are used to select
    default values for various things which can also be changed when the
    emulator is running.  Some useful things to select are default
    directories for .Z80, .TAP and .MDR files; these will be explained
    below.




2.2  Using the emulator


    In this section, the basic functions of the emulator, residing under
    the function keys F1-F10, are explained.

    When the emulator starts, you'll see the usual Spectrum copyright
    message appear on screen.  Pressing F1 will pop up a small help screen
    that explains the function of the function keys and various other
    special keys.

    By pressing F10, you enter the main menu of the emulator.  Most of the
    menu options can be chosen directly by pressing another function key; a
    small help screen pops up if you press F1.  If you're somewhere deep in
    the menu structure from the main menu, pressing ESC will get you one
    level higher most of the time.  Pressing F10 will get you back to the
    main menu.

    The 'Select Hardware' menu option sits under function key F9.  There
    are seven major configuration to choose from:

        Spectrum 48K
        Spectrum 48K + Interface I
        Spectrum 48K + SamRam + Interface I
        Spectrum 48K + M.G.T. Interface  (i.e. DISCiPLE or Plus D)
        Spectrum 128K
        Spectrum 128K + Interface I
        Spectrum 128K + M.G.T.

    This menu also allows to choose the M.G.T. type, +D, Disciple with a
    pre-loaded operating system supporting graphics output using the Epson
    format, and one supporting HP-PCL format graphics output.

    In all configurations except the one with SamRam, the Multiface 128 can
    be emulated too.  The Multiface 128 software is aware of, and can read
    and write to, the Microdrive of the Interface I and the Disciple and +D
    disk drive.

    After a change has been made, pressing ENTER switches to that mode and
    resets the Spectrum.  If you don't want the Spectrum to reset, pressing
    CTRL-ENTER will switch to the new mode while preserving as much of the
    runninge program as possible.  Switching from 128K mode to 48K mode
    will almost always crash the program, except if you enter the SPECTRUM
    command before switching.

    To use SamRam's monitor on a 128 program, switch the hardware from the
    main menu, and generate an NMI (Extra functions - N) before returning
    to the emulator.  This will often work, but you can't return to the
    program without crashing it.

    On a real Spectrum 128, the menu bar of the startup screen is moved
    using the cursor keys on the '128 keyboard.  These keys simultaneously
    press a normal cursor key (5,6,7 or 8) and shift.  So you can shift the
    menu bar with shift-6 and shift-7.  It is possible to use the PC cursor
    keys for this; you have to select Cursor joystick emulation (which is
    selected by default) and press Num-Lock once to have the PC-cursor keys
    press the Spectrum Shift key too.  You could also specify -xs on the
    command line (or put it in the Z80.INI file) to make the PC cursor keys
    by default press shift for you in '128 mode; see also the Miscellaneous
    remarks section.

    The Save and Load Program options (F2 and F3) will save the whole state
    of the Spectrum and some of the emulators' settings to a .Z80 snapshot
    file.  It will pack the data somewhat, so that the length of the file
    varies.  The amount of memory saved depends on the current hardware
    mode; 48K for normal Spectrum, 80K for SamRam, and 128K for Spectrum
    128.  (Note that the RAM contents of the M.G.T. interface or the
    Multiface 128 are not saved.)  The settings that are saved are those
    that are program dependent, for instance which joystick emulation is
    used, and more technical settings like those of the R register, LDIR
    and Issue 2 emulation, double interrupt frequency and video
    synchronisation.  These are explained below.

    Loading a .Z80 file will cause several settings to be changed.
    Resetting the Spectrum will not reset these settings to their default
    values! Especially the joystick emulation setting change can be
    confusing, so keep track of that.

    All settings can be checked and changed in the Change Settings menu,
    which pops up if you press F4. You can do many things here. explain
    them all now.  The I and O options can be used to redirect the RS232
    output; see section 2.13 for information on this.  R - R register
    emulation, and L - LDIR emulation are usually only necessary when
    loading programs;  for remarks on these options see section 2.6, and
    section 5.1 for more technical details.  Other settings and switches
    are:

    H - Hi color resolution emulation.  To eliminate flickering of moving
    characters, and to see some color effects otherwise not visible.  See
    section 2.4 for more information.

    2 - Issue 2 emulation will turn the emulated Spectrum in an Issue 2
    Spectrum.  (This option also works, but is out of place, in Spectrum
    128 mode).  Some very old programs (Blue Ribband, Spinads) will not
    respond to the keyboard properly on Issue 3 Spectrums, and for these
    programs this option was added.  Seldom needed.

    S - sound enables you to turn off all sound, useful for late-night
    playing.

    D - double interrupt frequency is useful for slow machines, as some
    programs will run faster when this option is on.  If you're typing in a
    BASIC program on a slow machine, always turn this on, since the
    keyboard, which is polled by an interrupt routine, will respond much
    better.  On the other hand, some programs will crash with this option
    active.

    V - video synchronisation is used to remove the flickering of moving
    characters in some programs.  You can choose between Normal, High and
    Low.  Normal works well for almost all programs; Ghosts and Goblins and
    Zynaps look much better when this is turned to High.  If you see
    characters not moving smoothly or flicker, or a background not moving
    as a whole, experiment a little bit with this setting, and re-save the
    snapshot when you've found the best setting.  On fast computers, try to
    use Hi Color Resolution emulation instead. (For a more detailed
    discussion of this option see section 2.4 and section 5.1)

    J - joystick emulation specifies which Spectrum joystick the PC cursor
    keys (and mouse, and analogue or digital joystick, if available)
    control. You can choose from Cursor (default), Kempston, Interface 2
    and user-defined.  As already said above, if Cursor joystick is chosen,
    the Num-Lock key controls whether Shift is pressed too with a joystick
    movement. (Since the shift and number keys are pressed exactly
    simultaneously, it is possible that the Spectrum has already read the
    Shift key, but not yet the others, when you press both keys down.
    Sometimes you will therefore get the number 5,6,7 or 8 instead of a
    cursor movement. If you have used a +3 or +2A Spectrum, you will be
    familiar with this!)

    Finally, C - Change speed lets you control the speed of the emulator.
    As a side effect, slowing down the emulator makes the timing of the
    various opcodes correspond more exactly to the actual timing on a real
    processor. (Remember this is not possible on slow PCs!)

    That concludes the discussion of the F4-'change settings' menu.  Let's
    continue with the other function keys.

    F5 generates an NMI. This is used to activate the Samram, Multiface
    128, or start the Disciple/+D Snapshot facility. If none of these are
    active it may reset the Spectrum or do nothing.

    ALT-F5 or CTRL-F5 resets the Spectrum.

    F6 turns on Real Mode.  Try this when the emulator is playing a tune
    and sounds a little harsh.  This mode is needed when you want to load
    turbo-saved games from tape; see below for more information.

    F7 and F8 activate the tape and Microdrive/M.G.T. menus.  Again, see
    below for more information.

    Resetting the Spectrum, or generating an NMI can be done from the main
    menu too, in the X - Extra Functions menu.  This is useful if you want
    to activate the NMI software of the SamRam for instance just after
    loading a snapshot file, or just after you changed the hardware mode.

    In this menu it is also possible to save or load a memory block or
    screen snapshot; to set a breakpoint or to temporarily shell to DOS.
    Furthermore, here you can find another sub-menu for the OUT logging
    feature.  If port FE is logged, such a log file can be translated
    into a .VOC sound sample file.

    When you're typing BASIC-programs in 48K mode, you'll probably have to
    look up some Spectrum keywords.  Further down in this documentation
    there is an alphabetical list of all keywords and their
    key-combination. For 'on-line' help, press ALT-F1 to see the Spectrum
    keyboard layout.




2.3  Keyboard emulation


    The keyboard.  Letter keys are mapped to the Spectrum's letter keys.
    The ALT and CTRL keys can both be used for Symbol Shift.  Then, there
    are a lot of keys on the PC keyboard which don't exist on the Spectrum
    keyboard.  Many of them are used, to make things easier:

    The function keys have several special functions.  See the previous
    section.

    CTRL-Break and CTRL-ALT-DEL quit the emulator.  Better use F10-Q-Y
    though.

    The punctuation keys - = ; ' , .  / and their shifts: _ + : " < > ?
    have the effect of pressing Symbol Shift and the corresponding letter
    key, so you can use these in the straightforward way.

    The ESC key presses Shift-1, EDIT, used as a sort of ESC key in many
    Spectrum programs.  The Backspace key presses Shift-0, the Delete of
    the Spectrum.  CapsLock presses Shift-2, Spectrum's capslock key.

    The PC-cursor keys and the numeric keypad keys 8,4,6 and 2 control the
    Cursor, Interface 2, Kempston or user-defined joystick.  The TAB key,
    and 0,5 and ./DEL on the numeric keypad control the fire button.  If
    the Cursor joystick is selected, you can select whether Shift should
    also be pressed with the NumLock key (but see the discussion above of
    the -xs switch).

    If you're running the emulator on a slow computer, try selecting double
    interrupt frequency.  Most programs poll the keyboard by interrupt, in
    any case the ROM does, and doubling the frequency with which this
    happens will make the emulated Spectrum react much more quickly on your
    keystrokes.

    If you've got an AZERTY keyboard, the standard mappings of the keys
    won't work at all properly.  Include the switch -xz in your Z80.INI
    file in this case; many punctuation keys will now also work properly.
    There is no support for other non-US keyboard layouts; sorry!




2.4  Screen emulation


    There are two different ways the emulator can emulate the screen.  The
    standard way, in which 50 times an emulated second the screen is
    checked for changes, and they are subsequently displayed on the
    monitor. This works fine, and was the only mode available in previous
    versions. It works basically the same with all video modes; however,
    some are much slower than others. EGA is notoriously slow, due to the
    ugly way it has to be addressed. VGA is definetely the fastest. EGA and
    VGA are the only video modes in which the colour of the overscan can be
    controlled; in these modes, some emulation of border effects (loading
    stripes, for example) can be done. You don't see these effects in the
    other video modes.

    Changing the overscan colour results in 'snow' lines appearing on the
    screen.  It is possible to eliminate these by waiting until the video
    adapter is in horizontal retrace.  This takes some time, therefore the
    emulator doesn't do this in Real Mode. Real time loading requires
    minimum delay, so the screen does not update. You can select the update
    option, but you risk Tape Loading errors!

    In the standard mode, the point (relative to the 50 Hz interrupt) at
    which the screen is displayed can be controlled by setting the 'Video
    Synchronisation Mode' to normal, high or low.  If you see moving
    characters flickering excessively, try changing this setting.  For
    instance, BC's Quest for Tires won't look at all good with a wrong
    setting; many programs display subtle differences in different modes.

    In the Hercules, CGA and Plantronics modes not all colours can be
    displayed.  In EGA mode, all colours can be displayed, but some colours
    have the same intensity in Bright 1 as in in Bright 0.  Only in VGA
    mode the colours resemble closely the Spectrum originals.

    The other video emulation mode is called Hi-resolution colour emulation
    mode (HCR mode). In this mode great care is taken to display each video
    line at exactly the right time, and also the precise times the border
    colour is changed is used to build the border pattern. In this mode,
    every hi-resolution colour effect is visible; all flickering problems
    are also eliminated (provided they weren't already there on a real
    Spectrum!), so no need to adjust the Video Synchronisation Mode.

    The drawback of using this mode is that it is much slower, since the
    emulator has to keep track of the number of T states passed, and also
    has to grab a line from screen memory and put it in a buffer 192 times,
    50 times a second.  But on fast computers, 486's and up, the emulator
    can still easily emulate at 100%.

    HCR mode only works with a VGA video adapter.  Writing those routines
    also for CGA and Hercules seems silly; and I don't even want to think
    about rewriting them for EGA boards.

    Finally, when loading turbo-saved programs in Real mode, screen updates
    are suspended because they take too much time (even on fast computers).
    You can refresh the screen by pressing U - Update in Real mode, but you
    should do this only if you're sure that the emulated program is not
    loading a block, for pressing U during loading is a sure way to get a
    tape loading error.




2.5  Sound emulation


    The Spectrum beeper is emulated by the PC's internal beeper.  Because
    every 1/50th of a second the screen has to be updated, and this takes a
    little time even if there are no changes, the sound is a bit harsh.  If
    you select real mode, the emulator won't update the screen and music
    will sound good.  If you select HCR mode, the sound will be even
    harsher than it does in normal mode.

    The sound of the Spectrum 128's sound chip is played through the Adlib
    card; if you haven't got such a card some notes are played through the
    internal speaker.  That sound will be turned off, however, as soon as
    the program makes a sound through the normal speaker of the Spectrum.
    Some Spectrum 128 programs use the sound chip and the beeper at the
    same time, and this won't work properly without an Adlib card.




2.6  Loading programs from tape


    This emulator can load programs that are saved to tape in the usual
    way, but also turbo-saved programs can be loaded.  Furthermore, you can
    make a disk file act as an 'emulated tape', so that the normal SAVE and
    LOAD commands can be used to transfer data to and from disk easily.

    The emulator can load programs from .VOC sound sample files.  This is
    very useful for multi level games; the levels on the tape can be put in
    .VOC samples, and loaded when needed without having to re-install the
    tape recorder.  How to use .VOC files is described in section 2.8
    below.  The current section is about loading programs directly from
    tape.

    First of all, you need an interface to connect the tape recorder to the
    PC.  There are two ways of doing this.  You can use a tape interface on
    the LPT port.  A circuit diagram is in the DIAGRAM.Z80 program, or you
    can obtain a ready-made interface from B G Services, see section 1.2
    for more details.

    Version 3 can also use the SoundBlaster for tape input.  This is easier
    since no additional interface is needed.  The LPT tape interface
    however is more robust in loading.  When using the SoundBlaster, you
    have to be careful not to put the volume level too high, since
    otherwise the SoundBlaster will clip, which is a sure way to producing
    tape loading errors.  The LPT tape interface is not sensitive to this.

    If you want to save programs back to tape, you have to use the LPT
    interface; it is not possible to use the SoundBlaster for this.  (There
    is a way to save programs in standard format to tape though; put them
    in a .TAP file - see below - convert it to a .VOC file and play this
    sample to a tape.  Use a good sample player, one that doesn't halt for
    half a millisecond between blocks!)

    In the program DIAGRAM.Z80 a tape tester is present.  The LPT tape
    interface has to be calibrated, and this program can also be used to
    check the volume level when using the SoundBlaster as input device. The
    variable resistor of the LPT tape interface has to be adjusted so that
    the bar, which should go to 0% when the volume is down, points just
    below 50% at normal volume.  In the case of the SoundBlaster, when the
    volume is turned up, the bar first goes from 0% to 50% and over, and
    after that drops below 50% again.  The volume has to be set such that
    it is below 50% before the maximum.

    You have to tell the emulator which LPT port you use for tape I/O.  Use
    command line switch -b2 for example to select LPT2 for tape input (or
    put it in the Z80.INI file).  Use -xo to select the SoundBlaster for
    tape input.  It uses base address 0220 by default; if this is not
    correct, use for instance -xq 0240 to specify address 0240.  The
    emulator does not use the SoundBlaster interrupts.

    There are two ways to load programs: in 'real' or normal mode.  In real
    mode, the emulator doesn't update the screen or scan the keyboard, so
    that the emulated Spectrum program can run smoothly.  The emulator has
    to run at about 100%, but then you're able to load everything a normal
    Spectrum would load, including turbo-saved programs.  The only thing
    you see on screen are the loading bars in the border (on EGA or VGA
    screens).  Real mode is selected by pressing F6.  Saving programs in
    real mode is a bit useless but it works; enter the SAVE command, press
    a key to start saving and quickly press F6 when the saving starts.  It
    will continue in real mode.

    If your computer is just fast enough, don't slow the emulator down too
    much.  Because the IN instruction is relatively slow, the emulator has
    to run at about 110% for the best results.  If your computer is really
    fast, you can best slow it down to exactly 100%.  If your computer is
    just a bit too slow, you can try to make your tape recorder run slower
    too (usually you can do this by adjusting a little screw at the back of
    the motor), I successfully loaded several speed-saved programs at 90%.

    In normal mode, the standard ROM loading and saving routines are
    'trapped' (at addresses 04d8 and 056a) when they're about to start
    saving or loading.  A routine in the emulator itself then takes over,
    and loads or saves a block to tape (or a disk file, see below).

    When you enter LOAD "", the emulator starts loading using its internal
    loading routine.  You'll see a blue window appear.  Pressing F6 now
    will switch to Real mode, and the emulated Spectrum program will
    continue the loading process (if it is running at 100%).

    Every time a block is loaded or saved, a window contiaining some
    information of the block to be loaded or saved appears.  If you don't
    want this, for example because you want to enjoy the loading screen,
    specify -tx on the command line.

    Using these SAVE and LOAD routines has a great advantage as well as a
    disadvantage compared to using the Spectrum's own routines in real
    mode. The advantage is that the internal routines work on every
    machine, no matter how slow or fast, without having to make the
    emulator run at 100%.  The disadvantage at using them is that they
    obviously won't understand turbo-saved files.  For normal use, these
    internal routines work much easier, and real mode loading is only
    necessary for turbo-saved and well protected programs.

    Today, most programs are protected.  The emulation of the Z80 processor
    has to be exactly right, or those strange decoding routines that use
    all features of the processor the programmer could think of, will
    definitely crash.  It is most important to switch the R-register and
    LDIR emulation on, as virtually all protected programs use at least the
    R register.  Sometimes programs are real sensitive to the timing of the
    interrupts; if programs refuse to load, try sampling the first few
    blocks in a .VOC file (see below) and load it from there (of course
    with R register and LDIR emulation on); when loading from VOC files,
    interrupt timings are exact.




2.7  Using .TAP files


    The emulator uses files with the extension .TAP to hold a piece of
    'tape', with several blocks on it.  Each block is usually either a
    header or a data block; a normal file thus consists of two blocks.
    There are two modes of operation when loading and saving to disk files,
    single and multiple .TAP file mode.

    In single .TAP file mode, each block saved is appended to the end of
    the .TAP file, like what would happen if you were actually saving to
    tape.  In the same way, when loading in single file mode, each time the
    ROM wants to load a block, it is presented the next block in the .TAP
    file.  It is handled as it would if the block was loaded from tape, so
    that if the ROM needs a header and is presented a data block, it will
    skip it.  The header will however be considered to be read.  So,
    entering LOAD "rubbish" will show all headers in the .TAP file, just as
    an actual Spectrum would show all headers on the tape if you left the
    tape running.

    If the last block is loaded, the file pointer is moved to the start
    again.  So a .TAP file can be considered to be an infinite tape. Single
    .TAP file mode is useful to save whole programs to disk, or for
    multi-load games that need to load in levels as you play.

    A sort of 'random access' file management is also useful, for instance
    when you're developing a program and need to save several pieces of
    data to disk and later load back a specific one.  This can be done in
    single .TAP file mode (by positioning the file pointer using the Browse
    function), but there's a different mode of operation that makes things
    easier: multiple .TAP file mode.  In fact, by default the emulator is
    in this mode.

    When the emulator is in multiple .TAP file mode, it will read all
    blocks from all .TAP files in a specified directory, one after the
    other.  When it has finished reading the last one, it will start all
    over again.

    When saving, the emulator will put the two blocks of a normal file, the
    header and the data block, in one .TAP file with a unique name made up
    of the printable letters of the file name and a two-digit number.  The
    name of the .TAP file is irrelevant to the emulator, but to have it
    resemble the name of the actual Spectrum file you saved is simply
    convenient.  If the Spectrum program saves a data block to tape without
    first saving a header, the .TAP file produced will contain only this
    data block, and the DOS file name will be HDRLES, with a two-digit
    number appended to make it unique.  The format of the .TAP files saved
    in multiple .TAP file mode is exactly the same as the format used in
    single .TAP file mode.

    You can easily string together .TAP files; for instance a number of
    .TAP files created in multiple .TAP file mode can be put into one big
    .TAP file simply by concatenating them, e.g.

        COPY /B FILE1.TAP + FILE2.TAP ALL.TAP.

    Now you know what you can do, but how to get the emulator to do it?
    That's what the final section is about: the tape menu.

    Press F7 to enter the tape menu.  Pressing S will select or de-select
    single file mode.  As a default, multiple .TAP file mode is selected.
    In this mode there are three other possible choices in the menu.  First
    of all, D selects a tape-file directory where the .TAP files will be
    saved into and loaded from.  A default directory can be selected by
    putting the -xs switch on the command line or in the Z80.INI file; for
    example -xs c:\spectrum\taps.

    The I and O options are used to select the source and destination of
    the saving and loading: the LPT port (in/out) or SoundBlaster port
    (only input) for a physical tape recorder, or 'disk' for disk files.
    Input and output are directed to disk by default if a default tape file
    directory is given by means of a switch on the command line or .INI
    file.

    If Single .TAP file mode is selected, different and more menu options
    appear.  With R and W, the input and output tape files can be selected.
    They may be the same.  If a specified output file already exists, you
    may choose to append to or overwrite this old file.  Saving is always
    at the end of the file; loading always starts at the beginning of the
    .TAP file.

    With the B option - Browse - the position of the file pointer into the
    input .TAP file can be changed.  If you, for instance, type LOAD""
    instead of LOAD "" CODE, the first header is read, and you would have
    to read all other headers before trying to load the file again.  With
    the browse option you can conveniently change the file pointer.  Of
    every header (that is, every block with flag byte 0 and length exactly
    17) the name and type, and of every data block the length is shown.

    The option B can also be used to delete specific blocks from a .TAP
    file.  Make sure you do not only delete a data block or a header, or
    the ROM may get confused.  (Double data blocks will be skipped, but
    double headers can generate Tape Loading errors).

    As in multiple .TAP file mode, I and O are used to specify the source
    and destination for saving and loading.  If you enter a .TAP file name
    with R or W, this will automatically be set correctly.  You can then
    always reset the input or output back to physical i/o again, of course.

    Finally, in Single .TAP file mode you can use 'tape mirroring': loading
    programs from tape (in normal mode, i.e.  not using Real mode) and at
    the same time saving a copy of each block loaded into a .TAP file. This
    .TAP file can later be used to load the program again, in case
    something goes wrong.  There are two ways of mirroring: normal
    mirroring and exact mirroring.  The last one must be used only in
    exceptional cases; it will always make a copy of a block, even if it
    had a tape error (the corresponding block in the .TAP file will also
    have a tape error).  This causes ticks in leader tones to make 0-byte
    blocks, so the .TAP file may get messy.  Do not use exact mirroring if
    you don't really have to; I think normal mirroring will always work in
    practice.

    If you try to leave the tape menu when for instance tape mirroring is
    selected, and no output filename is given, the emulator will warn you
    and will insist that the error be corrected.  Yes, it's stubborn!

    One final point about multiple .TAP file mode.  If you select a
    directory that contains no .TAP files at all, and try to load from the
    directory, the emulator will reset itself to physical tape I/O.  Select
    a different directory and try again.  Note that simply putting a .TAP
    file in the directory does not reset the emulator to multiple .TAP file
    mode, as it will not look in the directory again as soon as it uses
    physical tape I/O.




2.8  Using .VOC files


    .VOC files contain sound samples, so they can also contain the sound of
    a computer tape.  The emulator can load programs from these sound
    sample files, by keeping track of exactly how much time elapses during
    the emulation of a program, and every time the emulated Spectrum
    program reads the EAR port, supplying it with the right sample.  Via an
    intermediate file, a .OUT log file, the emulator can also SAVE and
    produce a .VOC file with the right sounds in it.

    In this section .VOC file playback is discussed.  For a discussion of
    how to SAVE to a .VOC file, or how to produce a .VOC file of
    Spectrum-generated music, please read section 2.18 about the OUT2VOC
    utility.

    Because the emulator has to keep track of the emulated time, and also
    has to do some calculation every time the EAR port is read (which a
    program does rather often when loading), the emulation speed drops
    considerably (by a factor of two, roughly) when playing back .VOC
    sample files.  So loading programs using VOC files may take longer than
    loading them directly.  On the other hand, it is not at all necessary
    to have the emulator run at 100% now, so that even slow computers can
    load turbo-saved programs, provided that they can read samples.  And on
    fast computers, the emulator can be set at the maximum speed, to load
    programs much faster than usual.

    Using .VOC files is sensible for instance when you have a multi level
    game, where subsequent levels are saved in a non-standard format, so
    that they cannot be stored in .TAP files.  The higher levels can be
    stored in .VOC files, and loaded when needed, without having to
    re-install the cassette player.

    You can take a sample with any sampler program.  The emulator supports
    most VOC block types.  It does not support compressed blocks, though;
    use full 8 bit samples.  The problem with a lot of sampler programs is
    that they leave a small gap between subsequent blocks within the .VOC
    file.  This gap is usually inaudible, but it causes tape loading
    errors.  It is very important that the sample is taken without any
    gaps.  The READVOC program reads samples from the LPT tape interface or
    the SoundBlaster, and can take long continuous samples without gaps.
    Because the emulator converts the 8-bit sample to a simple High or Low
    value, READVOC also uses only two values for the signal height.  This
    results in highly compressible .VOC files; compression factors of about
    25 are no exception.

    It is also possible to convert .TAP files to .VOC files, with the
    utility TAP2VOC.  This was useful to test the .VOC playback feature,
    and also makes it possible to write .TAP files back to tape using a
    sample player.

    To play back a VOC file, press F7 to go to the tape menu, and press P
    to select the VOC file playback menu, and enter the name of the VOC
    file to be played. The VOC file is now in stand-by. Just for
    convenience, the emulator starts playing back the VOC file as soon as
    the ROM loading routine is hit; that is, as soon as you type LOAD ""
    and ENTER.  The emulator will now play the VOC file to the end
    (irrespective of what the emulated Spectrum program is doing with the
    sound supplied to the EAR port!).  When the end is reached, it will
    alert the user, and switch back to normal emulation mode.

    It is possible to pause the play-back at any time.  Do not do this
    while loading, since it will immediately result in a tape loading
    error.  It is also possible to start play-back without LOAD "", which
    is necessary for instance when the VOC file consists of a turbo-saved
    block.

    And finally, it is possible to wind and re-wind the VOC file, as if it
    were a tape.  The position is displayed in minutes, seconds and
    hundreds of seconds.







2.9  Multi-load games


    Some games have several levels saved on the tape, to be loaded when a
    previous level is completed.  There are several ways to handle these
    programs.

    First, simply playing it, and loading next levels using a real
    tape-recorder seems a good solution.

    If the data blocks in which the level data is saved are written to tape
    in the standard format, you can convert them to .TAP files.  It is most
    likely that the program uses the usual ROM routine to load the blocks,
    and this routine is trapped by the emulator, so that instead of loading
    from tape, the blocks can be loaded from these .TAP files.  To convert
    the blocks to .TAP file, use a standard tape-to-tape copy program and,
    in the Tape menu (F7), specify that tape output should go to some file.
    If the blocks are just code blocks with header, simply enabling the
    Tape Mirroring option and loading the blocks at 16384 (ignore the
    crashes that most probably result; just reset the emulator and
    continue) will do the trick.  If the blocks are headerless, then go to
    the SamRam, press NMI (F5), D for Disassembler, and L:4000 (with tape
    mirroring enabled) to load and mirror each block.  Here also, ignore
    possible crashes which result if the block is too long.

    A general method is to store the level data blocks in .VOC sample
    files.  These files are huge, lengths of several megabytes are common,
    but they can be compressed very tightly (if you used READVOC to make
    them). Then, if you need a block, simply shell to DOS, decompress it,
    and load it.

    Finally, if you want to hack into the program, you can also try to find
    the routine that is responsible for the loading of a level.  At the
    appropriate point, enter an ED F6 instruction, with A containing the
    level number, and HL the address at which the block is to be loaded.
    The emulator will then look for the relevant file and load it.  The
    name of this file is the name of the snapshot last loaded, where the
    level number (in decimal) is appended to the end.  If this results in
    more than 8 characters, the shapshot name is made shorter.  The
    extension of these files is always .DAT.  If the file is not found, the
    user is informed of the level number, and given the opportunity to
    specify a name.

    This ED F6 feature first appeared in XZX 0.5.2, and was devised by
    Russel Marks.




2.10  Using the microdrive


    Compared to the tape, this is really simple.  Cartridges are emulated
    by files of 137923 bytes.  These files have the extension .MDR, and can
    contain up to 126K of data.  The emulator emulates 8 microdrives, the
    maximum amount the Interface I software can handle, and each of these
    cartridge files can be inserted in any of the 8 microdrives.  (Do not
    insert one file into more than one microdrive; this will cause problems
    with the buffering done by the emulator as well as the Interface I, and
    might result in data loss).

    Press F8 to enter the microdrive menu.  Press 1 to 8 to select a
    microdrive, and I to insert a microdrive cartridge.  You can select an
    existing one, or type a new name.  If the cartridge file isn't found,
    the emulator asks whether it should create it.  When created, you'll
    have to format it first; if you don't, you'll get a 'microdrive not
    present' error when you try to read it, just as happens with real
    unformatted cartridges.  To format a cartridge, type

        FORMAT "m";1;"name"

    After this the cartridge should have 126K of free space.

    The cartridge can be write protected; see the menu option in the F8
    menu.  This is a characteristic of the cartridge, and the write protect
    tab information is therefore stored in the cartridge file.

    As on the real Spectrum, you'll have to be careful with OUT's if a
    cartridge is inserted.  Try OUT 239,0 (on a real Spectrum, this turns
    on the microdrive motor) and wait a few seconds; most of your data will
    be lost!  You can stop the microdrive motor by typing STOP (or, more
    generally, generate an error).

    The microdrives are emulated at IN/OUT level.  This means that every
    utility or program that uses microdrives ought to work on the emulator.
    Most utilities use hook codes, and these will certainly work.

    The GAP line is emulated; this signal is activated if the interface I
    senses a piece of tape with no data on it.  If the checksum of the
    first header block of a microdrive header or data block is not correct,
    that block is considered to be a GAP.  This will only happen if some
    utility writes a bad block to microdrive deliberately, if the file is
    newly created and unformatted, or when you type OUT 239,0.

    To try the microdrive, load a Spectrum program, switch to Spectrum
    48K+If.1 mode if necessary, and turn on Multiface 128 emulation.  Press
    F8, I(nsert cartridge), enter some file name and create an unformatted
    cartridge, return to the Spectrum and press F5 (NMI), S(ave), enter
    some name, choose M(icrodrive), choose F(ormat) and wait a few seconds,
    then choose S(ave).  Then reset the Spectrum, and type LOAD
    *"m";1;"name" to re-load the snapshot you just made.

    Alternatively, switch to SamRam mode, make sure a formatted cartridge
    is present, press F5, S, M, S, name, and press ENTER twice to have the
    SamRam save a snapshot to microdrive.  This snapshot can only be loaded
    in SamRam mode.




2.11  Using the DISCiPLE and Plus D interfaces


    For an explanation of the commands of the DISCiPLE and Plus D
    interfaces, see the relevant sections in chapter 4.

    The ROM of the DISCiPLE is supplied with the emulator, together with
    two version of the D.O.S. pre-loaded in RAM.  The ROM of the Plus D
    interface is not supplied, for copyright reasons.  The emulator will
    only emulate a Plus D interface if it can find a file PLUSDROM.BIN in
    the emulator's own directory.  If you have a Plus D yourself, you can
    transfer the ROM in the following way.  Load the operating system from
    a Plus D system diskette, and save the entire ROM, together with the
    operating system, to disk by entering SAVE d1"rom" CODE 0,16384.  Then,
    start the emulator and choose hardware mode Spectrum 48K + Disciple
    (not Plus D of course), then type LOAD d1"rom" CODE 32768.  Finally,
    press F10, X, S for Save Data block, set start address and length to
    8000 and 4000 (hexadecimal) respectively, and save the ROM under the
    name PLUSDROM.BIN.  If you re-start the emulator now, it will emulate
    the Plus D too.

    The emulation of the DISCiPLE or Plus D interfaces in turned on simply
    by choosing the right hardware mode in the F9 menu.  Changing the
    M.G.T. type will result in a Spectrum reset (unless you change with
    CTRL-ENTER), since a different ROM is switched in.

    By default, disks 1 and 2 refer to drives A: and B: respectively, but
    this can be changed in the F8 menu.




2.12  Using the Multiface 128


    The following is an excerpt from the original Multiface 128
    documentation:

    MULTIFACE is a registered trademark af RORANTIC ROBOT.  Multiface 128
    is a true multi-purpose interface with

    1) fully universal and 100% automatic back-up facility for tape,
       microdrive, Discovery, Plus D or Disciple (although the Discovery is
       not emulated, so that that feature is not usable),
    2) 8K RAM extension - suitable for GENIE, LIFEGUARD, or as a buffer,
    3) MULTI TOOLKIT to study/modify/develop programs, POKE infinite lives,
       etc.

    Multiface 128 works on the Spectrum 48/128.  It can be used any time in
    any mode; it is immaterial what is inside the Spectrum at that moment
    or how or from what source (tape, disk, cartridge) it has been loaded
    (or typed in, etc.).  Multiface does not save programs, but computer
    contents (compressed RAM image).  Upon returning from the M128 or upon
    re-loading, the programs continue as if never frozen.  To use the M128:

    1) Push the NMI key (F5)
    2) Select the required option from the menu

    The MAIN MENU options are:

    Exit: to abandon the Multiface and exit to BASIC (provided BASIC is
      present).  By using exit, you come out of the Multiface entirely.
      All efforts are made to preserve the current program in the Spectrum
      intact.  The main condition is the existence of standard system
      variables - without these the Spectrum crashes.  A successful exit
      gives you full access to the program.  To restart it, if needed, you
      must know the starting line or address.  Exit is impossible in the
      128K mode when the edit ROM is paged and Spectrum ROM is off; in such
      cases it does not appear on the menu at all.  All in all, you can
      only exit to BASIC if it exists - it is like jumping into a pool: a
      joy if it's full of water, a crash if there is none.

    Return: to continue the program.

    Save: to proceed to the SAVE routines:
      a) input the name of the program.  Up to 9 characters (or just press
         ENTER to the input RUN automatically as a default)
      b) save to: Tape, Microdrive, Opus [does nothing], Disciple (use D
         for Plus D too).  You can save the entire program (including the
         screen), or the screen only.  Programs are compressed to take the
         minimal room possible and to load faster.  Screens saved on their
         own are left intact as standard Spectrum screens.
      c) Format microdrive cartridges.  Cartridges are automatically named
         after the programs to be saved.

    Tool: to access the MULTI TOOLKIT routines.
      quit - to return to the main menu
      Enter - to PEEK and scroll through addresses or to POKE
      Space - to allow you to type in a new address
      hex - to toggle between hexadecimal and decimal display format
      reg - to point to the Z80 registers as they were when the program was
        frozen
      window - to open a window with full on-screen editing using the
        cursor keys.  The flashing window address corresponds to the
        address in the bottom edit line.  The window display is by default
        in hex, but you can change it to
      text - to see the 128 bytes in the window as ASCII text.
      select - to inspect RAM banks 0-7 in 128K mode.  Press s + the bank
        number

    Print - to dump screen to printer.  For printer interfaces using COPY
      command.  You can POKE address 8200 (decimal) with the following
      values, if you wish to
      113 to turn the line feed on (cr+lf)
      112 to turn the line feed off (cr)
      17 to dump screen as text with the line feed on
      16 to dump screen as text with the line feed off

    Jump - not to return, but jump to another address.  Strictly for
      machine code users only.  Enter the address to jump at 8192/3
      (low/hi).  You can jump to Spectrum ROM/RAM and to M128 8K RAM.  As
      the M128 overshadows the ZX ROM (8192-16383), address 8194 determines
      the paging status: if it is 0, the M128 RAM remains paged, 1 pages
      out the RAM and any other value disables the jump command completely.
      [Note: if it is 0, also the M128 ROM (0-8191) remains paged.]

      You can jump from the main menu, and you can also pre-program M128 to
      jump directly upon NMI (F5) and by-pass the M128 ROM software
      entirely.  To program the direct jump, POKE 8192-3 with the jump
      address, and then also 8195-7 with a special identification word RUN
      (i.e. 82,85,87).  Whenever you press NMI now, you will jump to the
      predefined address and not see the M128 menu.  To return from your
      program to the program you stopped, use RST 0.  To revert back to the
      Multiface normal operation, press NMI and BREAK (shift+space)
      simultaneously.  This also cancels the code word RUN.

      In standard mode M128 uses 8192-11144 as a buffer (8192-13496 once
      you proceed to SAVE) and overwrites anything in there.  Using direct
      jump, you have 8257-16338 available.

    Clear - to clear the extra 64K RAM bank (in 128K mode only!).  You can
      clear any time, but it is only useful with 48K programs in 128K mode.
      However, you should save 48K programs in 48K mode anyway.  Also, for
      obvious reasons, clearing the banks in 128K programs is not a good
      idea.


    The actual M128 has a software on/off switch, so that it could be made
    completely invisible to programs until the NMI switch was pressed. This
    software switch is not emulated.  The M128 could be turned off by
    pressing 'O' in the main menu; this does not work on the emulator.  You
    can turn off the M128 in the Select Hardware (F9) menu.

    Using the extra 8K RAM - M128 has an 8K Rom containing its own
    software, and an 8K RAM used as a buffer.  You can use the 8K RAM for
    your own mcode routines or for data (but not for BASIC).  The RAM must
    be paged in machine code to be accessed: use IN A,(191) to page in, and
    IN A,(63) to page out.  The BASIC In and Out commands can not be used
    here (they work, but result in a crash).  The 8K RAM overshadows the
    Spectrum ROM and thus anything contained in the M128 RAM cannot make
    any calls to the Spectrum ROM, as they both occupy the same area. The
    M128 RAM routines should therefore be self-contained, independent of
    the Spectrum ROM.

    Poking infinite lives - To POKE, say 31000,0, first load the program as
    usual.  When it's loaded, press NMI (F5) and select the tool by
    pressing T.  When the toolkit menu appears, press SPACE and type 31000.
    Once you type 5 digits the cursor automatically moves to the value
    field (no need to press ENTER), so type 0 (value is 1-3 digits long)
    and this time press ENTER.  Finally press Q to quit the toolkit and R
    to return to the program.


    The Multiface 128 was designed by Romantic Robot UK Ltd, 54 Deanscroft
    Avenue, London NW9 8EN, tel. [phone].




2.13  Using the RS232 channel


    This was the only Spectrum i/o channel that could be used in the early
    versions of the emulator.  Using .TAP files instead of the RS232
    channel is often easier, but sometimes using the RS232 channel can be
    very useful too, for instance if you've got a null-modem lead that
    connects a Spectrum with interface I to the PC you can use it to
    transfer data and programs easily.  Furthermore, the RS232 channel is
    the easiest way to let the emulator communicate with a PC printer.

    Several things send their output to the channel designated as 'RS232
    output channel'.  First of all the ordinary Interface I RS232 "B" and
    "T" channels.  Secondly the 128K printer "P" channel.  Thirdly, ZX
    Printer output is converted to a format appropriate for Epson or HP PCL
    printers (works for most dot matrix, and most laser/inkjet printers
    respectively) and also sent to this channel. Input from the 'RS232
    input channel' is sent to the Interface I's "B" and "T" channels.

    The Interface I RS232 port, the "B" or "T" channel, behave slightly
    differently.  The first, binary, channel is the raw channel.  It will
    let all data go through unchanged.  The "T" channel won't let all
    control codes through and will expand any keyword; useful for LISTing a
    program but otherwise annoying.

    The Spectrum 128 has its own RS232 port; it is called the "P" channel.
    Output to either the Interface I's or Spectrum 128's own RS232 port
    will all be processed as 'RS232 output'.

    The output to the RS232 channel can be routed to an LPT port, to a COM
    port or to a file on disk.  Input can come from either a file or a COM
    port.

    If you want to use the RS232 channel for printing using LPRINT and
    LLIST (shorthand for PRINT #3 and LIST #3), be sure to open that
    channel for output to RS232; by default it sends its output to the ZX
    Printer, which is not supported.  You can open the channel by typing
    OPEN #3,"B" (or "T" for listings, or "P" on a Spectrum 128).

    Input and output are buffered.  This is important to remember when
    you're transferring files using the SAVE and LOAD *"b" commands of the
    Interface I.  If the header is missed, for instance if you try to load
    the wrong file type, re-sending the file will not directly work because
    there will still be bytes in the buffer.  You have to clear the input
    buffer before re-sending the file.  When inputting from a disk file,
    the file pointer can be reset to point to the start of the file again
    to re-read the header.

    When inputting from or outputting to a disk file, the read or write
    position is displayed as a byte-count.  An <EOF> sign will appear if an
    input file is read completely through to the end.

    The RS232 redirection options are in the Change Settings (F4) menu.

    When using a COM port, make sure you have initialised it before
    starting the emulator with the Dos MODE command, for instance

        MODE com1:96,n,8,1

    initialises COM1 to send and receive at 9600 baud, no parity, 8 data
    bits and 1 stop bit, the default for the Interface I.

    Here is how to transfer programs from a Spectrum to the PC using the
    RS232 lead.  First, you need a null-modem lead.  I myself use the
    following cable:

          Spectrum                                  'AT'      'PC'
          (9 pins)                                (9 pins)  (25 pins)

            3 TxD   ───────────────────────── RxD     2         3

            4 DSR   ───────────────────────── DTR     4        20

                                        ┌──── CTS     7         4
                                        └──── RTS     8         5

            7 GND   ───────────────────────── GND     5         7

    (so CTS and RTS have to be connected!)  This is not a full null-modem
    lead; you can only send data from the Spectrum to a PC.  If you have an
    Interface I, you can use the LOAD *"b" and SAVE *"b" commands on both
    your real Spectrum and the emulator to transfer programs and data. It's
    best to first type LOAD *"b" and then SAVE instead of the other way
    around.  If you have problems with transferring data, try to lower the
    baud rate to 4800 or 2400 baud; this sometimes helps.

    If you don't have an Interface I, but do have a printer interface using
    RS232 leads, then you can transfer data using LPRINT on the Spectrum
    side, and INKEY$ #3 on the emulator side.  It needs a little bit of
    programming.




2.14  On joysticks and mice


    The emulator support several joysticks and the Microsoft mouse, to
    control several Spectrum joystick interfaces, and the AMS Mouse
    interface.  First, joysticks are discussed.

    As was already said in the introduction, the emulated Spectrum joystick
    (Cursor, Interface 2, Kempston or user defined) is controlled by the PC
    cursor keys and 5/0/.  on the numeric keypad and TAB as fire keys.  The
    emulated joystick can also be controlled by a mouse, or by a real
    joystick, either analogue (PC standard) or digital.

    The analogue joystick support is rather straightforward.  If you've got
    one, it works - it couldn't be simpler.  The digital joystick support
    is less obvious, since PC's don't support these.

    To use digital joysticks, Ruud Zandbergen has made a device that uses
    the two inputs of a normal analogue joystickinterface to connect a
    digital joystick to a PC.  Here's the circuit diagram:


    15 pins male  (pc)                           9 pins male (joystick)


    1+9 <─────────┬───────────┬────────────┬─────────────┬──> 7 (5V)
                 ┌┴┐         ┌┴┐          ┌┴┐           ┌┴┐
        4 x 1 kΩ │ │ ¼ Watt  │ │          │ │           │ │
                 └┬┘         └┬┘          └┬┘           └┬┘
    3   <─────────┴──> 4 (up) │            │             │
                              │            │             │
    6   <─────────────────────┴──> 3 (dwn) │             │
                                           │             │
    13  <──────────────────────────────────┴──> 1 (rght) │
                                                         │
    11  <────────────────────────────────────────────────┴──> 2 (lft)
                       ┌────────────────────┐
    2   <──────────────┤    47 Ω ¼ Watt     ├───────────────> 6 (fire)
                       └────────────────────┘
    4+5+14 <────────────────────────────────────────────────> 8 (0V)


    4+5+14 means: connect pins 4, 5 and 14.  The same applies for pins 1 and
    9.  Here's the list of ingredients:

        1 x 9 pins D plug, male
        1 x 15 pins D plug, male
        4 x 1kΩ , ¼ Watt resistors
        1 x 47 Ω, ¼ Watt resistor
        piece of 7-wire flatcable

    Everything can be fitted into the 15-pins plug. Make sure the resistors
    don't touch the other blank connections! This interface can be used for
    all usual digital joysticks, with or without auto fire (that is every
    joystick that work with a Kempston joystick interface, or that work on
    a Commodore 64/Amiga or Atari). The joysticks for the Spectrum +2/+3
    will not work, however the pin layout is easy to change.

    This joystick interface needs an analogue PC-joystick interface on
    which you can connect TWO analogue joysticks (on one plug!).  Most
    cards can do this, but some multi-I/O cards support only one joystick.
    Check the documentation of your I/O card to see whether your
    joystickinterface is suitable.  The soundblaster joystick interface
    works fine.

    A number of PC games will behave strangely when the digital joystick
    interface is connected; they run very slow or crash.  When this
    happens, remove the joystick interface (not only the joystick!).

    With version 3, the Spectrum joystick (Cursor, Kempston, Sinclair 2 or
    user defined) can not only be controlled by the cursor keys or a real
    joystick, but also by a mouse.  Specify -km on the command line to have
    the mouse control the joystick too.  (By default, this switch is
    already in the Z80.INI file.)

    Finally, the Microsoft mouse can control the AMS Mouse interface, as
    supported for example by Art Studio.  Specify -ka on the command line
    to select this option.  The mouse will not control the joystick
    anymore.  Because of I/O address clashes, the AMS Mouse does not work
    with SamRam or an M.G.T. interface enabled.  Also, since the AMS
    interface must be initialized, and the state of the AMS interface is
    not saved in the .Z80 snapshot file, it may be necessary to make the
    snapshot before the point at which the Spectrum program initializes the
    AMS interface.  The program Art Studio re-initializes the AMS interface
    regularly, however, so with this program you don't have to worry about
    it.




2.15  The utility ConvZ80


    This program converts between various snapshot formats, and it can also
    convert various tape file formats to .TAP files.  Currently it supports
    .SNA format (used in various emulators, such as JPP, Peter McGavin's
    emulator on the Amiga, and XZX), the .SP format of VGASPEC and
    SPECTRUM, the .PRG format of SpecEm, and all old .Z80 file formats.

    If conversion is to a .Z80 file, the old (v1.45) format will be used.
    This is still supported by the emulator, and some other programs do not
    support the new format.  Note that, because of this, ConvZ80 will not
    convert .Z80 files containing snapshots of 128K or SamRam programs.

    CONVZ80 recognizes what it should do by the extension of the files you
    enter on the command line; to distinguish between VGASPEC's and
    SPECTRUM's .SP formats you can use the switch -o.  If the extension
    consists of digits only, it is taken to be a ZX tape file, and if it
    contains non-digits and is none of .SP, .Z80, .SNA, .PRG or .TAP it is
    regarded as a SpecEm tape file.

    SpecEm can load .PRG snapshot files, but cannot save them.  However, it
    emulates the Multiface I, which can save snapshots to tape.  SpecEm
    will save these blocks as tape files to disk.  If you convert these to
    a .TAP file (in the correct order!), you can load them into Z80 and
    save the program as a .Z80 file.




2.16  Converting file formats - the utility CONVERT


    This section is about the utility CONVERT, which can convert some of
    the Spectrum's own format into each other, and also converts some of
    the emulator's formats into others.  It is not about converting files
    from other emulators; read section 2.15 if you want to know about that.

    CONVERT was useful when the emulator could only communicate with
    snapshot files and the RS232 link.  It has become less useful now, with
    .TAP files and the possibility to load and save blocks directly into
    and from Spectrum memory, but it still has some useful features.

    It can read three types of input files: pure ASCII, pure bytes (for
    instance a .SCR screen dump), and files produced by a SAVE *"b"
    command.

    Output is pure bytes, ASCII with either CR (Spectrum standard) or CR/LF
    (PC standard) for line breaks, SAVE *"b" files containing a Basic or
    code file, a .PCX or a .GIF file.

    So what can you do? Main uses are adding LF (10 hex) bytes to a text
    file produced by the Spectrum; converting a code block into a SAVE *"b"
    to load it into the Spectrum using LOAD *"b" (and the reverse of
    course: converting a SAVE *"b" file to pure bytes), and converting a
    screen dump to .PCX or .GIF graphics files.

    Less useful, but possible: LISTing a program (SAVE *"b" file) to
    produce readable ASCII, and the reverse: converting an ASCII listing to
    executable Basic again.

    If you want to make a .PCX or a .GIF file, input should be a SAVE *"b"
    file of a screen (length 6921 bytes exactly) or a bare .SCR screendump
    (length 6912 bytes).  You can make screendumps by selecting the X-Extra
    functions menu from the main menu.




2.17  The utilities Z802TAP, TAP2TAPE and TAP2VOC


    The SamRam has built in it some snapshot software.  Using this software
    you can save any 48K Spectrum program to tape or to a .TAP file, as is
    explained in section 3.2 below.  But the SamRam software cannot handle
    a 128K program.  The Multiface 128 can also write a snapshot to tape,
    but in some cases it is still preferrable to use TAP2TAPE, since the
    latter produces less and shorter blocks, and doesn't corrupt the screen
    as much as the Multiface code does (on Spectrums without Multiface).

    The utility that can convert a 128K snapshot (and 48K ones for that
    matter) to a .TAP file is called Z802TAP.  The .TAP file includes a
    basic loader, and a loading screen if you want.  Z802TAP compresses the
    blocks it writes (using a better method than used in compressing .Z80
    files) to save loading time.  If you don't want it to compress the
    blocks, for instance when you want to take a look at the ram pages of
    the Spectrum 128, specify -u when you run Z802TAP.  You can load the
    converted program simply by executing

        Z80 -ti tapefile

    and typing LOAD "" (for a 48K program) or changing the hardware mode to
    Spectrum 128 and choose 'Tape Loader' in the menu.

    Of course you could also use Multiface 128 or the SamRam to convert a
    snapshot to a .TAP file.


    The program TAP2TAPE writes .TAP files back to tape.  The program
    consists of a batch file TAP2TAPE.BAT, which executes the TAP2TAPE.Z80
    file using the emulator.  The .TAP file is written to tape exactly as
    it is, so that if a block contains a tape error, it won't load
    correctly from tape either.  If the entire .TAP file has been saved the
    emulator will start loading from tape.  At that point, press space once
    to return to DOS.

    The TAP2VOC program converts the tape block in a .TAP file to the
    corresponding bips and clicks.  The resulting .VOC file will be rather
    large.  It can be loaded back into the emulator, which is rather silly
    since using the original .TAP file is better in all respects, or you
    can write the program to tape using a sample player.




2.18  The utility OUT2VOC - and how to make .OUT files


    The emulator can log OUTs to any I/O port.  These OUTs are logged in a
    .OUT file, in which is stored what was written to which port at what
    time.  These log files are used for recording sounds the emulated
    Spectrum produces.

    The OUTs to port FE, which controls the internal beeper, and those to
    ports BFFD and FFFD, which control the soundchip of the Spectrum 128,
    are translated into a sample file by OUT2VOC.

    There are a number of command line switches.  The sample frequency can
    be chosen by specifying "-f frequency" on the command line.  By default
    a sampling frequency of 10 kHz is used.

    Ordinarily the OUT2VOC program filters out all frequencies above half
    the sampling frequency, so that no aliasing occurs when the signal is
    stored as a sequence of samples in a .VOC sample file.  For sample
    files containing tape data, these aliasing effects are not important.
    For these sample files you can use -d to produce 'digital' sample
    files, containing only 'high' and 'low' sample values, and nothing in
    between.  These sample files can also be compressed much better.

    By default, the OUT2VOC program listens to the EAR output only.
    Specify -m to have it listen to the MIC output (only), and -a to have
    it listen to the AY-3-8912 soundchip of the Spectrum 128.  If you
    specify for example -e -a, the program will listen to both
    corresponding channels.

    Usually, not all registers of the AY soundchip are updated continually.
    Some registers are initialised and left at that.  So usually it is
    necessary to supply the initial values of the soundchip registers.  Do
    this by specifying '-i file', where 'file' is the snapshot taken just
    before the OUTs were recorded.

    Some Spectrum programs use extremely many OUTs to produce sounds.
    Fairlight for example OUTs about 70000 times a second, thereby indeed
    producing one of the finest music I've every heard coming out of an
    ordinary Spectrum.  The OUT2VOC program takes quite some time to
    compute the .VOC file from the raw .OUT output.  Use -q for a quick
    and little less precise conversion.  The difference seems to be barely
    audible.  This switch has no effect when converting '128 music.

    If you specify -s, silences of longer than 1 second will be truncated
    to 1 second.

    Finally, use -r to produce a raw sample file, without any header or
    length info.

    To record a sample, go to the Extra Functions menu (F10, X), and select
    O.  Select the ports you want to log (by default only FE is logged) and
    enter a name for the log file.  OUTs will be logged until you specify
    an illegal name, or press ENTER on an empty line here.

    To save a block of data to a .OUT file, simply type the right SAVE
    command or use any (turbo-save) program to save it to tape.  Note that
    .OUT files tend to grow fast; one bit on the tape corresponds to two
    OUTs and therefore two 5-byte entries in the .OUT file; an 48K file
    will produce a .OUT file of at least 4 Megabytes.

    If you give a 16 bit address for an I/O port, only OUTs to this address
    will be logged.  If you give an address smaller than 100 hex, all
    addresses whose low byte equal this number are logged.  Note that it is
    not possible to log all OUTs to, say, an even port.  Although the MIC
    and EAR ports respond to all even port addresses, virtually no program
    uses a port different from FE, so this will be no problem in practice.

    Note that whereas the 'official' addresses of the register and
    value-port of the AY soundchip are FFFD and BFFD respectively, some
    programs use other ports that work too.  One particular program uses
    BEFD, heaven knows why.  For these programs, specify FD (or 00FD) as
    OUT port to log; this will ensure that all OUTs to any address with low
    byte FD is logged (which, alas, includes the much-used port 7FFD).




2.19  Quick overview of command line switches, and features


    In this section I will briefly explain all command line switches.  It
    is useful to at least once read this section carefully; there are a few
    small handy features that will otherwise be readily overlooked. Starred
    switches are by default put in the Z80.INI file.

       -h        Hercules graphics
       -xh       Extended Hercules graphics
       -p        Plantronics graphics
       -q        Plantronics, different palette
       -c        CGA graphics
       -e        EGA graphics
       -v        VGA graphics

    Usually the emulator will by itself correctly determine which mode to
    use.  VGA mode is by far the best: it is the only mode in which all
    colours are correct (including the bright hues), and it is also the
    fastest mode.  On old computers with only an Hercules adapter, extended
    Hercules will usually give much better results.

       -xv       400-line VGA (for some Tridents)
       -xb       Black-and-white VGA

    The black-and-white switch is useful on black-and-white monitors;
    sometimes those only display one component of the RGB signal instead of
    a weighted average, so that some colours become indistinguishable grey
    tones.

    Some Trident video adapters, as well as some others, have a bug in
    their video BIOS: they don't want to be put in 200-line mode.  To get
    around this, when -xv is specified 400-line mode is used with a double
    amount of lines.

       -n        Emulate Spectrum without Interface I
       -s        Emulate Spectrum with SamRam
       -1[28]    Emulate Spectrum 128 (can be used with -n)
       -xk       Emulate Multiface 128 interface  (can't be used with SamRam)
       -9        Default to M.G.T. interface instead of Interface I
       -0d       M.G.T. = DISCiPLE ROM (default)
       -0p       M.G.T. = Plus D

    These switches select the default start-up hardware configuration of
    the emulator.  This can all be changed in the Change Hardware menu
    under function key F9.

    *  -znnn.n   Emulate the Spectrum at speed nnn.n%

    The most sensible setting for this is -z100.  By default this is done
    in the Z80.INI file.

       -xx       Hi-resolution colour emulation

    This selects hi-res colour emulation by default, so that border effects
    and hi-res colour effects are visible.  This setting can be changed in
    the F4 menu.

       -r        Emulate the R register

    This is usually necessary in turbo loaders and otherwise protected
    programs, since they almost invariably use the R register to decode
    things.  The R register has to be updated every instruction, so that
    enabling the emulation of it reduces the emulation speed considerably,
    by some 30%.  Don't do it unless it proves to be necessary.  I don't
    know of any program that uses it on the run.  If the R register is not
    emulated, the R register acts as a random generator.

    *  -l        Better (but slower) LDIR/LDDR emulation

    Normally a 8086 MOVSB is used to emulate an LDIR or LDDR.  This is a
    fast instruction.  Programs that use them a lot, most notably Jetset
    Willy and Manic Miner, run very fast.  On slow computers these programs
    are the only ones that are really playable.  On fast computers they run
    much too fast, so it is a wise thing to use -l on fast computers.
    Secondly, without -l the LDIR instruction is not emulated correctly
    when it overwrites itself; with -l it is.

       -yl, -yh  Low, high video synchronization mode

    These switches control the phase between the 50 Hz interrupt and the
    screen refresh.  Some programs need a different setting in order to
    remove flickering of moving characters.  Enabling hi-resolution color
    emulation also eliminates these problems.

       -2        Emulate an Issue-2 Spectrum

    Make the EAR line 1 when there's no signal, instead of 0 as it is on
    Issue 3 Spectrum's.  Some old programs need it (Spinads for example).

       -d        Double interrupt frequency (100 Hz)

    On slow computers this may help to get the keyboard to respond better.

       -aN       Redirect Spectrum RS232 output to LPTn
       -oN       Redirect Spectrum RS232 output to COMn
       -uF       Redirect file F to Spectrum RS232 input
       -iN       Redirect COMn to Spectrum RS232 input
       -wF       Redirect Spectrum RS232 output to file F

    All output to, and reading from, the Interface I's RS232 channel
    (channels "b" and "t"), the 128K printer channel (channel "p") will be
    sent to, respectively read from, the appropriate device.  Furthermore,
    output to the ZX Printer will be converted in a format suited for Epson
    matrix printers or HP Laserjet printers and also be sent to the 'RS232
    output' device or file.

       -g        No sound
       -xa       Do NOT use AdLib for 128 sound
       -xc       Use SoundBlaster CMS chips for noise
       -xi       Do NOT use internal PC speaker for '128 sound

    If no AdLib compatible card is detected, 128K sound output will be
    sent, as far as is possible, to the internal PC speaker.  Use -xa to
    hear 128K sound through the PC speaker when there is an AdLib card
    present.

    Without CMS chips, the 128K soundchip's noise cannot be faithfully
    reproduced.  If you have CMS chips installed, use -xc to use them.  If
    the SoundBlaster is on a different base address than 0220, use -xq to
    select it.

    *  -km       Use MS Mouse to control Spectrum joystick
       -ka       Emulate Spectrum AMS mouse interface controlled by MS Mouse
       -kz       Use digital Zandbergen joystick
       -kk       Do not look for analogue or Zandbergen joystick

    The emulated joystick (Cursor, Kempston, Sinclair 2 or user defined) is
    controlled by the arrow keys and TAB, 5, INS (0) on the PC keyboard,
    and optionally also by a digital joystick, and analogue IBM joystick or
    a mouse.  Use -kk if the emulator erroneously detects either joystick.
    If -ka is specified, the PC mouse controls the emulated AMS mouse
    interface.  Because of I/O address clashes, this only works with SamRam
    and the M.G.T. interfaces disabled.  The AMS mouse is supported by e.g.
    Art Studio.

       -jc       Emulate Cursor joystick (default)
       -jk       Emulate Kempston joystick
       -j2       Emulate Sinclair joystick 2 (keys 6,7,8,9 and 0)
       -ju<lf><rt><up><dn><fire>  User defined joystick

    Also quite clear I think.  For instance, -juipqzm makes the joystick
    control the i,p,q,z and m keys, for instance to play those lovely
    Horace games.  Special characters are [ for shift, ] for symbol shift,
    / for enter and \ for space.

    *  -xs       Default to shifted cursor keys (NumLock) in '128 mode

    By default, the PC arrow keys control the cursor keys 5,6,7,8 and 0 of
    the Spectrum.  The Spectrum 128 had its arrow keys press the cursor
    keys plus shift, and the menu bar of the reset screen of the '128 only
    responds to shift+cursor key.

       -bN       Use LPTn for tape I/O
       -xo       Use SoundBlaster's A/D Converter for tape input
       -xq adr   Set base IO address for SoundBlaster (default 0220)

    Either the LPT tape interface of the SoundBlaster is used for tape
    input.  Only the LPT tape interface can be used for tape (MIC) output.

       -tv F     Play .VOC file F to 'ear' input
       -m N F    Insert cartridge file F{.MDR} into microdrive N
       -xm D     Select default directory D for .MDR files
       -td D     Select directory D for Multiple .TAP File mode
       -ts D     Specify default directory for Single .TAP File mode
       -ti F     Use F{.TAP} as tape input
       -to F     Use F{.TAP} as tape output (if exists, append)
       -tm       Mirror tape input to disk (Do also specify output file!)
       -te       Mirror tape input to disk in EXACT mode
       -tw       Don't wrap load pointer of tapefile at end

    All quite clear I think.  If -tv is used, the VOC file starts playing
    immediately, so be sure there's an appropriate snapshot running to do
    something with the signal.  -tw makes the emulator load from physical
    tape when a .TAP file has been read to the end, instead of starting
    again from the beginning.

       -0e       Epson printer (for ZX PRINTER & M.G.T.)
       -0h       HP PCL printer (for ZX PRINTER & M.G.T.)

    Output to the ZX Printer will be converted into graphic data in Epson
    or HP PCL format and sent to the 'RS232 output'.  Use one of these
    switches to select which format to use.  Also, this selects the default
    DISCiPLE ROM to be used; the two ROMs have different screen dump
    routines pre-loaded.

       -0i       Disable Disciple interrupt

    Normally the Disciple and Plus D have their own interrupt routine being
    executed 50 times a second.  Because this involves many page swaps,
    this is quite slow on the emulator.  Since the interrupt is not really
    necessary anyway, it is reduced to once every two seconds.  On some
    computers this may still be too much, in which case -0i completely
    disables the Disciple and Plus D interrupts.  Do not try this in
    Unidos!  (which is not emulated [yet].)

       -xp D     Select default directory D for .Z80 snapshot files

    Clear.

       -xz       Assume AZERTY keyboard layout

    Assumes the Belgian and French AZERTY keyboard layout.

       -xr F     Use file F as standard Spectrum rom

    The ROM will be used in 48K modes only, and must be exactly 16K long.

       -xt       Use as little memory as possible with full functionality
       -xu       Use as little memory as possible; disable HCR emulation

    With -xt, all unnecessary buffers used for efficiency purposes only are
    reduced to minimum size.  Saves 47K, but can make all the difference
    sometimes.  With -xu, 83K is saved, but Hi Color Resolution emulation
    won't work anymore.

       -tx       Do not display tape info window when loading or saving

    Some people really seem to hate it.  Don't know why.

       -xe       Do not use expanded memory

    Specifying this switch will result in the emulator using 240K more base
    memory (making a grand total of 571K).  Furthermore, all page swapping
    will be much slower, so especially the 128K emulation gets verrry slow.

       -xg       Log all outs to FE in OUT log file
       -xy       Dump trace of program in .OUT file

    By default, OUTs to port #FE that do not change the state of either MIC
    or EAR are not saved to the log file, to save disk space.  If, for some
    reason, you want all OUTs to be logged, -xg will do the trick.  The -xy
    option can be used for producing a somewhat crude trace; see section
    5.5 on the .OUT format for more details.

       -xw       Run in Windows compatibility mode

    In this mode, neither the timer interrupt nor the keyboard interrupt
    are re-routed.  The emulator counts T states to see when an interrupt
    has to be generated (so emulation will be slower), and uses the BIOS
    keyboard routines to read the keyboard.  Since the BIOS doesn't tell
    when a key is released, and since not all key combinations are mapped
    to an (extended) ASCII value, keyboard emulation is inferior to the
    emulation in normal mode.  This mode is selected automatically when the
    emulator is run under Windows; use this mode only when there's a
    conflict with some other program, or operating system.

       -xf       Switch full 16K of Interface I ROM

    Useless.




2.20  Miscellaneous remarks


    1. Problems at the Rom/Ram boundary

    There are a few Spectrum programs that have an odd stack pointer, and
    run over the ram/rom boundary, for instance Deep Strike, and Elite.
    This crashed version 1.45 of the emulator; the problem was circumvented
    somewhat in version 2.01, and has been removed in version 3: in most
    cases, a word read from or written to FFFF will be read or written as
    two bytes.  You can check this by typing CLEAR 65535: POKE 65535,0:
    RETURN in BASIC; this will lock up version 1.45 of the emulator, it
    will lock up version 2.01 if the 80386 is in virtual mode, and it will
    only crash the emulated Spectrum (as it should) on version 3.

    The check on FFFF is not done at every potentially problematic op-code,
    because this would make the emulator noticeably slower.  It is
    therefore still possible to 'hang' the emulator.  Not going to tell you
    how, though.  All existing programs seem to work okay now.


    2. Critical timings

    A few programs (the only examples known to me are Fireman and Thing,
    but there are more) are quite sensitive to the relative actual
    execution speed of emulated Z80 instructions, and crash if it isn't
    right.  They rely on this-or-that amount of instruction to be executed
    between interrupts.  If you slow down the emulator, these program will
    run fine, because then individual instructions are more carefully
    timed.  When running in Windows compatibility mode, loading .VOC files
    or when the Hi-Res Color emulation is switched on, these problems
    disappear completely as the emulator is then counting off the exact
    number of T states to elapse between interrupts.


    3. Shifted cursor keys

    It may be annoying to have to press Num-Lock every time you use the
    Spectrum 128 (because otherwise you'll have to use Shift with the
    cursor keys to move the menu bar).  To make the emulator press shift by
    default every time you use the PC cursor keys in '128 mode, use the
    switch -xs. If you press Num-Lock now (in '128 mode), the shift-key
    won't be pressed.  The 48K modes are not affected by this switch.


    4. Running non-standard ROMs

    To run the emulator with a different rom than the standard one, you can
    specify a rom image file on the command line.  Use the switch -xr file,
    where 'file' is the name of the image file.  This file should be
    exactly 16384 bytes long.  It will of course not be used in Spectrum
    128 or SamRam mode.

    The emulator 'ZX' by Rindt and Bruckner comes with several roms, stored
    in their tape format.  You can convert these files to .TAP files, and
    then load them in the normal way (in RAM), and then save the 16K image
    from RAM directly.  You can also extract it from the files directly by
    using the DOS debug utility:

        C:\>debug rom.000       (or other rom file (of 16406 bytes))
        -m 115 L 4000,100       (move the rom down, overwrite header)
        -rcx                    (new length of exactly 16K bytes)
        CX 4016
        4000
        -n rom000.bin           (or some other name)
        -w                      (write it)
        Writing 04000 bytes
        -q                      (and quit)


    5. Printing with DISCiPLE and Plus D

    If, emulating a DISCiPLE/+D and by entering POKE @11,0 the parallel
    printer output has been selected, going back to a hardware mode without
    M.G.T. interface causes problems with printing to the ZX Printer, since
    the output addresses of the "p" channel have been changed by the M.G.T.
    ROM.  Use the "b" channel of the Interface I instead.  You can reset
    the channel to the ZX Printer by entering POKE @11,1 while still
    emulating the M.G.T. interface.

    Although by default channel #3 prints to the ZX Printer, in all
    hardware modes, if a DISCiPLE/+D is emulated output to the ZX Printer
    is ignored, as these interfaces use the ZX Printer I/O ports for their
    own purposes.


    6. ZX Printing

    When converting ZX Printer output for either Epson or HP-PCL printers,
    the emulator does not check whether the printer is on-line or not; this
    is left to the BIOS.  The result is that, when it is off-line (or when
    there is no printer connected at all to the specified port) the
    emulator may seem to hang.  Make sure to have specified the right
    output port with -xl N, and the right output format with either -0h or
    -0e.  See the default Z80.INI file.






3.  THE SAMRAM




3.1  Basic extensions


    The SamRam is a hardware device Johan and I built for our Spectrums. It
    consists of a 32K static RAM chip which contains a modified copy of the
    normal Basic ROM and a number of other useful routines, like a monitor
    and snapshot software.  You can compare it to a Multiface I interface,
    but it's more versatile.  Another useful feature was a simple hardware
    switch which allowed use of the shadow 32K Ram, present at 8000-FFFF in
    most Spectrums, but hardly ever actually used.

    For more details on the low-level hardware features of the SamRam read
    chapter 5.  In this chapter I'll explain the software features of the
    SamRam software, somewhat bombastically called the 'SamRam 32 Software
    System' or the 'Sam Operating System'.  By the way, all similarity
    between existing computers is in fact purely coincidental and has in no
    way been intended.  Really!

    The SamRam offers a few new Basic commands, and a lot of useful
    routines that are activated by an NMI, i.e.  by pressing F5.  First
    I'll discuss the Basic extension.

    Select the SamRam by starting the emulator with the -s switch, or by
    selecting it from the F9 menu.  Normal Basic functions as usual; the
    character set is different from the original one.  There are four new
    commands: *RS, *MOVE, *SAVE and *SPECTRUM, and two new functions, DEC
    and HEX, which have replaced ASN and ACS.  DEC takes a string argument
    containing a hexadecimal number, and returns the decimal value of it.
    HEX is the inverse of the DEC function, and yields a four-character
    string.

    *RS sends its arguments directly to the RS232 channel.  You don't have
    to open a "b" or "t" channel first.  You're right, it's of limited use.
    Example: *RS 13,10

    *MOVE is useful: it moves a block of memory to another place.  Example:
    *MOVE 50000,16384,6912 moves a screen-sized block from 50000 to the
    start of the screen memory.

    *SAVE works like *MOVE, except that it activates the shadow SamRam ROM
    before moving.  I used this command to update the shadow ROM, but on
    the emulator you can use it to move the shadow ROM to a convenient
    place in Ram where you can take a look at it, for instance by executing
    *SAVE 0,32768,16384.

    *SPECTRUM resets the SamRam Spectrum to a normal one.  You lose all
    data in memory.  By resetting the emulator by pressing ALT-F5, the
    SamRam is activated again.  Not very useful either.

    Then there's the Ramdisk, which is, like the Spectrum 128 ramdisk,
    accessed via the SAVE!, LOAD!, CAT!, ERASE! and FORMAT!.  The syntax is
    straightforward.  FORMAT! and CAT! need no parameters; ERASE! only
    needs a name.  If a file is not found, the SamRam will respond with a
    5-End of File error.  The Ramdisk has a capacity of 25K.




3.2  The NMI software


    Select the SamRam (F9-3), and press F5.  A menu with eight icons pops
    up.  You can select each icon by moving the arrow to it (using the
    cursor keys or the Kempston joystick), and pressing '0' or fire.  The
    icons can also be selected by pressing the appropriate letter key.

    The eight icons are two arrows with N and E within them, a magnifying
    glass with the letters 'mc' in it (activated by pressing D), two
    screens (identified by 1 and 2), a printer (P), a cassette (S) and a
    box saying 'overig'.  The 'D' activates the monitor or disassembler;
    read section 3.3 for information on this program.

    Pressing N or E returns you to the Spectrum.  If you pressed N, the
    normal Spectrum rom will be selected when the NMI software returns; if
    you press E, the Rom with the Basic extensions will be selected.  Some
    games may crash if they see a different rom than the standard Spectrum
    one.

    Pressing 1 selects the tiny screen editor.  You can move a '+' shaped
    cursor about the screen using the cursor keys.  The following commands
    are available:

        H: Get the current ATTR color from the screen at the cursor's
           current position, and store it in memory.  This color will be
           used by the next command:
        Z: Put the color on the screen
        G: Get a character from the screen
        P: Put the character on the screen
        R: Remove all screen data that is invisible by the ATTR color
        L: Take a look at the bitmap below the ATTR color codes
        T: Return to the main menu.  You can also return by pressing
           EDIT, or ESC in the emulator.
        B: Change border color
        V: Clear the whole screen

    If you press 0, you can edit the current 8x8 character block at pixel
    level.  Again you control the cursor with the cursor keys.  Now 0
    toggles a pixel.  In this mode there are two commands: C clears the
    whole block, and I inverts it.  Pressing EDIT (ESC) returns you to the
    big screen again.

    The SamRam has two screen buffers.  Buffer 1 is used to hold the screen
    which was visible when you pressed NMI, to be able to restore it when
    returning.  This is the screen you edit with '1'.  The second screen
    buffer can be used to hold a screen for some time; it is not touched by
    the NMI software directly, and will not even be destroyed by a Reset.
    If you press '2', a menu appears with four Dutch entries:

        1: Scherm 1 opslaan        (Store screen 1 into buffer 2)
        2: Scherm 2 veranderen     (Edit screen 2)
        3: Schermen verwisselen    (Swap screens)
        4: Scherm 2 weghalen       (Remove screen 2)

    These four functions are rather obvious, I believe.

    Pressing 'P' pops up the printer menu.  The screendump program is
    written specifically for my printer, a Star SG-10.  It will probably
    work on some other printers, but not on most.  The output is sent to
    the RS232 channel, so you have to redirect it to an LPT output.

    Skipping the most interesting, 'S', for a moment, let's first discuss
    the final menu, 'O' for 'Overig', Dutch for miscellaneous.  There are
    five menu options, of which three are not useful.  The first gives a
    directory of the cartridge currently in Microdrive 1.  The last, 'E',
    returns you to Basic if this is anywhere possible: it resets some
    crucial system variables and generates a Break into Program.  You can
    use this for instance to break in a BEEP, or crack a not-so-very-well-
    protected program.  The three other options select normal or speed-
    save, and store the current setting in CMOS Ram.  Speed-save won't work
    properly on the emulator, because the speed-save routine toggles the
    upper 32K ram bank regularly, and this takes too much time on the
    emulator.  The setting is not important if you use the internal save
    routine (which will be used by default, unless you select Real Mode).

    Finally, the 'S' option.  This option allows you to save a snapshot to
    tape or microdrive.  I used it a lot on my real Spectrum, and it works
    just as well on the emulator.  It is very useful is you want to load a
    .Z80 program back into a real Spectrum again.  There are three
    'switches' you can toggle.  The active choice is indicated by a bright
    green box, inactive boxes are non-bright.  You have to use EGA or VGA
    to be able to see it...  The first switch lets you select whether the
    SamRam rom should be active if the program loads or not.  This is only
    meaningful is you load it back in a SamRam again.  Usually I want the
    SamRam rom to be active because I like the character set better.  The
    second switch indicates whether the SamRam should save a 'loading
    screen', which it takes from screen buffer 2.  If screen buffer 2
    contains a screen, this switch will by default be on.  Finally, the
    last switch lets you select the output media, tape or cartridge.

    If the program is loaded back into the SamRam, the only bytes that have
    been corrupted are four bytes down on the stack; this will virtually
    never be any problem.  If the program is loaded back to a normal
    Spectrum, these four bytes will also be corrupted, and the bottom two
    pixel lines of the screen will be filled with data.  (This is
    considerably less than any other snapshotter I've seen: for instance
    the Multiface I uses more than 35% of the screen!)

    The Microdrive BASIC loader needs code in the SamRam rom to start the
    program (the RANDOMIZE USR 43 calls it).  It won't be very difficult to
    write a standard BASIC loader that doesn't need this code, but I don't
    think many people desperately need it...  Anyway, using the Multiface
    128 you can write a compressed snapshot to cartridge which doesn't need
    the Multiface.




3.3  The built-in monitor


    This is a really very convenient part of the emulator, and I use it a
    lot.  It is very MONS-like in its commands and visual appearance.  It
    cannot single-step however, but on the positive side it has some
    features MONS hasn't.  It is a part of the SamRam, and cannot therefore
    be used with Spectrum 128 programs.  If you want to take a look at a
    Spectrum 128 program, press F10, then change the hardware to SamRam
    without resetting, and finally generate an NMI in the Extra Functions
    menu.  You won't probably be able to continue to run the program, but
    at least you're able to see what it was doing.

    Press F5 for NMI, and D to enter the monitor/disassembler.  The first
    eight lines are the first eight instructions, starting at the Memory
    Pointer, from here on abbreviated by MP.  At first, MP is zero.  The
    disassembler knows all official instructions, and the SLL instruction.
    If another inofficial instruction (i.e.  starting with DD, FD or ED) is
    encountered, the first byte is displayed on a blank line.  The four
    lines below these display the value of PC and SP, the first nine words
    on the stack (including AF and the program counter, which have been
    pushed during NMI), and three MP-memories.  These can be used for
    temporary storage of the MP, for instance when you take a look at the
    body of a CALL, and want to return to the main procedure later.

    The bottom part of the screen displays 24 bytes around the memory
    pointer.

    Commands are one letter long; no ENTER needs to be given.  If one or
    more operands are needed, a colon will appear.  By default the monitor
    accepts hexadecimal input.  A leading $ denotes that the number is to
    be regarded as decimal.  If you give the # command, the default will
    toggle to decimal, and you need to explicitly put a # in front of a
    number which is to be interpreted as a hex number.  Also, after the #
    command all addresses on screen will be decimal.  A single character
    preceded by the " symbol evaluates to its ASCII code, and the single
    character M will evaluate to the current value of the memory pointer.

    The monitor commands:

        Q: Decrease the memory pointer by one.  You effectively shift one
           byte up.
        A: Increase the memory pointer, shifting one byte down.
        ENTER: Shift one instruction down: the memory pointer is
           increased by the length of first instruction displayed on
           screen.
        M: Change the value of the memory pointer.  For instance, M:M
           won't change it.
        P: Put.  The word operand supplied will be stored in the first MP
           memory, and the others will shift on place to the right.
           Usually, you'll want to store the memory pointer by P:M
        G: Get.  Typing G:1, G:2 or G:3 moves the value of one of the MP
           memories to the MP.
        B: Byte.  This command needs a byte operand; it will be poked
           into memory, and the memory pointer will move one up.
        I: Insert.  The same as B, except that you can poke more than one
           byte.  It continues to ask for bytes to poke until you type
           Enter on a blank line.
        #: Toggles the default number base between hexadecimal and
           decimal.
        F: Find.  You can enter up to ten bytes, which will be searched
           through memory.  Searching will stop at address 0, because
           since the search string is stored in shadow Ram, searching
           would otherwise not always terminate.  Typing Enter on a blank
           line starts the search.  Byte operands are entered as usual,
           but:
           - If a number bigger than 256 decimal is entered, it is
             treated as a word in the standard LSB/MSB format.  So, 1234
             will search for 34,12 hex in that order.  Note that 0012
             will search for 12, not 12,00.
           - A line starting with " decodes into the string of characters
             (up to ten) behind it.  Normally this would only be the
             first character.  So instead of typing "M "Y "N "A "M "E
             (space=enter here) you type "MYNAME.  Note that any
             terminating " will also be searched for!
           - An x is treated as a wildcard.  So if you search for CD x 80
             any call to a subroutine in the block 8000-80FF is a hit.
             If you search for x 8000, you'll see every one-byte
             instruction that has the address 8000 as operand.
        N: Continues the search started by F from the current MP.
        $: Displays one page of disassembly on screen.  In this mode,
           the following commands are possible:
           $: Back to the main screen
           7: [Shift 7 also works, cursor up]: Go to the previous page.
              The monitor stores the addresses of the previous eight
              pages only.
           Q: Go back one byte (decrease MP by one)
           A: Go one byte forward (increase MP by one)
           Z: Dump this screen to the printer, in ASCII format.  Redirect
              the RS232 output to a file, and run CONVERT on it to convert
              the CR's into CR/LF's before printing (or tell your printer
              to do the conversion).
           Every other key displays the next page of disassembly.
        K: List.  The same mode as with $ is entered, but instead of a
           disassembly the bytes with their ASCII characters are
           displayed.  Useful to look for text.
        C: Clear.  Fills blocks of memory with a specified value.  The
           monitor prompts with 'First', 'Last' and 'With'.  The 'Last'
           address is inclusive!
        D: Dump.  Prompts with 'First' and 'Last', and dumps a
           disassembly of the block between these addresses to the
           printer.  See remark at $-Z.  The 'Last' address is again
           inclusive.
        R: Registers.  If you press Enter after R, an overview of the
           registers contents is displayed.  If you type one of A,B,C,D,
           E,H,L,A',B',C',D',E',H',L',I,R,AF,BC,DE,HL,AF',BC',DE',HL',
           IX,IY,SP or PC, you can change the value of it.  Changing the
           value of SP also changes the PC and AF values by the way.  You
           cannot change the Interrupt mode or IFF.
        V: Verplaats.  (Move).  Prompts with 'From', 'To' and 'Length'.
           Obvious.
        S: Save.  Enter the start of the block you wish to save first.
           The monitor then prompts with 'Length'.  The block is saved
           without a header, as a normal data block (A, the flagbyte, is
           0FF)
        L: Load.  Loads a block of data from tape, at the specified
           address.  Normal data blocks, headers and blocks with non-
           standard flag bytes can be loaded.  The first byte in memory
           will contain the flag byte.  If the checksum isn't 0 after
           loading, indicating a tape error, you'll hear a beep.
        H: Header read.  Loads headers and displays the contents on
           screen.


    As you're reading this part, I assume you know something of machine
    code.  Probably you would be interested in peeking into the software of
    the SamRam, the Interface I, the Spectrum 128, the Disciple or the
    Multiface 128.  You'll first have to move these roms in ram to be able
    to look at them with the monitor.

    The Interface I rom can be moved into ram by saving it to microdrive or
    to the "b" channel, with SAVE *"m";1;"rom" CODE 0,8192 or SAVE *"b"
    CODE 0,8192, and loading it back again at 32768 for instance.  You can
    also put this small machine code routine at 23296 and run it: F3 21 0C
    5B E5 21 00 00 E5 C3 08 00 21 00 00 11 00 80 01 00 20 ED B0 FB C3 00
    07.

    The two SamRam roms are easy.  The first you don't need to transfer;
    the monitor looks at the extended basic rom by default.  The second rom
    can be moved to 32768 by typing *SAVE 0,32768,16384.  (The SAVE is not
    the keyword SAVE!)

    The first '128 rom, the one which is active at reset and contains most
    of the new code, is moved up by typing SAVE!"rom"CODE 0,16384, then
    LOAD!"rom"CODE 32768.  The other rom is most conveniently moved by
    saving it to a .TAP file and loading it back again in ram.  To select
    the SamRam type SPECTRUM first, and then switch the hardware without
    resetting.

    The Disciple and Plus D roms can be transferred to RAM by simply saving
    them to disk and loading them back at say 32768.

    The Multiface ROM is paged by an IN from 191, and paged out again by
    INning from address 63.  Don't forget to disable interrupts in between,
    I'm not sure whether the M128 has a well-behaved interrupt routine.
    ROM is from 0-8191, RAM on top of that.






4.  THE SPECTRUM




4.1  The Spectrum


    This emulator supports the Interface I, the Multiface 128, the DISCiPLE
    and Plus D interfaces, and the Spectrum 128.  Many Spectrum users will
    have no experience with them, so some comments may be useful.  On the
    other hand, I don't think this is the right place to describe the
    Spectrum Basic in full detail.  If you want to know it all, read the
    official manuals!  Information on the Multiface 128 can be found in
    section 2.12.

    If you want to use Spectrum Basic, you will need the keywords.  You
    could by the way now also use the Spectrum 128 Basic where you can type
    the keywords in by full.

    If you press ALT-F1 in the emulator, the Spectrum keyboard layout will
    appear.  For completeness I include an alphabetical list of all
    keywords and their key-combination.  In the list below, K stands for
    Keyword mode, E for E-mode (type Shift-Alt of Shift-Ctrl to select
    E-mode), S for Symbol Shift, and SE for Symbol Shifted (Alt/Ctrl)
    E-mode: select E mode and type the letter while depressing Symbol
    Shift.


        Keyw.    Code | Keyw.    Code | Keyw.    Code | Keyw.    Code

        ABS      E g    DRAW     K w    MERGE    SE t   SAVE     K s
        ACS      SE w   ERASE    SE 7   MOVE     SE 6   SCREEN$  SE k
        AND      S y    EXP      E x    NEW      K a    SGN      E f
        ASN      SE q   FLASH    SE v   NEXT     K n    SIN      E q
        AT       S i    FN       SE 2   NOT      S s    SQR      E h
        ATN      SE e   FOR      K f    OPEN #   SE 4   STEP     S d
        ATTR     SE l   FORMAT   SE 0   OR       S u    STOP     S a
        BEEP     SE z   GO SUB   K h    OUT      SE o   STR$     E y
        BIN      E b    GO TO    K g    OVER     SE n   TAB      E p
        BORDER   K b    IF       K u    PAPER    SE c   TAN      E e
        BRIGHT   SE b   IN       SE i   PAUSE    K m    THEN     S g
        CAT      SE 9   INK      SE x   PEEK     E o    TO       S f
        CHR$     E u    INKEY$   E n    PI       E m    USR      E l
        CIRCLE   SE h   INPUT    K i    PLOT     K q    VAL      E j
        CLEAR    K x    INT      E r    POINT    SE 8   VAL$     SE j
        CLOSE #  SE 5   INVERSE  SE m   POKE     K o    VERIFY   SE r
        CLS      K v    LEN      E k    PRINT    K p    <=       S q
        CODE     E i    LET      K l    RANDOMIZE K t   >=       S e
        CONTINUE K c    LIST     K k    READ     E a    <>       S w
        COPY     K z    LINE     SE 3   REM      K e
        COS      E w    LLIST    E v    RESTORE  E s    DEC      SE q
        DATA     E d    LN       E z    RETURN   K y    HEX      SE w
        DEF FN   SE 1   LOAD     K j    RND      E t
        DIM      K d    LPRINT   E c    RUN      K r


        Character  Spectrum kbrd   On PC keyboard

        &          S 6             ALT (or CTRL) 6
        '          S 7             ALT 7 or '/"
        (          S 8             ALT 8
        )          S 9             ALT 9
        _          S 0             ALT 0 or SHFT _/-
        <          S r             ALT r or SHFT </,
        >          S t             ALT t or SHFT >/,
        ;          S o             ALT o or :/;
        "          S p             ALT p or SHFT "/'
        ^          S h             ALT h
        -          S j             ALT j or _/-
        +          S k             ALT k or SHFT +/= or GREY +
        =          S l             ALT l or +/=
        :          S z             ALT z or SFHT :/;
        ?          S c             ALT c or SHFT ?//
        /          S v             ALT v or ?//
        *          S b             ALT b or GREY PRTSC/*
        ,          S n             ALT n or </,
        .          S m             ALT m or >/.




4.2  The Interface I


    If you want to use the microdrive, you'll need cartridge files.  The
    emulator can create an empty cartridge file for you.  You have to
    format it before you can use it.  Type

        FORMAT "m";1;"name"

    to format the cartridge currently in Microdrive 1 giving it the name
    'name'.  Next, type CAT 1 to get a catalogue of the files on it (none
    of course) and the number of kilobytes free.  You can save a file by
    typing for instance

        SAVE *"m";1;"screen"SCREEN$

    Instead of SCREEN$ you can use all other expressions that are permitted
    also when saving to tape, like LINE nnnn or CODE x,y etcetera.  To load
    a file back from cartridge, you type (you guessed it)

        LOAD *"m";1;"screen"SCREEN$

    If the file doesn't exist or is of the wrong type you'll get the
    appropriate error message.  To erase a file, type for instance

        ERASE "m";1;"screen"

    Note that no * is needed (or even permitted), and that only the name
    should be given.  There's another way to create a file on a cartridge,
    and that is by using a command like OPEN #3;"m";1;"name", and printing
    to that stream.  You can use MOVE to move data from stream to stream,
    but I'll not go into that --- it's not very much used anyway.

    Instead of to the microdrive, you can also 'save to the RS232 link'.
    For instance, type SAVE *"b"SCREEN$ (note: there's no name!) to save a
    screen.  On the emulator you can send the output to the RS232 channel
    to a printer (then SAVE *"b" is useless), to a file (can be useful) or
    to the COM port (very useful if you connect a real Spectrum to the PC's
    COM port!).  You can load the data back by typing LOAD *"b"SCREEN$ and
    making sure the RS232 channel is fed with the right input (from a COM
    port or a file).  See also section 2.13.

    If you want to use the RS232 channel for printing, open stream 3 for
    output to that channel by typing

        OPEN #3,"b"

    or

        OPEN #3,"t"

    The first will simply copy everything you send to stream 3 (using for
    instance LPRINT or LLIST) to the RS232 channel; the second converts
    CR's into CR/LF's, breaks off lines at 80 characters and translates
    keywords into character sequences.  "t" is useful for LLISTings, but
    not for anything else.

    Useful extra commands: CLS #, to clear the screen and reset the
    attributes to their reset defaults, and CLEAR # to do a CLS # and close
    all currently open streams (discarding all data that may still be
    buffered!)

    The Interface I uses its own system variables.  At the first error
    message you make (or RASP, or flashing question mark) and at the first
    Interface I statement you execute, it inserts them automatically.  Some
    programs will not run when the Interface I has inserted its system
    variables.  So if you load a game from tape, reset the Spectrum first
    and don't make an error typing LOAD "".  With a bit of exercise you
    should be able to do this.




4.3  The DISCiPLE and Plus D Interfaces - Introduction


    The DISCiPLE and Plus D were two disk interfaces for the spectrum
    designed by M.G.T. (Miles Gordon Technology).  The first of these
    interfaces was the DISCiPLE, this interface consisted of a disk
    interface, microdrive network compatible interface, parallel printer
    interface, 2 joystick ports (emulating kempston, cursor, and Sinclair 1
    and 2).  The unit also had an inhibit button which disabled the
    interface hardware (except the joystick ports), and finally a snapshot
    button which when pressed stopped the computer to allow the program to
    be saved to disk or the screen to be printed.  This was made by
    Rockfort.

    The Plus D was the second of the interfaces, this was a cut-down
    version of the DISCiPLE, this interface only had a disk interface,
    parallel printer interface and a snapshot button.

    Both interfaces had a D.O.S. (Disk Operating System) which was partly
    ROM (8K) and partly RAM (8K).  When the spectrum was turned on, the ROM
    part of the D.O.S. was in control and whenever the command RUN was
    issued the ROM tries to load up the RAM part of the D.O.S. from floppy
    disk.  The advantage of this is that the D.O.S. can be upgraded without
    having to change chips over (unless of course it was a major upgrade!).
    Another advantage was that D.O.S. extensions could be incorporated or
    replace other systems (see later).

    With both interfaces, they extended the BASIC commands, but unlike the
    microdrives and several other types of drives available, the DISCiPLE
    and Plus D took up none of the spectrum's RAM, therefore it was the
    most invisible of the disk systems available, not only that, but the
    DISCiPLE and Plus D used the same type of disk drives as the BBC micro,
    therefore disk drives were both cheap and widely available, also the
    disks themselves were also standard, ie 5.25" (800K DS/DD), then later
    3.5" (800K DS/DD).

    The ROM of the DISCiPLE is supplied with the emulator, together with
    two version of the D.O.S. pre-loaded in RAM.  The ROM of the Plus D
    interface is not supplied, for copyright reasons.  The emulator will
    only emulate a Plus D interface if it can find a file PLUSDROM.BIN in
    the emulator's own directory.  If you have a Plus D yourself, you can
    transfer the ROM in the following way.  Load the operating system from
    a Plus D system diskette, and save the entire ROM, together with the
    operating system, to disk by entering SAVE d1"rom" CODE 0,16384.  Then,
    start the emulator and choose hardware mode Spectrum 48K + Disciple
    (not Plus D of course), then type LOAD d1"rom" CODE 32768.  Finally,
    press F10, X, S for Save Data block, set start address and length to
    8000 and 4000 (hexadecimal) respectively, and save the ROM under the
    name PLUSDROM.BIN.  If you re-start the emulator now, it will emulate
    the Plus D too.




4.4  The DISCiPLE and Plus D Interfaces - The basic commands


    There are several levels of commands that can be used, these range from
    the most straightforward everyday use, to the more advanced, programmer
    type commands.

    I will first explain the most common commands, so that you can quickly
    and easily access DISCiPLE and Plus D disks.  Where a 1 is used in the
    following commands 2 could be used instead.  These commands are:-

     RUN -   when no D.O.S. (system file) is loaded it will cause this to
             be loaded. Otherwise it will just run the BASIC PROGRAM.  Please
             note that with the emulator the system file is already loaded,
             therefore this command is not required, although I have
             explained it for completeness.

     CAT 1 - will display a longhand catalogue of the disk drive selected.
             The form of this catalogue is as follows:-

                    program no., program name, sectors used, file type,
                    file size

     CAT * - will display a longhand catalogue of the currently selected disk
             drive in the same form as described above.

     CAT 1! - displays a shorthand catalogue of the disk drive selected.
              This catalogue consists of a 3 column list of the filename of
              the programs.

     CAT *! - displays a shorthand catalogue of the current disk drive.

     LOAD pn - p - letter p, n - number between 1 & 80.  This is the program
               number of the file on the disk, the program number is the
               number printed before the name in the longhand catalogue.

     LOAD d1"name" - load from drive 1 the program called name

     LOAD d*"name" - load from the current drive the program called name

     LOAD d1"name" S - load an 48K snapshot from drive 1 called name

     LOAD d1"name" K - load an 128K snapshot from drive 1 called name

     LOAD d1;a$ - load from drive 1 the program whose name is held in the
                  string a$

     LOAD d*;a$ - load from the current drive the program whose name is held
                  in the string a$

     FORMAT d1 -  format the disk in drive 1




4.5  The DISCiPLE and Plus D Interfaces - More advanced commands


    In the previous section I explained enough of the commands so that you
    could get to use the floppy disks with DISCiPLE/Plus D software on. Now
    I am going to explain the commands that the more experienced user and
    those who want to do just a little bit more than just load the
    programs.

    First of all comes the simple commands of SAVE, MERGE, VERIFY and LOAD.
    All of these commands are the same as rge tape versions except that you
    have d1, d2 or d* after the LOAD, SAVE etc.  There are only two
    exceptions to this rule, the first is when you have a string for the
    filename, in this case the command becomes:-

             LOAD d1;n$ ....... etc
             LOAD d*;n$ ....... etc

    The second exception is actually an extension.  When you save a code
    block, you can actually get it to autorun when it is loaded by adding a
    third parameter to the SAVE command, e.g. if you had a code block from
    40000 to 45000 and the run address was 41023 and you wanted it to be
    called testcode to drive 1, you would save it as:-

             SAVE d1"testcode"CODE 40000,5001,41023

    Now for the extensions.

    Any sector on the disk may be loaded to any area of RAM from 16384 to
    65535-512. The sector may also be loaded into the RAM of the interface,
    however caution should be used at all times when doing this, as you may
    destroy the operating system or cause it to behave irrationally.

    The syntax of the command is:-

             LOAD @n,tr,sec,add

    Where:-

             n   = drive number, ie 1 or 2, note * may not be used!
             tr  = track number => 0->79=side 0, 128->207=side 1
             sec = sector number => 1->10 normally, may not be 0!  If you
                                    try and load a sector that is sector 0,
                                    then the operating system will crash!

    You may also save to disk in the same way, so if you wanted to write to
    Track 5, Side 0, Sector 3 with code from 32768 to 33279 to drive 1 you
    would type:-

             SAVE @1,5,3,32768

    To format a disk all you need to type is:-

             FORMAT d1       or       FORMAT d2

    This is not however as simple as it seems!  Although a disk formatted
    on the DISCiPLE/Plus D will work with the PC it does not work the other
    way round, i.e. a disk formatted on the PC with this emulator will not
    necessarily work on the DISCiPLE/Plus D. This is because of differences
    of the floppy disk controller chips.  With the PC, it puts a special
    byte at the beginning of each track to tell the controller whether the
    disk is Double Density or High Density, and the spectrum floppy disk
    controller does not understand this byte and therefore will not read
    the track!  If you find this otherwise, then please write and let us
    know about it.

    You can set some of the D.O.S. system variables using an extended POKE
    command. The syntax is:-

             POKE @address,value

    The address is the BASE address of the system variables of the
    interface concerned, the BASE address for each of the interfaces is
    different, but the address you use in the POKE command is the same.




4.6  The DISCiPLE and Plus D Interfaces - The snapshot button


    The snapshot button is a button which is used to stop the processor
    from executing instructions and making it do something else. In the
    case of the DISCiPLE/PLUS D the button can do 5 different tasks
    initially. Later on I'll discuss how the fuctions can be altered so
    that it can do other tasks. Once these tasks are carried out, the
    processor is returned to it's original state and the program continues
    from where it left off from.

    There are 5 functions that can be carried out with the initial system
    file.

    To use the button, first you must get to a point in the program that
    you want to use the button at, then press the button on the emulator
    the snapshot button is F5 (NMI).  Once you do this the program will
    stop and the border of the computer will flash, this may also be
    accompanied with a buzzing noise on the speaker.  This is to tell you
    that the snapshot button has been activated.  The following functions
    can then be carried out:-

        1   - Print screen to printer in black/white screen size
        2   - Print screen to printer in grey scale A4 size
        3   - Snapshot screen to disk in SCREEN$ format
        4   - Snapshot program to disk in 48K SNAP format
        5   - Snapshot program to disk in 128K SNAP format
      SPACE - go back to program (ie if F5 was pressed by mistake)

    The printer options will print out to EPSON compatible printers,
    however the DISCiPLE code has been changed and it is now possible to
    print to HPGL printers (e.g. Deskjet and Laserjet printers).

    The Snapshot screen and snapshot 48K are very self explanatory and easy
    to use.

    The Snapshot 128K is slightly more complicated.  Once you select this
    option the disk drive will start up then after a slight pause the
    screen display may/may not change.  The border flashes again and you
    have to press y or n depending on whether the screen display changed or
    not.  If the screen stayed the same then press n, but if the screen
    changed type y.  This is because the 128K spectrum has 2 screens, and
    there is no way for the computer to determine which is being used by
    itself, therefore it needs the user's help.  After you press y or n the
    program will be saved onto disk.

    Seeing it is possible for you to load programs into the DISCiPLE/PLUS D
    RAM area it is possible to have these interfaces carry out other tasks.
    The snapshot button code is located in RAM, so you can therefore load a
    program into this part of the RAM and as soon as you press the snapshot
    button it will execute the new program.  There is one problem however,
    which is that the program must be written in assembly language and must
    also be compiled for running in that part of RAM, also it must take
    care of what it does because the SPECTRUM ROM is not paged in,
    therefore ROM calls are not easily carried out.

    There are several different commercial programs which use the snapshot
    button to carry out different tasks, some of these are:-

                        Snapshot compressing programs
                        Debugging tools
                        Cheat finders for games
                        Programs to allow snapshots back onto tape

    The list is endless, and if you are capable of writing a machine-code
    program and have the relevant information, then you too could write
    your own programs.




4.7  The Spectrum 128


    The main new features of the Spectrum 128 are its larger memory, that
    can be used as a Ram drive in Basic, and music capabilities.

    The Ram drive is accessed via the LOAD!, SAVE!, ERASE! and CAT!
    commands.  They work as you would expect.  Examples:

        SAVE !"name"SCREEN$
        CAT!
        LOAD !"name"SCREEN$
        ERASE !"name"

    The 3 channel sound chip of the Spectrum 128 can be used in Basic with
    the PLAY command.  Example:

        PLAY "cde","efg","gAB"

    plays three chords.  You can program complex effects, melodies and
    rhythms with the play command; they require many commands in the three
    voice strings which I won't explain...  They are explained in the
    Spectrum 128's user guide.






5.  TECHNICAL INFORMATION




5.1  The Spectrum


    In this section, the hardware of the 48K Spectrum is discussed.  At the
    end, a discussion on the video timings of the 128K Spectrum is also
    included.  In this section, 'Spectrum' by itself refers to the 48K
    machine.

    The Spectrum is at the hardware level a very simple machine.  There's
    the 16K ROM which occupies the lowest part of the address space, and
    48K of RAM which fills up the rest.  An ULA which reads the lowest 6912
    bytes of RAM to display the screen, and contains the logic for just one
    I/O port completes the machine, from a software point of view at least.

    Every even I/O address will address the ULA, but to avoid problems with
    other I/O devices only port FE should be used.  If this port is written
    to, bits have the following meaning:


        Bit   7   6   5   4   3   2   1   0
            ┌───┬───┬───┬───┬───┬───┬───┬───┐
            │   │   │   │ E │ M │   Border  │
            └───┴───┴───┴───┴───┴───┴───┴───┘


    The lowest three bits specify the border colour; a zero in bit 3
    activates the MIC output, and a one in bit 4 activates the EAR output
    (which sounds the internal speaker).  The real Spectrum also activates
    the MIC when the ear is written to; the emulator doesn't.  This is no
    problem; MIC is only used for saving, and when saving the Spectrum
    never sounds the internal speaker.  The upper three bits are unused.

    If port FE is read from, the highest eight address lines are important
    too.  A zero on one of these lines selects a particular half-row of
    five keys:

      IN:    Reads keys (bit 0 to bit 4 inclusive, in that order)

      #FEFE  SHIFT, Z, X, C, V            #EFFE  0, 9, 8, 7, 6
      #FDFE  A, S, D, F, G                #DFFE  P, O, I, U, Y
      #FBFE  Q, W, E, R, T                #BFFE  ENTER, L, K, J, H
      #F7FE  1, 2, 3, 4, 5                #7FFE  SPACE, SYM SHFT, M, N,

    A zero in one of the five lowest bits means that the corresponding key
    is being pressed.  If more than one address line is made low, the
    result is the logical AND of all single inputs, so a zero in a bit
    means that at least one of the corresponding keys are pressed.  For
    example, only if each of the five lowest bits of the result from
    reading from port 00FE (for instance by XOR A/IN A,(FE)) is one, no key
    is pressed.

    A final remark about the keyboard.  It is connected in a matrix-like
    fashion, with 8 rows of 5 columns, as is obvious from the above
    remarks.  Any two keys pressed simultaneously can be uniquely decoded
    by reading from the IN ports; however, if more than two keys are
    pressed decoding may not be uniquely possible.  For instance, if you
    press Caps shift, B and V, the Spectrum will think also the Space key
    is pressed, and react by giving the 'Break into Program' report.  This
    matrix behaviour is also emulated - without it, Zynaps for instance
    won't pause when you press 5,6,7,8 and 0 simultaneously.

    Bit 5 (value 64) of IN-port FE is the ear input bit.  When the line is
    silent, its value is zero, except in the early Model 2 of the Spectrum,
    where it was one.  When there is a signal, this bit toggles.  The
    Spectrum loading software is not sensitive to the polarity of this bit
    (which it definitely should not be, not only because of this model
    difference, but also because you cannot be sure the tape recorder
    doesn't change the polarity of the signal recorded!) Some old programs
    rely on the fact that bit 5 is always one (for instance Spinads); for
    these programs the emulator can mimic a Model 2 Spectrum.

    Bits 6 and 7 are always one.

    The ULA with the lower 16K of RAM, and the processor with the upper 32K
    RAM and 16K ROM are working independently of each other.  The data and
    address buses of the Z80 and the ULA are connected by small resistors;
    normally, these do effectively decouple the buses.  However, if the Z80
    wants to read of write the lower 16K, the ULA halts the processor if it
    is busy reading, and after it's finished it lets the processor access
    lower memory through the resistors.  A very fast, cheap and neat design
    indeed!

    If you run a program in the lower 16K of RAM, or read or write in that
    memory, the processor is halted sometimes.  This part of memory is
    therefore somewhat slower than the upper 32K block.  This is also the
    reason that you cannot write a sound- or save-routine in lower memory;
    the timing won't be exact, and the music will sound harsh.  Also,
    INning from port FE will halt the processor, because the ULA has to
    supply the result.  Therefore, INning from port FE is a tiny bit slower
    on average than INning from other ports; whilst normally an IN A,(nn)
    instruction would take 11 T states, it takes 12.15 T states on average
    if nn=FE. See below for more exact information.

    If the processor reads from a non-existing IN port, for instance FF,
    the ULA won't stop, but nothing will put anything on the data bus.
    Therefore, you'll read a mixture of FF's (idle bus), and screen and
    ATTR data bytes (the latter being very scarce, by the way).  This will
    only happen when the ULA is reading the screen memory, 61.5% (192/312)
    of the 1/50th second time slice in which a frame is generated.  The
    other 38.5% of the time the ULA is building the border or generating a
    vertical retrace.  This behaviour is actually used in some programs,
    for instance by Arkanoid, and Z80 also emulates this.

    Finally, there is an interesting bug in the ULA which also has to do
    with this split bus.  After each instruction fetch cycle of the
    processor, the processor puts the I-R register 'pair' (not the 8 bit
    internal Instruction Register, but the Interrupt and R registers) on
    the address bus.  The lowest 7 bits, the R register, are used for
    memory refresh.  However, the ULA gets confused if I is in the range
    64-127, because it thinks the processor wants to read from lower 16K
    ram very, very often.  The ULA can't cope with this read-frequency, and
    regularly misses a screen byte.  Instead of the actual byte, the byte
    previously read is used to build up the video signal.  The screen seems
    to be filled with 'snow'; however, the Spectrum won't crash, and
    program will continue to run normally.  There's one program I know of
    that uses this to generate a nice effect: Vectron.  (which has very
    nice music too by the way).  This effect has not been implemented
    however - it's a bit useless (but maybe I'll include it in the future).

    The processor has three interrupt modes, selected by the instructions
    IM 0, IM 1 and IM 2.  In mode 1, the processor simply executes a RST
    #38 instruction if an interrupt is requested.  This is the mode the
    Spectrum is normally in.  The other mode that is commonly used is IM 2.
    If an interrupt is requested, the processor first builds a 16 bit
    address by combining the I register (as the high byte) with whatever
    the interrupting device places on the data bus.  The processor then
    fetches the 16-bit address at this interrupt table entry, and finally
    CALLs the subroutine at that address.  Rodnay Zaks in his book
    'Programming the Z80' states that only even bytes are allowed as low
    index byte, but that isn't true.  The normal Spectrum contains no
    hardware to place a byte on the bus, and the bus will therefore always
    read FF (because the ULA also doesn't read the screen if it generates
    an interrupt), so the resulting index address is 256*I+0FF.  However,
    some not-so-neat hardware devices put things on the data bus when they
    shouldn't, so later programs didn't assume the low index byte was 0FF.
    These programs contain a 257 byte table of equal bytes starting at
    256*I, and the interrupt routine is placed at an address that is a
    multiple of 257.  A useful but not so much used trick is to make the
    table contain FF's (or use the ROM for this) and put a byte 18 hex, the
    opcode for JR, at FFFF.  The first byte of the ROM is a DI, F3 hex, so
    the JR will jump to FFF4, where a long JP to the actual interrupt
    routine is put.

    In interrupt mode 0, the processor executes the instruction that the
    interrupting device places on the data bus.  On a standard Spectrum
    this will be the byte FF, coincidentally (...) the opcode for RST #38.
    But for the same reasons as above, this is not really reliable.

    The 50 Hz interrupt is synchronized with the video signal generation by
    the ULA; both the interrupt and the video signal are generated by it.
    Many programs use the interrupt to synchronize with the frame cycle.
    Some use it to generate fantastic effects, such as full-screen
    characters, full-screen horizon (Aquaplane) or pixel colour (Uridium
    for instance).  Many modern programs use the fact that the screen is
    'written' (or 'fired') to the CRT in a finite time to do as much
    time-consuming screen calculations as possible without causing
    character flickering:  although the ULA has started displaying the
    screen for this frame already, the electron beam will for a moment not
    'pass' this-or-that part of the screen so it's safe to change something
    there. So the exact time in the 1/50 second time-slice at which the
    screen is updated is very important.  Normally the emulator updates the
    entire screen at once (50 times a second), and no best solution can be
    given as to when exactly the screen should be updated.  The user can
    select one of three possibilities (low, normal and high video
    synchronisation, corresponding to a screen update after 1/200, 2/200 or
    3/200 of a (relative) second after a Z80 interrupt) to try to get the
    best results.  Try for instance Zynaps; with normal video
    synchronisation the top four or five lines of the background move
    out-of-phase with the rest, and your space-ship flickers in that
    region.  With low video synchronisation the background moves smoothly
    but the sprites flicker in all parts of the screen.  Only with high
    video sync everything moves smoothly and doesn't flicker.

    In Hi-resolution color emulation mode, however, the emulator makes a
    copy of every screen- and attribute-line in a buffer at the exact time
    the ULA would display it.  Also, the exact times the border colour is
    changed is stored.  Using this information the emulator builds the
    screen; in this way, what you see on your PC monitor is exactly what a
    real Spectrum would display on a television.  Remember Aquaplane, with
    its full-width horizon?

    Each line takes exactly 224 T states.  After an interrupt occurs, 64
    line times pass before the byte 16384 is displayed.  At least the last
    48 of these are actual border-lines.  I could not determine whether my
    monitor didn't display the others or whether it was in vertical
    retrace, but luckily that's not really important.  Then the 192
    screen+border lines are displayed, followed by 56 border lines again.
    This makes a total of 312 lines of 224 T states, or 69888 T states,
    which is, at 3.5 MHz, very nearly 1/50th of a second.

    Now for the timings of each line itself.  I define a screen line to
    start with 256 screen pixels, then border, then horizontal retrace, and
    then border again.  All this takes 224 T states.  Every half T state a
    pixel is written to the CRT, so if the ULA is reading bytes it does so
    each 4 T states (and then it reads two: a screen and an ATTR byte). The
    border is 48 pixels wide at each side.  A video screen line is
    therefore timed as follows: 128 T states of screen, 24 T states of
    right border, 48 T states of horizontal retrace and 24 T states of left
    border.

    When an interrupt occurs, the running instruction has to be completed
    first.  The Z80 samples the state of its interrupt request line at the
    start of the last T state of each instruction.  The Z80 starts to act
    upon an interrupt request at least 1, and at most 1+23 T states after
    it is made active, as the slowest instructions (e.g. INC (IX+d), RL
    (IX+d), EX (SP),IX) take 23 T states.  This difference, which may be
    hard to control, is sometimes significant in practice for hi-resolution
    color effects.

    In interrupt mode 0, the processor takes 2 more T states for executing
    the opcode supplied than the normal value; if RST #38 is supplied
    (#FF), it takes 13 T states.  In interrupt mode 1, my reference gives
    two values (12 and 13 T states) for the timing of a mode 1 interrupt.
    I would put my money on 12 T states.  A mode 2 interrupt takes 19 T
    states.  Finally, a Non Maskable interrupt is fastest: it takes only 11
    T states.

    The ZX81 hardware generates a WAIT only 16 T states before it generates
    an NMI, which, by some combined hardware and software wizardry,
    generates one scanline on the television screen.  It seems therefore
    that by executing a whole lot of slow instructions in a block, it is
    possible to jam the horizontal synchonisation of the ZX81 video signal.
    Has this ever been tried?

    Now when to OUT to the border to change it at the place you want?
    First of all, you cannot change the border within a 'byte', an 8-pixel
    chunk. If we forget about the screen for a moment, if you OUT to port
    FE after 14326 to 14329 T states (including the OUT) from the start of
    the IM 2 interrupt routine, the border will change at exactly the
    position of byte 16384 of the screen.  The other positions can be
    computed by remembering that 8 pixels take 4 T states, and a line takes
    224 T states.  You would think that OUTing after 14322 to 14325 T
    states, the border would change at 8 pixels left of the upper left
    corner of the screen.  This is right for 14322, 14323 and 14324 T
    states, but if you wait 14325 T states the ULA happens to be reading
    byte 16384 (or 22528, or both) and will halt the processor for a while,
    thereby making you miss the 8 pixels.  This exception happens again
    after 224 T states, and again after 448, an so forth.  These 192
    exceptions left of the actual screen rectangle are the only ones;
    similar things don't happen at the right edge because the ULA don't
    need to read things there - it has just finished!

    As noted above, reading or writing in low ram (or OUTing to the ULA!)
    causes the ULA to halt the processor.  When and how much?  The
    processor is halted each time you want to access the ULA or low memory
    and the ULA is busy reading.  Of the 312 'lines' the ULA generates,
    only 192 contain actual screen pixels, and the ULA will only read bytes
    during 128 of the 224 T states of each screen line.  But if it does,
    the processor seems to be halted for 64 T states.  It is not clear to
    me when, and for how long exactly, the ULA halts the processor.
    Sometimes the ULA even stops the processor when it is not interfering
    with it (when it is busy making the border left or right of the screen
    rectangle).

    Finally, the 128K timings.  These are slightly different from the 48K
    video timings, causing for instance the loading bars in the border to
    move differently (which can be seen most clearly when saving).  The
    really important difference of the 128K with respect to the video is
    that the 128K ULA is more relaxed in giving the Z80 access to (screen)
    memory.  This allows programs to make hi-resolution color effects not
    only in the border, but also on the screen itself.  Many 128K programs
    use this effect.  Note however that, although the 128K ULA is more
    relaxed towards memory access, it does still halt the Z80 occasionally.
    Partly for this reason it is impossible to have hi-res color effect
    over the entire screen; there is only time to change approximately half
    of it.

    The basic video timings, with the Z80 out of the way, are as follows.
    Each video line takes 228 T states, 4 T states more than on the 48K
    Spectrum.  It starts with 128 T states of screen pixels (or border).
    Then there's border, horizontal retrace and border again, of 100 T
    states.  A complete '50 Hz' frame consists of 311 video lines (of which
    a few are vertical retraces), that is, 1 less than for 48K models.  A
    complete frame is 311 x 228 = 70908 T states long.

    I don't know whether the 128K model uses a different crystal.  If not,
    one frame on the Spectrum 128K is 1.5% longer than a 48K frame.

    Directly after an interrupt is generated by the ULA (so slightly before
    the Z80 acts upon it), 63 video lines are written to the CRT.  A first
    few may be verical retraces; this is difficult to find out without an
    oscilloscope, but it isn't useful information either.  Then 192 screen
    lines are written, and then 56 border lines and (possibly) vertical
    retrace lines.  The first screen byte is written to the screen 14364 T
    states after the interrupt was generated.



5.2  The Interface I


    The Interface I is quite complicated.  It uses three different I/O
    ports, and contains logic to page and unpage an 8K ROM if new commands
    are used.  I won't be very detailed here; you could refer to the source
    code of the emulator if you want to know some details, or read the
    'Spectrum Shadow ROM Disassembly' by Gianlura Carri, published by
    Melbourne House - but don't expect the same level of detail as of Ian
    Logan and Frank O'Hara in their Rom disassembly book.

    The ROM is paged if the processor executes the instruction at ROM
    address 0008 or 1708 hexadecimal, the error and close# routines.  It is
    inactivated when the Z80 executes the RET at address 0700.

    I/O Port E7 is used to send or receive data to and from the microdrive.
    Accessing this port will halt the Z80 until the Interface I has
    collected 8 bits from the microdrive head; therefore, it the microdrive
    motor isn't running, or there is no formatted cartridge in the
    microdrive, the Spectrum hangs.  This is the famous 'IN 0 crash'.

    Port EF is used for several things:


       Bit    7   6    5    4    3    2    1     0
            ┌───┬───┬────┬────┬─────┬───┬─────┬─────┐
        READ│   │   │    │busy│ dtr │gap│ sync│write│
            │   │   │    │    │     │   │     │prot.│
            ├───┼───┼────┼────┼─────┼───┼─────┼─────┤
       WRITE│   │   │wait│ cts│erase│r/w│comms│comms│
            │   │   │    │    │     │   │ clk │ data│
            └───┴───┴────┴────┴─────┴───┴─────┴─────┘


    Bits DTR and CTS are used by the RS232 interface.  The WAIT bit is used
    by the Network to synchronise, GAP, SYNC, WR_PROT, ERASE, R/_W, COMMS
    CLK and COMMS DATA are used by the microdrive system.  If the
    microdrive is not being used, the COMMS DATA output selects the
    function of bit 0 of out-port F7:


       Bit      7    6   5   4   3   2   1       0
            ┌──────┬───┬───┬───┬───┬───┬───┬───────────┐
        READ│txdata│   │   │   │   │   │   │    net    │
            │      │   │   │   │   │   │   │   input   │
            ├──────┼───┼───┼───┼───┼───┼───┼───────────┤
       WRITE│      │   │   │   │   │   │   │net output/│
            │      │   │   │   │   │   │   │   rxdata  │
            └──────┴───┴───┴───┴───┴───┴───┴───────────┘


    TXDATA and RXDATA are the input and output of the RS232 port.  COMMS
    DATA determines whether bit 0 of F7 is output for the RS232 or the
    network.




5.3  The SamRam


    The SamRam contains a 32K static CMOS Ram chip, and some I/O logic for
    port 31.  If this port is read, it returns the position of the
    joystick, as a normal Kempston joystickinterface would.  If written to,
    the port controls a programmable latch chip (the 74LS259) which
    contains 8 latches:


       Bit    7   6   5   4   3   2   1   0
            ┌───┬───┬───┬───┬───┬───┬───┬───┐
       WRITE│   │   │   │   │  address  │bit│
            └───┴───┴───┴───┴───┴───┴───┴───┘


    The address selects on of the eight latches; bit 0 is the new state of
    the latch.  The 16 different possibilities are collected in the diagram
    below:

        OUT 31,   │  Latch  │ Result
        ──────────┼─────────┼────────────────────────────────────────
            0     │    0    │ Switch on write protect of CMOS RAM
            1     │    "    │ Writes to CMOS RAM allowed
            2     │    1    │ turn on CMOS RAM (see also 6/7)
            3     │    "    │ turn off CMOS RAM (standard Spec.  ROM)
            4     │    2    │ -
            5     │    "    │ Ignore all OUT's to 31 hereafter
            6     │    3    │ Select CMOS bank 0 (Basic ROM)
            7     │    "    │ Select CMOS bank 1 (Monitor,...)
            8     │    4    │ Select interface 1
            9     │    "    │ Turn off IF 1 (IF1 rom won't be paged)
           10     │    5    │ Select 32K ram bank 0 (32768-65535)
           11     │    "    │ Select 32K ram bank 1 (32768-65535)
           12     │    6    │ Turn off beeper
           13     │    "    │ Turn on beeper
           14     │    7    │ -
           15     │    "    │ -

    At reset, all latches are 0.  If an OUT 31,5 is issued, only a reset
    will give you control over the latches again.  The write protect latch
    is not emulated; you're never able to write the emulated CMOS ram in
    the emulator.  Latch 4 will pull up the M1 output of the Z80.  The
    Interface I won't page the ROM anymore then.




5.4  The Z80 microprocessor


    The Z80 processor is quite straightforward, and contains to my
    knowledge no interesting bugs or quirks.  However, it has some
    undocumented features.  Some of these are quite useful, and some are
    not, but since many programs use the useful ones, and a few programs
    use the weird ones, I tried to figure them out and emulate them as best
    as I could.  There is a Z80 emulator around, intended as a CP/M
    emulator, which halts the program if an undocumented opcode is
    encountered.  I don't think this makes sense.  ZiLOG doesn't dictate
    the law, the programs which use the processor's features do!

    In section 5.1 there is some information on Z80 interrupt timings in
    different modes.

    Most Z80 opcodes are one byte long, not counting a possible byte or
    word operand.  The four opcodes CB, DD, ED and FD are 'shift' opcodes:
    they change the meaning of the opcode following them.

    There are 248 different CB opcodes.  The block CB 30 to CB 37 is
    missing from the official list.  These instructions, usually denoted by
    the mnemonic SLL, Shift Left Logical, shift left the operand and make
    bit 0 always one.  Bounder and Enduro Racer use them, to name just two.
    The SamRam monitor can disassemble these and uses the mnemonic SLL.
    These instructions are quite commonly used.

    The DD and FD opcodes precede instructions using the IX and IY
    registers.  If you look at the instructions carefully, you see how they
    work:

        2A nn           LD HL,(nn)
        DD 2A nn        LD IX,(nn)
        7E              LD A,(HL)
        DD 7E d         LD A,(IX+d)

    A DD opcode simply changes the meaning of HL in the next instruction.
    If a memory byte is addressed indirectly via HL, as in the second
    example, a displacement byte is added.  Otherwise the instruction
    simply acts on IX instead of HL.  (A notational awkwardness, that will
    only bother assembler and disassembler writers: JP (HL) is not
    indirect; it should have been denoted by JP HL)  If a DD opcode
    precedes an instruction that doesn't use the HL register pair at all,
    the instruction is executed as usual.  However, if the instruction uses
    the H or L register, it will now use the high or low halves of the IX
    register! Example:

        44              LD B,H
        FD 44           LD B,IYh

    These types of inofficial instructions are used in many programs. By
    the way, many DD or FD opcodes after each other will effectively be
    NOPs, doing nothing except repeatedly setting the flag 'treat HL as IX'
    (or IY) and taking up 4 T states.  (But try to let MONS disassemble
    such a block.)

    The doubly-shifted opcodes that start with DD CB and DD ED behave
    differently.  If a DD or FD precedes an ED instruction, the DD or FD is
    ignored.  ED instructions never operate on the IX or IY register, and
    are executed normally instead.  With CB instructions, the situation is
    more interesting.  Within an 8-instruction block, every DD CB
    instruction works as the official one, but also copies the result to
    the specified register (except when it is (HL)).  For example,

        CB CE           SET 0,(HL)
        CB C0           SET 0,B
        DD CB nn CE     SET 0,(IX+nn)
        DD CB nn C0     SET 0,(IX+nn) ; copy result to B

    (The information about the inofficial CB instructions was given to me
    by Arnt Gulbrandsen, and originated from David Librik.)

    There are a number of inofficial ED instructions, but none of them are
    very useful.  The ED opcodes in the range 00-3F and 80-FF (except for
    the block instructions of course) do nothing at all but taking up 8 T
    states and incrementing the R register by 2.  Most of the unlisted
    opcodes in the range 40-7F do have an effect, however.  The complete
    list: (* = not official)

        ED40   IN B,(C)                 ED60   IN H,(C)
        ED41   OUT (C),B                ED61   OUT (C),H
        ED42   SBC HL,BC                ED62   SBC HL,HL
        ED43   LD (nn),BC               ED63 * LD (nn),HL
        ED44   NEG                      ED64 * NEG
        ED45   RETN                     ED65 * RET
        ED46   IM 0                     ED66 * IM 0
        ED47   LD I,A                   ED67   RRD
        ED48   IN C,(C)                 ED68   IN L,(C)
        ED49   OUT (C),C                ED69   OUT (C),L
        ED4A   ADC HL,BC                ED6A   ADC HL,HL
        ED4B   LD BC,(nn)               ED6B * LD HL,(nn)
        ED4C * NEG                      ED6C * NEG
        ED4D   RETI                     ED6D * RET
        ED4E * IM 0                     ED6E * IM 0
        ED4F   LD R,A                   ED6F   RLD
        ED50   IN D,(C)                 ED70 * IN (C)
        ED51   OUT (C),D                ED71 * OUT (C),0
        ED52   SBC HL,DE                ED72   SBC HL,SP
        ED53   LD (nn),DE               ED73   LD (nn),SP
        ED54 * NEG                      ED74 * NEG
        ED55 * RET                      ED75 * RET
        ED56   IM 1                     ED76 * IM 1
        ED57   LD A,I                   ED77 * NOP
        ED58   IN E,(C)                 ED78   IN A,(C)
        ED59   OUT (C),E                ED79   OUT (C),A
        ED5A   ADC HL,DE                ED7A   ADC HL,SP
        ED5B   LD DE,(nn)               ED7B   LD SP,(nn)
        ED5C * NEG                      ED7C * NEG
        ED5D * RET                      ED7D * RET
        ED5E   IM 2                     ED7E * IM 2
        ED5F   LD A,R                   ED7F * NOP

    The ED70 instruction reads from port (C), just like the other
    instructions, but throws away the result.  It does change the flags in
    the same way as the other IN instructions, however.  The ED71
    instruction OUTs a byte zero to port (C), interestingly.  These
    instructions 'should', by regularity of the instruction set, use (HL)
    as operand, but since from the processor's point of view accessing
    memory or accessing I/O devices is almost the same thing, and since the
    Z80 cannot access memory twice in one instruction (disregarding
    instruction fetch of course) it can't fetch or store the data byte.  (A
    hint in this direction is that, even though the NOP-synonyms LD B,B, LD
    C,C etcetera do exist, LD (HL),(HL) is absent and replaced by the HALT
    instruction.)

    The instructions ED 4E and ED 6E are IM 0 equivalents: when FF was put
    on the bus at interrupt time, the Spectrum continued to execute
    normally, whereas when an EF (RST #28) was put on the bus it crashed,
    just as it does in that case when the Z80 is in the official interrupt
    mode 0.  In IM 1 the Z80 just executes a RST #38 (opcode FF) no matter
    what is on the bus.

    The RETI instruction is functionally exactly equivalent to the RET
    instruction.  It is used only to signify the end of an interrupt
    routine to an external hardware device (read: the Z80 PIO).  The RETN
    however is different from RET in that it resets IFF1 to the current
    value of IFF2.  Now IFF1 and IFF2 are usually equal (and become equal
    after DI and EI and after a maskable interrupt has been accepted).
    They're different only if an NMI occurs when interrupts are enabled;
    then IFF1 is off, and IFF2, holding the previous state of the interrupt
    flip flop, is on, signifying that interrupts were enabled before the
    non-maskable interrupt.  Since the state of IFF2 can be read by using
    LD A,R and LD A,I, the RETN instruction is not used much in Spectrum
    ROM software, and it is utterly useless in normal software.  In other
    words, I have not tried to figure out whether the unofficial RET's are
    RETI's or RETN's.

    About the R register.  This is not really an undocumented feature,
    although I have never seen any thorough description of it anywhere.
    The R register is a counter that is updated every instruction, where
    DD, FD, ED and CB are to be regarded as separate instructions.  So
    shifted instructions will increase R by two.  There's an interesting
    exception: doubly-shifted opcodes, the DDCB and FDCB ones, increase R
    by two too. LDI increases R by two, LDIR increases it by 2 times BC, as
    does LDDR etcetera.  The sequence LD R,A / LD A,R increases A by two.
    The highest bit of the R register is never changed (except possibly by
    LD R,A of course).  This is because in the old days everyone used 16
    Kbit chips.  Inside the chip the bits where grouped in a 128x128
    matrix, needing a 7 bit refresh cycle.  Therefore ZiLOG decided to
    count only the lowest 7 bits.  If the R register emulation is switched
    on the R register will behave as is does on a real Spectrum; if it is
    off it will (except for the upper bit) act as a random generator.

    You can easily check that the R register is really crucial to memory
    refresh.  Assemble this program:

        ORG 32768
        DI
        LD B,0
    L1  XOR A
        LD R,A
        DEC HL
        LD A,H
        OR L
        JR NZ,L1
        DJNZ L1
        EI
        RET

    It will take about three minutes to run.  Look at the upper 32K of
    memory, for instance the UDG graphics.  It will have faded.  Only the
    first few bytes of each 256 byte block will still contain zeros,
    because they were refreshed during the execution of the loop.  The ULA
    took care of the refreshing of the lower 16K.  (This example won't work
    on the emulator of course!)

    Then there's one other dark corner of the Z80 which has its effect on
    programs like Sabre Wulf, Ghosts'n Goblins and Speedlock.  The Mystery
    of the Undocumented Flags!

    Bit 3 and 5 of the F register are not used.  They can contain
    information, as you can readily figure out by using PUSH AF and POP AF.
    Furthermore, sometimes their values change.  I found the following
    empirical rule:

        The values of bit 7, 5 and 3 follow the values of the
        corresponding bits of the last 8 bit result of an instruction
        that changed the usual flags.

    For instance, after an ADD A,B those bits will be identical to the bits
    of the A register.  (Bit 7 of F is the sign flag, and fits the rule
    exactly).  An exception is the CP x instruction (x=register, (HL) or
    direct argument).  In that case the bits are copied from the argument.

    If the instruction is one that operates on a 16 bit word, the 8 bits of
    the rule are the highest 8 bits of the 16 bit result - that was to be
    expected since the S flag is extracted from bit 15.

    Ghosts'n Goblins use the undocumented flag due to a programming error.
    The rhino in Sabre Wulf walks backward or keeps running in little
    circles in a corner, if the (in this case undocumented) behaviour of
    the sign flag in the BIT instruction isn't right.  I quote:

        AD86    DD CB 06 7E        BIT 7,(IX+6)
        AD8A    F2 8F AD           JP P,#AD8F

    An amazing piece of code!  Speedlock does so many weird things that
    everything must be exactly right for it to run.  Finally, the '128 rom
    uses the AF register to hold the return address of a subroutine for a
    while.  To keep all programs happy, and still have a fast emulator, I
    had to make a compromise.  The undocumented flags are not always
    emulated right, but they are most of the time.  Not telling you when
    not.

    Now for the emulated Z80.  I have added eight instructions, to speed up
    the RS232 input and output of the Interface I and several things of the
    SamRam.  These opcodes, ED F8 to ED FE are of little use to any other
    program.  ED FF is a nice one: it returns you to DOS immediately.  I
    used it for debugging purposes, and it is also used in TAP2TAPE and
    SAMLIST.

    The opcode ED F6, which is used by the SamRam, is now also used to use
    multi-load games on the emulator.  If the emulator encounters the
    opcode ED F6 in RAM (above 16384), it loads a block of code into memory
    at address HL.  The name of the file to be loaded is the name of the
    snapshot file currently run, with the decimal value of the A register
    attached to it.  The extension is .DAT.  If such a file is not found,
    the user is informed of the value of the A register and allowed to
    supply a file name himself (no sexual prejudice implied).




5.5  File formats


    This section describes the format of the files used by the emulator.



    ROMS.BIN:
    ---------

        00000-03fff     Ordinary Spectrum rom
        04000-05fff     Interface I rom (8K)
        06000-09fff     First SamRam rom (contains BASIC)
        0a000-0dfff     Second SamRam rom (contains monitor,...)
        0e000-11fff     First Spectrum 128K rom (active at RESET)
        12000-15fff     Second Spectrum 128K rom (contains BASIC)
        16000-19fff     Disciple rom, system file 3b, Epson printer code
        1a000-1dfff     Disciple rom, system file 3b, HP printer code
        1e000-1ffff     Multiface rom (8K)

    The ordinary rom has not been modified.  The Interface I rom has
    undergone some modifications, to speed up the RS232 input/output
    routines.  If you don't like this, or want to use another version of
    the Interface I, you could put that code at the right place in the
    ROMS.BIN file.  The interface I should work properly, although the
    RS232 will be slower (always FORMAT the "b" or "t" channel at 19200
    baud, by the way, if you replace the rom code, there's no point in
    waiting for nothing.) The microdrive routines have not been modified in
    any way.  Here are the changes of the Interface I rom:

        Address: Old: New:           Address: Old: New:

        0B9E     ED   ED             0D20     FB   00
        0B9F     5B   FC             0D2A     37   ED
        0BA0     C3   F5             0D2B     F3   FD
        0BA1     5C   C3             0D2C     CE   18
        0BA2     21   34             0D2D     00   10
        0BA3     20   0C             0D4C     FB   00

    These changes are not likely to cause problems; there are several
    versions of the Interface I rom around, and program developers know
    this.  It is also a bit pointless to check whether the Interface I rom
    hasn't been modified; who would put his snapshot software in there
    anyway, and that's what those people are afraid of.

    The first and second SamRam rom have been modified more extensively.
    The biggest problem was that switching the upper 32K ram bank is very
    fast in reality, but on the PC two blocks of 32K bytes had to be REP
    MOVSWded (or the EMS emulator be called).  But since no programs know
    of the SamRam code anyway, this won't cause any more problems it
    wouldn't already cause either.

    The two Spectrum 128 roms have not been modified, and neither have the
    Disciple roms or the Multiface rom.  The Disciple roms, as they appear
    in the ROMS.BIN file, do have system files pre-loaded however.



    .TAP FILES:
    -----------

    The .TAP files contain blocks of tape-saved data.  All blocks start
    with two bytes specifying how many bytes will follow (not counting the
    two length bytes).  Then raw tape data follows, including the flag and
    checksum bytes.  The checksum is the bitwise XOR of all bytes including
    the flag byte.  For example, when you execute the line SAVE "ROM" CODE
    0,2 this will result:


             |------ Spectrum-generated data -------|       |---------|

       13 00 00 03 52 4f 4d 7x20 02 00 00 00 00 80 f1 04 00 ff f3 af a3

       ^^^^^...... first block is 19 bytes (17 bytes+flag+checksum)
             ^^... flag byte (A reg, 00 for headers, ff for data blocks)
                ^^ first byte of header, indicating a code block

       file name ..^^^^^^^^^^^^^
       header info ..............^^^^^^^^^^^^^^^^^
       checksum of header .........................^^
       length of second block ........................^^^^^
       flag byte ............................................^^
       first two bytes of rom .................................^^^^^
       checksum (checkbittoggle would be a better name!).............^^


    The emulator will always start reading bytes at the beginning of a
    block.  If less bytes are loaded than are available, the other bytes
    are skipped, and the last byte loaded is used as checksum.  If more
    bytes are asked for than exist in the block, the loading routine will
    terminate with the usual tape-loading-error flags set, leaving the
    error handling to the calling Z80 program.

    Note that it is possible to join .TAP files by simply stringing them
    together, for example COPY /B FILE1.TAP + FILE2.TAP ALL.TAP

    For completeness, I'll include the structure of a tape header.  A
    header always consists of 17 bytes:

        Byte    Length  Description
        0       1       Type (0,1,2 or 3)
        1       10      Filename (padded with blanks)
        11      2       Length of data block
        13      2       Parameter 1
        15      2       Parameter 2

    The type is 0,1,2 or 3 for a Program, Number array, Character array or
    Code file.  A screen$ file is regarded as a Code file with start
    address 16384 and length 6912 decimal.  If the file is a Program file,
    parameter 1 holds the autostart line number (or a number >=32768 if no
    LINE parameter was given) and parameter 2 holds the start of the
    variable area relative to the start of the program.  If it's a Code
    file, parameter 1 holds the start of the code block when saved, and
    parameter 2 holds 32768.  For data files finally, the byte at position
    14 decimal holds the variable name.



    .MDR FILES:
    -----------

    The emulator uses a cartridge file format identical to the 'Microdrive
    File' format of Carlo Delhez' Spectrum emulator Spectator for the QL,
    who devised the format.  This format is now also supported by XZX of
    Des Harriot.  The following information is adapted from Carlo's
    documentation.  It can also be found in the 'Spectrum Microdrive Book',
    by Ian Logan (co-writer of the excellent 'Complete Spectrum ROM
    Disassembly').

    A cartridge file contains 254 'sectors' of 543 bytes each, and a final
    byte flag which is non-zero is the cartridge is write protected, so the
    total length is 137923 bytes.  On the cartridge tape, after a GAP of
    some time the Interface I writes 10 zeros and 2 FF bytes (the
    preamble), and then a fifteen byte header-block-with-checksum.  After
    another GAP, it writes a preamble again, with a 15-byte record-
    descriptor-with-checksum (which has a structure very much like the
    header block), immediately followed by the data block of 512 bytes, and
    a final checksum of those 512 bytes.  The preamble is used by the
    Interface I hardware to synchronise, and is not explicitly used by the
    software.  The preamble is not saved to the microdrive file:

    offset length name    contents

      0      1   HDFLAG   Value 1, to indicate header block
      1      1   HDNUMB   sector number (values 254 down to 1)
      2      2            not used
      4     10   HDNAME   microdrive cartridge name (blank padded)
     14      1   HDCHK    header checksum (of first 14 bytes)

     15      1   RECFLG   - bit 0: always 0 to indicate record block
                          - bit 1: set for the EOF block
                          - bit 2: reset for a PRINT file
                          - bits 3-7: not used (value 0)
     16      1   RECNUM   data block sequence number (value starts at 0)
     17      2   RECLEN   data block length (<=512, LSB first)
     19     10   RECNAM   filename (blank padded)
     29      1   DESCHK   record descriptor checksum (of previous 14 bytes)
     30    512            data block
    542      1   DCHK     data block checksum (of all 512 bytes of data
                           block, even when not all bytes are used)
    ---------
    254 times


    (Actually, this information is 'transparent' to the emulator.  All it
    does is store 2 times 254 blocks in the .MDR file as it is OUTed,
    alternatingly of length 15 and 528 bytes.  The emulator does check
    checksums, see below; the other fields are dealt with by the emulated
    Interface I software.)

    A used record block is either an EOF block (bit 1 of RECFLG is 1) or
    contains 512 bytes of data (RECLEN=512, i.e.  bit 1 of MSB is 1).  An
    empty record block has a zero in bit 1 of RECFLG and also RECLEN=0.  An
    unusable block (as determined by the FORMAT command) is an EOF block
    with RECLEN=0.

    The three checksums are calculated by adding all the bytes together
    modulo 255; this will never produce a checksum of 255.  Possibly, this
    is the value that is read by the Interface I if there's no or bad data
    on the tape.

    In normal operation, all first-fifteen-byte blocks of each header or
    record block will have the right checksum.  If the checksum is not
    right, the block will be treated as a GAP.  For instance, if you type
    OUT 239,0 on a normal Spectrum with interface I, the microdrive motor
    starts running and the cartridge will be erased completely in 7
    seconds. CAT 1 will respond with 'microdrive not ready'.  Try it on the
    emulator...




    .OUT FILES:
    -----------

    These files are produced when logging OUTs; see menu option O in the
    Extra Functions menu.  For the specified I/O ports, all OUTs to these
    ports are recorded in the .OUT file, together with the exact time at
    which the OUTs were executed.

    An .OUT file consists of a string of 5-byte blocks.  The first word is
    the timing word; it has a value between 0 and 17471 inclusive (or
    between 0 and 17726 inclusive when a 128K Spectrum was emulated), and a
    unit value corresponds to 1 T state (=1/3494400 s).  After this, the
    OUT port that was written to follows, then the value OUTed itself:

        Offset  Length  Description

        0       2       Time (0-17471 or 0-17726)
        2       2       Port address
        4       1       Value

    Every 1/200th of an emulated second, that is, every 69888/4=17472 T
    states (or 70908/4=17727 T states on 128K Spectrums), a time-wraparound
    block is written to the .OUT file:

        Offset  Length  Description

        0       2       Flag word #FFFF indicating wraparound-block
        2       2       Length of preceding block (17472 or 17727 T)
        4       1       Not used

    So even when the Spectrum does not OUT to the logged ports at all, 1000
    bytes get written to the log file every second.

    By default, an OUT to an even I/O address which does not change the
    state of the MIC and EAR outputs is not written to the .OUT file, to
    save disk space when recording music.  If you want all OUTs, specify
    -xg on the command line.

    The .OUT files are also used to make a simple trace of a running
    Spectrum program.  Specify -xy on the command line; as soon as you
    activate OUT logging, a trace is dumped also.  For each instruction
    encountered during emulation, the following block is written to the
    .OUT file:

        Offset  Length  Description

        0       2       Flag word (#FFFE)
        2       2       Program counter
        5       1       A register

    Furthermore, no time-wraparound blocks are written to the .OUT file
    when tracing.  HALT instructions (118 decimal) are special in that they
    do not generate a block in the log file; this is to make comparisons
    between different logs of the same program easier.  Admittedly, this is
    a very crude way of tracing a program, but it's better than nothing,
    and very useful very occasionally.




    .SCR FILES:
    -----------

    .SCR files are memory dumps of the first 6912 bytes of the Spectrum
    memory.  A coordinate (x,y), x between 0 and 255 and y between 0 and
    192, (0,0) being the upper left corner of the screen, corresponds to
    the pixel address

        16384+INT (x/8)+1792*INT (y/64)-2016*INT (y/8)+256*y

    I admit this is not quite the clearest way to explain the organization
    of Spectrum's video memory, but with a bit or (hard) thinking you can
    extract from above formula all information you need...  The lowest
    three bits of x determine which bit of this address corresponds to the
    pixel (x,y).  This bit-map constitutes the larger part of the screen
    memory, 256*192/8=6144 bytes.  The final 768 bytes are attribute bytes.
    The address of the attribute byte corresponding to pixel (x,y) is

        22528+INT (x/8)+32*INT (y/8)

    The lowest three bits of the attribute byte control the foreground
    color (the color of the pixel if the corresponding bit in the bitmap is
    set), bits 3-5 control the background color, bit 6 is the bright bit
    and bit 7 is the flash bit - if it is set, every 16/50th of a second
    the ULA effectively flips the foreground and background colours.



    .Z80 FILES:
    -----------

    The old .Z80 snapshot format (for version 1.45 and below) looks like
    this:

        Offset  Length  Description

        0       1       A register
        1       1       F register
        2       2       BC register pair (LSB, i.e.  C, first)
        4       2       HL register pair
        6       2       Program counter
        8       2       Stack pointer
        10      1       Interrupt register
        11      1       Refresh register (Bit 7 is not significant!)
        12      1       Bit 0  : Bit 7 of the R-register
                        Bit 1-3: Border colour
                        Bit 4  : 1=Basic SamRom switched in
                        Bit 5  : 1=Block of data is compressed
                        Bit 6-7: No meaning
        13      2       DE register pair
        15      2       BC' register pair
        17      2       DE' register pair
        19      2       HL' register pair
        21      1       A' register
        22      1       F' register
        23      2       IY register (Again LSB first)
        25      2       IX register
        27      1       Interrupt flipflop, 0=DI, otherwise EI
        28      1       IFF2 (not particularly important...)
        29      1       Bit 0-1: Interrupt mode (0, 1 or 2)
                        Bit 2  : 1=Issue 2 emulation
                        Bit 3  : 1=Double interrupt frequency
                        Bit 4-5: 1=High video synchronisation
                                 3=Low video synchronisation
                                 0,2=Normal
                        Bit 6-7: 0=Cursor/Protek/AGF joystick
                                 1=Kempston joystick
                                 2=Sinclair 2 Left joystick (or user
                                   defined, for version 3 .Z80 files)
                                 3=Sinclair 2 Right joystick

    Because of compatibility, if byte 12 is 255, it has to be regarded as
    being 1.  After this header block of 30 bytes the 48K bytes of Spectrum
    memory follows in a compressed format (if bit 5 of byte 12 is one).
    The compression method is very simple: it replaces repetitions of at
    least five equal bytes by a four-byte code ED ED xx yy, which stands
    for "byte yy repeated xx times".  Only sequences of length at least 5
    are coded. The exception is sequences consisting of ED's; if they are
    encountered, even two ED's are encoded into ED ED 02 ED.  Finally,
    every byte directly following a single ED is not taken into a block,
    for example ED 6*00 is not encoded into ED ED ED 06 00 but into ED 00
    ED ED 05 00. The block is terminated by an end marker, 00 ED ED 00.

    That's the format of .Z80 files as used by versions up to 1.45.
    Starting from version 2.0, a different format is used, since from then
    on also 128K snapshots had to be supported.  This new format is used
    for all snapshots, either 48K or 128K.  However, the emulator still
    understands the old format.

    Also note that, although old .Z80 file formats are still understood,
    the emulator will never procude an old format .Z80 file, and also 48K
    snapshots are written in the new format.  But, then again, new .Z80
    file formats can be translated back to the old one (provided that it is
    an 48K snapshot of course) by using ConvZ80.

    Version 2.01 and 3.0 .Z80 files start with the same 30 byte header as
    old .Z80 files used.  Bit 4 and 5 of the flag byte have no meaning
    anymore, and the program counter (byte 6 and 7) are zero to signal a
    version 2.01 or version 3.0 snapshot file.

    After the first 30 bytes, the additional header follows:


        Offset  Length  Description

      * 30      2       Length of additional header block (see below)
      * 32      2       Program counter
      * 34      1       Hardware mode (see below)
      * 35      1       If in SamRam mode, bitwise state of 74ls259.
                        For example, bit 6=1 after an OUT 31,13 (=2*6+1)
                        If in 128 mode, contains last OUT to 7ffd
      * 36      1       Contains 0FF if Interface I rom paged
      * 37      1       Bit 0: 1 if R register emulation on
                        Bit 1: 1 if LDIR emulation on
      * 38      1       Last OUT to fffd (soundchip register number)
      * 39      16      Contents of the sound chip registers
        55      2       Low T state counter
        57      1       Hi T state counter
        58      1       Flag byte used by Spectator (QL spec. emulator)
                        Ignored by Z80 when loading, zero when saving
        59      1       0FF if MGT Rom paged
        60      1       0FF if Multiface Rom paged. Should always be 0.
        61      1       0FF if 0-8191 is RAM
        62      1       0FF if 8192-16383 is RAM
        63      10      5x keyboard mappings for user defined joystick
        73      10      5x ascii word: keys corresponding to mappings above
        83      1       MGT type: 0=Disciple+Epson,1=Discipls+HP,16=Plus D
        84      1       Disciple inhibit button status: 0=out, 0ff=in
        85      1       Disciple inhibit flag: 0=rom pageable, 0ff=not


    The value of the word at position 30 is 23 for version 2.01 files, and
    54 for version 3.0 files.  The starred fields are the ones that
    constitute the version 2.01 header, and their interpretation has
    remained unchanged except for byte 34:

        Value:          Meaning in v2.01        Meaning in v3.0

        0               48k                     48k
        1               48k + If.1              48k + If.1
        2               SamRam                  48k + M.G.T.
        3               128k                    SamRam
        4               128k + If.1             128k
        5               -                       128k + If.1
        6               -                       128k + M.G.T.

    The hi T state counter counts up modulo 4.  Just after the ULA
    generates its once-in-every-20-ms interrupt, it is 3, and is increased
    by one every 5 emulated milliseconds.  In these 1/200s intervals, the
    low T state counter counts down from 17472 to 0, which make a total of
    69888 T states per frame.

    The 5 ascii words (high byte always 0) at 73-82 are the keys
    corresponding to the joystick directions left, right, down (!), up (!),
    fire respectively.  Shift, Symbol Shift, Enter and Space are denoted by
    [,],/,\ respectively.  The ascii values are used only to display the
    joystick keys; the information in the 5 keyboard mapping words
    determine which key is actually pressed (and should correspond to the
    ascii values).  The low byte is in the range 0-7 and determines the
    keyboard row.  The high byte is a mask byte and determines the column.
    Enter for example is stored as 0x0106 (row 6 and column 1) and 'g' as
    0x1001 (row 1 and column 4).

    Byte 60 must be zero, because the contents of the Multiface RAM is not
    saved in the snapshot file.  If the Multiface was paged when the
    snapshot was saved, the emulated program will most probably crash when
    loaded back.

    Bytes 61 and 62 are a function of the other flags, such as byte 34, 59,
    60 and 83.

    Hereafter a number of memory blocks follow, each containing the
    compressed data of a 16K block.  The compression is according to the
    old scheme, except for the end-marker, which is now absent.  The
    structure of a memory block is:


        Byte    Length  Description

        0       2       Length of data (without this 3-byte header)
        2       1       Page number of block
        3       [0]     Compressed data


    The pages are numbered, depending on the hardware mode, in the
    following way:


        Page    In '48 mode     In '128 mode    In SamRam mode

         0      48K rom         rom (basic)     48K rom
         1      Interface I, Disciple or Plus D rom, according to setting
         2      -               rom (reset)     samram rom (basic)
         3      -               page 0          samram rom (monitor,..)
         4      8000-bfff       page 1          Normal 8000-bfff
         5      c000-ffff       page 2          Normal c000-ffff
         6      -               page 3          Shadow 8000-bfff
         7      -               page 4          Shadow c000-ffff
         8      4000-7fff       page 5          4000-7fff
         9      -               page 6          -
        10      -               page 7          -
        11      Multiface rom   Multiface rom   -


    In 48K mode, pages 4,5 and 8 are saved.  In SamRam mode, pages 4 to 8
    are saved.  In '128 mode, all pages from 3 to 10 are saved.  This
    version saves the pages in numerical order.  There is no end marker.