Mikko's Z80 and Sinclair ZX Spectrum utilities

General information about the package

Mikko's Z80 and Sinclair ZX Spectrum utilities is a collection of Java applications which are used in emulating, testing, debugging and profiling Z80 processor, Z80 systems and Sinclair ZX Spectrum implementations. Currently (as of 2009-07-19) the package consists of a Z80 test bench, Spectrum emulator and embedded Z80 disassembler/debugger.

Download

You may choose the version from the following table. Currently (as of 2009-12-03), only source package is available. There is also an example games bundle of some old Spectrum games in appropriate format. Note that these are, in general, NOT released under GNU GPL, but are included as they are well available in the Internet.

Download options
Product	Binary	Source
Mikko's Z80 utilities Note that instructions are for this version.	-	z80util-0.8.tar.gz
Spectrum games bundle	examplegamesbundle.tar.gz	-
Mikko's Z80 utilities	-	z80util-0.9.tar.gz

Requirements

The source package requires Apache Maven as a compilation tool. You may download it from here and follow the installation instructions.

Installation of Z80 utilities

After properly configuring Maven, you may install the Z80 utilities package. Unzip the package by

$ zcat mz80util-<version>.tar.gz | tar xvf -

change directory to it by

$ cd mz80util-<version>

and compile it by

$ mvn clean install

Testing the Z80 utilities

Change to Z80 test bench directory

$ cd testbench

and type

$ mvn exec:java

This should launch the testbench with two Z80 emulator implementations described in detail below. Close the testbench and change then to Spectrum directory by

$ cd ../spectrum

and again type

$ mvn exec:java

This should launch the Spectrum emulator with grayish-white background and Sinclair copyright text in it.

MZ80TestBench - an open source Z80 test bench application

MZ80TestBench after successful processor feature comparison.

General things about Z80 processor

It is often a somewhat difficult task to correctly emulate a processor, even a relatively simple one, like Z80. Although it seems simple to assign values to registers and memory address, there are anyway lots of commands and some of them affect the so-called flags register, F, in a strange way. Especially if one uses shortcuts and tries to implement a large number of commands in same if construct, for example taking advantage of syntax of LD Q,R whose binary opcode is in general 01QQQRRR where Q and R are taken from the following table:

LD Q,R
Value of Q or R	Register / memory pointer
000	B
001	C
010	D
011	E
100	H
101	L
110	(HL)
111	A

Here we have multiple things to be aware of. For example the special value 110 which stands for memory pointer (HL) but not a register. To make things more complicated, if this type of command is DDh or FDh-prefixed, then the command reads or writes from an indexed memory reference, ie. the three-byte machine instruction "DD 74 E0 " stands for LD (IX-20h),H , not LD (IX),H , LD (IX+E0h),H nor LD (IX-20h), IXH . Without forgetting that the binary code 01110110=76h stands for HALT, not any sort of load or store command at all! One therefore often needs to rely to a verifier, testbench or exerciser against one's own Z80 emulator, whatever we call it.

If at this point you feel that you know nothing what the above is all about, please refer to some of the following links:

Z80 emulators compatible with this testbench

To design your Z80 emulator compatible for this testbench, there is just two requirements, it must implement packages Z80-interface and it must be declared as a Spring Framework bean as described below. There are two complete examples of such Z80 cores here, (a) YazeBasedZ80Impl + YazeBasedALU, and (b) QaopZ80Impl. The "Yaze"-one is loosely (only central ALU-functions, as the command fork in this one is implemented by me!) based on Yaze-AG, many authors, but originally written by Frank D. Cringle. The "Qaop"-one is based on Qaop, which is a Z80 and Sinclair ZX Spectrum emulator written by Jan Bobrowski and further based on "The Undocumented Z80 Documented" by Sean Young.

Smoke-testing the testbench

To check that the test bench actually works and manages to print the code and name of the failing instruction properly, you may make a minor change to either one of the provided processor implementations (to calculate a single or couple of Z80 instruction wrong) and then re-compile and re-run the application. The application should halt with the progress bar turning red and provide a detailed message, what went wrong. Below is an example what happens, if QaopZ80Impl:s "CP D" command was corrupted like this:

 case 0xB9: cp(C); break;
 case 0xBA: /* cp(D) */ cp(E); break;
 case 0xBB: cp(E); break;

MZ80TestBench after failed processor feature comparison.

Note that it failed in this case to the undocumented 3 and 5 flags. Even if those flags were ignored it would most likely have failed to some other flags like the carry flag, as the test is repeated many times (specified in "spring-testbench.xml") per instruction.

Wiring your Z80 emulator class into testbench

The testbench uses Spring Framework for dependency injection. There should be a file named "spring-testbench.xml", with a section like this:

<bean id="testbench" class="org.mn.z80util.testbench.MZ80TestBench">
    <property name="processor1" ref="YazeProcessor"/>
    <property name="processor2" ref="QaopProcessor"/>
    ...
</bean>

You should replace either one of the processors with your own processor's Spring bean, resembling the bean definition like this, found in the same file:

<bean id="QaopProcessor" class="org.mn.z80util.z80.qaop.QaopZ80Impl">
    <property name="ula" ref="ula"/>
</bean>

After this, you should re-compile and re-run the application. Note that it is possible to start your Z80 emulator from scratch (see MockZ80.java) and develop it command by command or command group by command group test-drivenly against either of the demo implementations.

Jeccy - an open source Sinclair ZX Spectrum emulator

Jeccy is a (currently silent) Sinclair ZX Spectrum (48K) emulator which can load and save Z80 and SNA snapshots. TAP or TZX tape files are unfortunately not currently (as of 2009-07-20) supported. To start the Spectrum emulator, chdir into "spectrum/" and type

$ mvn exec:java

You should see the following application window appear:

The Spectrum main window

You may open the disassembler/debugger by choosing "View"->"Debugger", which should open the following window:

The debugger main window

By entering start and end hexadecimal values into "Start address" and "End address"-fields and then pressing "Submit", you should obtain a listing of Z80 machine code instructions. The emulator is built in such a way that entering "step" mode (by "Step" button, "Continue" releases), every command not previously in the machine code listing is appended to the end of it. See the following image:

The debugger in use

As mentioned before, it is possible to load and save Z80 and SNA snapshots via the "File"-menu. Some of these are available in the following bundle: Spectrum example games. One of them is "Manic Miner", by Matthew Smith:

Manic Miner start screen

Acknowledgements

Special thanks for the following Z80 and Sinclair ZX Spectrum hobbyists and professionals:

Jan Bobrowski from Poland, for Qaop Z80 implementations.
Miklos Szeredi from Hungary, for Z80 and SNA snapshot algorithms, ported from his Spectemu.
Andreas Gerlich from Germany, and Frank D. Cringle (country unknown) for "YAZE-based ALU" algorithms
Matthew Smith for Manic Miner and Jet Set Willy

Mikko Nummelin