From 811431b99f1bf9d29f4bde08427265a36356bf9b Mon Sep 17 00:00:00 2001 From: Shen Mengjing Date: Wed, 8 Jul 2026 17:52:54 +0800 Subject: [PATCH] docs: Sync CN and EN docs without translation label --- docs/en/api-reference/peripherals/i2s.rst | 11 +-- .../api-reference/peripherals/sdmmc_host.rst | 3 - .../spi_flash/spi_flash_concurrency.rst | 1 + docs/en/api-reference/system/esp_err.rst | 4 +- .../api-reference/system/power_management.rst | 1 + .../zh_CN/api-guides/jtag-debugging/index.rst | 1 - docs/zh_CN/api-reference/peripherals/i2s.rst | 10 +-- .../api-reference/peripherals/sdmmc_host.rst | 8 ++- .../protocols/esp_http_client.rst | 4 +- .../zh_CN/api-reference/protocols/esp_tls.rst | 3 +- docs/zh_CN/api-reference/system/efuse.rst | 4 +- docs/zh_CN/api-reference/system/esp_err.rst | 70 +++++++++++++++++++ .../api-reference/system/power_management.rst | 4 +- 13 files changed, 93 insertions(+), 31 deletions(-) diff --git a/docs/en/api-reference/peripherals/i2s.rst b/docs/en/api-reference/peripherals/i2s.rst index 64a41f65d98..91bad27e598 100644 --- a/docs/en/api-reference/peripherals/i2s.rst +++ b/docs/en/api-reference/peripherals/i2s.rst @@ -345,16 +345,9 @@ To satisfy the high quality audio requirement, following advanced APIs are provi The typical usage steps are: 1. Create and initialize an I2S TX channel. - 2. Call :cpp:func:`i2s_channel_config_tx_fifo_sync` to configure :cpp:type:`i2s_tx_fifo_sync_config_t`. ``ideal_cnt`` - is the expected number of transmitted data units at each ETM synchronization check. This step can be performed while the TX channel is running, but TX FIFO synchronization must be disabled before reconfiguration. ``auto_suppl_thresh`` is - the automatic hardware supplement threshold and must be smaller than ``manual_suppl_thresh``. - ``manual_suppl_thresh`` is the threshold for triggering the callback for manual handling. If the difference - exceeds the automatic supplement threshold but has not reached the manual supplement threshold, hardware - automatically supplements or deletes the corresponding amount of data to synchronize with ``ideal_cnt``. + 2. Call :cpp:func:`i2s_channel_config_tx_fifo_sync` to configure :cpp:type:`i2s_tx_fifo_sync_config_t`. ``ideal_cnt`` is the expected number of transmitted data units at each ETM synchronization check. This step can be performed while the TX channel is running, but TX FIFO synchronization must be disabled before reconfiguration. ``auto_suppl_thresh`` is the automatic hardware supplement threshold and must be smaller than ``manual_suppl_thresh``. ``manual_suppl_thresh`` is the threshold for triggering the callback for manual handling. If the difference exceeds the automatic supplement threshold but has not reached the manual supplement threshold, hardware automatically supplements or deletes the corresponding amount of data to synchronize with ``ideal_cnt``. 3. To handle severe out-of-sync conditions, call :cpp:func:`i2s_channel_register_event_callback` to register a callback. - 4. Call :cpp:func:`i2s_channel_enable_tx_fifo_sync` with ``enable`` set to ``true`` to activate both automatic - hardware supplementation and manual interrupt simultaneously. This call resets the TX FIFO/BCLK synchronization - counters, so the first ETM synchronization check uses a new count window. + 4. Call :cpp:func:`i2s_channel_enable_tx_fifo_sync` with ``enable`` set to ``true`` to activate both automatic hardware supplementation and manual interrupt simultaneously. This call resets the TX FIFO/BCLK synchronization counters, so the first ETM synchronization check uses a new count window. 5. Call :cpp:func:`i2s_new_etm_task` to create the ``I2S_ETM_TASK_SYNC_FIFO`` task, and connect an external ETM event to this task. 6. Enable the ETM channel and I2S TX channel, so that ETM events periodically trigger synchronization checks. diff --git a/docs/en/api-reference/peripherals/sdmmc_host.rst b/docs/en/api-reference/peripherals/sdmmc_host.rst index 19b40c24cff..a8e91ad4e4f 100644 --- a/docs/en/api-reference/peripherals/sdmmc_host.rst +++ b/docs/en/api-reference/peripherals/sdmmc_host.rst @@ -66,7 +66,6 @@ Overview Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be concurrently shared between an SD card and an SPI flash. If you need to use Slot 0, establish an alternative connection for the SPI flash using different pins and configure the necessary eFuses accordingly. - .. only:: esp32s3 Both slots :c:macro:`SDMMC_HOST_SLOT_0` and :c:macro:`SDMMC_HOST_SLOT_1` support 1-, 4- and 8-line SD interfaces. The slots are connected to {IDF_TARGET_NAME} GPIOs using the GPIO matrix. This means that any GPIO may be used for each of the SD card signals. @@ -215,7 +214,5 @@ API Reference ------------- .. include-build-file:: inc/sdmmc_host.inc - .. include-build-file:: inc/sd_pwr_ctrl.inc - .. include-build-file:: inc/sd_pwr_ctrl_by_on_chip_ldo.inc diff --git a/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst b/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst index 245d326357d..7459ced67f4 100644 --- a/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst +++ b/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst @@ -86,6 +86,7 @@ See :ref:`iram-safe-interrupt-handlers` for information on how to prevent an int When the cache is disabled, all CPUs should execute code and access data only from internal RAM. For differences between internal RAM (e.g., IRAM, DRAM) and flash cache, please refer to the :ref:`application memory layout ` documentation. + .. _iram-safe-interrupt-handlers: IRAM-Safe Interrupt Handlers diff --git a/docs/en/api-reference/system/esp_err.rst b/docs/en/api-reference/system/esp_err.rst index bb7271d5354..6658acdd804 100644 --- a/docs/en/api-reference/system/esp_err.rst +++ b/docs/en/api-reference/system/esp_err.rst @@ -12,7 +12,7 @@ For the full list of error codes defined in ESP-IDF, see :doc:`Error Codes Refer .. _registering-error-codes: Registering Error Codes ------------------------- +----------------------- ESP-IDF uses a composable error code registration system that automatically collects error code definitions from all components at build time. This allows :cpp:func:`esp_err_to_name` and :cpp:func:`esp_err_to_name_r` to look up error codes defined across the entire project without requiring manual maintenance of a central registry. @@ -77,7 +77,7 @@ After building your project, calls to ``esp_err_to_name(ESP_ERR_MY_COMPONENT_INI .. note:: - Most ESP-IDF components already have their error codes registered. You only need to add ``idf_define_esp_err_codes()`` for your own custom components or when adding new error codes to existing components. + Most ESP-IDF components already have their error codes registered. You only need to add ``idf_define_esp_err_codes()`` for your own custom components or for new error codes added to existing components. .. _esp-check-api-ref: diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index aabcb3b0326..51d6dceab78 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -63,6 +63,7 @@ Dynamic frequency scaling (DFS) and automatic Light-sleep can be enabled in an a Power Management Locks ---------------------- + {IDF_TARGET_MAX_CPU_FREQ: default="Not updated yet", esp32="80 MHz, 160 MHz, or 240 MHz", esp32s2="80 MHz, 160 MHz, or 240 MHz", esp32s3="80 MHz, 160 MHz, or 240 MHz", esp32c2="80 MHz or 120 MHz", esp32c3="80 MHz or 160 MHz", esp32c6="80 MHz or 160 MHz", esp32p4="360 MHz", esp32c5="80 MHz, 160 MHz or 240 MHz", esp32c61="80 MHz or 160 MHz"} Applications have the ability to acquire/release locks in order to control the power management algorithm. When an application acquires a lock, the power management algorithm operation is restricted in a way described below. When the lock is released, such restrictions are removed. diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index 269e05d8114..3b199c19842 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -341,7 +341,6 @@ semihosting tips-and-quirks - 相关文档 -------- diff --git a/docs/zh_CN/api-reference/peripherals/i2s.rst b/docs/zh_CN/api-reference/peripherals/i2s.rst index 1ac807ad296..9d9592e38d7 100644 --- a/docs/zh_CN/api-reference/peripherals/i2s.rst +++ b/docs/zh_CN/api-reference/peripherals/i2s.rst @@ -345,15 +345,9 @@ I2S 的数据传输（包括数据发送和接收）由 DMA 实现。在传输 使用该功能的一般步骤如下： 1. 创建并初始化 I2S TX 通道。 - 2. 调用 :cpp:func:`i2s_channel_config_tx_fifo_sync` 配置 :cpp:type:`i2s_tx_fifo_sync_config_t`。``ideal_cnt`` - 为每次 ETM 同步检查时期望发送的数据个数。该步骤可在 TX 通道运行时执行，但重新配置前必须先关闭 TX FIFO 同步功能。``auto_suppl_thresh`` 为硬件自动补偿阈值， - 必须小于 ``manual_suppl_thresh``。 - ``manual_suppl_thresh`` 为触发回调并交由软件手动处理的阈值。如果偏差 - 超过自动补偿阈值但尚未达到手动补偿阈值，硬件会自动补充或删除相应数量的数据， - 以实现与 ``ideal_cnt`` 同步。 + 2. 调用 :cpp:func:`i2s_channel_config_tx_fifo_sync` 配置 :cpp:type:`i2s_tx_fifo_sync_config_t`。``ideal_cnt`` 为每次 ETM 同步检查时期望发送的数据个数。该步骤可在 TX 通道运行时执行，但重新配置前必须先关闭 TX FIFO 同步功能。``auto_suppl_thresh`` 为硬件自动补偿阈值，必须小于 ``manual_suppl_thresh``。``manual_suppl_thresh`` 为触发回调并交由软件手动处理的阈值。如果偏差超过自动补偿阈值但尚未达到手动补偿阈值，硬件会自动补充或删除相应数量的数据，以实现与 ``ideal_cnt`` 同步。 3. 如需处理严重不同步场景，调用 :cpp:func:`i2s_channel_register_event_callback` 注册回调。 - 4. 调用 :cpp:func:`i2s_channel_enable_tx_fifo_sync` 并将 ``enable`` 设为 ``true``，同时激活硬件自动补偿 - 和手动补偿中断。该调用会重置 TX FIFO/BCLK 同步计数器，因此第一次 ETM 同步检查会使用新的计数窗口。 + 4. 调用 :cpp:func:`i2s_channel_enable_tx_fifo_sync` 并将 ``enable`` 设为 ``true``，同时激活硬件自动补偿和手动补偿中断。该调用会重置 TX FIFO/BCLK 同步计数器，因此第一次 ETM 同步检查会使用新的计数窗口。 5. 调用 :cpp:func:`i2s_new_etm_task` 创建 ``I2S_ETM_TASK_SYNC_FIFO`` 任务，并将外部 ETM 事件连接到该任务。 6. 使能 ETM 通道和 I2S TX 通道，由 ETM 事件周期性触发同步检查。 diff --git a/docs/zh_CN/api-reference/peripherals/sdmmc_host.rst b/docs/zh_CN/api-reference/peripherals/sdmmc_host.rst index 75ad46c74d0..f36b1895d51 100644 --- a/docs/zh_CN/api-reference/peripherals/sdmmc_host.rst +++ b/docs/zh_CN/api-reference/peripherals/sdmmc_host.rst @@ -66,7 +66,6 @@ SDMMC 主机驱动 卡槽 0 使用的管脚 (``HS1_*``) 既用于连接主机上的 SD 卡插槽，也用于连接 ESP32-WROOM 和 ESP32-WROVER 模组中的 SPI flash 芯片，但这些管脚不能同时用于 SD 卡与 SPI flash。如需使用卡槽 0，请将 SPI flash 连接到其他管脚，并根据需要配置 eFuse。 - .. only:: esp32s3 卡槽 :c:macro:`SDMMC_HOST_SLOT_0` 和 :c:macro:`SDMMC_HOST_SLOT_1` 都支持 1、4、8 线的 SD 接口，这些卡槽通过 GPIO 交换矩阵连接到 {IDF_TARGET_NAME} 的 GPIO，即每个 SD 卡信号都可以使用任意 GPIO 连接。 @@ -78,6 +77,11 @@ SDMMC 主机驱动 在 {IDF_TARGET_NAME} 上，SDMMC 主机需要外部电源为 IO 电压供电。详情请参阅 :ref:`pwr-ctrl`。 +.. only:: esp32s31 + + - 卡槽 :c:macro:`SDMMC_HOST_SLOT_0` 和 :c:macro:`SDMMC_HOST_SLOT_1` 均使用专用 IO。 + - :c:macro:`SDMMC_HOST_SLOT_0` 支持 UHS-I 模式。 + 支持的速率模式 --------------------- @@ -210,7 +214,5 @@ API 参考 ------------- .. include-build-file:: inc/sdmmc_host.inc - .. include-build-file:: inc/sd_pwr_ctrl.inc - .. include-build-file:: inc/sd_pwr_ctrl_by_on_chip_ldo.inc diff --git a/docs/zh_CN/api-reference/protocols/esp_http_client.rst b/docs/zh_CN/api-reference/protocols/esp_http_client.rst index 057eed20cb0..af05049cdba 100644 --- a/docs/zh_CN/api-reference/protocols/esp_http_client.rst +++ b/docs/zh_CN/api-reference/protocols/esp_http_client.rst @@ -16,8 +16,8 @@ ESP HTTP 客户端 应用示例 -------- -:example:`protocols/esp_http_client` 演示了如何使用 ESP HTTP 客户端发起 HTTP/S 请求。 - +- :example:`protocols/esp_http_client` 演示了如何使用 ESP HTTP 客户端发起 HTTP/S 请求。 +- :example:`protocols/esp_http_client_mutual_auth` 演示了如何使用 ESP HTTP 客户端配置双向 TLS 认证。 HTTP 基本请求 ------------- diff --git a/docs/zh_CN/api-reference/protocols/esp_tls.rst b/docs/zh_CN/api-reference/protocols/esp_tls.rst index 1967aed1cae..dfc6f3dee75 100644 --- a/docs/zh_CN/api-reference/protocols/esp_tls.rst +++ b/docs/zh_CN/api-reference/protocols/esp_tls.rst @@ -258,7 +258,8 @@ ESP-TLS 支持通过 PSA Crypto 不透明驱动接口在 ESP32 系列芯片上 psa_status_t status = psa_import_key(&key_attr, (const uint8_t *)&opaque_key, sizeof(opaque_key), &psa_key_id); if (status != PSA_SUCCESS) { - /* 处理错误 - 通常表示安全元件回调未注册或属性无效。 */ + /* 处理错误 - 通常表示安全元件回调未注册 + * 或属性无效。 */ return; } diff --git a/docs/zh_CN/api-reference/system/efuse.rst b/docs/zh_CN/api-reference/system/efuse.rst index ebfd87d8bec..ab76261aedb 100644 --- a/docs/zh_CN/api-reference/system/efuse.rst +++ b/docs/zh_CN/api-reference/system/efuse.rst @@ -278,9 +278,9 @@ eFuse 支持各种编码方式，能够检测或纠正错误，保护 eFuse 数 由于采用批量写入模式，一个编码单元只能写入一次，禁止在同一编码单元重复写入。这意味着，在运行时写入的编码单元中只能包含一个 eFuse 字段。但是，如果事先通过 CSV 文件指定了编码单元的 eFuse 字段，或通过 :cpp:func:`esp_efuse_write_block` 写入编码单元的 eFuse 字段，那么一个编码单元中仍可包含多个 eFuse 字段。 - ``重复编码`` 方式 ^^^^^^^^^^^^^^^^^^^^^^^^ + ``重复编码`` 方式只是简单重复每个 eFuse 位，不会像 ``3/4 编码`` 方式那样受到批量写入模式的限制。不过，这样做会产生很大的开销，每个 eFuse 块中只有 128 个位可用。 .. only:: not esp32 @@ -356,6 +356,8 @@ eFuse API * :cpp:func:`esp_efuse_get_keypurpose_dis_write` - 返回 eFuse 密钥块的密钥用途字段的写保护状态（对于 esp32 始终为 true）。 * :cpp:func:`esp_efuse_key_block_unused` - 如果密钥块未使用，则返回 true，否则返回 false。 * :cpp:func:`esp_efuse_destroy_block` - 销毁此 eFuse 块中的数据。该函数有两个作用：(1) 如果未开启写保护，则将不为 1 的位都烧写为 1；(2) 如果未开启读保护，则开启读保护。 +* :cpp:func:`esp_efuse_token_dump` - 生成紧凑的单行 eFuse 令牌（``EFSR``、``EFSW`` 或 ``EFSRW``），可从设备日志中复制，并在主机端通过 ``espefuse --token ...`` 进行解码（适用于无法直接访问 eFuse 的场景）。 +* :cpp:func:`esp_efuse_token_burn` - 通过烧录暂存且已编码至令牌中的 eFuse 写入数据，在设备上应用 ``EFSW`` 令牌（其他类型的令牌将被拒绝）。 经常使用的字段有专门的函数可供使用，例如 :cpp:func:`esp_efuse_get_pkg_ver`。 diff --git a/docs/zh_CN/api-reference/system/esp_err.rst b/docs/zh_CN/api-reference/system/esp_err.rst index 12491c82ecc..bcbc8180017 100644 --- a/docs/zh_CN/api-reference/system/esp_err.rst +++ b/docs/zh_CN/api-reference/system/esp_err.rst @@ -9,6 +9,76 @@ 有关 ESP-IDF 定义的错误代码的完整列表，请参阅 :doc:`错误代码参考 <../error-codes>`。 +.. _registering-error-codes: + +注册错误码 +---------- + +ESP-IDF 使用可组合的错误码注册系统，在构建时自动从所有组件中收集错误码定义。这使得 :cpp:func:`esp_err_to_name` 和 :cpp:func:`esp_err_to_name_r` 能够查找整个项目中定义的错误码，而无需手动维护中央注册表。 + +工作原理 +^^^^^^^^ + +错误码在链接时通过名为 ``.esp_err_msg_tbl`` 的链接器段进行注册。在组件的头文件中定义错误码后，需要将这些头文件注册到构建系统中，构建系统将会： + +1. 在构建过程中提取错误码定义 +2. 生成 C 代码，将错误码放入 ``.esp_err_msg_tbl`` 段 +3. 自动将生成的 C 代码链接到应用程序中 + +链接器会将所有组件中的错误码条目收集到一个数组中，供 :cpp:func:`esp_err_to_name` 在运行时查找。 + +注册组件的错误码 +^^^^^^^^^^^^^^^^ + +要注册组件中的错误码，请在组件的 ``CMakeLists.txt`` 中添加以下内容： + +.. code-block:: cmake + + idf_define_esp_err_codes(HEADERS include/my_component.h) + +将 ``include/my_component.h`` 替换为包含错误码定义的头文件路径。可以指定多个头文件： + +.. code-block:: cmake + + idf_define_esp_err_codes(HEADERS + include/my_api.h + include/my_driver.h + ) + +构建系统将自动处理这些头文件，并注册所有符合错误码命名规则的 ``#define`` 指令（通常以 ``ESP_ERR_`` 或类似前缀开头）。 + +示例 +^^^^ + +在组件的头文件 ``include/my_component.h`` 中： + +.. code-block:: c + + #pragma once + + #include "esp_err.h" + + #define ESP_ERR_MY_COMPONENT_BASE 0x7000 + #define ESP_ERR_MY_COMPONENT_INIT (ESP_ERR_MY_COMPONENT_BASE + 1) /*!< Component initialization failed */ + #define ESP_ERR_MY_COMPONENT_BUSY (ESP_ERR_MY_COMPONENT_BASE + 2) /*!< Component is busy */ + +在组件的 ``CMakeLists.txt`` 中： + +.. code-block:: cmake + + idf_component_register(SRCS "my_component.c" + INCLUDE_DIRS "include" + PRIV_REQUIRES esp_common) + + # Register error codes + idf_define_esp_err_codes(HEADERS include/my_component.h) + +构建项目后，调用 ``esp_err_to_name(ESP_ERR_MY_COMPONENT_INIT)`` 将返回字符串 ``"ESP_ERR_MY_COMPONENT_INIT"``。 + +.. note:: + + 大多数 ESP-IDF 组件的错误码已经完成注册，只有在为自定义组件注册错误码，或向现有组件添加新错误码时，才需要添加 ``idf_define_esp_err_codes()``。 + .. _esp-check-api-ref: API 参考 diff --git a/docs/zh_CN/api-reference/system/power_management.rst b/docs/zh_CN/api-reference/system/power_management.rst index a02f8fde083..3ca6481c352 100644 --- a/docs/zh_CN/api-reference/system/power_management.rst +++ b/docs/zh_CN/api-reference/system/power_management.rst @@ -49,6 +49,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， Light-sleep 状态下，外设设有时钟门控，不会产生来自 GPIO 和内部外设的中断。:doc:`sleep_modes` 文档中所提到的唤醒源可用于从 Light-sleep 状态触发唤醒。 .. warning:: + 自动 Light-sleep 模式基于定时器唤醒实现，请勿手动配置定时器唤醒源。 .. only:: SOC_PM_SUPPORT_EXT0_WAKEUP and SOC_PM_SUPPORT_EXT1_WAKEUP @@ -61,7 +62,8 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， 电源管理锁 ----------------------- +---------- + {IDF_TARGET_MAX_CPU_FREQ: default="Not updated yet", esp32="80 MHz, 160 MHz, or 240 MHz", esp32s2="80 MHz, 160 MHz, 或 240 MHz", esp32s3="80 MHz, 160 MHz, 或 240 MHz", esp32c2="80 MHz 或 120 MHz", esp32c3="80 MHz 或 160 MHz", esp32c6="80 MHz 或 160 MHz", esp32p4="360 MHz", esp32c5="80 MHz, 160 MHz, 或 240 MHz", esp32c61="80 MHz 或 160 MHz"} 应用程序可以通过获取或释放管理锁来控制电源管理算法。应用程序获取电源管理锁后，电源管理算法的操作将受到下面的限制。释放电源管理锁后，限制解除。