Detailed error code handling

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:

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

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)
+/** @} */

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
 }

src/flash.c

@@ -11,13 +11,12 @@
 #include <target/flash.h>
 #include <private/rom_flash_config.h>
 
-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));

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;
 }