Chip 1998 March/Chip_1998-03_cd.bin/hry/Sinclair/SimDOS2/Z80.DOC

Text File | 1996-11-10 | 169KB | 3,388 lines

Sinclair ZX Spectrum Emulator 'Z80' v3.05  -  11/11/96  -  by G.A. Lunter



Contents:

    1.    INTRODUCTION, REGISTRATION, GENERAL INFORMATION
    1.1   Some general remarks
    1.2   Registration
    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  The utilities READVOC and READSB
    2.20  Quick overview of command line switches, and features
    2.21  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 DISCiPLE and Plus D Interfaces - The system variables
    4.8   The Spectrum 128

    5.    TECHNICAL INFORMATION  (in file TECHINFO.DOC)
    5.1   The Spectrum 48K
    5.2   The Spectrum 128K
    5.3   The AY-3-8912 sound chip
    5.4   The ZX Printer
    5.5   The Interface I
    5.6   The SamRam
    5.7   The Multiface 128
    5.8   The AMX mouse interface
    5.9   The Z80 microprocessor
    5.10  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
      - Supports digital and analogue joysticks, and mouse, controlling
        Cursor, Sinclair, Kempston or user-defined joystick.
      - Emulates Spectrum AMX Mouse interface (used by e.g. Art Studio)
      - Runs on any PC, including oldies with 8088/8086 processor.
      - 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.
      - 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.  This log file can be translated into a .VOC
        sound sample file using OUT2VOC, for both ear and AY soundchip
        output.
      - Simple tracing feature
      - Opcode mapping feature, tags bytes that are executed during
        emulation; useful for debugging and disassembling purposes.
        (It is meant to be used with the disassembler program DNSA by
         Leslie Styles, [e-mail])
      - Multi-level support as in XZX 0.5.2; also support of .SLT files.
      - 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 (95).
      - Supports VGA, EGA, CGA and Hercules video adapters including
        monochrome VGA.  (Support for Plantronics discontinued.)

    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.
    After reading sections 2.1 and 2.2, you will know most of the basics.
    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 AMX 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, 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, which can be found in the separate
    file TECHINFO.DOC.  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 there.

    Please note that the Tatort BBS, which used to be the 'Spectrum
    emulator support BBS', has ceased to exist.

    There is by now a great lot of Spectrum-related information and
    software available on the net.  A good starting point is the FAQ
    (Frequently Asked Questions) list originally started by Marat
    Fayzullin, and now maintained by Damien Burke.  It can be found at
    http://www.cs.bham.ac.uk/~dmb/speccy/faq.html.  It is also available at
    ftp://ftp.nvg.unit.no/pub/sinclair/docs/specfaq.  This latter site
    carries a lot of Spectrum snapshot and Sinclair-related information.
    Highly recommended!  A long list of FTP sites carrying Spectrum
    programs is included in Damien Burke's FAQ list.

    If you have access to internet newsgroups, take a look at
    comp.sys.sinclair, where many Sinclair enthousiasts meet and share
    thoughts.  You will find lots of well-informed people there.  Please
    read the aforementioned FAQ file before asking questions, but be
    invited to join in afterwards.  Note: Please do *not* post binaries to
    the comp.sys.sinclair newsgroup!





1.2  Registration


    '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-304.ZIP archive file, which
    should contain the following 12 files:

        Z80.EXE      - The emulator itself.
        Z80.INI      - Default initialisation file (used by Z80.EXE).
        Z80.PIF      - Program Info File to run 'Z80' under Windows
        Z80.ICO      - Windows icon.
        Z80.DOC      - Documentation file for the emulator.
        Z80FAQ.DOC   - Frequently asked questions and answers.
        REGISTER.DOC - This file.
        NEW.DOC      - The What's New file.
        ROMS.BIN     - Various ROM images (used by Z80.EXE).
        TECHINFO.DOC - Technical info about the Spectrum etc.
        LAYOUT.SCR   - Keyboard layout help screen (used by Z80.EXE).
        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 displays a message when the
    program is started, and will only run normally for five minutes, after
    which the program cannot be slowed down anymore.  Furthermore, 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
                   translate 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.)
        ADDDAT   - Utility to edit the additional data part of .SLT
                   snapshot files, which contain loading screens and level
                   data.
        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.
        READSB   - Reads .VOC sound samples from SoundBlaster using DMA,
                   and applies a digital filtering and oversampling algo-
                   rithm tuned for Spectrum tapes.
        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, but you will receive everything
    stated above (including the DISCIPLE program); the only difference is
    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 Jimaz in the Czech Republic,
    or David Pomeroy in New Zealand, whichever is most convenient.  Please
    note that Friendware in Spain and Sinclair Freakeren are no longer
    registration sites.

    IMPORTANT NOTE:

    When sending registrations, please either PRINT your order and address,
    or use BLOCK CAPITALS to aid readability.  If you use a postal cheque
    service, or direct transfer, please try to also send a letter to the
    site with details of the payment etc.  Many payment slips are
    unreadable copies.



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

    The registration fee is BP 20 or BP 15 (BP=British Pound) for the
    version with or without DISCiPLE/Plus D emulation respectively.
    Payment can be by cheques (Sterling on a UK bank, or Eurocheques) or UK
    postal order made payable to B G Services.  You can also transfer
    directly to the Giro account 324.82.16  (B G Services).  Girobank plc,
    Bootle, Merseyside G1R 0AA.

    You can also send money in cash.  Please send British Pounds and no
    other currencies!

    Please do not use other currencies than British Pounds on cheques; it
    is not economic to change.  If it is the only option available, please
    add BP 8 to cover drawing costs.  I regret I cannot accept orders via
    charge or credit card.

    The address is:

                B G Services
                64 Roebuck Road
                Chessington
                Surrey KT9 1JX
                (United Kingdom)

    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 14.50.
    These are professional quality items built into 25W 'D' connectors.
    (If this archive is old, please enquire on price before ordering)

    Files will be on a 3.5" HD disc together with some ready converted
    software, which is either PD, or has the approval of the authors.
    Other disc sizes may be requested, but these may not contain all the
    extra files.




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

    Registration via B G Services is fastest, and is preferred.  In some
    cases, however, sending money to The Netherlands may be more convenient.

    Dutch users can transfer NLG 50,- (full version) or NLG 35,-- (without
    Disciple emulation) to the following Giro account:

        59.45.263  (G.A. Lunter, Groningen)

    The registration fee of BP 20/BP 15, US$ 30/US$ 25, DM 50/DM 40, can
    also be sent, in cash, to the following address:

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

    Any other (convertible) currency of an approximately equivalent amount
    will also be accepted.  From Spain and Italy, postal money orders work
    best.

    Eurocheques can also be accepted.  Please do NOT use other currencies
    than Dutch Guilders (NLG), and do NOT fill in the place you live, but
    write 'Groningen' or leave blank.  Cheques that are filled in
    differently cost HFL 15-25 to draw.




    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.



    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$.



                              ==================



    All sites reserve the right to ignore any order which does not comply
    with the conditions above.

    If you have an older registered version and wish to upgrade, please
    contact your registration site, sending return postage.  Updates within
    the same version number and normally sent free if a disc and return
    postage is received.  Updates from previous versions will carry a small
    update fee.





1.3  Other emulators


    I used to have a list of other emulators for the PC and other computers
    here, but the list in Marat Fayzullin/Damien Burke's FAQ was much more
    complete and detailed, so I deleted mine.  It lists:

    14 emulators for PC's,
    6 for the Commodore Amiga,
    4 for the Acorn Archimedes,
    4 for UNIX platforms,
    3 for the Macintosh,
    1 for the Atari ST,
    1 for the NeXTStep, and
    1 very old one for the Commodore 64

    I believe this makes the Sinclair ZX Spectrum the most often emulated
    computer ever!

    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).  There are probably
    more.  For more information, take a look at the FAQ of the newsgroup
    comp.sys.emulators.misc.




1.4  Acknowledgements


    From the very first beginning in november 1988, when I wrote the first
    lines of code for 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, many 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,
    o   Robert Zmyslowicz, Einar Gattoni Saukas, Bernhard Lutz,
            Erik Kunze and Mr. Lee Tonks aka Blood for their thorough
            beta-testing of v3.05.

    and all the people that I forgot to mention.




1.5  Disclaimers


    The last version contained a few bugs, but this version is guaranteed
    to be bug-free.  You can safely operate nuclear power plants or life
    support systems with this software.  And if it still happens to break
    down, feel free to sue me.

    Many of the bugs that disfigured the previous version are gotten rid of
    now.  Most notably, the problem that saving a Disciple/+D snapshot
    caused old data to be overwritten has been fixed.  On the other hand,
    FORMATting Disciple/+D disks still has its problems, but, depending on
    the machine in question, they have overcome in particular cases.

    Many people have sent me bug reports, for which I am very grateful.  I
    have removed most of those, but have not been able to remove them all,
    sometimes because the report was too vague and/or irreproducible on my
    machine, or because of a mixture of reasons like: difficult to find,
    not a problem to most people, easily circumvented, or laziness on my
    part.




1.6  Copyrights etc.


    Amstrad still holds the copyright on the 48K and 128K rom.  However,
    they have kindly 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 640K memory and at least a 80286
    processor, with a VGA, EGA, Hercules or CGA 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), and it reads .SLT files (containing snapshots plus
    additional data, mostly level data for games consisting of various game
    levels).

    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 VGA adapters do not produce a stable picture when Z80 is using the
    standard VGA mode.  If your monitor doesn't sync, try switch -xv.

    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 Colour 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 and Real mode doesn't work anymore.  In
    version 3.04, keyboard handling under Windows is much improved, and
    works as well as without Windows.  If you let the emulator run
    full-screen you may use EGA or VGA, if you want to run it windowed
    you'll 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; even Windows 95 doesn't know how to handle it). 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.

    The emulator measures the speed of the computer it runs on in the
    normal way.  Under Windows 95 this gives reliable results; however,
    Windows 3.1 causes Z80 to run about 3 to 4 times slower than normal.
    You may have to tinker with the speed setting to get it to run at a
    reasonable 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.  If you use this switch under
    Windows, it turns windows compatibility mode OFF, and hangs unless you
    use Hi Resolution Colour emulation (which doesn't rely on the timer).

    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.  Be careful when you change the disk drive
    emulation; when switching an MGT interface (Disciple or +D) on or off,
    it is wise always to reset the emulator, as otherwise the hardware will
    often not match the system variables.

    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 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.

    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.  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 resolution colour emulation, also called 'coppering'.  To
    eliminate flickering of moving characters, and to see some colour
    effects otherwise not visible.  Also, this allows you to see the famous
    loading stripes in the border.  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.

    F - toggle between 50 Hz frame interrupt rate (the standard value) and
    some value defined via the switch -dN, setting the frame rate to 100/N
    Hz.  Without switches, the alternate rate is 100 Hz.  If -dN is used
    the default rate is set to 100/N Hz and alternate rate to 50 Hz; is -dN
    is specified twice (with the same divisor N) then default and alternate
    rate are swapped.

    Doubling the 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 fast machines, this feature is useful for running Spectrum
    programs quickly while keeping a normal keyboard response.  Some
    programs will crash with a frame interrupt rate different from 50 Hz.

    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 res colour emulation instead.  This setting has no effect when
    Hi res colour emulation is on.  (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 (see section 2.21) 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 using the OUT2VOC
    utility.

    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 doubling the
    interrupt frequency (switch -d).  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!

    You can re-map the keyboard by yourself by using the -kx switch.  It
    has the format

        -kxABCD

    where #AB denoted the scan-code (in hex, between #01 and #58) and #CD
    the key that should be pressed when the emulator sees this scan code.
    Normal keys are coded by bytes below #40; the lower three bits denote
    the row number (0-7), and the upper three bits the column number (1-5).
    Column 1 of rows 0-7 are respectively Shift,A,Q,1,0,P,Enter and Space.
    Column 2 to 5 are the keys on the same line, but more toward the
    center.  For instance, C is on row 0, column 4, and has code 0+8*4=32=
    #20.  Function key F11 has scan code #57, so to map F11 to C use
    -kx5720.  Code keys '#CD' in the range #C0 - #DD are used to code for
    special keys.  Here is the list of codes in this range:

        #C0  Edit                          #CF  Joystick left
        #C1  - or _                        #D0  Joystick right
        #C2  + or =                        #D1  + or =
        #C3  Delete                        #D2  Joystick down
        #C4  ; or :                        #D3  Joystick fire
        #C5  " or '                        #D4  F1
        #C6  , or <                        #D5  F2
        #C7  . or >                        #D6  F3
        #C8  / or ?                        #D7  F4
        #C9  *                             #D8  F5
        #CA  Capslock                      #D9  F10
        #CB  Numlock (Shift toggle)        #DA  F6
        #CC  Scroll lock (+CTRL=Quit)      #DB  F7
        #CD  Joystick up                   #DC  F8
        #CE  - or _ (for grey -)           #DD  F9

    Simultaneous keypresses on the PC keyboard are only transmitted to the
    PC to a certain extent, depending on the particular keyboard.  My old
    keyboard could handle TAB and the keys on the numerical keypad
    simultaneously, but my new keyboard can't: when I press TAB and hold it
    down, further key presses on the numeric pad are not seen by the PC
    at all.  There is absolutely nothing to be done about it.  Playing
    games can be a problem sometimes.  You'll have to live with it.  All
    information sent by the keyboard is used.




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 and CGA 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. 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%.

    HRC mode only works with a VGA video adapter.

    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 HRC 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.

    It has proven very difficult to load programs directly via
    SoundBlaster.  This is due to the fact that the emulator does not have
    time to filter the SoundBlaster input (except for a trivial hi-pass
    filter to remove a 50 Hz hum) in Real mode.  For direct loading, the
    LPT interface is strongly recommended.  For loading via the
    SoundBlaster, the utility READSB (see section 2.19) will read in and
    filter the sample.  Loading via READSB is, I think, as reliable as
    loading via the LPT interface.

    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
    then saturates and drops below 50% again.  The volume has to be set
    such that it is just 50% in the non-saturated zone.

    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.

    Please note that in real mode, the PC clock is not updated.  It will
    run behind for as many minutes as real mode has been switched on.  The
    CMOS clock won't be affected, so the next time you start up your
    computer things will be normal again.

    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 containing 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.

    A useful shortcut is ALT-F7: it will automatically select single file
    mode, and prompt for an input .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 some samplers is that they
    leave a small gap between subsequent blocks within the .VOC file.
    These gaps are usually inaudible, but do cause 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.

    READVOC is good at taking samples from the LPT tape interface, but it
    performs worse when used to take samples from sound cards.  You'll be
    better off using samplers provided with the card.

    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, a window
    will pop up, and the emulator switches 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.

    Starting the emulator by "z80 -tv file.voc" will play that .VOC file to
    the EAR input as soon as the emulator starts.  It makes sense also to
    load a .Z80 snapshot file from the command line.  To make a snapshot
    file that starts loading right away, type LOAD "" <ENTER>, press F6
    (real mode), B (back to normal mode), F2 (save snapshot) and save it.




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 or READSB
    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 FB instruction, with A containing the
    level number, and HL the address at which the block is to be loaded.
    The emulator will then try to load the data.  If loading failed, the
    carry flag is toggled; it is untouched if the data was loaded
    successfully.

    The level data can be stored in a .SLT file (Super Loader Trap file),
    which contains a snapshot and can contain data for several levels.  If
    the current program was not loaded from a .SLT file, the emulator will
    look for files with the .DAT extension.  The name is made from the
    snapshot last loaded, with the required level number appended in
    decimal; letters are dropped from the file name if necessary to make
    them at most 8 characters long. If the file is not found, the user is
    informed of the level number, and given the opportunity to specify a
    name.

    .SLT files can be produced using the ADDDAT utility.  See also section
    5.10, file formats, for more information.

    This ED FB feature first appeared in XZX 0.5.2, and was devised by
    Russell Marks.  It is now supported by many other emulators as well.




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 to load the
    rom at address 32768.  Then type

        POKE 48623,0

    to reset the 'open file' counter; failing to do so will result in data
    being overwritten when you use the Plus D snapshot feature as the Plus
    D system will not build up a used-sector-bitmap if this counter is
    non-zero.  You can check that this counter is 1 by typing PRINT PEEK
    48623; this one open file is the file "rom" itself.

    Finally, press F10, X, S for Save Data block, set start address and
    length to 32768 and 16384 (decimal) respectively, and save the ROM by
    the name PLUSDROM.BIN.  If you re-start the emulator now, it will
    emulate the Plus D too.

    (Aside: to use your own version of the DISCiPLE rom, proceed as above,
    but type

        POKE 40431,0

    Note that for this, the base of DISCiPLE's system variables must be
    #0298 = 664 decimal.  If it is different, change above address
    (corresponding to location #1DEF but displaced by #8000 bytes, i.e.
    relative position 6999 decimal).  Then use DEBUG or any flexible
    file cut-and-paste utility to put the 16K file in the correct position
    in the ROMS.BIN file; see file TECHINFO.DOC for the exact position.
    End of aside.)

    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 AMX 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 AMX 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 AMX Mouse does not work
    with SamRam or an M.G.T. interface enabled.  Also, since the AMX
    interface must be initialized, and the state of the AMX 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
    AMX interface.  The program Art Studio re-initializes the AMX interface
    regularly, however, so with this program you don't have to worry about
    it.  You still need to customize the program to use the AMX mouse of
    course, so a snapshot of Art Studio will not automatically work; you
    need to load the original from tape again, and go through the
    customization procedure.




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 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 value.  So it may be
    necessary to supply the initial values of the soundchip registers.  Do
    this by specifying '-i file', where 'file' is the snapshot taken just
    before you started recording the OUTs.

    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 AY soundchip 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; a 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).

    A recent discussion on comp.sys.sinclair revealed that the AY
    conversion of OUT2VOC leaves much to be desired.  It is on my list of
    things-to-do.



2.19  The utilities READVOC and READSB


    These programs can read samples from the LPT port or the SoundBlaster
    and store them in .VOC files, for later play-back to the emulator.
    This is useful when you use the SoundBlaster as input device, as direct
    loading is not very reliable then because Z80 does not filter its input
    appropriately; you can store level data of games on hard-disk and load
    them without having to play the actual tape again; thirdly, this allows
    you to try to load the program with different emulator settings easily.

    READVOC uses polling to read the sample.  This method does not allow
    for very high sample frequencies (even 20 kHz is too much sometimes),
    and does not work reliably in multi-tasking environments (DOS boxes of
    Windows (95) for example).  It is however the only way to take samples
    from the LPT interface, and works well under DOS.

    READSB has been written for taking samples from the SoundBlaster.  It
    uses DMA to read the sample, and applies a digital filtering algorithm
    for reliable loading.  It offers a number of command-line switches.
    Digital filtering is highly recommended: for programs that use the
    ordinary tape format, -n is appropriate; for turbo-save formats, use
    -d.  If neither of -d and -n are used, ordinary analogue sample files
    are produced, which will very often not load successfully when played
    back to Z80.  For low sample rates, say 10 kHz, it is a good thing to
    use two-times oversampling (switch -2).

    When READSB is started, it displays a signal level bar.  Set the volume
    so that a reasonable input level is reached; do not increase the volume
    too much above 50%.  Press any key to start sampling, and then 'p' to
    pause and display the signal level bar again, or any other key to save
    the sample and quit.

    READSB uses 0220 as default base SoundBlaster I/O address, and IRQ 7 as
    default interrupt level.  Be sure to set these to their appropriate
    values if your card is not set to these defaults.

    Both READVOC and READSB produce very large files.  Be sure to have
    several megabytes of free disk space available.  After sampling, these
    sample files can be compressed using ordinary compression programs to
    very small sizes.



2.20  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
       -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.  Versions prior to v3.04 also had Plantronics and Extended
    Hercules as possible video modes; these are removed to save memory.

       -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 colour
    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).

       -dN       Set frame interrupt frequency to 100/N Hz

    There used to be an option -d which set the frame interrupt frequency
    to 100 Hz; therefore now -d is equivalent to -d1.  -d2 is the default
    setting, 50 Hz.  On slow computers, -d helps to get a better keyboard
    response.  On the other hand, setting for instance -z350 -d7 makes Z80
    emulate a Spectrum 3.5 times as fast while maintaining normal keyboard
    response.  At run time, the frame interrupt rate may be toggled between
    50 Hz and the value set by this switch.  If you set -dN twice, then the
    emulator starts off with a 50 Hz frame rate, with alternate rate set to
    100/N Hz.

       -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 AMX mouse interface controlled by MS Mouse
       -kz       Use digital Zandbergen joystick
       -kk       Do not look for analogue or Zandbergen joystick
       -k1       Do not use 2nd analogue joystick as Sinclair 1 (1,2,3,4,5)
       -k2       Use 2nd joystick as Sinclair 1 always

    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 AMX mouse
    interface.  Because of I/O address clashes, this only works with SamRam
    and the M.G.T. interfaces disabled.  The AMX mouse is supported by e.g.
    Art Studio.

    A second analogue joystick will, when present, always be attached to
    keys 1 to 5, the Sinclair 1 joystick keys.  If neither -k1 nor -k2 is
    given, the emulator will look if the second joystick is in an
    acceptable neutral position (i.e. is attached) and if so will use it.
    This will usually work.  If it incorrectly recognizes the joystick use
    -k1.  If it doesn't recognize a joystick while it is connected, use
    -k2.

       -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
       -tp       Pause after loading .TAP block

    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.  It is used in Tap2Tape.

       -xl N     Select LPTn for ZX-Printer output
       -xj       'Off-line=wait' instead of 'Off-line=No ZX Printer'
       -0e       Epson printer (for ZX PRINTER & M.G.T.)
       -0h       HP PCL printer (for ZX PRINTER & M.G.T.)
       -0f N     Issue a Form Feed every N ZX Printer lines when printing
                 to a HP PCL compatible printer

    Output to the ZX Printer will be converted into graphic data in Epson
    (most matrix printers) or HP PCL (most inkjet and laser printers)
    format.  Use -0e or -0h to select which format to use; default is Epson
    format (defaulted in Z80.INI).  Also, this selects the default DISCiPLE
    ROM to be used; the two ROMs have different screen dump routines
    pre-loaded.  If you're using a Laser printer, use -0f 103 to have Z80
    eject the page once in a while.  103 lines approximate one sheet A4.
    Select the LPT port to print the data to with -xl; default is LPT1.

    If the printer to which ZX Printer output is sent is absent, busy or
    off-line, the emulator tells the Spectrum program that the ZX Printer
    is not attached.  If you want the Spectrum program to wait in case of
    an off-line or busy printer, then put -xj in the Z80.INI file.  This
    switch is not defaulted because printers sometimes say they're merely
    busy or off-line when in fact they are not there at all.  Besides, some
    Spectrum programs do a COPY without asking, and with this switch the
    program would lock up (as versions 3.00 to 3.02 did; in v3.03 and above
    you can BREAK into such a loop).

    If a printer becomes off-line or unavailable during printing, Z80 will
    try to finish its job anyhow, and the program may appear to hang.
    Pressing the space bar will make Z80 break the printing loop, and
    signal to the Spectrum program that the ZX Printer does not exist.
    This, in turn, will cause the ROM printer routines to just skip
    printing.  Z80 will periodically check the printer status, and when it
    becomes available again will make the ZX Printer appear again.

       -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].)

       -0sND     Set Disciple/+D drive N to D:

    By default, the Disciple/+D drive 1 controls drive A: while 2 controls
    B:.  If, for example, your B: drive is your only 3.5'' drive, you might
    want to map both 1 and 2 to B: which is accomplished by putting -0s1b
    in the Z80.INI file.

       -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 HRC 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 Resolution Colour emulation
    won't work anymore.

       -tx       Do not display tape info window when loading or saving
       -00       Do not show intro screen, and don't pause at startup

    Some people seem to really hate either, or even both.  Don't know why.
    For better annoyance, -00 only works in the registered version.  Hehe.

       -xe       Do not use expanded memory

    Specifying this switch will result in the emulator using 240K more base
    memory (making a grand total of 564K).  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.10 on the .OUT format for more details.

       -0m F     Build map of opcode locations in file F

    When this option is specified, Z80 keeps a map of the 65536 address
    locations in memory, and tags the address of each instruction that is
    emulated.  When the emulator is shut down, this map is written to disk
    as a 8192 byte file.  See section 5.10 of TECHINFO.DOC for an
    explanation of the file format, and remarks on how to use this feature.

       -xw       Run in Windows compatibility mode

    In this mode, the timer is not re-programmed.  The emulator counts T
    states to see when an interrupt has to be generated (so emulation will
    be slower).  In a Windows (3.1 or 95) DOS box, using -xw will turn
    Windows compatibility mode off (as Z80 is aware of Windows and has
    turned this switch on itself in that case) and the emulator will
    usually hang.  There is probably never a need to use this switch.

       -kxABCD   Press key #CD for scancode #AB.

    This can be used to re-map the keyboard, for instance if your C key is
    broken, you can re-map it to F11, or any other key for that matter.
    Combinations are hard-coded, so that a key pressing , also presses <
    when shifted.  The scan code is between #01 (ESC) and #58 (F12); a full
    list can be found in many places.  The format of the key byte is
    explained in section 2.3.

       -xf       Switch full 16K of Interface I ROM

    Useless.




2.21  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 instructions 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 Colour 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.  Note however that the printer OUT port
    #FB of the ZX Printer is used by the Disciple printer interface, so
    that using the ordinary ZX Printer code of the ROM results in rubbish
    coming out of the printer.  The +D can use the Centronics interface and
    the old ZX Printer at the same time.

    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. Breakpoints

    A Breakpoint may be set in the Extra Functions menu, option B.  If it
    is set, the emulator will at the beginning of each instruction check
    whether the program counter is equal to the breakpoint address.  If
    this is the case, it notifies the user, and continues to the main menu.
    You could now save the snapshot and inspect register values using
    Z80Dump, for example.  You could change hardware mode to SamRam, and
    generate an NMI from the menu (using Extra Functions, N) to inspect the
    code around the breakpoint.

    Some fine points.  If a breakpoint is hit, the instruction at the
    breakpoint address is not yet executed.  It will be upon returning.  If
    you generate an NMI, and subsequently return from it, the first
    instruction that will be executed after the NMI is the instruction at
    the breakpoint; this will thus make the emulator go to the main menu
    once again.  Press ESC to continue emulating.

    For technical reasons, when counting T states, the time taken by the
    instruction directly preceding (in execution) the one at the breakpoint
    address is not taken into account.  When the emulator hits a
    breakpoint, the current frame will be a few T states longer.  Not that
    you'll notice, probably.  The R register is counted through properly
    (if it's emulated, that is.)

    If the breakpoint address happens to point to an operand instead of an
    opcode, the emulator will not respond.


    7.  Emulation of floating bus

    Reading from e.g. port #FE accesses the ULA bus which is used to read
    the screen memory.  While the ULA is generating the border or
    horizontal or vertical retrace signals, this will result in #FF;
    otherwise, the value returned is the ATTR or screen byte the ULA is
    currently reading.  Some programs use this to check whether the ULA is
    in vertical retrace (Arkanoid), some use it to actually wait for
    specific bytes to pass, which signals that a certain part of the screen
    is being generated (Ricochet).  Only in Hi Res Color mode will the
    emulation of this effect be reasonably accurate to get Ricochet running
    correctly.  Arkanoid runs reasonably well, but due to the way it is
    implemented it produces 'ticks' in the speaker when it is not run in
    HRC mode.






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 colour from the screen at the cursor's
           current position, and store it in memory.  This colour will be
           used by the next command:
        Z: Put the colour 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 colour
        L: Take a look at the bitmap below the ATTR colour codes
        T: Return to the main menu.  You can also return by pressing
           EDIT, or ESC in the emulator.
        B: Change border colour
        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.  You ought to be able to disassemble this piece by heart.

    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 DISCiPLE and Plus D Interfaces - The system variables


    The system variables reside in the RAM of the interface, and cannot be
    read of changed by using the normal POKE statement.  For access to
    these locations the designer of the Disciple and +D ROM has implemented
    the POKE @x,y command.  It changes the value at address (#0298+x) in
    the interface's RAM.  Here are the system variables, with their
    meaning.  Default values are between brackets.

    Note that when y (the second argument) of a POKE @ command is larger
    than 255, it is interpreted as a word, and it is poked at locations x
    and x+1.  Handy for locations 14 and 16.

    POKE @0: (7)   Border change mask when reading/writing disks
    POKE @1: (80+128=208)   Number of tracks of drive 1. 128 means DS
    POKE @2: (208) Same for drive 2
    POKE @3: (6)   Step rate in ms (may not be lower than 6)
    POKE @4: (1)   Network (0=off, 1=master, 2..10=assistant, 11..63=slave)
    POKE @5: (80)  Printer line width (# of chars printed before CR is
                   inserted)
    POKE @6: (0)   Control code conversion (0=on, 1=off)
    POKE @7: (12)  Printer line feed when printing graphics (1/72th inches)
    POKE @8: (1)   Number of Line Feeds (10) inserted after each CR (13)
    POKE @9: (0)   Left margin: number of spaces printed after each CR
    POKE @10:(0)   Convert some characters into graphics (0=off, 1=on)
    POKE @11:(0)   Enable MGT Centronics printer interface (0=yes,
                   1=route to standard "p" channel, i.e. ZX Printer)
    POKE @12:(word 0)     Unused
    POKE @14:(word 0)     Basic extension call vector
    POKE @16:(word #3b0)  Basic extension call vector (I think)

    The default value of variable 10 was changed to 0.  Previous rom images
    supplied with Z80 had @11 set to 1 (printer disabled) and @8 to 0
    (don't add line feeds), but these were not Disciple/+D defaults, so
    they were changed back in version 3.05.



4.8  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.