esp-idf/components/log
Darian Leung c5fd79547a freertos: Add CHOOSE_MACRO_VA_ARG selector
This commit adds a CHOOSE_MACRO_VA_ARG() selector to allow selection between two
versions of a macro based on the number of arguments. This replaces the previous
portGET_ARGUMENT_COUNT() selector.

- portYIELD_FROM_ISR() now uses CHOOSE_MACRO_VA_ARG()
- portYIELD_FROM_ISR(arg) version added to risc-v port
- Old vPortEvaluateYieldFromISR() and portGET_ARGUMENT_COUNT removed
2022-02-07 20:01:11 +08:00
..
host_test/log_test [build system]: Fixed common requirement for Linux 2021-08-13 16:50:29 +08:00
include freertos: Add CHOOSE_MACRO_VA_ARG selector 2022-02-07 20:01:11 +08:00
CMakeLists.txt soc: don't expose unstable soc header files in public api 2022-01-06 23:10:22 +08:00
esp_log_private.h log: refactoring to make compatible with no-FreeRTOS builds 2019-11-22 11:41:35 +01:00
Kconfig log: Allow setting maximum log level higher than default 2021-04-23 18:25:41 +10:00
linker.lf log: refactoring to make compatible with no-FreeRTOS builds 2019-11-22 11:41:35 +01:00
log_buffers.c G0: Memory layouts are now part of heap components 2021-07-15 11:38:23 +10:00
log_freertos.c log: Allow setting maximum log level higher than default 2021-04-23 18:25:41 +10:00
log_linux.c [esp_rom]: Partially buildable for linux 2021-08-03 12:03:24 +08:00
log_noos.c log: update copyright year 2021-04-18 23:53:48 +02:00
log.c esp_log: Refactor esp_log_level_get() into a common static function 2021-06-08 16:53:23 +10:00
README.rst fix a small typo in logging library docs 2021-11-04 04:08:35 +02:00

Logging library
===============

Overview
--------

The logging library provides two ways for setting log verbosity:

- **At compile time**: in menuconfig, set the verbosity level using the option :ref:`CONFIG_LOG_DEFAULT_LEVEL`.
- Optionally, also in menuconfig, set the maximum verbosity level using the option :ref:`CONFIG_LOG_MAXIMUM_LEVEL`. By default this is the same as the default level, but it can be set higher in order to compile more optional logs into the firmware.
- **At runtime**: all logs for verbosity levels lower than :ref:`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.

There are the following verbosity levels:

- Error (lowest)
- Warning
- Info
- Debug
- Verbose (highest)

.. note::

    The function :cpp:func:`esp_log_level_set` cannot set logging levels higher than specified by :ref:`CONFIG_LOG_MAXIMUM_LEVEL`. To increase log level for a specific file above this maximum at compile time, use the macro `LOG_LOCAL_LEVEL` (see the details below).


How to use this library
-----------------------

In each C file that uses logging functionality, define the TAG variable as shown below:

.. 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 (lowest)
* ``ESP_LOGW`` - warning
* ``ESP_LOGI`` - info
* ``ESP_LOGD`` - debug
* ``ESP_LOGV`` - verbose (highest)

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.

There are also ``ESP_DRAM_LOGx`` versions for each of these macros, e.g. :c:macro:`ESP_DRAM_LOGE`. These versions are used in some places where logging may occur with interrupts disabled or with flash cache inaccessible. Use of this macros should be as sparing as possible, as logging in these types of code should be avoided for performance reasons.

.. note::

   Inside critical sections interrupts are disabled so it's only possible to use ``ESP_DRAM_LOGx`` (preferred) or ``ESP_EARLY_LOGx``. Even though it's possible to log in these situations, it's better if your program can be structured not to require it.

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

   #define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
   #include "esp_log.h"

At component scope, define it in the component makefile:

.. code-block:: cmake

   target_compile_definitions(${COMPONENT_LIB} PUBLIC "-DLOG_LOCAL_LEVEL=ESP_LOG_VERBOSE")

To configure logging output per module at runtime, add calls to the function :cpp:func:`esp_log_level_set` as follows:

.. code-block:: c

   esp_log_level_set("*", ESP_LOG_ERROR);        // set all components to ERROR level
   esp_log_level_set("wifi", ESP_LOG_WARN);      // enable WARN logs from WiFi stack
   esp_log_level_set("dhcpc", ESP_LOG_INFO);     // enable INFO logs from DHCP client

.. note::

   The "DRAM" and "EARLY" log macro variants documented above do not support per module setting of log verbosity. These macros will always log at the "default" verbosity level, which can only be changed at runtime by calling ``esp_log_level("*", level)``.

Logging to Host via JTAG
^^^^^^^^^^^^^^^^^^^^^^^^

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`.