From 9638a7174dc974c0bb13ea149c86a0d5d462b463 Mon Sep 17 00:00:00 2001 From: redcode Date: Tue, 12 Jul 2022 21:40:23 +0200 Subject: [PATCH] Doxygen comments. --- API/Z80.h | 202 ++++++++++++++++++++++++++---------------------------- 1 file changed, 97 insertions(+), 105 deletions(-) diff --git a/API/Z80.h b/API/Z80.h index 191bd2a..5270020 100644 --- a/API/Z80.h +++ b/API/Z80.h @@ -163,107 +163,101 @@ typedef struct { void *context; - /** @brief Callback invoked to perform an opcode fetch. + /** @brief Invoked to perform an opcode fetch. * * This callback indicates the beginning of an opcode fetch M-cycle. * The function must return the byte located at the memory address - * specified by the 2nd parameter. - * - * @attention This callback is mandatory, setting it to @c Z_NULL will - * cause the program to crash. */ + * specified by the second parameter. */ Z80Read fetch_opcode; - /** @brief Callback invoked to perform a memory read on instruction - * data. + /** @brief Invoked to perform a memory read on instruction data. * * This callback indicates the beginning of a memory read M-cycle - * during which the CPU fetches one byte of instruction data (i.e., - * one byte of the instruction that is neither a prefix nor an opcode). - * The function must return the byte located at the memory address - * specified by the 2nd parameter. - * - * @attention This callback is mandatory, setting it to @c Z_NULL will - * cause the program to crash. */ + * during which the CPU fetches one byte of instruction data (i.e., one + * byte of the instruction that is neither a prefix nor an opcode). The + * function must return the byte located at the memory address + * specified by the second parameter. */ Z80Read fetch; - /** @brief Callback invoked to perform a memory read. + /** @brief Invoked to perform a memory read. * * This callback indicates the beginning of a memory read M-cycle. The * function must return the byte located at the memory address - * specified by the 2nd parameter. - * - * @attention This callback is mandatory, setting it to @c Z_NULL will - * cause the program to crash. */ + * specified by the second parameter. */ Z80Read read; - /** @brief Callback invoked to peform a memory write. + /** @brief Invoked to peform a memory write. * * This callback indicates the beginning of a memory write M-cycle. The - * function must write the value of the 3rd parameter into the memory - * location specified by the 2nd parameter. - * - * @attention This callback is mandatory, setting it to @c Z_NULL will - * cause the program to crash. */ + * function must write the value of the third parameter into the memory + * location specified by the second parameter. */ Z80Write write; - /** @brief Callback invoked to perform an I/O port read. + /** @brief Invoked to perform an I/O port read. * * This callback indicates the beginning of an I/O read M-cycle. The * function must return the byte read from the I/O port specified by - * the 2nd parameter. - * - * @attention This callback is mandatory, setting it to @c Z_NULL will - * cause the program to crash. */ + * the second parameter. */ Z80Read in; - /** @brief Callback invoked to perform an I/O port write. + /** @brief Invoked to perform an I/O port write. * * This callback indicates the beginning of an I/O write M-cycle. The - * function must write the value of the 3rd parameter to the I/O port - * specified by the 2nd parameter. - * - * @attention This callback is mandatory, setting it to @c Z_NULL will - * cause the program to crash. */ + * function must write the value of the third parameter to the I/O port + * specified by the second parameter. */ Z80Write out; - /** @brief Callback invoked when the state of the HALT line changes. + /** @brief Invoked when the state of the HALT line changes. * * This callback indicates that the CPU is entering or exiting the HALT - * state. It is invoked after updating the value of Z80::halt_line, - * which is passed as the 2nd parameter. + * state. It is invoked after updating the value of @ref Z80::halt_line, + * which is passed as the second parameter to the function. * * When exiting the HALT state, this callback is invoked before @ref - * Z80::inta, @ref Z80::reti or @ref Z80::reset. - * - * @attention This callback is optional and must be set to @c Z_NULL - * when not used. */ + * Z80::inta, @ref Z80::reti or @ref Z80::reset. */ Z80HALT halt; - /** @brief Callback invoked to perform the disregarded opcode fetch of - * an internal NOP operation. + /** @brief Invoked to perform an opcode fetch that corresponds to an + * internal NOP. * - * @attention This callback is optional and must be set to @c Z_NULL - * when not used. */ + * This callback indicates the beginning of an internal NOP, which is + * an opcode fetch M-cycle that is generated in two situations: + * + * - During the HALT state, the CPU repeatedly executes an internal NOP + * that fetches the next opcode after @c halt without incrementing + * the PC register. This opcode is read again and again until an exit + * condition occurs. + * + * - After detecting a special reset signal, the CPU completes the + * ongoing instruction and then executes an internal NOP during which + * it zeroes the PC register. + * + * The role of this callback is analogous to the role of @ref + * Z80::fetch_opcode but the function is free to return any value + * (since the opcode is disregarded). + * + * This callback is optional. Setting it to @c Z_NULL is equivalent to + * setting the @ref Z80_OPTION_HALT_SKIP option. */ Z80Read nop; - /** @brief Callback invoked to perform the disregarded opcode fetch of - * a non-maskable interrupt acknowledge. + /** @brief Invoked to perform an opcode fetch that correspond to a + * non-maskable interrupt acknowledge M-cycle. * * @attention This callback is optional and must be set to @c Z_NULL * when not used. */ Z80Read nmia; - /** @brief Callback invoked to perform the data bus read of a maskable - * interrupt acknowledge. + /** @brief Invoked to perform the data bus read of a maskable interrupt + * acknowledge M-cycle. * * @attention This callback is optional and must be set to @c Z_NULL * when not used. */ @@ -286,23 +280,21 @@ typedef struct { Z80Reset reset; - /** @brief Callback invoked when an ld i,a instruction is - * fetched. + /** @brief Invoked when an ld i,a instruction is fetched. * * @attention This callback is optional and must be set to @c Z_NULL * when not used. */ Z80Notify ld_i_a; - /** @brief Callback invoked when an ld r,a instruction is - * fetched. + /** @brief Invoked when an ld r,a instruction is fetched. * * @attention This callback is optional and must be set to @c Z_NULL * when not used. */ Z80Notify ld_r_a; - /** @brief Callback invoked when a @c reti instruction is fetched. + /** @brief Invoked when a @c reti instruction is fetched. * * @attention This callback is optional and must be set to @c Z_NULL * when not used. */ @@ -316,15 +308,14 @@ typedef struct { Z80Notify retn; - /** @brief Callback invoked when a trap is fecthed. + /** @brief Invoked when a trap is fecthed. * * @attention This callback is optional and must be set to @c Z_NULL * when not used. */ Z80Read hook; - /** @brief Callback invoked to delegate the emulation of an illegal - * opcode. + /** @brief Invoked to delegate the emulation of an illegal opcode. * * @attention This callback is optional and must be set to @c Z_NULL * when not used. */ @@ -406,15 +397,16 @@ typedef struct { /** @brief State of the INT line. * - * Contains @c TRUE if the INT line is low, or @c FALSE otherwise. */ + * The value of this member is @c TRUE if the INT line is low; + * otherwise, @c FALSE. */ zuint8 int_line; /** @brief State of the HALT line. * - * Contains @c TRUE if the HALT line is low, or @c FALSE otherwise. - * The emulator always modifies this variable @b before invoking the - * @ref Z80::halt callback. */ + * The value of this member is @c TRUE if the HALT line is low; + * otherwise, @c FALSE. The emulator always updates this member before + * invoking the @ref Z80::halt callback. */ zuint8 halt_line; } Z80; @@ -522,171 +514,171 @@ typedef struct { #define Z80_RESUME_SPECIAL_RESET_XY 5 #define Z80_RESUME_SPECIAL_RESET_NOP 6 -/** @brief Accesses the MEMPTR register of a @ref Z80 @c object. */ +/** @brief Accesses the MEMPTR register of a @ref Z80 @p object. */ #define Z80_MEMPTR(object) (object).memptr.uint16_value -/** @brief Accesses the PC register of a @ref Z80 @c object. */ +/** @brief Accesses the PC register of a @ref Z80 @p object. */ #define Z80_PC(object) (object).pc.uint16_value -/** @brief Accesses the SP register of a @ref Z80 @c object. */ +/** @brief Accesses the SP register of a @ref Z80 @p object. */ #define Z80_SP(object) (object).sp.uint16_value -/** @brief Accesses the temporary IX/IY register of a @ref Z80 @c object */ +/** @brief Accesses the temporary IX/IY register of a @ref Z80 @p object */ #define Z80_XY(object) (object).xy.uint16_value -/** @brief Accesses the IX register of a @ref Z80 @c object. */ +/** @brief Accesses the IX register of a @ref Z80 @p object. */ #define Z80_IX(object) (object).ix.uint16_value -/** @brief Accesses the IY register of a @ref Z80 @c object. */ +/** @brief Accesses the IY register of a @ref Z80 @p object. */ #define Z80_IY(object) (object).iy.uint16_value -/** @brief Accesses the AF register of a @ref Z80 @c object. */ +/** @brief Accesses the AF register of a @ref Z80 @p object. */ #define Z80_AF(object) (object).af.uint16_value -/** @brief Accesses the BC register of a @ref Z80 @c object. */ +/** @brief Accesses the BC register of a @ref Z80 @p object. */ #define Z80_BC(object) (object).bc.uint16_value -/** @brief Accesses the DE register of a @ref Z80 @c object. */ +/** @brief Accesses the DE register of a @ref Z80 @p object. */ #define Z80_DE(object) (object).de.uint16_value -/** @brief Accesses the HL register of a @ref Z80 @c object. */ +/** @brief Accesses the HL register of a @ref Z80 @p object. */ #define Z80_HL(object) (object).hl.uint16_value -/** @brief Accesses the AF' register of a @ref Z80 @c object. */ +/** @brief Accesses the AF' register of a @ref Z80 @p object. */ #define Z80_AF_(object) (object).af_.uint16_value -/** @brief Accesses the BC' register of a @ref Z80 @c object. */ +/** @brief Accesses the BC' register of a @ref Z80 @p object. */ #define Z80_BC_(object) (object).bc_.uint16_value -/** @brief Accesses the DE' register of a @ref Z80 @c object. */ +/** @brief Accesses the DE' register of a @ref Z80 @p object. */ #define Z80_DE_(object) (object).de_.uint16_value -/** @brief Accesses the HL' register of a @ref Z80 @c object. */ +/** @brief Accesses the HL' register of a @ref Z80 @p object. */ #define Z80_HL_(object) (object).hl_.uint16_value -/** @brief Accesses the MEMPTRH register of a @ref Z80 @c object. */ +/** @brief Accesses the MEMPTRH register of a @ref Z80 @p object. */ #define Z80_MEMPTRH(object) (object).memptr.uint8_values.at_1 -/** @brief Accesses the MEMPTRL register of a @ref Z80 @c object. */ +/** @brief Accesses the MEMPTRL register of a @ref Z80 @p object. */ #define Z80_MEMPTRL(object) (object).memptr.uint8_values.at_0 -/** @brief Accesses the PCH register of a @ref Z80 @c object. */ +/** @brief Accesses the PCH register of a @ref Z80 @p object. */ #define Z80_PCH(object) (object).pc.uint8_values.at_1 -/** @brief Accesses the PCL register of a @ref Z80 @c object. */ +/** @brief Accesses the PCL register of a @ref Z80 @p object. */ #define Z80_PCL(object) (object).pc.uint8_values.at_0 -/** @brief Accesses the SPH register of a @ref Z80 @c object. */ +/** @brief Accesses the SPH register of a @ref Z80 @p object. */ #define Z80_SPH(object) (object).sp.uint8_values.at_1 -/** @brief Accesses the SPL register of a @ref Z80 @c object. */ +/** @brief Accesses the SPL register of a @ref Z80 @p object. */ #define Z80_SPL(object) (object).sp.uint8_values.at_0 -/** @brief Accesses the temporary IXH/IYH register of a @ref Z80 @c object. */ +/** @brief Accesses the temporary IXH/IYH register of a @ref Z80 @p object. */ #define Z80_XYH(object) (object).xy.uint8_values.at_1 -/** @brief Accesses the temporary IXL/IYL register of a @ref Z80 @c object. */ +/** @brief Accesses the temporary IXL/IYL register of a @ref Z80 @p object. */ #define Z80_XYL(object) (object).xy.uint8_values.at_0 -/** @brief Accesses the IXH register of a @ref Z80 @c object. */ +/** @brief Accesses the IXH register of a @ref Z80 @p object. */ #define Z80_IXH(object) (object).ix.uint8_values.at_1 -/** @brief Accesses the IXL register of a @ref Z80 @c object. */ +/** @brief Accesses the IXL register of a @ref Z80 @p object. */ #define Z80_IXL(object) (object).ix.uint8_values.at_0 -/** @brief Accesses the IYH register of a @ref Z80 @c object. */ +/** @brief Accesses the IYH register of a @ref Z80 @p object. */ #define Z80_IYH(object) (object).iy.uint8_values.at_1 -/** @brief Accesses the IYL register of a @ref Z80 @c object. */ +/** @brief Accesses the IYL register of a @ref Z80 @p object. */ #define Z80_IYL(object) (object).iy.uint8_values.at_0 -/** @brief Accesses the A register of a @ref Z80 @c object. */ +/** @brief Accesses the A register of a @ref Z80 @p object. */ #define Z80_A(object) (object).af.uint8_values.at_1 -/** @brief Accesses the F register of a @ref Z80 @c object. */ +/** @brief Accesses the F register of a @ref Z80 @p object. */ #define Z80_F(object) (object).af.uint8_values.at_0 -/** @brief Accesses the B register of a @ref Z80 @c object. */ +/** @brief Accesses the B register of a @ref Z80 @p object. */ #define Z80_B(object) (object).bc.uint8_values.at_1 -/** @brief Accesses the C register of a @ref Z80 @c object. */ +/** @brief Accesses the C register of a @ref Z80 @p object. */ #define Z80_C(object) (object).bc.uint8_values.at_0 -/** @brief Accesses the D register of a @ref Z80 @c object. */ +/** @brief Accesses the D register of a @ref Z80 @p object. */ #define Z80_D(object) (object).de.uint8_values.at_1 -/** @brief Accesses the E register of a @ref Z80 @c object. */ +/** @brief Accesses the E register of a @ref Z80 @p object. */ #define Z80_E(object) (object).de.uint8_values.at_0 -/** @brief Accesses the H register of a @ref Z80 @c object. */ +/** @brief Accesses the H register of a @ref Z80 @p object. */ #define Z80_H(object) (object).hl.uint8_values.at_1 -/** @brief Accesses the L register of a @ref Z80 @c object. */ +/** @brief Accesses the L register of a @ref Z80 @p object. */ #define Z80_L(object) (object).hl.uint8_values.at_0 -/** @brief Accesses the A' register of a @ref Z80 @c object. */ +/** @brief Accesses the A' register of a @ref Z80 @p object. */ #define Z80_A_(object) (object).af_.uint8_values.at_1 -/** @brief Accesses the F' register of a @ref Z80 @c object. */ +/** @brief Accesses the F' register of a @ref Z80 @p object. */ #define Z80_F_(object) (object).af_.uint8_values.at_0 -/** @brief Accesses the B' register of a @ref Z80 @c object. */ +/** @brief Accesses the B' register of a @ref Z80 @p object. */ #define Z80_B_(object) (object).bc_.uint8_values.at_1 -/** @brief Accesses the C' register of a @ref Z80 @c object. */ +/** @brief Accesses the C' register of a @ref Z80 @p object. */ #define Z80_C_(object) (object).bc_.uint8_values.at_0 -/** @brief Accesses the D' register of a @ref Z80 @c object. */ +/** @brief Accesses the D' register of a @ref Z80 @p object. */ #define Z80_D_(object) (object).de_.uint8_values.at_1 -/** @brief Accesses the E' register of a @ref Z80 @c object. */ +/** @brief Accesses the E' register of a @ref Z80 @p object. */ #define Z80_E_(object) (object).de_.uint8_values.at_0 -/** @brief Accesses the H' register of a @ref Z80 @c object. */ +/** @brief Accesses the H' register of a @ref Z80 @p object. */ #define Z80_H_(object) (object).hl_.uint8_values.at_1 -/** @brief Accesses the L' register of a @ref Z80 @c object. */ +/** @brief Accesses the L' register of a @ref Z80 @p object. */ #define Z80_L_(object) (object).hl_.uint8_values.at_0