feat: error codes as a list

Author: antmak

CMakeLists.txt

@@ -39,9 +39,10 @@ target_include_directories(${ESP_STUB_LIB}
     INTERFACE include
     PRIVATE include/esp-stub-lib
 )
-# Public within the library
+# Accessible within stub-lib (including subdirectories target/<chip> and target/common), but not from top-level client code
 include_directories(include)
 include_directories(include/esp-stub-lib)
+include_directories(include/private)
 
 # STUB_COMPILE_DEFS is optional definitions coming from the parent CMakeLists.txt
 add_compile_definitions(${STUB_COMPILE_DEFS})

example/CMakeLists.txt

@@ -27,8 +27,10 @@ file(GLOB SRC_FILES "${SRC_DIR}/*.c" "${SRC_DIR}/*.S")
 
 # Target configuration
 add_executable(${PROJECT_NAME} ${SRC_FILES})
+add_dependencies(${PROJECT_NAME} stub_lib_err_header)
 target_include_directories(${PROJECT_NAME}
     PRIVATE include
+    PRIVATE .
 )
 foreach(script ${LINKER_SCRIPTS})
     target_link_options(${PROJECT_NAME} PRIVATE -T${script})
@@ -54,3 +56,10 @@ add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
 get_filename_component(PROJECT_ROOT ${CMAKE_CURRENT_LIST_DIR}/.. ABSOLUTE)
 add_subdirectory(${PROJECT_ROOT} esp-stub-lib)
 target_link_libraries(${PROJECT_NAME} PRIVATE esp-stub-lib)
+
+add_custom_target(stub_lib_err_header
+    COMMAND ${CMAKE_COMMAND} -E copy
+            ${PROJECT_ROOT}/include/private/stub_lib_err.h
+            ${CMAKE_CURRENT_LIST_DIR}/stub_lib_err.h
+    COMMENT "Preparing stub_lib_err.h before building the stub"
+)

example/stub_main.c

@@ -11,7 +11,8 @@
 
 #include <esp-stub-lib/log.h>
 #include <esp-stub-lib/flash.h>
-#include <esp-stub-lib/err.h>
+
+#include "stub_lib_err.h"
 
 #include "stub_main.h"
 

include/esp-stub-lib/err.h

@@ -7,7 +7,8 @@
 #pragma once
 
 #include <stdint.h>
-#include "err.h"
+
+#include <stub_lib_err.h>
 
 typedef struct stub_lib_flash_info {
     uint32_t id;

include/esp-stub-lib/flash.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+// Limit error code range for stub-lib
+#define STUB_LIB_ERR_END                            0x100000
+
+#define STUB_LIB_ERROR_CODE_LIST \
+    X(STUB_LIB_OK,                                  0,                              "Operation esp-stub-lib success") \
+    X(STUB_LIB_FAIL,                                (STUB_LIB_ERR_END - 1),         "Generic esp-stub-lib failure") \
+    \
+    X(STUB_LIB_ERR_FLASH_INIT_UNKNOWN_FLASH_ID,     0x1000,                         "Unknown flash size, unknown flash id") \
+
+// Only numerical values, used in esp-stub-lib sources
+
+#define X(code_, value_, info_) code_ = value_,
+typedef enum stub_lib_err_codes {
+    STUB_LIB_ERROR_CODE_LIST
+} stub_lib_err_t;
+#undef X

include/private/stub_lib_err.h

@@ -5,8 +5,8 @@
  */
 
 #include <flash.h>
-#include <err.h>
 #include <log.h>
+#include <stub_lib_err.h>
 #include <target/flash.h>
 #include <private/rom_flash_config.h>
 
@@ -16,8 +16,7 @@ stub_lib_err_t stub_lib_flash_init(void **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_FAIL;
+        return STUB_LIB_ERR_FLASH_INIT_UNKNOWN_FLASH_ID;
     }
     STUB_LOG_TRACEF("Flash size: %d MB\n", flash_size / (1024 * 1024));
 

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