diff --git a/components/log/include/esp_log.h b/components/log/include/esp_log.h index 0886504627..78bd661f97 100644 --- a/components/log/include/esp_log.h +++ b/components/log/include/esp_log.h @@ -15,48 +15,12 @@ #include "esp_log_color.h" #include "esp_log_buffer.h" #include "esp_log_timestamp.h" +#include "esp_log_write.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" diff --git a/components/log/include/esp_log_write.h b/components/log/include/esp_log_write.h new file mode 100644 index 0000000000..75d9184a2b --- /dev/null +++ b/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 +#include +#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 diff --git a/components/log/src/os/log_write.c b/components/log/src/os/log_write.c index 83ab65e5a3..3fb4788b99 100644 --- a/components/log/src/os/log_write.c +++ b/components/log/src/os/log_write.c @@ -8,7 +8,7 @@ #include #include #include -#include "esp_log.h" +#include "esp_log_write.h" #include "esp_private/log_lock.h" #include "esp_private/log_level.h" #include "sdkconfig.h" diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 44f44b8810..74f5f15638 100644 --- a/docs/doxygen/Doxyfile +++ b/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 \ diff --git a/docs/en/api-reference/system/log.rst b/docs/en/api-reference/system/log.rst index ecf94d0cee..3fd7b56892 100644 --- a/docs/en/api-reference/system/log.rst +++ b/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 diff --git a/docs/zh_CN/api-reference/system/log.rst b/docs/zh_CN/api-reference/system/log.rst index 991c2fad13..c78ed10a90 100644 --- a/docs/zh_CN/api-reference/system/log.rst +++ b/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