log: Document that normally logging APIs don't work in critical sections

Closes https://github.com/espressif/esp-idf/issues/6600
This commit is contained in:
Angus Gratton
2021-04-23 18:26:29 +10:00
parent 9dc0bd16a3
commit 88829d68fc
2 changed files with 12 additions and 3 deletions

View File

@@ -50,6 +50,10 @@ Additionally, there are ``ESP_EARLY_LOGx`` versions for each of these macros, e.
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. 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. 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.: At file scope, define it before including ``esp_log.h``, e.g.:

View File

@@ -280,7 +280,7 @@ void esp_log_writev(esp_log_level_t level, const char* tag, const char* format,
/** @endcond */ /** @endcond */
/// macro to output logs in startup code, before heap allocator and syscalls have been initialized. log at ``ESP_LOG_ERROR`` level. @see ``printf``,``ESP_LOGE`` /// macro to output logs in startup code, before heap allocator and syscalls have been initialized. log at ``ESP_LOG_ERROR`` level. @see ``printf``,``ESP_LOGE``,``ESP_DRAM_LOGE``
#define ESP_EARLY_LOGE( tag, format, ... ) ESP_LOG_EARLY_IMPL(tag, format, ESP_LOG_ERROR, E, ##__VA_ARGS__) #define ESP_EARLY_LOGE( tag, format, ... ) ESP_LOG_EARLY_IMPL(tag, format, ESP_LOG_ERROR, E, ##__VA_ARGS__)
/// macro to output logs in startup code at ``ESP_LOG_WARN`` level. @see ``ESP_EARLY_LOGE``,``ESP_LOGE``, ``printf`` /// macro to output logs in startup code at ``ESP_LOG_WARN`` level. @see ``ESP_EARLY_LOGE``,``ESP_LOGE``, ``printf``
#define ESP_EARLY_LOGW( tag, format, ... ) ESP_LOG_EARLY_IMPL(tag, format, ESP_LOG_WARN, W, ##__VA_ARGS__) #define ESP_EARLY_LOGW( tag, format, ... ) ESP_LOG_EARLY_IMPL(tag, format, ESP_LOG_WARN, W, ##__VA_ARGS__)
@@ -312,7 +312,9 @@ void esp_log_writev(esp_log_level_t level, const char* tag, const char* format,
#define ESP_LOGV( tag, format, ... ) ESP_LOG_LEVEL_LOCAL(ESP_LOG_VERBOSE, tag, format, ##__VA_ARGS__) #define ESP_LOGV( tag, format, ... ) ESP_LOG_LEVEL_LOCAL(ESP_LOG_VERBOSE, tag, format, ##__VA_ARGS__)
#else #else
/** /**
* macro to output logs at ESP_LOG_ERROR level. * Macro to output logs at ESP_LOG_ERROR level.
*
* @note This macro cannot be used when interrupts are disabled or inside an ISR. @see ``ESP_DRAM_LOGE``.
* *
* @param tag tag of the log, which can be used to change the log level by ``esp_log_level_set`` at runtime. * @param tag tag of the log, which can be used to change the log level by ``esp_log_level_set`` at runtime.
* *
@@ -368,7 +370,10 @@ void esp_log_writev(esp_log_level_t level, const char* tag, const char* format,
/** /**
* @brief Macro to output logs when the cache is disabled. log at ``ESP_LOG_ERROR`` level. * @brief Macro to output logs when the cache is disabled. log at ``ESP_LOG_ERROR`` level.
* *
* Similar to `ESP_EARLY_LOGE`, the log level cannot be changed per-tag, however * @note Unlike normal logging macros, it's possible to use this macro when interrupts are
* disabled or inside an ISR.
*
* Similar to @see ``ESP_EARLY_LOGE``, the log level cannot be changed per-tag, however
* esp_log_level_set("*", level) will set the default level which controls these log lines also. * esp_log_level_set("*", level) will set the default level which controls these log lines also.
* *
* Usage: `ESP_DRAM_LOGE(DRAM_STR("my_tag"), "format", or `ESP_DRAM_LOGE(TAG, "format", ...)`, * Usage: `ESP_DRAM_LOGE(DRAM_STR("my_tag"), "format", or `ESP_DRAM_LOGE(TAG, "format", ...)`,