Fixed desription of logging library
This commit is contained in:
Krzysztof
Ivan Grokhotkov
parent
905d27815c
commit
f6118c67b0
61
components/log/README.rst
Normal file
61
components/log/README.rst
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
Logging library
|
||||
===============
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using ``esp_log_set_level`` function.
|
||||
|
||||
At compile time, filtering is done using ``CONFIG_LOG_DEFAULT_LEVEL`` macro, set via menuconfig. All logging statments for levels higher than ``CONFIG_LOG_DEFAULT_LEVEL`` will be removed by the preprocessor.
|
||||
|
||||
At run time, all logs below ``CONFIG_LOG_DEFAULT_LEVEL`` are enabled by default. ``esp_log_set_level`` function may be used to set logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
|
||||
|
||||
How to use this library
|
||||
-----------------------
|
||||
|
||||
In each C file which uses logging functionality, define TAG variable like this:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
static const char* TAG = "MyModule";
|
||||
|
||||
then use one of logging macros to produce output, e.g:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
|
||||
|
||||
Several macros are available for different verbosity levels:
|
||||
|
||||
* ``ESP_LOGE`` - error
|
||||
* ``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.
|
||||
|
||||
(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.)
|
||||
|
||||
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.:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
|
||||
#include "esp_log.h"
|
||||
|
||||
|
||||
At component scope, define it in component makefile:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
|
||||
|
||||
To configure logging output per module at runtime, add calls to ``esp_log_set_level`` function:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
esp_log_set_level("*", ESP_LOG_ERROR); // set all components to ERROR level
|
||||
esp_log_set_level("wifi", ESP_LOG_WARN); // enable WARN logs from WiFi stack
|
||||
esp_log_set_level("dhcpc", ESP_LOG_INFO); // enable INFO logs from DHCP client
|
||||
|
||||
|
|
@ -24,76 +24,16 @@ extern "C" {
|
|||
#endif
|
||||
|
||||
/**
|
||||
* @brief Logging library
|
||||
*
|
||||
* Log library has two ways of managing log verbosity: compile time, set via
|
||||
* menuconfig, and runtime, using esp_log_set_level function.
|
||||
*
|
||||
* At compile time, filtering is done using CONFIG_LOG_DEFAULT_LEVEL macro, set via
|
||||
* menuconfig. All logging statments for levels higher than CONFIG_LOG_DEFAULT_LEVEL
|
||||
* will be removed by the preprocessor.
|
||||
*
|
||||
* At run time, all logs below CONFIG_LOG_DEFAULT_LEVEL are enabled by default.
|
||||
* esp_log_set_level function may be used to set logging level per module.
|
||||
* Modules are identified by their tags, which are human-readable ASCII
|
||||
* zero-terminated strings.
|
||||
*
|
||||
* How to use this library:
|
||||
*
|
||||
* In each C file which uses logging functionality, define TAG variable like this:
|
||||
*
|
||||
* static const char* TAG = "MyModule";
|
||||
*
|
||||
* then use one of logging macros to produce output, e.g:
|
||||
*
|
||||
* ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
|
||||
*
|
||||
* Several macros are available for different verbosity levels:
|
||||
*
|
||||
* ESP_LOGE — error
|
||||
* 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.
|
||||
*
|
||||
* (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.)
|
||||
*
|
||||
* 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.:
|
||||
*
|
||||
* #define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
|
||||
* #include "esp_log.h"
|
||||
*
|
||||
* 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_set_level function:
|
||||
*
|
||||
* esp_log_set_level("*", ESP_LOG_ERROR); // set all components to ERROR level
|
||||
* esp_log_set_level("wifi", ESP_LOG_WARN); // enable WARN logs from WiFi stack
|
||||
* esp_log_set_level("dhcpc", ESP_LOG_INFO); // enable INFO logs from DHCP client
|
||||
* @brief Log level
|
||||
*
|
||||
*/
|
||||
|
||||
|
||||
typedef enum {
|
||||
ESP_LOG_NONE, // No log output
|
||||
ESP_LOG_ERROR, // Critical errors, software module can not recover on its own
|
||||
ESP_LOG_WARN, // Error conditions from which recovery measures have been taken
|
||||
ESP_LOG_INFO, // Information messages which describe normal flow of events
|
||||
ESP_LOG_DEBUG, // Extra information which is not necessary for normal use (values, pointers, sizes, etc).
|
||||
ESP_LOG_VERBOSE // Bigger chunks of debugging information, or frequent messages which can potentially flood the output.
|
||||
ESP_LOG_NONE, /*!< No log output */
|
||||
ESP_LOG_ERROR, /*!< Critical errors, software module can not recover on its own */
|
||||
ESP_LOG_WARN, /*!< Error conditions from which recovery measures have been taken */
|
||||
ESP_LOG_INFO, /*!< Information messages which describe normal flow of events */
|
||||
ESP_LOG_DEBUG, /*!< Extra information which is not necessary for normal use (values, pointers, sizes, etc). */
|
||||
ESP_LOG_VERBOSE /*!< Bigger chunks of debugging information, or frequent messages which can potentially flood the output. */
|
||||
} esp_log_level_t;
|
||||
|
||||
typedef int (*vprintf_like_t)(const char *, va_list);
|
||||
|
|
@ -143,7 +83,7 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
|
|||
*
|
||||
* @return timestamp, in milliseconds
|
||||
*/
|
||||
uint32_t esp_log_timestamp();
|
||||
uint32_t esp_log_timestamp(void);
|
||||
|
||||
|
||||
#if CONFIG_LOG_COLORS
|
||||
|
|
|
|||
Loading…
Reference in a new issue