From cc4a2f4cd75e8b8886a0b769561b68e7fdf228f8 Mon Sep 17 00:00:00 2001 From: redcode Date: Wed, 31 Oct 2018 05:40:59 +0100 Subject: [PATCH] Doxygen comments. --- API/emulation/CPU/Z80.h | 64 ++++++++++++++++++++++++++++++++--------- 1 file changed, 50 insertions(+), 14 deletions(-) diff --git a/API/emulation/CPU/Z80.h b/API/emulation/CPU/Z80.h index 92a1c39..b36409b 100644 --- a/API/emulation/CPU/Z80.h +++ b/API/emulation/CPU/Z80.h @@ -30,47 +30,83 @@ this library. If not, see . */ /** Z80 emulator instance object. */ typedef struct { - zusize cycles; /**< Cycles executed in the last call to z80_run. */ - void* context; /**< Callback functions' @c context argument. */ - ZZ80State state; /**< CPU registers and internal bits. */ - Z16Bit xy; /**< Temporaty IX/IY register for DD/FD prefixes. */ - zuint8 r7; /**< Backup of the 7th bit of the R register. */ - Z32Bit data; /**< Temporary cache of the current instruction. */ - /** Called when the CPU needs to read 8 bits from memory. + /** Number of cycles executed in the current call to @c z80_run. + * @details @c z80run sets this variable to 0 before starting to + * execute instructions and its value persists after returning. + * A callback can use this variable to know in which cycle it is + * being called. */ + + zusize cycles; + + /** The value of the first argument used when calling a callback. + * @details This variable should be initialized before using the + * emulator and can be used to reference the context or instance + * of the machine being emulated. */ + + void *context; + + /** CPU registers and internal bits. + * @details It contains the values of the CPU registers, as well as + * the interruption flip-flops, variables related to interruptions and + * other necessary flags. This is where a debugger should look for its + * data source. */ + + ZZ80State state; + + /** Temporay IX or IY register for the emulation of instructions with + * DDh or FDh prefix. */ + + Z16Bit xy; + + /** Backup of the 7th bit of the R register. + * @details The value of the R register is incremented as instructions + * are executed, but its most significant bit remains unchanged. For + * optimization reasons, this bit is saved at the beginning of the + * execution of @c z80_run and restored before returning. If an + * instruction directly affects the R register, this variable is also + * updated accordingly. */ + + zuint8 r7; + + /** Temporary fetching cache for the instruction being emulated. */ + + Z32Bit data; + + /** Callback called when the CPU needs to read 8 bits from memory. * @param context The value of the member @c context. * @param address The memory address to read. * @return The 8 bits read from memory. */ zuint8 (* read)(void *context, zuint16 address); - /** Called when the CPU needs to write 8 bits to memory. + /** Callback called when the CPU needs to write 8 bits to memory. * @param context The value of the member @c context. * @param address The memory address to write. * @param value The value to write in address. */ void (* write)(void *context, zuint16 address, zuint8 value); - /** Called when the CPU needs to read 8 bits from an I/O port. + /** Callback called when the CPU needs to read 8 bits from an I/O port. * @param context The value of the member @c context. * @param port The number of the I/O port. * @return The 8 bits read from the I/O port. */ zuint8 (* in)(void *context, zuint16 port); - /** Called when the CPU needs to write 8 bits to an I/O port. + /** Callback called when the CPU needs to write 8 bits to an I/O port. * @param context The value of the member @c context. * @param port The number of the I/O port. * @param value The value to write. */ void (* out)(void *context, zuint16 port, zuint8 value); - /** Called when the CPU starts executing a maskable interrupt and the - * interruption mode is 0. This callback must return the instruction - * that the CPU would read from the data bus in this case. + /** Callback Called when the CPU starts executing a maskable interrupt + * and the interruption mode is 0. This callback must return the + * instruction that the CPU would read from the data bus in this case. * @param context The value of the member @c context. * @return A 32-bit value containing the bytes of an instruction. The - * instruction must begin at the most significant byte of the value. */ + * instruction must begin at the most significant byte (big endian). */ zuint32 (* int_data)(void *context);