feat(log): add CXX log trace guard and ESP-IDF log implementation

CHANGELOG.md

@@ -1,5 +1,15 @@
 # ChangeLog
 
+## v0.2.2 - 2025-06-27
+
+### Enhancements:
+
+* feat(log): add CXX log trace guard and ESP-IDF log implementation
+* feat(check): add value check macros
+* feat(repo): add thread module, support configure thread
+* feat(repo): add more module, support some guard classes
+* feat(cmake): remove CXX compile options
+
 ## v0.2.1 - 2025-05-30
 
 ### Enhancements:

CMakeLists.txt

@@ -6,6 +6,7 @@ if(ESP_PLATFORM)
     idf_component_register(
         SRCS ${SRCS_C} ${SRCS_CPP}
         INCLUDE_DIRS ${SRC_DIR}
+        PRIV_REQUIRES pthread
     )
 else()
     set(COMPONENT_LIB esp-lib-utils)
@@ -16,8 +17,6 @@ endif()
 target_compile_options(${COMPONENT_LIB}
     PUBLIC
         -Wno-missing-field-initializers
-    PRIVATE
-        $<$<COMPILE_LANGUAGE:CXX>:-std=gnu++20>
 )
 
 if(NOT ESP_PLATFORM)

Kconfig

@@ -7,7 +7,7 @@ menu "ESP Library Utils Configurations"
 
     if ESP_UTILS_CONF_FILE_SKIP
         menu "Check functions"
-            choice ESP_UTILS_CONF_CHECK_HANDLE_METHOD
+            choice ESP_UTILS_CONF_CHECK_HANDLE_METHOD_CHOICE
                 prompt "Select handle method when check failed"
                 default ESP_UTILS_CHECK_HANDLE_WITH_ERROR_LOG
 
@@ -29,7 +29,23 @@ menu "ESP Library Utils Configurations"
         endmenu
 
         menu "Log functions"
-            choice ESP_UTILS_CONF_LOG_LEVEL
+            choice ESP_UTILS_CONF_LOG_IMPL_TYPE_CHOICE
+                prompt "Select log implementation"
+                default ESP_UTILS_CONF_LOG_IMPL_ESP
+
+                config ESP_UTILS_CONF_LOG_IMPL_STDLIB
+                    bool "Standard (printf)"
+
+                config ESP_UTILS_CONF_LOG_IMPL_ESP
+                    bool "ESP (ESP_LOG)"
+            endchoice
+
+            config ESP_UTILS_CONF_LOG_IMPL_TYPE
+                int
+                default 0 if ESP_UTILS_CONF_LOG_IMPL_STDLIB
+                default 1 if ESP_UTILS_CONF_LOG_IMPL_ESP
+
+            choice ESP_UTILS_CONF_LOG_LEVEL_CHOICE
                 prompt "Select global log level"
                 default ESP_UTILS_CONF_LOG_LEVEL_INFO
 
@@ -110,7 +126,7 @@ menu "ESP Library Utils Configurations"
                     default 2 if ESP_UTILS_CONF_MEM_GEN_ALLOC_TYPE_MICROPYTHON
                     default 3 if ESP_UTILS_CONF_MEM_GEN_ALLOC_TYPE_CUSTOM
 
-                choice ESP_UTILS_CONF_MEM_GEN_ALLOC_ESP_CAPS
+                choice ESP_UTILS_CONF_MEM_GEN_ALLOC_ESP_CAPS_CHOICE
                     prompt "ESP memory caps"
                     depends on ESP_UTILS_CONF_MEM_GEN_ALLOC_TYPE_ESP
                     default ESP_UTILS_CONF_MEM_GEN_ALLOC_ESP_CAPS_DEFAULT
@@ -177,7 +193,7 @@ menu "ESP Library Utils Configurations"
                     default 2 if ESP_UTILS_CONF_MEM_CXX_GLOB_ALLOC_TYPE_MICROPYTHON
                     default 3 if ESP_UTILS_CONF_MEM_CXX_GLOB_ALLOC_TYPE_CUSTOM
 
-                choice ESP_UTILS_CONF_MEM_CXX_GLOB_ALLOC_ESP_CAPS
+                choice ESP_UTILS_CONF_MEM_CXX_GLOB_ALLOC_ESP_CAPS_CHOICE
                     prompt "ESP memory caps"
                     depends on ESP_UTILS_CONF_MEM_CXX_GLOB_ALLOC_TYPE_ESP
                     default ESP_UTILS_CONF_MEM_CXX_GLOB_ALLOC_ESP_CAPS_DEFAULT

esp_utils_conf.h

@@ -22,6 +22,13 @@
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 ////////////////////////////////////////////////// Log Configurations //////////////////////////////////////////////////
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Log implementation, choose one of the following:
+ *  - ESP_UTILS_CONF_LOG_IMPL_STDLIB:      Use the standard library log implementation (printf)
+ *  - ESP_UTILS_CONF_LOG_IMPL_ESP:         Use the ESP-IDF log implementation (ESP_LOG)
+ */
+#define ESP_UTILS_CONF_LOG_IMPL_TYPE                        (ESP_UTILS_CONF_LOG_IMPL_STDLIB)
+
 /**
  * Global log level, logs with a level lower than this will not be compiled. Choose one of the following:
  *  - ESP_UTILS_LOG_LEVEL_DEBUG:   Extra information which is not necessary for normal use (values, pointers, sizes, etc)
@@ -135,7 +142,7 @@
  * 3. Patch version mismatch: No impact on functionality
  */
 #define ESP_UTILS_CONF_FILE_VERSION_MAJOR 1
-#define ESP_UTILS_CONF_FILE_VERSION_MINOR 3
+#define ESP_UTILS_CONF_FILE_VERSION_MINOR 4
 #define ESP_UTILS_CONF_FILE_VERSION_PATCH 0
 
 // *INDENT-ON*

idf_component.yml

@@ -1,4 +1,4 @@
-version: "0.2.1"
+version: "0.2.2"
 description: esp-lib-utils is a library designed for ESP SoCs to provide utility functions, including logging, checking, and memory.
 url: https://github.com/esp-arduino-libs/esp-lib-utils
 repository: https://github.com/esp-arduino-libs/esp-lib-utils.git

library.properties

@@ -1,5 +1,5 @@
 name=esp-lib-utils
-version=0.2.1
+version=0.2.2
 author=espressif
 maintainer=espressif
 sentence=esp-lib-utils is a library designed for ESP SoCs to provide utility functions, including logging, checking, and memory.

src/check/esp_utils_check.h

@@ -189,6 +189,21 @@
     } while (0)
 #endif // __cplusplus && CONFIG_COMPILER_CXX_EXCEPTIONS
 
+/**
+ * @brief Check if the value is within the range [min, max];
+ *
+ * @param x Value to check
+ * @param min Minimum acceptable value
+ * @param max Maximum acceptable value
+ */
+#define ESP_UTILS_CHECK_VALUE(x, min, max) do { \
+            __typeof__(x) _x = (x); \
+            __typeof__(min) _min = (min); \
+            __typeof__(max) _max = (max); \
+            if ((_x < _min) || (_x > _max)) { \
+            } \
+        } while(0)
+
 #else
 
 #ifndef unlikely
@@ -392,6 +407,22 @@
     } while (0)
 #endif // __cplusplus && CONFIG_COMPILER_CXX_EXCEPTIONS
 
+/**
+ * @brief Check if the value is within the range [min, max]; if not, log an error
+ *
+ * @param x Value to check
+ * @param min Minimum acceptable value
+ * @param max Maximum acceptable value
+ */
+#define ESP_UTILS_CHECK_VALUE(x, min, max) do { \
+            __typeof__(x) _x = (x);                                \
+            __typeof__(min) _min = (min);                          \
+            __typeof__(max) _max = (max);                          \
+            if ((_x < _min) || (_x > _max)) { \
+                ESP_UTILS_LOGE("Invalid value: %d, should be in range [%d, %d]", _x, _min, _max); \
+            }                                                      \
+        } while(0)
+
 #elif ESP_UTILS_CONF_CHECK_HANDLE_METHOD == ESP_UTILS_CHECK_HANDLE_WITH_ASSERT
 
 #define ESP_UTILS_CHECK_NULL_RETURN(x, ...)             assert((x) != NULL)
@@ -456,9 +487,69 @@
     } while (0)
 #endif // __cplusplus && CONFIG_COMPILER_CXX_EXCEPTIONS
 
+#define ESP_UTILS_CHECK_VALUE(x, min, max) do { \
+            __typeof__(x) _x = (x);                                \
+            __typeof__(min) _min = (min);                          \
+            __typeof__(max) _max = (max);                          \
+            assert((_x >= _min) && (_x <= _max)); \
+        } while(0)
+
 #endif // ESP_UTILS_CONF_CHECK_HANDLE_METHOD
 #endif // ESP_UTILS_CONF_CHECK_HANDLE_METHOD
 
+/**
+ * @brief Check if the value is within the range [min, max]; if not, log an error and return the specified value.
+ *
+ * @param x Value to check
+ * @param min Minimum acceptable value
+ * @param max Maximum acceptable value
+ * @param ret Value to return if the value is out of range
+ * @param fmt Format string for the error message
+ * @param ... Additional arguments for the format string
+ */
+#define ESP_UTILS_CHECK_VALUE_RETURN(x, min, max, ret, fmt, ...) do { \
+            __typeof__(x) __x = (x);                                \
+            __typeof__(min) __min = (min);                          \
+            __typeof__(max) __max = (max);                          \
+            ESP_UTILS_CHECK_VALUE(__x, __min, __max); \
+            ESP_UTILS_CHECK_FALSE_RETURN((__x >= __min) && (__x <= __max), ret, fmt, ##__VA_ARGS__); \
+        } while(0)
+
+/**
+ * @brief Check if the value is within the range [min, max]; if not, log an error and goto the specified label.
+ *
+ * @param x Value to check
+ * @param min Minimum acceptable value
+ * @param max Maximum acceptable value
+ * @param goto_tag Label to jump to if the value is out of range
+ * @param fmt Format string for the error message
+ * @param ... Additional arguments for the format string
+ */
+#define ESP_UTILS_CHECK_VALUE_GOTO(x, min, max, goto_tag, fmt, ...) do { \
+            __typeof__(x) __x = (x);                                   \
+            __typeof__(min) __min = (min);                          \
+            __typeof__(max) __max = (max);                          \
+            ESP_UTILS_CHECK_VALUE(__x, __min, __max); \
+            ESP_UTILS_CHECK_FALSE_GOTO((__x >= __min) && (__x <= __max), goto_tag, fmt, ##__VA_ARGS__); \
+        } while(0)
+
+/**
+ * @brief Check if the value is within the range [min, max]; if not, log an error and return without a value.
+ *
+ * @param x Value to check
+ * @param min Minimum acceptable value
+ * @param max Maximum acceptable value
+ * @param fmt Format string for the error message
+ * @param ... Additional arguments for the format string
+ */
+#define ESP_UTILS_CHECK_VALUE_EXIT(x, min, max, fmt, ...) do { \
+            __typeof__(x) __x = (x);                         \
+            __typeof__(min) __min = (min);                          \
+            __typeof__(max) __max = (max);                          \
+            ESP_UTILS_CHECK_VALUE(__x, __min, __max); \
+            ESP_UTILS_CHECK_FALSE_EXIT((__x >= __min) && (__x <= __max), fmt, ##__VA_ARGS__); \
+        } while(0)
+
 #ifdef __cplusplus
 #ifndef ESP_UTILS_CHECK_EXCEPTION_RETURN
 #define ESP_UTILS_CHECK_EXCEPTION_RETURN(x, ret, fmt, ...)      ((void)(x))

src/esp_lib_utils.h

@@ -18,3 +18,12 @@
 
 /* Memory */
 #include "memory/esp_utils_mem.h"
+
+#if defined(__cplusplus)
+/* Thread */
+#include "thread/esp_utils_thread.hpp"
+/* Log */
+#include "log/esp_utils_log.hpp"
+/* More */
+#include "more/esp_utils_more.hpp"
+#endif // defined(__cplusplus)

src/esp_utils_conf_kconfig.h

@@ -20,6 +20,14 @@
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 ////////////////////////////////////////////////// LOG Configurations //////////////////////////////////////////////////
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+#ifndef ESP_UTILS_CONF_LOG_IMPL_TYPE
+#   ifdef CONFIG_ESP_UTILS_CONF_LOG_IMPL_TYPE
+#       define ESP_UTILS_CONF_LOG_IMPL_TYPE      CONFIG_ESP_UTILS_CONF_LOG_IMPL_TYPE
+#   else
+#       define ESP_UTILS_CONF_LOG_IMPL_TYPE      ESP_UTILS_LOG_IMPL_STDLIB
+#   endif
+#endif
+
 #ifndef ESP_UTILS_CONF_LOG_LEVEL
 #   ifdef CONFIG_ESP_UTILS_CONF_LOG_LEVEL
 #       define ESP_UTILS_CONF_LOG_LEVEL      CONFIG_ESP_UTILS_CONF_LOG_LEVEL

src/esp_utils_types.h

@@ -13,6 +13,12 @@
 #define ESP_UTILS_CHECK_HANDLE_WITH_ERROR_LOG   (1) /*!< Print error message when check failed */
 #define ESP_UTILS_CHECK_HANDLE_WITH_ASSERT      (2) /*!< Assert when check failed */
 
+/**
+ * @brief Macros for log implementation
+ */
+#define ESP_UTILS_LOG_IMPL_STDLIB              (0) /*!< Standard (printf) */
+#define ESP_UTILS_LOG_IMPL_ESP                 (1) /*!< ESP (esp_log) */
+
 /**
  * @brief Macros for log level
  */

src/esp_utils_versions.h

@@ -8,9 +8,9 @@
 /* Library Version */
 #define ESP_UTILS_VERSION_MAJOR 0
 #define ESP_UTILS_VERSION_MINOR 2
-#define ESP_UTILS_VERSION_PATCH 1
+#define ESP_UTILS_VERSION_PATCH 2
 
 /* File `esp_utils_conf.h` */
 #define ESP_UTILS_CONF_VERSION_MAJOR 1
-#define ESP_UTILS_CONF_VERSION_MINOR 3
+#define ESP_UTILS_CONF_VERSION_MINOR 4
 #define ESP_UTILS_CONF_VERSION_PATCH 0

src/log/esp_utils_log.h

@@ -8,25 +8,23 @@
 #include <stdio.h>
 #include <string.h>
 #include "esp_utils_conf_internal.h"
+#if ESP_UTILS_CONF_LOG_IMPL_TYPE == ESP_UTILS_LOG_IMPL_STDLIB
+#   include "impl/esp_utils_log_impl_std.h"
+#elif ESP_UTILS_CONF_LOG_IMPL_TYPE == ESP_UTILS_LOG_IMPL_ESP
+#   include "impl/esp_utils_log_impl_esp.h"
+#else
+#   error "Invalid log implementation"
+#endif
 
 #ifndef ESP_UTILS_LOG_TAG
 #define ESP_UTILS_LOG_TAG "Utils"
 #endif
 
-#define ESP_UTILS_IMPL_LOGD(format, ...) printf("[D][" ESP_UTILS_LOG_TAG "][%s:%04d](%s): " format "\n", \
-                                         esp_utils_log_extract_file_name(__FILE__), __LINE__, __func__,  ##__VA_ARGS__)
-#define ESP_UTILS_IMPL_LOGI(format, ...) printf("[I][" ESP_UTILS_LOG_TAG "][%s:%04d](%s): " format "\n", \
-                                         esp_utils_log_extract_file_name(__FILE__), __LINE__, __func__,  ##__VA_ARGS__)
-#define ESP_UTILS_IMPL_LOGW(format, ...) printf("[W][" ESP_UTILS_LOG_TAG "][%s:%04d](%s): " format "\n", \
-                                         esp_utils_log_extract_file_name(__FILE__), __LINE__, __func__,  ##__VA_ARGS__)
-#define ESP_UTILS_IMPL_LOGE(format, ...) printf("[E][" ESP_UTILS_LOG_TAG "][%s:%04d](%s): " format "\n", \
-                                         esp_utils_log_extract_file_name(__FILE__), __LINE__, __func__,  ##__VA_ARGS__)
-
 #define ESP_UTILS_LOG_LEVEL(level, format, ...) do {                                                    \
-        if      (level == ESP_UTILS_LOG_LEVEL_DEBUG)   { ESP_UTILS_IMPL_LOGD(format, ##__VA_ARGS__); }  \
-        else if (level == ESP_UTILS_LOG_LEVEL_INFO)    { ESP_UTILS_IMPL_LOGI(format, ##__VA_ARGS__); }  \
-        else if (level == ESP_UTILS_LOG_LEVEL_WARNING) { ESP_UTILS_IMPL_LOGW(format, ##__VA_ARGS__); }  \
-        else if (level == ESP_UTILS_LOG_LEVEL_ERROR)   { ESP_UTILS_IMPL_LOGE(format, ##__VA_ARGS__); }  \
+        if      (level == ESP_UTILS_LOG_LEVEL_DEBUG)   { ESP_UTILS_IMPL_LOGD(ESP_UTILS_LOG_TAG, format, ##__VA_ARGS__); }  \
+        else if (level == ESP_UTILS_LOG_LEVEL_INFO)    { ESP_UTILS_IMPL_LOGI(ESP_UTILS_LOG_TAG, format, ##__VA_ARGS__); }  \
+        else if (level == ESP_UTILS_LOG_LEVEL_WARNING) { ESP_UTILS_IMPL_LOGW(ESP_UTILS_LOG_TAG, format, ##__VA_ARGS__); }  \
+        else if (level == ESP_UTILS_LOG_LEVEL_ERROR)   { ESP_UTILS_IMPL_LOGE(ESP_UTILS_LOG_TAG, format, ##__VA_ARGS__); }  \
         else { }                                                                                        \
     } while(0)
 
@@ -52,15 +50,6 @@
 #   define ESP_UTILS_LOG_TRACE_ENTER()
 #   define ESP_UTILS_LOG_TRACE_EXIT()
 #endif
-#ifdef __cplusplus
-#   if ESP_UTILS_CONF_ENABLE_LOG_TRACE
-#       define ESP_UTILS_LOG_TRACE_ENTER_WITH_THIS() ESP_UTILS_LOGD("(@%p) Enter", this)
-#       define ESP_UTILS_LOG_TRACE_EXIT_WITH_THIS()  ESP_UTILS_LOGD("(@%p) Exit", this)
-#   else
-#       define ESP_UTILS_LOG_TRACE_ENTER_WITH_THIS()
-#       define ESP_UTILS_LOG_TRACE_EXIT_WITH_THIS()
-#   endif
-#endif
 
 #ifdef __cplusplus
 extern "C" {