Merge branch 'feature/logv2_preliminary' into 'master'

feat(log): Some simple changes in log to prepare it for log v2

See merge request espressif/esp-idf!35289

components/esp_rom/include/esp_rom_sys.h

@@ -53,6 +53,34 @@ int esp_rom_printf(const char *fmt, ...);
  */
 int esp_rom_vprintf(const char *fmt, va_list ap);
 
+/**
+ * @brief Convert an unsigned integer value to a string representation in the specified radix.
+ *
+ * This function converts the given unsigned integer value to a string representation in the specified radix.
+ * The resulting string is stored in the provided character buffer `buf`.
+ *
+ * @param[in] val    The unsigned integer value to be converted.
+ * @param[in] radix  The base of the numeral system to be used for the conversion.
+ *                   It determines the number of unique digits in the numeral system
+ *                   (e.g., 2 for binary, 10 for decimal, 16 for hexadecimal).
+ * @param[in] pad    The optional padding width (0 - unused) for the resulting string. It adds zero-padding.
+ *                   (val=123, pad=6 -> result=000123).
+ * @param[in] digits Pointer to a character array representing the digits of the
+ *                   numeral system. The array must contain characters in the order of increasing
+ *                   values, corresponding to the digits of the radix. For example, "0123456789ABCDEF"
+ *                   or hexadecimal.
+ * @param[out] buf   Pointer to the character buffer where the resulting string will
+ *                   be stored. The buffer must have enough space to accommodate the entire converted
+ *                   string, including the null-terminator.
+ *
+ * @return The length of the resulting string (excluding the null-terminator).
+ *
+ * @note The buffer `buf` must have sufficient space to hold the entire converted string, including the null-terminator.
+ *       The caller is responsible for ensuring the buffer's size is large enough to prevent buffer overflow.
+ * @note The provided `digits` array must have enough elements to cover the entire radix used for conversion. Otherwise, undefined behavior may occur.
+ */
+int esp_rom_cvt(unsigned long long val, long radix, int pad, const char *digits, char *buf);
+
 /**
  * @brief Pauses execution for us microseconds
  *

components/esp_rom/patches/esp_rom_print.c

@@ -14,34 +14,52 @@
 #include "rom/ets_sys.h"
 #include "sdkconfig.h"
 
-#if !ESP_ROM_HAS_VPRINTF_FUNC
+int esp_rom_cvt(unsigned long long val, long radix, int pad, const char *digits, char *buf)
-static int _cvt(unsigned long long val, char *buf, long radix, const char *digits)
 {
-#ifdef SUPPORT_LITTLE_RADIX
+    char *orig_buf = buf;
-    char temp[64];
-#else
-    char temp[32];
-#endif
-    char *cp = temp;
     int length = 0;
 
-    if (val == 0) {
+    if (radix <= 0 || digits == NULL || buf == NULL) {
-        /* Special case */
+        return 0;
-        *cp++ = '0';
+    }
-    } else {
+
-        while (val) {
+    // The comments below show an example of the conversion process for val = 123 and pad = 6
-            *cp++ = digits[val % radix];
+    do {
+        *buf++ = digits[val % radix];
         val /= radix;
-        }
+        length++;
-    }
+    } while (val);
-    while (cp != temp) {
+    //        3   2   1
-        *buf++ = *--cp;
+    // buf = [0] [1] [2] [3]
+
+    // length = 3, pad = 6
+    while (pad > 0 && pad > length) {
+        *buf++ = '0';
         length++;
     }
     *buf = '\0';
+    // length = 6
+    //        3   2   1   0   0   0  \0
+    // buf = [0] [1] [2] [3] [4] [5] [6]
+
+    --buf;
+    // reverse the order of characters
+    //             3   2   1   0   0   0  \0
+    //            [0] [1] [2] [3] [4] [5] [6]
+    // orig_buf -- ^                   ^ ----- buf
+    while (orig_buf < buf) {
+        char first_char = *orig_buf;
+        char last_char = *buf;
+        *buf-- = first_char;
+        *orig_buf++ = last_char;
+    }
+    //        0   0   0   1   2   3  \0
+    // buf = [0] [1] [2] [3] [4] [5] [6]
+
     return (length);
 }
 
+#if !ESP_ROM_HAS_VPRINTF_FUNC
 #define is_digit(c) ((c >= '0') && (c <= '9'))
 static int ets_vprintf(void (*putc)(char c), const char *fmt, va_list ap)
 {
@@ -151,14 +169,14 @@ static int ets_vprintf(void (*putc)(char c), const char *fmt, va_list ap)
                 case 'D':
                 case 'u':
                 case 'U':
-                    length = _cvt(val, buf, 10, "0123456789");
+                    length = esp_rom_cvt(val, 10, 0, "0123456789", buf);
                     break;
                 case 'p':
                 case 'x':
-                    length = _cvt(val, buf, 16, "0123456789abcdef");
+                    length = esp_rom_cvt(val, 16, 0, "0123456789abcdef", buf);
                     break;
                 case 'X':
-                    length = _cvt(val, buf, 16, "0123456789ABCDEF");
+                    length = esp_rom_cvt(val, 16, 0, "0123456789ABCDEF", buf);
                     break;
                 }
                 cp = buf;

components/log/include/esp_log.h

@@ -15,55 +15,13 @@
 #include "esp_log_color.h"
 #include "esp_log_buffer.h"
 #include "esp_log_timestamp.h"
+#include "esp_log_write.h"
+#include "esp_log_format.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-typedef int (*vprintf_like_t)(const char *, va_list);
-
-/**
- * @brief Set function used to output log entries
- *
- * By default, log output goes to UART0. This function can be used to redirect log
- * output to some other destination, such as file or network. Returns the original
- * log handler, which may be necessary to return output to the previous destination.
- *
- * @note Please note that function callback here must be re-entrant as it can be
- * invoked in parallel from multiple thread context.
- *
- * @param func new Function used for output. Must have same signature as vprintf.
- *
- * @return func old Function used for output.
- */
-vprintf_like_t esp_log_set_vprintf(vprintf_like_t func);
-
-/**
- * @brief Write message into the log
- *
- * This function is not intended to be used directly. Instead, use one of
- * ESP_LOGE, ESP_LOGW, ESP_LOGI, ESP_LOGD, ESP_LOGV macros.
- *
- * This function or these macros should not be used from an interrupt.
- */
-void esp_log_write(esp_log_level_t level, const char* tag, const char* format, ...) __attribute__((format(printf, 3, 4)));
-
-/**
- * @brief Write message into the log, va_list variant
- * @see esp_log_write()
- *
- * This function is provided to ease integration toward other logging framework,
- * so that esp_log can be used as a log sink.
- */
-void esp_log_writev(esp_log_level_t level, const char* tag, const char* format, va_list args);
-
-/** @cond */
-
-#define LOG_FORMAT(letter, format)  LOG_COLOR_ ## letter #letter " (%" PRIu32 ") %s: " format LOG_RESET_COLOR "\n"
-#define LOG_SYSTEM_TIME_FORMAT(letter, format)  LOG_COLOR_ ## letter #letter " (%s) %s: " format LOG_RESET_COLOR "\n"
-
-/** @endcond */
-
 /// macro to output logs in startup code, before heap allocator and syscalls have been initialized.
 /// Log at ``ESP_LOG_ERROR`` level. @see ``printf``,``ESP_LOGE``,``ESP_DRAM_LOGE``
 
@@ -244,7 +202,6 @@ void esp_log_writev(esp_log_level_t level, const char* tag, const char* format,
 #endif // !(defined(__cplusplus) && (__cplusplus >  201703L))
 
 /** @cond */
-#define _ESP_LOG_DRAM_LOG_FORMAT(letter, format)  DRAM_STR(#letter " %s: " format "\n")
 
 #if defined(__cplusplus) && (__cplusplus >  201703L)
 #define ESP_DRAM_LOG_IMPL(tag, format, log_level, log_tag_letter, ...) do {                                  \

components/log/include/esp_log_buffer.h

@@ -80,7 +80,7 @@ void esp_log_buffer_hexdump_internal(const char *tag, const void *buffer, uint16
  * @param  level    Log level
  */
 #define ESP_LOG_BUFFER_HEX_LEVEL(tag, buffer, buff_len, level) \
-    do { if (LOG_LOCAL_LEVEL >= (level)) {esp_log_buffer_hex_internal(tag, buffer, buff_len, level);} } while(0)
+    do { if (ESP_LOG_ENABLED(level)) {esp_log_buffer_hex_internal(tag, buffer, buff_len, level);} } while(0)
 
 /**
  * @brief Log a buffer of characters at specified level, separated into 16 bytes each line. Buffer should contain only printable characters.
@@ -100,7 +100,7 @@ void esp_log_buffer_hexdump_internal(const char *tag, const void *buffer, uint16
  *
  */
 #define ESP_LOG_BUFFER_CHAR_LEVEL(tag, buffer, buff_len, level) \
-    do { if (LOG_LOCAL_LEVEL >= (level)) {esp_log_buffer_char_internal(tag, buffer, buff_len, level);} } while(0)
+    do { if (ESP_LOG_ENABLED(level)) {esp_log_buffer_char_internal(tag, buffer, buff_len, level);} } while(0)
 
 /**
  * @brief Dump a buffer to the log at specified level.
@@ -121,7 +121,7 @@ void esp_log_buffer_hexdump_internal(const char *tag, const void *buffer, uint16
  * @param level     Log level.
  */
 #define ESP_LOG_BUFFER_HEXDUMP(tag, buffer, buff_len, level) \
-    do { if (LOG_LOCAL_LEVEL >= (level)) {esp_log_buffer_hexdump_internal(tag, buffer, buff_len, level);} } while(0)
+    do { if (ESP_LOG_ENABLED(level)) {esp_log_buffer_hexdump_internal(tag, buffer, buff_len, level);} } while(0)
 
 /**
  * @brief Log a buffer of hex bytes at Info level
@@ -134,7 +134,7 @@ void esp_log_buffer_hexdump_internal(const char *tag, const void *buffer, uint16
  *
  */
 #define ESP_LOG_BUFFER_HEX(tag, buffer, buff_len) \
-    do { if (LOG_LOCAL_LEVEL >= ESP_LOG_INFO) {ESP_LOG_BUFFER_HEX_LEVEL(tag, buffer, buff_len, ESP_LOG_INFO);} } while(0)
+    do { if (ESP_LOG_ENABLED(ESP_LOG_INFO)) {ESP_LOG_BUFFER_HEX_LEVEL(tag, buffer, buff_len, ESP_LOG_INFO);} } while(0)
 
 /**
  * @brief Log a buffer of characters at Info level. Buffer should contain only printable characters.
@@ -147,7 +147,7 @@ void esp_log_buffer_hexdump_internal(const char *tag, const void *buffer, uint16
  *
  */
 #define ESP_LOG_BUFFER_CHAR(tag, buffer, buff_len) \
-    do { if (LOG_LOCAL_LEVEL >= ESP_LOG_INFO) {ESP_LOG_BUFFER_CHAR_LEVEL(tag, buffer, buff_len, ESP_LOG_INFO);} } while(0)
+    do { if (ESP_LOG_ENABLED(ESP_LOG_INFO)) {ESP_LOG_BUFFER_CHAR_LEVEL(tag, buffer, buff_len, ESP_LOG_INFO);} } while(0)
 
 /** @cond */
 /**

components/log/include/esp_log_format.h

@@ -0,0 +1,22 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @cond */
+// For backward compatibility (these macros are not used in the log v2).
+#define LOG_FORMAT(letter, format)  LOG_COLOR_ ## letter #letter " (%" PRIu32 ") %s: " format LOG_RESET_COLOR "\n"
+#define _ESP_LOG_DRAM_LOG_FORMAT(letter, format)  DRAM_STR(#letter " %s: " format "\n")
+#define LOG_SYSTEM_TIME_FORMAT(letter, format)  LOG_COLOR_ ## letter #letter " (%s) %s: " format LOG_RESET_COLOR "\n"
+/** @endcond */
+
+#ifdef __cplusplus
+}
+#endif

components/log/include/esp_log_level.h

@@ -7,6 +7,7 @@
 #pragma once
 
 #include <stdint.h>
+#include "esp_assert.h"
 #include "sdkconfig.h"
 
 #ifdef __cplusplus
@@ -26,7 +27,11 @@ typedef enum {
     ESP_LOG_MAX     = 6,    /*!< Number of levels supported */
 } esp_log_level_t;
 
+#define ESP_LOG_LEVEL_LEN   (3) /*!< Number of bits used to represent the log level */
+#define ESP_LOG_LEVEL_MASK  ((1 << ESP_LOG_LEVEL_LEN) - 1) /*!< Mask for log level */
+
 /** @cond */
+ESP_STATIC_ASSERT(ESP_LOG_MAX <= ESP_LOG_LEVEL_MASK, "Log level items of esp_log_level_t must fit ESP_LOG_LEVEL_MASK");
 
 // LOG_LOCAL_LEVEL controls what log levels are included in the binary.
 #ifndef LOG_LOCAL_LEVEL
@@ -39,6 +44,19 @@ typedef enum {
 #endif
 #endif // LOG_LOCAL_LEVEL
 
+/**
+ * @brief Check if a specific log level is enabled at compile-time.
+ *
+ * This macro checks whether logging for the specified log level is enabled based on the
+ * current local log level setting (`LOG_LOCAL_LEVEL`). It uses a compile-time check to
+ * determine if logging for the specified level should be included in the binary,
+ * helping to exclude logs that are not configured.
+ *
+ * @param level log level.
+ * @return true if the specified log level is enabled, false otherwise.
+ */
+#define ESP_LOG_ENABLED(level) (LOG_LOCAL_LEVEL >= (level))
+
 #if NON_OS_BUILD
 
 #define _ESP_LOG_ENABLED(log_level) (LOG_LOCAL_LEVEL >= (log_level))

components/log/include/esp_log_write.h

@@ -0,0 +1,72 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdarg.h>
+#include "esp_log_level.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef int (*vprintf_like_t)(const char *, va_list);
+
+/**
+ * @brief Set function used to output log entries
+ *
+ * By default, log output goes to UART0. This function can be used to redirect log
+ * output to some other destination, such as file or network. Returns the original
+ * log handler, which may be necessary to return output to the previous destination.
+ *
+ * @note Please note that function callback here must be re-entrant as it can be
+ * invoked in parallel from multiple tasks context.
+ *
+ * @param func new Function used for output. Must have same signature as vprintf.
+ *
+ * @return func old Function used for output.
+ */
+vprintf_like_t esp_log_set_vprintf(vprintf_like_t func);
+
+/**
+ * @brief Write message into the log
+ *
+ * This function is not intended to be used directly. Instead, use one of
+ * ESP_LOGE, ESP_LOGW, ESP_LOGI, ESP_LOGD, ESP_LOGV macros.
+ *
+ * This function or these macros should not be used from an interrupt.
+ *
+ * This function does not add any formatting elements such as color, timestamp, or tag.
+ * It checks the level and tag level. If logging is allowed then it outputs it as is.
+ *
+ * @param level     Log level of the message.
+ * @param tag       It is used to check whether logging is enabled for that tag (depends on CONFIG_LOG_TAG_LEVEL_IMPL).
+ * @param format    The format string for the log message. It has to be fully formatted, no additional formatting items will be added.
+ * @param ...       Optional arguments to be formatted according to the format string.
+ */
+void esp_log_write(esp_log_level_t level, const char* tag, const char* format, ...) __attribute__((format(printf, 3, 4)));
+
+/**
+ * @brief Write message into the log, va_list variant
+ * @see esp_log_write()
+ *
+ * This function is provided to ease integration toward other logging framework,
+ * so that esp_log can be used as a log sink.
+ *
+ * This function does not add any formatting elements such as color, timestamp, or tag.
+ * It checks the level and tag level. If logging is allowed then it outputs it as is.
+ *
+ * @param level     Log level of the message.
+ * @param tag       It is used to check whether logging is enabled for that tag (depends on CONFIG_LOG_TAG_LEVEL_IMPL).
+ * @param format    The format string for the log message. It has to be fully formatted, no additional formatting items will be added.
+ * @param args      List of arguments.
+ */
+void esp_log_writev(esp_log_level_t level, const char* tag, const char* format, va_list args);
+
+#ifdef __cplusplus
+}
+#endif

components/log/src/buffer/log_buffers.c

@@ -6,6 +6,7 @@
 
 #include <string.h>
 #include <stdbool.h>
+#include <sys/param.h>
 #include "esp_log.h"
 #include "esp_private/log_util.h"
 
@@ -73,7 +74,7 @@ static void print_buffer(const char *tag, const void *buffer, uint16_t buff_len,
 
     do {
         const char *ptr_line = buffer;
-        int bytes_cur_line = (buff_len > BYTES_PER_LINE) ? BYTES_PER_LINE : buff_len;
+        int bytes_cur_line = MIN(BYTES_PER_LINE, buff_len);
         if (!esp_ptr_byte_accessible(buffer)) {
             //use memcpy to get around alignment issue
             memcpy(temp_buffer, buffer, (bytes_cur_line + 3) / 4 * 4);
@@ -92,11 +93,13 @@ static void log_buffer_hex_line(uintptr_t orig_buff, const void *ptr_line, char
 {
     (void) orig_buff;
     const unsigned char *ptr = (unsigned char *)ptr_line;
-    for (int i = 0; i < buff_len; i++) {
+    int i;
+    for (i = 0; i < buff_len - 1; i++) {
         output_str += esp_log_util_cvt_hex(ptr[i], 2, output_str);
         *output_str++ = ' ';
     }
-    *--output_str = 0;
+    output_str += esp_log_util_cvt_hex(ptr[i], 2, output_str);
+    *output_str = '\0';
 }
 
 static void log_buffer_char_line(uintptr_t orig_buff, const void *ptr_line, char *output_str, int buff_len)

components/log/src/log_level/tag_log_level/cache/log_binary_heap.c

@@ -56,12 +56,12 @@
 
 ESP_STATIC_ASSERT(((CONFIG_LOG_TAG_LEVEL_IMPL_CACHE_SIZE & (CONFIG_LOG_TAG_LEVEL_IMPL_CACHE_SIZE + 1)) == 0), "Number of tags to be cached must be 2**n - 1, n >= 2. [1, 3, 7, 15, 31, 63, 127, 255, ...]");
 #define TAG_CACHE_SIZE (CONFIG_LOG_TAG_LEVEL_IMPL_CACHE_SIZE)
-#define MAX_GENERATION ((1 << 29) - 1)
+#define MAX_GENERATION ((1 << (32 - ESP_LOG_LEVEL_LEN)) - 1)
 
 typedef struct {
     const char *tag;
-    uint32_t level : 3;
+    uint32_t level : ESP_LOG_LEVEL_LEN;
-    uint32_t generation : 29; // this size should be the same in MAX_GENERATION
+    uint32_t generation : (32 - ESP_LOG_LEVEL_LEN); // this size should be the same in MAX_GENERATION
 } cached_tag_entry_t;
 
 static cached_tag_entry_t s_log_cache[TAG_CACHE_SIZE];

components/log/src/os/log_write.c

@@ -8,7 +8,7 @@
 #include <stddef.h>
 #include <string.h>
 #include <stdio.h>
-#include "esp_log.h"
+#include "esp_log_write.h"
 #include "esp_private/log_lock.h"
 #include "esp_private/log_level.h"
 #include "sdkconfig.h"

components/log/src/util.c

@@ -5,54 +5,19 @@
  */
 
 #include <stdint.h>
+#include "esp_rom_sys.h"
 
 int esp_log_util_cvt(unsigned long long val, long radix, int pad, const char *digits, char *buf)
 {
-    char *orig_buf = buf;
+    return esp_rom_cvt(val, radix, pad, digits, buf);
-    int length = 0;
-
-    // val = 123
-    do {
-        *buf++ = digits[val % radix];
-        val /= radix;
-        length++;
-    } while (val);
-    //        3   2   1
-    // buf = [0] [1] [2] [3]
-
-    // length = 3, pad = 6
-    while (pad > 0 && pad > length) {
-        *buf++ = '0';
-        length++;
-    }
-    *buf = '\0';
-    // length = 6
-    //        3   2   1   0   0   0  \0
-    // buf = [0] [1] [2] [3] [4] [5] [6]
-
-    --buf;
-    // reverse the order of characters
-    //             3   2   1   0   0   0  \0
-    //            [0] [1] [2] [3] [4] [5] [6]
-    // orig_buf -- ^                   ^ ----- buf
-    while (orig_buf < buf) {
-        char first_char = *orig_buf;
-        char last_char = *buf;
-        *buf-- = first_char;
-        *orig_buf++ = last_char;
-    }
-    //        0   0   0   1   2   3  \0
-    // buf = [0] [1] [2] [3] [4] [5] [6]
-
-    return (length);
 }
 
 int esp_log_util_cvt_hex(unsigned long long val, int pad, char *buf)
 {
-    return esp_log_util_cvt(val, 16, pad, "0123456789abcdef", buf);
+    return esp_rom_cvt(val, 16, pad, "0123456789abcdef", buf);
 }
 
 int esp_log_util_cvt_dec(unsigned long long val, int pad, char *buf)
 {
-    return esp_log_util_cvt(val, 10, pad, "0123456789", buf);
+    return esp_rom_cvt(val, 10, pad, "0123456789", buf);
 }

docs/doxygen/Doxyfile

@@ -278,6 +278,7 @@ INPUT = \
     $(PROJECT_PATH)/components/log/include/esp_log_buffer.h \
     $(PROJECT_PATH)/components/log/include/esp_log_timestamp.h \
     $(PROJECT_PATH)/components/log/include/esp_log_color.h \
+    $(PROJECT_PATH)/components/log/include/esp_log_write.h \
     $(PROJECT_PATH)/components/lwip/include/apps/esp_sntp.h \
     $(PROJECT_PATH)/components/lwip/include/apps/ping/ping_sock.h \
     $(PROJECT_PATH)/components/mbedtls/esp_crt_bundle/include/esp_crt_bundle.h \

docs/en/api-reference/system/log.rst

@@ -155,3 +155,4 @@ API Reference
 .. include-build-file:: inc/esp_log_buffer.inc
 .. include-build-file:: inc/esp_log_timestamp.inc
 .. include-build-file:: inc/esp_log_color.inc
+.. include-build-file:: inc/esp_log_write.inc

docs/zh_CN/api-reference/system/log.rst

@@ -155,3 +155,4 @@ API 参考
 .. include-build-file:: inc/esp_log_buffer.inc
 .. include-build-file:: inc/esp_log_timestamp.inc
 .. include-build-file:: inc/esp_log_color.inc
+.. include-build-file:: inc/esp_log_write.inc