diff --git a/docs/en/api-guides/performance/ram-usage.rst b/docs/en/api-guides/performance/ram-usage.rst index 77a2070671..142ccdf864 100644 --- a/docs/en/api-guides/performance/ram-usage.rst +++ b/docs/en/api-guides/performance/ram-usage.rst @@ -194,7 +194,7 @@ The following options will reduce IRAM usage of some ESP-IDF features: - Disable :ref:`CONFIG_LIBC_LOCKS_PLACE_IN_IRAM` if no ISRs that run while cache is disabled (i.e. IRAM ISRs) use libc lock APIs. :CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - Disable :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS` to save approximately 1000 bytes of IRAM, at the cost of reduced performance. :SOC_SPIRAM_SUPPORTED: - Enable :ref:`CONFIG_ESP_EVENT_LOOP_IN_EXT_RAM` to force ``esp_event`` to place event loop related allocations in external RAM instead of internal RAM. - :not CONFIG_ESP_ROM_HAS_VPRINTF_FUNC: - When using **Log V2**, disable :ref:`CONFIG_LOG_API_CONSTRAINED_ENV_SAFE` to remove ``esp_rom_vprintf`` from IRAM, saving ~1.2 KB. This means ``ESP_LOGx`` will no longer safely fall back to ROM-based printing in ISRs or with cache disabled. Use ``ESP_DRAM_LOGx`` explicitly for constrained-environment logging. See :doc:`/api-reference/system/log` for details. + :not CONFIG_ESP_ROM_HAS_VPRINTF_FUNC: - When using **Log V2**, disable :ref:`CONFIG_LOG_API_CONSTRAINED_ENV_SAFE` to remove ``esp_rom_vprintf`` from IRAM, saving about 1.2 KB. This means ``ESP_LOGx`` will no longer safely fall back to ROM-based printing in ISRs or with cache disabled. Use ``ESP_DRAM_LOGx`` explicitly for constrained-environment logging. See :doc:`/api-reference/system/log` for details. .. only:: esp32 diff --git a/docs/en/api-reference/system/log.rst b/docs/en/api-reference/system/log.rst index 3f39b8e150..abf8b0d9cc 100644 --- a/docs/en/api-reference/system/log.rst +++ b/docs/en/api-reference/system/log.rst @@ -661,14 +661,14 @@ Enabling **Log V2** increases IRAM usage while reducing the overall application Reducing IRAM Usage in Log V2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The IRAM increase in **Log V2** is primarily caused by ``esp_rom_vprintf``, which is compiled into IRAM (~1.2 KB) on {IDF_TARGET_NAME}. This function is referenced as the fallback formatter for constrained environments (ISR, cache disabled) in the ``esp_log_vprintf()`` inline function. + The IRAM increase in **Log V2** is primarily caused by ``esp_rom_vprintf``, which is compiled into IRAM (about 1.2 KB) on {IDF_TARGET_NAME}. This function is referenced as the fallback formatter for constrained environments (ISR, cache disabled) in the ``esp_log_vprintf()`` inline function. - On chips where IRAM and DRAM share the same memory pool, this also reduces available heap by the same amount. + On chips where IRAM and DRAM share the same memory pool, this also reduces available heap by the same amount (about 1.2 KB). To eliminate this cost, disable :ref:`CONFIG_LOG_API_CONSTRAINED_ENV_SAFE` (enabled by default). When disabled: - ``ESP_DRAM_LOGx`` and ``ESP_EARLY_LOGx`` expand directly to ``esp_rom_printf()`` (a true ROM function, zero IRAM cost), bypassing the ``esp_log()`` pipeline entirely. - - Normal ``ESP_LOGx`` calls in constrained environments (ISR, cache disabled) will use the standard ``vprintf`` function. If ``vprintf`` resides in flash, such calls may crash. Use ``ESP_DRAM_LOGx`` for any logging that must work with cache disabled or from an ISR. + - Normal ``ESP_LOGx`` calls in constrained environments will use the standard ``vprintf`` function. If ``vprintf`` resides in flash, such calls may crash. Use ``ESP_DRAM_LOGx`` for any logging that must work with cache disabled or from an ISR. - ``esp_rom_vprintf`` is never referenced, so the linker excludes it from the binary. When enabled, the original **Log V2** behavior is preserved: all constrained-environment logs route through ``esp_log()`` and use ``esp_rom_vprintf`` as the formatter for early/DRAM logs. diff --git a/docs/zh_CN/api-guides/performance/ram-usage.rst b/docs/zh_CN/api-guides/performance/ram-usage.rst index a09670f24e..3fa620de94 100644 --- a/docs/zh_CN/api-guides/performance/ram-usage.rst +++ b/docs/zh_CN/api-guides/performance/ram-usage.rst @@ -194,6 +194,7 @@ IRAM 优化 - 禁用 :ref:`CONFIG_LIBC_LOCKS_PLACE_IN_IRAM`。若在缓存禁用的情况下，运行中的中断服务程序（即 IRAM ISR）没有使用 libc 锁 API，那么禁用该配置可以节省 IRAM 空间。 :CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - 禁用 :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS` 可以节省大约 1000 字节的 IRAM，但会降低性能。 :SOC_SPIRAM_SUPPORTED: - 启用 :ref:`CONFIG_ESP_EVENT_LOOP_IN_EXT_RAM`，强制 ``esp_event`` 将事件循环相关的内存分配放在外部 RAM 而不是内部 RAM 中。 + :not CONFIG_ESP_ROM_HAS_VPRINTF_FUNC: - 在使用 **Log V2** 时，可禁用 :ref:`CONFIG_LOG_API_CONSTRAINED_ENV_SAFE`，以从IRAM 中移除 ``esp_rom_vprintf``，从而节省约 1.2 KB 空间。这样一来，``ESP_LOGx`` 在 ISR 中或在缓存被禁用时将无法安全回退到 ROM 打印功能；在受限环境下请显式使用 ``ESP_DRAM_LOGx`` 进行日志记录。详情请参阅 :doc:`/api-reference/system/log`。 .. only:: esp32 diff --git a/docs/zh_CN/api-reference/system/log.rst b/docs/zh_CN/api-reference/system/log.rst index e6683aeee6..7f107398d8 100644 --- a/docs/zh_CN/api-reference/system/log.rst +++ b/docs/zh_CN/api-reference/system/log.rst @@ -656,6 +656,23 @@ buffer 日志需特殊处理 启用 **Log V2** 会增加 IRAM 的使用量，同时减少整个应用程序的二进制文件大小、flash 代码和数据量。 +.. only:: not CONFIG_ESP_ROM_HAS_VPRINTF_FUNC + + 在 Log V2 中减少 IRAM 使用 + ^^^^^^^^^^^^^^^^^^^^^^^^^^ + + **Log V2** 中 IRAM 开销增加的主要原因是 ``esp_rom_vprintf`` 在 {IDF_TARGET_NAME} 上被编译进了 IRAM（约 1.2 KB）。在内联函数 ``esp_log_vprintf()`` 中，``esp_rom_vprintf`` 作为受限环境（例如在 ISR 中或缓存被禁用时）的回退格式化函数被引用。 + + 在 IRAM 与 DRAM 共用同一内存池的芯片上，这也会减少相应的可用堆空间（约 1.2 KB）。 + + 为消除该开销，请禁用 :ref:`CONFIG_LOG_API_CONSTRAINED_ENV_SAFE` （默认启用）。禁用后： + + - ``ESP_DRAM_LOGx`` 和 ``ESP_EARLY_LOGx`` 直接展开为 ``esp_rom_printf()`` （真正的 ROM 函数，无需 IRAM 开销），完全绕过 ``esp_log()`` 处理流程。 + - 在受限环境中，普通的 ``ESP_LOGx`` 调用将使用标准 ``vprintf`` 函数。如果 ``vprintf`` 位于 flash 中，此类调用可能导致崩溃。对于必须在缓存被禁用时或在 ISR 中使用的日志，请使用 ``ESP_DRAM_LOGx``。 + - ``esp_rom_vprintf`` 不会被引用，因此链接器会将其从二进制文件中排除。 + + 若启用 :ref:`CONFIG_LOG_API_CONSTRAINED_ENV_SAFE`，则保留原始 **Log V2** 行为：所有受限环境的日志都通过 ``esp_log()`` 路由，并使用 ``esp_rom_vprintf`` 作为早期/DRAM 日志的格式化函数。 + 通过 JTAG 将日志记录到主机 ------------------------------