From a58afdd925ecfef20e7bfbf004f606552643e70d Mon Sep 17 00:00:00 2001 From: Anton Maklakov Date: Sun, 31 Aug 2025 13:04:52 +0700 Subject: [PATCH] fix: clean up error codes --- example/stub_main.c | 33 ++++++++++++++++++++++++++------- example/stub_main.h | 9 ++++++--- include/esp-stub-lib/err.h | 21 +++++++++++++++++---- include/esp-stub-lib/flash.h | 14 +++++++------- src/flash.c | 3 +-- src/target/common/src/flash.c | 2 +- 6 files changed, 58 insertions(+), 24 deletions(-) diff --git a/example/stub_main.c b/example/stub_main.c index 3a649293..9d8e4345 100644 --- a/example/stub_main.c +++ b/example/stub_main.c @@ -79,12 +79,29 @@ __asm__( "j stub_main;"); #endif +const char *stub_err_str(int ret_code) +{ + switch (ret_code) { + case ESP_STUB_FAIL: + return "Generic error"; + case ESP_STUB_OK: + return "Success"; + + case STUB_LIB_FAIL: + return "Failure in the lib"; + case STUB_LIB_ERR_UNKNOWN_FLASH_ID: + return "Unknown flash ID"; + + default: + return "Unknown stub error"; + } +} + int stub_main(int cmd, ...) { va_list ap; void *flash_state = NULL; int ret = ESP_STUB_FAIL; - stub_lib_err_t rc = STUB_LIB_FAIL; /* zero bss */ for (uint32_t *p = &_bss_start; p < &_bss_end; p++) { @@ -95,20 +112,21 @@ int stub_main(int cmd, ...) STUB_LOG_INIT(); - rc = stub_lib_flash_init(&flash_state); - if (rc != STUB_LIB_OK) { - return ESP_STUB_FAIL; - } - STUB_LOGI("Command: 0x%x\n", cmd); + int lib_ret = stub_lib_flash_init(&flash_state); + if (lib_ret != STUB_LIB_OK) { + STUB_LOGE("Flash init failure: (0x%X) %s\n", lib_ret, stub_err_str(lib_ret)); + return lib_ret; + } + const struct stub_cmd_handler *handler = cmd_handlers; while (handler->handler) { if (handler->cmd == cmd) { STUB_LOGI("Executing command: %s\n", handler->name); ret = handler->handler(ap); if (ret != ESP_STUB_OK) { - STUB_LOGE("Command %s (0x%x) failed\n", handler->name, handler->cmd); + STUB_LOGE("Command %s (0x%x) failed: (0x%X) %s\n", handler->name, handler->cmd, ret, stub_err_str(ret)); goto flash_va_end; } break; @@ -118,6 +136,7 @@ int stub_main(int cmd, ...) if (!handler->handler) { STUB_LOGE("Unknown command (0x%x)!\n", cmd); + ret = ESP_STUB_ERR_CMD_NOT_SUPPORTED; } flash_va_end: diff --git a/example/stub_main.h b/example/stub_main.h index f5e83721..d3536d8f 100644 --- a/example/stub_main.h +++ b/example/stub_main.h @@ -13,6 +13,9 @@ enum esp_stub_cmd { ESP_STUB_CMD_FLASH_MAX_ID = 0x01, }; -// Stub return codes -#define ESP_STUB_OK 0 -#define ESP_STUB_FAIL -1 +// Stub return codes, all compatible with esp-stub-lib/err.h without overlap + +#define ESP_STUB_OK 0x0 // Equal to STUB_LIB_OK +#define ESP_STUB_FAIL 0x1 // Different from STUB_LIB_FAIL + +#define ESP_STUB_ERR_CMD_NOT_SUPPORTED 0x2 diff --git a/include/esp-stub-lib/err.h b/include/esp-stub-lib/err.h index 8d780261..8d047555 100644 --- a/include/esp-stub-lib/err.h +++ b/include/esp-stub-lib/err.h @@ -6,9 +6,22 @@ #pragma once -typedef int stub_lib_err_t; +/** + * @file + * @brief Error codes used in esp-stub-lib + * + * Please use int for return codes + * + * The error code range of esp-stub-lib starts at STUB_LIB_ERROR_BASE, intentionally chosen to distinguish library codes + */ -#define STUB_LIB_OK 0 // stub_lib_err_t value indicating success (no error) -#define STUB_LIB_FAIL -1 // Generic stub_lib_err_t code indicating failure +#define STUB_LIB_ERROR_BASE 0x10000000 -#define STUB_LIB_ERR_UNKNOWN_FLASH_ID 0x1 +#define STUB_LIB_OK 0 /**< Success (no error) */ +#define STUB_LIB_FAIL STUB_LIB_ERROR_BASE /**< A generic error code. Prefer specific codes instead. */ + +/** @name Specific error codes + * @{ + */ +#define STUB_LIB_ERR_UNKNOWN_FLASH_ID (STUB_LIB_ERROR_BASE + 0x1) +/** @} */ diff --git a/include/esp-stub-lib/flash.h b/include/esp-stub-lib/flash.h index b172e4ce..8ee085ad 100644 --- a/include/esp-stub-lib/flash.h +++ b/include/esp-stub-lib/flash.h @@ -34,7 +34,7 @@ extern "C" { * - STUB_LIB_OK - success * - STUB_LIB_ERR_UNKNOWN_FLASH_ID - can't get size from flash id */ -stub_lib_err_t stub_lib_flash_init(void **state); +int stub_lib_flash_init(void **state); /** * @brief Restore flash state at the end of the stub. @@ -51,12 +51,12 @@ void stub_lib_flash_deinit(const void *state); void stub_lib_flash_get_info(stub_lib_flash_info_t *info); void stub_lib_flash_info_print(const stub_lib_flash_info_t *info); -stub_lib_err_t stub_lib_flash_read_buff(uint32_t addr, void *buffer, uint32_t size); -stub_lib_err_t stub_lib_flash_write_buff(uint32_t addr, const void *buffer, uint32_t size, int encrypt); -stub_lib_err_t stub_lib_flash_erase_area(uint32_t addr, uint32_t size); -stub_lib_err_t stub_lib_flash_erase_sector(uint32_t addr); -stub_lib_err_t stub_lib_flash_erase_block(uint32_t addr); -stub_lib_err_t stub_lib_flash_erase_chip(void); +int stub_lib_flash_read_buff(uint32_t addr, void *buffer, uint32_t size); +int stub_lib_flash_write_buff(uint32_t addr, const void *buffer, uint32_t size, int encrypt); +int stub_lib_flash_erase_area(uint32_t addr, uint32_t size); +int stub_lib_flash_erase_sector(uint32_t addr); +int stub_lib_flash_erase_block(uint32_t addr); +int stub_lib_flash_erase_chip(void); #ifdef __cplusplus } diff --git a/src/flash.c b/src/flash.c index f6d1e248..10810b7b 100644 --- a/src/flash.c +++ b/src/flash.c @@ -11,13 +11,12 @@ #include #include -stub_lib_err_t stub_lib_flash_init(void **state) +int stub_lib_flash_init(void **state) { stub_target_flash_init(state); uint32_t flash_id = stub_target_flash_get_flash_id(); uint32_t flash_size = stub_target_flash_id_to_flash_size(flash_id); if (flash_size == 0) { - STUB_LOGE("Invalid flash size: 0\n"); return STUB_LIB_ERR_UNKNOWN_FLASH_ID; } STUB_LOG_TRACEF("Flash size: %d MB\n", MB(flash_size)); diff --git a/src/target/common/src/flash.c b/src/target/common/src/flash.c index 851d6954..901698ca 100644 --- a/src/target/common/src/flash.c +++ b/src/target/common/src/flash.c @@ -45,6 +45,6 @@ uint32_t stub_target_flash_id_to_flash_size(uint32_t flash_id) return 32 * 1024 * 1024; } - STUB_LOGE("Unknown flash_id: 0x%x", flash_id); + STUB_LOGE("Unknown flash_id: 0x%x\n", flash_id); return 0; }