Fixed desription of logging library

This commit is contained in:
Krzysztof 2016-10-29 23:00:46 +02:00 committed by Ivan Grokhotkov
parent 905d27815c
commit f6118c67b0
2 changed files with 69 additions and 68 deletions

61
components/log/README.rst Normal file
View 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

View file

@ -24,76 +24,16 @@ extern "C" {
#endif #endif
/** /**
* @brief Logging library * @brief Log level
*
* 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
* *
*/ */
typedef enum { typedef enum {
ESP_LOG_NONE, // No log output ESP_LOG_NONE, /*!< No log output */
ESP_LOG_ERROR, // Critical errors, software module can not recover on its own 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_WARN, /*!< Error conditions from which recovery measures have been taken */
ESP_LOG_INFO, // Information messages which describe normal flow of events 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_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_VERBOSE /*!< Bigger chunks of debugging information, or frequent messages which can potentially flood the output. */
} esp_log_level_t; } esp_log_level_t;
typedef int (*vprintf_like_t)(const char *, va_list); 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 * @return timestamp, in milliseconds
*/ */
uint32_t esp_log_timestamp(); uint32_t esp_log_timestamp(void);
#if CONFIG_LOG_COLORS #if CONFIG_LOG_COLORS