docs: Update CN translations for ram-usage.rst and log.rst

This commit is contained in:
Shen Mengjing
2026-04-21 15:23:36 +08:00
parent 4cd39bc28f
commit 0aeccc1adf
4 changed files with 22 additions and 4 deletions
+1 -1
View File
@@ -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
+3 -3
View File
@@ -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.
@@ -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
+17
View File
@@ -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 将日志记录到主机
------------------------------