mirror of
https://github.com/espressif/esp-idf.git
synced 2025-10-03 10:30:58 +02:00
docs: Update CN translation for IRAM-related docs
This commit is contained in:
Zhang Shuxian
@@ -179,7 +179,7 @@ The following options will reduce IRAM usage of some ESP-IDF features:
|
||||
|
||||
.. list::
|
||||
|
||||
- Disable :ref:`CONFIG_FREERTOS_IN_IRAM` if enabled to place FreeRTOS functions in Flash instead of IRAM. By default, FreeRTOS functions are already placed in Flash to save IRAM.
|
||||
- Disable :ref:`CONFIG_FREERTOS_IN_IRAM` if enabled to place FreeRTOS functions in flash instead of IRAM. By default, FreeRTOS functions are already placed in Flash to save IRAM.
|
||||
- Disable :ref:`CONFIG_RINGBUF_IN_IRAM` if enabled to place ring buffer functions in Flash instead of IRAM. By default, ring buffer functions are already placed in Flash to save IRAM.
|
||||
- Enable :ref:`CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH`. This option is not safe to use if the ISR ringbuf functions are used from an IRAM interrupt context, e.g., if :ref:`CONFIG_UART_ISR_IN_IRAM` is enabled. For the ESP-IDF drivers where this is the case, you can get an error at run-time when installing the driver in question.
|
||||
:SOC_WIFI_SUPPORTED: - Disabling Wi-Fi options :ref:`CONFIG_ESP_WIFI_IRAM_OPT` and/or :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT` options frees available IRAM at the cost of Wi-Fi performance.
|
||||
|
||||
@@ -154,7 +154,7 @@ The following changes increase the speed of a chosen part of the firmware applic
|
||||
|
||||
IRAM is a limited resource, and using more IRAM may reduce available DRAM, so a strategic approach is needed when moving code to IRAM. See :ref:`iram` for more information.
|
||||
|
||||
- Jump table optimizations can be re-enabled for individual source files that do not need to be placed in IRAM. For hot paths in large ``switch cases``, this improves performance. For instructions on how to add the ``-fjump-tables`` and ``-ftree-switch-conversion`` options when compiling individual source files, see :ref:`component_build_control`
|
||||
- Jump table optimizations can be re-enabled for individual source files that do not need to be placed in IRAM. For hot paths in large ``switch cases``, this improves performance. For instructions on how to add the ``-fjump-tables`` and ``-ftree-switch-conversion`` options when compiling individual source files, see :ref:`component_build_control`.
|
||||
|
||||
- Many ESP-IDF components and drivers provide configuration options to place performance-critical functions in IRAM for reduced latency and improved speed. These options typically have names like ``CONFIG_*_IN_IRAM``, ``CONFIG_*_ISR_IN_IRAM``, or ``CONFIG_*_IRAM_OPT``. Some examples are :ref:`CONFIG_FREERTOS_IN_IRAM` for FreeRTOS functions, :ref:`CONFIG_ESP_WIFI_IRAM_OPT` for Wi-Fi operations, :ref:`CONFIG_UART_ISR_IN_IRAM` for UART interrupt handling, and :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` for SPI operations. These options trade IRAM usage for speed, so they should be used selectively based on your application's performance requirements and available IRAM space.
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@ Partial Image Download over HTTPS
|
||||
|
||||
To use the partial image download feature, you need to:
|
||||
|
||||
* **Enable the component-level configuration**: enable :ref:`CONFIG_ESP_HTTPS_OTA_ENABLE_PARTIAL_DOWNLOAD` in menuconfig (``Component config`` → ``ESP HTTPS OTA`` → ``Enable partial HTTP download for OTA``)
|
||||
* **Enable the component-level configuration**: Enable :ref:`CONFIG_ESP_HTTPS_OTA_ENABLE_PARTIAL_DOWNLOAD` in menuconfig (``Component config`` → ``ESP HTTPS OTA`` → ``Enable partial HTTP download for OTA``)
|
||||
|
||||
* **Enable the feature in your application**: Set the ``partial_http_download`` field in :cpp:struct:`esp_https_ota_config_t` configuration structure
|
||||
|
||||
|
||||
@@ -282,7 +282,7 @@ Now verify that the serial connection is operational. You can do this using a se
|
||||
Windows and Linux
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
In this example, we use `PuTTY SSH Client <https://putty.software/>`_ that is available for both Windows and Linux. You can use other serial programs and set communication parameters like below.
|
||||
In this example, we use the `PuTTY SSH Client <https://putty.software/>`_, available for both Windows and Linux. You can use other serial programs and set communication parameters as shown below.
|
||||
|
||||
Run terminal and set identified serial port. Baud rate = 115200 (if needed, change this to the default baud rate of the chip in use), data bits = 8, stop bits = 1, and parity = N. Below are example screenshots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above.
|
||||
|
||||
|
||||
@@ -157,7 +157,7 @@ LCD
|
||||
SPI
|
||||
---
|
||||
|
||||
The :ref:`CONFIG_SPI_MASTER_IN_IRAM` option is now invisible by default in menuconfig and depends on :ref:`CONFIG_FREERTOS_IN_IRAM`. This change was made to prevent potential crashes when SPI functions in IRAM call FreeRTOS functions that are placed in Flash.
|
||||
The :ref:`CONFIG_SPI_MASTER_IN_IRAM` option is now invisible by default in menuconfig and depends on :ref:`CONFIG_FREERTOS_IN_IRAM`. This change was made to prevent potential crashes when SPI functions in IRAM call FreeRTOS functions that are placed in flash.
|
||||
|
||||
To enable SPI master IRAM optimization:
|
||||
|
||||
|
||||
@@ -106,7 +106,9 @@ The function :cpp:func:`pxTaskGetStackStart` has been deprecated. Use :cpp:func:
|
||||
**Memory Placement**
|
||||
|
||||
To reduce IRAM usage, the default placement for most FreeRTOS functions has been changed from IRAM to Flash. Consequently, the ``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, the previous behavior can be restored by enabling the new :ref:`CONFIG_FREERTOS_IN_IRAM` option.
|
||||
|
||||
When deciding whether to enable ``CONFIG_FREERTOS_IN_IRAM``, consider conducting performance testing to measure the actual impact on your specific use case. Performance differences between Flash and IRAM configurations can vary depending on flash cache efficiency, API usage patterns, and system load.
|
||||
|
||||
A baseline performance test is provided in ``components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c`` that measures the execution time of commonly used FreeRTOS APIs. This test can help you evaluate the performance impact of memory placement for your target hardware and application requirements.
|
||||
|
||||
Ring Buffer
|
||||
|
||||
@@ -179,8 +179,8 @@ IRAM 优化
|
||||
|
||||
.. list::
|
||||
|
||||
- 如果启用了 :ref:`CONFIG_FREERTOS_IN_IRAM`，可以禁用它以将 FreeRTOS 函数放置在 Flash 中而不是 IRAM 中。默认情况下，FreeRTOS 函数已经被放置在 Flash 中以节省 IRAM。
|
||||
- 如果启用了 :ref:`CONFIG_RINGBUF_IN_IRAM`，可以禁用它以将环形缓冲区函数放置在 Flash 中而不是 IRAM 中。默认情况下，环形缓冲区函数已经被放置在 Flash 中以节省 IRAM。
|
||||
- 如果已启用 :ref:`CONFIG_FREERTOS_IN_IRAM`，请将其禁用，以便将 FreeRTOS 函数放置在 flash 中而不是 IRAM 中。默认情况下，FreeRTOS 函数已经被放置在 flash 中以节省 IRAM。
|
||||
- 如果已启用 :ref:`CONFIG_RINGBUF_IN_IRAM`，请将其禁用，以便将环形缓冲区函数放置在 flash 中而不是 IRAM 中。默认情况下，环形缓冲区函数已经被放置在 flash 中以节省 IRAM。
|
||||
- 启用 :ref:`CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH`。如果从 IRAM 中的中断上下文中使用 ISR ringbuf 函数，例如启用了 :ref:`CONFIG_UART_ISR_IN_IRAM`，则无法安全使用此选项。在此情况下，安装 ESP-IDF 相关驱动程序时，将在运行时报错。
|
||||
:SOC_WIFI_SUPPORTED: - 禁用 Wi-Fi 选项 :ref:`CONFIG_ESP_WIFI_IRAM_OPT` 和/或 :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT` 会释放可用 IRAM，但会牺牲部分 Wi-Fi 性能。
|
||||
:CONFIG_ESP_ROM_HAS_SPI_FLASH: - 启用 :ref:`CONFIG_SPI_FLASH_ROM_IMPL` 选项可以释放一些 IRAM，但此时 esp_flash 错误修复程序及新的 flash 芯片支持将失效，详情请参阅 :doc:`/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom`。
|
||||
|
||||
@@ -152,11 +152,11 @@
|
||||
|
||||
- 将频繁执行的代码移至 IRAM。应用程序中的所有代码都默认从 flash 中执行。这意味着缓存缺失时，CPU 需要等待从 flash 加载后续指令。如果将函数复制到 IRAM 中，则仅需要在启动时加载一次，然后始终以全速执行。
|
||||
|
||||
IRAM 资源有限，使用更多的 IRAM 可能会减少可用的 DRAM。因此，将代码移动到 IRAM 需要有所取舍。更多信息参见 :ref:`iram` 。
|
||||
IRAM 资源有限，使用更多的 IRAM 可能会减少可用的 DRAM。因此，将代码移动到 IRAM 需要有所取舍。更多信息参见 :ref:`iram`。
|
||||
|
||||
- 针对不需要放置在 IRAM 中的单个源文件，可以重新启用跳转表优化。这将提高大型 ``switch cases`` 代码中的热路径性能。关于如何在编译单个源文件时添加 -fjump-tables -ftree-switch-conversion 选项，参见 :ref:`component_build_control` 。
|
||||
- 针对不需要放置在 IRAM 中的单个源文件，可以重新启用跳转表优化。这将提高大型 ``switch cases`` 代码中的热路径性能。关于如何在编译单个源文件时添加 -fjump-tables -ftree-switch-conversion 选项，参见 :ref:`component_build_control`。
|
||||
|
||||
- 许多 ESP-IDF 组件和驱动程序提供配置选项，将性能关键函数放置在 IRAM 中以减少延迟并提高速度。这些选项通常具有类似 ``CONFIG_*_IN_IRAM``、``CONFIG_*_ISR_IN_IRAM`` 或 ``CONFIG_*_IRAM_OPT`` 的名称。一些示例包括 :ref:`CONFIG_FREERTOS_IN_IRAM` 用于 FreeRTOS 函数，:ref:`CONFIG_ESP_WIFI_IRAM_OPT` 用于 Wi-Fi 操作，:ref:`CONFIG_UART_ISR_IN_IRAM` 用于 UART 中断处理，:ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` 用于 SPI 操作。这些选项以 IRAM 使用量换取速度，因此应根据应用程序的性能要求和可用 IRAM 空间有选择地使用。
|
||||
- 许多 ESP-IDF 组件和驱动程序提供了配置选项，用于将性能关键的函数放置在 IRAM 中以降低延迟并提高速度。这些选项通常以 ``CONFIG_*_IN_IRAM``、``CONFIG_*_ISR_IN_IRAM`` 或 ``CONFIG_*_IRAM_OPT`` 命名。例如，FreeRTOS 函数的 :ref:`CONFIG_FREERTOS_IN_IRAM`，Wi-Fi 操作的 :ref:`CONFIG_ESP_WIFI_IRAM_OPT`，UART 中断处理的 :ref:`CONFIG_UART_ISR_IN_IRAM`，以及 SPI 操作的 :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM`。这些选项通过增加 IRAM 占用换取速度提升，因此应根据应用的性能需求和可用 IRAM 空间有选择地使用。
|
||||
|
||||
减少启动时间
|
||||
----------------------------
|
||||
|
||||
@@ -38,10 +38,16 @@ ESP HTTPS OTA 升级
|
||||
|
||||
应使用服务器端点的 **根** 证书应用于验证，而不能使用证书链中的任何中间证书，因为根证书有效期最长，且通常长时间维持不变。用户还可以通过 :cpp:member:`esp_http_client_config_t::crt_bundle_attach` 成员使用 ``ESP x509 证书包`` 功能进行验证，其中涵盖了大多数受信任的根证书。
|
||||
|
||||
通过 HTTPS 下载部分镜像
|
||||
通过 HTTPS 分段下载镜像
|
||||
---------------------------------
|
||||
|
||||
要使用部分镜像下载功能，请启用 ``esp_https_ota_config_t`` 中的 ``partial_http_download`` 配置。启用此配置后，固件镜像将通过多个指定大小的 HTTP 请求进行下载。将 ``max_http_request_size`` 设置为所需值，即可指定每个请求的最大内容长度。
|
||||
要使用分段镜像下载功能，需要：
|
||||
|
||||
* **启用组件级配置**：在 menuconfig 中启用 :ref:`CONFIG_ESP_HTTPS_OTA_ENABLE_PARTIAL_DOWNLOAD` in menuconfig (``Component config`` → ``ESP HTTPS OTA`` → ``Enable partial HTTP download for OTA``)
|
||||
|
||||
* **在应用程序中启用该功能**：在 :cpp:struct:`esp_https_ota_config_t` 配置结构中设置 ``partial_http_download`` 字段
|
||||
|
||||
启用该配置后，固件镜像将通过多个指定大小的 HTTP 请求进行下载。通过将 ``max_http_request_size`` 设置为所需值，即可指定每个请求的最大内容长度。
|
||||
|
||||
在从 AWS S3 等服务获取镜像时，这一选项非常有用。在启用该选项时，可以将 mbedTLS Rx 的 buffer 大小（即 :ref:`CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN`）设置为较小的值。不启用此配置时，无法将其设置为较小值。
|
||||
|
||||
|
||||
@@ -282,7 +282,7 @@ macOS::
|
||||
Windows 和 Linux 操作系统
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
在本示例中，我们将使用 `PuTTY SSH Client <https://www.putty.org/>`_，`PuTTY SSH Client <https://www.putty.org/>`_ 既可用于 Windows 也可用于 Linux。也可以使用其他串口程序并设置如下的通信参数。
|
||||
在本示例中，我们使用 `PuTTY SSH Client <https://putty.software/>`_，该工具可在 Windows 和 Linux 上使用。你也可以使用其他串口程序，并按照下方所示设置通信参数。
|
||||
|
||||
运行终端，配置在上述步骤中确认的串口：波特率 = 115200（如有需要，请更改为使用芯片的默认波特率），数据位 = 8，停止位 = 1，奇偶校验 = N。以下截屏分别展示了如何在 Windows 和 Linux 中配置串口和上述通信参数（如 115200-8-1-N）。注意，这里一定要选择在上述步骤中确认的串口进行配置。
|
||||
|
||||
|
||||
@@ -157,13 +157,13 @@ LCD
|
||||
SPI
|
||||
---
|
||||
|
||||
:ref:`CONFIG_SPI_MASTER_IN_IRAM` 选项现在在 menuconfig 中默认不可见，并且依赖于 :ref:`CONFIG_FREERTOS_IN_IRAM`。此更改是为了防止位于 IRAM 中的 SPI 函数调用位于 Flash 中的 FreeRTOS 函数时可能发生的崩溃。
|
||||
:ref:`CONFIG_SPI_MASTER_IN_IRAM` 选项在 menuconfig 中默认不可见，并且依赖于 :ref:`CONFIG_FREERTOS_IN_IRAM`。这样修改是为了防止位于 IRAM 中的 SPI 函数调用位于 flash 中的 FreeRTOS 函数时可能发生的崩溃。
|
||||
|
||||
要启用 SPI 主机 IRAM 优化：
|
||||
|
||||
1. 在 menuconfig 中导航到 ``Component config`` → ``FreeRTOS`` → ``Port``
|
||||
1. 在 menuconfig 中进入 ``Component config`` → ``FreeRTOS`` → ``Port``
|
||||
2. 启用 ``Place FreeRTOS functions in IRAM`` (:ref:`CONFIG_FREERTOS_IN_IRAM`)
|
||||
3. 导航到 ``Component config`` → ``ESP-Driver:SPI Configurations``
|
||||
3. 在 menuconfig 中进入 ``Component config`` → ``ESP-Driver:SPI Configurations``
|
||||
4. 启用 ``Place transmitting functions of SPI master into IRAM`` (:ref:`CONFIG_SPI_MASTER_IN_IRAM`)
|
||||
|
||||
请注意，启用 :ref:`CONFIG_FREERTOS_IN_IRAM` 会显著增加 IRAM 使用量。在为 SPI 性能进行优化时，请考虑此权衡。
|
||||
请注意，启用 :ref:`CONFIG_FREERTOS_IN_IRAM` 会显著增加 IRAM 使用量。在优化 SPI 性能时，需进行权衡。
|
||||
|
||||
@@ -105,9 +105,11 @@ FreeRTOS
|
||||
|
||||
**内存布局**
|
||||
|
||||
为了减少 IRAM 的使用，大多数 FreeRTOS 函数的默认位置已从 IRAM 更改为 Flash。因此，``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` 选项已被移除。此举可节省大量 IRAM，但可能会对性能造成轻微影响。对于性能要求严苛的应用程序，可通过启用新增的 :ref:`CONFIG_FREERTOS_IN_IRAM` 选项来恢复之前的行为。
|
||||
在决定是否启用 ``CONFIG_FREERTOS_IN_IRAM`` 时，建议进行性能测试以测量对特定用例的实际影响。Flash 和 IRAM 配置之间的性能差异可能因 Flash 缓存效率、API 使用模式和系统负载而异。
|
||||
在 ``components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c`` 中提供了基准性能测试，用于测量常用 FreeRTOS API 的执行时间。此测试可帮助您评估内存布局对目标硬件和应用程序要求的性能影响。
|
||||
为了减少 IRAM 的使用，大多数 FreeRTOS 函数的默认位置已从 IRAM 更改为 flash。因此，``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` 选项已被移除。这项变更可显著节省 IRAM 空间，但可能会对性能造成轻微影响。如果应用对性能有严苛要求，可通过启用新增的 :ref:`CONFIG_FREERTOS_IN_IRAM` 选项来恢复原先配置。
|
||||
|
||||
在决定是否启用 ``CONFIG_FREERTOS_IN_IRAM`` 时，建议进行性能测试以评估对具体应用场景的实际影响。flash 和 IRAM 配置的性能差异会受 flash 缓存效率、API 调用模式和系统负载等因素影响。
|
||||
|
||||
``components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c`` 中提供了基准性能测试，可测量常用 FreeRTOS API 的执行时间。该测试有助于根据目标硬件和应用需求评估内存布局调整带来的性能影响。
|
||||
|
||||
环形缓冲区
|
||||
----------
|
||||
@@ -139,6 +141,13 @@ CRC 数据完整性检查已被弃用。`ESP_COREDUMP_CHECKSUM_CRC32` 表示该
|
||||
|
||||
函数 :cpp:func:`esp_core_dump_partition_and_size_get()` 现在对空白（已擦除）分区返回 `ESP_ERR_NOT_FOUND`，而不是 `ESP_ERR_INVALID_SIZE`。
|
||||
|
||||
OTA 更新
|
||||
-----------
|
||||
|
||||
ESP HTTPS OTA 的分段下载功能已移至配置选项下，以便在未使用分段下载时减少内存占用。
|
||||
|
||||
如果要在 OTA 应用中使用分段下载功能，需要在 menuconfig 中启用组件级配置 :ref:`CONFIG_ESP_HTTPS_OTA_ENABLE_PARTIAL_DOWNLOAD` (``Component config`` → ``ESP HTTPS OTA`` → ``Enable partial HTTP download for OTA``)。
|
||||
|
||||
Gcov
|
||||
----
|
||||
|
||||
|
||||
Reference in New Issue
Block a user