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
-----------------------
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
-
-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.
+* ``ESP_LOGV`` - verbose (highest)
-(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.:
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
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`.
*
* 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);
*/
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
#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 ) \
* @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 ) \
* 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 ) \
* @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``
* @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``
}\
} while(0)
+/** @cond */
//to be back compatible
#define esp_log_buffer_hex ESP_LOG_BUFFER_HEX
#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``
/** 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``