Zilog Z80 emulation engine, sorta

A complete emulation of the Zilog Z80 processor written in C++11.

Extremely accurate - passes all the test ROMs at my disposal

Platform-independent and architecture-independent code

Compact - base emulator consists of only a single header and source file

Kabuki CPU decryption natively supported (as an optional single-header extension)

Easily customizable interface

Dynamic disassembly (from any memory address) and simple debug output

And more to come!

The BeeZ80 library (and the testing framework, if desired) does not have any dependencies and can be compiled with MinGW on Windows, and (presumably) both GCC and Clang on Linux, as well as (presumably) AppleClang on OSX.

In order to build the testing framework, simply pass -DBUILD_Z80_TESTS="ON" to CMake.

Step 1: Install dependencies:

Core dependencies:

Compiler: GCC or Clang. You only need one of those two:

GCC 10.2.0+ (earlier versions not tested):

Debian (not tested): sudo apt-get install build-essential

Arch (not tested): sudo pacman -S base-devel

Fedora (not tested): sudo dnf install gcc-c++

OpenSUSE (not tested): sudo zypper in gcc-c++

Clang (not tested):

Debian: sudo apt-get install clang clang-format libc++-dev (in some distros, clang-5.0)

Arch: pacman -S clang, libc++ is in the AUR. Use pacaur or yaourt to install it.

Fedora: dnf install clang libcxx-devel

OpenSUSE: zypper in clang

Other core dependencies:

Git (if not installed already) and CMake 3.1+:

Debian (not tested): sudo apt-get install git cmake

Arch (not tested): sudo pacman -S git

Fedora (not tested): sudo dnf install git cmake

OpenSUSE (not tested): sudo zypper in git cmake extra-cmake-modules

Step 2: Clone the repository:

git clone --recursive https://github.com/BueniaDev/BeeZ80.git

cd BeeZ80

Step 3: Compile:

mkdir build && cd build

cmake .. -G "Unix Makefiles" -DBUILD_Z80_TESTS="<ON/OFF>" -DCMAKE_BUILD_TYPE="<Debug/Release>"

make -j$(nproc --all)

You will need homebrew, a recent version of Xcode and the Xcode command-line tools to build BeeZ80. Please note that due to personal financial constraints, BeeZ80 has not been tested on Mac OS as of yet.

Step 1: Install dependencies:

brew install git cmake pkg-config

Step 2: Clone the repository:

git clone --recursive https://github.com/BueniaDev/BeeZ80.git

cd BeeZ80

Step 3: Compile:

mkdir build && cd build

cmake .. -G "Unix Makefiles" -DBUILD_Z80_TESTS="<ON/OFF>" -DCMAKE_BUILD_TYPE="<Debug/Release>"

make -j$(sysctl -n hw.ncpu)

You will need MSYS2 in order to install BeeZ80. Make sure to run pacman -Syu as needed.

Step 1: Install dependencies:

pacman -S base-devel mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake git

Step 2: Clone the repository:

git clone --recursive https://github.com/BueniaDev/BeeZ80.git

cd BeeZ80

Step 3: Compile:

mkdir build && cd build

cmake .. -G "MSYS Makefiles" -DBUILD_Z80_TESTS="<ON/OFF>" -DCMAKE_BUILD_TYPE="<Debug/Release>"

(mingw32-)make -j$(nproc --all)

If you chose to build the (optional) testing framework:

../msys-dist.sh

Step 1. Include the header file:

#include "beez80.h"
using namespace beez80;

Step 2: Implement the interface:

class Interface : public BeeZ80Interface
{
    public:
	uint8_t ram[0x10000]; // 64KB memory (minimum)
	uint8_t io[0x100]; // 256 bytes of I/O ports

	Interface()
	{
	    memset(&ram, 0, sizeof(ram));
	    memset(&io, 0, sizeof(io));
	}

	// Memory read request per 1 byte from CPU
	uint8_t readByte(uint16_t addr)
	{
	    return ram[addr];
	}

	// Optional function, set the return value to false
	// if the opcode space is the same as the program space
	bool isSeperateOps()
	{
	    return true;
	}

	// Opcode read request per 1 byte from CPU
	// (optional, define this function if using seperate opcode spaces)
	uint8_t readOpcode(uint16_t addr)
	{
	    return ram[addr];
	}

	// Memory write request per 1 byte from CPU
	void writeByte(uint16_t addr, uint8_t val)
	{
	    ram[addr] = value;
	}

	// IN operand request from CPU
	uint8_t portIn(uint16_t port)
	{
	    return io[(port & 0xFF)];
	}

	// OUT operand request from CPU
	void portOut(uint16_t port, uint8_t val)
	{
	    io[(port & 0xFF)] = val;
	}
};

Step 3: Create an instance of the emulated Zilog Z80:

Interface interface;

// Create instance of Zilog Z80
BeeZ80 core;

// Set hardware abstraction interface
core.setinterface(&interface);

// (Optional) Set cycle prescalers for both regular and M1
// (i.e. instruction fetch) cycles

int num_instr_cycles = 1;
int num_fetch_cycles = 0;

core.set_prescalers(num_instr_cycles, num_fetch_cycles);

Step 4: Initialize the processor:

core.init(); // Initializes the program counter to 0...

// but you can set the program counter to an abritary 16-bit value too
// core.init(0x100);

Step 5: Begin executing instructions:

// Run one Zilog Z080 instruction
int instr_cycles = core.runinstruction();

If you want to generate an interrupt:

// This function accepts a valid Zilog Z80 opcode as its first argument
// The second argument can be used to assert or clear the IRQ line

// Generate IRQ
core.generate_interrupt(0xFF); // 0xFF = RST 38H

// Generate IRQ and assert IRQ line
core.generate_interrupt(0xFF, true); // 0xFF = RST 38H

// Clear IRQ line
core.generate_interrupt(0xFF, false);

If you want to generate an NMI:

// The sole argument of this function can be used to assert or clear the NMI line

// Generate NMI
core.generate_nmi();

// Assert NMI line
core.generate_nmi(true);

// Clear NMI line
core.generate_nmi(false);

If you want to reset the CPU:

core.reset(); // Resets the CPU with the program counter set to 0...

// but you can set the program counter to an abritary 16-bit value too
// core.reset(0x100);

If you want to disassemble an instruction at a specific address:

// "addr" is the address of the instruction you want to disassemble
// The resulting string can be printed to the console,
// or even utilized in some sort of graphical debugger
string instr_disassembly = core.disassembleinstr(addr);

If you want to output a more complete debug log of the emulated CPU state to the console:

// Call this function before executing an instruction
core.debugoutput();
// Run a single instruction
core.runinstruction();

Expand debugging support

Feature parity with MAME's Z80 core

Graphical debugger (possibly via Qt5?)

BeeZ80 is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

(C) 2021 BueniaDev. This project is not affiliated in any way with Zilog or its associates. Zilog Z80 is a registered trademark of Zilog, Inc.

For information regarding BeeZ80's stance on copyright infringement, as well as proof of BeeZ80's legality, see the LEGAL.md file in this repository.