eaw/Z80
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
1f7129cd6ca8ade4dcbbd8151a5a1eb8bfa39ae3
Z80/README
redcode 028f50cbde v0.2-alpha
2022-05-17 12:53:52 +02:00

320 lines
13 KiB
Plaintext
Raw Blame History

________________ ________________ _________________
| /\ | || |
|_______ / / | ____ || ____ |
\_____/ / / | |____| || |___/| |
/ / / | || | | | |
/ / / | ____ || | | | |
/ /_/_____| |____| || |__|_| |
/ || || |
/_______________||________________||________________|
\________________\\______________//________________/
______________________________________________________________________________
| |
| Zilog Z80 CPU Emulator |
| version 0.2 |
| |
| Copyright (C) 1999-2022 Manuel Sainz de Baranda y Goñi |
| Released under the terms of the GNU Lesser General Public License v3 |
| |
| https://zxe.io/software/Z80 |
| |
'=============================================================================='
1. Introduction
================
The Z80 library implements a fast, small and accurate emulator of the Zilog Z80.
It emulates all that is known to date about this CPU, including the undocumented
behaviour, MEMPTR, Q and the special RESET. It also has the honor of having been
the first open source project to provide full emulation of the interrupt mode 0.
The source code is written in ANSI C for maximum portability and is extensively
commented. The aim has been to write a well-structured, easy to understand piece
of software; something solid and elegant that can stand the test of time with no
need for major changes.
2. Emulation accuracy
======================
The Zilog Z80 emulator has a classic design with instruction-level granularity.
This provides the best performance when speed is a critical factor, while still
offering a reasonable flexibility to achieve precision down to the T-state level
when accuracy is imperative.
Instruction-level granularity implies that, except in a few well-defined cases,
the execution of a given instruction cannot stop until all its internal M-cycles
are completed. This kind of emulation is also carried out in an efficient way:
the pertinent registers are modified only once per instruction and the T-state
counter is updated only after a whole instruction is executed.
That said, instructions, flags, memory accesses, interrupt and reset responses,
clock cycles, etc. are accurately emulated as far as is known, according to the
technical documentation available, the findings made after decades of research
on the Z80 and electronic simulations. And, of course, the emulator passes the
most exhaustive tests written to date such as Patrik Rak's "Zilog Z80 CPU Test
Suite", Frank D. Cringle's "Z80 Instruction Set Exerciser", Mark Woodmass' "Z80
Test Suite" and Peter Helcmanovsky's "Z80 Block Flags Test", to name a few.
3. Installation
================
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 you have LaTeX with PDF support installed on your system in case you want
to generate the documentation in PDF format.
The emulator requires some types and macros included in Zeta (https://zeta.st),
a dependency-free, header-only library used to retain compatibility with most C
compilers. Install Zeta or extract its official source code package to the same
directory of this README or its parent directory. Zeta is the sole dependency;
the emulator is a freestanding implementation and as such does not depend on the
C standard library.
Once all requirements are met, create a directory and run cmake from there to
prepare the build system:
$ mkdir build
$ cd build
$ cmake <directory of this README> [options]
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
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)
Build the project as a shared library rather than a static one.
The default is NO.
-DCMAKE_BUILD_TYPE=(Debug|Release|RelWithDebInfo)
Choose the type of build (configuration) to generate.
The default is Release.
-DCMAKE_INSTALL_PREFIX="<path>"
Specify the installation prefix on UNIX and UNIX-like operating systems.
The default is "/usr/local".
Package-specific options are prefixed with "Z80_" and can be divided into two
groups. The first one controls aspects not related to the source code of the
library:
-DZ80_DOWNLOAD_TEST_FILES=(YES|NO)
Download the firmware and software used by the testing tool.
The default is NO.
-DZ80_INSTALL_CMAKEDIR="<path>"
Specify the directory in which to install the CMake config-file package.
The default is "${CMAKE_INSTALL_LIBDIR}/cmake/Z80".
-DZ80_INSTALL_PKGCONFIGDIR="<path>"
Specify the directory in which to install the pkg-config file.
The default is "${CMAKE_INSTALL_LIBDIR}/pkgconfig".
-DZ80_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 "".
-DZ80_SHARED_LIBS=(YES|NO)
Build the project as a shared library rather than a static one.
This option takes precedence over "BUILD_SHARED_LIBS".
Not defined by default.
-DZ80_SPHINX_HTML_THEME="[<name>]"
Specify the Sphinx theme for the documentation in HTML format.
The default is "" (use the default theme).
-DZ80_WITH_CMAKE_SUPPORT=(YES|NO)
Generate and install the CMake config-file package.
The default is NO.
-DZ80_WITH_HTML_DOCUMENTATION=(YES|NO)
Build and install the documentation in HTML format.
It requires Doxygen, Sphinx and Breathe.
The default is NO.
-DZ80_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.
-DZ80_WITH_PKGCONFIG_SUPPORT=(YES|NO)
Generate and install the pkg-config file.
The default is NO.
-DZ80_WITH_STANDARD_DOCUMENTS=(YES|NO)
Install the standard text documents distributed with the package:
AUTHORS, COPYING, COPYING.LESSER, HISTORY, README and THANKS.
The default is NO.
-DZ80_WITH_TESTS=(YES|NO)
Build the testing tool.
The default is NO.
The second group of package-specific options configures the source code of the
library by predefining macros that enable optional implementations:
-DZ80_WITH_EXECUTE=(YES|NO)
Build the implementation of the z80_execute function.
The default is NO.
-DZ80_WITH_FULL_IM0=(YES|NO)
Build the full implementation of the interrupt mode 0 rather than the
reduced one.
The default is NO.
-DZ80_WITH_Q=(YES|NO)
Build the implementation of the Q "register".
The default is NO.
-DZ80_WITH_RESET_SIGNAL=(YES|NO)
Build the implementation of the normal RESET signal.
The default is NO.
-DZ80_WITH_SPECIAL_RESET_SIGNAL=(YES|NO)
Build the implementation of the special RESET signal.
The default is NO.
-DZ80_WITH_UNOFFICIAL_RETI=(YES|NO)
Configure the ED5Dh, ED6Dh and ED7Dh undocumented instructions as "reti"
instead of "retn".
The default is NO.
-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=(YES|NO)
Build the implementation of the bug affecting the Zilog Z80 NMOS, which
causes the P/V flag to be reset when a maskable interrupt is accepted
during the execution of the "ld a,{i|r}" instructions.
The default is NO.
Package maintainers should use at least the following options for both shared and
static library targets:
-DZ80_WITH_EXECUTE=YES
-DZ80_WITH_FULL_IM0=YES
-DZ80_WITH_Q=YES
-DZ80_WITH_RESET_SIGNAL=YES
-DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=YES
Finally, once the build system is configured according to your needs, build and
install the package:
$ make
# make install/strip
4. Integration
===============
4.1. As an external dependency in CMake-based projects
The Z80 library includes find-modules and a config-file package for integration
into CMake-based projects. It is recommended to always copy the FindZ80.cmake
and FindZeta.cmake files into the CMake modules directory of projects that use
the library as an external dependency. This will allow CMake to find the library
if the necessary config-file packages are not installed on the system.
Both the config-file package and the find-module support dual installations of
the shared and static versions of the Z80 library. You can specify the linking
method by using the component mechanism of "find_package".
Example:
find_package(Z80 REQUIRED [Shared|Static])
target_link_libraries(your-target Z80)
Omitting the linking method will select the "Shared" version of the library or,
if not installed, the "Static" version instead.
4.2. As a CMake subproject
To embed the library as a CMake subproject, just place its entire source tree
into a subdirectory of your project.
It is advisable to configure the library in the CMakeLists.txt of your project.
This will prevent the user from having to specify configuration options of the
Z80 subproject through the CMake command line when building the main project.
As noted in the "Installation" section of this document, all package-specific
options are prefixed with "Z80_", so, in a normal scenario, there should be no
risk of name collision with the options and variables of the parent project.
Example:
set(Z80_SHARED_LIBS NO CACHE BOOL "")
set(Z80_WITH_Q YES CACHE BOOL "")
set(Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG YES CACHE BOOL "")
add_subdirectory(dependencies/Z80)
target_link_libraries(your-target Z80)
It is important to set the "Z80_SHARED_LIBS" option. Otherwise CMake will build
the library type indicated by "BUILD_SHARED_LIBS", which may not be the desired
one.
4.3. Manual integration
There are several macros that can be used to configure the source code of the
library. You can define those you need in your build system or at the beginning
of the Z80.c file. The following ones allow you to configure the integration of
Z80.h and Z80.c into the project:
#define Z80_DEPENDENCIES_HEADER "header name.h"
Specifies the only external header to #include, replacing those of Zeta.
If used, it must also be defined before including the Z80.h header.
#define Z80_STATIC
Needed for compiling and/or using the emulator as a static library or as
an internal part of other project.
If used, it must also be defined before including the Z80.h header.
#define Z80_WITH_LOCAL_HEADER
Tells Z80.c to #include "Z80.h" instead of <Z80.h>.
The second group of package-specific options, explained in the "Installation"
section of this document, activates various optional implementations in the
source code by predefining the following macros:
#define Z80_WITH_EXECUTE
#define Z80_WITH_FULL_IM0
#define Z80_WITH_Q
#define Z80_WITH_RESET_SIGNAL
#define Z80_WITH_SPECIAL_RESET_SIGNAL
#define Z80_WITH_UNOFFICIAL_RETI
#define Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG
Please note that the activation of some these optional implementations affects
the speed of the emulator due to various factors (read the documentation for
more details).
As a final note, except for "Z80_DEPENDENCIES_HEADER", the above macros do not
need to be set to a particular token when used, as the source code only checks
whether or not they are defined.
5. License
===========
This library is free software: you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option) any
later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along
with this library. If not, see <http://www.gnu.org/licenses/>.
--------------------------------------------------------------------------------
Last update: 2022-05-16 README EOF
Reference in New Issue View Git Blame Copy Permalink