Zilog Z80 CPU Emulator

Copyright © 1999-2016 Manuel Sainz de Baranda y Goñi.
Released under the terms of the GNU General Public License v3.

This is a very accurate Z80 emulator I wrote many years ago. It has been used in several machine emulators by other people and it has been extensivelly tested. It's very fast and small (although there are faster ones written in assembly), its structure is very clear and the code is commented.

If you are looking for an accurate Zilog Z80 CPU emulator for your project maybe you have found the correct one. I use this core in the ZX Spectrum emulator I started as hobby.

Building

In order to compile you must install Z, a header only library which provides types, macros, inline functions, and a lot of utilities to detect the particularities of the compiler and the target system. This is the only dependency, the standard C library and its headers are not used and the emulator doesn't need to be dynamically linked with any library.

A Xcode project file is provided to build the emulator. It has the following targets:

Targets

Name	Description
dynamic	Shared library.
module	Module for A.C.M.E.
static	Static library.
static+ABI	Static library with a descriptive ABI to be used in modular multi-machine emulators. Building the ABI implies callback pointers with slots enabled.
static+ABI-API	The same as above but exposing only the symbol of the ABI, the API functions will be private.

Constants used in Z80.h

Name	Description
CPU_Z80_STATIC	You need to define this if you are using the emulator as a static library or if you have added its sources to your project.
CPU_Z80_USE_SLOTS	Always needed when using the ABI. Each callback function will have its own context pointer, which should store the address of the object assigned to the call.

Constants used in Z80.c

Name	Description
CPU_Z80_DYNAMIC	Needed to build a shared library. Exports the public symbols.
CPU_Z80_BUILD_ABI	Builds the ABI of type ZCPUEmulatorABI declared in the header with the identifier abi_emulation_cpu_z80.
CPU_Z80_BUILD_MODULE_ABI	Builds a generic module ABI of type ZModuleABI. This constant enables CPU_Z80_BUILD_ABI automatically so abi_emulation_cpu_z80 will be build too. This option is intended to be used when building a true module loadable at runtime with dlopen(), LoadLibrary() or similar. The module ABI can be accessed retrieving the weak symbol __module_abi__.
CPU_Z80_HIDE_API	Makes the API functions private.
CPU_Z80_HIDE_ABI	Makes the abi_emulation_cpu_z80 private.
CPU_Z80_USE_LOCAL_HEADER	Use this if you have imported Z80.h and Z80.c to your project. Z80.c will include "Z80.h" instead of <emulation/CPU/Z80.h>.

API

z80_run

Description
Runs the core for the given amount of cycles.

Prototype

zsize z80_run(Z80 *object, zsize cycles);

Parameters
object: A pointer to an emulator instance.
cycles: The number of cycles to be executed.

Return value
The number of cycles executed.

Discusion
Given the fact that one Z80 instruction needs between 4 and 23 cycles to be executed, it is not always possible to run the core the exact number of cycles specfified.

z80_power

Description
Switchs the core power status.

Prototype

void z80_power(Z80 *object, zboolean state);

Parameters
object: A pointer to an emulator instance.
state: ON / OFF

Return value
None.

z80_reset

Description
Resets the core by reinitializing its variables and sets its registers to the state they would be in a real Z80 CPU after a pulse in the RESET line.

Prototype

void z80_reset(Z80 *object);

Parameters
object: A pointer to an emulator instance.

Return value
None.

z80_nmi

Description
Performs a non-maskable interrupt. This is equivalent to a pulse in the NMI line of a real Z80 CPU.

Prototype

void z80_nmi(Z80 *object);

Parameters
object: A pointer to an emulator instance.

Return value
None.

z80_int

Description
Switchs the state of the maskable interrupt. This is equivalent to a change in the INT line of a real Z80 CPU.

Prototype

void z80_int(Z80 *object, zboolean state);

Parameters
object: A pointer to an emulator instance.
state: ON = set line high, OFF = set line low

Return value
None.

Callbacks

read

Description
Called when the CPU needs to read 8 bits from memory.

Prototype

typedef zuint8 (* ZContext16BitAddressRead8Bit)(void *context, zuint16 address);
ZContext16BitAddressRead8Bit read;

Parameters
context: A pointer to the calling emulator instance.
address: The memory address to read.

Return value
The 8 bits read from memory.

write

Description
Called when the CPU needs to write 8 bits to memory.

Prototype

typedef void (* ZContext16BitAddressWrite8Bit)(void *context, zuint16 address, zuint8 value);
ZContext16BitAddressWrite8Bit write;

Parameters
context: A pointer to the emulator instance.
address: The memory address to write.
value: The value to write in address.

Return value
None.

in

out

int_data

halt

History

• v1.0.0 (2016-05-02)
  • Initial release.