Z80 Instruction Clock

Z80InsnClock is a small library written in ANSI C that provides T-state level precision to Zilog Z80 emulators. It allows to determine the exact clock cycle within an instruction at which the ongoing M-cycle starts, as well as its duration.

The library offers two modes of operation: Basic and Extra. Each mode increases the size of the library by 4 KiB of tables that contain patterns describing all Z80 instructions.

The Basic mode is the most simple, determining only the starting clock cycle of each M-cycle, and all related functions are inline.

The Extra mode allows knowing, in addition to the starting clock cycle, the number of extra clock cycles in the M-cycle and thus its duration, making it suitable for emulating systems such as the ZX Spectrum. This mode is a bit more complex and requires calling a non-inline function during the opcode fetch.

Most users will integrate Z80InsnClock as a CMake subproject or copy its source code into their projects. In this case, if you do not need both operation modes, you can disable the compilation of the unused one.

Installation

Debian, Ubuntu and other Debian-based Linux distributions

First, add the zxe repository and update the package index:

sudo mkdir -pm700 /root/.gnupg
sudo mkdir -pm755 /etc/apt/keyrings
sudo gpg --no-default-keyring --keyring /etc/apt/keyrings/zxe-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys FE214A38D6A0C01D9AF514EE841EA3BD3A7E1487
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/zxe-archive-keyring.gpg] https://zxe.io/repos/apt stable main" | sudo tee /etc/apt/sources.list.d/zxe.list
sudo apt update

Next, install the library package:

sudo apt install libz80insnclock

In case you need to build software that requires the Z80InsnClock library, install the development package too:

sudo apt install libz80insnclock-dev

Gentoo

First, add and sync the zxe overlay:

eselect repository add zxe git https://github.com/redcode/zxe-gentoo-overlay.git
emaint sync --repo zxe

Then install the library:

emerge emulation-libs/z80insnclock

Homebrew

brew install redcode/zxe/z80insnclock

Windows

Pre-built binaries for Windows are available on the download page.

Installation from sources

Prerequisites

You will need CMake v3.14 or later to build the package and, optionally, recent versions of Doxygen, Sphinx and Breathe to compile the documentation. Also, make sure that you have LaTeX with PDF support installed on your system if you want to generate the documentation in PDF format.

The Z80InsnClock library requires some types and macros included in Zeta, a header-only, dependency-free library used for portability reasons. Zeta is the sole dependency; Z80InsnClock does not depend on the C standard library.

Configure

Once the prerequisites are met, create a directory and run cmake from there to prepare the build system:

mkdir build
cd build
cmake [options] <Z80InsnClock-project-directory>

The resulting build files can be configured by passing options to cmake. To show a complete list of those available along with their current settings, type the following:

cmake -LAH -N -B .

If in doubt, read the CMake documentation for more information on configuration options. The following are some of the most relevant standard options of CMake:

• -DBUILD_SHARED_LIBS=(YES|NO)
  Generate shared libraries rather than static libraries.
  The default is NO.

• -DCMAKE_BUILD_TYPE=(Debug|Release|RelWithDebInfo|MinSizeRel)
  Choose the type of build (configuration) to generate.
  The default is Release.

• -DCMAKE_INSTALL_NAME_DIR="<path>"
  Specify the directory portion of the dynamic library install name on Apple platforms (for installed shared libraries).
  Not defined by default.

• -DCMAKE_INSTALL_PREFIX="<path>"
  Specify the installation prefix.
  The default is "/usr/local" (on UNIX and UNIX-like operating systems).

Package-specific options are as follows:

• -DZ80InsnClock=(All|Basic|Extra)
  Specify which operation mode(s) to build.
  All enables both Basic and Extra. Basic mode is the simplest and only determines the clock cycle at which the ongoing M-cycle begins, while Extra mode additionally provides information about the duration of the M-cycle.
  The default is All.

• -DZ80InsnClock_INSTALL_CMAKEDIR="<path>"
  Specify the directory in which to install the CMake config-file package.
  The default is "${CMAKE_INSTALL_LIBDIR}/cmake/Z80InsnClock".

• -DZ80InsnClock_INSTALL_PKGCONFIGDIR="<path>"
  Specify the directory in which to install the pkg-config file.
  The default is "${CMAKE_INSTALL_LIBDIR}/pkgconfig".

• -DZ80InsnClock_NOSTDLIB_FLAGS=(Auto|"[<flag>[;<flag>...]]")
  Specify the linker flags used to avoid linking against system libraries.
  The default is Auto (autoconfigure flags). If you get linker errors, set this option to "".

• -DZ80InsnClock_OBJECT_LIBS=(YES|NO)
  Build Z80InsnClock as an object library.
  This option takes precedence over BUILD_SHARED_LIBS and Z80InsnClock_SHARED_LIBS. If enabled, the build system will ignore Z80InsnClock_WITH_CMAKE_SUPPORT and Z80InsnClock_WITH_PKGCONFIG_SUPPORT, as no libraries or support files will be installed.
  The default is NO.

• -DZ80InsnClock_SHARED_LIBS=(YES|NO)
  Build Z80InsnClock as a shared library, rather than static.
  This option takes precedence over BUILD_SHARED_LIBS.
  Not defined by default.

• -DZ80InsnClock_SPHINX_HTML_THEME="[<name>]"
  Specify the Sphinx theme for the documentation in HTML format.
  The default is "" (use the default theme).

• -DZ80InsnClock_WITH_CMAKE_SUPPORT=(YES|NO)
  Generate and install the CMake config-file package.
  The default is NO.

• -DZ80InsnClock_WITH_HTML_DOCUMENTATION=(YES|NO)
  Build and install the documentation in HTML format.
  It requires Doxygen, Sphinx and Breathe.
  The default is NO.

• -DZ80InsnClock_WITH_PDF_DOCUMENTATION=(YES|NO)
  Build and install the documentation in PDF format.
  It requires Doxygen, Sphinx, Breathe, and LaTeX with PDF support.
  The default is NO.

• -DZ80InsnClock_WITH_PKGCONFIG_SUPPORT=(YES|NO)
  Generate and install the pkg-config file.
  The default is NO.

• -DZ80InsnClock_WITH_STANDARD_DOCUMENTS=(YES|NO)
  Install the standard text documents distributed with the package: AUTHORS, HISTORY, LICENSE-0BSD and README.
  The default is NO.

Build and install

Finally, once the build system is configured according to your needs, build and install the package:

cmake --build . [--config (Debug|Release|RelWithDebInfo|MinSizeRel)]
cmake --install . [--config <configuration>] [--strip]

The --config option is only necessary for those CMake generators that ignore CMAKE_BUILD_TYPE (e.g., Xcode and Visual Studio). Use --strip to remove debugging information and non-public symbols when installing non-debug builds of the shared library.

TL;DR

Use the following to build Z80InsnClock as a shared library and install it along with the development files into $HOME/.local:

mkdir work && cd work
git clone https://github.com/agaxia/Z80InsnClock.git
cd Z80InsnClock
mkdir build && cd build
cmake \
	-DBUILD_SHARED_LIBS=YES \
	-DCMAKE_BUILD_TYPE=Release \
	-DCMAKE_INSTALL_NAME_DIR="$HOME/.local/lib" \
	-DCMAKE_INSTALL_PREFIX="$HOME/.local" \
	-DZ80InsnClock_WITH_CMAKE_SUPPORT=YES \
	-DZ80InsnClock_WITH_PKGCONFIG_SUPPORT=YES \
	..
cmake --build . --config Release
cmake --install . --config Release --strip

^{build-and-install-Z80InsnClock.sh}

License

Copyright © 2021-2025 Sofía Ortega Sosa.

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.