header documentation improvements

This commit is contained in:
Robin Jones 2024-11-05 21:32:17 +00:00
parent 2fc4a6a6c1
commit fb0a04e048
3 changed files with 240 additions and 70 deletions

View File

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

View File

@ -3,37 +3,47 @@
#include <stdint.h> #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 { typedef union {
uint32_t raw; uint32_t raw; /**< Raw 32-bit instruction */
struct { struct {
uint32_t op : 6; uint32_t op : 6; /**< Opcode field */
uint32_t rs : 5; uint32_t rs : 5; /**< Source register */
uint32_t rt : 5; uint32_t rt : 5; /**< Target register */
uint32_t imm : 16; uint32_t imm : 16; /**< Immediate value */
} i_type; } i_type; /**< I-type instruction format */
struct { struct {
uint32_t op : 6; uint32_t op : 6; /**< Opcode field */
uint32_t target : 26; uint32_t target : 26; /**< Target Address field */
} j_type; } j_type; /**< J-type instruction format */
struct { struct {
uint32_t op : 6; uint32_t op : 6; /**< Opcode field */
uint32_t rs : 5; uint32_t rs : 5; /**< Source register */
uint32_t rt : 5; uint32_t rt : 5; /**< Target register */
uint32_t rd : 5; uint32_t rd : 5; /**< Destination register */
uint32_t sa : 5; uint32_t sa : 5; /**< Shift amount */
uint32_t funct : 6; uint32_t funct : 6; /**< Function field */
} r_type; } r_type; /**< Alternate R-type instruction format */
struct { struct {
uint32_t op : 6; uint32_t op : 6; /**< Opcode field */
uint32_t co : 1; uint32_t co : 1; /**< Coprocessor operation bit */
uint32_t funct : 25; uint32_t funct : 25; /**< Function field */
} c_type; } c_type; /**< C-type instruction format */
} vr4300_instruction_t; } vr4300_instruction_t;
/**
* @brief VR4300 Opcode Enumeration
*
* Enumeration for different opcodes used in VR4300 instructions.
*/
typedef enum { typedef enum {
OP_SPECIAL, OP_SPECIAL,
OP_REGIMM, 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_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) #define I_SW(rt, offset, base) __ASM_I_INST(OP_SW, base, rt, offset)
#endif #endif /* VR4300_ASM_H__ */

View File

@ -7,37 +7,166 @@
#ifndef MP3_PLAYER_H__ #ifndef MP3_PLAYER_H__
#define MP3_PLAYER_H__ #define MP3_PLAYER_H__
#include <stdbool.h> #include <stdbool.h>
/**
/** @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 { typedef enum {
MP3PLAYER_OK, MP3PLAYER_OK, /**< No error */
MP3PLAYER_ERR_OUT_OF_MEM, MP3PLAYER_ERR_OUT_OF_MEM, /**< Out of memory error */
MP3PLAYER_ERR_IO, MP3PLAYER_ERR_IO, /**< Input/Output error */
MP3PLAYER_ERR_NO_FILE, MP3PLAYER_ERR_NO_FILE, /**< No file found error */
MP3PLAYER_ERR_INVALID_FILE, MP3PLAYER_ERR_INVALID_FILE, /**< Invalid file error */
} mp3player_err_t; } mp3player_err_t;
/**
* @brief Initialize the MP3 player mixer.
*
* This function initializes the mixer for the MP3 player.
*/
void mp3player_mixer_init(void);
void mp3player_mixer_init (void); /**
mp3player_err_t mp3player_init (void); * @brief Initialize the MP3 player.
void mp3player_deinit (void); *
mp3player_err_t mp3player_load (char *path); * This function initializes the MP3 player and prepares it for playback.
void mp3player_unload (void); *
mp3player_err_t mp3player_process (void); * @return mp3player_err_t Error code indicating the result of the initialization.
bool mp3player_is_playing (void); */
bool mp3player_is_finished (void); mp3player_err_t mp3player_init(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);
/**
* @brief Deinitialize the MP3 player.
*
* This function deinitializes the MP3 player and releases any resources.
*/
void mp3player_deinit(void);
#endif /**
* @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);
#endif /* MP3_PLAYER_H__ */