Review log.rst and index.rst files in api-reference/system
This commit is contained in:
parent
70eda3d221
commit
a01ec59f74
|
@ -4,26 +4,34 @@ Logging library
|
||||||
Overview
|
Overview
|
||||||
--------
|
--------
|
||||||
|
|
||||||
Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using :cpp:func:`esp_log_level_set` function.
|
The logging library provides two ways for setting log verbosity:
|
||||||
|
|
||||||
The log levels are Error, Warning, Info, Debug, and Verbose (from lowest to highest level of verbosity).
|
- **At compile time**: in menuconfig, set the verbosity level using the option :envvar:`CONFIG_LOG_DEFAULT_LEVEL`. All logging statements for verbosity levels higher than :envvar:`CONFIG_LOG_DEFAULT_LEVEL` will be removed by the preprocessor.
|
||||||
|
- **At runtime**: all logs for verbosity levels lower than :envvar:`CONFIG_LOG_DEFAULT_LEVEL` are enabled by default. The function :cpp:func:`esp_log_level_set` can be used to set a logging level on a per module basis. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
|
||||||
|
|
||||||
At compile time, filtering is done using :envvar:`CONFIG_LOG_DEFAULT_LEVEL` option, set via menuconfig. All logging statements for levels higher than :envvar:`CONFIG_LOG_DEFAULT_LEVEL` will be removed by the preprocessor.
|
There are the following verbosity levels:
|
||||||
|
|
||||||
At run time, all logs below :envvar:`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.
|
- Error (lowest)
|
||||||
|
- Warning
|
||||||
|
- Info
|
||||||
|
- Debug
|
||||||
|
- Verbose (highest)
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The function :cpp:func:`esp_log_level_set` cannot set logging levels higher than specified by :envvar:`CONFIG_LOG_DEFAULT_LEVEL`. To increase log level for a specific file at compile time, use the macro `LOG_LOCAL_LEVEL` (see the details below).
|
||||||
|
|
||||||
Note that :cpp:func:`esp_log_level_set` can not increase logging level beyound that set by :envvar:`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
|
How to use this library
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
In each C file which uses logging functionality, define TAG variable like this:
|
In each C file that uses logging functionality, define the TAG variable as shown below:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
static const char* TAG = "MyModule";
|
static const char* TAG = "MyModule";
|
||||||
|
|
||||||
then use one of logging macros to produce output, e.g:
|
Then use one of logging macros to produce output, e.g:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
@ -37,23 +45,24 @@ Several macros are available for different verbosity levels:
|
||||||
* ``ESP_LOGD`` - debug
|
* ``ESP_LOGD`` - debug
|
||||||
* ``ESP_LOGV`` - verbose (highest)
|
* ``ESP_LOGV`` - verbose (highest)
|
||||||
|
|
||||||
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.
|
Additionally, there are ``ESP_EARLY_LOGx`` versions for each of these macros, e.g., :c:macro:`ESP_EARLY_LOGE`. These versions have to be used explicitly in the early startup code only, before heap allocator and syscalls have been initialized. Normal ``ESP_LOGx`` macros can also be used while compiling the bootloader, but they will fall back to the same implementation as ``ESP_EARLY_LOGx`` macros.
|
||||||
|
|
||||||
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.:
|
To override default verbosity level at file or component scope, define the ``LOG_LOCAL_LEVEL`` macro.
|
||||||
|
|
||||||
|
At file scope, define it before including ``esp_log.h``, e.g.:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
|
#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
|
||||||
#include "esp_log.h"
|
#include "esp_log.h"
|
||||||
|
|
||||||
|
At component scope, define it in the component makefile:
|
||||||
At component scope, define it in component makefile:
|
|
||||||
|
|
||||||
.. code-block:: make
|
.. code-block:: make
|
||||||
|
|
||||||
CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
|
CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
|
||||||
|
|
||||||
To configure logging output per module at runtime, add calls to :cpp:func:`esp_log_level_set` function:
|
To configure logging output per module at runtime, add calls to the function :cpp:func:`esp_log_level_set` as follows:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
@ -64,5 +73,5 @@ To configure logging output per module at runtime, add calls to :cpp:func:`esp_l
|
||||||
Logging to Host via JTAG
|
Logging to Host via JTAG
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
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`.
|
By default, the logging library uses the vprintf-like function to write formatted output to the 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`.
|
||||||
|
|
||||||
|
|
|
@ -26,4 +26,4 @@ System API
|
||||||
Miscellaneous System APIs <system>
|
Miscellaneous System APIs <system>
|
||||||
|
|
||||||
|
|
||||||
Example code for this API section is provided in :example:`system` directory of ESP-IDF examples.
|
Code examples for this API section are provided in the :example:`system` directory of ESP-IDF examples.
|
||||||
|
|
|
@ -3,11 +3,11 @@
|
||||||
Application Example
|
Application Example
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
Log library is commonly used by most of esp-idf components and examples. For demonstration of log functionality check :idf:`examples` folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that among others, contains the following examples:
|
The logging library is commonly used by most esp-idf components and examples. For demonstration of log functionality, check ESP-IDF's :idf:`examples` directory. The most revelant examples that deal with logging are the following:
|
||||||
|
|
||||||
* :example:`system/ota`
|
* :example:`system/ota`
|
||||||
* :example:`storage/sd_card`
|
* :example:`storage/sd_card`
|
||||||
* :example:`protocols/https_request`
|
* :example:`protocols/https_request`
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
-------------
|
-------------
|
||||||
|
|
Loading…
Reference in a new issue