From fb0a04e048ed78a96c32d59397b1894f9b4aec61 Mon Sep 17 00:00:00 2001 From: Robin Jones Date: Tue, 5 Nov 2024 21:32:17 +0000 Subject: [PATCH] header documentation improvements --- src/boot/boot_io.h | 77 ++++++++++++------ src/boot/vr4300_asm.h | 52 +++++++----- src/menu/mp3_player.h | 185 +++++++++++++++++++++++++++++++++++------- 3 files changed, 242 insertions(+), 72 deletions(-) diff --git a/src/boot/boot_io.h b/src/boot/boot_io.h index 6923e4df..eb9f5cc6 100644 --- a/src/boot/boot_io.h +++ b/src/boot/boot_io.h @@ -7,41 +7,79 @@ #ifndef BOOT_IO_H__ #define BOOT_IO_H__ - #include #include - +/** + * @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__ */ diff --git a/src/boot/vr4300_asm.h b/src/boot/vr4300_asm.h index 59dfd77c..b2736e21 100644 --- a/src/boot/vr4300_asm.h +++ b/src/boot/vr4300_asm.h @@ -3,37 +3,47 @@ #include +/** + * @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__ */ diff --git a/src/menu/mp3_player.h b/src/menu/mp3_player.h index baea06bf..20f6c485 100644 --- a/src/menu/mp3_player.h +++ b/src/menu/mp3_player.h @@ -7,37 +7,166 @@ #ifndef MP3_PLAYER_H__ #define MP3_PLAYER_H__ - #include - -/** @brief MP3 file error enumeration */ +/** + * @brief MP3 file error enumeration. + * + * Enumeration for different types of errors that can occur in the MP3 player. + */ typedef enum { - MP3PLAYER_OK, - MP3PLAYER_ERR_OUT_OF_MEM, - MP3PLAYER_ERR_IO, - MP3PLAYER_ERR_NO_FILE, - MP3PLAYER_ERR_INVALID_FILE, + MP3PLAYER_OK, /**< No error */ + MP3PLAYER_ERR_OUT_OF_MEM, /**< Out of memory error */ + MP3PLAYER_ERR_IO, /**< Input/Output error */ + MP3PLAYER_ERR_NO_FILE, /**< No file found error */ + MP3PLAYER_ERR_INVALID_FILE, /**< Invalid file error */ } mp3player_err_t; +/** + * @brief Initialize the MP3 player mixer. + * + * This function initializes the mixer for the MP3 player. + */ +void mp3player_mixer_init(void); + +/** + * @brief Initialize the MP3 player. + * + * This function initializes the MP3 player and prepares it for playback. + * + * @return mp3player_err_t Error code indicating the result of the initialization. + */ +mp3player_err_t mp3player_init(void); + +/** + * @brief Deinitialize the MP3 player. + * + * This function deinitializes the MP3 player and releases any resources. + */ +void mp3player_deinit(void); + +/** + * @brief Load an MP3 file. + * + * This function loads an MP3 file from the specified path. + * + * @param path Path to the MP3 file. + * @return mp3player_err_t Error code indicating the result of the load operation. + */ +mp3player_err_t mp3player_load(char *path); + +/** + * @brief Unload the current MP3 file. + * + * This function unloads the currently loaded MP3 file. + */ +void mp3player_unload(void); + +/** + * @brief Process the MP3 player. + * + * This function processes the MP3 player, handling playback and other operations. + * + * @return mp3player_err_t Error code indicating the result of the process operation. + */ +mp3player_err_t mp3player_process(void); + +/** + * @brief Check if the MP3 player is playing. + * + * This function checks if the MP3 player is currently playing. + * + * @return true if the MP3 player is playing, false otherwise. + */ +bool mp3player_is_playing(void); + +/** + * @brief Check if the MP3 player has finished playing. + * + * This function checks if the MP3 player has finished playing the current file. + * + * @return true if the MP3 player has finished playing, false otherwise. + */ +bool mp3player_is_finished(void); + +/** + * @brief Start playback of the MP3 file. + * + * This function starts playback of the currently loaded MP3 file. + * + * @return mp3player_err_t Error code indicating the result of the play operation. + */ +mp3player_err_t mp3player_play(void); + +/** + * @brief Stop playback of the MP3 file. + * + * This function stops playback of the currently loaded MP3 file. + */ +void mp3player_stop(void); + +/** + * @brief Toggle playback of the MP3 file. + * + * This function toggles playback of the currently loaded MP3 file. + * + * @return mp3player_err_t Error code indicating the result of the toggle operation. + */ +mp3player_err_t mp3player_toggle(void); + +/** + * @brief Mute or unmute the MP3 player. + * + * This function mutes or unmutes the MP3 player. + * + * @param mute true to mute, false to unmute. + */ +void mp3player_mute(bool mute); + +/** + * @brief Seek to a specific position in the MP3 file. + * + * This function seeks to a specific position in the currently loaded MP3 file. + * + * @param seconds Number of seconds to seek. + * @return mp3player_err_t Error code indicating the result of the seek operation. + */ +mp3player_err_t mp3player_seek(int seconds); + +/** + * @brief Get the duration of the MP3 file. + * + * This function gets the duration of the currently loaded MP3 file. + * + * @return float Duration of the MP3 file in seconds. + */ +float mp3player_get_duration(void); + +/** + * @brief Get the bitrate of the MP3 file. + * + * This function gets the bitrate of the currently loaded MP3 file. + * + * @return float Bitrate of the MP3 file in kbps. + */ +float mp3player_get_bitrate(void); + +/** + * @brief Get the sample rate of the MP3 file. + * + * This function gets the sample rate of the currently loaded MP3 file. + * + * @return int Sample rate of the MP3 file in Hz. + */ +int mp3player_get_samplerate(void); + +/** + * @brief Get the current playback progress. + * + * This function gets the current playback progress of the MP3 file. + * + * @return float Current playback progress as a percentage (0.0 to 100.0). + */ +float mp3player_get_progress(void); -void mp3player_mixer_init (void); -mp3player_err_t mp3player_init (void); -void mp3player_deinit (void); -mp3player_err_t mp3player_load (char *path); -void mp3player_unload (void); -mp3player_err_t mp3player_process (void); -bool mp3player_is_playing (void); -bool mp3player_is_finished (void); -mp3player_err_t mp3player_play (void); -void mp3player_stop (void); -mp3player_err_t mp3player_toggle (void); -void mp3player_mute (bool mute); -mp3player_err_t mp3player_seek (int seconds); -float mp3player_get_duration (void); -float mp3player_get_bitrate (void); -int mp3player_get_samplerate (void); -float mp3player_get_progress (void); - - -#endif +#endif /* MP3_PLAYER_H__ */