From 9dc0bd16a32ff057faafe4ba384b66a3bcccae17 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 11 Mar 2021 21:37:11 +1100 Subject: [PATCH] docs: Update the main log document with recent API changes --- components/log/README.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/components/log/README.rst b/components/log/README.rst index e6061bcb1c..922e081373 100644 --- a/components/log/README.rst +++ b/components/log/README.rst @@ -6,8 +6,9 @@ Overview The logging library provides two ways for setting log 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**: 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 otional 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: @@ -19,7 +20,7 @@ There are the following verbosity levels: .. 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). + 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 @@ -45,7 +46,9 @@ Several macros are available for different verbosity levels: * ``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. +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. To override default verbosity level at file or component scope, define the ``LOG_LOCAL_LEVEL`` macro. @@ -58,9 +61,9 @@ At file scope, define it before including ``esp_log.h``, e.g.: At component scope, define it in the component makefile: -.. code-block:: make +.. code-block:: cmake - CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG + 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: @@ -70,6 +73,10 @@ To configure logging output per module at runtime, add calls to the function :cp 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 ^^^^^^^^^^^^^^^^^^^^^^^^