home *** CD-ROM | disk | FTP | other *** search
/ Brotikasten / BROTCD01.iso / spectrum / z80.txt < prev    next >
Text File  |  1994-12-28  |  212KB  |  4,272 lines

  1. Sinclair ZX Spectrum Emulator 'Z80' v3.03  -  29/12/94  -  by G.A. Lunter
  2.  
  3.  
  4.  
  5. Contents:
  6.  
  7.     1.    INTRODUCTION, REGISTRATION, GENERAL INFORMATION
  8.     1.1   Some general remarks
  9.     1.2   Registering - sounds interesting!
  10.     1.3   Other emulators
  11.     1.4   Acknowledgements
  12.     1.5   Disclaimers
  13.     1.6   Copyright notices
  14.  
  15.     2.    THE EMULATOR
  16.     2.1   Starting the emulator
  17.     2.2   Using the emulator
  18.     2.3   Keyboard emulation
  19.     2.4   Screen emulation
  20.     2.5   Sound emulation
  21.     2.6   Loading programs from tape
  22.     2.7   Using .TAP files
  23.     2.8   Using .VOC files
  24.     2.9   Multi-load games
  25.     2.10  Using the Microdrive
  26.     2.11  Using the Disciple and Plus D interfaces
  27.     2.12  Using the Multiface
  28.     2.13  Using the RS232 channel
  29.     2.14  On joysticks and mice
  30.     2.15  The utility ConvZ80
  31.     2.16  Converting file formats - the utility CONVERT
  32.     2.17  The utilities Z802TAP, TAP2TAPE and TAP2VOC
  33.     2.18  The utility OUT2VOC - and how to make .OUT files
  34.     2.19  Quick overview of command line switches, and features
  35.     2.20  Miscellaneous remarks
  36.  
  37.     3.    THE SAMRAM
  38.     3.1   Basic extensions
  39.     3.2   NMI software
  40.     3.3   The built-in monitor
  41.  
  42.     4.    THE SPECTRUM
  43.     4.1   The Spectrum
  44.     4.2   The Interface I
  45.     4.3   The DISCiPLE and Plus D Interfaces - Introduction
  46.     4.4   The DISCiPLE and Plus D Interfaces - Basic commands
  47.     4.5   The DISCiPLE and Plus D Interfaces - More advanced commands
  48.     4.6   The DISCiPLE and Plus D Interfaces - The snapshot button
  49.     4.7   The Spectrum 128
  50.  
  51.     5.    TECHNICAL INFORMATION
  52.     5.1   The Spectrum
  53.     5.2   The Interface I
  54.     5.3   The SamRam
  55.     5.4   The Z80 microprocessor
  56.     5.5   File formats
  57.  
  58.  
  59.  
  60.  
  61.  
  62. 1. INTRODUCTION, REGISTRATION, GENERAL INFORMATION
  63.  
  64.  
  65.  
  66.  
  67. 1.1  Some general remarks
  68.  
  69.  
  70.     This is the documentation for 'Z80', a Sinclair ZX Spectrum 48/128
  71.     emulator.  The program turns your PC into a Spectrum.  Its features in
  72.     a (largish) nut-shell:
  73.  
  74.       - Emulates ZX Spectrum 48K model 2 or 3, and Spectrum 128K.
  75.       - Best compatibility of current Spectrum emulators.
  76.       - Emulates Interface I and Microdrive (cartridge in cartridge file),
  77.         Disciple and Plus D disk interfaces, Multiface 128.
  78.       - Full tape support: loads both normal and turbo-saved programs using
  79.         either tape interface on LPT port, SoundBlaster AD converter or
  80.         .VOC sound sample files; can also use .TAP binary tape image files
  81.         by trapping ROM save/load routines.  Saving back to tape is also
  82.         possible, either directly to tape or to a .VOC sound sample file.
  83.       - Full emulation of Spectrum screen, including all colour effects.
  84.         Border, and timing-sensitive border and attribute effects are also
  85.         emulated.
  86.       - Emulation of ZX Printer, for Epson and HP Laserjet compatible
  87.         printers.
  88.       - Emulation of beeper through PC beeper, and of 128K sound through
  89.         either PC beeper or AdLib (SoundBlaster) compatible cards
  90.       - A program is included which makes .VOC or raw sound sample files
  91.         of sounds produces by the Spectrum, either by the beeper, the
  92.         soundchip of the Spectrum 128, or the MIC port.
  93.       - OUTs to any port can be logged, and stored in a log file with
  94.         timing information.
  95.       - Supports digital and analogue joysticks, and mouse, controlling
  96.         Cursor, Sinclair, Kempston or user-defined joystick.
  97.       - Emulates Spectrum AMS Mouse interface (used by e.g. Art Studio)
  98.       - Runs on any PC (but needs 640K base memory if no EMS is present).
  99.       - Emulator runs just above 100% of actual Spectrum speed on 20 MHz
  100.         286 and 25 MHz 386SX; can be slowed down on faster machines.
  101.       - Z80 emulation includes emulation of R register, all unofficial
  102.         instruction codes, and unofficial flags; interrupts once every
  103.         1/50th emulated second; I have tried to make each instruction
  104.         execute in a time proportional to the time taken on a real Z80.
  105.       - Registered package includes all source files.
  106.       - Interface I and Spectrum 128's "p" channel input/output can be
  107.         re-routed to LPT or COM port, or to a file.
  108.       - Includes several utilities; to convert from and to other snapshot
  109.         and tape file formats, to convert snapshots into tape files, tape
  110.         files into sound sample files, to display contents of snapshot
  111.         files, to convert screen snapshots to .PCX and .GIF files, to read
  112.         .VOC sound sample files from the LPT tape interface or
  113.         SoundBlaster.
  114.       - Multi-level support as in XZX 0.5.2
  115.       - Emulator can set a breakpoint, invisible to the running program.
  116.       - Emulator can load and save blocks of Spectrum memory to disk
  117.         directly.
  118.       - Emulator can run under Windows.
  119.       - Supports VGA, EGA, CGA, Hercules and Plantronics video adapters
  120.         including mono VGA.
  121.  
  122.     There is quite a lot to explain in this documentation.  First of all
  123.     the emulator itself requires some of your PC's resources.  It is not
  124.     really a demanding program, but there are some things that need
  125.     attention.  These technicalities are dealt with in section 2.1.
  126.  
  127.     Some general things about the emulator are explained in section 2.2. If
  128.     you read 2.1 and 2.2, you will know most of the basic stuff.  The
  129.     details can be found in subsequent sections.
  130.  
  131.     The Spectrum has a number of ways to communicate with the outside
  132.     world, like the obvious keyboard and the screen, but also the
  133.     microdrives, the DISCiPLE/Plus D disk interfaces, the tape interface,
  134.     the beeper, the sound chip of the Spectrum 128, the Kempston joystick,
  135.     the AMS Mouse, the ZX Printer interface, and the RS232 channel of the
  136.     Interface I and Spectrum 128 can be used to communicate with PC
  137.     channels in some way. For instance, the keyboard is connected to the PC
  138.     keyboard (sounds obvious) and the tape I/O can be routed to a file, as
  139.     well as to a physical tape recorder, or it can come from a .VOC sound
  140.     sample file.  All these things are explained in the rest of chapter 2.
  141.  
  142.     For our own Spectrums Johan Muizelaar and I built a piece of hardware
  143.     we called the SamRam (which has nothing to do with the SAM Coupe, by
  144.     the way!).  It contains a monitor program and software to make
  145.     snapshots of programs.  It's still very useful and I still use it a
  146.     lot.  An explanation of its functions is to be found in chapter 3.
  147.  
  148.     Some things peculiar to the Spectrum or its interfaces, not specific to
  149.     this program but useful to know, are collected in chapter 4.  It
  150.     contains for instance a table of Spectrum keywords and the key
  151.     combination to get them; unfortunately this information is not printed
  152.     on standard PC keyboards! More importantly, in this chapter it is
  153.     explained how to use the Microdrive and DISCiPLE interfaces, both of
  154.     which are probably unfamiliar to many former Spectrum users.
  155.  
  156.     There are some interesting technical facts about the Spectrum that I
  157.     discovered while debugging the emulator.  As much as I could think of
  158.     is contained in the final chapter.  You don't need to read this chapter
  159.     to use the emulator.  A specification of the file formats used by the
  160.     emulator is also included.
  161.  
  162.     For Spectrum software, utilities, other emulators for PC's as well as
  163.     other computers, and other Spectrum related software, you can call the
  164.     Spectrum Emulator support BBS in Groningen:
  165.  
  166.         Tatort BBS Groningen
  167.         050-264840
  168.         (+31-50-264840)
  169.         300-14400 baud
  170.  
  171.     At the time of writing the BBS is open 24 hours a day, but this is
  172.     subject to change.  Please try calling between 22:00 and 9:00 local
  173.     time first.
  174.  
  175.     A number of interesting Internet addresses are
  176.  
  177.         FTP      ftp.nvg.unit.no         /pub/spectrum
  178.         FTP      wuarchive.wustl.edu     /systems/sinclair
  179.         FTP      ftp.ijs.si              /pub/zx
  180.         GOPHER   gopher.nvg.unit.no
  181.         WWW      www.nvg.unit.no         http://www.nvg.unit.no/
  182.                                                /Sinclair/Spectrum
  183.  
  184.     (The Internet addresses above were taken from the FAQ list maintained
  185.     by Marat Fayzullin).
  186.  
  187.     Usenet, often offered with Internet access, has Newsgroups like
  188.     comp.sys.sinclair, comp.emulators.announce and comp.emulators.misc
  189.     which can be sources of useful information; for instance, you can get
  190.     the FAQ list mentioned above there.
  191.  
  192.     If you want to get in touch with me, my email address is
  193.     gerton@rcondw.rug.nl.
  194.  
  195.  
  196.  
  197.  
  198.  
  199. 1.2  Registering - sounds interesting!
  200.  
  201.  
  202.     'Z80' is a shareware program.  The program is not completely
  203.     functional, and the parts which are left out are included when you
  204.     register.  You are encouraged to give this demo version to friends, but
  205.     DO NOT change the original archive in any way, please.  The shareware
  206.     version of the emulator consists of the Z80-303.ZIP archive file, which
  207.     should contain the following 11 files:
  208.     
  209.         Z80.EXE      - The emulator
  210.         Z80.INI      - Default initialisation file
  211.         Z80.PIF      - Program Info File to run 'Z80' under Windows 3.1
  212.         Z80.ICO      - Windows icon
  213.         Z80.DOC      - This documentation file
  214.         Z80FAQ.DOC   - Frequently asked questions - and answers!
  215.         REGISTER.DOC - Information on how to register for 'Z80'
  216.         NEW.DOC      - The What's New file
  217.         ROMS.BIN     - Various ROM images
  218.         LAYOUT.SCR   - Keyboard lay-out help screen
  219.         DIAGRAM.Z80  - Circuit diagram for tape interface, and calibration
  220.  
  221.     The shareware version of the emulator differs from the registered
  222.     version in the following respects: it cannot be slowed down, it cannot
  223.     load from or save to tape, and it does not emulate the DISCiPLE and the
  224.     Plus D interfaces.  Everything else works as in the registered version.
  225.  
  226.     If you register, you get the fully working version, and the following
  227.     utilities:
  228.  
  229.  
  230.         CONVERT  - a general conversion program: can list out BASIC and
  231.                    tranlate it back, produce .GIF or .PCX files from
  232.                    screen dumps, translate Spectrum ASCII (CR) to PC ASCII
  233.                    (CR/LF), and some other things.
  234.         CONVZ80  - Translates various snapshot and tape formats of other
  235.                    Spectrum emulators into each other.  Can handle the
  236.                    familiar .SNA format use by several emulators (JPP,
  237.                    XZX,...), and also Pedro Gimeno's (VGASPEC and SPECTRUM)
  238.                    .SP format and Kevin J. Phairs' (SPECEM) .PRG format.
  239.                    It can also handle tape files of SPECEM and L. Rindt and
  240.                    E. Brukner's emulator ZX.
  241.         DISCIPLE - Reads DISCiPLE and Plus D diskettes, both 3.5'' and
  242.                    5.25''.  It translates the 48K and 128K snapshot files
  243.                    to .Z80 snapshots, and ordinary files and screen
  244.                    snapshots to .TAP tape files. (Not necessary for the
  245.                    fully registered version, but handy for the cheaper
  246.                    one.)
  247.         Z802TAP  - Converts a .Z80 snapshot, 48K or 128K, to a .TAP file
  248.                    which can be loaded into the emulator and saved to tape
  249.                    by the next utility:
  250.         TAP2TAPE - Saves the contents of a .TAP file back to tape, to load
  251.                    it into an ordinary Spectrum.
  252.         TAP2VOC  - Converts a .TAP file to a .VOC sound sample file, to
  253.                    write to tape, or to load into the emulator.
  254.         READVOC  - Reads in a long, 'digital' .VOC sound sample, to be
  255.                    used as input to the emulator, from the LPT tape
  256.                    interface or a SoundBlaster.
  257.         OUT2VOC  - Converts .OUT log files into .VOC or raw sound sample
  258.                    files, so that you can easily extract music samples from
  259.                    Spectrum/Spectrum 128 games, or SAVE directly to a .VOC
  260.                    or raw sample file.
  261.         Z80DUMP  - Shows the header and the contents of a .Z80 file.
  262.  
  263.  
  264.     You will also receive the source files of the emulator, the above
  265.     utilities and the SamRam, and you will be kept informed about future
  266.     updates.
  267.  
  268.     You can also choose to register for the emulator without DISCiPLE and
  269.     Plus D emulation, if you are not interested in those parts.  The
  270.     registration fee is a bit lower then, and you will receive everything
  271.     stated above (including the DISCIPLE program), the only difference
  272.     being that you get a version of the emulator that will not emulate the
  273.     M.G.T. interfaces.
  274.  
  275.     There are several registration sites, the main one being B.G. Services
  276.     in the U.K.  You can also register with me in the Netherlands, or with
  277.     Jimaz in the Czech Republic, with Sinclair Freakeren in Denmark, David
  278.     Pomeroy in New Zealand and with FriendWare in Spain, whichever is most
  279.     convenient.  Details follow:
  280.  
  281.  
  282.  
  283.     B G Services, U.K.
  284.     ------------------
  285.  
  286.     The registration fee is BP 20 or BP 15 for the version with or without
  287.     DISCiPLE/Plus D emulation respectively.  Payment can be by sterling
  288.     (Euro)cheques or postal order made payable to B G Services.  You can
  289.     also transfer directly to the Giro account 324.82.16 (B G Services).
  290.     The address is:
  291.  
  292.                 B G Services
  293.                 64 Roebuck Road
  294.                 Chessington
  295.                 Surrey KT9 1JX
  296.  
  297.     Telephone enquiries on (0181) 287 4180, Fax (0181) 391 0744, or from
  298.     abroad: +44 181 287 4180 and +44 181 391 0744 respectively.
  299.  
  300.     B G Services can also supply ready built tape interfaces for BP 11.50.
  301.     These are proffessional quality items built into 25W 'D' connectors.
  302.  
  303.  
  304.  
  305.     Myself, The Netherlands
  306.     -----------------------
  307.  
  308.     Registration fee is BP 20/BP 15, US$ 30/US$ 23,  HFL 50/HFL 35,  or
  309.     equivalent amounts in your local (convertible) currency, for the
  310.     version with or without DISCiPLE/Plus D emulation respectively.
  311.  
  312.     From the Netherlands, you can most conveniently transfer the fee to my
  313.     Giro account 59.45.263, G.A. Lunter, Groningen.
  314.  
  315.     From every other country, I prefer bank notes or international postal
  316.     money orders.
  317.  
  318.     From Europe, you can sometimes use a Eurocheque.  Please fill it in
  319.     completely, including the number at the back, and please write it out
  320.     in DUTCH currency.  Eurocheques written out in foreign currency cost
  321.     HFL 20 to cash.
  322.  
  323.     I discourage using any other cheques.  If you have no other option
  324.     available, please add the equivalent of HFL 20 for drawing the cheque,
  325.     and specify whether you want the version with or without DISCiPLE/+D
  326.     emulation.
  327.  
  328.     The address is:
  329.  
  330.                 Gerton Lunter
  331.                 P.O. Box 2535
  332.                 NL-9704 CM  Groningen
  333.                 The Netherlands
  334.  
  335.     You'll get the files on a 3.5'' HD disk by default, but you can also
  336.     get it on DD or 5.25 inch disks if you want.
  337.  
  338.  
  339.  
  340.     Jimaz, Czech Republic
  341.     ---------------------
  342.  
  343.     For registrations in the Czech Republic, you can contact Jimaz.
  344.  
  345.                 JIMAZ s.r.o.
  346.                 Hermanova 37
  347.                 170 00 Praha 7
  348.                 phone: +42 2 379 498
  349.                 fax:   +42 2 378 103
  350.                 Email: vondrack@cslab.felk.cvut.cs
  351.  
  352.     Registration fee is 500 and 650 Czech crowns.
  353.  
  354.  
  355.  
  356.     Sinclair Freakren, Denmark
  357.     --------------------------
  358.  
  359.     For registrations in Denmark, you can register with
  360.  
  361.                 Sinclair Freakren
  362.                 Leif Mortensen
  363.                 Bryggervangen 29
  364.                 DK-7120 Vejle /Ost
  365.                 Denmark
  366.  
  367.     Registration fee is (150) 200 DKr for the (un)discipled version.
  368.  
  369.  
  370.  
  371.     David Pomeroy, New Zealand and Australia
  372.     ----------------------------------------
  373.  
  374.     For registrations in New Zealand and Australia, contact
  375.  
  376.                 David Pomeroy
  377.                 P O Box 2939
  378.                 Shortland Street
  379.                 Auckland                        
  380.                 New Zealand
  381.                 Phone: (09) 627-9618
  382.                 Email: davidpom@iconz.co.nz
  383.  
  384.  
  385.     The registration fee is 40/50 NZ$, or 30/40 AUS$.
  386.  
  387.  
  388.  
  389.     Friendware, Spain
  390.     -----------------
  391.  
  392.     In Spain, you can register with Friendware.  The address is
  393.  
  394.                 Friendware
  395.                 C/Miguel Angel, 6 2nd 5
  396.                 28010 Madrid
  397.                 SPAIN
  398.                 Phone: (91) 308 3446
  399.                 Fax:   (91) 308 5297
  400.                 CompuServe: 100413, 1667
  401.                 Email:  100413.1667@CompuServe.COM
  402.  
  403.     Registration fee is 3500 and 4700 Pts, respectively.
  404.  
  405.  
  406.  
  407.  
  408. 1.3  Other emulators
  409.  
  410.  
  411.     There are several other Spectrum emulators, both for the PC and other
  412.     computers.  The list below ia mostly from Carlo Delhez (the QL
  413.     emulators) and partly copied from Arnt Gulbrandsen's documentation of
  414.     his JPP.  I don't think the list is complete, so if you know more
  415.     Spectrum emulators, for any computer, please let me know.
  416.  
  417.  
  418.     For PC's:
  419.  
  420.     o WARAJEVO, by Zeljco Juric and Samir Ribic.  Written, in Sarajevo, in
  421.       bad conditions during the Bosnian war.  A very thorough program;
  422.       clean sounds, automatic R-register and 'LDIR'-emulation when needed,
  423.       fast operation when not, traps on some RST's to speed up BASIC, good
  424.       emulation of unofficial opcodes, well-organised tape file system,
  425.       machine code monitor, ZX Printer emulation, sneaky software detecting
  426.       some speed-loaders by their code and feeding regular tape files to
  427.       them (!), partial 128K emulation.
  428.     o JPP, by Arnt Gulbrandsen (Norway).  Faster than mine (but according
  429.       to an OUTLET review slower on some boards), by using a very smart
  430.       decoding technique, but requires a 80386 or '486 processor.  Is less
  431.       compatible than Z80. Uses the .SNA snapshot format.  Needs VGA. Not
  432.       many extra features. o VGASPEC, by Alberto Olloqui (Spain).  Needs
  433.       VGA and 80286.  Quite slow, and crashes on quite a lot of programs.
  434.       Uses the .SP snapshot format.  Allows ROM pokes.  This program is an
  435.       illegal pre-release of SPECTRUM, by Pedro Gimeno.
  436.     o SPECTRUM, by Pedro Gimeno (Spain).  Uses another .SP snapshot format.
  437.       Has a tape interface.  Also quite slow. Allows changing the rom.
  438.     o SP, by J. Swiatek and K. Makowski (Poland).  Cannot load or save
  439.       snapshots, but can load programs using LOAD "" via a file called
  440.       TAPE_ZX.SPC.  Crashes many programs; even basic behaves weird
  441.       sometimes.  Has a built-in monitor, but no documentation.  No border.
  442.     o SPECEM, by Kevin J. Phair (Ireland). Also allows rom changes.
  443.       Displays the registers on screen.  Can save and load directly from
  444.       disk using LOAD/SAVE "filename" in BASIC. Loads .PRG snapshots, but
  445.       cannot save them.  Emulates a Multiface I.
  446.     o ZX, by L. Rindt and E. Brukner (Czech Republic).  Haven't tested its
  447.       compatibility thoroughly, but one of the games supplied didn't
  448.       respond well to the keyboard, while it did work on Z80 after
  449.       conversion.  Good tape file support including headerless files,
  450.       almost identical to the multiple .TAP file mode of Z80.  Somewhat
  451.       slower than Z80.  Includes program to load from tape and convert to
  452.       tape file.  No documentation at all.
  453.  
  454.  
  455.     For the Sinclair QL:
  456.  
  457.     o SPECTATOR by Carlo Delhez, The Netherlands; shareware; supports
  458.       tape-files, Microdrives, RS232, Z80 snapshots, MBF snapshots and
  459.       Disciple (SNP) snapshots; utilities to convert Disciple, Beta and
  460.       Opus disks enclosed.
  461.     o ZM-1/2/3/4, ZM-HT by Ergon Development, Italy; ZM-1 is shareware,
  462.       others are commercial.  They all support tape-files and Z80
  463.       snapshots, some support Microdrives and RS232; contain a utility to
  464.       transfer programs from tape via a Spectrum to the QL.  Seem to be
  465.       real good and fast.
  466.     o ZX by Andew Lavrov, CIS; shareware; supports tape-files, MBF
  467.       snapshots en Z80 snapshots; utility to read from Spectrum tapes (and
  468.       write them).
  469.  
  470.  
  471.     For the Amiga:
  472.  
  473.     o Spectrum, by Peter McGavin.  Very good, JPP is based to a large
  474.       extent on it.  Needs about a 25MHz machine to run at full speed.
  475.       Has tape support.
  476.     o KGB.  I haven't seen it.  A bit slower than Peter's, and the
  477.       version Peter saw wouldn't work on the Amiga 3000.
  478.     o An Italian emulator which I don't know the name of.  Excellent
  479.       compatibility, rather fast.  May be shareware.
  480.     o Several unreleased emulators.  Peter knows more about them.
  481.  
  482.  
  483.     For the Atari ST/TT:
  484.  
  485.     o One, called Spectrum.  Don't know anything about it, but the doc
  486.       file is written in quite the worst English I've seen.  [This is
  487.       Arnt speaking --- I've seen worse! GAL] Available by anonymous
  488.       ftp from terminator.cc.umich.edu.
  489.     o There's another one in the make, to be released very soon as one of
  490.       the programmers told me, written by Markus Oberhumer and other(s).
  491.  
  492.  
  493.     For the Acorn Archimedes:
  494.  
  495.     o A good emulator written by Carsten Witt (Rostocker Str. 5, 45739
  496.       Oer-Erkenschwick, Germany), written in ARM code, RISC OS Desktop
  497.       compatible, multitasking, loading and saving to disk or tape via
  498.       RS432, understands .Z80 snapshots and others, emulates microdrives.
  499.       Seems to be the best one around for the Archimedes at the moment.
  500.       (Information supplied by Mr. G. Oeing-Hanhoff)
  501.     o A company called Arxe wrote one, intended to be commercial but
  502.       never released because Amstrad wouldn't permit Arxe to enclose the
  503.       ROM.
  504.     o Someone called D. Lawrence wrote another, or maybe the same.
  505.       This one is floating around but nobody has any documentation.  I
  506.       don't know what its status is.  Runs at about 70% of Spectrum speed on
  507.       an ARM2, not quite perfect graphics emulation.
  508.  
  509.  
  510.     For the Commodore 64:
  511.  
  512.     o The Whitby Software Spectrum simulator is a rewrite of the
  513.       Spectrum Basic.  It will not run machine-code programs.  I don't
  514.       know whether it's PD, shareware, or commercial.  Quite good.
  515.       (Responds nicely to a POKE 23659,0)
  516.  
  517.  
  518.     For the Amstrad CPC
  519.  
  520.     o Spectator - I believe this appeared on a cover tape on a
  521.       now dead magazine.
  522.  
  523.     All emulators for PC, and some for the Atari, Amiga and QL are
  524.     available on the support BBS.
  525.  
  526.     There are also emulators available for the ZX81.  Carlo Delhez, who
  527.     also wrote a Spectrum emulator for the QL, wrote the ZX81 emulators
  528.     XTricator (for the QL) and XTender (for PC's).  These programs can also
  529.     be downloaded from the support BBS.
  530.  
  531.  
  532.  
  533.  
  534. 1.4  Acknowledgements
  535.  
  536.  
  537.     From the very first beginning in november 1988, when I wrote the first
  538.     lines of the emulator, Johan Muizelaar has been a very demanding and
  539.     critical user, being only satisfied when it was perfect.  Besides,
  540.     there are quite a few things I would never have started working on if
  541.     he hadn't insisted that I would!
  542.  
  543.     I have also profited much from the fine cooperation with Brian Gaff,
  544.     who, besides handling the UK registrations, also generates a continual
  545.     stream of suggestions, remarks and bug reports.  He also brought me
  546.     into contact with many people that contributed to the emulator in
  547.     several ways.
  548.  
  549.     A major part of the things new to version 3 of the emulator have been
  550.     written by Hugh McLenaghan.  He wrote all code for the Disciple/Plus D
  551.     emulation, and for the ZX Printer emulation (where I subsequently
  552.     introduced bugs...)  Also, Hugh wrote much of the documentation for the
  553.     Disciple and Plus D interfaces in this file.
  554.  
  555.     
  556.     Finally, thanks are due to
  557.  
  558.     o   Carlo Delhez for information on the '128 and several other things,
  559.     o   Andre Mostert for some more '128 info and info on EMS memory,
  560.     o   Walter Prins for many '128 programs,
  561.     o   Marco Holmer for making the program such a big hit at the HCC dagen,
  562.     o   Henk de Groot, for finding a solution to a bug in A86 v3.22,
  563.     o   Arnt Gulbrandsen for a suggestion which made the emulator faster,
  564.             and information on a group of unofficial Z80 opcodes,
  565.     o   Ruud Zandbergen for his digital joystick interface,
  566.     o   Jan Garnier for providing the chips to reanimate my real Spectrum,
  567.     o   Ettore de Simone for finding a noisy bug,
  568.     o   Rudy Biesma and Tonnie Stap for providing info on the DISCiPLE disk
  569.             formats,
  570.     o   Burkhard Taige for various bug reports on it,
  571.     o   Ian Cull for enhancing the DISCiPLE program and two bugfixes,
  572.     o   Bert Lenaerts for information on the AZERTY keyboard,
  573.     o   Chris Lemon for fixing a bug in the CALL instruction,
  574.  
  575.     and many more not mentioned!
  576.  
  577.  
  578.  
  579.  
  580. 1.5  Disclaimers
  581.  
  582.  
  583.     Of course the software is not guaranteed to work as it is supposed to
  584.     do.  It is more than probable that the program contains some as yet
  585.     unknown bugs.
  586.  
  587.     But, the program as it is now also contains some _known_ bugs!  It
  588.     looked as if it would have taken another few weeks to remove these
  589.     bugs, and if Hugh and I would have been too perfectionistic, the
  590.     program would never be released.  So here it is, complete with the
  591.     following bugs:
  592.  
  593.         - FORMATting a Disciple/+D disk on a PC does not always work.
  594.         - Saving a Snapshot to Disciple/+D disk using the built-in
  595.           Disciple/+D snapshot software only works the first time it is
  596.           used.  Subsequent use of the snapshot button overwrites the
  597.           first snapshot.
  598.  
  599.     It is recommended that you make backups of important Disciple/+D disks
  600.     before writing to them (especially snapshots).  Reading disks is safe.
  601.  
  602.  
  603.  
  604.  
  605. 1.6  Copyrights etc.
  606.  
  607.  
  608.     Amstrad holds the copyright on the 48K and 128K rom.  However, they
  609.     have allowed free use of them.
  610.  
  611.     The Disciple ROM is (c) Bruce Gordon / Format Publications.
  612.  
  613.     The Plus D ROM is copyright Datel / Format Publications.
  614.  
  615.     Multiface and Lifeguard are registered trademarks of Romantic Robot.
  616.     They are licensed from Romantic Robot for use in Z80.
  617.  
  618.     The registered version of the Spectrum emulator 'Z80', and the version
  619.     distributed with PC Format, may NOT be further distributed.  The source
  620.     codes, which are part of the registered package, may NOT be used in
  621.     other Spectrum emulators running on PC's. In principle, it is okay to
  622.     use the Z80 emulator code in an emulator for another Z80-based
  623.     computer; however, please do contact me if you want to use it.
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630. 2.  THE EMULATOR
  631.  
  632.  
  633.  
  634.  
  635. 2.1  Starting the emulator
  636.  
  637.  
  638.     The emulator will work on any PC with at least 640K memory, with a VGA,
  639.     EGA, Hercules, CGA or Plantronics video adapter.  If available, it will
  640.     also use EMS memory, an Adlib compatible soundcard, the SoundBlaster
  641.     card, a mouse, and an analogue or digital joystick.
  642.  
  643.     The emulator will first read in the switches that are given in the
  644.     Z80.INI file.  You can enter switches there just like you do on the
  645.     command line.  Lines starting with a % sign are ignored; they are used
  646.     for comments.
  647.  
  648.     After any switches, you may specify a snapshot file on the command
  649.     line. This file will then be loaded and executed directly.  The
  650.     extension .Z80 is not necessary.  The emulator will also read .SNA
  651.     files (the snapshot format of, amongst others, Arnt Gulbrandsen's JPP);
  652.     you don't have to convert them to .Z80 files (but you may want to to
  653.     save disk space).
  654.  
  655.     The emulator tries to figure out what hardware is available, and uses
  656.     things as it finds them.  Most of the time this will work without you
  657.     having to tell it anything, but if you have to, you can override the
  658.     defaults by putting switches on the command line.  Switches that you
  659.     use often can be put in the Z80.INI file.  If you give a switch a
  660.     second time, for instance if it is also in the Z80.INI file, it will
  661.     disable it again.
  662.  
  663.     If you're using a Trident VGA with version 3 BIOS, you may see the
  664.     picture compressed at the top of the screen, while the bottom half
  665.     contains vertical white lines.  This is due to a bug in the Trident VGA
  666.     Bios.  Start the emulator with the switch -xv to get a full picture.
  667.  
  668.     Some black-and-white VGA monitors only display one of the three RGB
  669.     colours (green most of the times), resulting in several Spectrum
  670.     colours becoming indistinguishable.  Use -xb to use grey tones instead
  671.     of colours.
  672.  
  673.     If you are using Hercules, try starting the emulator with -xh on the
  674.     command line.  The emulator will use a non-standard Hercules mode to
  675.     display a full-screen Spectrum picture.  You may need to calibrate your
  676.     monitor to make the image steady.
  677.  
  678.     If you're using Plantronics, try -p and -q to see which gives the best
  679.     result.
  680.  
  681.     If you haven't got EMS memory, the page swapping of the Spectrum 128
  682.     cannot be emulated exactly, and, more seriously, it is extremely slow.
  683.     Although most programs will work, they will be too slow to be of any
  684.     use.  Also, the emulator needs lots of base memory if no EMS memory is
  685.     present; if you don't have enough, try specifying -xt on the command
  686.     line to make the emulator use as little memory as possible (by
  687.     shrinking several buffers).  The emulator uses 332K or 572K of base
  688.     memory (with and without EMS memory respectively), and 47K less in both
  689.     cases if -xt is specified.  If this is still not enough, try to use
  690.     -xu, which saves 83K, but then Hi Resolution Color emulation does not
  691.     work anymore.
  692.  
  693.     On 386 and 486 machines you can emulate EMS by software using EMM386
  694.     for instance.  The speed of the EMS emulator determines in part the
  695.     emulation speed of Spectrum 128K programs, so it may be wise to try a
  696.     few for the best results.  I use QEMM, which seems to be faster than
  697.     EMM386.
  698.  
  699.     The Spectrum 128 has a built-in sound chip.  If you have an Adlib
  700.     compatible soundcard installed, the Spectrum 128 sound will be played
  701.     through the Adlib card.  If you haven't, the loudest of the three sound
  702.     channels will be played through the internal PC speaker.  Sometimes the
  703.     effect is quite nice, sometimes it is horrible, but it's all I can do
  704.     on a standard PC.  If you don't want to have the Spectrum 128 sound
  705.     played through the internal speaker, use the switch -xi.  If you don't
  706.     want the Adlib card to be used (for instance to hear the sound through
  707.     the internal speaker) use -xa.
  708.  
  709.     If you're using the Pro-Audio Spectrum 16 sound card, do not install
  710.     the resident FM.EXE program; it causes problems with the emulator. Do
  711.     make sure that MVSOUND.SYS is installed in your CONFIG.SYS file, to
  712.     make the Pro-Audio Spectrum 16 Adlib compatible.
  713.  
  714.     The noise channels of the Spectrum 128 sound chip can work on different
  715.     frequencies, whereas the FM chips of the Adlib card cannot.  However,
  716.     if your Soundblaster is equipped with CMS chips, the noise frequency
  717.     can be programmed.  Specify -xc to use the CMS chips.  (These chips are
  718.     not available on Soundblaster Pro cards, and neither on most
  719.     Soundblaster clones).
  720.  
  721.     If you're living in Belgium or France, you are probably using an AZERTY
  722.     keyboard.  Specifying -xz on the command line will make all letter keys
  723.     and many punctuation keys work in the right way.
  724.  
  725.     If the emulator erroneously detects an analogue or digital joystick,
  726.     use the switch -kk.
  727.  
  728.     The emulator can now also be run under Windows 3.1!  However, you
  729.     cannot use the tape interface, Real mode doesn't work anymore, and the
  730.     keyboard is not emulated as well as usual, because I have to scan it
  731.     using BIOS calls.  Be sure not to set the keyboard repeat rate too low;
  732.     an initial delay of 250 ms followed by 10 keys a second will do, but
  733.     don't make it slower.  Some key combinations may not work, such as ALT
  734.     4 for $.  So if you want to use the emulator seriously then you
  735.     shouldn't run it under Windows, but it's nice to see three Spectrums
  736.     run simultaneously...  If you let the emulator run full-screen you may
  737.     use EGA or VGA, if you want to run it windowed you'll probably have to
  738.     use CGA, because the virtual video display driver of Windows cannot
  739.     handle the VGA mode I use (although it's only a standard text mode!).
  740.     You'll probably want other default settings of some parameters (such as
  741.     the video mode) if you run the emulator under Windows; the emulator
  742.     will always use the .INI file in the directory of the Z80.EXE file so
  743.     the other switches must be put on the command line or in a .PIF file.
  744.     An example .PIF file (which runs the emulator in windowed CGA mode) and
  745.     a .ICO icon file are supplied
  746.  
  747.     Since the execution speed of a program running under Windows heavily
  748.     depends on other processes, the emulator doesn't try to measure how
  749.     fast it is running under Windows.  It says it runs at 100%, and you can
  750.     slow it down in the usual way, but the percentage is now relative to
  751.     the maximum speed, and has nothing to do with the actual execution
  752.     speed.
  753.  
  754.     The emulator will automatically detect whether Windows is running, and
  755.     act appropriately.  To run the emulator in Windows compatibility mode
  756.     in a normal DOS environment, use -xw.
  757.  
  758.     When running the emulator under Desqview, use -e for EGA mode display.
  759.  
  760.     At present running under OS/2 is not a good idea as it will crash if
  761.     the speed is altered!
  762.  
  763.     These are the most important switches that you have to specify when you
  764.     start the emulator.  Most of the other switches are used to select
  765.     default values for various things which can also be changed when the
  766.     emulator is running.  Some useful things to select are default
  767.     directories for .Z80, .TAP and .MDR files; these will be explained
  768.     below.
  769.  
  770.  
  771.  
  772.  
  773. 2.2  Using the emulator
  774.  
  775.  
  776.     In this section, the basic functions of the emulator, residing under
  777.     the function keys F1-F10, are explained.
  778.  
  779.     When the emulator starts, you'll see the usual Spectrum copyright
  780.     message appear on screen.  Pressing F1 will pop up a small help screen
  781.     that explains the function of the function keys and various other
  782.     special keys.
  783.  
  784.     By pressing F10, you enter the main menu of the emulator.  Most of the
  785.     menu options can be chosen directly by pressing another function key; a
  786.     small help screen pops up if you press F1.  If you're somewhere deep in
  787.     the menu structure from the main menu, pressing ESC will get you one
  788.     level higher most of the time.  Pressing F10 will get you back to the
  789.     main menu.
  790.  
  791.     The 'Select Hardware' menu option sits under function key F9.  There
  792.     are seven major configuration to choose from:
  793.  
  794.         Spectrum 48K
  795.         Spectrum 48K + Interface I
  796.         Spectrum 48K + SamRam + Interface I
  797.         Spectrum 48K + M.G.T. Interface  (i.e. DISCiPLE or Plus D)
  798.         Spectrum 128K
  799.         Spectrum 128K + Interface I
  800.         Spectrum 128K + M.G.T.
  801.  
  802.     This menu also allows to choose the M.G.T. type, +D, Disciple with a
  803.     pre-loaded operating system supporting graphics output using the Epson
  804.     format, and one supporting HP-PCL format graphics output.
  805.  
  806.     In all configurations except the one with SamRam, the Multiface 128 can
  807.     be emulated too.  The Multiface 128 software is aware of, and can read
  808.     and write to, the Microdrive of the Interface I and the Disciple and +D
  809.     disk drive.
  810.  
  811.     After a change has been made, pressing ENTER switches to that mode and
  812.     resets the Spectrum.  If you don't want the Spectrum to reset, pressing
  813.     CTRL-ENTER will switch to the new mode while preserving as much of the
  814.     runninge program as possible.  Switching from 128K mode to 48K mode
  815.     will almost always crash the program, except if you enter the SPECTRUM
  816.     command before switching.
  817.  
  818.     To use SamRam's monitor on a 128 program, switch the hardware from the
  819.     main menu, and generate an NMI (Extra functions - N) before returning
  820.     to the emulator.  This will often work, but you can't return to the
  821.     program without crashing it.
  822.  
  823.     On a real Spectrum 128, the menu bar of the startup screen is moved
  824.     using the cursor keys on the '128 keyboard.  These keys simultaneously
  825.     press a normal cursor key (5,6,7 or 8) and shift.  So you can shift the
  826.     menu bar with shift-6 and shift-7.  It is possible to use the PC cursor
  827.     keys for this; you have to select Cursor joystick emulation (which is
  828.     selected by default) and press Num-Lock once to have the PC-cursor keys
  829.     press the Spectrum Shift key too.  You could also specify -xs on the
  830.     command line (or put it in the Z80.INI file) to make the PC cursor keys
  831.     by default press shift for you in '128 mode; see also the Miscellaneous
  832.     remarks section.
  833.  
  834.     The Save and Load Program options (F2 and F3) will save the whole state
  835.     of the Spectrum and some of the emulators' settings to a .Z80 snapshot
  836.     file.  It will pack the data somewhat, so that the length of the file
  837.     varies.  The amount of memory saved depends on the current hardware
  838.     mode; 48K for normal Spectrum, 80K for SamRam, and 128K for Spectrum
  839.     128.  (Note that the RAM contents of the M.G.T. interface or the
  840.     Multiface 128 are not saved.)  The settings that are saved are those
  841.     that are program dependent, for instance which joystick emulation is
  842.     used, and more technical settings like those of the R register, LDIR
  843.     and Issue 2 emulation, double interrupt frequency and video
  844.     synchronisation.  These are explained below.
  845.  
  846.     Loading a .Z80 file will cause several settings to be changed.
  847.     Resetting the Spectrum will not reset these settings to their default
  848.     values! Especially the joystick emulation setting change can be
  849.     confusing, so keep track of that.
  850.  
  851.     All settings can be checked and changed in the Change Settings menu,
  852.     which pops up if you press F4. You can do many things here. explain
  853.     them all now.  The I and O options can be used to redirect the RS232
  854.     output; see section 2.13 for information on this.  R - R register
  855.     emulation, and L - LDIR emulation are usually only necessary when
  856.     loading programs;  for remarks on these options see section 2.6, and
  857.     section 5.1 for more technical details.  Other settings and switches
  858.     are:
  859.  
  860.     H - Hi color resolution emulation.  To eliminate flickering of moving
  861.     characters, and to see some color effects otherwise not visible.  See
  862.     section 2.4 for more information.
  863.  
  864.     2 - Issue 2 emulation will turn the emulated Spectrum in an Issue 2
  865.     Spectrum.  (This option also works, but is out of place, in Spectrum
  866.     128 mode).  Some very old programs (Blue Ribband, Spinads) will not
  867.     respond to the keyboard properly on Issue 3 Spectrums, and for these
  868.     programs this option was added.  Seldom needed.
  869.  
  870.     S - sound enables you to turn off all sound, useful for late-night
  871.     playing.
  872.  
  873.     D - double interrupt frequency is useful for slow machines, as some
  874.     programs will run faster when this option is on.  If you're typing in a
  875.     BASIC program on a slow machine, always turn this on, since the
  876.     keyboard, which is polled by an interrupt routine, will respond much
  877.     better.  On the other hand, some programs will crash with this option
  878.     active.
  879.  
  880.     V - video synchronisation is used to remove the flickering of moving
  881.     characters in some programs.  You can choose between Normal, High and
  882.     Low.  Normal works well for almost all programs; Ghosts and Goblins and
  883.     Zynaps look much better when this is turned to High.  If you see
  884.     characters not moving smoothly or flicker, or a background not moving
  885.     as a whole, experiment a little bit with this setting, and re-save the
  886.     snapshot when you've found the best setting.  On fast computers, try to
  887.     use Hi Color Resolution emulation instead. (For a more detailed
  888.     discussion of this option see section 2.4 and section 5.1)
  889.  
  890.     J - joystick emulation specifies which Spectrum joystick the PC cursor
  891.     keys (and mouse, and analogue or digital joystick, if available)
  892.     control. You can choose from Cursor (default), Kempston, Interface 2
  893.     and user-defined.  As already said above, if Cursor joystick is chosen,
  894.     the Num-Lock key controls whether Shift is pressed too with a joystick
  895.     movement. (Since the shift and number keys are pressed exactly
  896.     simultaneously, it is possible that the Spectrum has already read the
  897.     Shift key, but not yet the others, when you press both keys down.
  898.     Sometimes you will therefore get the number 5,6,7 or 8 instead of a
  899.     cursor movement. If you have used a +3 or +2A Spectrum, you will be
  900.     familiar with this!)
  901.  
  902.     Finally, C - Change speed lets you control the speed of the emulator.
  903.     As a side effect, slowing down the emulator makes the timing of the
  904.     various opcodes correspond more exactly to the actual timing on a real
  905.     processor. (Remember this is not possible on slow PCs!)
  906.  
  907.     That concludes the discussion of the F4-'change settings' menu.  Let's
  908.     continue with the other function keys.
  909.  
  910.     F5 generates an NMI. This is used to activate the Samram, Multiface
  911.     128, or start the Disciple/+D Snapshot facility. If none of these are
  912.     active it may reset the Spectrum or do nothing.
  913.  
  914.     ALT-F5 or CTRL-F5 resets the Spectrum.
  915.  
  916.     F6 turns on Real Mode.  Try this when the emulator is playing a tune
  917.     and sounds a little harsh.  This mode is needed when you want to load
  918.     turbo-saved games from tape; see below for more information.
  919.  
  920.     F7 and F8 activate the tape and Microdrive/M.G.T. menus.  Again, see
  921.     below for more information.
  922.  
  923.     Resetting the Spectrum, or generating an NMI can be done from the main
  924.     menu too, in the X - Extra Functions menu.  This is useful if you want
  925.     to activate the NMI software of the SamRam for instance just after
  926.     loading a snapshot file, or just after you changed the hardware mode.
  927.  
  928.     In this menu it is also possible to save or load a memory block or
  929.     screen snapshot; to set a breakpoint or to temporarily shell to DOS.
  930.     Furthermore, here you can find another sub-menu for the OUT logging
  931.     feature.  If port FE is logged, such a log file can be translated
  932.     into a .VOC sound sample file.
  933.  
  934.     When you're typing BASIC-programs in 48K mode, you'll probably have to
  935.     look up some Spectrum keywords.  Further down in this documentation
  936.     there is an alphabetical list of all keywords and their
  937.     key-combination. For 'on-line' help, press ALT-F1 to see the Spectrum
  938.     keyboard layout.
  939.  
  940.  
  941.  
  942.  
  943. 2.3  Keyboard emulation
  944.  
  945.  
  946.     The keyboard.  Letter keys are mapped to the Spectrum's letter keys.
  947.     The ALT and CTRL keys can both be used for Symbol Shift.  Then, there
  948.     are a lot of keys on the PC keyboard which don't exist on the Spectrum
  949.     keyboard.  Many of them are used, to make things easier:
  950.  
  951.     The function keys have several special functions.  See the previous
  952.     section.
  953.  
  954.     CTRL-Break and CTRL-ALT-DEL quit the emulator.  Better use F10-Q-Y
  955.     though.
  956.  
  957.     The punctuation keys - = ; ' , .  / and their shifts: _ + : " < > ?
  958.     have the effect of pressing Symbol Shift and the corresponding letter
  959.     key, so you can use these in the straightforward way.
  960.  
  961.     The ESC key presses Shift-1, EDIT, used as a sort of ESC key in many
  962.     Spectrum programs.  The Backspace key presses Shift-0, the Delete of
  963.     the Spectrum.  CapsLock presses Shift-2, Spectrum's capslock key.
  964.  
  965.     The PC-cursor keys and the numeric keypad keys 8,4,6 and 2 control the
  966.     Cursor, Interface 2, Kempston or user-defined joystick.  The TAB key,
  967.     and 0,5 and ./DEL on the numeric keypad control the fire button.  If
  968.     the Cursor joystick is selected, you can select whether Shift should
  969.     also be pressed with the NumLock key (but see the discussion above of
  970.     the -xs switch).
  971.  
  972.     If you're running the emulator on a slow computer, try selecting double
  973.     interrupt frequency.  Most programs poll the keyboard by interrupt, in
  974.     any case the ROM does, and doubling the frequency with which this
  975.     happens will make the emulated Spectrum react much more quickly on your
  976.     keystrokes.
  977.  
  978.     If you've got an AZERTY keyboard, the standard mappings of the keys
  979.     won't work at all properly.  Include the switch -xz in your Z80.INI
  980.     file in this case; many punctuation keys will now also work properly.
  981.     There is no support for other non-US keyboard layouts; sorry!
  982.  
  983.  
  984.  
  985.  
  986. 2.4  Screen emulation
  987.  
  988.  
  989.     There are two different ways the emulator can emulate the screen.  The
  990.     standard way, in which 50 times an emulated second the screen is
  991.     checked for changes, and they are subsequently displayed on the
  992.     monitor. This works fine, and was the only mode available in previous
  993.     versions. It works basically the same with all video modes; however,
  994.     some are much slower than others. EGA is notoriously slow, due to the
  995.     ugly way it has to be addressed. VGA is definetely the fastest. EGA and
  996.     VGA are the only video modes in which the colour of the overscan can be
  997.     controlled; in these modes, some emulation of border effects (loading
  998.     stripes, for example) can be done. You don't see these effects in the
  999.     other video modes.
  1000.  
  1001.     Changing the overscan colour results in 'snow' lines appearing on the
  1002.     screen.  It is possible to eliminate these by waiting until the video
  1003.     adapter is in horizontal retrace.  This takes some time, therefore the
  1004.     emulator doesn't do this in Real Mode. Real time loading requires
  1005.     minimum delay, so the screen does not update. You can select the update
  1006.     option, but you risk Tape Loading errors!
  1007.  
  1008.     In the standard mode, the point (relative to the 50 Hz interrupt) at
  1009.     which the screen is displayed can be controlled by setting the 'Video
  1010.     Synchronisation Mode' to normal, high or low.  If you see moving
  1011.     characters flickering excessively, try changing this setting.  For
  1012.     instance, BC's Quest for Tires won't look at all good with a wrong
  1013.     setting; many programs display subtle differences in different modes.
  1014.  
  1015.     In the Hercules, CGA and Plantronics modes not all colours can be
  1016.     displayed.  In EGA mode, all colours can be displayed, but some colours
  1017.     have the same intensity in Bright 1 as in in Bright 0.  Only in VGA
  1018.     mode the colours resemble closely the Spectrum originals.
  1019.  
  1020.     The other video emulation mode is called Hi-resolution colour emulation
  1021.     mode (HCR mode). In this mode great care is taken to display each video
  1022.     line at exactly the right time, and also the precise times the border
  1023.     colour is changed is used to build the border pattern. In this mode,
  1024.     every hi-resolution colour effect is visible; all flickering problems
  1025.     are also eliminated (provided they weren't already there on a real
  1026.     Spectrum!), so no need to adjust the Video Synchronisation Mode.
  1027.  
  1028.     The drawback of using this mode is that it is much slower, since the
  1029.     emulator has to keep track of the number of T states passed, and also
  1030.     has to grab a line from screen memory and put it in a buffer 192 times,
  1031.     50 times a second.  But on fast computers, 486's and up, the emulator
  1032.     can still easily emulate at 100%.
  1033.  
  1034.     HCR mode only works with a VGA video adapter.  Writing those routines
  1035.     also for CGA and Hercules seems silly; and I don't even want to think
  1036.     about rewriting them for EGA boards.
  1037.  
  1038.     Finally, when loading turbo-saved programs in Real mode, screen updates
  1039.     are suspended because they take too much time (even on fast computers).
  1040.     You can refresh the screen by pressing U - Update in Real mode, but you
  1041.     should do this only if you're sure that the emulated program is not
  1042.     loading a block, for pressing U during loading is a sure way to get a
  1043.     tape loading error.
  1044.  
  1045.  
  1046.  
  1047.  
  1048. 2.5  Sound emulation
  1049.  
  1050.  
  1051.     The Spectrum beeper is emulated by the PC's internal beeper.  Because
  1052.     every 1/50th of a second the screen has to be updated, and this takes a
  1053.     little time even if there are no changes, the sound is a bit harsh.  If
  1054.     you select real mode, the emulator won't update the screen and music
  1055.     will sound good.  If you select HCR mode, the sound will be even
  1056.     harsher than it does in normal mode.
  1057.  
  1058.     The sound of the Spectrum 128's sound chip is played through the Adlib
  1059.     card; if you haven't got such a card some notes are played through the
  1060.     internal speaker.  That sound will be turned off, however, as soon as
  1061.     the program makes a sound through the normal speaker of the Spectrum.
  1062.     Some Spectrum 128 programs use the sound chip and the beeper at the
  1063.     same time, and this won't work properly without an Adlib card.
  1064.  
  1065.  
  1066.  
  1067.  
  1068. 2.6  Loading programs from tape
  1069.  
  1070.  
  1071.     This emulator can load programs that are saved to tape in the usual
  1072.     way, but also turbo-saved programs can be loaded.  Furthermore, you can
  1073.     make a disk file act as an 'emulated tape', so that the normal SAVE and
  1074.     LOAD commands can be used to transfer data to and from disk easily.
  1075.  
  1076.     The emulator can load programs from .VOC sound sample files.  This is
  1077.     very useful for multi level games; the levels on the tape can be put in
  1078.     .VOC samples, and loaded when needed without having to re-install the
  1079.     tape recorder.  How to use .VOC files is described in section 2.8
  1080.     below.  The current section is about loading programs directly from
  1081.     tape.
  1082.  
  1083.     First of all, you need an interface to connect the tape recorder to the
  1084.     PC.  There are two ways of doing this.  You can use a tape interface on
  1085.     the LPT port.  A circuit diagram is in the DIAGRAM.Z80 program, or you
  1086.     can obtain a ready-made interface from B G Services, see section 1.2
  1087.     for more details.
  1088.  
  1089.     Version 3 can also use the SoundBlaster for tape input.  This is easier
  1090.     since no additional interface is needed.  The LPT tape interface
  1091.     however is more robust in loading.  When using the SoundBlaster, you
  1092.     have to be careful not to put the volume level too high, since
  1093.     otherwise the SoundBlaster will clip, which is a sure way to producing
  1094.     tape loading errors.  The LPT tape interface is not sensitive to this.
  1095.  
  1096.     If you want to save programs back to tape, you have to use the LPT
  1097.     interface; it is not possible to use the SoundBlaster for this.  (There
  1098.     is a way to save programs in standard format to tape though; put them
  1099.     in a .TAP file - see below - convert it to a .VOC file and play this
  1100.     sample to a tape.  Use a good sample player, one that doesn't halt for
  1101.     half a millisecond between blocks!)
  1102.  
  1103.     In the program DIAGRAM.Z80 a tape tester is present.  The LPT tape
  1104.     interface has to be calibrated, and this program can also be used to
  1105.     check the volume level when using the SoundBlaster as input device. The
  1106.     variable resistor of the LPT tape interface has to be adjusted so that
  1107.     the bar, which should go to 0% when the volume is down, points just
  1108.     below 50% at normal volume.  In the case of the SoundBlaster, when the
  1109.     volume is turned up, the bar first goes from 0% to 50% and over, and
  1110.     after that drops below 50% again.  The volume has to be set such that
  1111.     it is below 50% before the maximum.
  1112.  
  1113.     You have to tell the emulator which LPT port you use for tape I/O.  Use
  1114.     command line switch -b2 for example to select LPT2 for tape input (or
  1115.     put it in the Z80.INI file).  Use -xo to select the SoundBlaster for
  1116.     tape input.  It uses base address 0220 by default; if this is not
  1117.     correct, use for instance -xq 0240 to specify address 0240.  The
  1118.     emulator does not use the SoundBlaster interrupts.
  1119.  
  1120.     There are two ways to load programs: in 'real' or normal mode.  In real
  1121.     mode, the emulator doesn't update the screen or scan the keyboard, so
  1122.     that the emulated Spectrum program can run smoothly.  The emulator has
  1123.     to run at about 100%, but then you're able to load everything a normal
  1124.     Spectrum would load, including turbo-saved programs.  The only thing
  1125.     you see on screen are the loading bars in the border (on EGA or VGA
  1126.     screens).  Real mode is selected by pressing F6.  Saving programs in
  1127.     real mode is a bit useless but it works; enter the SAVE command, press
  1128.     a key to start saving and quickly press F6 when the saving starts.  It
  1129.     will continue in real mode.
  1130.  
  1131.     If your computer is just fast enough, don't slow the emulator down too
  1132.     much.  Because the IN instruction is relatively slow, the emulator has
  1133.     to run at about 110% for the best results.  If your computer is really
  1134.     fast, you can best slow it down to exactly 100%.  If your computer is
  1135.     just a bit too slow, you can try to make your tape recorder run slower
  1136.     too (usually you can do this by adjusting a little screw at the back of
  1137.     the motor), I successfully loaded several speed-saved programs at 90%.
  1138.  
  1139.     In normal mode, the standard ROM loading and saving routines are
  1140.     'trapped' (at addresses 04d8 and 056a) when they're about to start
  1141.     saving or loading.  A routine in the emulator itself then takes over,
  1142.     and loads or saves a block to tape (or a disk file, see below).
  1143.  
  1144.     When you enter LOAD "", the emulator starts loading using its internal
  1145.     loading routine.  You'll see a blue window appear.  Pressing F6 now
  1146.     will switch to Real mode, and the emulated Spectrum program will
  1147.     continue the loading process (if it is running at 100%).
  1148.  
  1149.     Every time a block is loaded or saved, a window contiaining some
  1150.     information of the block to be loaded or saved appears.  If you don't
  1151.     want this, for example because you want to enjoy the loading screen,
  1152.     specify -tx on the command line.
  1153.  
  1154.     Using these SAVE and LOAD routines has a great advantage as well as a
  1155.     disadvantage compared to using the Spectrum's own routines in real
  1156.     mode. The advantage is that the internal routines work on every
  1157.     machine, no matter how slow or fast, without having to make the
  1158.     emulator run at 100%.  The disadvantage at using them is that they
  1159.     obviously won't understand turbo-saved files.  For normal use, these
  1160.     internal routines work much easier, and real mode loading is only
  1161.     necessary for turbo-saved and well protected programs.
  1162.  
  1163.     Today, most programs are protected.  The emulation of the Z80 processor
  1164.     has to be exactly right, or those strange decoding routines that use
  1165.     all features of the processor the programmer could think of, will
  1166.     definitely crash.  It is most important to switch the R-register and
  1167.     LDIR emulation on, as virtually all protected programs use at least the
  1168.     R register.  Sometimes programs are real sensitive to the timing of the
  1169.     interrupts; if programs refuse to load, try sampling the first few
  1170.     blocks in a .VOC file (see below) and load it from there (of course
  1171.     with R register and LDIR emulation on); when loading from VOC files,
  1172.     interrupt timings are exact.
  1173.  
  1174.  
  1175.  
  1176.  
  1177. 2.7  Using .TAP files
  1178.  
  1179.  
  1180.     The emulator uses files with the extension .TAP to hold a piece of
  1181.     'tape', with several blocks on it.  Each block is usually either a
  1182.     header or a data block; a normal file thus consists of two blocks.
  1183.     There are two modes of operation when loading and saving to disk files,
  1184.     single and multiple .TAP file mode.
  1185.  
  1186.     In single .TAP file mode, each block saved is appended to the end of
  1187.     the .TAP file, like what would happen if you were actually saving to
  1188.     tape.  In the same way, when loading in single file mode, each time the
  1189.     ROM wants to load a block, it is presented the next block in the .TAP
  1190.     file.  It is handled as it would if the block was loaded from tape, so
  1191.     that if the ROM needs a header and is presented a data block, it will
  1192.     skip it.  The header will however be considered to be read.  So,
  1193.     entering LOAD "rubbish" will show all headers in the .TAP file, just as
  1194.     an actual Spectrum would show all headers on the tape if you left the
  1195.     tape running.
  1196.  
  1197.     If the last block is loaded, the file pointer is moved to the start
  1198.     again.  So a .TAP file can be considered to be an infinite tape. Single
  1199.     .TAP file mode is useful to save whole programs to disk, or for
  1200.     multi-load games that need to load in levels as you play.
  1201.  
  1202.     A sort of 'random access' file management is also useful, for instance
  1203.     when you're developing a program and need to save several pieces of
  1204.     data to disk and later load back a specific one.  This can be done in
  1205.     single .TAP file mode (by positioning the file pointer using the Browse
  1206.     function), but there's a different mode of operation that makes things
  1207.     easier: multiple .TAP file mode.  In fact, by default the emulator is
  1208.     in this mode.
  1209.  
  1210.     When the emulator is in multiple .TAP file mode, it will read all
  1211.     blocks from all .TAP files in a specified directory, one after the
  1212.     other.  When it has finished reading the last one, it will start all
  1213.     over again.
  1214.  
  1215.     When saving, the emulator will put the two blocks of a normal file, the
  1216.     header and the data block, in one .TAP file with a unique name made up
  1217.     of the printable letters of the file name and a two-digit number.  The
  1218.     name of the .TAP file is irrelevant to the emulator, but to have it
  1219.     resemble the name of the actual Spectrum file you saved is simply
  1220.     convenient.  If the Spectrum program saves a data block to tape without
  1221.     first saving a header, the .TAP file produced will contain only this
  1222.     data block, and the DOS file name will be HDRLES, with a two-digit
  1223.     number appended to make it unique.  The format of the .TAP files saved
  1224.     in multiple .TAP file mode is exactly the same as the format used in
  1225.     single .TAP file mode.
  1226.  
  1227.     You can easily string together .TAP files; for instance a number of
  1228.     .TAP files created in multiple .TAP file mode can be put into one big
  1229.     .TAP file simply by concatenating them, e.g.
  1230.  
  1231.         COPY /B FILE1.TAP + FILE2.TAP ALL.TAP.
  1232.  
  1233.     Now you know what you can do, but how to get the emulator to do it?
  1234.     That's what the final section is about: the tape menu.
  1235.  
  1236.     Press F7 to enter the tape menu.  Pressing S will select or de-select
  1237.     single file mode.  As a default, multiple .TAP file mode is selected.
  1238.     In this mode there are three other possible choices in the menu.  First
  1239.     of all, D selects a tape-file directory where the .TAP files will be
  1240.     saved into and loaded from.  A default directory can be selected by
  1241.     putting the -xs switch on the command line or in the Z80.INI file; for
  1242.     example -xs c:\spectrum\taps.
  1243.  
  1244.     The I and O options are used to select the source and destination of
  1245.     the saving and loading: the LPT port (in/out) or SoundBlaster port
  1246.     (only input) for a physical tape recorder, or 'disk' for disk files.
  1247.     Input and output are directed to disk by default if a default tape file
  1248.     directory is given by means of a switch on the command line or .INI
  1249.     file.
  1250.  
  1251.     If Single .TAP file mode is selected, different and more menu options
  1252.     appear.  With R and W, the input and output tape files can be selected.
  1253.     They may be the same.  If a specified output file already exists, you
  1254.     may choose to append to or overwrite this old file.  Saving is always
  1255.     at the end of the file; loading always starts at the beginning of the
  1256.     .TAP file.
  1257.  
  1258.     With the B option - Browse - the position of the file pointer into the
  1259.     input .TAP file can be changed.  If you, for instance, type LOAD""
  1260.     instead of LOAD "" CODE, the first header is read, and you would have
  1261.     to read all other headers before trying to load the file again.  With
  1262.     the browse option you can conveniently change the file pointer.  Of
  1263.     every header (that is, every block with flag byte 0 and length exactly
  1264.     17) the name and type, and of every data block the length is shown.
  1265.  
  1266.     The option B can also be used to delete specific blocks from a .TAP
  1267.     file.  Make sure you do not only delete a data block or a header, or
  1268.     the ROM may get confused.  (Double data blocks will be skipped, but
  1269.     double headers can generate Tape Loading errors).
  1270.  
  1271.     As in multiple .TAP file mode, I and O are used to specify the source
  1272.     and destination for saving and loading.  If you enter a .TAP file name
  1273.     with R or W, this will automatically be set correctly.  You can then
  1274.     always reset the input or output back to physical i/o again, of course.
  1275.  
  1276.     Finally, in Single .TAP file mode you can use 'tape mirroring': loading
  1277.     programs from tape (in normal mode, i.e.  not using Real mode) and at
  1278.     the same time saving a copy of each block loaded into a .TAP file. This
  1279.     .TAP file can later be used to load the program again, in case
  1280.     something goes wrong.  There are two ways of mirroring: normal
  1281.     mirroring and exact mirroring.  The last one must be used only in
  1282.     exceptional cases; it will always make a copy of a block, even if it
  1283.     had a tape error (the corresponding block in the .TAP file will also
  1284.     have a tape error).  This causes ticks in leader tones to make 0-byte
  1285.     blocks, so the .TAP file may get messy.  Do not use exact mirroring if
  1286.     you don't really have to; I think normal mirroring will always work in
  1287.     practice.
  1288.  
  1289.     If you try to leave the tape menu when for instance tape mirroring is
  1290.     selected, and no output filename is given, the emulator will warn you
  1291.     and will insist that the error be corrected.  Yes, it's stubborn!
  1292.  
  1293.     One final point about multiple .TAP file mode.  If you select a
  1294.     directory that contains no .TAP files at all, and try to load from the
  1295.     directory, the emulator will reset itself to physical tape I/O.  Select
  1296.     a different directory and try again.  Note that simply putting a .TAP
  1297.     file in the directory does not reset the emulator to multiple .TAP file
  1298.     mode, as it will not look in the directory again as soon as it uses
  1299.     physical tape I/O.
  1300.  
  1301.  
  1302.  
  1303.  
  1304. 2.8  Using .VOC files
  1305.  
  1306.  
  1307.     .VOC files contain sound samples, so they can also contain the sound of
  1308.     a computer tape.  The emulator can load programs from these sound
  1309.     sample files, by keeping track of exactly how much time elapses during
  1310.     the emulation of a program, and every time the emulated Spectrum
  1311.     program reads the EAR port, supplying it with the right sample.  Via an
  1312.     intermediate file, a .OUT log file, the emulator can also SAVE and
  1313.     produce a .VOC file with the right sounds in it.
  1314.  
  1315.     In this section .VOC file playback is discussed.  For a discussion of
  1316.     how to SAVE to a .VOC file, or how to produce a .VOC file of
  1317.     Spectrum-generated music, please read section 2.18 about the OUT2VOC
  1318.     utility.
  1319.  
  1320.     Because the emulator has to keep track of the emulated time, and also
  1321.     has to do some calculation every time the EAR port is read (which a
  1322.     program does rather often when loading), the emulation speed drops
  1323.     considerably (by a factor of two, roughly) when playing back .VOC
  1324.     sample files.  So loading programs using VOC files may take longer than
  1325.     loading them directly.  On the other hand, it is not at all necessary
  1326.     to have the emulator run at 100% now, so that even slow computers can
  1327.     load turbo-saved programs, provided that they can read samples.  And on
  1328.     fast computers, the emulator can be set at the maximum speed, to load
  1329.     programs much faster than usual.
  1330.  
  1331.     Using .VOC files is sensible for instance when you have a multi level
  1332.     game, where subsequent levels are saved in a non-standard format, so
  1333.     that they cannot be stored in .TAP files.  The higher levels can be
  1334.     stored in .VOC files, and loaded when needed, without having to
  1335.     re-install the cassette player.
  1336.  
  1337.     You can take a sample with any sampler program.  The emulator supports
  1338.     most VOC block types.  It does not support compressed blocks, though;
  1339.     use full 8 bit samples.  The problem with a lot of sampler programs is
  1340.     that they leave a small gap between subsequent blocks within the .VOC
  1341.     file.  This gap is usually inaudible, but it causes tape loading
  1342.     errors.  It is very important that the sample is taken without any
  1343.     gaps.  The READVOC program reads samples from the LPT tape interface or
  1344.     the SoundBlaster, and can take long continuous samples without gaps.
  1345.     Because the emulator converts the 8-bit sample to a simple High or Low
  1346.     value, READVOC also uses only two values for the signal height.  This
  1347.     results in highly compressible .VOC files; compression factors of about
  1348.     25 are no exception.
  1349.  
  1350.     It is also possible to convert .TAP files to .VOC files, with the
  1351.     utility TAP2VOC.  This was useful to test the .VOC playback feature,
  1352.     and also makes it possible to write .TAP files back to tape using a
  1353.     sample player.
  1354.  
  1355.     To play back a VOC file, press F7 to go to the tape menu, and press P
  1356.     to select the VOC file playback menu, and enter the name of the VOC
  1357.     file to be played. The VOC file is now in stand-by. Just for
  1358.     convenience, the emulator starts playing back the VOC file as soon as
  1359.     the ROM loading routine is hit; that is, as soon as you type LOAD ""
  1360.     and ENTER.  The emulator will now play the VOC file to the end
  1361.     (irrespective of what the emulated Spectrum program is doing with the
  1362.     sound supplied to the EAR port!).  When the end is reached, it will
  1363.     alert the user, and switch back to normal emulation mode.
  1364.  
  1365.     It is possible to pause the play-back at any time.  Do not do this
  1366.     while loading, since it will immediately result in a tape loading
  1367.     error.  It is also possible to start play-back without LOAD "", which
  1368.     is necessary for instance when the VOC file consists of a turbo-saved
  1369.     block.
  1370.  
  1371.     And finally, it is possible to wind and re-wind the VOC file, as if it
  1372.     were a tape.  The position is displayed in minutes, seconds and
  1373.     hundreds of seconds.
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381. 2.9  Multi-load games
  1382.  
  1383.  
  1384.     Some games have several levels saved on the tape, to be loaded when a
  1385.     previous level is completed.  There are several ways to handle these
  1386.     programs.
  1387.  
  1388.     First, simply playing it, and loading next levels using a real
  1389.     tape-recorder seems a good solution.
  1390.  
  1391.     If the data blocks in which the level data is saved are written to tape
  1392.     in the standard format, you can convert them to .TAP files.  It is most
  1393.     likely that the program uses the usual ROM routine to load the blocks,
  1394.     and this routine is trapped by the emulator, so that instead of loading
  1395.     from tape, the blocks can be loaded from these .TAP files.  To convert
  1396.     the blocks to .TAP file, use a standard tape-to-tape copy program and,
  1397.     in the Tape menu (F7), specify that tape output should go to some file.
  1398.     If the blocks are just code blocks with header, simply enabling the
  1399.     Tape Mirroring option and loading the blocks at 16384 (ignore the
  1400.     crashes that most probably result; just reset the emulator and
  1401.     continue) will do the trick.  If the blocks are headerless, then go to
  1402.     the SamRam, press NMI (F5), D for Disassembler, and L:4000 (with tape
  1403.     mirroring enabled) to load and mirror each block.  Here also, ignore
  1404.     possible crashes which result if the block is too long.
  1405.  
  1406.     A general method is to store the level data blocks in .VOC sample
  1407.     files.  These files are huge, lengths of several megabytes are common,
  1408.     but they can be compressed very tightly (if you used READVOC to make
  1409.     them). Then, if you need a block, simply shell to DOS, decompress it,
  1410.     and load it.
  1411.  
  1412.     Finally, if you want to hack into the program, you can also try to find
  1413.     the routine that is responsible for the loading of a level.  At the
  1414.     appropriate point, enter an ED F6 instruction, with A containing the
  1415.     level number, and HL the address at which the block is to be loaded.
  1416.     The emulator will then look for the relevant file and load it.  The
  1417.     name of this file is the name of the snapshot last loaded, where the
  1418.     level number (in decimal) is appended to the end.  If this results in
  1419.     more than 8 characters, the shapshot name is made shorter.  The
  1420.     extension of these files is always .DAT.  If the file is not found, the
  1421.     user is informed of the level number, and given the opportunity to
  1422.     specify a name.
  1423.  
  1424.     This ED F6 feature first appeared in XZX 0.5.2, and was devised by
  1425.     Russel Marks.
  1426.  
  1427.  
  1428.  
  1429.  
  1430. 2.10  Using the microdrive
  1431.  
  1432.  
  1433.     Compared to the tape, this is really simple.  Cartridges are emulated
  1434.     by files of 137923 bytes.  These files have the extension .MDR, and can
  1435.     contain up to 126K of data.  The emulator emulates 8 microdrives, the
  1436.     maximum amount the Interface I software can handle, and each of these
  1437.     cartridge files can be inserted in any of the 8 microdrives.  (Do not
  1438.     insert one file into more than one microdrive; this will cause problems
  1439.     with the buffering done by the emulator as well as the Interface I, and
  1440.     might result in data loss).
  1441.  
  1442.     Press F8 to enter the microdrive menu.  Press 1 to 8 to select a
  1443.     microdrive, and I to insert a microdrive cartridge.  You can select an
  1444.     existing one, or type a new name.  If the cartridge file isn't found,
  1445.     the emulator asks whether it should create it.  When created, you'll
  1446.     have to format it first; if you don't, you'll get a 'microdrive not
  1447.     present' error when you try to read it, just as happens with real
  1448.     unformatted cartridges.  To format a cartridge, type
  1449.  
  1450.         FORMAT "m";1;"name"
  1451.  
  1452.     After this the cartridge should have 126K of free space.
  1453.  
  1454.     The cartridge can be write protected; see the menu option in the F8
  1455.     menu.  This is a characteristic of the cartridge, and the write protect
  1456.     tab information is therefore stored in the cartridge file.
  1457.  
  1458.     As on the real Spectrum, you'll have to be careful with OUT's if a
  1459.     cartridge is inserted.  Try OUT 239,0 (on a real Spectrum, this turns
  1460.     on the microdrive motor) and wait a few seconds; most of your data will
  1461.     be lost!  You can stop the microdrive motor by typing STOP (or, more
  1462.     generally, generate an error).
  1463.  
  1464.     The microdrives are emulated at IN/OUT level.  This means that every
  1465.     utility or program that uses microdrives ought to work on the emulator.
  1466.     Most utilities use hook codes, and these will certainly work.
  1467.  
  1468.     The GAP line is emulated; this signal is activated if the interface I
  1469.     senses a piece of tape with no data on it.  If the checksum of the
  1470.     first header block of a microdrive header or data block is not correct,
  1471.     that block is considered to be a GAP.  This will only happen if some
  1472.     utility writes a bad block to microdrive deliberately, if the file is
  1473.     newly created and unformatted, or when you type OUT 239,0.
  1474.  
  1475.     To try the microdrive, load a Spectrum program, switch to Spectrum
  1476.     48K+If.1 mode if necessary, and turn on Multiface 128 emulation.  Press
  1477.     F8, I(nsert cartridge), enter some file name and create an unformatted
  1478.     cartridge, return to the Spectrum and press F5 (NMI), S(ave), enter
  1479.     some name, choose M(icrodrive), choose F(ormat) and wait a few seconds,
  1480.     then choose S(ave).  Then reset the Spectrum, and type LOAD
  1481.     *"m";1;"name" to re-load the snapshot you just made.
  1482.  
  1483.     Alternatively, switch to SamRam mode, make sure a formatted cartridge
  1484.     is present, press F5, S, M, S, name, and press ENTER twice to have the
  1485.     SamRam save a snapshot to microdrive.  This snapshot can only be loaded
  1486.     in SamRam mode.
  1487.  
  1488.  
  1489.  
  1490.  
  1491. 2.11  Using the DISCiPLE and Plus D interfaces
  1492.  
  1493.  
  1494.     For an explanation of the commands of the DISCiPLE and Plus D
  1495.     interfaces, see the relevant sections in chapter 4.
  1496.  
  1497.     The ROM of the DISCiPLE is supplied with the emulator, together with
  1498.     two version of the D.O.S. pre-loaded in RAM.  The ROM of the Plus D
  1499.     interface is not supplied, for copyright reasons.  The emulator will
  1500.     only emulate a Plus D interface if it can find a file PLUSDROM.BIN in
  1501.     the emulator's own directory.  If you have a Plus D yourself, you can
  1502.     transfer the ROM in the following way.  Load the operating system from
  1503.     a Plus D system diskette, and save the entire ROM, together with the
  1504.     operating system, to disk by entering SAVE d1"rom" CODE 0,16384.  Then,
  1505.     start the emulator and choose hardware mode Spectrum 48K + Disciple
  1506.     (not Plus D of course), then type LOAD d1"rom" CODE 32768.  Finally,
  1507.     press F10, X, S for Save Data block, set start address and length to
  1508.     8000 and 4000 (hexadecimal) respectively, and save the ROM under the
  1509.     name PLUSDROM.BIN.  If you re-start the emulator now, it will emulate
  1510.     the Plus D too.
  1511.  
  1512.     The emulation of the DISCiPLE or Plus D interfaces in turned on simply
  1513.     by choosing the right hardware mode in the F9 menu.  Changing the
  1514.     M.G.T. type will result in a Spectrum reset (unless you change with
  1515.     CTRL-ENTER), since a different ROM is switched in.
  1516.  
  1517.     By default, disks 1 and 2 refer to drives A: and B: respectively, but
  1518.     this can be changed in the F8 menu.
  1519.  
  1520.  
  1521.  
  1522.  
  1523. 2.12  Using the Multiface 128
  1524.  
  1525.  
  1526.     The following is an excerpt from the original Multiface 128
  1527.     documentation:
  1528.  
  1529.     MULTIFACE is a registered trademark af RORANTIC ROBOT.  Multiface 128
  1530.     is a true multi-purpose interface with
  1531.  
  1532.     1) fully universal and 100% automatic back-up facility for tape,
  1533.        microdrive, Discovery, Plus D or Disciple (although the Discovery is
  1534.        not emulated, so that that feature is not usable),
  1535.     2) 8K RAM extension - suitable for GENIE, LIFEGUARD, or as a buffer,
  1536.     3) MULTI TOOLKIT to study/modify/develop programs, POKE infinite lives,
  1537.        etc.
  1538.  
  1539.     Multiface 128 works on the Spectrum 48/128.  It can be used any time in
  1540.     any mode; it is immaterial what is inside the Spectrum at that moment
  1541.     or how or from what source (tape, disk, cartridge) it has been loaded
  1542.     (or typed in, etc.).  Multiface does not save programs, but computer
  1543.     contents (compressed RAM image).  Upon returning from the M128 or upon
  1544.     re-loading, the programs continue as if never frozen.  To use the M128:
  1545.  
  1546.     1) Push the NMI key (F5)
  1547.     2) Select the required option from the menu
  1548.  
  1549.     The MAIN MENU options are:
  1550.  
  1551.     Exit: to abandon the Multiface and exit to BASIC (provided BASIC is
  1552.       present).  By using exit, you come out of the Multiface entirely.
  1553.       All efforts are made to preserve the current program in the Spectrum
  1554.       intact.  The main condition is the existence of standard system
  1555.       variables - without these the Spectrum crashes.  A successful exit
  1556.       gives you full access to the program.  To restart it, if needed, you
  1557.       must know the starting line or address.  Exit is impossible in the
  1558.       128K mode when the edit ROM is paged and Spectrum ROM is off; in such
  1559.       cases it does not appear on the menu at all.  All in all, you can
  1560.       only exit to BASIC if it exists - it is like jumping into a pool: a
  1561.       joy if it's full of water, a crash if there is none.
  1562.  
  1563.     Return: to continue the program.
  1564.  
  1565.     Save: to proceed to the SAVE routines:
  1566.       a) input the name of the program.  Up to 9 characters (or just press
  1567.          ENTER to the input RUN automatically as a default)
  1568.       b) save to: Tape, Microdrive, Opus [does nothing], Disciple (use D
  1569.          for Plus D too).  You can save the entire program (including the
  1570.          screen), or the screen only.  Programs are compressed to take the
  1571.          minimal room possible and to load faster.  Screens saved on their
  1572.          own are left intact as standard Spectrum screens.
  1573.       c) Format microdrive cartridges.  Cartridges are automatically named
  1574.          after the programs to be saved.
  1575.  
  1576.     Tool: to access the MULTI TOOLKIT routines.
  1577.       quit - to return to the main menu
  1578.       Enter - to PEEK and scroll through addresses or to POKE
  1579.       Space - to allow you to type in a new address
  1580.       hex - to toggle between hexadecimal and decimal display format
  1581.       reg - to point to the Z80 registers as they were when the program was
  1582.         frozen
  1583.       window - to open a window with full on-screen editing using the
  1584.         cursor keys.  The flashing window address corresponds to the
  1585.         address in the bottom edit line.  The window display is by default
  1586.         in hex, but you can change it to
  1587.       text - to see the 128 bytes in the window as ASCII text.
  1588.       select - to inspect RAM banks 0-7 in 128K mode.  Press s + the bank
  1589.         number
  1590.  
  1591.     Print - to dump screen to printer.  For printer interfaces using COPY
  1592.       command.  You can POKE address 8200 (decimal) with the following
  1593.       values, if you wish to
  1594.       113 to turn the line feed on (cr+lf)
  1595.       112 to turn the line feed off (cr)
  1596.       17 to dump screen as text with the line feed on
  1597.       16 to dump screen as text with the line feed off
  1598.  
  1599.     Jump - not to return, but jump to another address.  Strictly for
  1600.       machine code users only.  Enter the address to jump at 8192/3
  1601.       (low/hi).  You can jump to Spectrum ROM/RAM and to M128 8K RAM.  As
  1602.       the M128 overshadows the ZX ROM (8192-16383), address 8194 determines
  1603.       the paging status: if it is 0, the M128 RAM remains paged, 1 pages
  1604.       out the RAM and any other value disables the jump command completely.
  1605.       [Note: if it is 0, also the M128 ROM (0-8191) remains paged.]
  1606.  
  1607.       You can jump from the main menu, and you can also pre-program M128 to
  1608.       jump directly upon NMI (F5) and by-pass the M128 ROM software
  1609.       entirely.  To program the direct jump, POKE 8192-3 with the jump
  1610.       address, and then also 8195-7 with a special identification word RUN
  1611.       (i.e. 82,85,87).  Whenever you press NMI now, you will jump to the
  1612.       predefined address and not see the M128 menu.  To return from your
  1613.       program to the program you stopped, use RST 0.  To revert back to the
  1614.       Multiface normal operation, press NMI and BREAK (shift+space)
  1615.       simultaneously.  This also cancels the code word RUN.
  1616.  
  1617.       In standard mode M128 uses 8192-11144 as a buffer (8192-13496 once
  1618.       you proceed to SAVE) and overwrites anything in there.  Using direct
  1619.       jump, you have 8257-16338 available.
  1620.  
  1621.     Clear - to clear the extra 64K RAM bank (in 128K mode only!).  You can
  1622.       clear any time, but it is only useful with 48K programs in 128K mode.
  1623.       However, you should save 48K programs in 48K mode anyway.  Also, for
  1624.       obvious reasons, clearing the banks in 128K programs is not a good
  1625.       idea.
  1626.  
  1627.  
  1628.     The actual M128 has a software on/off switch, so that it could be made
  1629.     completely invisible to programs until the NMI switch was pressed. This
  1630.     software switch is not emulated.  The M128 could be turned off by
  1631.     pressing 'O' in the main menu; this does not work on the emulator.  You
  1632.     can turn off the M128 in the Select Hardware (F9) menu.
  1633.  
  1634.     Using the extra 8K RAM - M128 has an 8K Rom containing its own
  1635.     software, and an 8K RAM used as a buffer.  You can use the 8K RAM for
  1636.     your own mcode routines or for data (but not for BASIC).  The RAM must
  1637.     be paged in machine code to be accessed: use IN A,(191) to page in, and
  1638.     IN A,(63) to page out.  The BASIC In and Out commands can not be used
  1639.     here (they work, but result in a crash).  The 8K RAM overshadows the
  1640.     Spectrum ROM and thus anything contained in the M128 RAM cannot make
  1641.     any calls to the Spectrum ROM, as they both occupy the same area. The
  1642.     M128 RAM routines should therefore be self-contained, independent of
  1643.     the Spectrum ROM.
  1644.  
  1645.     Poking infinite lives - To POKE, say 31000,0, first load the program as
  1646.     usual.  When it's loaded, press NMI (F5) and select the tool by
  1647.     pressing T.  When the toolkit menu appears, press SPACE and type 31000.
  1648.     Once you type 5 digits the cursor automatically moves to the value
  1649.     field (no need to press ENTER), so type 0 (value is 1-3 digits long)
  1650.     and this time press ENTER.  Finally press Q to quit the toolkit and R
  1651.     to return to the program.
  1652.  
  1653.  
  1654.     The Multiface 128 was designed by Romantic Robot UK Ltd, 54 Deanscroft
  1655.     Avenue, London NW9 8EN, tel. 081-200 8870.
  1656.  
  1657.  
  1658.  
  1659.  
  1660. 2.13  Using the RS232 channel
  1661.  
  1662.  
  1663.     This was the only Spectrum i/o channel that could be used in the early
  1664.     versions of the emulator.  Using .TAP files instead of the RS232
  1665.     channel is often easier, but sometimes using the RS232 channel can be
  1666.     very useful too, for instance if you've got a null-modem lead that
  1667.     connects a Spectrum with interface I to the PC you can use it to
  1668.     transfer data and programs easily.  Furthermore, the RS232 channel is
  1669.     the easiest way to let the emulator communicate with a PC printer.
  1670.  
  1671.     Several things send their output to the channel designated as 'RS232
  1672.     output channel'.  First of all the ordinary Interface I RS232 "B" and
  1673.     "T" channels.  Secondly the 128K printer "P" channel.  Thirdly, ZX
  1674.     Printer output is converted to a format appropriate for Epson or HP PCL
  1675.     printers (works for most dot matrix, and most laser/inkjet printers
  1676.     respectively) and also sent to this channel. Input from the 'RS232
  1677.     input channel' is sent to the Interface I's "B" and "T" channels.
  1678.  
  1679.     The Interface I RS232 port, the "B" or "T" channel, behave slightly
  1680.     differently.  The first, binary, channel is the raw channel.  It will
  1681.     let all data go through unchanged.  The "T" channel won't let all
  1682.     control codes through and will expand any keyword; useful for LISTing a
  1683.     program but otherwise annoying.
  1684.  
  1685.     The Spectrum 128 has its own RS232 port; it is called the "P" channel.
  1686.     Output to either the Interface I's or Spectrum 128's own RS232 port
  1687.     will all be processed as 'RS232 output'.
  1688.  
  1689.     The output to the RS232 channel can be routed to an LPT port, to a COM
  1690.     port or to a file on disk.  Input can come from either a file or a COM
  1691.     port.
  1692.  
  1693.     If you want to use the RS232 channel for printing using LPRINT and
  1694.     LLIST (shorthand for PRINT #3 and LIST #3), be sure to open that
  1695.     channel for output to RS232; by default it sends its output to the ZX
  1696.     Printer, which is not supported.  You can open the channel by typing
  1697.     OPEN #3,"B" (or "T" for listings, or "P" on a Spectrum 128).
  1698.  
  1699.     Input and output are buffered.  This is important to remember when
  1700.     you're transferring files using the SAVE and LOAD *"b" commands of the
  1701.     Interface I.  If the header is missed, for instance if you try to load
  1702.     the wrong file type, re-sending the file will not directly work because
  1703.     there will still be bytes in the buffer.  You have to clear the input
  1704.     buffer before re-sending the file.  When inputting from a disk file,
  1705.     the file pointer can be reset to point to the start of the file again
  1706.     to re-read the header.
  1707.  
  1708.     When inputting from or outputting to a disk file, the read or write
  1709.     position is displayed as a byte-count.  An <EOF> sign will appear if an
  1710.     input file is read completely through to the end.
  1711.  
  1712.     The RS232 redirection options are in the Change Settings (F4) menu.
  1713.  
  1714.     When using a COM port, make sure you have initialised it before
  1715.     starting the emulator with the Dos MODE command, for instance
  1716.  
  1717.         MODE com1:96,n,8,1
  1718.  
  1719.     initialises COM1 to send and receive at 9600 baud, no parity, 8 data
  1720.     bits and 1 stop bit, the default for the Interface I.
  1721.  
  1722.     Here is how to transfer programs from a Spectrum to the PC using the
  1723.     RS232 lead.  First, you need a null-modem lead.  I myself use the
  1724.     following cable:
  1725.  
  1726.           Spectrum                                  'AT'      'PC'
  1727.           (9 pins)                                (9 pins)  (25 pins)
  1728.  
  1729.             3 TxD   ───────────────────────── RxD     2         3
  1730.  
  1731.             4 DSR   ───────────────────────── DTR     4        20
  1732.  
  1733.                                         ┌──── CTS     7         4
  1734.                                         └──── RTS     8         5
  1735.  
  1736.             7 GND   ───────────────────────── GND     5         7
  1737.  
  1738.     (so CTS and RTS have to be connected!)  This is not a full null-modem
  1739.     lead; you can only send data from the Spectrum to a PC.  If you have an
  1740.     Interface I, you can use the LOAD *"b" and SAVE *"b" commands on both
  1741.     your real Spectrum and the emulator to transfer programs and data. It's
  1742.     best to first type LOAD *"b" and then SAVE instead of the other way
  1743.     around.  If you have problems with transferring data, try to lower the
  1744.     baud rate to 4800 or 2400 baud; this sometimes helps.
  1745.  
  1746.     If you don't have an Interface I, but do have a printer interface using
  1747.     RS232 leads, then you can transfer data using LPRINT on the Spectrum
  1748.     side, and INKEY$ #3 on the emulator side.  It needs a little bit of
  1749.     programming.
  1750.  
  1751.  
  1752.  
  1753.  
  1754. 2.14  On joysticks and mice
  1755.  
  1756.  
  1757.     The emulator support several joysticks and the Microsoft mouse, to
  1758.     control several Spectrum joystick interfaces, and the AMS Mouse
  1759.     interface.  First, joysticks are discussed.
  1760.  
  1761.     As was already said in the introduction, the emulated Spectrum joystick
  1762.     (Cursor, Interface 2, Kempston or user defined) is controlled by the PC
  1763.     cursor keys and 5/0/.  on the numeric keypad and TAB as fire keys.  The
  1764.     emulated joystick can also be controlled by a mouse, or by a real
  1765.     joystick, either analogue (PC standard) or digital.
  1766.  
  1767.     The analogue joystick support is rather straightforward.  If you've got
  1768.     one, it works - it couldn't be simpler.  The digital joystick support
  1769.     is less obvious, since PC's don't support these.
  1770.  
  1771.     To use digital joysticks, Ruud Zandbergen has made a device that uses
  1772.     the two inputs of a normal analogue joystickinterface to connect a
  1773.     digital joystick to a PC.  Here's the circuit diagram:
  1774.  
  1775.  
  1776.     15 pins male  (pc)                           9 pins male (joystick)
  1777.  
  1778.  
  1779.     1+9 <─────────┬───────────┬────────────┬─────────────┬──> 7 (5V)
  1780.                  ┌┴┐         ┌┴┐          ┌┴┐           ┌┴┐
  1781.         4 x 1 kΩ │ │ ¼ Watt  │ │          │ │           │ │
  1782.                  └┬┘         └┬┘          └┬┘           └┬┘
  1783.     3   <─────────┴──> 4 (up) │            │             │
  1784.                               │            │             │
  1785.     6   <─────────────────────┴──> 3 (dwn) │             │
  1786.                                            │             │
  1787.     13  <──────────────────────────────────┴──> 1 (rght) │
  1788.                                                          │
  1789.     11  <────────────────────────────────────────────────┴──> 2 (lft)
  1790.                        ┌────────────────────┐
  1791.     2   <──────────────┤    47 Ω ¼ Watt     ├───────────────> 6 (fire)
  1792.                        └────────────────────┘
  1793.     4+5+14 <────────────────────────────────────────────────> 8 (0V)
  1794.  
  1795.  
  1796.     4+5+14 means: connect pins 4, 5 and 14.  The same applies for pins 1 and
  1797.     9.  Here's the list of ingredients:
  1798.  
  1799.         1 x 9 pins D plug, male
  1800.         1 x 15 pins D plug, male
  1801.         4 x 1kΩ , ¼ Watt resistors
  1802.         1 x 47 Ω, ¼ Watt resistor
  1803.         piece of 7-wire flatcable
  1804.  
  1805.     Everything can be fitted into the 15-pins plug. Make sure the resistors
  1806.     don't touch the other blank connections! This interface can be used for
  1807.     all usual digital joysticks, with or without auto fire (that is every
  1808.     joystick that work with a Kempston joystick interface, or that work on
  1809.     a Commodore 64/Amiga or Atari). The joysticks for the Spectrum +2/+3
  1810.     will not work, however the pin layout is easy to change.
  1811.  
  1812.     This joystick interface needs an analogue PC-joystick interface on
  1813.     which you can connect TWO analogue joysticks (on one plug!).  Most
  1814.     cards can do this, but some multi-I/O cards support only one joystick.
  1815.     Check the documentation of your I/O card to see whether your
  1816.     joystickinterface is suitable.  The soundblaster joystick interface
  1817.     works fine.
  1818.  
  1819.     A number of PC games will behave strangely when the digital joystick
  1820.     interface is connected; they run very slow or crash.  When this
  1821.     happens, remove the joystick interface (not only the joystick!).
  1822.  
  1823.     With version 3, the Spectrum joystick (Cursor, Kempston, Sinclair 2 or
  1824.     user defined) can not only be controlled by the cursor keys or a real
  1825.     joystick, but also by a mouse.  Specify -km on the command line to have
  1826.     the mouse control the joystick too.  (By default, this switch is
  1827.     already in the Z80.INI file.)
  1828.  
  1829.     Finally, the Microsoft mouse can control the AMS Mouse interface, as
  1830.     supported for example by Art Studio.  Specify -ka on the command line
  1831.     to select this option.  The mouse will not control the joystick
  1832.     anymore.  Because of I/O address clashes, the AMS Mouse does not work
  1833.     with SamRam or an M.G.T. interface enabled.  Also, since the AMS
  1834.     interface must be initialized, and the state of the AMS interface is
  1835.     not saved in the .Z80 snapshot file, it may be necessary to make the
  1836.     snapshot before the point at which the Spectrum program initializes the
  1837.     AMS interface.  The program Art Studio re-initializes the AMS interface
  1838.     regularly, however, so with this program you don't have to worry about
  1839.     it.
  1840.  
  1841.  
  1842.  
  1843.  
  1844. 2.15  The utility ConvZ80
  1845.  
  1846.  
  1847.     This program converts between various snapshot formats, and it can also
  1848.     convert various tape file formats to .TAP files.  Currently it supports
  1849.     .SNA format (used in various emulators, such as JPP, Peter McGavin's
  1850.     emulator on the Amiga, and XZX), the .SP format of VGASPEC and
  1851.     SPECTRUM, the .PRG format of SpecEm, and all old .Z80 file formats.
  1852.  
  1853.     If conversion is to a .Z80 file, the old (v1.45) format will be used.
  1854.     This is still supported by the emulator, and some other programs do not
  1855.     support the new format.  Note that, because of this, ConvZ80 will not
  1856.     convert .Z80 files containing snapshots of 128K or SamRam programs.
  1857.  
  1858.     CONVZ80 recognizes what it should do by the extension of the files you
  1859.     enter on the command line; to distinguish between VGASPEC's and
  1860.     SPECTRUM's .SP formats you can use the switch -o.  If the extension
  1861.     consists of digits only, it is taken to be a ZX tape file, and if it
  1862.     contains non-digits and is none of .SP, .Z80, .SNA, .PRG or .TAP it is
  1863.     regarded as a SpecEm tape file.
  1864.  
  1865.     SpecEm can load .PRG snapshot files, but cannot save them.  However, it
  1866.     emulates the Multiface I, which can save snapshots to tape.  SpecEm
  1867.     will save these blocks as tape files to disk.  If you convert these to
  1868.     a .TAP file (in the correct order!), you can load them into Z80 and
  1869.     save the program as a .Z80 file.
  1870.  
  1871.  
  1872.  
  1873.  
  1874. 2.16  Converting file formats - the utility CONVERT
  1875.  
  1876.  
  1877.     This section is about the utility CONVERT, which can convert some of
  1878.     the Spectrum's own format into each other, and also converts some of
  1879.     the emulator's formats into others.  It is not about converting files
  1880.     from other emulators; read section 2.15 if you want to know about that.
  1881.  
  1882.     CONVERT was useful when the emulator could only communicate with
  1883.     snapshot files and the RS232 link.  It has become less useful now, with
  1884.     .TAP files and the possibility to load and save blocks directly into
  1885.     and from Spectrum memory, but it still has some useful features.
  1886.  
  1887.     It can read three types of input files: pure ASCII, pure bytes (for
  1888.     instance a .SCR screen dump), and files produced by a SAVE *"b"
  1889.     command.
  1890.  
  1891.     Output is pure bytes, ASCII with either CR (Spectrum standard) or CR/LF
  1892.     (PC standard) for line breaks, SAVE *"b" files containing a Basic or
  1893.     code file, a .PCX or a .GIF file.
  1894.  
  1895.     So what can you do? Main uses are adding LF (10 hex) bytes to a text
  1896.     file produced by the Spectrum; converting a code block into a SAVE *"b"
  1897.     to load it into the Spectrum using LOAD *"b" (and the reverse of
  1898.     course: converting a SAVE *"b" file to pure bytes), and converting a
  1899.     screen dump to .PCX or .GIF graphics files.
  1900.  
  1901.     Less useful, but possible: LISTing a program (SAVE *"b" file) to
  1902.     produce readable ASCII, and the reverse: converting an ASCII listing to
  1903.     executable Basic again.
  1904.  
  1905.     If you want to make a .PCX or a .GIF file, input should be a SAVE *"b"
  1906.     file of a screen (length 6921 bytes exactly) or a bare .SCR screendump
  1907.     (length 6912 bytes).  You can make screendumps by selecting the X-Extra
  1908.     functions menu from the main menu.
  1909.  
  1910.  
  1911.  
  1912.  
  1913. 2.17  The utilities Z802TAP, TAP2TAPE and TAP2VOC
  1914.  
  1915.  
  1916.     The SamRam has built in it some snapshot software.  Using this software
  1917.     you can save any 48K Spectrum program to tape or to a .TAP file, as is
  1918.     explained in section 3.2 below.  But the SamRam software cannot handle
  1919.     a 128K program.  The Multiface 128 can also write a snapshot to tape,
  1920.     but in some cases it is still preferrable to use TAP2TAPE, since the
  1921.     latter produces less and shorter blocks, and doesn't corrupt the screen
  1922.     as much as the Multiface code does (on Spectrums without Multiface).
  1923.  
  1924.     The utility that can convert a 128K snapshot (and 48K ones for that
  1925.     matter) to a .TAP file is called Z802TAP.  The .TAP file includes a
  1926.     basic loader, and a loading screen if you want.  Z802TAP compresses the
  1927.     blocks it writes (using a better method than used in compressing .Z80
  1928.     files) to save loading time.  If you don't want it to compress the
  1929.     blocks, for instance when you want to take a look at the ram pages of
  1930.     the Spectrum 128, specify -u when you run Z802TAP.  You can load the
  1931.     converted program simply by executing
  1932.  
  1933.         Z80 -ti tapefile
  1934.  
  1935.     and typing LOAD "" (for a 48K program) or changing the hardware mode to
  1936.     Spectrum 128 and choose 'Tape Loader' in the menu.
  1937.  
  1938.     Of course you could also use Multiface 128 or the SamRam to convert a
  1939.     snapshot to a .TAP file.
  1940.  
  1941.  
  1942.     The program TAP2TAPE writes .TAP files back to tape.  The program
  1943.     consists of a batch file TAP2TAPE.BAT, which executes the TAP2TAPE.Z80
  1944.     file using the emulator.  The .TAP file is written to tape exactly as
  1945.     it is, so that if a block contains a tape error, it won't load
  1946.     correctly from tape either.  If the entire .TAP file has been saved the
  1947.     emulator will start loading from tape.  At that point, press space once
  1948.     to return to DOS.
  1949.  
  1950.     The TAP2VOC program converts the tape block in a .TAP file to the
  1951.     corresponding bips and clicks.  The resulting .VOC file will be rather
  1952.     large.  It can be loaded back into the emulator, which is rather silly
  1953.     since using the original .TAP file is better in all respects, or you
  1954.     can write the program to tape using a sample player.
  1955.  
  1956.  
  1957.  
  1958.  
  1959. 2.18  The utility OUT2VOC - and how to make .OUT files
  1960.  
  1961.  
  1962.     The emulator can log OUTs to any I/O port.  These OUTs are logged in a
  1963.     .OUT file, in which is stored what was written to which port at what
  1964.     time.  These log files are used for recording sounds the emulated
  1965.     Spectrum produces.
  1966.  
  1967.     The OUTs to port FE, which controls the internal beeper, and those to
  1968.     ports BFFD and FFFD, which control the soundchip of the Spectrum 128,
  1969.     are translated into a sample file by OUT2VOC.
  1970.  
  1971.     There are a number of command line switches.  The sample frequency can
  1972.     be chosen by specifying "-f frequency" on the command line.  By default
  1973.     a sampling frequency of 10 kHz is used.
  1974.  
  1975.     Ordinarily the OUT2VOC program filters out all frequencies above half
  1976.     the sampling frequency, so that no aliasing occurs when the signal is
  1977.     stored as a sequence of samples in a .VOC sample file.  For sample
  1978.     files containing tape data, these aliasing effects are not important.
  1979.     For these sample files you can use -d to produce 'digital' sample
  1980.     files, containing only 'high' and 'low' sample values, and nothing in
  1981.     between.  These sample files can also be compressed much better.
  1982.  
  1983.     By default, the OUT2VOC program listens to the EAR output only.
  1984.     Specify -m to have it listen to the MIC output (only), and -a to have
  1985.     it listen to the AY-3-8912 soundchip of the Spectrum 128.  If you
  1986.     specify for example -e -a, the program will listen to both
  1987.     corresponding channels.
  1988.  
  1989.     Usually, not all registers of the AY soundchip are updated continually.
  1990.     Some registers are initialised and left at that.  So usually it is
  1991.     necessary to supply the initial values of the soundchip registers.  Do
  1992.     this by specifying '-i file', where 'file' is the snapshot taken just
  1993.     before the OUTs were recorded.
  1994.  
  1995.     Some Spectrum programs use extremely many OUTs to produce sounds.
  1996.     Fairlight for example OUTs about 70000 times a second, thereby indeed
  1997.     producing one of the finest music I've every heard coming out of an
  1998.     ordinary Spectrum.  The OUT2VOC program takes quite some time to
  1999.     compute the .VOC file from the raw .OUT output.  Use -q for a quick
  2000.     and little less precise conversion.  The difference seems to be barely
  2001.     audible.  This switch has no effect when converting '128 music.
  2002.  
  2003.     If you specify -s, silences of longer than 1 second will be truncated
  2004.     to 1 second.
  2005.  
  2006.     Finally, use -r to produce a raw sample file, without any header or
  2007.     length info.
  2008.  
  2009.     To record a sample, go to the Extra Functions menu (F10, X), and select
  2010.     O.  Select the ports you want to log (by default only FE is logged) and
  2011.     enter a name for the log file.  OUTs will be logged until you specify
  2012.     an illegal name, or press ENTER on an empty line here.
  2013.  
  2014.     To save a block of data to a .OUT file, simply type the right SAVE
  2015.     command or use any (turbo-save) program to save it to tape.  Note that
  2016.     .OUT files tend to grow fast; one bit on the tape corresponds to two
  2017.     OUTs and therefore two 5-byte entries in the .OUT file; an 48K file
  2018.     will produce a .OUT file of at least 4 Megabytes.
  2019.  
  2020.     If you give a 16 bit address for an I/O port, only OUTs to this address
  2021.     will be logged.  If you give an address smaller than 100 hex, all
  2022.     addresses whose low byte equal this number are logged.  Note that it is
  2023.     not possible to log all OUTs to, say, an even port.  Although the MIC
  2024.     and EAR ports respond to all even port addresses, virtually no program
  2025.     uses a port different from FE, so this will be no problem in practice.
  2026.  
  2027.     Note that whereas the 'official' addresses of the register and
  2028.     value-port of the AY soundchip are FFFD and BFFD respectively, some
  2029.     programs use other ports that work too.  One particular program uses
  2030.     BEFD, heaven knows why.  For these programs, specify FD (or 00FD) as
  2031.     OUT port to log; this will ensure that all OUTs to any address with low
  2032.     byte FD is logged (which, alas, includes the much-used port 7FFD).
  2033.  
  2034.  
  2035.  
  2036.  
  2037. 2.19  Quick overview of command line switches, and features
  2038.  
  2039.  
  2040.     In this section I will briefly explain all command line switches.  It
  2041.     is useful to at least once read this section carefully; there are a few
  2042.     small handy features that will otherwise be readily overlooked. Starred
  2043.     switches are by default put in the Z80.INI file.
  2044.  
  2045.        -h        Hercules graphics
  2046.        -xh       Extended Hercules graphics
  2047.        -p        Plantronics graphics
  2048.        -q        Plantronics, different palette
  2049.        -c        CGA graphics
  2050.        -e        EGA graphics
  2051.        -v        VGA graphics
  2052.  
  2053.     Usually the emulator will by itself correctly determine which mode to
  2054.     use.  VGA mode is by far the best: it is the only mode in which all
  2055.     colours are correct (including the bright hues), and it is also the
  2056.     fastest mode.  On old computers with only an Hercules adapter, extended
  2057.     Hercules will usually give much better results.
  2058.  
  2059.        -xv       400-line VGA (for some Tridents)
  2060.        -xb       Black-and-white VGA
  2061.  
  2062.     The black-and-white switch is useful on black-and-white monitors;
  2063.     sometimes those only display one component of the RGB signal instead of
  2064.     a weighted average, so that some colours become indistinguishable grey
  2065.     tones.
  2066.  
  2067.     Some Trident video adapters, as well as some others, have a bug in
  2068.     their video BIOS: they don't want to be put in 200-line mode.  To get
  2069.     around this, when -xv is specified 400-line mode is used with a double
  2070.     amount of lines.
  2071.  
  2072.        -n        Emulate Spectrum without Interface I
  2073.        -s        Emulate Spectrum with SamRam
  2074.        -1[28]    Emulate Spectrum 128 (can be used with -n)
  2075.        -xk       Emulate Multiface 128 interface  (can't be used with SamRam)
  2076.        -9        Default to M.G.T. interface instead of Interface I
  2077.        -0d       M.G.T. = DISCiPLE ROM (default)
  2078.        -0p       M.G.T. = Plus D
  2079.  
  2080.     These switches select the default start-up hardware configuration of
  2081.     the emulator.  This can all be changed in the Change Hardware menu
  2082.     under function key F9.
  2083.  
  2084.     *  -znnn.n   Emulate the Spectrum at speed nnn.n%
  2085.  
  2086.     The most sensible setting for this is -z100.  By default this is done
  2087.     in the Z80.INI file.
  2088.  
  2089.        -xx       Hi-resolution colour emulation
  2090.  
  2091.     This selects hi-res colour emulation by default, so that border effects
  2092.     and hi-res colour effects are visible.  This setting can be changed in
  2093.     the F4 menu.
  2094.  
  2095.        -r        Emulate the R register
  2096.  
  2097.     This is usually necessary in turbo loaders and otherwise protected
  2098.     programs, since they almost invariably use the R register to decode
  2099.     things.  The R register has to be updated every instruction, so that
  2100.     enabling the emulation of it reduces the emulation speed considerably,
  2101.     by some 30%.  Don't do it unless it proves to be necessary.  I don't
  2102.     know of any program that uses it on the run.  If the R register is not
  2103.     emulated, the R register acts as a random generator.
  2104.  
  2105.     *  -l        Better (but slower) LDIR/LDDR emulation
  2106.  
  2107.     Normally a 8086 MOVSB is used to emulate an LDIR or LDDR.  This is a
  2108.     fast instruction.  Programs that use them a lot, most notably Jetset
  2109.     Willy and Manic Miner, run very fast.  On slow computers these programs
  2110.     are the only ones that are really playable.  On fast computers they run
  2111.     much too fast, so it is a wise thing to use -l on fast computers.
  2112.     Secondly, without -l the LDIR instruction is not emulated correctly
  2113.     when it overwrites itself; with -l it is.
  2114.  
  2115.        -yl, -yh  Low, high video synchronization mode
  2116.  
  2117.     These switches control the phase between the 50 Hz interrupt and the
  2118.     screen refresh.  Some programs need a different setting in order to
  2119.     remove flickering of moving characters.  Enabling hi-resolution color
  2120.     emulation also eliminates these problems.
  2121.  
  2122.        -2        Emulate an Issue-2 Spectrum
  2123.  
  2124.     Make the EAR line 1 when there's no signal, instead of 0 as it is on
  2125.     Issue 3 Spectrum's.  Some old programs need it (Spinads for example).
  2126.  
  2127.        -d        Double interrupt frequency (100 Hz)
  2128.  
  2129.     On slow computers this may help to get the keyboard to respond better.
  2130.  
  2131.        -aN       Redirect Spectrum RS232 output to LPTn
  2132.        -oN       Redirect Spectrum RS232 output to COMn
  2133.        -uF       Redirect file F to Spectrum RS232 input
  2134.        -iN       Redirect COMn to Spectrum RS232 input
  2135.        -wF       Redirect Spectrum RS232 output to file F
  2136.  
  2137.     All output to, and reading from, the Interface I's RS232 channel
  2138.     (channels "b" and "t"), the 128K printer channel (channel "p") will be
  2139.     sent to, respectively read from, the appropriate device.  Furthermore,
  2140.     output to the ZX Printer will be converted in a format suited for Epson
  2141.     matrix printers or HP Laserjet printers and also be sent to the 'RS232
  2142.     output' device or file.
  2143.  
  2144.        -g        No sound
  2145.        -xa       Do NOT use AdLib for 128 sound
  2146.        -xc       Use SoundBlaster CMS chips for noise
  2147.        -xi       Do NOT use internal PC speaker for '128 sound
  2148.  
  2149.     If no AdLib compatible card is detected, 128K sound output will be
  2150.     sent, as far as is possible, to the internal PC speaker.  Use -xa to
  2151.     hear 128K sound through the PC speaker when there is an AdLib card
  2152.     present.
  2153.  
  2154.     Without CMS chips, the 128K soundchip's noise cannot be faithfully
  2155.     reproduced.  If you have CMS chips installed, use -xc to use them.  If
  2156.     the SoundBlaster is on a different base address than 0220, use -xq to
  2157.     select it.
  2158.  
  2159.     *  -km       Use MS Mouse to control Spectrum joystick
  2160.        -ka       Emulate Spectrum AMS mouse interface controlled by MS Mouse
  2161.        -kz       Use digital Zandbergen joystick
  2162.        -kk       Do not look for analogue or Zandbergen joystick
  2163.  
  2164.     The emulated joystick (Cursor, Kempston, Sinclair 2 or user defined) is
  2165.     controlled by the arrow keys and TAB, 5, INS (0) on the PC keyboard,
  2166.     and optionally also by a digital joystick, and analogue IBM joystick or
  2167.     a mouse.  Use -kk if the emulator erroneously detects either joystick.
  2168.     If -ka is specified, the PC mouse controls the emulated AMS mouse
  2169.     interface.  Because of I/O address clashes, this only works with SamRam
  2170.     and the M.G.T. interfaces disabled.  The AMS mouse is supported by e.g.
  2171.     Art Studio.
  2172.  
  2173.        -jc       Emulate Cursor joystick (default)
  2174.        -jk       Emulate Kempston joystick
  2175.        -j2       Emulate Sinclair joystick 2 (keys 6,7,8,9 and 0)
  2176.        -ju<lf><rt><up><dn><fire>  User defined joystick
  2177.  
  2178.     Also quite clear I think.  For instance, -juipqzm makes the joystick
  2179.     control the i,p,q,z and m keys, for instance to play those lovely
  2180.     Horace games.  Special characters are [ for shift, ] for symbol shift,
  2181.     / for enter and \ for space.
  2182.  
  2183.     *  -xs       Default to shifted cursor keys (NumLock) in '128 mode
  2184.  
  2185.     By default, the PC arrow keys control the cursor keys 5,6,7,8 and 0 of
  2186.     the Spectrum.  The Spectrum 128 had its arrow keys press the cursor
  2187.     keys plus shift, and the menu bar of the reset screen of the '128 only
  2188.     responds to shift+cursor key.
  2189.  
  2190.        -bN       Use LPTn for tape I/O
  2191.        -xo       Use SoundBlaster's A/D Converter for tape input
  2192.        -xq adr   Set base IO address for SoundBlaster (default 0220)
  2193.  
  2194.     Either the LPT tape interface of the SoundBlaster is used for tape
  2195.     input.  Only the LPT tape interface can be used for tape (MIC) output.
  2196.  
  2197.        -tv F     Play .VOC file F to 'ear' input
  2198.        -m N F    Insert cartridge file F{.MDR} into microdrive N
  2199.        -xm D     Select default directory D for .MDR files
  2200.        -td D     Select directory D for Multiple .TAP File mode
  2201.        -ts D     Specify default directory for Single .TAP File mode
  2202.        -ti F     Use F{.TAP} as tape input
  2203.        -to F     Use F{.TAP} as tape output (if exists, append)
  2204.        -tm       Mirror tape input to disk (Do also specify output file!)
  2205.        -te       Mirror tape input to disk in EXACT mode
  2206.        -tw       Don't wrap load pointer of tapefile at end
  2207.  
  2208.     All quite clear I think.  If -tv is used, the VOC file starts playing
  2209.     immediately, so be sure there's an appropriate snapshot running to do
  2210.     something with the signal.  -tw makes the emulator load from physical
  2211.     tape when a .TAP file has been read to the end, instead of starting
  2212.     again from the beginning.
  2213.  
  2214.        -0e       Epson printer (for ZX PRINTER & M.G.T.)
  2215.        -0h       HP PCL printer (for ZX PRINTER & M.G.T.)
  2216.  
  2217.     Output to the ZX Printer will be converted into graphic data in Epson
  2218.     or HP PCL format and sent to the 'RS232 output'.  Use one of these
  2219.     switches to select which format to use.  Also, this selects the default
  2220.     DISCiPLE ROM to be used; the two ROMs have different screen dump
  2221.     routines pre-loaded.
  2222.  
  2223.        -0i       Disable Disciple interrupt
  2224.  
  2225.     Normally the Disciple and Plus D have their own interrupt routine being
  2226.     executed 50 times a second.  Because this involves many page swaps,
  2227.     this is quite slow on the emulator.  Since the interrupt is not really
  2228.     necessary anyway, it is reduced to once every two seconds.  On some
  2229.     computers this may still be too much, in which case -0i completely
  2230.     disables the Disciple and Plus D interrupts.  Do not try this in
  2231.     Unidos!  (which is not emulated [yet].)
  2232.  
  2233.        -xp D     Select default directory D for .Z80 snapshot files
  2234.  
  2235.     Clear.
  2236.  
  2237.        -xz       Assume AZERTY keyboard layout
  2238.  
  2239.     Assumes the Belgian and French AZERTY keyboard layout.
  2240.  
  2241.        -xr F     Use file F as standard Spectrum rom
  2242.  
  2243.     The ROM will be used in 48K modes only, and must be exactly 16K long.
  2244.  
  2245.        -xt       Use as little memory as possible with full functionality
  2246.        -xu       Use as little memory as possible; disable HCR emulation
  2247.  
  2248.     With -xt, all unnecessary buffers used for efficiency purposes only are
  2249.     reduced to minimum size.  Saves 47K, but can make all the difference
  2250.     sometimes.  With -xu, 83K is saved, but Hi Color Resolution emulation
  2251.     won't work anymore.
  2252.  
  2253.        -tx       Do not display tape info window when loading or saving
  2254.  
  2255.     Some people really seem to hate it.  Don't know why.
  2256.  
  2257.        -xe       Do not use expanded memory
  2258.  
  2259.     Specifying this switch will result in the emulator using 240K more base
  2260.     memory (making a grand total of 571K).  Furthermore, all page swapping
  2261.     will be much slower, so especially the 128K emulation gets verrry slow.
  2262.  
  2263.        -xg       Log all outs to FE in OUT log file
  2264.        -xy       Dump trace of program in .OUT file
  2265.  
  2266.     By default, OUTs to port #FE that do not change the state of either MIC
  2267.     or EAR are not saved to the log file, to save disk space.  If, for some
  2268.     reason, you want all OUTs to be logged, -xg will do the trick.  The -xy
  2269.     option can be used for producing a somewhat crude trace; see section
  2270.     5.5 on the .OUT format for more details.
  2271.  
  2272.        -xw       Run in Windows compatibility mode
  2273.  
  2274.     In this mode, neither the timer interrupt nor the keyboard interrupt
  2275.     are re-routed.  The emulator counts T states to see when an interrupt
  2276.     has to be generated (so emulation will be slower), and uses the BIOS
  2277.     keyboard routines to read the keyboard.  Since the BIOS doesn't tell
  2278.     when a key is released, and since not all key combinations are mapped
  2279.     to an (extended) ASCII value, keyboard emulation is inferior to the
  2280.     emulation in normal mode.  This mode is selected automatically when the
  2281.     emulator is run under Windows; use this mode only when there's a
  2282.     conflict with some other program, or operating system.
  2283.  
  2284.        -xf       Switch full 16K of Interface I ROM
  2285.  
  2286.     Useless.
  2287.  
  2288.  
  2289.  
  2290.  
  2291. 2.20  Miscellaneous remarks
  2292.  
  2293.  
  2294.     1. Problems at the Rom/Ram boundary
  2295.  
  2296.     There are a few Spectrum programs that have an odd stack pointer, and
  2297.     run over the ram/rom boundary, for instance Deep Strike, and Elite.
  2298.     This crashed version 1.45 of the emulator; the problem was circumvented
  2299.     somewhat in version 2.01, and has been removed in version 3: in most
  2300.     cases, a word read from or written to FFFF will be read or written as
  2301.     two bytes.  You can check this by typing CLEAR 65535: POKE 65535,0:
  2302.     RETURN in BASIC; this will lock up version 1.45 of the emulator, it
  2303.     will lock up version 2.01 if the 80386 is in virtual mode, and it will
  2304.     only crash the emulated Spectrum (as it should) on version 3.
  2305.  
  2306.     The check on FFFF is not done at every potentially problematic op-code,
  2307.     because this would make the emulator noticeably slower.  It is
  2308.     therefore still possible to 'hang' the emulator.  Not going to tell you
  2309.     how, though.  All existing programs seem to work okay now.
  2310.  
  2311.  
  2312.     2. Critical timings
  2313.  
  2314.     A few programs (the only examples known to me are Fireman and Thing,
  2315.     but there are more) are quite sensitive to the relative actual
  2316.     execution speed of emulated Z80 instructions, and crash if it isn't
  2317.     right.  They rely on this-or-that amount of instruction to be executed
  2318.     between interrupts.  If you slow down the emulator, these program will
  2319.     run fine, because then individual instructions are more carefully
  2320.     timed.  When running in Windows compatibility mode, loading .VOC files
  2321.     or when the Hi-Res Color emulation is switched on, these problems
  2322.     disappear completely as the emulator is then counting off the exact
  2323.     number of T states to elapse between interrupts.
  2324.  
  2325.  
  2326.     3. Shifted cursor keys
  2327.  
  2328.     It may be annoying to have to press Num-Lock every time you use the
  2329.     Spectrum 128 (because otherwise you'll have to use Shift with the
  2330.     cursor keys to move the menu bar).  To make the emulator press shift by
  2331.     default every time you use the PC cursor keys in '128 mode, use the
  2332.     switch -xs. If you press Num-Lock now (in '128 mode), the shift-key
  2333.     won't be pressed.  The 48K modes are not affected by this switch.
  2334.  
  2335.  
  2336.     4. Running non-standard ROMs
  2337.  
  2338.     To run the emulator with a different rom than the standard one, you can
  2339.     specify a rom image file on the command line.  Use the switch -xr file,
  2340.     where 'file' is the name of the image file.  This file should be
  2341.     exactly 16384 bytes long.  It will of course not be used in Spectrum
  2342.     128 or SamRam mode.
  2343.  
  2344.     The emulator 'ZX' by Rindt and Bruckner comes with several roms, stored
  2345.     in their tape format.  You can convert these files to .TAP files, and
  2346.     then load them in the normal way (in RAM), and then save the 16K image
  2347.     from RAM directly.  You can also extract it from the files directly by
  2348.     using the DOS debug utility:
  2349.  
  2350.         C:\>debug rom.000       (or other rom file (of 16406 bytes))
  2351.         -m 115 L 4000,100       (move the rom down, overwrite header)
  2352.         -rcx                    (new length of exactly 16K bytes)
  2353.         CX 4016
  2354.         4000
  2355.         -n rom000.bin           (or some other name)
  2356.         -w                      (write it)
  2357.         Writing 04000 bytes
  2358.         -q                      (and quit)
  2359.  
  2360.  
  2361.     5. Printing with DISCiPLE and Plus D
  2362.  
  2363.     If, emulating a DISCiPLE/+D and by entering POKE @11,0 the parallel
  2364.     printer output has been selected, going back to a hardware mode without
  2365.     M.G.T. interface causes problems with printing to the ZX Printer, since
  2366.     the output addresses of the "p" channel have been changed by the M.G.T.
  2367.     ROM.  Use the "b" channel of the Interface I instead.  You can reset
  2368.     the channel to the ZX Printer by entering POKE @11,1 while still
  2369.     emulating the M.G.T. interface.
  2370.  
  2371.     Although by default channel #3 prints to the ZX Printer, in all
  2372.     hardware modes, if a DISCiPLE/+D is emulated output to the ZX Printer
  2373.     is ignored, as these interfaces use the ZX Printer I/O ports for their
  2374.     own purposes.
  2375.  
  2376.  
  2377.     6. ZX Printing
  2378.  
  2379.     When converting ZX Printer output for either Epson or HP-PCL printers,
  2380.     the emulator does not check whether the printer is on-line or not; this
  2381.     is left to the BIOS.  The result is that, when it is off-line (or when
  2382.     there is no printer connected at all to the specified port) the
  2383.     emulator may seem to hang.  Make sure to have specified the right
  2384.     output port with -xl N, and the right output format with either -0h or
  2385.     -0e.  See the default Z80.INI file.
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.  
  2392. 3.  THE SAMRAM
  2393.  
  2394.  
  2395.  
  2396.  
  2397. 3.1  Basic extensions
  2398.  
  2399.  
  2400.     The SamRam is a hardware device Johan and I built for our Spectrums. It
  2401.     consists of a 32K static RAM chip which contains a modified copy of the
  2402.     normal Basic ROM and a number of other useful routines, like a monitor
  2403.     and snapshot software.  You can compare it to a Multiface I interface,
  2404.     but it's more versatile.  Another useful feature was a simple hardware
  2405.     switch which allowed use of the shadow 32K Ram, present at 8000-FFFF in
  2406.     most Spectrums, but hardly ever actually used.
  2407.  
  2408.     For more details on the low-level hardware features of the SamRam read
  2409.     chapter 5.  In this chapter I'll explain the software features of the
  2410.     SamRam software, somewhat bombastically called the 'SamRam 32 Software
  2411.     System' or the 'Sam Operating System'.  By the way, all similarity
  2412.     between existing computers is in fact purely coincidental and has in no
  2413.     way been intended.  Really!
  2414.  
  2415.     The SamRam offers a few new Basic commands, and a lot of useful
  2416.     routines that are activated by an NMI, i.e.  by pressing F5.  First
  2417.     I'll discuss the Basic extension.
  2418.  
  2419.     Select the SamRam by starting the emulator with the -s switch, or by
  2420.     selecting it from the F9 menu.  Normal Basic functions as usual; the
  2421.     character set is different from the original one.  There are four new
  2422.     commands: *RS, *MOVE, *SAVE and *SPECTRUM, and two new functions, DEC
  2423.     and HEX, which have replaced ASN and ACS.  DEC takes a string argument
  2424.     containing a hexadecimal number, and returns the decimal value of it.
  2425.     HEX is the inverse of the DEC function, and yields a four-character
  2426.     string.
  2427.  
  2428.     *RS sends its arguments directly to the RS232 channel.  You don't have
  2429.     to open a "b" or "t" channel first.  You're right, it's of limited use.
  2430.     Example: *RS 13,10
  2431.  
  2432.     *MOVE is useful: it moves a block of memory to another place.  Example:
  2433.     *MOVE 50000,16384,6912 moves a screen-sized block from 50000 to the
  2434.     start of the screen memory.
  2435.  
  2436.     *SAVE works like *MOVE, except that it activates the shadow SamRam ROM
  2437.     before moving.  I used this command to update the shadow ROM, but on
  2438.     the emulator you can use it to move the shadow ROM to a convenient
  2439.     place in Ram where you can take a look at it, for instance by executing
  2440.     *SAVE 0,32768,16384.
  2441.  
  2442.     *SPECTRUM resets the SamRam Spectrum to a normal one.  You lose all
  2443.     data in memory.  By resetting the emulator by pressing ALT-F5, the
  2444.     SamRam is activated again.  Not very useful either.
  2445.  
  2446.     Then there's the Ramdisk, which is, like the Spectrum 128 ramdisk,
  2447.     accessed via the SAVE!, LOAD!, CAT!, ERASE! and FORMAT!.  The syntax is
  2448.     straightforward.  FORMAT! and CAT! need no parameters; ERASE! only
  2449.     needs a name.  If a file is not found, the SamRam will respond with a
  2450.     5-End of File error.  The Ramdisk has a capacity of 25K.
  2451.  
  2452.  
  2453.  
  2454.  
  2455. 3.2  The NMI software
  2456.  
  2457.  
  2458.     Select the SamRam (F9-3), and press F5.  A menu with eight icons pops
  2459.     up.  You can select each icon by moving the arrow to it (using the
  2460.     cursor keys or the Kempston joystick), and pressing '0' or fire.  The
  2461.     icons can also be selected by pressing the appropriate letter key.
  2462.  
  2463.     The eight icons are two arrows with N and E within them, a magnifying
  2464.     glass with the letters 'mc' in it (activated by pressing D), two
  2465.     screens (identified by 1 and 2), a printer (P), a cassette (S) and a
  2466.     box saying 'overig'.  The 'D' activates the monitor or disassembler;
  2467.     read section 3.3 for information on this program.
  2468.  
  2469.     Pressing N or E returns you to the Spectrum.  If you pressed N, the
  2470.     normal Spectrum rom will be selected when the NMI software returns; if
  2471.     you press E, the Rom with the Basic extensions will be selected.  Some
  2472.     games may crash if they see a different rom than the standard Spectrum
  2473.     one.
  2474.  
  2475.     Pressing 1 selects the tiny screen editor.  You can move a '+' shaped
  2476.     cursor about the screen using the cursor keys.  The following commands
  2477.     are available:
  2478.  
  2479.         H: Get the current ATTR color from the screen at the cursor's
  2480.            current position, and store it in memory.  This color will be
  2481.            used by the next command:
  2482.         Z: Put the color on the screen
  2483.         G: Get a character from the screen
  2484.         P: Put the character on the screen
  2485.         R: Remove all screen data that is invisible by the ATTR color
  2486.         L: Take a look at the bitmap below the ATTR color codes
  2487.         T: Return to the main menu.  You can also return by pressing
  2488.            EDIT, or ESC in the emulator.
  2489.         B: Change border color
  2490.         V: Clear the whole screen
  2491.  
  2492.     If you press 0, you can edit the current 8x8 character block at pixel
  2493.     level.  Again you control the cursor with the cursor keys.  Now 0
  2494.     toggles a pixel.  In this mode there are two commands: C clears the
  2495.     whole block, and I inverts it.  Pressing EDIT (ESC) returns you to the
  2496.     big screen again.
  2497.  
  2498.     The SamRam has two screen buffers.  Buffer 1 is used to hold the screen
  2499.     which was visible when you pressed NMI, to be able to restore it when
  2500.     returning.  This is the screen you edit with '1'.  The second screen
  2501.     buffer can be used to hold a screen for some time; it is not touched by
  2502.     the NMI software directly, and will not even be destroyed by a Reset.
  2503.     If you press '2', a menu appears with four Dutch entries:
  2504.  
  2505.         1: Scherm 1 opslaan        (Store screen 1 into buffer 2)
  2506.         2: Scherm 2 veranderen     (Edit screen 2)
  2507.         3: Schermen verwisselen    (Swap screens)
  2508.         4: Scherm 2 weghalen       (Remove screen 2)
  2509.  
  2510.     These four functions are rather obvious, I believe.
  2511.  
  2512.     Pressing 'P' pops up the printer menu.  The screendump program is
  2513.     written specifically for my printer, a Star SG-10.  It will probably
  2514.     work on some other printers, but not on most.  The output is sent to
  2515.     the RS232 channel, so you have to redirect it to an LPT output.
  2516.  
  2517.     Skipping the most interesting, 'S', for a moment, let's first discuss
  2518.     the final menu, 'O' for 'Overig', Dutch for miscellaneous.  There are
  2519.     five menu options, of which three are not useful.  The first gives a
  2520.     directory of the cartridge currently in Microdrive 1.  The last, 'E',
  2521.     returns you to Basic if this is anywhere possible: it resets some
  2522.     crucial system variables and generates a Break into Program.  You can
  2523.     use this for instance to break in a BEEP, or crack a not-so-very-well-
  2524.     protected program.  The three other options select normal or speed-
  2525.     save, and store the current setting in CMOS Ram.  Speed-save won't work
  2526.     properly on the emulator, because the speed-save routine toggles the
  2527.     upper 32K ram bank regularly, and this takes too much time on the
  2528.     emulator.  The setting is not important if you use the internal save
  2529.     routine (which will be used by default, unless you select Real Mode).
  2530.  
  2531.     Finally, the 'S' option.  This option allows you to save a snapshot to
  2532.     tape or microdrive.  I used it a lot on my real Spectrum, and it works
  2533.     just as well on the emulator.  It is very useful is you want to load a
  2534.     .Z80 program back into a real Spectrum again.  There are three
  2535.     'switches' you can toggle.  The active choice is indicated by a bright
  2536.     green box, inactive boxes are non-bright.  You have to use EGA or VGA
  2537.     to be able to see it...  The first switch lets you select whether the
  2538.     SamRam rom should be active if the program loads or not.  This is only
  2539.     meaningful is you load it back in a SamRam again.  Usually I want the
  2540.     SamRam rom to be active because I like the character set better.  The
  2541.     second switch indicates whether the SamRam should save a 'loading
  2542.     screen', which it takes from screen buffer 2.  If screen buffer 2
  2543.     contains a screen, this switch will by default be on.  Finally, the
  2544.     last switch lets you select the output media, tape or cartridge.
  2545.  
  2546.     If the program is loaded back into the SamRam, the only bytes that have
  2547.     been corrupted are four bytes down on the stack; this will virtually
  2548.     never be any problem.  If the program is loaded back to a normal
  2549.     Spectrum, these four bytes will also be corrupted, and the bottom two
  2550.     pixel lines of the screen will be filled with data.  (This is
  2551.     considerably less than any other snapshotter I've seen: for instance
  2552.     the Multiface I uses more than 35% of the screen!)
  2553.  
  2554.     The Microdrive BASIC loader needs code in the SamRam rom to start the
  2555.     program (the RANDOMIZE USR 43 calls it).  It won't be very difficult to
  2556.     write a standard BASIC loader that doesn't need this code, but I don't
  2557.     think many people desperately need it...  Anyway, using the Multiface
  2558.     128 you can write a compressed snapshot to cartridge which doesn't need
  2559.     the Multiface.
  2560.  
  2561.  
  2562.  
  2563.  
  2564. 3.3  The built-in monitor
  2565.  
  2566.  
  2567.     This is a really very convenient part of the emulator, and I use it a
  2568.     lot.  It is very MONS-like in its commands and visual appearance.  It
  2569.     cannot single-step however, but on the positive side it has some
  2570.     features MONS hasn't.  It is a part of the SamRam, and cannot therefore
  2571.     be used with Spectrum 128 programs.  If you want to take a look at a
  2572.     Spectrum 128 program, press F10, then change the hardware to SamRam
  2573.     without resetting, and finally generate an NMI in the Extra Functions
  2574.     menu.  You won't probably be able to continue to run the program, but
  2575.     at least you're able to see what it was doing.
  2576.  
  2577.     Press F5 for NMI, and D to enter the monitor/disassembler.  The first
  2578.     eight lines are the first eight instructions, starting at the Memory
  2579.     Pointer, from here on abbreviated by MP.  At first, MP is zero.  The
  2580.     disassembler knows all official instructions, and the SLL instruction.
  2581.     If another inofficial instruction (i.e.  starting with DD, FD or ED) is
  2582.     encountered, the first byte is displayed on a blank line.  The four
  2583.     lines below these display the value of PC and SP, the first nine words
  2584.     on the stack (including AF and the program counter, which have been
  2585.     pushed during NMI), and three MP-memories.  These can be used for
  2586.     temporary storage of the MP, for instance when you take a look at the
  2587.     body of a CALL, and want to return to the main procedure later.
  2588.  
  2589.     The bottom part of the screen displays 24 bytes around the memory
  2590.     pointer.
  2591.  
  2592.     Commands are one letter long; no ENTER needs to be given.  If one or
  2593.     more operands are needed, a colon will appear.  By default the monitor
  2594.     accepts hexadecimal input.  A leading $ denotes that the number is to
  2595.     be regarded as decimal.  If you give the # command, the default will
  2596.     toggle to decimal, and you need to explicitly put a # in front of a
  2597.     number which is to be interpreted as a hex number.  Also, after the #
  2598.     command all addresses on screen will be decimal.  A single character
  2599.     preceded by the " symbol evaluates to its ASCII code, and the single
  2600.     character M will evaluate to the current value of the memory pointer.
  2601.  
  2602.     The monitor commands:
  2603.  
  2604.         Q: Decrease the memory pointer by one.  You effectively shift one
  2605.            byte up.
  2606.         A: Increase the memory pointer, shifting one byte down.
  2607.         ENTER: Shift one instruction down: the memory pointer is
  2608.            increased by the length of first instruction displayed on
  2609.            screen.
  2610.         M: Change the value of the memory pointer.  For instance, M:M
  2611.            won't change it.
  2612.         P: Put.  The word operand supplied will be stored in the first MP
  2613.            memory, and the others will shift on place to the right.
  2614.            Usually, you'll want to store the memory pointer by P:M
  2615.         G: Get.  Typing G:1, G:2 or G:3 moves the value of one of the MP
  2616.            memories to the MP.
  2617.         B: Byte.  This command needs a byte operand; it will be poked
  2618.            into memory, and the memory pointer will move one up.
  2619.         I: Insert.  The same as B, except that you can poke more than one
  2620.            byte.  It continues to ask for bytes to poke until you type
  2621.            Enter on a blank line.
  2622.         #: Toggles the default number base between hexadecimal and
  2623.            decimal.
  2624.         F: Find.  You can enter up to ten bytes, which will be searched
  2625.            through memory.  Searching will stop at address 0, because
  2626.            since the search string is stored in shadow Ram, searching
  2627.            would otherwise not always terminate.  Typing Enter on a blank
  2628.            line starts the search.  Byte operands are entered as usual,
  2629.            but:
  2630.            - If a number bigger than 256 decimal is entered, it is
  2631.              treated as a word in the standard LSB/MSB format.  So, 1234
  2632.              will search for 34,12 hex in that order.  Note that 0012
  2633.              will search for 12, not 12,00.
  2634.            - A line starting with " decodes into the string of characters
  2635.              (up to ten) behind it.  Normally this would only be the
  2636.              first character.  So instead of typing "M "Y "N "A "M "E
  2637.              (space=enter here) you type "MYNAME.  Note that any
  2638.              terminating " will also be searched for!
  2639.            - An x is treated as a wildcard.  So if you search for CD x 80
  2640.              any call to a subroutine in the block 8000-80FF is a hit.
  2641.              If you search for x 8000, you'll see every one-byte
  2642.              instruction that has the address 8000 as operand.
  2643.         N: Continues the search started by F from the current MP.
  2644.         $: Displays one page of disassembly on screen.  In this mode,
  2645.            the following commands are possible:
  2646.            $: Back to the main screen
  2647.            7: [Shift 7 also works, cursor up]: Go to the previous page.
  2648.               The monitor stores the addresses of the previous eight
  2649.               pages only.
  2650.            Q: Go back one byte (decrease MP by one)
  2651.            A: Go one byte forward (increase MP by one)
  2652.            Z: Dump this screen to the printer, in ASCII format.  Redirect
  2653.               the RS232 output to a file, and run CONVERT on it to convert
  2654.               the CR's into CR/LF's before printing (or tell your printer
  2655.               to do the conversion).
  2656.            Every other key displays the next page of disassembly.
  2657.         K: List.  The same mode as with $ is entered, but instead of a
  2658.            disassembly the bytes with their ASCII characters are
  2659.            displayed.  Useful to look for text.
  2660.         C: Clear.  Fills blocks of memory with a specified value.  The
  2661.            monitor prompts with 'First', 'Last' and 'With'.  The 'Last'
  2662.            address is inclusive!
  2663.         D: Dump.  Prompts with 'First' and 'Last', and dumps a
  2664.            disassembly of the block between these addresses to the
  2665.            printer.  See remark at $-Z.  The 'Last' address is again
  2666.            inclusive.
  2667.         R: Registers.  If you press Enter after R, an overview of the
  2668.            registers contents is displayed.  If you type one of A,B,C,D,
  2669.            E,H,L,A',B',C',D',E',H',L',I,R,AF,BC,DE,HL,AF',BC',DE',HL',
  2670.            IX,IY,SP or PC, you can change the value of it.  Changing the
  2671.            value of SP also changes the PC and AF values by the way.  You
  2672.            cannot change the Interrupt mode or IFF.
  2673.         V: Verplaats.  (Move).  Prompts with 'From', 'To' and 'Length'.
  2674.            Obvious.
  2675.         S: Save.  Enter the start of the block you wish to save first.
  2676.            The monitor then prompts with 'Length'.  The block is saved
  2677.            without a header, as a normal data block (A, the flagbyte, is
  2678.            0FF)
  2679.         L: Load.  Loads a block of data from tape, at the specified
  2680.            address.  Normal data blocks, headers and blocks with non-
  2681.            standard flag bytes can be loaded.  The first byte in memory
  2682.            will contain the flag byte.  If the checksum isn't 0 after
  2683.            loading, indicating a tape error, you'll hear a beep.
  2684.         H: Header read.  Loads headers and displays the contents on
  2685.            screen.
  2686.  
  2687.  
  2688.     As you're reading this part, I assume you know something of machine
  2689.     code.  Probably you would be interested in peeking into the software of
  2690.     the SamRam, the Interface I, the Spectrum 128, the Disciple or the
  2691.     Multiface 128.  You'll first have to move these roms in ram to be able
  2692.     to look at them with the monitor.
  2693.  
  2694.     The Interface I rom can be moved into ram by saving it to microdrive or
  2695.     to the "b" channel, with SAVE *"m";1;"rom" CODE 0,8192 or SAVE *"b"
  2696.     CODE 0,8192, and loading it back again at 32768 for instance.  You can
  2697.     also put this small machine code routine at 23296 and run it: F3 21 0C
  2698.     5B E5 21 00 00 E5 C3 08 00 21 00 00 11 00 80 01 00 20 ED B0 FB C3 00
  2699.     07.
  2700.  
  2701.     The two SamRam roms are easy.  The first you don't need to transfer;
  2702.     the monitor looks at the extended basic rom by default.  The second rom
  2703.     can be moved to 32768 by typing *SAVE 0,32768,16384.  (The SAVE is not
  2704.     the keyword SAVE!)
  2705.  
  2706.     The first '128 rom, the one which is active at reset and contains most
  2707.     of the new code, is moved up by typing SAVE!"rom"CODE 0,16384, then
  2708.     LOAD!"rom"CODE 32768.  The other rom is most conveniently moved by
  2709.     saving it to a .TAP file and loading it back again in ram.  To select
  2710.     the SamRam type SPECTRUM first, and then switch the hardware without
  2711.     resetting.
  2712.  
  2713.     The Disciple and Plus D roms can be transferred to RAM by simply saving
  2714.     them to disk and loading them back at say 32768.
  2715.  
  2716.     The Multiface ROM is paged by an IN from 191, and paged out again by
  2717.     INning from address 63.  Don't forget to disable interrupts in between,
  2718.     I'm not sure whether the M128 has a well-behaved interrupt routine.
  2719.     ROM is from 0-8191, RAM on top of that.
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725.  
  2726. 4.  THE SPECTRUM
  2727.  
  2728.  
  2729.  
  2730.  
  2731. 4.1  The Spectrum
  2732.  
  2733.  
  2734.     This emulator supports the Interface I, the Multiface 128, the DISCiPLE
  2735.     and Plus D interfaces, and the Spectrum 128.  Many Spectrum users will
  2736.     have no experience with them, so some comments may be useful.  On the
  2737.     other hand, I don't think this is the right place to describe the
  2738.     Spectrum Basic in full detail.  If you want to know it all, read the
  2739.     official manuals!  Information on the Multiface 128 can be found in
  2740.     section 2.12.
  2741.  
  2742.     If you want to use Spectrum Basic, you will need the keywords.  You
  2743.     could by the way now also use the Spectrum 128 Basic where you can type
  2744.     the keywords in by full.
  2745.  
  2746.     If you press ALT-F1 in the emulator, the Spectrum keyboard layout will
  2747.     appear.  For completeness I include an alphabetical list of all
  2748.     keywords and their key-combination.  In the list below, K stands for
  2749.     Keyword mode, E for E-mode (type Shift-Alt of Shift-Ctrl to select
  2750.     E-mode), S for Symbol Shift, and SE for Symbol Shifted (Alt/Ctrl)
  2751.     E-mode: select E mode and type the letter while depressing Symbol
  2752.     Shift.
  2753.  
  2754.  
  2755.         Keyw.    Code | Keyw.    Code | Keyw.    Code | Keyw.    Code
  2756.  
  2757.         ABS      E g    DRAW     K w    MERGE    SE t   SAVE     K s
  2758.         ACS      SE w   ERASE    SE 7   MOVE     SE 6   SCREEN$  SE k
  2759.         AND      S y    EXP      E x    NEW      K a    SGN      E f
  2760.         ASN      SE q   FLASH    SE v   NEXT     K n    SIN      E q
  2761.         AT       S i    FN       SE 2   NOT      S s    SQR      E h
  2762.         ATN      SE e   FOR      K f    OPEN #   SE 4   STEP     S d
  2763.         ATTR     SE l   FORMAT   SE 0   OR       S u    STOP     S a
  2764.         BEEP     SE z   GO SUB   K h    OUT      SE o   STR$     E y
  2765.         BIN      E b    GO TO    K g    OVER     SE n   TAB      E p
  2766.         BORDER   K b    IF       K u    PAPER    SE c   TAN      E e
  2767.         BRIGHT   SE b   IN       SE i   PAUSE    K m    THEN     S g
  2768.         CAT      SE 9   INK      SE x   PEEK     E o    TO       S f
  2769.         CHR$     E u    INKEY$   E n    PI       E m    USR      E l
  2770.         CIRCLE   SE h   INPUT    K i    PLOT     K q    VAL      E j
  2771.         CLEAR    K x    INT      E r    POINT    SE 8   VAL$     SE j
  2772.         CLOSE #  SE 5   INVERSE  SE m   POKE     K o    VERIFY   SE r
  2773.         CLS      K v    LEN      E k    PRINT    K p    <=       S q
  2774.         CODE     E i    LET      K l    RANDOMIZE K t   >=       S e
  2775.         CONTINUE K c    LIST     K k    READ     E a    <>       S w
  2776.         COPY     K z    LINE     SE 3   REM      K e
  2777.         COS      E w    LLIST    E v    RESTORE  E s    DEC      SE q
  2778.         DATA     E d    LN       E z    RETURN   K y    HEX      SE w
  2779.         DEF FN   SE 1   LOAD     K j    RND      E t
  2780.         DIM      K d    LPRINT   E c    RUN      K r
  2781.  
  2782.  
  2783.         Character  Spectrum kbrd   On PC keyboard
  2784.  
  2785.         &          S 6             ALT (or CTRL) 6
  2786.         '          S 7             ALT 7 or '/"
  2787.         (          S 8             ALT 8
  2788.         )          S 9             ALT 9
  2789.         _          S 0             ALT 0 or SHFT _/-
  2790.         <          S r             ALT r or SHFT </,
  2791.         >          S t             ALT t or SHFT >/,
  2792.         ;          S o             ALT o or :/;
  2793.         "          S p             ALT p or SHFT "/'
  2794.         ^          S h             ALT h
  2795.         -          S j             ALT j or _/-
  2796.         +          S k             ALT k or SHFT +/= or GREY +
  2797.         =          S l             ALT l or +/=
  2798.         :          S z             ALT z or SFHT :/;
  2799.         ?          S c             ALT c or SHFT ?//
  2800.         /          S v             ALT v or ?//
  2801.         *          S b             ALT b or GREY PRTSC/*
  2802.         ,          S n             ALT n or </,
  2803.         .          S m             ALT m or >/.
  2804.  
  2805.  
  2806.  
  2807.  
  2808. 4.2  The Interface I
  2809.  
  2810.  
  2811.     If you want to use the microdrive, you'll need cartridge files.  The
  2812.     emulator can create an empty cartridge file for you.  You have to
  2813.     format it before you can use it.  Type
  2814.  
  2815.         FORMAT "m";1;"name"
  2816.  
  2817.     to format the cartridge currently in Microdrive 1 giving it the name
  2818.     'name'.  Next, type CAT 1 to get a catalogue of the files on it (none
  2819.     of course) and the number of kilobytes free.  You can save a file by
  2820.     typing for instance
  2821.  
  2822.         SAVE *"m";1;"screen"SCREEN$
  2823.  
  2824.     Instead of SCREEN$ you can use all other expressions that are permitted
  2825.     also when saving to tape, like LINE nnnn or CODE x,y etcetera.  To load
  2826.     a file back from cartridge, you type (you guessed it)
  2827.  
  2828.         LOAD *"m";1;"screen"SCREEN$
  2829.  
  2830.     If the file doesn't exist or is of the wrong type you'll get the
  2831.     appropriate error message.  To erase a file, type for instance
  2832.  
  2833.         ERASE "m";1;"screen"
  2834.  
  2835.     Note that no * is needed (or even permitted), and that only the name
  2836.     should be given.  There's another way to create a file on a cartridge,
  2837.     and that is by using a command like OPEN #3;"m";1;"name", and printing
  2838.     to that stream.  You can use MOVE to move data from stream to stream,
  2839.     but I'll not go into that --- it's not very much used anyway.
  2840.  
  2841.     Instead of to the microdrive, you can also 'save to the RS232 link'.
  2842.     For instance, type SAVE *"b"SCREEN$ (note: there's no name!) to save a
  2843.     screen.  On the emulator you can send the output to the RS232 channel
  2844.     to a printer (then SAVE *"b" is useless), to a file (can be useful) or
  2845.     to the COM port (very useful if you connect a real Spectrum to the PC's
  2846.     COM port!).  You can load the data back by typing LOAD *"b"SCREEN$ and
  2847.     making sure the RS232 channel is fed with the right input (from a COM
  2848.     port or a file).  See also section 2.13.
  2849.  
  2850.     If you want to use the RS232 channel for printing, open stream 3 for
  2851.     output to that channel by typing
  2852.  
  2853.         OPEN #3,"b"
  2854.  
  2855.     or
  2856.  
  2857.         OPEN #3,"t"
  2858.  
  2859.     The first will simply copy everything you send to stream 3 (using for
  2860.     instance LPRINT or LLIST) to the RS232 channel; the second converts
  2861.     CR's into CR/LF's, breaks off lines at 80 characters and translates
  2862.     keywords into character sequences.  "t" is useful for LLISTings, but
  2863.     not for anything else.
  2864.  
  2865.     Useful extra commands: CLS #, to clear the screen and reset the
  2866.     attributes to their reset defaults, and CLEAR # to do a CLS # and close
  2867.     all currently open streams (discarding all data that may still be
  2868.     buffered!)
  2869.  
  2870.     The Interface I uses its own system variables.  At the first error
  2871.     message you make (or RASP, or flashing question mark) and at the first
  2872.     Interface I statement you execute, it inserts them automatically.  Some
  2873.     programs will not run when the Interface I has inserted its system
  2874.     variables.  So if you load a game from tape, reset the Spectrum first
  2875.     and don't make an error typing LOAD "".  With a bit of exercise you
  2876.     should be able to do this.
  2877.  
  2878.  
  2879.  
  2880.  
  2881. 4.3  The DISCiPLE and Plus D Interfaces - Introduction
  2882.  
  2883.  
  2884.     The DISCiPLE and Plus D were two disk interfaces for the spectrum
  2885.     designed by M.G.T. (Miles Gordon Technology).  The first of these
  2886.     interfaces was the DISCiPLE, this interface consisted of a disk
  2887.     interface, microdrive network compatible interface, parallel printer
  2888.     interface, 2 joystick ports (emulating kempston, cursor, and Sinclair 1
  2889.     and 2).  The unit also had an inhibit button which disabled the
  2890.     interface hardware (except the joystick ports), and finally a snapshot
  2891.     button which when pressed stopped the computer to allow the program to
  2892.     be saved to disk or the screen to be printed.  This was made by
  2893.     Rockfort.
  2894.  
  2895.     The Plus D was the second of the interfaces, this was a cut-down
  2896.     version of the DISCiPLE, this interface only had a disk interface,
  2897.     parallel printer interface and a snapshot button.
  2898.  
  2899.     Both interfaces had a D.O.S. (Disk Operating System) which was partly
  2900.     ROM (8K) and partly RAM (8K).  When the spectrum was turned on, the ROM
  2901.     part of the D.O.S. was in control and whenever the command RUN was
  2902.     issued the ROM tries to load up the RAM part of the D.O.S. from floppy
  2903.     disk.  The advantage of this is that the D.O.S. can be upgraded without
  2904.     having to change chips over (unless of course it was a major upgrade!).
  2905.     Another advantage was that D.O.S. extensions could be incorporated or
  2906.     replace other systems (see later).
  2907.  
  2908.     With both interfaces, they extended the BASIC commands, but unlike the
  2909.     microdrives and several other types of drives available, the DISCiPLE
  2910.     and Plus D took up none of the spectrum's RAM, therefore it was the
  2911.     most invisible of the disk systems available, not only that, but the
  2912.     DISCiPLE and Plus D used the same type of disk drives as the BBC micro,
  2913.     therefore disk drives were both cheap and widely available, also the
  2914.     disks themselves were also standard, ie 5.25" (800K DS/DD), then later
  2915.     3.5" (800K DS/DD).
  2916.  
  2917.     The ROM of the DISCiPLE is supplied with the emulator, together with
  2918.     two version of the D.O.S. pre-loaded in RAM.  The ROM of the Plus D
  2919.     interface is not supplied, for copyright reasons.  The emulator will
  2920.     only emulate a Plus D interface if it can find a file PLUSDROM.BIN in
  2921.     the emulator's own directory.  If you have a Plus D yourself, you can
  2922.     transfer the ROM in the following way.  Load the operating system from
  2923.     a Plus D system diskette, and save the entire ROM, together with the
  2924.     operating system, to disk by entering SAVE d1"rom" CODE 0,16384.  Then,
  2925.     start the emulator and choose hardware mode Spectrum 48K + Disciple
  2926.     (not Plus D of course), then type LOAD d1"rom" CODE 32768.  Finally,
  2927.     press F10, X, S for Save Data block, set start address and length to
  2928.     8000 and 4000 (hexadecimal) respectively, and save the ROM under the
  2929.     name PLUSDROM.BIN.  If you re-start the emulator now, it will emulate
  2930.     the Plus D too.
  2931.  
  2932.  
  2933.  
  2934.  
  2935. 4.4  The DISCiPLE and Plus D Interfaces - The basic commands
  2936.  
  2937.  
  2938.     There are several levels of commands that can be used, these range from
  2939.     the most straightforward everyday use, to the more advanced, programmer
  2940.     type commands.
  2941.  
  2942.     I will first explain the most common commands, so that you can quickly
  2943.     and easily access DISCiPLE and Plus D disks.  Where a 1 is used in the
  2944.     following commands 2 could be used instead.  These commands are:-
  2945.  
  2946.      RUN -   when no D.O.S. (system file) is loaded it will cause this to
  2947.              be loaded. Otherwise it will just run the BASIC PROGRAM.  Please
  2948.              note that with the emulator the system file is already loaded,
  2949.              therefore this command is not required, although I have
  2950.              explained it for completeness.
  2951.  
  2952.      CAT 1 - will display a longhand catalogue of the disk drive selected.
  2953.              The form of this catalogue is as follows:-
  2954.  
  2955.                     program no., program name, sectors used, file type,
  2956.                     file size
  2957.  
  2958.      CAT * - will display a longhand catalogue of the currently selected disk
  2959.              drive in the same form as described above.
  2960.  
  2961.      CAT 1! - displays a shorthand catalogue of the disk drive selected.
  2962.               This catalogue consists of a 3 column list of the filename of
  2963.               the programs.
  2964.  
  2965.      CAT *! - displays a shorthand catalogue of the current disk drive.
  2966.  
  2967.      LOAD pn - p - letter p, n - number between 1 & 80.  This is the program
  2968.                number of the file on the disk, the program number is the
  2969.                number printed before the name in the longhand catalogue.
  2970.  
  2971.      LOAD d1"name" - load from drive 1 the program called name
  2972.  
  2973.      LOAD d*"name" - load from the current drive the program called name
  2974.  
  2975.      LOAD d1"name" S - load an 48K snapshot from drive 1 called name
  2976.  
  2977.      LOAD d1"name" K - load an 128K snapshot from drive 1 called name
  2978.  
  2979.      LOAD d1;a$ - load from drive 1 the program whose name is held in the
  2980.                   string a$
  2981.  
  2982.      LOAD d*;a$ - load from the current drive the program whose name is held
  2983.                   in the string a$
  2984.  
  2985.      FORMAT d1 -  format the disk in drive 1
  2986.  
  2987.  
  2988.  
  2989.  
  2990. 4.5  The DISCiPLE and Plus D Interfaces - More advanced commands
  2991.  
  2992.  
  2993.     In the previous section I explained enough of the commands so that you
  2994.     could get to use the floppy disks with DISCiPLE/Plus D software on. Now
  2995.     I am going to explain the commands that the more experienced user and
  2996.     those who want to do just a little bit more than just load the
  2997.     programs.
  2998.  
  2999.     First of all comes the simple commands of SAVE, MERGE, VERIFY and LOAD.
  3000.     All of these commands are the same as rge tape versions except that you
  3001.     have d1, d2 or d* after the LOAD, SAVE etc.  There are only two
  3002.     exceptions to this rule, the first is when you have a string for the
  3003.     filename, in this case the command becomes:-
  3004.  
  3005.              LOAD d1;n$ ....... etc
  3006.              LOAD d*;n$ ....... etc
  3007.  
  3008.     The second exception is actually an extension.  When you save a code
  3009.     block, you can actually get it to autorun when it is loaded by adding a
  3010.     third parameter to the SAVE command, e.g. if you had a code block from
  3011.     40000 to 45000 and the run address was 41023 and you wanted it to be
  3012.     called testcode to drive 1, you would save it as:-
  3013.  
  3014.              SAVE d1"testcode"CODE 40000,5001,41023
  3015.  
  3016.     Now for the extensions.
  3017.  
  3018.     Any sector on the disk may be loaded to any area of RAM from 16384 to
  3019.     65535-512. The sector may also be loaded into the RAM of the interface,
  3020.     however caution should be used at all times when doing this, as you may
  3021.     destroy the operating system or cause it to behave irrationally.
  3022.  
  3023.     The syntax of the command is:-
  3024.  
  3025.              LOAD @n,tr,sec,add
  3026.  
  3027.     Where:-
  3028.  
  3029.              n   = drive number, ie 1 or 2, note * may not be used!
  3030.              tr  = track number => 0->79=side 0, 128->207=side 1
  3031.              sec = sector number => 1->10 normally, may not be 0!  If you
  3032.                                     try and load a sector that is sector 0,
  3033.                                     then the operating system will crash!
  3034.  
  3035.     You may also save to disk in the same way, so if you wanted to write to
  3036.     Track 5, Side 0, Sector 3 with code from 32768 to 33279 to drive 1 you
  3037.     would type:-
  3038.  
  3039.              SAVE @1,5,3,32768
  3040.  
  3041.     To format a disk all you need to type is:-
  3042.  
  3043.              FORMAT d1       or       FORMAT d2
  3044.  
  3045.     This is not however as simple as it seems!  Although a disk formatted
  3046.     on the DISCiPLE/Plus D will work with the PC it does not work the other
  3047.     way round, i.e. a disk formatted on the PC with this emulator will not
  3048.     necessarily work on the DISCiPLE/Plus D. This is because of differences
  3049.     of the floppy disk controller chips.  With the PC, it puts a special
  3050.     byte at the beginning of each track to tell the controller whether the
  3051.     disk is Double Density or High Density, and the spectrum floppy disk
  3052.     controller does not understand this byte and therefore will not read
  3053.     the track!  If you find this otherwise, then please write and let us
  3054.     know about it.
  3055.  
  3056.     You can set some of the D.O.S. system variables using an extended POKE
  3057.     command. The syntax is:-
  3058.  
  3059.              POKE @address,value
  3060.  
  3061.     The address is the BASE address of the system variables of the
  3062.     interface concerned, the BASE address for each of the interfaces is
  3063.     different, but the address you use in the POKE command is the same.
  3064.  
  3065.  
  3066.  
  3067.  
  3068. 4.6  The DISCiPLE and Plus D Interfaces - The snapshot button
  3069.  
  3070.  
  3071.     The snapshot button is a button which is used to stop the processor
  3072.     from executing instructions and making it do something else. In the
  3073.     case of the DISCiPLE/PLUS D the button can do 5 different tasks
  3074.     initially. Later on I'll discuss how the fuctions can be altered so
  3075.     that it can do other tasks. Once these tasks are carried out, the
  3076.     processor is returned to it's original state and the program continues
  3077.     from where it left off from.
  3078.  
  3079.     There are 5 functions that can be carried out with the initial system
  3080.     file.
  3081.  
  3082.     To use the button, first you must get to a point in the program that
  3083.     you want to use the button at, then press the button on the emulator
  3084.     the snapshot button is F5 (NMI).  Once you do this the program will
  3085.     stop and the border of the computer will flash, this may also be
  3086.     accompanied with a buzzing noise on the speaker.  This is to tell you
  3087.     that the snapshot button has been activated.  The following functions
  3088.     can then be carried out:-
  3089.  
  3090.         1   - Print screen to printer in black/white screen size
  3091.         2   - Print screen to printer in grey scale A4 size
  3092.         3   - Snapshot screen to disk in SCREEN$ format
  3093.         4   - Snapshot program to disk in 48K SNAP format
  3094.         5   - Snapshot program to disk in 128K SNAP format
  3095.       SPACE - go back to program (ie if F5 was pressed by mistake)
  3096.  
  3097.     The printer options will print out to EPSON compatible printers,
  3098.     however the DISCiPLE code has been changed and it is now possible to
  3099.     print to HPGL printers (e.g. Deskjet and Laserjet printers).
  3100.  
  3101.     The Snapshot screen and snapshot 48K are very self explanatory and easy
  3102.     to use.
  3103.  
  3104.     The Snapshot 128K is slightly more complicated.  Once you select this
  3105.     option the disk drive will start up then after a slight pause the
  3106.     screen display may/may not change.  The border flashes again and you
  3107.     have to press y or n depending on whether the screen display changed or
  3108.     not.  If the screen stayed the same then press n, but if the screen
  3109.     changed type y.  This is because the 128K spectrum has 2 screens, and
  3110.     there is no way for the computer to determine which is being used by
  3111.     itself, therefore it needs the user's help.  After you press y or n the
  3112.     program will be saved onto disk.
  3113.  
  3114.     Seeing it is possible for you to load programs into the DISCiPLE/PLUS D
  3115.     RAM area it is possible to have these interfaces carry out other tasks.
  3116.     The snapshot button code is located in RAM, so you can therefore load a
  3117.     program into this part of the RAM and as soon as you press the snapshot
  3118.     button it will execute the new program.  There is one problem however,
  3119.     which is that the program must be written in assembly language and must
  3120.     also be compiled for running in that part of RAM, also it must take
  3121.     care of what it does because the SPECTRUM ROM is not paged in,
  3122.     therefore ROM calls are not easily carried out.
  3123.  
  3124.     There are several different commercial programs which use the snapshot
  3125.     button to carry out different tasks, some of these are:-
  3126.  
  3127.                         Snapshot compressing programs
  3128.                         Debugging tools
  3129.                         Cheat finders for games
  3130.                         Programs to allow snapshots back onto tape
  3131.  
  3132.     The list is endless, and if you are capable of writing a machine-code
  3133.     program and have the relevant information, then you too could write
  3134.     your own programs.
  3135.  
  3136.  
  3137.  
  3138.  
  3139. 4.7  The Spectrum 128
  3140.  
  3141.  
  3142.     The main new features of the Spectrum 128 are its larger memory, that
  3143.     can be used as a Ram drive in Basic, and music capabilities.
  3144.  
  3145.     The Ram drive is accessed via the LOAD!, SAVE!, ERASE! and CAT!
  3146.     commands.  They work as you would expect.  Examples:
  3147.  
  3148.         SAVE !"name"SCREEN$
  3149.         CAT!
  3150.         LOAD !"name"SCREEN$
  3151.         ERASE !"name"
  3152.  
  3153.     The 3 channel sound chip of the Spectrum 128 can be used in Basic with
  3154.     the PLAY command.  Example:
  3155.  
  3156.         PLAY "cde","efg","gAB"
  3157.  
  3158.     plays three chords.  You can program complex effects, melodies and
  3159.     rhythms with the play command; they require many commands in the three
  3160.     voice strings which I won't explain...  They are explained in the
  3161.     Spectrum 128's user guide.
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168. 5.  TECHNICAL INFORMATION
  3169.  
  3170.  
  3171.  
  3172.  
  3173. 5.1  The Spectrum
  3174.  
  3175.  
  3176.     In this section, the hardware of the 48K Spectrum is discussed.  At the
  3177.     end, a discussion on the video timings of the 128K Spectrum is also
  3178.     included.  In this section, 'Spectrum' by itself refers to the 48K
  3179.     machine.
  3180.  
  3181.     The Spectrum is at the hardware level a very simple machine.  There's
  3182.     the 16K ROM which occupies the lowest part of the address space, and
  3183.     48K of RAM which fills up the rest.  An ULA which reads the lowest 6912
  3184.     bytes of RAM to display the screen, and contains the logic for just one
  3185.     I/O port completes the machine, from a software point of view at least.
  3186.  
  3187.     Every even I/O address will address the ULA, but to avoid problems with
  3188.     other I/O devices only port FE should be used.  If this port is written
  3189.     to, bits have the following meaning:
  3190.  
  3191.  
  3192.         Bit   7   6   5   4   3   2   1   0
  3193.             ┌───┬───┬───┬───┬───┬───┬───┬───┐
  3194.             │   │   │   │ E │ M │   Border  │
  3195.             └───┴───┴───┴───┴───┴───┴───┴───┘
  3196.  
  3197.  
  3198.     The lowest three bits specify the border colour; a zero in bit 3
  3199.     activates the MIC output, and a one in bit 4 activates the EAR output
  3200.     (which sounds the internal speaker).  The real Spectrum also activates
  3201.     the MIC when the ear is written to; the emulator doesn't.  This is no
  3202.     problem; MIC is only used for saving, and when saving the Spectrum
  3203.     never sounds the internal speaker.  The upper three bits are unused.
  3204.  
  3205.     If port FE is read from, the highest eight address lines are important
  3206.     too.  A zero on one of these lines selects a particular half-row of
  3207.     five keys:
  3208.  
  3209.       IN:    Reads keys (bit 0 to bit 4 inclusive, in that order)
  3210.  
  3211.       #FEFE  SHIFT, Z, X, C, V            #EFFE  0, 9, 8, 7, 6
  3212.       #FDFE  A, S, D, F, G                #DFFE  P, O, I, U, Y
  3213.       #FBFE  Q, W, E, R, T                #BFFE  ENTER, L, K, J, H
  3214.       #F7FE  1, 2, 3, 4, 5                #7FFE  SPACE, SYM SHFT, M, N,
  3215.  
  3216.     A zero in one of the five lowest bits means that the corresponding key
  3217.     is being pressed.  If more than one address line is made low, the
  3218.     result is the logical AND of all single inputs, so a zero in a bit
  3219.     means that at least one of the corresponding keys are pressed.  For
  3220.     example, only if each of the five lowest bits of the result from
  3221.     reading from port 00FE (for instance by XOR A/IN A,(FE)) is one, no key
  3222.     is pressed.
  3223.  
  3224.     A final remark about the keyboard.  It is connected in a matrix-like
  3225.     fashion, with 8 rows of 5 columns, as is obvious from the above
  3226.     remarks.  Any two keys pressed simultaneously can be uniquely decoded
  3227.     by reading from the IN ports; however, if more than two keys are
  3228.     pressed decoding may not be uniquely possible.  For instance, if you
  3229.     press Caps shift, B and V, the Spectrum will think also the Space key
  3230.     is pressed, and react by giving the 'Break into Program' report.  This
  3231.     matrix behaviour is also emulated - without it, Zynaps for instance
  3232.     won't pause when you press 5,6,7,8 and 0 simultaneously.
  3233.  
  3234.     Bit 5 (value 64) of IN-port FE is the ear input bit.  When the line is
  3235.     silent, its value is zero, except in the early Model 2 of the Spectrum,
  3236.     where it was one.  When there is a signal, this bit toggles.  The
  3237.     Spectrum loading software is not sensitive to the polarity of this bit
  3238.     (which it definitely should not be, not only because of this model
  3239.     difference, but also because you cannot be sure the tape recorder
  3240.     doesn't change the polarity of the signal recorded!) Some old programs
  3241.     rely on the fact that bit 5 is always one (for instance Spinads); for
  3242.     these programs the emulator can mimic a Model 2 Spectrum.
  3243.  
  3244.     Bits 6 and 7 are always one.
  3245.  
  3246.     The ULA with the lower 16K of RAM, and the processor with the upper 32K
  3247.     RAM and 16K ROM are working independently of each other.  The data and
  3248.     address buses of the Z80 and the ULA are connected by small resistors;
  3249.     normally, these do effectively decouple the buses.  However, if the Z80
  3250.     wants to read of write the lower 16K, the ULA halts the processor if it
  3251.     is busy reading, and after it's finished it lets the processor access
  3252.     lower memory through the resistors.  A very fast, cheap and neat design
  3253.     indeed!
  3254.  
  3255.     If you run a program in the lower 16K of RAM, or read or write in that
  3256.     memory, the processor is halted sometimes.  This part of memory is
  3257.     therefore somewhat slower than the upper 32K block.  This is also the
  3258.     reason that you cannot write a sound- or save-routine in lower memory;
  3259.     the timing won't be exact, and the music will sound harsh.  Also,
  3260.     INning from port FE will halt the processor, because the ULA has to
  3261.     supply the result.  Therefore, INning from port FE is a tiny bit slower
  3262.     on average than INning from other ports; whilst normally an IN A,(nn)
  3263.     instruction would take 11 T states, it takes 12.15 T states on average
  3264.     if nn=FE. See below for more exact information.
  3265.  
  3266.     If the processor reads from a non-existing IN port, for instance FF,
  3267.     the ULA won't stop, but nothing will put anything on the data bus.
  3268.     Therefore, you'll read a mixture of FF's (idle bus), and screen and
  3269.     ATTR data bytes (the latter being very scarce, by the way).  This will
  3270.     only happen when the ULA is reading the screen memory, 61.5% (192/312)
  3271.     of the 1/50th second time slice in which a frame is generated.  The
  3272.     other 38.5% of the time the ULA is building the border or generating a
  3273.     vertical retrace.  This behaviour is actually used in some programs,
  3274.     for instance by Arkanoid, and Z80 also emulates this.
  3275.  
  3276.     Finally, there is an interesting bug in the ULA which also has to do
  3277.     with this split bus.  After each instruction fetch cycle of the
  3278.     processor, the processor puts the I-R register 'pair' (not the 8 bit
  3279.     internal Instruction Register, but the Interrupt and R registers) on
  3280.     the address bus.  The lowest 7 bits, the R register, are used for
  3281.     memory refresh.  However, the ULA gets confused if I is in the range
  3282.     64-127, because it thinks the processor wants to read from lower 16K
  3283.     ram very, very often.  The ULA can't cope with this read-frequency, and
  3284.     regularly misses a screen byte.  Instead of the actual byte, the byte
  3285.     previously read is used to build up the video signal.  The screen seems
  3286.     to be filled with 'snow'; however, the Spectrum won't crash, and
  3287.     program will continue to run normally.  There's one program I know of
  3288.     that uses this to generate a nice effect: Vectron.  (which has very
  3289.     nice music too by the way).  This effect has not been implemented
  3290.     however - it's a bit useless (but maybe I'll include it in the future).
  3291.  
  3292.     The processor has three interrupt modes, selected by the instructions
  3293.     IM 0, IM 1 and IM 2.  In mode 1, the processor simply executes a RST
  3294.     #38 instruction if an interrupt is requested.  This is the mode the
  3295.     Spectrum is normally in.  The other mode that is commonly used is IM 2.
  3296.     If an interrupt is requested, the processor first builds a 16 bit
  3297.     address by combining the I register (as the high byte) with whatever
  3298.     the interrupting device places on the data bus.  The processor then
  3299.     fetches the 16-bit address at this interrupt table entry, and finally
  3300.     CALLs the subroutine at that address.  Rodnay Zaks in his book
  3301.     'Programming the Z80' states that only even bytes are allowed as low
  3302.     index byte, but that isn't true.  The normal Spectrum contains no
  3303.     hardware to place a byte on the bus, and the bus will therefore always
  3304.     read FF (because the ULA also doesn't read the screen if it generates
  3305.     an interrupt), so the resulting index address is 256*I+0FF.  However,
  3306.     some not-so-neat hardware devices put things on the data bus when they
  3307.     shouldn't, so later programs didn't assume the low index byte was 0FF.
  3308.     These programs contain a 257 byte table of equal bytes starting at
  3309.     256*I, and the interrupt routine is placed at an address that is a
  3310.     multiple of 257.  A useful but not so much used trick is to make the
  3311.     table contain FF's (or use the ROM for this) and put a byte 18 hex, the
  3312.     opcode for JR, at FFFF.  The first byte of the ROM is a DI, F3 hex, so
  3313.     the JR will jump to FFF4, where a long JP to the actual interrupt
  3314.     routine is put.
  3315.  
  3316.     In interrupt mode 0, the processor executes the instruction that the
  3317.     interrupting device places on the data bus.  On a standard Spectrum
  3318.     this will be the byte FF, coincidentally (...) the opcode for RST #38.
  3319.     But for the same reasons as above, this is not really reliable.
  3320.  
  3321.     The 50 Hz interrupt is synchronized with the video signal generation by
  3322.     the ULA; both the interrupt and the video signal are generated by it.
  3323.     Many programs use the interrupt to synchronize with the frame cycle.
  3324.     Some use it to generate fantastic effects, such as full-screen
  3325.     characters, full-screen horizon (Aquaplane) or pixel colour (Uridium
  3326.     for instance).  Many modern programs use the fact that the screen is
  3327.     'written' (or 'fired') to the CRT in a finite time to do as much
  3328.     time-consuming screen calculations as possible without causing
  3329.     character flickering:  although the ULA has started displaying the
  3330.     screen for this frame already, the electron beam will for a moment not
  3331.     'pass' this-or-that part of the screen so it's safe to change something
  3332.     there. So the exact time in the 1/50 second time-slice at which the
  3333.     screen is updated is very important.  Normally the emulator updates the
  3334.     entire screen at once (50 times a second), and no best solution can be
  3335.     given as to when exactly the screen should be updated.  The user can
  3336.     select one of three possibilities (low, normal and high video
  3337.     synchronisation, corresponding to a screen update after 1/200, 2/200 or
  3338.     3/200 of a (relative) second after a Z80 interrupt) to try to get the
  3339.     best results.  Try for instance Zynaps; with normal video
  3340.     synchronisation the top four or five lines of the background move
  3341.     out-of-phase with the rest, and your space-ship flickers in that
  3342.     region.  With low video synchronisation the background moves smoothly
  3343.     but the sprites flicker in all parts of the screen.  Only with high
  3344.     video sync everything moves smoothly and doesn't flicker.
  3345.  
  3346.     In Hi-resolution color emulation mode, however, the emulator makes a
  3347.     copy of every screen- and attribute-line in a buffer at the exact time
  3348.     the ULA would display it.  Also, the exact times the border colour is
  3349.     changed is stored.  Using this information the emulator builds the
  3350.     screen; in this way, what you see on your PC monitor is exactly what a
  3351.     real Spectrum would display on a television.  Remember Aquaplane, with
  3352.     its full-width horizon?
  3353.  
  3354.     Each line takes exactly 224 T states.  After an interrupt occurs, 64
  3355.     line times pass before the byte 16384 is displayed.  At least the last
  3356.     48 of these are actual border-lines.  I could not determine whether my
  3357.     monitor didn't display the others or whether it was in vertical
  3358.     retrace, but luckily that's not really important.  Then the 192
  3359.     screen+border lines are displayed, followed by 56 border lines again.
  3360.     This makes a total of 312 lines of 224 T states, or 69888 T states,
  3361.     which is, at 3.5 MHz, very nearly 1/50th of a second.
  3362.  
  3363.     Now for the timings of each line itself.  I define a screen line to
  3364.     start with 256 screen pixels, then border, then horizontal retrace, and
  3365.     then border again.  All this takes 224 T states.  Every half T state a
  3366.     pixel is written to the CRT, so if the ULA is reading bytes it does so
  3367.     each 4 T states (and then it reads two: a screen and an ATTR byte). The
  3368.     border is 48 pixels wide at each side.  A video screen line is
  3369.     therefore timed as follows: 128 T states of screen, 24 T states of
  3370.     right border, 48 T states of horizontal retrace and 24 T states of left
  3371.     border.
  3372.  
  3373.     When an interrupt occurs, the running instruction has to be completed
  3374.     first.  The Z80 samples the state of its interrupt request line at the
  3375.     start of the last T state of each instruction.  The Z80 starts to act
  3376.     upon an interrupt request at least 1, and at most 1+23 T states after
  3377.     it is made active, as the slowest instructions (e.g. INC (IX+d), RL
  3378.     (IX+d), EX (SP),IX) take 23 T states.  This difference, which may be
  3379.     hard to control, is sometimes significant in practice for hi-resolution
  3380.     color effects.
  3381.  
  3382.     In interrupt mode 0, the processor takes 2 more T states for executing
  3383.     the opcode supplied than the normal value; if RST #38 is supplied
  3384.     (#FF), it takes 13 T states.  In interrupt mode 1, my reference gives
  3385.     two values (12 and 13 T states) for the timing of a mode 1 interrupt.
  3386.     I would put my money on 12 T states.  A mode 2 interrupt takes 19 T
  3387.     states.  Finally, a Non Maskable interrupt is fastest: it takes only 11
  3388.     T states.
  3389.  
  3390.     The ZX81 hardware generates a WAIT only 16 T states before it generates
  3391.     an NMI, which, by some combined hardware and software wizardry,
  3392.     generates one scanline on the television screen.  It seems therefore
  3393.     that by executing a whole lot of slow instructions in a block, it is
  3394.     possible to jam the horizontal synchonisation of the ZX81 video signal.
  3395.     Has this ever been tried?
  3396.  
  3397.     Now when to OUT to the border to change it at the place you want?
  3398.     First of all, you cannot change the border within a 'byte', an 8-pixel
  3399.     chunk. If we forget about the screen for a moment, if you OUT to port
  3400.     FE after 14326 to 14329 T states (including the OUT) from the start of
  3401.     the IM 2 interrupt routine, the border will change at exactly the
  3402.     position of byte 16384 of the screen.  The other positions can be
  3403.     computed by remembering that 8 pixels take 4 T states, and a line takes
  3404.     224 T states.  You would think that OUTing after 14322 to 14325 T
  3405.     states, the border would change at 8 pixels left of the upper left
  3406.     corner of the screen.  This is right for 14322, 14323 and 14324 T
  3407.     states, but if you wait 14325 T states the ULA happens to be reading
  3408.     byte 16384 (or 22528, or both) and will halt the processor for a while,
  3409.     thereby making you miss the 8 pixels.  This exception happens again
  3410.     after 224 T states, and again after 448, an so forth.  These 192
  3411.     exceptions left of the actual screen rectangle are the only ones;
  3412.     similar things don't happen at the right edge because the ULA don't
  3413.     need to read things there - it has just finished!
  3414.  
  3415.     As noted above, reading or writing in low ram (or OUTing to the ULA!)
  3416.     causes the ULA to halt the processor.  When and how much?  The
  3417.     processor is halted each time you want to access the ULA or low memory
  3418.     and the ULA is busy reading.  Of the 312 'lines' the ULA generates,
  3419.     only 192 contain actual screen pixels, and the ULA will only read bytes
  3420.     during 128 of the 224 T states of each screen line.  But if it does,
  3421.     the processor seems to be halted for 64 T states.  It is not clear to
  3422.     me when, and for how long exactly, the ULA halts the processor.
  3423.     Sometimes the ULA even stops the processor when it is not interfering
  3424.     with it (when it is busy making the border left or right of the screen
  3425.     rectangle).
  3426.  
  3427.     Finally, the 128K timings.  These are slightly different from the 48K
  3428.     video timings, causing for instance the loading bars in the border to
  3429.     move differently (which can be seen most clearly when saving).  The
  3430.     really important difference of the 128K with respect to the video is
  3431.     that the 128K ULA is more relaxed in giving the Z80 access to (screen)
  3432.     memory.  This allows programs to make hi-resolution color effects not
  3433.     only in the border, but also on the screen itself.  Many 128K programs
  3434.     use this effect.  Note however that, although the 128K ULA is more
  3435.     relaxed towards memory access, it does still halt the Z80 occasionally.
  3436.     Partly for this reason it is impossible to have hi-res color effect
  3437.     over the entire screen; there is only time to change approximately half
  3438.     of it.
  3439.  
  3440.     The basic video timings, with the Z80 out of the way, are as follows.
  3441.     Each video line takes 228 T states, 4 T states more than on the 48K
  3442.     Spectrum.  It starts with 128 T states of screen pixels (or border).
  3443.     Then there's border, horizontal retrace and border again, of 100 T
  3444.     states.  A complete '50 Hz' frame consists of 311 video lines (of which
  3445.     a few are vertical retraces), that is, 1 less than for 48K models.  A
  3446.     complete frame is 311 x 228 = 70908 T states long.
  3447.  
  3448.     I don't know whether the 128K model uses a different crystal.  If not,
  3449.     one frame on the Spectrum 128K is 1.5% longer than a 48K frame.
  3450.  
  3451.     Directly after an interrupt is generated by the ULA (so slightly before
  3452.     the Z80 acts upon it), 63 video lines are written to the CRT.  A first
  3453.     few may be verical retraces; this is difficult to find out without an
  3454.     oscilloscope, but it isn't useful information either.  Then 192 screen
  3455.     lines are written, and then 56 border lines and (possibly) vertical
  3456.     retrace lines.  The first screen byte is written to the screen 14364 T
  3457.     states after the interrupt was generated.
  3458.  
  3459.  
  3460.  
  3461. 5.2  The Interface I
  3462.  
  3463.  
  3464.     The Interface I is quite complicated.  It uses three different I/O
  3465.     ports, and contains logic to page and unpage an 8K ROM if new commands
  3466.     are used.  I won't be very detailed here; you could refer to the source
  3467.     code of the emulator if you want to know some details, or read the
  3468.     'Spectrum Shadow ROM Disassembly' by Gianlura Carri, published by
  3469.     Melbourne House - but don't expect the same level of detail as of Ian
  3470.     Logan and Frank O'Hara in their Rom disassembly book.
  3471.  
  3472.     The ROM is paged if the processor executes the instruction at ROM
  3473.     address 0008 or 1708 hexadecimal, the error and close# routines.  It is
  3474.     inactivated when the Z80 executes the RET at address 0700.
  3475.  
  3476.     I/O Port E7 is used to send or receive data to and from the microdrive.
  3477.     Accessing this port will halt the Z80 until the Interface I has
  3478.     collected 8 bits from the microdrive head; therefore, it the microdrive
  3479.     motor isn't running, or there is no formatted cartridge in the
  3480.     microdrive, the Spectrum hangs.  This is the famous 'IN 0 crash'.
  3481.  
  3482.     Port EF is used for several things:
  3483.  
  3484.  
  3485.        Bit    7   6    5    4    3    2    1     0
  3486.             ┌───┬───┬────┬────┬─────┬───┬─────┬─────┐
  3487.         READ│   │   │    │busy│ dtr │gap│ sync│write│
  3488.             │   │   │    │    │     │   │     │prot.│
  3489.             ├───┼───┼────┼────┼─────┼───┼─────┼─────┤
  3490.        WRITE│   │   │wait│ cts│erase│r/w│comms│comms│
  3491.             │   │   │    │    │     │   │ clk │ data│
  3492.             └───┴───┴────┴────┴─────┴───┴─────┴─────┘
  3493.  
  3494.  
  3495.     Bits DTR and CTS are used by the RS232 interface.  The WAIT bit is used
  3496.     by the Network to synchronise, GAP, SYNC, WR_PROT, ERASE, R/_W, COMMS
  3497.     CLK and COMMS DATA are used by the microdrive system.  If the
  3498.     microdrive is not being used, the COMMS DATA output selects the
  3499.     function of bit 0 of out-port F7:
  3500.  
  3501.  
  3502.        Bit      7    6   5   4   3   2   1       0
  3503.             ┌──────┬───┬───┬───┬───┬───┬───┬───────────┐
  3504.         READ│txdata│   │   │   │   │   │   │    net    │
  3505.             │      │   │   │   │   │   │   │   input   │
  3506.             ├──────┼───┼───┼───┼───┼───┼───┼───────────┤
  3507.        WRITE│      │   │   │   │   │   │   │net output/│
  3508.             │      │   │   │   │   │   │   │   rxdata  │
  3509.             └──────┴───┴───┴───┴───┴───┴───┴───────────┘
  3510.  
  3511.  
  3512.     TXDATA and RXDATA are the input and output of the RS232 port.  COMMS
  3513.     DATA determines whether bit 0 of F7 is output for the RS232 or the
  3514.     network.
  3515.  
  3516.  
  3517.  
  3518.  
  3519. 5.3  The SamRam
  3520.  
  3521.  
  3522.     The SamRam contains a 32K static CMOS Ram chip, and some I/O logic for
  3523.     port 31.  If this port is read, it returns the position of the
  3524.     joystick, as a normal Kempston joystickinterface would.  If written to,
  3525.     the port controls a programmable latch chip (the 74LS259) which
  3526.     contains 8 latches:
  3527.  
  3528.  
  3529.        Bit    7   6   5   4   3   2   1   0
  3530.             ┌───┬───┬───┬───┬───┬───┬───┬───┐
  3531.        WRITE│   │   │   │   │  address  │bit│
  3532.             └───┴───┴───┴───┴───┴───┴───┴───┘
  3533.  
  3534.  
  3535.     The address selects on of the eight latches; bit 0 is the new state of
  3536.     the latch.  The 16 different possibilities are collected in the diagram
  3537.     below:
  3538.  
  3539.         OUT 31,   │  Latch  │ Result
  3540.         ──────────┼─────────┼────────────────────────────────────────
  3541.             0     │    0    │ Switch on write protect of CMOS RAM
  3542.             1     │    "    │ Writes to CMOS RAM allowed
  3543.             2     │    1    │ turn on CMOS RAM (see also 6/7)
  3544.             3     │    "    │ turn off CMOS RAM (standard Spec.  ROM)
  3545.             4     │    2    │ -
  3546.             5     │    "    │ Ignore all OUT's to 31 hereafter
  3547.             6     │    3    │ Select CMOS bank 0 (Basic ROM)
  3548.             7     │    "    │ Select CMOS bank 1 (Monitor,...)
  3549.             8     │    4    │ Select interface 1
  3550.             9     │    "    │ Turn off IF 1 (IF1 rom won't be paged)
  3551.            10     │    5    │ Select 32K ram bank 0 (32768-65535)
  3552.            11     │    "    │ Select 32K ram bank 1 (32768-65535)
  3553.            12     │    6    │ Turn off beeper
  3554.            13     │    "    │ Turn on beeper
  3555.            14     │    7    │ -
  3556.            15     │    "    │ -
  3557.  
  3558.     At reset, all latches are 0.  If an OUT 31,5 is issued, only a reset
  3559.     will give you control over the latches again.  The write protect latch
  3560.     is not emulated; you're never able to write the emulated CMOS ram in
  3561.     the emulator.  Latch 4 will pull up the M1 output of the Z80.  The
  3562.     Interface I won't page the ROM anymore then.
  3563.  
  3564.  
  3565.  
  3566.  
  3567. 5.4  The Z80 microprocessor
  3568.  
  3569.  
  3570.     The Z80 processor is quite straightforward, and contains to my
  3571.     knowledge no interesting bugs or quirks.  However, it has some
  3572.     undocumented features.  Some of these are quite useful, and some are
  3573.     not, but since many programs use the useful ones, and a few programs
  3574.     use the weird ones, I tried to figure them out and emulate them as best
  3575.     as I could.  There is a Z80 emulator around, intended as a CP/M
  3576.     emulator, which halts the program if an undocumented opcode is
  3577.     encountered.  I don't think this makes sense.  ZiLOG doesn't dictate
  3578.     the law, the programs which use the processor's features do!
  3579.  
  3580.     In section 5.1 there is some information on Z80 interrupt timings in
  3581.     different modes.
  3582.  
  3583.     Most Z80 opcodes are one byte long, not counting a possible byte or
  3584.     word operand.  The four opcodes CB, DD, ED and FD are 'shift' opcodes:
  3585.     they change the meaning of the opcode following them.
  3586.  
  3587.     There are 248 different CB opcodes.  The block CB 30 to CB 37 is
  3588.     missing from the official list.  These instructions, usually denoted by
  3589.     the mnemonic SLL, Shift Left Logical, shift left the operand and make
  3590.     bit 0 always one.  Bounder and Enduro Racer use them, to name just two.
  3591.     The SamRam monitor can disassemble these and uses the mnemonic SLL.
  3592.     These instructions are quite commonly used.
  3593.  
  3594.     The DD and FD opcodes precede instructions using the IX and IY
  3595.     registers.  If you look at the instructions carefully, you see how they
  3596.     work:
  3597.  
  3598.         2A nn           LD HL,(nn)
  3599.         DD 2A nn        LD IX,(nn)
  3600.         7E              LD A,(HL)
  3601.         DD 7E d         LD A,(IX+d)
  3602.  
  3603.     A DD opcode simply changes the meaning of HL in the next instruction.
  3604.     If a memory byte is addressed indirectly via HL, as in the second
  3605.     example, a displacement byte is added.  Otherwise the instruction
  3606.     simply acts on IX instead of HL.  (A notational awkwardness, that will
  3607.     only bother assembler and disassembler writers: JP (HL) is not
  3608.     indirect; it should have been denoted by JP HL)  If a DD opcode
  3609.     precedes an instruction that doesn't use the HL register pair at all,
  3610.     the instruction is executed as usual.  However, if the instruction uses
  3611.     the H or L register, it will now use the high or low halves of the IX
  3612.     register! Example:
  3613.  
  3614.         44              LD B,H
  3615.         FD 44           LD B,IYh
  3616.  
  3617.     These types of inofficial instructions are used in many programs. By
  3618.     the way, many DD or FD opcodes after each other will effectively be
  3619.     NOPs, doing nothing except repeatedly setting the flag 'treat HL as IX'
  3620.     (or IY) and taking up 4 T states.  (But try to let MONS disassemble
  3621.     such a block.)
  3622.  
  3623.     The doubly-shifted opcodes that start with DD CB and DD ED behave
  3624.     differently.  If a DD or FD precedes an ED instruction, the DD or FD is
  3625.     ignored.  ED instructions never operate on the IX or IY register, and
  3626.     are executed normally instead.  With CB instructions, the situation is
  3627.     more interesting.  Within an 8-instruction block, every DD CB
  3628.     instruction works as the official one, but also copies the result to
  3629.     the specified register (except when it is (HL)).  For example,
  3630.  
  3631.         CB CE           SET 0,(HL)
  3632.         CB C0           SET 0,B
  3633.         DD CB nn CE     SET 0,(IX+nn)
  3634.         DD CB nn C0     SET 0,(IX+nn) ; copy result to B
  3635.  
  3636.     (The information about the inofficial CB instructions was given to me
  3637.     by Arnt Gulbrandsen, and originated from David Librik.)
  3638.  
  3639.     There are a number of inofficial ED instructions, but none of them are
  3640.     very useful.  The ED opcodes in the range 00-3F and 80-FF (except for
  3641.     the block instructions of course) do nothing at all but taking up 8 T
  3642.     states and incrementing the R register by 2.  Most of the unlisted
  3643.     opcodes in the range 40-7F do have an effect, however.  The complete
  3644.     list: (* = not official)
  3645.  
  3646.         ED40   IN B,(C)                 ED60   IN H,(C)
  3647.         ED41   OUT (C),B                ED61   OUT (C),H
  3648.         ED42   SBC HL,BC                ED62   SBC HL,HL
  3649.         ED43   LD (nn),BC               ED63 * LD (nn),HL
  3650.         ED44   NEG                      ED64 * NEG
  3651.         ED45   RETN                     ED65 * RET
  3652.         ED46   IM 0                     ED66 * IM 0
  3653.         ED47   LD I,A                   ED67   RRD
  3654.         ED48   IN C,(C)                 ED68   IN L,(C)
  3655.         ED49   OUT (C),C                ED69   OUT (C),L
  3656.         ED4A   ADC HL,BC                ED6A   ADC HL,HL
  3657.         ED4B   LD BC,(nn)               ED6B * LD HL,(nn)
  3658.         ED4C * NEG                      ED6C * NEG
  3659.         ED4D   RETI                     ED6D * RET
  3660.         ED4E * IM 0                     ED6E * IM 0
  3661.         ED4F   LD R,A                   ED6F   RLD
  3662.         ED50   IN D,(C)                 ED70 * IN (C)
  3663.         ED51   OUT (C),D                ED71 * OUT (C),0
  3664.         ED52   SBC HL,DE                ED72   SBC HL,SP
  3665.         ED53   LD (nn),DE               ED73   LD (nn),SP
  3666.         ED54 * NEG                      ED74 * NEG
  3667.         ED55 * RET                      ED75 * RET
  3668.         ED56   IM 1                     ED76 * IM 1
  3669.         ED57   LD A,I                   ED77 * NOP
  3670.         ED58   IN E,(C)                 ED78   IN A,(C)
  3671.         ED59   OUT (C),E                ED79   OUT (C),A
  3672.         ED5A   ADC HL,DE                ED7A   ADC HL,SP
  3673.         ED5B   LD DE,(nn)               ED7B   LD SP,(nn)
  3674.         ED5C * NEG                      ED7C * NEG
  3675.         ED5D * RET                      ED7D * RET
  3676.         ED5E   IM 2                     ED7E * IM 2
  3677.         ED5F   LD A,R                   ED7F * NOP
  3678.  
  3679.     The ED70 instruction reads from port (C), just like the other
  3680.     instructions, but throws away the result.  It does change the flags in
  3681.     the same way as the other IN instructions, however.  The ED71
  3682.     instruction OUTs a byte zero to port (C), interestingly.  These
  3683.     instructions 'should', by regularity of the instruction set, use (HL)
  3684.     as operand, but since from the processor's point of view accessing
  3685.     memory or accessing I/O devices is almost the same thing, and since the
  3686.     Z80 cannot access memory twice in one instruction (disregarding
  3687.     instruction fetch of course) it can't fetch or store the data byte.  (A
  3688.     hint in this direction is that, even though the NOP-synonyms LD B,B, LD
  3689.     C,C etcetera do exist, LD (HL),(HL) is absent and replaced by the HALT
  3690.     instruction.)
  3691.  
  3692.     The instructions ED 4E and ED 6E are IM 0 equivalents: when FF was put
  3693.     on the bus at interrupt time, the Spectrum continued to execute
  3694.     normally, whereas when an EF (RST #28) was put on the bus it crashed,
  3695.     just as it does in that case when the Z80 is in the official interrupt
  3696.     mode 0.  In IM 1 the Z80 just executes a RST #38 (opcode FF) no matter
  3697.     what is on the bus.
  3698.  
  3699.     The RETI instruction is functionally exactly equivalent to the RET
  3700.     instruction.  It is used only to signify the end of an interrupt
  3701.     routine to an external hardware device (read: the Z80 PIO).  The RETN
  3702.     however is different from RET in that it resets IFF1 to the current
  3703.     value of IFF2.  Now IFF1 and IFF2 are usually equal (and become equal
  3704.     after DI and EI and after a maskable interrupt has been accepted).
  3705.     They're different only if an NMI occurs when interrupts are enabled;
  3706.     then IFF1 is off, and IFF2, holding the previous state of the interrupt
  3707.     flip flop, is on, signifying that interrupts were enabled before the
  3708.     non-maskable interrupt.  Since the state of IFF2 can be read by using
  3709.     LD A,R and LD A,I, the RETN instruction is not used much in Spectrum
  3710.     ROM software, and it is utterly useless in normal software.  In other
  3711.     words, I have not tried to figure out whether the unofficial RET's are
  3712.     RETI's or RETN's.
  3713.  
  3714.     About the R register.  This is not really an undocumented feature,
  3715.     although I have never seen any thorough description of it anywhere.
  3716.     The R register is a counter that is updated every instruction, where
  3717.     DD, FD, ED and CB are to be regarded as separate instructions.  So
  3718.     shifted instructions will increase R by two.  There's an interesting
  3719.     exception: doubly-shifted opcodes, the DDCB and FDCB ones, increase R
  3720.     by two too. LDI increases R by two, LDIR increases it by 2 times BC, as
  3721.     does LDDR etcetera.  The sequence LD R,A / LD A,R increases A by two.
  3722.     The highest bit of the R register is never changed (except possibly by
  3723.     LD R,A of course).  This is because in the old days everyone used 16
  3724.     Kbit chips.  Inside the chip the bits where grouped in a 128x128
  3725.     matrix, needing a 7 bit refresh cycle.  Therefore ZiLOG decided to
  3726.     count only the lowest 7 bits.  If the R register emulation is switched
  3727.     on the R register will behave as is does on a real Spectrum; if it is
  3728.     off it will (except for the upper bit) act as a random generator.
  3729.  
  3730.     You can easily check that the R register is really crucial to memory
  3731.     refresh.  Assemble this program:
  3732.  
  3733.         ORG 32768
  3734.         DI
  3735.         LD B,0
  3736.     L1  XOR A
  3737.         LD R,A
  3738.         DEC HL
  3739.         LD A,H
  3740.         OR L
  3741.         JR NZ,L1
  3742.         DJNZ L1
  3743.         EI
  3744.         RET
  3745.  
  3746.     It will take about three minutes to run.  Look at the upper 32K of
  3747.     memory, for instance the UDG graphics.  It will have faded.  Only the
  3748.     first few bytes of each 256 byte block will still contain zeros,
  3749.     because they were refreshed during the execution of the loop.  The ULA
  3750.     took care of the refreshing of the lower 16K.  (This example won't work
  3751.     on the emulator of course!)
  3752.  
  3753.     Then there's one other dark corner of the Z80 which has its effect on
  3754.     programs like Sabre Wulf, Ghosts'n Goblins and Speedlock.  The Mystery
  3755.     of the Undocumented Flags!
  3756.  
  3757.     Bit 3 and 5 of the F register are not used.  They can contain
  3758.     information, as you can readily figure out by using PUSH AF and POP AF.
  3759.     Furthermore, sometimes their values change.  I found the following
  3760.     empirical rule:
  3761.  
  3762.         The values of bit 7, 5 and 3 follow the values of the
  3763.         corresponding bits of the last 8 bit result of an instruction
  3764.         that changed the usual flags.
  3765.  
  3766.     For instance, after an ADD A,B those bits will be identical to the bits
  3767.     of the A register.  (Bit 7 of F is the sign flag, and fits the rule
  3768.     exactly).  An exception is the CP x instruction (x=register, (HL) or
  3769.     direct argument).  In that case the bits are copied from the argument.
  3770.  
  3771.     If the instruction is one that operates on a 16 bit word, the 8 bits of
  3772.     the rule are the highest 8 bits of the 16 bit result - that was to be
  3773.     expected since the S flag is extracted from bit 15.
  3774.  
  3775.     Ghosts'n Goblins use the undocumented flag due to a programming error.
  3776.     The rhino in Sabre Wulf walks backward or keeps running in little
  3777.     circles in a corner, if the (in this case undocumented) behaviour of
  3778.     the sign flag in the BIT instruction isn't right.  I quote:
  3779.  
  3780.         AD86    DD CB 06 7E        BIT 7,(IX+6)
  3781.         AD8A    F2 8F AD           JP P,#AD8F
  3782.  
  3783.     An amazing piece of code!  Speedlock does so many weird things that
  3784.     everything must be exactly right for it to run.  Finally, the '128 rom
  3785.     uses the AF register to hold the return address of a subroutine for a
  3786.     while.  To keep all programs happy, and still have a fast emulator, I
  3787.     had to make a compromise.  The undocumented flags are not always
  3788.     emulated right, but they are most of the time.  Not telling you when
  3789.     not.
  3790.  
  3791.     Now for the emulated Z80.  I have added eight instructions, to speed up
  3792.     the RS232 input and output of the Interface I and several things of the
  3793.     SamRam.  These opcodes, ED F8 to ED FE are of little use to any other
  3794.     program.  ED FF is a nice one: it returns you to DOS immediately.  I
  3795.     used it for debugging purposes, and it is also used in TAP2TAPE and
  3796.     SAMLIST.
  3797.  
  3798.     The opcode ED F6, which is used by the SamRam, is now also used to use
  3799.     multi-load games on the emulator.  If the emulator encounters the
  3800.     opcode ED F6 in RAM (above 16384), it loads a block of code into memory
  3801.     at address HL.  The name of the file to be loaded is the name of the
  3802.     snapshot file currently run, with the decimal value of the A register
  3803.     attached to it.  The extension is .DAT.  If such a file is not found,
  3804.     the user is informed of the value of the A register and allowed to
  3805.     supply a file name himself (no sexual prejudice implied).
  3806.  
  3807.  
  3808.  
  3809.  
  3810. 5.5  File formats
  3811.  
  3812.  
  3813.     This section describes the format of the files used by the emulator.
  3814.  
  3815.  
  3816.  
  3817.     ROMS.BIN:
  3818.     ---------
  3819.  
  3820.         00000-03fff     Ordinary Spectrum rom
  3821.         04000-05fff     Interface I rom (8K)
  3822.         06000-09fff     First SamRam rom (contains BASIC)
  3823.         0a000-0dfff     Second SamRam rom (contains monitor,...)
  3824.         0e000-11fff     First Spectrum 128K rom (active at RESET)
  3825.         12000-15fff     Second Spectrum 128K rom (contains BASIC)
  3826.         16000-19fff     Disciple rom, system file 3b, Epson printer code
  3827.         1a000-1dfff     Disciple rom, system file 3b, HP printer code
  3828.         1e000-1ffff     Multiface rom (8K)
  3829.  
  3830.     The ordinary rom has not been modified.  The Interface I rom has
  3831.     undergone some modifications, to speed up the RS232 input/output
  3832.     routines.  If you don't like this, or want to use another version of
  3833.     the Interface I, you could put that code at the right place in the
  3834.     ROMS.BIN file.  The interface I should work properly, although the
  3835.     RS232 will be slower (always FORMAT the "b" or "t" channel at 19200
  3836.     baud, by the way, if you replace the rom code, there's no point in
  3837.     waiting for nothing.) The microdrive routines have not been modified in
  3838.     any way.  Here are the changes of the Interface I rom:
  3839.  
  3840.         Address: Old: New:           Address: Old: New:
  3841.  
  3842.         0B9E     ED   ED             0D20     FB   00
  3843.         0B9F     5B   FC             0D2A     37   ED
  3844.         0BA0     C3   F5             0D2B     F3   FD
  3845.         0BA1     5C   C3             0D2C     CE   18
  3846.         0BA2     21   34             0D2D     00   10
  3847.         0BA3     20   0C             0D4C     FB   00
  3848.  
  3849.     These changes are not likely to cause problems; there are several
  3850.     versions of the Interface I rom around, and program developers know
  3851.     this.  It is also a bit pointless to check whether the Interface I rom
  3852.     hasn't been modified; who would put his snapshot software in there
  3853.     anyway, and that's what those people are afraid of.
  3854.  
  3855.     The first and second SamRam rom have been modified more extensively.
  3856.     The biggest problem was that switching the upper 32K ram bank is very
  3857.     fast in reality, but on the PC two blocks of 32K bytes had to be REP
  3858.     MOVSWded (or the EMS emulator be called).  But since no programs know
  3859.     of the SamRam code anyway, this won't cause any more problems it
  3860.     wouldn't already cause either.
  3861.  
  3862.     The two Spectrum 128 roms have not been modified, and neither have the
  3863.     Disciple roms or the Multiface rom.  The Disciple roms, as they appear
  3864.     in the ROMS.BIN file, do have system files pre-loaded however.
  3865.  
  3866.  
  3867.  
  3868.     .TAP FILES:
  3869.     -----------
  3870.  
  3871.     The .TAP files contain blocks of tape-saved data.  All blocks start
  3872.     with two bytes specifying how many bytes will follow (not counting the
  3873.     two length bytes).  Then raw tape data follows, including the flag and
  3874.     checksum bytes.  The checksum is the bitwise XOR of all bytes including
  3875.     the flag byte.  For example, when you execute the line SAVE "ROM" CODE
  3876.     0,2 this will result:
  3877.  
  3878.  
  3879.              |------ Spectrum-generated data -------|       |---------|
  3880.  
  3881.        13 00 00 03 52 4f 4d 7x20 02 00 00 00 00 80 f1 04 00 ff f3 af a3
  3882.  
  3883.        ^^^^^...... first block is 19 bytes (17 bytes+flag+checksum)
  3884.              ^^... flag byte (A reg, 00 for headers, ff for data blocks)
  3885.                 ^^ first byte of header, indicating a code block
  3886.  
  3887.        file name ..^^^^^^^^^^^^^
  3888.        header info ..............^^^^^^^^^^^^^^^^^
  3889.        checksum of header .........................^^
  3890.        length of second block ........................^^^^^
  3891.        flag byte ............................................^^
  3892.        first two bytes of rom .................................^^^^^
  3893.        checksum (checkbittoggle would be a better name!).............^^
  3894.  
  3895.  
  3896.     The emulator will always start reading bytes at the beginning of a
  3897.     block.  If less bytes are loaded than are available, the other bytes
  3898.     are skipped, and the last byte loaded is used as checksum.  If more
  3899.     bytes are asked for than exist in the block, the loading routine will
  3900.     terminate with the usual tape-loading-error flags set, leaving the
  3901.     error handling to the calling Z80 program.
  3902.  
  3903.     Note that it is possible to join .TAP files by simply stringing them
  3904.     together, for example COPY /B FILE1.TAP + FILE2.TAP ALL.TAP
  3905.  
  3906.     For completeness, I'll include the structure of a tape header.  A
  3907.     header always consists of 17 bytes:
  3908.  
  3909.         Byte    Length  Description
  3910.         0       1       Type (0,1,2 or 3)
  3911.         1       10      Filename (padded with blanks)
  3912.         11      2       Length of data block
  3913.         13      2       Parameter 1
  3914.         15      2       Parameter 2
  3915.  
  3916.     The type is 0,1,2 or 3 for a Program, Number array, Character array or
  3917.     Code file.  A screen$ file is regarded as a Code file with start
  3918.     address 16384 and length 6912 decimal.  If the file is a Program file,
  3919.     parameter 1 holds the autostart line number (or a number >=32768 if no
  3920.     LINE parameter was given) and parameter 2 holds the start of the
  3921.     variable area relative to the start of the program.  If it's a Code
  3922.     file, parameter 1 holds the start of the code block when saved, and
  3923.     parameter 2 holds 32768.  For data files finally, the byte at position
  3924.     14 decimal holds the variable name.
  3925.  
  3926.  
  3927.  
  3928.     .MDR FILES:
  3929.     -----------
  3930.  
  3931.     The emulator uses a cartridge file format identical to the 'Microdrive
  3932.     File' format of Carlo Delhez' Spectrum emulator Spectator for the QL,
  3933.     who devised the format.  This format is now also supported by XZX of
  3934.     Des Harriot.  The following information is adapted from Carlo's
  3935.     documentation.  It can also be found in the 'Spectrum Microdrive Book',
  3936.     by Ian Logan (co-writer of the excellent 'Complete Spectrum ROM
  3937.     Disassembly').
  3938.  
  3939.     A cartridge file contains 254 'sectors' of 543 bytes each, and a final
  3940.     byte flag which is non-zero is the cartridge is write protected, so the
  3941.     total length is 137923 bytes.  On the cartridge tape, after a GAP of
  3942.     some time the Interface I writes 10 zeros and 2 FF bytes (the
  3943.     preamble), and then a fifteen byte header-block-with-checksum.  After
  3944.     another GAP, it writes a preamble again, with a 15-byte record-
  3945.     descriptor-with-checksum (which has a structure very much like the
  3946.     header block), immediately followed by the data block of 512 bytes, and
  3947.     a final checksum of those 512 bytes.  The preamble is used by the
  3948.     Interface I hardware to synchronise, and is not explicitly used by the
  3949.     software.  The preamble is not saved to the microdrive file:
  3950.  
  3951.     offset length name    contents
  3952.  
  3953.       0      1   HDFLAG   Value 1, to indicate header block
  3954.       1      1   HDNUMB   sector number (values 254 down to 1)
  3955.       2      2            not used
  3956.       4     10   HDNAME   microdrive cartridge name (blank padded)
  3957.      14      1   HDCHK    header checksum (of first 14 bytes)
  3958.  
  3959.      15      1   RECFLG   - bit 0: always 0 to indicate record block
  3960.                           - bit 1: set for the EOF block
  3961.                           - bit 2: reset for a PRINT file
  3962.                           - bits 3-7: not used (value 0)
  3963.      16      1   RECNUM   data block sequence number (value starts at 0)
  3964.      17      2   RECLEN   data block length (<=512, LSB first)
  3965.      19     10   RECNAM   filename (blank padded)
  3966.      29      1   DESCHK   record descriptor checksum (of previous 14 bytes)
  3967.      30    512            data block
  3968.     542      1   DCHK     data block checksum (of all 512 bytes of data
  3969.                            block, even when not all bytes are used)
  3970.     ---------
  3971.     254 times
  3972.  
  3973.  
  3974.     (Actually, this information is 'transparent' to the emulator.  All it
  3975.     does is store 2 times 254 blocks in the .MDR file as it is OUTed,
  3976.     alternatingly of length 15 and 528 bytes.  The emulator does check
  3977.     checksums, see below; the other fields are dealt with by the emulated
  3978.     Interface I software.)
  3979.  
  3980.     A used record block is either an EOF block (bit 1 of RECFLG is 1) or
  3981.     contains 512 bytes of data (RECLEN=512, i.e.  bit 1 of MSB is 1).  An
  3982.     empty record block has a zero in bit 1 of RECFLG and also RECLEN=0.  An
  3983.     unusable block (as determined by the FORMAT command) is an EOF block
  3984.     with RECLEN=0.
  3985.  
  3986.     The three checksums are calculated by adding all the bytes together
  3987.     modulo 255; this will never produce a checksum of 255.  Possibly, this
  3988.     is the value that is read by the Interface I if there's no or bad data
  3989.     on the tape.
  3990.  
  3991.     In normal operation, all first-fifteen-byte blocks of each header or
  3992.     record block will have the right checksum.  If the checksum is not
  3993.     right, the block will be treated as a GAP.  For instance, if you type
  3994.     OUT 239,0 on a normal Spectrum with interface I, the microdrive motor
  3995.     starts running and the cartridge will be erased completely in 7
  3996.     seconds. CAT 1 will respond with 'microdrive not ready'.  Try it on the
  3997.     emulator...
  3998.  
  3999.  
  4000.  
  4001.  
  4002.     .OUT FILES:
  4003.     -----------
  4004.  
  4005.     These files are produced when logging OUTs; see menu option O in the
  4006.     Extra Functions menu.  For the specified I/O ports, all OUTs to these
  4007.     ports are recorded in the .OUT file, together with the exact time at
  4008.     which the OUTs were executed.
  4009.  
  4010.     An .OUT file consists of a string of 5-byte blocks.  The first word is
  4011.     the timing word; it has a value between 0 and 17471 inclusive (or
  4012.     between 0 and 17726 inclusive when a 128K Spectrum was emulated), and a
  4013.     unit value corresponds to 1 T state (=1/3494400 s).  After this, the
  4014.     OUT port that was written to follows, then the value OUTed itself:
  4015.  
  4016.         Offset  Length  Description
  4017.  
  4018.         0       2       Time (0-17471 or 0-17726)
  4019.         2       2       Port address
  4020.         4       1       Value
  4021.  
  4022.     Every 1/200th of an emulated second, that is, every 69888/4=17472 T
  4023.     states (or 70908/4=17727 T states on 128K Spectrums), a time-wraparound
  4024.     block is written to the .OUT file:
  4025.  
  4026.         Offset  Length  Description
  4027.  
  4028.         0       2       Flag word #FFFF indicating wraparound-block
  4029.         2       2       Length of preceding block (17472 or 17727 T)
  4030.         4       1       Not used
  4031.  
  4032.     So even when the Spectrum does not OUT to the logged ports at all, 1000
  4033.     bytes get written to the log file every second.
  4034.  
  4035.     By default, an OUT to an even I/O address which does not change the
  4036.     state of the MIC and EAR outputs is not written to the .OUT file, to
  4037.     save disk space when recording music.  If you want all OUTs, specify
  4038.     -xg on the command line.
  4039.  
  4040.     The .OUT files are also used to make a simple trace of a running
  4041.     Spectrum program.  Specify -xy on the command line; as soon as you
  4042.     activate OUT logging, a trace is dumped also.  For each instruction
  4043.     encountered during emulation, the following block is written to the
  4044.     .OUT file:
  4045.  
  4046.         Offset  Length  Description
  4047.  
  4048.         0       2       Flag word (#FFFE)
  4049.         2       2       Program counter
  4050.         5       1       A register
  4051.  
  4052.     Furthermore, no time-wraparound blocks are written to the .OUT file
  4053.     when tracing.  HALT instructions (118 decimal) are special in that they
  4054.     do not generate a block in the log file; this is to make comparisons
  4055.     between different logs of the same program easier.  Admittedly, this is
  4056.     a very crude way of tracing a program, but it's better than nothing,
  4057.     and very useful very occasionally.
  4058.  
  4059.  
  4060.  
  4061.  
  4062.     .SCR FILES:
  4063.     -----------
  4064.  
  4065.     .SCR files are memory dumps of the first 6912 bytes of the Spectrum
  4066.     memory.  A coordinate (x,y), x between 0 and 255 and y between 0 and
  4067.     192, (0,0) being the upper left corner of the screen, corresponds to
  4068.     the pixel address
  4069.  
  4070.         16384+INT (x/8)+1792*INT (y/64)-2016*INT (y/8)+256*y
  4071.  
  4072.     I admit this is not quite the clearest way to explain the organization
  4073.     of Spectrum's video memory, but with a bit or (hard) thinking you can
  4074.     extract from above formula all information you need...  The lowest
  4075.     three bits of x determine which bit of this address corresponds to the
  4076.     pixel (x,y).  This bit-map constitutes the larger part of the screen
  4077.     memory, 256*192/8=6144 bytes.  The final 768 bytes are attribute bytes.
  4078.     The address of the attribute byte corresponding to pixel (x,y) is
  4079.  
  4080.         22528+INT (x/8)+32*INT (y/8)
  4081.  
  4082.     The lowest three bits of the attribute byte control the foreground
  4083.     color (the color of the pixel if the corresponding bit in the bitmap is
  4084.     set), bits 3-5 control the background color, bit 6 is the bright bit
  4085.     and bit 7 is the flash bit - if it is set, every 16/50th of a second
  4086.     the ULA effectively flips the foreground and background colours.
  4087.  
  4088.  
  4089.  
  4090.     .Z80 FILES:
  4091.     -----------
  4092.  
  4093.     The old .Z80 snapshot format (for version 1.45 and below) looks like
  4094.     this:
  4095.  
  4096.         Offset  Length  Description
  4097.  
  4098.         0       1       A register
  4099.         1       1       F register
  4100.         2       2       BC register pair (LSB, i.e.  C, first)
  4101.         4       2       HL register pair
  4102.         6       2       Program counter
  4103.         8       2       Stack pointer
  4104.         10      1       Interrupt register
  4105.         11      1       Refresh register (Bit 7 is not significant!)
  4106.         12      1       Bit 0  : Bit 7 of the R-register
  4107.                         Bit 1-3: Border colour
  4108.                         Bit 4  : 1=Basic SamRom switched in
  4109.                         Bit 5  : 1=Block of data is compressed
  4110.                         Bit 6-7: No meaning
  4111.         13      2       DE register pair
  4112.         15      2       BC' register pair
  4113.         17      2       DE' register pair
  4114.         19      2       HL' register pair
  4115.         21      1       A' register
  4116.         22      1       F' register
  4117.         23      2       IY register (Again LSB first)
  4118.         25      2       IX register
  4119.         27      1       Interrupt flipflop, 0=DI, otherwise EI
  4120.         28      1       IFF2 (not particularly important...)
  4121.         29      1       Bit 0-1: Interrupt mode (0, 1 or 2)
  4122.                         Bit 2  : 1=Issue 2 emulation
  4123.                         Bit 3  : 1=Double interrupt frequency
  4124.                         Bit 4-5: 1=High video synchronisation
  4125.                                  3=Low video synchronisation
  4126.                                  0,2=Normal
  4127.                         Bit 6-7: 0=Cursor/Protek/AGF joystick
  4128.                                  1=Kempston joystick
  4129.                                  2=Sinclair 2 Left joystick (or user
  4130.                                    defined, for version 3 .Z80 files)
  4131.                                  3=Sinclair 2 Right joystick
  4132.  
  4133.     Because of compatibility, if byte 12 is 255, it has to be regarded as
  4134.     being 1.  After this header block of 30 bytes the 48K bytes of Spectrum
  4135.     memory follows in a compressed format (if bit 5 of byte 12 is one).
  4136.     The compression method is very simple: it replaces repetitions of at
  4137.     least five equal bytes by a four-byte code ED ED xx yy, which stands
  4138.     for "byte yy repeated xx times".  Only sequences of length at least 5
  4139.     are coded. The exception is sequences consisting of ED's; if they are
  4140.     encountered, even two ED's are encoded into ED ED 02 ED.  Finally,
  4141.     every byte directly following a single ED is not taken into a block,
  4142.     for example ED 6*00 is not encoded into ED ED ED 06 00 but into ED 00
  4143.     ED ED 05 00. The block is terminated by an end marker, 00 ED ED 00.
  4144.  
  4145.     That's the format of .Z80 files as used by versions up to 1.45.
  4146.     Starting from version 2.0, a different format is used, since from then
  4147.     on also 128K snapshots had to be supported.  This new format is used
  4148.     for all snapshots, either 48K or 128K.  However, the emulator still
  4149.     understands the old format.
  4150.  
  4151.     Also note that, although old .Z80 file formats are still understood,
  4152.     the emulator will never procude an old format .Z80 file, and also 48K
  4153.     snapshots are written in the new format.  But, then again, new .Z80
  4154.     file formats can be translated back to the old one (provided that it is
  4155.     an 48K snapshot of course) by using ConvZ80.
  4156.  
  4157.     Version 2.01 and 3.0 .Z80 files start with the same 30 byte header as
  4158.     old .Z80 files used.  Bit 4 and 5 of the flag byte have no meaning
  4159.     anymore, and the program counter (byte 6 and 7) are zero to signal a
  4160.     version 2.01 or version 3.0 snapshot file.
  4161.  
  4162.     After the first 30 bytes, the additional header follows:
  4163.  
  4164.  
  4165.         Offset  Length  Description
  4166.  
  4167.       * 30      2       Length of additional header block (see below)
  4168.       * 32      2       Program counter
  4169.       * 34      1       Hardware mode (see below)
  4170.       * 35      1       If in SamRam mode, bitwise state of 74ls259.
  4171.                         For example, bit 6=1 after an OUT 31,13 (=2*6+1)
  4172.                         If in 128 mode, contains last OUT to 7ffd
  4173.       * 36      1       Contains 0FF if Interface I rom paged
  4174.       * 37      1       Bit 0: 1 if R register emulation on
  4175.                         Bit 1: 1 if LDIR emulation on
  4176.       * 38      1       Last OUT to fffd (soundchip register number)
  4177.       * 39      16      Contents of the sound chip registers
  4178.         55      2       Low T state counter
  4179.         57      1       Hi T state counter
  4180.         58      1       Flag byte used by Spectator (QL spec. emulator)
  4181.                         Ignored by Z80 when loading, zero when saving
  4182.         59      1       0FF if MGT Rom paged
  4183.         60      1       0FF if Multiface Rom paged. Should always be 0.
  4184.         61      1       0FF if 0-8191 is RAM
  4185.         62      1       0FF if 8192-16383 is RAM
  4186.         63      10      5x keyboard mappings for user defined joystick
  4187.         73      10      5x ascii word: keys corresponding to mappings above
  4188.         83      1       MGT type: 0=Disciple+Epson,1=Discipls+HP,16=Plus D
  4189.         84      1       Disciple inhibit button status: 0=out, 0ff=in
  4190.         85      1       Disciple inhibit flag: 0=rom pageable, 0ff=not
  4191.  
  4192.  
  4193.     The value of the word at position 30 is 23 for version 2.01 files, and
  4194.     54 for version 3.0 files.  The starred fields are the ones that
  4195.     constitute the version 2.01 header, and their interpretation has
  4196.     remained unchanged except for byte 34:
  4197.  
  4198.         Value:          Meaning in v2.01        Meaning in v3.0
  4199.  
  4200.         0               48k                     48k
  4201.         1               48k + If.1              48k + If.1
  4202.         2               SamRam                  48k + M.G.T.
  4203.         3               128k                    SamRam
  4204.         4               128k + If.1             128k
  4205.         5               -                       128k + If.1
  4206.         6               -                       128k + M.G.T.
  4207.  
  4208.     The hi T state counter counts up modulo 4.  Just after the ULA
  4209.     generates its once-in-every-20-ms interrupt, it is 3, and is increased
  4210.     by one every 5 emulated milliseconds.  In these 1/200s intervals, the
  4211.     low T state counter counts down from 17472 to 0, which make a total of
  4212.     69888 T states per frame.
  4213.  
  4214.     The 5 ascii words (high byte always 0) at 73-82 are the keys
  4215.     corresponding to the joystick directions left, right, down (!), up (!),
  4216.     fire respectively.  Shift, Symbol Shift, Enter and Space are denoted by
  4217.     [,],/,\ respectively.  The ascii values are used only to display the
  4218.     joystick keys; the information in the 5 keyboard mapping words
  4219.     determine which key is actually pressed (and should correspond to the
  4220.     ascii values).  The low byte is in the range 0-7 and determines the
  4221.     keyboard row.  The high byte is a mask byte and determines the column.
  4222.     Enter for example is stored as 0x0106 (row 6 and column 1) and 'g' as
  4223.     0x1001 (row 1 and column 4).
  4224.  
  4225.     Byte 60 must be zero, because the contents of the Multiface RAM is not
  4226.     saved in the snapshot file.  If the Multiface was paged when the
  4227.     snapshot was saved, the emulated program will most probably crash when
  4228.     loaded back.
  4229.  
  4230.     Bytes 61 and 62 are a function of the other flags, such as byte 34, 59,
  4231.     60 and 83.
  4232.  
  4233.     Hereafter a number of memory blocks follow, each containing the
  4234.     compressed data of a 16K block.  The compression is according to the
  4235.     old scheme, except for the end-marker, which is now absent.  The
  4236.     structure of a memory block is:
  4237.  
  4238.  
  4239.         Byte    Length  Description
  4240.  
  4241.         0       2       Length of data (without this 3-byte header)
  4242.         2       1       Page number of block
  4243.         3       [0]     Compressed data
  4244.  
  4245.  
  4246.     The pages are numbered, depending on the hardware mode, in the
  4247.     following way:
  4248.  
  4249.  
  4250.         Page    In '48 mode     In '128 mode    In SamRam mode
  4251.  
  4252.          0      48K rom         rom (basic)     48K rom
  4253.          1      Interface I, Disciple or Plus D rom, according to setting
  4254.          2      -               rom (reset)     samram rom (basic)
  4255.          3      -               page 0          samram rom (monitor,..)
  4256.          4      8000-bfff       page 1          Normal 8000-bfff
  4257.          5      c000-ffff       page 2          Normal c000-ffff
  4258.          6      -               page 3          Shadow 8000-bfff
  4259.          7      -               page 4          Shadow c000-ffff
  4260.          8      4000-7fff       page 5          4000-7fff
  4261.          9      -               page 6          -
  4262.         10      -               page 7          -
  4263.         11      Multiface rom   Multiface rom   -
  4264.  
  4265.  
  4266.     In 48K mode, pages 4,5 and 8 are saved.  In SamRam mode, pages 4 to 8
  4267.     are saved.  In '128 mode, all pages from 3 to 10 are saved.  This
  4268.     version saves the pages in numerical order.  There is no end marker.
  4269.  
  4270.  
  4271.  
  4272.