header documentation improvements

src/boot/boot_io.h

@@ -7,41 +7,79 @@
 #ifndef BOOT_IO_H__
 #define BOOT_IO_H__
 
-
 #include <stddef.h>
 #include <stdint.h>
 
-
+/**
+ * @typedef io8_t
+ * @brief 8-bit volatile IO type.
+ */
 typedef volatile uint8_t io8_t;
-typedef volatile uint32_t io32_t;
 
+/**
+ * @typedef io32_t
+ * @brief 32-bit volatile IO type.
+ */
+typedef volatile uint32_t io32_t;
 
+/**
+ * @brief Convert an address to its uncached equivalent.
+ * 
+ * This macro takes an address and converts it to its uncached equivalent
+ * by setting the appropriate bits.
+ * 
+ * @param address The address to convert.
+ * @return The uncached equivalent of the address.
+ */
 #define UNCACHED(address)           ((typeof(address)) (((io32_t) (address)) | (0xA0000000UL)))
 
-/** @brief Memory Structure. */
+/**
+ * @brief Memory Structure.
+ * 
+ * This structure represents the memory layout for the SP (Signal Processor),
+ * containing both Data Memory (DMEM) and Instruction Memory (IMEM).
+ */
 typedef struct {
-    io32_t DMEM[1024];
-    io32_t IMEM[1024];
+    io32_t DMEM[1024]; /**< Data Memory (DMEM) array of 1024 32-bit words. */
+    io32_t IMEM[1024]; /**< Instruction Memory (IMEM) array of 1024 32-bit words. */
 } sp_mem_t;
 
+/**
+ * @brief Base address for SP memory.
+ */
 #define SP_MEM_BASE                 (0x04000000UL)
+
+/**
+ * @brief Pointer to the SP memory structure.
+ */
 #define SP_MEM                      ((sp_mem_t *) SP_MEM_BASE)
 
-/** @brief SP Registers Structure. */
+/**
+ * @brief SP Registers Structure.
+ * 
+ * This structure represents the registers for the SP (Signal Processor).
+ */
 typedef struct {
-    io32_t PADDR;
-    io32_t MADDR;
-    io32_t RD_LEN;
-    io32_t WR_LEN;
-    io32_t SR;
-    io32_t DMA_FULL;
-    io32_t DMA_BUSY;
-    io32_t SEMAPHORE;
+    io32_t PADDR; /**< Physical Address Register. */
+    io32_t MADDR; /**< Memory Address Register. */
+    io32_t RD_LEN; /**< Read Length Register. */
+    io32_t WR_LEN; /**< Write Length Register. */
+    io32_t SR; /**< Status Register. */
+    io32_t DMA_FULL; /**< DMA Full Register. */
+    io32_t DMA_BUSY; /**< DMA Busy Register. */
+    io32_t SEMAPHORE; /**< Semaphore Register. */
     io32_t __reserved[0xFFF8];
     io32_t PC;
 } sp_regs_t;
 
+/**
+ * @brief Base address for SP registers.
+ */
 #define SP_BASE                     (0x04040000UL)
+
+/**
+ * @brief Pointer to the SP registers structure.
+ */
 #define SP                          ((sp_regs_t *) SP_BASE)
 
 #define SP_SR_HALT                  (1 << 0)
@@ -85,7 +123,6 @@ typedef struct {
 #define SP_SR_CLR_SIG7              (1 << 23)
 #define SP_SR_SET_SIG7              (1 << 24)
 
-
 /** @brief DPC Registers Structure. */
 typedef struct {
     io32_t START;
@@ -123,7 +160,6 @@ typedef struct {
 #define DPC_SR_CLR_CMD_CTR          (1 << 8)
 #define DPC_SR_CLR_CLOCK_CTR        (1 << 9)
 
-
 /** @brief Video Interface Registers Structure. */
 typedef struct {
     /** @brief The Control Register. */
@@ -198,7 +234,6 @@ typedef struct {
 #define AI_SR_FIFO_FULL             (1 << 31)
 #define AI_CR_DMA_ON                (1 << 0)
 
-
 /** @brief Peripheral Interface Register Structure. */
 typedef struct {
     /** @brief The Memory Address. */
@@ -233,15 +268,12 @@ typedef struct {
 #define PI_SR_RESET                 (1 << 0)
 #define PI_SR_CLR_INTR              (1 << 1)
 
-
 #define ROM_DDIPL_BASE              (0x06000000UL)
 #define ROM_DDIPL                   ((io32_t *) ROM_DDIPL_BASE)
 
-
 #define ROM_CART_BASE               (0x10000000UL)
 #define ROM_CART                    ((io32_t *) ROM_CART_BASE)
 
-
 static inline uint32_t cpu_io_read (io32_t *address) {
     io32_t *uncached = UNCACHED(address);
     uint32_t value = *uncached;
@@ -253,5 +285,4 @@ static inline void cpu_io_write (io32_t *address, uint32_t value) {
     *uncached = value;
 }
 
-
-#endif
+#endif /* BOOT_IO_H__ */

src/boot/vr4300_asm.h

@@ -3,37 +3,47 @@
 
 #include <stdint.h>
 
+/**
+ * @brief VR4300 Instruction Structure
+ * 
+ * This structure represents a VR4300 instruction, which can be of different types (R-type, I-type, J-type, etc.).
+ */
 typedef union {
-    uint32_t raw;
+    uint32_t raw; /**< Raw 32-bit instruction */
 
     struct {
-        uint32_t op : 6;
-        uint32_t rs : 5;
-        uint32_t rt : 5;
-        uint32_t imm : 16;
-    } i_type;
+        uint32_t op : 6;    /**< Opcode field */
+        uint32_t rs : 5;    /**< Source register */
+        uint32_t rt : 5;    /**< Target register */
+        uint32_t imm : 16; /**< Immediate value */
+    } i_type; /**< I-type instruction format */
 
     struct {
-        uint32_t op : 6;
-        uint32_t target : 26;
-    } j_type;
+        uint32_t op : 6;    /**< Opcode field */
+        uint32_t target : 26; /**< Target Address field */
+    } j_type; /**< J-type instruction format */
 
     struct {
-        uint32_t op : 6;
-        uint32_t rs : 5;
-        uint32_t rt : 5;
-        uint32_t rd : 5;
-        uint32_t sa : 5;
-        uint32_t funct : 6;
-    } r_type;
+        uint32_t op : 6;    /**< Opcode field */
+        uint32_t rs : 5;    /**< Source register */
+        uint32_t rt : 5;    /**< Target register */
+        uint32_t rd : 5;    /**< Destination register */
+        uint32_t sa : 5;    /**< Shift amount */
+        uint32_t funct : 6; /**< Function field */
+    } r_type; /**< Alternate R-type instruction format */
 
     struct {
-        uint32_t op : 6;
-        uint32_t co : 1;
-        uint32_t funct : 25;
-    } c_type;
+        uint32_t op : 6;    /**< Opcode field */
+        uint32_t co : 1;    /**< Coprocessor operation bit */
+        uint32_t funct : 25; /**< Function field */
+    } c_type; /**< C-type instruction format */
 } vr4300_instruction_t;
 
+/**
+ * @brief VR4300 Opcode Enumeration
+ * 
+ * Enumeration for different opcodes used in VR4300 instructions.
+ */
 typedef enum {
     OP_SPECIAL,
     OP_REGIMM,
@@ -394,4 +404,4 @@ typedef enum {
 #define I_SRL(rd, rt, sa) __ASM_R_INST(OP_SPECIAL, 0, rt, rd, sa, FUNCT_SRL)
 #define I_SW(rt, offset, base) __ASM_I_INST(OP_SW, base, rt, offset)
 
-#endif
+#endif /* VR4300_ASM_H__ */