
                         ===================
                         A new ZX81 emulator
                         ===================

New features :
        Runs ZX80 Rom (included)
        Runs AszMic Rom (included)
        Command Line Configuration.

This grew out of my unreleased Spectrum Emulator, as did my Jupiter Ace
emulator. (I'm going backwards in time...) I got quite fascinated with
the extraordinary hardware of the ZX81 and decided to hack my Z80 engine
to emulate a ZX81. Large chunks of the code were nicked from my other
emulators, (you may recognise them if you've played with the Ace
emulator). It works quite happily with the ZX80's ROM,and the Assembler
ROM AszMic.

[At present Tree4th does not work, mainly because of its somewhat esoteric
use of memory... under development. Anyone know of any more ROMs ?].

What's different about this one ? Well, its free, its got a built in
debugger, it's fairly quick (say about 1/3 speed of XtenderF) - but it
was never designed to go like a train. All the Z80 Registers are stored
in RAM, and the display is emulated correctly. There is a hack for
standard screens to speed display rendering up, but it still works through
the standard code if you want. And it is completely free.

I could make it faster but why ? - it's fast enough. On my Cyrix P120
it goes nippily rather than insanely, flat out things run quick rather
than as a blur. This'll mean it probably needs a 486SX-25 ish for
full speed, ATs and things are out.

It does have some improvements over the shareware xtenderf .. (for
example "Zombies" works properly and the keyboard works correctly)
and ts1000 (the copy I had was a bit erratic ?). Hires seems to
work ok. I've tried the Steve McDonald Games, Wilf's 16k and 1k
programs & they seem to work ok.

The only program that didn't work correctly was 'Chess' which has
some copy protection on the front. Towards the end of the protection
an NMI is generated without the display being setup, which makes it
go haywire. A few 'P' files didn't work, but did work after being
Loaded into Xtender and then Saved again.

The source code is also available, if you want it.

It is also freeware - if you like it you can send me a nice email
message. Well, actually , its reportbugware, which means that if
you find a bug you have to tell me about it via email.....

Command Line
============

     zx81 [-x] [-h] [-v] [-n] [-a] [-d] <filename>[.P|.81]

-x      Load the ZX80 Rom rather than the ZX81 Rom.
-a      Load the AszMic Rom rather than the ZX81 Rom.
-h      Emulate the ZX80 hardware (No NMI generator basically !)
-v      "Vanilla" Roms. The speed and tape patches are not installed.
-n      Emulate the NMI fully, don't use NMI Speed up trick.
-d      Don't use the display acceleration patch on ZX80/ZX81, all
        graphics done on a scanline basis. (Doesn't affect AszMic Rom)
-s      Boot in standard speed

At present the other ROMs are not fully supported, as SAVE and LOAD
functionality has not yet been implemented.

Some of these are automatic - selecting the ZX80 ROM will force use of
the ZX80 Hardware, for example.

If you supply a file name with the command line it will set that as
the default file (either P or 81 type), and can be loaded via LOAD ""
LOAD "name" loads the given file. You do not need to supply the
extension, it will look for xxxx.p then xxxx.81 by itself.
SAVE "<filename>" saves to <filename>.P

Note : Some P files don't seem to work for some reason, but they
do work if loaded and saved into Xtender. This emulator requires
a straight data dump from 4009-xxxx.

The easiest front end is from Windows (it runs happily in 95 and
in a window as much as anything does !) is to associate .P and .81
files with ZX81.EXE and when it runs just press J'' (== LOAD "")

Escape          Quit (to MSDOS)
Keypad +        Toggle Standard / Turbo (Border Red in Turbo,is default)
F1              Reset ZX81
F2              Next Colour Scheme
F10             Enter Debugger

Extra keys are provided to help with typing - these are :

+ - = , : and ; map to their equivalents on the ZX81.
[ and ] map to ( and ) on the ZX81.
' maps to " on the ZX81.

Note : Shift 9 and 0 (brackets) can't be automapped because they
do something else on a ZX81 [Rubout/Graphics]

The Debugger
------------
The debugger is simple but functional. There are 3 windows - machine status
disassembled program and data.

The values are set by the same keys. To set the breakpoint address, use
the Alt key. To set the Data Address, use the Ctrl Key. Changing the
address in the 'disassembly' area does NOT change the program counter. At
present it isn't possible to change the Z80 registers.
 
0-9,A-F                 Rotate address right,insert digit (Try it !)
Up/Down/PUp/PDn         Move Up or Down by 1 or 16 bytes
Home                    Set equal to PC

Debugger Function Keys
----------------------
F1              Break = Disassembly Address
F5              Display Current Screen
F7              Step Through (until SP = value before call).. bit ropey !
F8              Single Step
F9              Run until Breakpoint
ESC             Run normally (no Breakpoint)

Technical Stuff
===============

Memory between 8 and 16k is sometimes RAM , and sometimes ROM.
To get round this, on RESET the ROM at 0000-1FFF is copied to
2000-3FFF. Only memory from 0000-1FFF is write protected however.

There are two hacks to the ROM, at present. The included ROM is
Vanilla ZX81. It would work without any hacks *except* you couldn't
load much into it.

The first hack is for Tape Save/Load. (I presumed you didn't want to
load in programs at 300 baud connected to a Soundblaster card. If you
do.... errmm buy a real ZX81). Load is a brutal patch of the code at
$0340 in the ROM, fundamentally it ignores it , loads the data to 4009,
and does an error call 13 (fail) or 0 (run). Save is a couple of
patches, trapping the filename and data respectively.

The second hack patches the IRQ routine at 0041h, so that if it detects
a standard screen display it uses direct drawing code to speed up the
screen rendering. This involves using whole characters rather than
rendering single lines, assumes a standard display file. The definition
of this is as follows. If there are any wierd Hires displays which
would pass this test (?) let me know.

On entry to 'generation' (e.g. JUMP to >$8000)....

    (1) Z80 C register must be 8,
                e.g. doing a whole character, not 1 pixel high characters
    (2) IX must point to ROM
                e.g. using the standard video routine.
    (3) The first byte of the display must not be code.
                (special hack for Erno Borgesteede's display)
    (4) The CLI option to disable the speedup is used (-d)

The fast mode synchronisation hack has been removed, it now works
happily without it (putting the screen in the proper place)

However, there is a fudge (sorry). When executing code in the upper
32k of Memory (e.g. display code)  R bit 6 going zero causes the IRQ
to refresh the next line. However, this won't work if the code currently
running is in 0000-7FFF (because every R increment would have to be
tested). According to the docs A6 is connected to !INT so A6 low should
cause an Interrupt at any time (in the refresh cycle ?). Code run in
$8000-$FFFF is handled differently to code in $0000-$7FFF (because
you are executing the Display File or similar)

The NMI is partially emulated. It is only physically 'called' when
the alternate A register (which counts blank lines) is 255 - e.g.
immediately before the display or vsync starts. Most of the time
it just increments A' itself. This gets a little extra speed, because
in SLOW mode a ZX81 is calling this every 64us if it isn't generating
the screen display. It is possible to correctly emulate the NMI
through the command line.

Things to do :-

        - Complete emulation for ZX80 and AszMic Rom
        - Support TreeForth ROM
        - Support for ZX81 Joystick (does it exist)
        - Filename Selector for LOAD "" when no CLI Filename

Paul Robson
autismuk@aol.com

