From f6128b838d84e1c3b6c69493d761895090587728 Mon Sep 17 00:00:00 2001 From: redcode Date: Sat, 13 Jan 2024 16:17:27 -0500 Subject: [PATCH] Documentation WIP. --- documentation/Installation.rst | 2 +- documentation/Integration.rst | 4 ++-- documentation/Introduction.rst | 6 +++--- documentation/Thanks.rst | 2 +- documentation/VersionHistory.rst | 14 +++++++------- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/documentation/Installation.rst b/documentation/Installation.rst index 9e6dcf93..186c3a09 100644 --- a/documentation/Installation.rst +++ b/documentation/Installation.rst @@ -178,7 +178,7 @@ The second group of package-specific options configures the source code of the l .. option:: -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. |br| |nl| + 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. |br| |nl| The default is ``NO``. Package maintainers are encouraged to use at least the following options for the shared library: diff --git a/documentation/Integration.rst b/documentation/Integration.rst index d3cc6b80..ada7ec40 100644 --- a/documentation/Integration.rst +++ b/documentation/Integration.rst @@ -70,7 +70,7 @@ The source code of the emulator can be configured at compile time by predefining .. c:macro:: Z80_WITH_LOCAL_HEADER - Tells :file:`Z80.c` to ``#include "Z80.h"`` instead of ````. + Tells :file:`Z80.c` to ``#include "Z80.h"`` instead of ````. The :ref:`optional features ` of the emulator mentioned in the ":doc:`Installation`" 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 `: @@ -100,6 +100,6 @@ The :ref:`optional features ` of the emulator me .. 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. + 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_DEPENDENCIES_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 index 367f5ea3..5d436a54 100644 --- a/documentation/Introduction.rst +++ b/documentation/Introduction.rst @@ -38,7 +38,7 @@ 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. +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). @@ -82,11 +82,11 @@ Enabling unofficial ``reti`` opcodes will configure the instructions ``ED5Dh``, Package maintainers should **never enable** unofficial ``reti`` opcodes. -Zilog NMOS bug of the ``ld a,i`` and ``ld a,r`` instructions +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. +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/Thanks.rst b/documentation/Thanks.rst index 7d1ed3ad..c043658e 100644 --- a/documentation/Thanks.rst +++ b/documentation/Thanks.rst @@ -81,7 +81,7 @@ Many thanks to the following individuals (in alphabetical order): * **Cooke, Simon** - * For discovering how the ``out (c),0`` instruction behaves on the Zilog Z80 CMOS. |re| |fe| :ref:`15` |ren| |ces| + * For discovering how the ``out (c),0`` instruction behaves on the Zilog Z80 CMOS. |re| |fe| :ref:`15` |ren| |ces| * **Cringle, Frank D.** diff --git a/documentation/VersionHistory.rst b/documentation/VersionHistory.rst index e165ca9b..880ecb95 100644 --- a/documentation/VersionHistory.rst +++ b/documentation/VersionHistory.rst @@ -34,7 +34,7 @@ This is an important update that addresses a number of issues and also includes 21. Added emulation of the INT acknowledge M-cycle through the new :c:data:`Z80::inta` callback, which replaces ``Z80::int_data``. 22. Added optional full emulation of the interrupt mode 0, along with the new :c:data:`Z80::int_fetch` callback for performing bus read operations on instruction data. If not enabled at compile-time, the old simplified emulation is built, which supports only the most typical instructions. 23. Added four callbacks for notifying the execution of important instructions: :c:data:`Z80::ld_i_a`, :c:data:`Z80::ld_r_a`, :c:data:`Z80::reti` and :c:data:`Z80::retn`. -24. Added hooking functionality through the ``ld h,h`` instruction and the new :c:data:`Z80::hook` callback. +24. Added hooking functionality through the ``ld h,h`` instruction and the new :c:data:`Z80::hook` callback. 25. Added the :c:data:`Z80::illegal` callback for delegating the emulation of illegal instructions. 26. Added :ref:`emulation options ` that can be configured at runtime. 27. Removed ``Z80::state``. Replaced with individual members for the registers, the interrupt enable flip-flops and the interrupt mode. @@ -42,18 +42,18 @@ This is an important update that addresses a number of issues and also includes 29. Removed all module-related stuff. 30. Added emulation of the additional flag changes performed during the extra 5 clock cycles of the following instructions: ``ldir``, ``lddr``, ``cpir``, ``cpdr``, ``inir``, ``indr``, ``otir`` and ``otdr``. 31. Added emulation of the interrupt acceptance deferral that occurs during the ``reti`` and ``retn`` instructions. -32. Added MEMPTR emulation. The ``bit N,(hl)`` instruction now produces a correct value of F. +32. Added MEMPTR emulation. The ``bit N,(hl)`` instruction now produces a correct value of F. 33. Added optional emulation of Q. If enabled at compile-time, the ``ccf`` and ``scf`` instructions will produce a correct value of F. -34. Added emulation of the ``out (c),255`` instruction (Zilog Z80 CMOS). -35. Added optional emulation of the bug affecting the ``ld a,{i|r}`` instructions (Zilog Z80 NMOS). If enabled at compile-time and configured at runtime, the P/V flag will be reset if an INT is accepted during the execution of these instructions. +34. Added emulation of the ``out (c),255`` instruction (Zilog Z80 CMOS). +35. Added optional emulation of the bug affecting the ``ld a,{i|r}`` instructions (Zilog Z80 NMOS). If enabled at compile-time and configured at runtime, the P/V flag will be reset if an INT is accepted during the execution of these instructions. 36. Increased granularity. The emulator can now stop directly after fetching a prefix ``DDh`` or ``FDh`` if it runs out of clock cycles. This also works during the INT response in mode 0. 37. Reimplemented the HALT state. The emulation should now be fully accurate. HALTskip optimization is also supported. 38. Fixed a bug in the ``sll`` instruction. 39. Fixed a bug in the ``INX`` and ``OUTX`` macros affecting the S and N flags. 40. Fixed a bug in the ``OUTX`` macro affecting the MSByte of the port number. -41. Fixed the clock cycles of the ``dec XY`` and ``in (c)`` instructions. +41. Fixed the clock cycles of the ``dec XY`` and ``in (c)`` instructions. 42. Fixed the ``read_16`` function so that the order of the memory read operations is not determined by the order in which the compiler evaluates expressions. -43. Fixed the order in which the memory write operations are performed when the SP register is involved. This affects the NMI response, the INT response in modes 1 and 2, and the following instructions: ``ex (sp),{hl|XY}``, ``push TT``, ``push XY``, ``call WORD``, ``call Z,WORD`` and ``rst N``. +43. Fixed the order in which the memory write operations are performed when the SP register is involved. This affects the NMI response, the INT response in modes 1 and 2, and the following instructions: ``ex (sp),{hl|XY}``, ``push TT``, ``push XY``, ``call WORD``, ``call Z,WORD`` and ``rst N``. 44. Fixed the handling of illegal instructions to avoid stack overflows in long sequences of ``DDh/FDh`` prefixes. 45. Fixed several implicit conversions to avoid warnings about loss of sign and precision. 46. Fixed some bitwise operations to avoid undefined behavior and arithmetic right shifts on signed integers. @@ -61,7 +61,7 @@ This is an important update that addresses a number of issues and also includes 48. Renamed the 8-bit register lists: ``X/Y`` to ``J/K``; ``J/K`` and ``P/Q`` to ``O/P``. 49. Replaced all P/V overflow computation functions with a single, faster macro. 50. Replaced all register resolution functions with macros. -51. Replaced all ``ld {J,K|O,P}`` instructions that have the same destination and source register with NOPs. In addition, the "illegal" forms of the following instructions are now executed without using the illegal instruction handler: ``ld O,P``, ``ld O,BYTE``, ``U [a,]P`` and ``V O``. +51. Replaced all ``ld {J,K|O,P}`` instructions that have the same destination and source register with NOPs. In addition, the "illegal" forms of the following instructions are now executed without using the illegal instruction handler: ``ld O,P``, ``ld O,BYTE``, ``U [a,]P`` and ``V O``. 52. Optimizations in flag computation and condition evaluation. 53. New source code comments and improvements to existing ones. 54. Improved code aesthetics.