From 9e960edb677d2e4b0ae6ebc7a1272c981c22b32a Mon Sep 17 00:00:00 2001 From: Robin Jones Date: Sat, 22 Feb 2025 01:27:32 +0000 Subject: [PATCH] Add documentation 64drive --- src/flashcart/64drive/64drive.c | 66 +++++++++++++++++++++++-- src/flashcart/64drive/64drive_ll.c | 77 ++++++++++++++++++++++++++++-- 2 files changed, 133 insertions(+), 10 deletions(-) diff --git a/src/flashcart/64drive/64drive.c b/src/flashcart/64drive/64drive.c index 6419663b..272f4869 100644 --- a/src/flashcart/64drive/64drive.c +++ b/src/flashcart/64drive/64drive.c @@ -1,3 +1,9 @@ +/** + * @file 64drive.c + * @brief 64drive functions implementation + * @ingroup flashcart + */ + #include #include #include @@ -12,7 +18,6 @@ #include "64drive_ll.h" #include "64drive.h" - #define ROM_ADDRESS (0x10000000) #define SAVE_ADDRESS_DEV_A (0x13FE0000) #define SAVE_ADDRESS_DEV_A_PKST2 (0x11606560) @@ -20,11 +25,14 @@ #define SUPPORTED_FPGA_REVISION (205) - static d64_device_variant_t device_variant = DEVICE_VARIANT_UNKNOWN; static d64_save_type_t current_save_type = SAVE_TYPE_NONE; - +/** + * @brief Initialize the 64drive. + * + * @return flashcart_err_t Error code. + */ static flashcart_err_t d64_init (void) { uint16_t fpga_revision; uint32_t bootloader_version; @@ -62,6 +70,11 @@ static flashcart_err_t d64_init (void) { return FLASHCART_OK; } +/** + * @brief Deinitialize the 64drive. + * + * @return flashcart_err_t Error code. + */ static flashcart_err_t d64_deinit (void) { if (d64_ll_enable_cartrom_writes(false)) { return FLASHCART_ERR_INT; @@ -70,6 +83,12 @@ static flashcart_err_t d64_deinit (void) { return FLASHCART_OK; } +/** + * @brief Check if the 64drive has a specific feature. + * + * @param feature The feature to check. + * @return true if the feature is supported, false otherwise. + */ static bool d64_has_feature (flashcart_features_t feature) { switch (feature) { case FLASHCART_FEATURE_64DD: return false; @@ -108,6 +127,13 @@ static flashcart_firmware_version_t d64_get_firmware_version (void) { return version_info; } +/** + * @brief Load a ROM into the 64drive. + * + * @param rom_path Path to the ROM file. + * @param progress Progress callback function. + * @return flashcart_err_t Error code. + */ static flashcart_err_t d64_load_rom (char *rom_path, flashcart_progress_callback_t *progress) { FIL fil; UINT br; @@ -150,6 +176,14 @@ static flashcart_err_t d64_load_rom (char *rom_path, flashcart_progress_callback return FLASHCART_OK; } +/** + * @brief Load a file into the 64Drive. + * + * @param file_path Path to the file. + * @param rom_offset ROM offset. + * @param file_offset File offset. + * @return flashcart_err_t Error code. + */ static flashcart_err_t d64_load_file (char *file_path, uint32_t rom_offset, uint32_t file_offset) { FIL fil; UINT br; @@ -188,6 +222,12 @@ static flashcart_err_t d64_load_file (char *file_path, uint32_t rom_offset, uint return FLASHCART_OK; } +/** + * @brief Load a save file into the 64drive. + * + * @param save_path Path to the save file. + * @return flashcart_err_t Error code. + */ static flashcart_err_t d64_load_save (char *save_path) { uint8_t eeprom_contents[2048] __attribute__((aligned(8))); FIL fil; @@ -234,6 +274,12 @@ static flashcart_err_t d64_load_save (char *save_path) { return FLASHCART_OK; } +/** + * @brief Set the save type for the 64drive. + * + * @param save_type The save type. + * @return flashcart_err_t Error code. + */ static flashcart_err_t d64_set_save_type (flashcart_save_type_t save_type) { d64_save_type_t type; @@ -280,6 +326,12 @@ static flashcart_err_t d64_set_save_type (flashcart_save_type_t save_type) { return FLASHCART_OK; } +/** + * @brief Set the save writeback for the 64drive. + * + * @param save_path Path to the save file. + * @return flashcart_err_t Error code. + */ static flashcart_err_t d64_set_save_writeback (char *save_path) { uint32_t sectors[SAVE_WRITEBACK_MAX_SECTORS] __attribute__((aligned(8))); @@ -298,7 +350,7 @@ static flashcart_err_t d64_set_save_writeback (char *save_path) { return FLASHCART_OK; } - +/** @brief Flashcart structure for 64drive. */ static flashcart_t flashcart_d64 = { .init = d64_init, .deinit = d64_deinit, @@ -313,7 +365,11 @@ static flashcart_t flashcart_d64 = { .set_save_writeback = d64_set_save_writeback, }; - +/** + * @brief Get the flashcart structure for 64drive. + * + * @return flashcart_t* Pointer to the flashcart structure. + */ flashcart_t *d64_get_flashcart (void) { return &flashcart_d64; } diff --git a/src/flashcart/64drive/64drive_ll.c b/src/flashcart/64drive/64drive_ll.c index d0a02ce0..b0c9ecb7 100644 --- a/src/flashcart/64drive/64drive_ll.c +++ b/src/flashcart/64drive/64drive_ll.c @@ -1,15 +1,22 @@ +/** + * @file 64drive_ll.c + * @brief Low-level functions for 64drive + * @ingroup flashcart + */ + #include #include "../flashcart_utils.h" #include "64drive_ll.h" - #define CI_STATUS_BUSY (1 << 12) #define D64_DEVICE_VARIANT_MASK (0xFFFF) #define D64_FPGA_REVISION_MASK (0xFFFF) - +/** + * @brief Command IDs for 64drive. + */ typedef enum { CMD_ID_SET_SAVE_TYPE = 0xD0, CMD_ID_DISABLE_SAVE_WRITEBACK = 0xD1, @@ -22,10 +29,13 @@ typedef enum { CMD_ID_DISABLE_EXTENDED_MODE = 0xF9, } d64_ci_cmd_id_t; - static d64_regs_t *d64_regs = D64_REGS; - +/** + * @brief Wait for the CI (Command Interface) to become idle. + * + * @return true if a timeout occurred, false otherwise. + */ static bool d64_ll_ci_wait (void) { int timeout = 0; do { @@ -36,12 +46,25 @@ static bool d64_ll_ci_wait (void) { return false; } +/** + * @brief Send a command to the CI (Command Interface). + * + * @param id The command ID. + * @return true if a timeout occurred, false otherwise. + */ static bool d64_ll_ci_cmd (d64_ci_cmd_id_t id) { io_write((uint32_t) (&d64_regs->COMMAND), id); return d64_ll_ci_wait(); } - +/** + * @brief Get the version information of the 64drive. + * + * @param device_variant Pointer to store the device variant. + * @param fpga_revision Pointer to store the FPGA revision. + * @param bootloader_version Pointer to store the bootloader version. + * @return true if a timeout occurred, false otherwise. + */ bool d64_ll_get_version (d64_device_variant_t *device_variant, uint16_t *fpga_revision, uint32_t *bootloader_version) { if (d64_ll_ci_wait()) { return true; @@ -52,6 +75,14 @@ bool d64_ll_get_version (d64_device_variant_t *device_variant, uint16_t *fpga_re return d64_ll_ci_wait(); } +/** + * @brief Set the persistent variable storage on the 64drive. + * + * @param quick_reboot Flag indicating whether to enable quick reboot. + * @param force_tv_type The TV type to force. + * @param cic_seed The CIC seed value. + * @return true if a timeout occurred, false otherwise. + */ bool d64_ll_set_persistent_variable_storage (bool quick_reboot, d64_tv_type_t force_tv_type, uint8_t cic_seed) { if (d64_ll_ci_wait()) { return true; @@ -60,6 +91,12 @@ bool d64_ll_set_persistent_variable_storage (bool quick_reboot, d64_tv_type_t fo return d64_ll_ci_wait(); } +/** + * @brief Set the save type on the 64drive. + * + * @param save_type The save type. + * @return true if a timeout occurred, false otherwise. + */ bool d64_ll_set_save_type (d64_save_type_t save_type) { if (d64_ll_ci_wait()) { return true; @@ -68,6 +105,12 @@ bool d64_ll_set_save_type (d64_save_type_t save_type) { return d64_ll_ci_cmd(CMD_ID_SET_SAVE_TYPE); } +/** + * @brief Enable or disable save writeback on the 64drive. + * + * @param enabled Flag indicating whether to enable save writeback. + * @return true if a timeout occurred, false otherwise. + */ bool d64_ll_enable_save_writeback (bool enabled) { if (d64_ll_ci_wait()) { return true; @@ -75,6 +118,12 @@ bool d64_ll_enable_save_writeback (bool enabled) { return d64_ll_ci_cmd(enabled ? CMD_ID_ENABLE_SAVE_WRITEBACK : CMD_ID_DISABLE_SAVE_WRITEBACK); } +/** + * @brief Enable or disable cart ROM writes on the 64drive. + * + * @param enabled Flag indicating whether to enable cart ROM writes. + * @return true if a timeout occurred, false otherwise. + */ bool d64_ll_enable_cartrom_writes (bool enabled) { if (d64_ll_ci_wait()) { return true; @@ -82,6 +131,12 @@ bool d64_ll_enable_cartrom_writes (bool enabled) { return d64_ll_ci_cmd(enabled ? CMD_ID_ENABLE_CARTROM_WRITES : CMD_ID_DISABLE_CARTROM_WRITES); } +/** + * @brief Enable or disable extended mode on the 64drive. + * + * @param enabled Flag indicating whether to enable extended mode. + * @return true if a timeout occurred, false otherwise. + */ bool d64_ll_enable_extended_mode (bool enabled) { d64_ll_ci_wait(); if (enabled) { @@ -93,6 +148,12 @@ bool d64_ll_enable_extended_mode (bool enabled) { return d64_ll_ci_wait(); } +/** + * @brief Write EEPROM contents to the 64drive. + * + * @param contents Pointer to the EEPROM contents. + * @return true if a timeout occurred, false otherwise. + */ bool d64_ll_write_eeprom_contents (void *contents) { if (d64_ll_ci_wait()) { return true; @@ -101,6 +162,12 @@ bool d64_ll_write_eeprom_contents (void *contents) { return d64_ll_ci_wait(); } +/** + * @brief Write the save writeback LBA list to the 64drive. + * + * @param list Pointer to the LBA list. + * @return true if a timeout occurred, false otherwise. + */ bool d64_ll_write_save_writeback_lba_list (void *list) { if (d64_ll_ci_wait()) { return true;