mirror of
https://github.com/espressif/esp-idf.git
synced 2025-10-31 04:59:55 +00:00
log: clean up docs, clarify esp_log_level_set usage
Closes https://github.com/espressif/esp-idf/issues/1713
This commit is contained in:
Ivan Grokhotkov
@@ -4,11 +4,15 @@ Logging library
|
||||
Overview
|
||||
--------
|
||||
|
||||
Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using ``esp_log_level_set`` function.
|
||||
Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using :cpp:func:`esp_log_level_set` function.
|
||||
|
||||
At compile time, filtering is done using ``CONFIG_LOG_DEFAULT_LEVEL`` macro, set via menuconfig. All logging statements for levels higher than ``CONFIG_LOG_DEFAULT_LEVEL`` will be removed by the preprocessor.
|
||||
The log levels are Error, Warning, Info, Debug, and Verbose (from lowest to highest level of verbosity).
|
||||
|
||||
At run time, all logs below ``CONFIG_LOG_DEFAULT_LEVEL`` are enabled by default. ``esp_log_level_set`` function may be used to set logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
|
||||
At compile time, filtering is done using :ref:`CONFIG_LOG_DEFAULT_LEVEL` option, set via menuconfig. All logging statements for levels higher than :ref:`CONFIG_LOG_DEFAULT_LEVEL` will be removed by the preprocessor.
|
||||
|
||||
At run time, all logs below :ref:`CONFIG_LOG_DEFAULT_LEVEL` are enabled by default. :cpp:func:`esp_log_level_set` function may be used to reduce logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
|
||||
|
||||
Note that :cpp:func:`esp_log_level_set` can not increase logging level beyound that set by :ref:`CONFIG_LOG_DEFAULT_LEVEL`. To increase log level for a specific file at compile time, `LOG_LOCAL_LEVEL` macro can be used (see below for details).
|
||||
|
||||
How to use this library
|
||||
-----------------------
|
||||
@@ -27,15 +31,13 @@ then use one of logging macros to produce output, e.g:
|
||||
|
||||
Several macros are available for different verbosity levels:
|
||||
|
||||
* ``ESP_LOGE`` - error
|
||||
* ``ESP_LOGE`` - error (lowest)
|
||||
* ``ESP_LOGW`` - warning
|
||||
* ``ESP_LOGI`` - info
|
||||
* ``ESP_LOGD`` - debug
|
||||
* ``ESP_LOGV`` - verbose
|
||||
* ``ESP_LOGV`` - verbose (highest)
|
||||
|
||||
Additionally there is an _EARLY_ variant for each of these macros (e.g. ``ESP_EARLY_LOGE``). These variants can run in startup code, before heap allocator and syscalls have been initialized. When compiling bootloader, normal ``ESP_LOGx`` macros fall back to the same implementation as ``ESP_EARLY_LOGx`` macros. So the only place where ``ESP_EARLY_LOGx`` have to be used explicitly is the early startup code, such as heap allocator initialization code.
|
||||
|
||||
(Note that such distinction would not have been necessary if we would have an ``ets_vprintf`` function in the ROM. Then it would be possible to switch implementation from _EARLY_ version to normal version on the fly. Unfortunately, ``ets_vprintf`` in ROM has been inlined by the compiler into ``ets_printf``, so it is not accessible outside.)
|
||||
Additionally there is an ``_EARLY`` variant for each of these macros (e.g. :c:macro:`ESP_EARLY_LOGE`). These variants can run in startup code, before heap allocator and syscalls have been initialized. When compiling bootloader, normal ``ESP_LOGx`` macros fall back to the same implementation as ``ESP_EARLY_LOGx`` macros. So the only place where ``ESP_EARLY_LOGx`` have to be used explicitly is the early startup code, such as heap allocator initialization code.
|
||||
|
||||
To override default verbosity level at file or component scope, define ``LOG_LOCAL_LEVEL`` macro. At file scope, define it before including ``esp_log.h``, e.g.:
|
||||
|
||||
@@ -51,7 +53,7 @@ At component scope, define it in component makefile:
|
||||
|
||||
CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
|
||||
|
||||
To configure logging output per module at runtime, add calls to ``esp_log_level_set`` function:
|
||||
To configure logging output per module at runtime, add calls to :cpp:func:`esp_log_level_set` function:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -62,5 +64,5 @@ To configure logging output per module at runtime, add calls to ``esp_log_level_
|
||||
Logging to Host via JTAG
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
By default logging library uses vprintf-like function to write formatted output to dedicated UART. With calling a simple API, all log output my be routed to JTAG instead, and make the logging several times faster. For details please refer to section :ref:`app_trace-logging-to-host`.
|
||||
By default logging library uses vprintf-like function to write formatted output to dedicated UART. By calling a simple API, all log output may be routed to JTAG instead, making logging several times faster. For details please refer to section :ref:`app_trace-logging-to-host`.
|
||||
|
||||
|
||||
@@ -44,10 +44,18 @@ typedef int (*vprintf_like_t)(const char *, va_list);
|
||||
*
|
||||
* If logging for given component has already been enabled, changes previous setting.
|
||||
*
|
||||
* Note that this function can not raise log level above the level set using
|
||||
* CONFIG_LOG_DEFAULT_LEVEL setting in menuconfig.
|
||||
*
|
||||
* To raise log level above the default one for a given file, define
|
||||
* LOG_LOCAL_LEVEL to one of the ESP_LOG_* values, before including
|
||||
* esp_log.h in this file.
|
||||
*
|
||||
* @param tag Tag of the log entries to enable. Must be a non-NULL zero terminated string.
|
||||
* Value "*" resets log level for all tags to the given value.
|
||||
*
|
||||
* @param level Selects log level to enable. Only logs at this and lower levels will be shown.
|
||||
* @param level Selects log level to enable. Only logs at this and lower verbosity
|
||||
* levels will be shown.
|
||||
*/
|
||||
void esp_log_level_set(const char* tag, esp_log_level_t level);
|
||||
|
||||
@@ -98,6 +106,8 @@ uint32_t esp_log_early_timestamp(void);
|
||||
*/
|
||||
void esp_log_write(esp_log_level_t level, const char* tag, const char* format, ...) __attribute__ ((format (printf, 3, 4)));
|
||||
|
||||
/** @cond */
|
||||
|
||||
#include "esp_log_internal.h"
|
||||
|
||||
#ifndef LOG_LOCAL_LEVEL
|
||||
@@ -108,16 +118,15 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
||||
#endif
|
||||
#endif
|
||||
|
||||
/** @endcond */
|
||||
|
||||
/**
|
||||
* @brief Log a buffer of hex bytes at specified level, separated into 16 bytes each line.
|
||||
*
|
||||
* @param tag description tag
|
||||
*
|
||||
* @param buffer Pointer to the buffer array
|
||||
*
|
||||
* @param buff_len length of buffer in bytes
|
||||
*
|
||||
* @param level level of the log
|
||||
* @param level level of the log
|
||||
*
|
||||
*/
|
||||
#define ESP_LOG_BUFFER_HEX_LEVEL( tag, buffer, buff_len, level ) \
|
||||
@@ -131,12 +140,9 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
||||
* @brief Log a buffer of characters at specified level, separated into 16 bytes each line. Buffer should contain only printable characters.
|
||||
*
|
||||
* @param tag description tag
|
||||
*
|
||||
* @param buffer Pointer to the buffer array
|
||||
*
|
||||
* @param buff_len length of buffer in bytes
|
||||
*
|
||||
* @param level level of the log
|
||||
* @param level level of the log
|
||||
*
|
||||
*/
|
||||
#define ESP_LOG_BUFFER_CHAR_LEVEL( tag, buffer, buff_len, level ) \
|
||||
@@ -158,11 +164,8 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
||||
* It is highly recommend to use terminals with over 102 text width.
|
||||
*
|
||||
* @param tag description tag
|
||||
*
|
||||
* @param buffer Pointer to the buffer array
|
||||
*
|
||||
* @param buff_len length of buffer in bytes
|
||||
*
|
||||
* @param level level of the log
|
||||
*/
|
||||
#define ESP_LOG_BUFFER_HEXDUMP( tag, buffer, buff_len, level ) \
|
||||
@@ -176,9 +179,7 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
||||
* @brief Log a buffer of hex bytes at Info level
|
||||
*
|
||||
* @param tag description tag
|
||||
*
|
||||
* @param buffer Pointer to the buffer array
|
||||
*
|
||||
* @param buff_len length of buffer in bytes
|
||||
*
|
||||
* @see ``esp_log_buffer_hex_level``
|
||||
@@ -195,9 +196,7 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
||||
* @brief Log a buffer of characters at Info level. Buffer should contain only printable characters.
|
||||
*
|
||||
* @param tag description tag
|
||||
*
|
||||
* @param buffer Pointer to the buffer array
|
||||
*
|
||||
* @param buff_len length of buffer in bytes
|
||||
*
|
||||
* @see ``esp_log_buffer_char_level``
|
||||
@@ -210,6 +209,7 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
||||
}\
|
||||
} while(0)
|
||||
|
||||
/** @cond */
|
||||
|
||||
//to be back compatible
|
||||
#define esp_log_buffer_hex ESP_LOG_BUFFER_HEX
|
||||
@@ -243,6 +243,8 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
||||
|
||||
#define LOG_FORMAT(letter, format) LOG_COLOR_ ## letter #letter " (%d) %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``
|
||||
#define ESP_EARLY_LOGE( tag, format, ... ) ESP_LOG_EARLY_IMPL(tag, format, ESP_LOG_ERROR, E, ##__VA_ARGS__)
|
||||
/// macro to output logs in startup code at ``ESP_LOG_WARN`` level. @see ``ESP_EARLY_LOGE``,``ESP_LOGE``, ``printf``
|
||||
@@ -287,11 +289,8 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
||||
/** runtime macro to output logs at a specified level.
|
||||
*
|
||||
* @param tag tag of the log, which can be used to change the log level by ``esp_log_level_set`` at runtime.
|
||||
*
|
||||
* @param level level of the output log.
|
||||
*
|
||||
* @param format format of the output log. see ``printf``
|
||||
*
|
||||
* @param ... variables to be replaced into the log. see ``printf``
|
||||
*
|
||||
* @see ``printf``
|
||||
|
||||
Reference in New Issue
Block a user