From d6a19a053dfed52d63a90d1c43ab8dcba938bd9c Mon Sep 17 00:00:00 2001 From: redcode Date: Tue, 29 Oct 2024 05:20:03 +0100 Subject: [PATCH] Remove unused files. --- documentation/Integration.rst | 105 ------ documentation/Introduction.rst | 92 ------ documentation/License.rst | 11 - documentation/Tests.rst | 3 - documentation/Thanks.rst | 570 --------------------------------- documentation/Usage.rst | 131 -------- 6 files changed, 912 deletions(-) delete mode 100644 documentation/Integration.rst delete mode 100644 documentation/Introduction.rst delete mode 100644 documentation/License.rst delete mode 100644 documentation/Tests.rst delete mode 100644 documentation/Thanks.rst delete mode 100644 documentation/Usage.rst diff --git a/documentation/Integration.rst b/documentation/Integration.rst deleted file mode 100644 index 062d97a..0000000 --- a/documentation/Integration.rst +++ /dev/null @@ -1,105 +0,0 @@ -=========== -Integration -=========== - -.. |BUILD_SHARED_LIBS| replace:: ``BUILD_SHARED_LIBS`` -.. _BUILD_SHARED_LIBS: https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html - -.. |find_package| replace:: ``find_package`` -.. _find_package: https://cmake.org/cmake/help/latest/command/find_package.html - -.. |add_subdirectory| replace:: ``add_subdirectory`` -.. _add_subdirectory: https://cmake.org/cmake/help/latest/command/add_subdirectory.html - -As an external dependency in CMake-based projects -================================================= - -The Z80 library includes a `config-file package `_ for integration into CMake-based projects that must be installed for development. Use |find_package|_ to find the ``Z80`` package. This creates the ``Z80`` imported library target, which carries the necessary transitive link dependencies. Optionally, the linking method can be selected by specifying either the ``Shared`` or ``Static`` component. - -Example: - -.. code-block:: cmake - - find_package(Z80 REQUIRED Shared) - target_link_libraries(your-target Z80) - -When not specified as a component, the linking method is selected according to :option:`Z80_SHARED_LIBS<-DZ80_SHARED_LIBS>`. If this option is not defined, the config-file uses the type of library that is installed on the system and, if it finds both the shared and the static versions, |BUILD_SHARED_LIBS|_ determines which one to link against. - -As a CMake subproject -===================== - -To embed the Z80 library as a CMake subproject, extract the source code tarballs of `Zeta `_ and `Z80 `_ (or clone their respective repositories) into a subdirectory of another project. Then use |add_subdirectory|_ in the parent project to add the Z80 source code tree to the build process (N.B., the Z80 subproject will automatically find Zeta and import it as an `interface library `_). - -It is advisable to configure the Z80 library in the :file:`CMakeLists.txt` of the parent project. This will prevent the user from having to specify :ref:`configuration options for the Z80 subproject ` through the command line when building the main project. - -Example: - -.. code-block:: cmake - - 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 :option:`Z80_SHARED_LIBS<-DZ80_SHARED_LIBS>` option. Otherwise, CMake will build the library type indicated by |BUILD_SHARED_LIBS|_, which may not be the desired one. - -Non-CMake-based projects -======================== - -The source code of the emulator can be configured at compile time by predefining a series of macros. Both :file:`Z80.h` and :file:`Z80.c` obey the first two explained below. The rest of the macros are only relevant when compiling :file:`Z80.c`: - -.. c:macro:: Z80_EXTERNAL_HEADER - - Specifies the only external header to ``#include``, replacing all others. - - Predefine this macro to provide a header file that defines the external types and macros used by the emulator, thus preventing your project from depending on `Zeta `_: - - * Macros: ``Z_ALWAYS_INLINE``, ``Z_API_EXPORT``, ``Z_API_IMPORT``, ``Z_CAST``, ``Z_EMPTY``, ``Z_EXTERN_C_BEGIN``, ``Z_EXTERN_C_END``, ``Z_MEMBER_OFFSET``, ``Z_NULL``, ``Z_UINT8_ROTATE_LEFT``, ``Z_UINT8_ROTATE_RIGHT``, ``Z_UINT16``, ``Z_UINT16_BIG_ENDIAN``, ``Z_UINT32``, ``Z_UINT32_BIG_ENDIAN``, ``Z_UNUSED``, ``Z_USIZE`` and ``Z_USIZE_MAXIMUM``. - - * Types: ``zboolean``, ``zchar``, ``zsint``, ``zsint8``, ``zuint``, ``zuint8``, ``zuint16``, ``zuint32``, ``zusize``, ``ZInt16`` and ``ZInt32``. - - You can use this macro when compiling :file:`Z80.c` as a part of your project or (if your types do not break the binary compatibility) when including ```` and linking against a pre-built Z80 library. - -.. c:macro:: Z80_STATIC - - Restricts the visibility of public symbols. - - This macro is required if you are building :file:`Z80.c` as a static library, compiling it directly as a part of your project, or linking your program against the static version of the Z80 library. In either of these cases, make sure this macro is defined before including ``"Z80.h"`` or ````. - -.. c:macro:: Z80_WITH_LOCAL_HEADER - - Tells :file:`Z80.c` to ``#include "Z80.h"`` instead of ````. - -The :ref:`optional features ` of the emulator mentioned in the ":doc:`installation-from-sources`" section are disabled by default. If you compile :file:`Z80.c` as a part of your project, enable those features you need by predefining their respective activation macros. They have the same name as their :ref:`CMake equivalents `: - -.. c:macro:: Z80_WITH_EXECUTE - - Enables the implementation of the :c:func:`z80_execute` function. - -.. c:macro:: Z80_WITH_FULL_IM0 - - Enables the full implementation of the interrupt mode 0. - -.. c:macro:: Z80_WITH_IM0_RETX_NOTIFICATIONS - - Enables optional notifications for any ``reti`` or ``retn`` instruction executed during the interrupt mode 0 response. - -.. c:macro:: Z80_WITH_Q - - Enables the implementation of `Q `_. - -.. c:macro:: Z80_WITH_SPECIAL_RESET - - Enables the implementation of the `special RESET `_. - -.. c:macro:: Z80_WITH_UNOFFICIAL_RETI - - Configures the undocumented instructions ``ED5Dh``, ``ED6Dh`` and ``ED7Dh`` as ``reti`` instead of ``retn``. - -.. c:macro:: Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG - - Enables 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. - -Except for :c:macro:`Z80_EXTERNAL_HEADER`, the above macros can be empty; the source code only checks whether they are defined. diff --git a/documentation/Introduction.rst b/documentation/Introduction.rst deleted file mode 100644 index 5d436a5..0000000 --- a/documentation/Introduction.rst +++ /dev/null @@ -1,92 +0,0 @@ -============ -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 behaviors, `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. - -Limitations -=========== - -Granularity ------------ - -Fetch/execute overlapping -------------------------- - -Real Z80 CPUs overlap some operations of certain instructions with the fetch phase of the next instruction or interrupt response. For example, the effective modification of registers A and F. The library does not emulate this feature for speed reasons and only guarantees register coherence at the instruction level, not at the T-state level. - -Normal RESET ------------- - -BUSREQ and WAIT ---------------- - -Optional features -================= - -:c:func:`z80_execute` ---------------------- - -This function performs a partial emulation of the Z80 CPU that ignores interrupts and the special RESET. It is somewhat faster than :c:func:`z80_run`, since the emulation loop does not have to check each iteration for pending interrupts before executing the instruction. - -Not enabling the implementation of this function allows a slight reduction in the size of the library, but it is usually marginal. - -Package maintainers should enable the implementation of the :c:func:`z80_execute` function. - -Interrupt mode 0 ----------------- - -The interrupt mode 0 executes an instruction supplied to the CPU via the data bus. Real Z80 chips can execute any instruction, even illegal ones, and also long sequences of ``DDh/FDh`` prefixes, although most existing hardware only uses a few instructions from the control transfer groups. - -The Z80 library includes two different implementations of this interrupt mode: full, which emulates everything; and reduced, which emulates only the ``jp WORD``, ``call WORD`` and ``rst N`` instructions. - -Enabling the full implementation of the interrupt mode 0 can increase the size of the library by 1 or 2 KB approximately (depending on the target ISA and the executable format). - -Package maintainers should enable the full implementation of the interrupt mode 0. - -Notifications of ``reti`` and ``retn`` in the interrupt mode 0 --------------------------------------------------------------- - -The Z80 emulator notifies the fetch of the instructions ``reti`` and ``retn`` through the callbacks :c:data:`Z80::reti` and :c:data:`Z80::retn`. This simplifies the emulation of chips such as the Zilog Z80 CTC, which monitors the appearance of the ``reti`` instruction on the data bus to evaluate whether the CPU is returning from an ISR. - -It is presumed that the Z80 CTC is not capable of detecting ``reti`` when executed through interrupt mode 0. Furthermore, there is no known hardware that supplies these instructions to the CPU during the interrupt response. However, the notifications of ``reti`` and ``retn`` in the interrupt mode 0 have no impact on speed, the increase in the size of the library is minimal, and they can be disabled at runtime anyway. - -Package maintainers should enable notifications of ``reti`` and ``retn`` in the interrupt mode 0, just in case. - -Q -- - -Q is an abstraction of certain ALU latches related to flag computation. The state of Q affects the undocumented flags X and Y in the ``ccf`` and ``scf`` instructions of Z80 CPUs from Zilog and other manufacturers. - -Enabling the implementation of this feature adds code to update the value of Q in each instruction and interrupt response, which slightly increases the size of the library and, depending on the target ISA and the specific microarchitecture of the host CPU, can result in a performance loss of up to 2.4%. - -Package maintainers should, however, enable the implementation of Q, as it is necessary for the emulator to pass all tests. - -Special RESET -------------- - -The special RESET is a little-known pseudo-interrupt described in U.S. Patent No. `4,486,827 `_. It was first `documented `_ in detail by Tony Brewer. It is not of particular interest for the emulation of commercial systems, as no machine is known to make use of it except for a few development boards such as the Zilog In-Circuit Emulator (ICE). - -Enabling the implementation of the special RESET is discouraged because it adds extra operations that slightly affect the speed of interrupt responses and the resumption of the HALT state. - -Package maintainers **should not enable** the implementation of the special RESET. - -Unofficial ``reti`` opcodes ---------------------------- - -The ``retn`` instruction has 8 different opcodes: 1 documented, 6 undocumented and ``reti``, which is just the specific ``retn`` opcode whose execution is monitored by the Z80 CTC chip to know whether the CPU is returning from an ISR. - -Some Z80 CPU emulators assign the 4 opcodes whose bit 3 is ``0`` to ``retn``, and the other 4 to ``reti``. However, as far as is known, the Z80 CTC and other similar circuits only monitor the execution of the two-byte instruction ``ED4Dh`` (i.e. the instruction that the official documentation designates as ``reti``). - -Enabling unofficial ``reti`` opcodes will configure the instructions ``ED5Dh``, ``ED6Dh`` and ``ED7Dh`` as ``reti``, causing their execution to be notified through the :c:data:`Z80::reti` callback rather than :c:data:`Z80::retn`. - -Package maintainers should **never enable** unofficial ``reti`` opcodes. - -Zilog NMOS bug of the ``ld a,i`` and ``ld a,r`` instructions ------------------------------------------------------------- - -The Z80 CPU models that use NMOS technology have a bug that causes the P/V flag to be reset when a maskable interrupt is accepted during the execution of these instructions. This affects processors manufactured by Zilog, second sources, NEC and can also be found in CMOS models from SGS-Thomson (and possibly other companies). - -Enabling the implementation of this bug adds code in the maskable interrupt response to check whether or not the previous instruction was ``ld a,i`` or ``ld a,r``, thus making the interrupt response slightly slower. - -Package maintainers should, however, enable the implementation of this bug, as there is firmware and software that depend on it. diff --git a/documentation/License.rst b/documentation/License.rst deleted file mode 100644 index 1a18021..0000000 --- a/documentation/License.rst +++ /dev/null @@ -1,11 +0,0 @@ -======= -License -======= - -Copyright © 1999-2024 Manuel Sainz de Baranda y Goñi. - -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 . diff --git a/documentation/Tests.rst b/documentation/Tests.rst deleted file mode 100644 index 9591137..0000000 --- a/documentation/Tests.rst +++ /dev/null @@ -1,3 +0,0 @@ -===== -Tests -===== diff --git a/documentation/Thanks.rst b/documentation/Thanks.rst deleted file mode 100644 index 051c7ff..0000000 --- a/documentation/Thanks.rst +++ /dev/null @@ -1,570 +0,0 @@ -====== -Thanks -====== - -.. only:: html - - .. |re| raw:: html - - - - .. |ren| raw:: html - - - -.. only:: latex - - .. |fe| raw:: latex - - \textsuperscript{ - - .. |ces| raw:: latex - - } - -Many thanks to the following individuals (in alphabetical order): - -* **Akimov, Vadim (lvd)** - - * For testing the library on many different platforms and CPU architectures. - -* **azesmbog** - - 1. For validating tests on real hardware. |re| |fe| :ref:`1.1` |ren| |ces| - 2. For discovering the unstable behavior of the ``ccf/scf`` instructions. - 3. For testing the ``ccf/scf`` instructions on real hardware. |re| |fe| :ref:`2`, :ref:`3` |ren| |ces| - 4. For his invaluable help. - -* **Banks, David (hoglet)** - - 1. For deciphering the additional flag changes of the block instructions. |re| |fe| :ref:`4.1`, :ref:`4.2`, :ref:`5` |ren| |ces| - 2. For his research on the ``ccf/scf`` instructions. |re| |fe| :ref:`5`, :ref:`6` |ren| |ces| - -* **Beliansky, Anatoly (Tolik_Trek)** - - * For validating tests on real hardware. |re| |fe| :ref:`1.2` |ren| |ces| - -* **Bobrowski, Jan** - - * For fixing the *"Z80 Full Instruction Set Exerciser for Spectrum"*. |re| |fe| :ref:`7` |ren| |ces| - -* **boo_boo** - - * For deciphering the behavior of MEMPTR. |re| |fe| :ref:`8`, :ref:`9`, :ref:`10`, :ref:`11` |ren| |ces| - -* **Brady, Stuart** - - * For his research on the ``ccf/scf`` instructions. |re| |fe| :ref:`12` |ren| |ces| - -* **Brewer, Tony** - - 1. For his research on the special RESET. |re| |fe| :ref:`4.3`, :ref:`13` |ren| |ces| - 2. For helping to decipher the additional flag changes of the block instructions. |re| |fe| :ref:`4` |ren| |ces| - 3. For conducting low-level tests on real hardware. |re| |fe| :ref:`4` |ren| |ces| - 4. For helping me to test different undocumented behaviors of the Zilog Z80. - -* **Bystrov, Dmitry (Alone Coder)** - - * For validating tests on real hardware. |re| |fe| :ref:`1.2` |ren| |ces| - -* **Chandler, Richard** - - 1. For his corrections to the documentation. - 2. For validating tests on real hardware. |re| |fe| :ref:`14` |ren| |ces| - -* **Chunin, Roman (CHRV)** - - * For testing the behavior of MEMPTR on real hardware. |re| |fe| :ref:`8`, :ref:`9`, :ref:`10`, :ref:`11` |ren| |ces| - -* **Conway, Simon (BadBeard)** - - * For validating the *"Z80 Test Suite"* on several Z80 clones. |re| |fe| :ref:`15` |ren| |ces| - -* **Cooke, Simon** - - * For discovering how the ``out (c),0`` instruction behaves on the Zilog Z80 CMOS. |re| |fe| :ref:`16` |ren| |ces| - -* **Cringle, Frank D.** - - * For writing the *"Z80 Instruction Set Exerciser"*. |re| |fe| :ref:`17` |ren| |ces| - -* **Devic, Goran** - - * For his research on undocumented behaviors of the Z80 CPU. |re| |fe| :ref:`18` |ren| |ces| - -* **Dunn, Paul (ZXDunny)** - - * For his corrections to the documentation. - -* **Equinox** - - * For his corrections to the documentation. - -* **Flammenkamp, Achim** - - * For his article on Z80 interrupts. |re| |fe| :ref:`19` |ren| |ces| - -* **Gimeno Fortea, Pedro** - - 1. For his research work. |re| |fe| :ref:`20` |ren| |ces| - 2. For writing the first-ever ZX Spectrum emulator. |re| |fe| :ref:`21`, :ref:`22` |ren| |ces| - -* **goodboy** - - * For testing the behavior of MEMPTR on real hardware. |re| |fe| :ref:`8`, :ref:`9`, :ref:`10`, :ref:`11` |ren| |ces| - -* **Greenway, Ian** - - * For testing the ``ccf/scf`` instructions on real hardware. |re| |fe| :ref:`12`, :ref:`23` |ren| |ces| - -* **Harston, Jonathan Graham** - - 1. For his research work. - 2. For his technical documents about the Zilog Z80. |re| |fe| :ref:`24`, :ref:`25`, :ref:`26` |ren| |ces| - 3. For porting the *"Z80 Instruction Set Exerciser"* to the ZX Spectrum. |re| |fe| :ref:`27` |ren| |ces| - -* **Helcmanovsky, Peter (Ped7g)** - - 1. For helping me to write the *"IN-MEMPTR"* test. - 2. For writing the *"Z80 Block Flags Test"*. |re| |fe| :ref:`1`, :ref:`28` |ren| |ces| - 3. For writing the *"Z80 CCF SCF Outcome Stability"* test. |re| |fe| :ref:`28` |ren| |ces| - 4. For writing the *"Z80 INT Skip"* test. |re| |fe| :ref:`28` |ren| |ces| - 5. For his research on the ``ccf/scf`` instructions. - 6. For his invaluable help. - -* **Iborra Debón, Víctor (Eremus)** - - * For validating tests on real hardware. - -* **icebear** - - * For testing the behavior of MEMPTR on real hardware. |re| |fe| :ref:`8`, :ref:`9`, :ref:`10`, :ref:`11` |ren| |ces| - -* **ICEknight** - - * For validating tests on real hardware. - -* **Kladov, Vladimir** - - * For deciphering the behavior of MEMPTR. |re| |fe| :ref:`8`, :ref:`9`, :ref:`10`, :ref:`11` |ren| |ces| - -* **Krook, Magnus** - - * For validating tests on real hardware. |re| |fe| :ref:`1.3` |ren| |ces| - -* **London, Matthew (mattinx)** - - * For validating tests on real hardware. - -* **Martínez Cantero, Ricardo (Kyp)** - - * For validating tests on real hardware. - -* **Molodtsov, Aleksandr** - - * For testing the behavior of MEMPTR on real hardware. |re| |fe| :ref:`8`, :ref:`9`, :ref:`10`, :ref:`11` |ren| |ces| - -* **Nair, Arjun** - - * For validating tests on real hardware. |re| |fe| :ref:`1` |ren| |ces| - -* **Nicolás-González, César** - - * For helping me to investigate the unstable behavior of the ``ccf/scf`` instructions. - -* **Ortega Sosa, Sofía** - - 1. For optimizing the emulator. - 2. For her help and support. - -* **Owen, Simon** - - * For the idea of the hooking method used in this emulator. - -* **Ownby, Matthew P.** - - * For his research on the state of the registers after POWER-ON. |re| |fe| :ref:`29` |ren| |ces| - -* **Rak, Patrik** - - 1. For improving the *"Z80 Instruction Set Exerciser for Spectrum"*. |re| |fe| :ref:`30` |ren| |ces| - 2. For deciphering the behavior of the ``ccf/scf`` instructions. |re| |fe| :ref:`15`, :ref:`30` |ren| |ces| - 3. For writing the *"Zilog Z80 CPU Test Suite"*. |re| |fe| :ref:`30`, :ref:`31` |ren| |ces| - 4. For his research on the unstable behavior of the ``ccf/scf`` instructions. - -* **Rodríguez Jódar, Miguel Ángel (mcleod_ideafix)** - - * For his research on the state of the registers after POWER-ON/RESET. |re| |fe| :ref:`32` |ren| |ces| - -* **Rodríguez Palomino, Mario (r-lyeh)** - - * For teaching me how emulators work. - -* **Sainz de Baranda y Romero, Manuel** - - * For teaching me programming and giving me my first computer. - -* **Sánchez Ordiñana, José Ismael (Vaporatorius)** - - * For validating tests on real hardware. |re| |fe| :ref:`31.1`, :ref:`33` |ren| |ces| - -* **Sevillano Mancilla, Marta (TheMartian)** - - * For validating tests on real hardware. |re| |fe| :ref:`14.1` |ren| |ces| - -* **Stevenson, Dave** - - 1. For testing the special RESET on real hardware. |re| |fe| :ref:`13` |ren| |ces| - 2. For conducting low-level tests on real hardware. |re| |fe| :ref:`4.4` |ren| |ces| - -* **Titov, Andrey (Titus)** - - * For his research on the ``ccf/scf`` instructions. |re| |fe| :ref:`2`, :ref:`3` |ren| |ces| - -* **Vučenović, Zoran** - - * For writing the Pascal binding. - -* **Weissflog, Andre (Floh)** - - 1. For discovering that the ``reti/retn`` instructions defer the acceptance of the maskable interrupt. |re| |fe| :ref:`34` |ren| |ces| - 2. For writing the *"Visual Z80 Remix"* simulator. |re| |fe| :ref:`35` |ren| |ces| - -* **Wilkinson, Oli (evolutional)** - - * For validating tests on real hardware. |re| |fe| :ref:`1` |ren| |ces| - -* **Wlodek** - - * For testing the behavior of MEMPTR on real hardware. |re| |fe| :ref:`8`, :ref:`9`, :ref:`10`, :ref:`11` |ren| |ces| - -* **Woodmass, Mark (Woody)** - - 1. For his invaluable contributions to the emuscene. - 2. For writing the *"Z80 Test Suite"*. |re| |fe| :ref:`15` |ren| |ces| - 3. For his research on the behavior of the `ccf/scf` instructions. |re| |fe| :ref:`36` |ren| |ces| - 4. For writing the *"HALT2INT"* test. - 5. For writing the *"EIHALT"* test. - -* **Young, Sean** - - 1. For his research work. - 2. For his technical documents about the Zilog Z80. |re| |fe| :ref:`20`, :ref:`29`, :ref:`37` |ren| |ces| - -* **ZXGuesser** - - * For validating tests on real hardware. - - -References -========== - -1. - - .. _r_1: - - https://spectrumcomputing.co.uk/forums/viewtopic.php?t=6102 - - 1. - - .. _r_1_1: - - https://spectrumcomputing.co.uk/forums/viewtopic.php?p=83384#p83384 - - 2. - - .. _r_1_2: - - https://spectrumcomputing.co.uk/forums/viewtopic.php?p=83041#p83041 - - 3. - - .. _r_1_3: - - https://spectrumcomputing.co.uk/forums/viewtopic.php?p=83157#p83157 - -2. - - .. _r_2: - - https://zx-pk.ru/threads/34173-revers-inzhiniring-z80.html - -3. - - .. _r_3: - - https://zx-pk.ru/threads/35936-zagadka-plavayushchikh-flagov-scf-ccf-raskryta!.html - -4. - - .. _r_4: - - https://stardot.org.uk/forums/viewtopic.php?t=15464 - - 1. - - .. _r_4_1: - - https://stardot.org.uk/forums/viewtopic.php?p=211042#p211042 - - 2. - - .. _r_4_2: - - https://stardot.org.uk/forums/viewtopic.php?p=212021#p212021 - - 3. - - .. _r_4_3: - - https://stardot.org.uk/forums/viewtopic.php?p=357136#p357136 - - 4. - - .. _r_4_4: - - https://stardot.org.uk/forums/viewtopic.php?p=212360#p212360 - -5. - - .. _r_5: - - Banks, David (2018-08-21). *"Undocumented Z80 Flags"* rev. 1.0. - - * https://stardot.org.uk/forums/download/file.php?id=39831 - * https://github.com/hoglet67/Z80Decoder/wiki/Undocumented-Flags - -6. - - .. _r_6: - - https://github.com/hoglet67/Z80Decoder/wiki/Unstable-CCF-SCF-Behaviour - -7. - - .. _r_7: - - http://wizard.ae.krakow.pl/~jb/qaop/tests.html - -8. - - .. _r_8: - - https://zxpress.ru/zxnet/zxnet.pc/5909 - -9. - - .. _r_9: - - https://zx-pk.ru/threads/2506-komanda-bit-n-(hl).html - -10. - - .. _r_10: - - https://zx-pk.ru/threads/2586-prosba-realshchikam-ot-emulyatorshchikov.html - -11. - - .. _r_11: - - boo_boo; Kladov, Vladimir (2006-03-29). *"MEMPTR, Esoteric Register of the Zilog Z80 CPU"*. - - * https://zx-pk.ru/showpost.php?p=43688 - * https://zx-pk.ru/attachment.php?attachmentid=2984 - * https://zx-pk.ru/showpost.php?p=43800 - * https://zx-pk.ru/attachment.php?attachmentid=2989 - -12. - - .. _r_12: - - https://sourceforge.net/p/fuse-emulator/mailman/message/6929573 - -13. - - .. _r_13: - - Brewer, Tony (2014-12). *"Z80 Special Reset"*. - - * http://primrosebank.net/computers/z80/z80_special_reset.htm - -14. - - .. _r_14: - - https://spectrumcomputing.co.uk/forums/viewtopic.php?t=10555 - - 1. - - .. _r_14_1: - - https://spectrumcomputing.co.uk/forums/viewtopic.php?p=132144#p132144 - -15. - - .. _r_15: - - https://worldofspectrum.org/forums/discussion/20345 - -16. - - .. _r_16: - - https://groups.google.com/g/comp.os.cpm/c/HfSTFpaIkuU/m/KotvMWu3bZoJ - -17. - - .. _r_17: - - Cringle, Frank D. (1998-01-28). *"Yaze - Yet Another Z80 Emulator"* v1.10. - - * ftp://ftp.ping.de/pub/misc/emulators/yaze-1.10.tar.gz - -18. - - .. _r_18: - - https://baltazarstudios.com/zilog-z80-undocumented-behavior - -19. - - .. _r_19: - - Flammenkamp, Achim. *"Interrupt Behaviour of the Z80 CPU"*. - - * http://z80.info/interrup.htm - -20. - - .. _r_20: - - Young, Sean (1998-10). *"Z80 Undocumented Features (in Software Behaviour)"* v0.3. - - * http://www.msxnet.org/tech/Z80/z80undoc.txt - -21. - - .. _r_21: - - https://elmundodelspectrum.com/desenterrando-el-primer-emulador-de-spectrum - -22. - - .. _r_22: - - https://elmundodelspectrum.com/con-vosotros-el-emulador-de-pedro-gimeno-1989 - -23. - - .. _r_23: - - https://sourceforge.net/p/fuse-emulator/mailman/message/4502844 - -24. - - .. _r_24: - - Harston, Jonathan Graham (2008). *"Full Z80 Opcode List Including Undocumented Opcodes"* v0.11 (revised). - - * https://mdfs.net/Docs/Comp/Z80/OpList - -25. - - .. _r_25: - - Harston, Jonathan Graham (2012). *"Z80 Microprocessor Undocumented Instructions"* v0.15. - - * https://mdfs.net/Docs/Comp/Z80/UnDocOps - -26. - - .. _r_26: - - Harston, Jonathan Graham (2014). *"Z80 Opcode Map"* v0.10 (revised). - - * https://mdfs.net/Docs/Comp/Z80/OpCodeMap - -27. - - .. _r_27: - - https://mdfs.net/Software/Z80/Exerciser/Spectrum - -28. - - .. _r_28: - - https://github.com/MrKWatkins/ZXSpectrumNextTests - -29. - - .. _r_29: - - Young, Sean (2005-09-18). *"Undocumented Z80 Documented, The"* v0.91. - - * http://www.myquest.nl/z80undocumented - * http://www.myquest.nl/z80undocumented/z80-documented-v0.91.pdf - -30. - - .. _r_30: - - https://worldofspectrum.org/forums/discussion/41704 - - * http://zxds.raxoft.cz/taps/misc/zexall2.zip - -31. - - .. _r_31: - - https://worldofspectrum.org/forums/discussion/41834 - - * http://zxds.raxoft.cz/taps/misc/z80test-1.0.zip - * https://github.com/raxoft/z80test - - 1. - - .. _r_31_1: - - https://worldofspectrum.org/forums/discussion/comment/668760/#Comment_668760 - -32. - - .. _r_32: - - https://worldofspectrum.org/forums/discussion/34574 - -33. - - .. _r_33: - - https://jisanchez.com/test-a-dos-placas-de-zx-spectrum - -34. - - .. _r_34: - - Weissflog, Andre (2021-12-17). *"New Cycle-Stepped Z80 Emulator, A"*. - - * https://floooh.github.io/2021/12/17/cycle-stepped-z80.html - -35. - - .. _r_35: - - https://github.com/floooh/v6502r - -36. - - .. _r_36: - - https://groups.google.com/g/comp.sys.sinclair/c/WPsPr6j6w5k/m/O_u1zNQf3VYJ - -37. - - .. _r_37: - - Young, Sean (1997-09-21). *"Zilog Z80 CPU Specifications"*. - - * http://www.msxnet.org/tech/Z80/z80.zip diff --git a/documentation/Usage.rst b/documentation/Usage.rst deleted file mode 100644 index a69bc5a..0000000 --- a/documentation/Usage.rst +++ /dev/null @@ -1,131 +0,0 @@ -===== -Usage -===== - -.. code-block:: c - - #include /* Z_NULL */ - #include - - #define CYCLES_PER_FRAME 69888 - #define CYCLES_AT_INT 24 - #define CYCLES_PER_INT 32 - #define ROM_SIZE 0x4000 /* 16 KiB */ - #define MEMORY_SIZE 0x8000 /* 32 KiB */ - - typedef struct { - void* context; - zuint8 (* read)(void *context); - void (* write)(void *context, zuint8 value); - zuint16 assigned_port; - } Device; - - typedef struct { - zusize cycles; - zuint8 memory[65536]; - Z80 cpu; - Device* devices; - zusize device_count; - } Machine; - - - Device *machine_find_device(Machine *self, zuint16 port) - { - zusize index = 0; - - for (; index < device_count; index++) - if (self->devices[index]->assigned_port == port) - return &self->devices[index]; - - return Z_NULL; - } - - - static zuint8 machine_cpu_read(Machine *self, zuint16 address) - { - return address < MEMORY_SIZE ? self->memory[address] : 0xFF; - } - - - static void machine_cpu_write(Machine *self, zuint16 address, zuint8 value) - { - if (address >= ROM_SIZE && address < MEMORY_SIZE) - self->memory[address] = value; - } - - - static zuint8 machine_cpu_in(Machine *self, zuint16 port) - { - Device *device = machine_find_device(self, port); - - return device != Z_NULL ? device->read(device->context) : 0xFF; - } - - - static void machine_cpu_out(Machine *self, zuint16 port, zuint8 value) - { - Device *device = machine_find_device(self, port); - - if (device != Z_NULL) device->write(device->context, value); - } - - - void machine_initialize(Machine *self) - { - self->cpu.context = self; - self->cpu.fetch_opcode = - self->cpu.fetch = - self->cpu.nop = - self->cpu.read = (Z80Read )machine_cpu_read; - self->cpu.write = (Z80Write)machine_cpu_write; - self->cpu.in = (Z80Read )machine_cpu_in; - self->cpu.out = (Z80Write)machine_cpu_out; - self->cpu.halt = Z_NULL; - self->cpu.nmia = Z_NULL; - self->cpu.inta = Z_NULL; - self->cpu.int_fetch = Z_NULL; - self->cpu.ld_i_a = Z_NULL; - self->cpu.ld_r_a = Z_NULL; - self->cpu.reti = Z_NULL; - self->cpu.retn = Z_NULL; - self->cpu.hook = Z_NULL; - self->cpu.illegal = Z_NULL; - self->cpu.options = Z80_MODEL_ZILOG_NMOS; - - /* Create and initialize devices... */ - } - - - void machine_power(Machine *self, zboolean state) - { - if (state) - { - self->cycles = 0; - memset(self->memory, 0, 65536); - } - - z80_power(&self->cpu, state); - } - - - void machine_reset(Machine *self) - { - z80_instant_reset(&self->cpu); - } - - - void machine_run_frame(Machine *self) - { - /* CPU cycles before the INT signal */ - self->cycles += z80_execute(&self->cpu, CYCLES_AT_INT - self->cycles); - - /* CPU cycles during the INT signal */ - z80_int(&self->cpu, Z_TRUE); - self->cycles += z80_run(&self->cpu, (CYCLES_AT_INT + CYCLES_PER_INT) - self->cycles); - z80_int(&self->cpu, Z_FALSE); - - /* CPU cycles after the INT signal */ - self->cycles += z80_execute(&self->cpu, CYCLES_PER_FRAME - self->cycles); - - self->cycles -= CYCLES_PER_FRAME; - }