Add z80_wait, improve Doxygen documentation and update history.

Author: redcode

API/Z80.h

@@ -825,7 +825,8 @@ Z80_API void z80_int(Z80 *self, zbool state);
 Z80_API void z80_nmi(Z80 *self);
 
 /** @brief Runs a <tt>@ref Z80</tt> for a given number of clock @p cycles,
-  * executing only instructions without responding to signals.
+  * executing only instructions without responding to interrupts requests or
+  * special RESET signals.
   *
   * @param self Pointer to the object on which the function is called.
   * @param cycles Number of clock cycles to be emulated.
@@ -915,6 +916,19 @@ static Z_ALWAYS_INLINE zuint8 z80_out_cycle(Z80 const *self)
 	}
 
 
+/** @brief Sends a WAIT signal to a <tt>@ref Z80</tt>.
+  *
+  * This function should only be used inside callback functions. It adds the
+  * given number of clock @p cycles to <tt>@ref Z80::cycles</tt>, thus
+  * lengthening the ongoing emulation step.
+  *
+  * @param self Pointer to the object on which the function is called.
+  * @param cycles Duration of the WAIT signal, in clock cycles. */
+
+static Z_ALWAYS_INLINE void z80_wait(Z80 *self, zusize cycles)
+	{self->cycles += cycles;}
+
+
 Z_EXTERN_C_END
 
 #endif /* Z80_H */

HISTORY

@@ -29,88 +29,90 @@ Changes:
 16. Added the `z80_in_cycle` and `z80_out_cycle` functions for obtaining the
     clock cycle at which the I/O M-cycle begins, relative to the start of the
     instruction.
-17. Added the `z80_refresh_address` function for getting the refresh address of
+17. Added the `z80_r` function for getting the current value of the R register.
+18. Added the `z80_refresh_address` function for getting the refresh address of
     the current M1 cycle.
-18. Renamed the `z80_reset` function to `z80_instant_reset`.
-19. Added optional emulation of the special RESET, and the `z80_special_reset`
+19. Added the `z80_wait` function for inserting wait states.
+20. Renamed the `z80_reset` function to `z80_instant_reset`.
+21. Added optional emulation of the special RESET, and the `z80_special_reset`
     function.
-20. Added the `Z80::fetch_opcode` and `Z80::fetch` callbacks for performing,
+22. Added the `Z80::fetch_opcode` and `Z80::fetch` callbacks for performing,
     respectively, opcode fetch operations and memory read operations on
     instruction data.
-21. Added the `Z80::nop` callback for performing disregarded opcode fetch
+23. Added the `Z80::nop` callback for performing disregarded opcode fetch
     operations during internal NOP M-cycles.
-22. Added emulation of the NMI acknowledge M-cycle through the new `Z80::nmia`
+24. Added emulation of the NMI acknowledge M-cycle through the new `Z80::nmia`
     callback.
-23. Added emulation of the INT acknowledge M-cycle through the new `Z80::inta`
+25. Added emulation of the INT acknowledge M-cycle through the new `Z80::inta`
     callback, which replaces `Z80::int_data`.
-24. Added optional full emulation of the interrupt mode 0, along with the new
+26. Added optional full emulation of the interrupt mode 0, along with the new
     `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.
-25. Added four callbacks for notifying the execution of important instructions:
+27. Added four callbacks for notifying the execution of important instructions:
     `Z80::ld_i_a`, `Z80::ld_r_a`, `Z80::reti` and `Z80::retn`.
-26. Added hooking functionality through the `ld h,h` instruction and the new
+28. Added hooking functionality through the `ld h,h` instruction and the new
     `Z80::hook` callback.
-27. Added the `Z80::illegal` callback for delegating the emulation of illegal
+29. Added the `Z80::illegal` callback for delegating the emulation of illegal
     instructions.
-28. Added emulation options that can be configured at runtime.
-29. Removed `Z80::state`. Replaced with individual members for the registers,
+30. Added emulation options that can be configured at runtime.
+31. Removed `Z80::state`. Replaced with individual members for the registers,
     the interrupt enable flip-flops and the interrupt mode.
-30. Removed the superfluous EI flag. The previous opcode is checked instead,
+32. Removed the superfluous EI flag. The previous opcode is checked instead,
     which is faster and makes the `Z80` object smaller.
-31. Removed all module-related stuff.
-32. Added emulation of the additional flag changes performed during the extra 5
+33. Removed all module-related stuff.
+34. 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`.
-33. Added emulation of the interrupt acceptance deferral that occurs during the
+35. Added emulation of the interrupt acceptance deferral that occurs during the
     `reti` and `retn` instructions.
-34. Added MEMPTR emulation. The `bit N,(hl)` instruction now produces a correct
+36. Added MEMPTR emulation. The `bit N,(hl)` instruction now produces a correct
     value of F.
-35. Added optional emulation of Q. If enabled at compile-time, the `ccf` and
+37. Added optional emulation of Q. If enabled at compile-time, the `ccf` and
     `scf` instructions will produce a correct value of F.
-36. Added emulation of the `out (c),255` instruction (Zilog Z80 CMOS).
-37. Added optional emulation of the bug affecting the `ld a,{i|r}` instructions
+38. Added emulation of the `out (c),255` instruction (Zilog Z80 CMOS).
+39. 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.
-38. Added an optional implementation of the parity calculation for the P/V flag
+40. Added an optional implementation of the parity calculation for the P/V flag
     that performs the actual computation instead of using a table of precomputed
     values.
-39. Added an optional implementation of the `daa` instruction that uses a table
+41. Added an optional implementation of the `daa` instruction that uses a table
     of precomputed values.
-40. Increased granularity. The emulator can now stop directly after fetching a
+42. 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.
-41. Reimplemented the HALT state. The emulation should now be fully accurate.
+43. Reimplemented the HALT state. The emulation should now be fully accurate.
     HALTskip optimization is also supported.
-42. Fixed a bug in the `sll` instruction.
-43. Fixed a bug in the `INX` and `OUTX` macros affecting the S and N flags.
-44. Fixed a bug in the `OUTX` macro affecting the MSByte of the port number.
-45. Fixed the clock cycles of the `dec XY` and `in (c)` instructions.
-46. Fixed the `read_16` function so that the order of the memory read operations
+44. Fixed a bug in the `sll` instruction.
+45. Fixed a bug in the `INX` and `OUTX` macros affecting the S and N flags.
+46. Fixed a bug in the `OUTX` macro affecting the MSByte of the port number.
+47. Fixed the clock cycles of the `dec XY` and `in (c)` instructions.
+48. 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.
-47. Fixed the order in which the memory write operations are performed when the
+49. 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`.
-48. Fixed the handling of illegal instructions to avoid stack overflows in long
+50. Fixed the handling of illegal instructions to avoid stack overflows in long
     sequences of DDh/FDh prefixes.
-49. Fixed several implicit conversions to avoid warnings about loss of sign and
+51. Fixed several implicit conversions to avoid warnings about loss of sign and
     precision.
-50. Fixed some bitwise operations to avoid undefined behavior and arithmetic
+52. Fixed some bitwise operations to avoid undefined behavior and arithmetic
     right shifts on signed integers.
-51. Fixed violations of the C standard in several identifiers.
-52. Renamed the 8-bit register lists: X/Y to J/K; J/K and P/Q to O/P.
-53. Replaced all P/V overflow computation functions with a single, faster macro.
-54. Replaced all register resolution functions with macros.
-55. Replaced all `ld {J,K|O,P}` instructions that have the same destination and
+53. Fixed violations of the C standard in several identifiers.
+54. Renamed the 8-bit register lists: X/Y to J/K; J/K and P/Q to O/P.
+55. Replaced all P/V overflow computation functions with a single, faster macro.
+56. Replaced all register resolution functions with macros.
+57. 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`.
-56. Optimizations in flag computation and condition evaluation.
-57. New source code comments and improvements to existing ones.
-58. Improved code aesthetics.
-59. Other improvements, optimizations and minor changes.
+58. Optimizations in flag computation and condition evaluation.
+59. New source code comments and improvements to existing ones.
+60. Improved code aesthetics.
+61. Other improvements, optimizations and minor changes.
 
 
 Z80 v0.1 (2018-11-10)