Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-02 03:00:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(kconfig): update kconfig ref links to use menuitem

Browse Source
This commit is contained in:
Marius Vikhammer
2026-08-11 11:19:45 +02:00
parent c6e80a336a
commit 4d332f710e
304 changed files with 2362 additions and 2372 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh_CN/api-reference/peripherals/adc/adc_calibration.rst
+3 -3
View File
@@ -185,9 +185,9 @@ ADC 校准驱动程序会提供 ADC 校准方案。对于驱动程序来说，
Kconfig 选项
^^^^^^^^^^^^^^^
- :ref:`CONFIG_ADC_CALI_EFUSE_TP_ENABLE` - 如果校准相关的 eFuse 值没有配置为 :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP`，则可以禁用该选项，减小代码大小。
- :ref:`CONFIG_ADC_CALI_EFUSE_VREF_ENABLE` - 如果校准相关的 eFuse 值没有配置为 :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`，则可以禁用该选项，减小代码大小。
- :ref:`CONFIG_ADC_CALI_LUT_ENABLE` - 如果校准 ADC 原始结果时，衰减没有设置成 :c:macro:`ADC_ATTEN_DB_12`，则可以禁用该选项，减小代码大小。
- :menuitem:`CONFIG_ADC_CALI_EFUSE_TP_ENABLE` - 如果校准相关的 eFuse 值没有配置为 :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP`，则可以禁用该选项，减小代码大小。
- :menuitem:`CONFIG_ADC_CALI_EFUSE_VREF_ENABLE` - 如果校准相关的 eFuse 值没有配置为 :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`，则可以禁用该选项，减小代码大小。
- :menuitem:`CONFIG_ADC_CALI_LUT_ENABLE` - 如果校准 ADC 原始结果时，衰减没有设置成 :c:macro:`ADC_ATTEN_DB_12`，则可以禁用该选项，减小代码大小。
.. _adc-minimize-noise:
docs/zh_CN/api-reference/peripherals/adc/adc_continuous.rst
+6 -6
View File
@@ -252,7 +252,7 @@ ADC 控制
在调用 :cpp:func:`adc_continuous_register_event_callbacks` 时，还可以通过参数 ``user_data`` 注册自己的上下文，该用户数据将直接传递给回调函数。
此回调函数可能由于 :c:macro:`ESP_ERR_INVALID_ARG` 等原因返回错误。启用 :ref:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` 时，如果回调函数失败并报错，可能是因为回调函数不在内部 RAM 中，请查看错误日志了解详情。此外，如果回调函数出现 :c:macro:`ESP_ERR_INVALID_STATE` 错误，表明 ADC 连续转换模式驱动已经启动，此时不应添加回调。
此回调函数可能由于 :c:macro:`ESP_ERR_INVALID_ARG` 等原因返回错误。启用 :menuitem:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` 时，如果回调函数失败并报错，可能是因为回调函数不在内部 RAM 中，请查看错误日志了解详情。此外，如果回调函数出现 :c:macro:`ESP_ERR_INVALID_STATE` 错误，表明 ADC 连续转换模式驱动已经启动，此时不应添加回调。
转换完成事件
@@ -266,7 +266,7 @@ ADC 控制
.. note::
启用 Kconfig 选项 :ref:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` 时，注册的回调函数以及回调函数中调用的函数应放置在 IRAM 中，涉及的变量也应放置在内部 RAM 中。
启用 Kconfig 选项 :menuitem:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` 时，注册的回调函数以及回调函数中调用的函数应放置在 IRAM 中，涉及的变量也应放置在内部 RAM 中。
缓冲池溢出事件
~~~~~~~~~~~~~~~~~~~
@@ -395,15 +395,15 @@ ADC 连续转换模式读取的原始数据需要进一步解析才能获得可
:esp32: - ESP32 DevKitC：由于存在外部自动烧录电路，GPIO 0 不能用于 ADC 连续转换模式。
:esp32: - ESP-WROVER-KIT：由于部分 GPIO 管脚可能已经用于其他目的，GPIO 0、2、4 和 15 不能用于 ADC 连续转换模式。
:esp32s2: - ADC 连续转换模式驱动使用 SPI3 外设作为硬件 DMA FIFO。因此，如果 SPI3 已在使用中，:cpp:func:`adc_continuous_new_handle` 将返回 :c:macro:`ESP_ERR_NOT_FOUND`。
:esp32c3: - 由于硬件限制，现已不再支持使用 ADC2 DMA 功能获取 ADC 转换结果。使用 ADC2 连续转换的结果可能不稳定，具体可参考 `ESP32-C3 系列芯片勘误表 <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_cn.pdf>`__。出于兼容性考虑，可以启用 :ref:`CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3`，强制使用 ADC2。
:esp32s3: - 由于硬件限制，现已不再支持使用 ADC2 DMA 功能获取 ADC 转换结果。使用 ADC2 连续转换的结果可能不稳定，具体可参考 `ESP32-S3 系列芯片勘误表 <https://www.espressif.com/sites/default/files/documentation/esp32-s3_errata_cn.pdf>`__。出于兼容性考虑，可以启用 :ref:`CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3`，强制使用 ADC2。
:esp32c3: - 由于硬件限制，现已不再支持使用 ADC2 DMA 功能获取 ADC 转换结果。使用 ADC2 连续转换的结果可能不稳定，具体可参考 `ESP32-C3 系列芯片勘误表 <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_cn.pdf>`__。出于兼容性考虑，可以启用 :menuitem:`CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3`，强制使用 ADC2。
:esp32s3: - 由于硬件限制，现已不再支持使用 ADC2 DMA 功能获取 ADC 转换结果。使用 ADC2 连续转换的结果可能不稳定，具体可参考 `ESP32-S3 系列芯片勘误表 <https://www.espressif.com/sites/default/files/documentation/esp32-s3_errata_cn.pdf>`__。出于兼容性考虑，可以启用 :menuitem:`CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3`，强制使用 ADC2。
.. _adc-continuous-power-management:
电源管理
^^^^^^^^^^^^^^^^
启用电源管理，即启用 :ref:`CONFIG_PM_ENABLE` 时，系统在空闲状态下，可能会调整 APB 时钟频率，这可能会改变 ADC 连续转换的行为。
启用电源管理，即启用 :menuitem:`CONFIG_PM_ENABLE` 时，系统在空闲状态下，可能会调整 APB 时钟频率，这可能会改变 ADC 连续转换的行为。
然而，通过获取类型为 :cpp:enumerator:`ESP_PM_APB_FREQ_MAX` 的电源管理锁，ADC 连续转换模式驱动可以阻止这种改变。调用 :cpp:func:`adc_continuous_start` 启动连续转换后即可获取该锁。同样，调用 :cpp:func:`adc_continuous_stop` 停止转换后将释放该锁。因此，必须确保 :cpp:func:`adc_continuous_start` 和 :cpp:func:`adc_continuous_stop` 成对出现，否则电源管理将失效。
@@ -413,7 +413,7 @@ ADC 连续转换模式读取的原始数据需要进一步解析才能获得可
IRAM 安全
^^^^^^^^^
ADC 连续转换模式驱动的所有 API 均非 IRAM 安全。禁用 cache 时，不应运行这类 API。启用 Kconfig 选项 :ref:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` 可确保驱动的内部 ISR 处理程序为 IRAM 安全，此时即使禁用 cache，驱动仍然会将转换结果保存到其内部缓冲池中。
ADC 连续转换模式驱动的所有 API 均非 IRAM 安全。禁用 cache 时，不应运行这类 API。启用 Kconfig 选项 :menuitem:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` 可确保驱动的内部 ISR 处理程序为 IRAM 安全，此时即使禁用 cache，驱动仍然会将转换结果保存到其内部缓冲池中。
.. _adc-continuous-thread-safety:
docs/zh_CN/api-reference/peripherals/adc/adc_oneshot.rst
+3 -3
View File
@@ -163,7 +163,7 @@ ADC 单次转换模式驱动基于 {IDF_TARGET_NAME} SAR ADC 模块实现，不
:SOC_ADC_DMA_SUPPORTED: - 一个 ADC 单元每次只能在一种操作模式下运行，可以是连续模式或单次模式。:cpp:func:`adc_oneshot_start` 提供了保护措施。
:SOC_ADC_DIFF_SUPPORTED: - 在单端模式下，如果使用 N 端通道作为输入接口，其原始数据极性是反向的。输入电压范围为 -2 V ~ 2 V 时，N 端 raw 值为 4393~0。请使用 ADC 校准 API。
:esp32 or esp32s2 or esp32s3: - Wi-Fi 也使用 ADC2，:cpp:func:`adc_oneshot_read` 提供了 Wi-Fi 驱动与 ADC 单次转换模式驱动间的保护。
:esp32c3: - 由于硬件限制，现已不再支持使用 ADC2 DMA 功能获取 ADC 转换结果。使用 ADC2 单次转换的结果可能不稳定，具体可参考 `ESP32-C3 系列芯片勘误表 <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_cn.pdf>`__。出于兼容性考虑，可以启用 :ref:`CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3`，强制使用 ADC2。
:esp32c3: - 由于硬件限制，现已不再支持使用 ADC2 DMA 功能获取 ADC 转换结果。使用 ADC2 单次转换的结果可能不稳定，具体可参考 `ESP32-C3 系列芯片勘误表 <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_cn.pdf>`__。出于兼容性考虑，可以启用 :menuitem:`CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3`，强制使用 ADC2。
:esp32: - ESP32-DevKitC：GPIO0 已用于自动烧录功能，不能用于 ADC 单次转换模式。
:esp32: - ESP-WROVER-KIT：GPIO0、GPIO2、GPIO4 和 GPIO15 已有其他用途，不能用于 ADC 单次转换模式。
@@ -172,7 +172,7 @@ ADC 单次转换模式驱动基于 {IDF_TARGET_NAME} SAR ADC 模块实现，不
电源管理
^^^^^^^^
启用电源管理，即启用 :ref:`CONFIG_PM_ENABLE` 时，系统在空闲状态下可能会调整系统时钟频率。然而，ADC 单次转换模式驱动以轮询例程运行，:cpp:func:`adc_oneshot_read` 会不断检查 CPU 是否完成读取，直到函数返回。在此期间，ADC 单次转换模式驱动程序所在的任务不会受阻塞。因此，在读取时时钟频率保持稳定。
启用电源管理，即启用 :menuitem:`CONFIG_PM_ENABLE` 时，系统在空闲状态下可能会调整系统时钟频率。然而，ADC 单次转换模式驱动以轮询例程运行，:cpp:func:`adc_oneshot_read` 会不断检查 CPU 是否完成读取，直到函数返回。在此期间，ADC 单次转换模式驱动程序所在的任务不会受阻塞。因此，在读取时时钟频率保持稳定。
.. _adc-oneshot-iram-safe:
@@ -201,7 +201,7 @@ flash 写入/擦除、OTA 等原因都可能导致 cache 禁用，此时，默
Kconfig 选项
^^^^^^^^^^^^
- :ref:`CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM` 决定了放置 ADC 快速读取函数的位置，即 IRAM 或 flash 中，详情请参阅 :ref:`adc-oneshot-iram-safe`。
- :menuitem:`CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM` 决定了放置 ADC 快速读取函数的位置，即 IRAM 或 flash 中，详情请参阅 :ref:`adc-oneshot-iram-safe`。
应用示例
docs/zh_CN/api-reference/peripherals/ana_cmpr.rst
+7 -7
View File
@@ -240,7 +240,7 @@
.. note::
如果启用了 :ref:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`，请确保回调函数和所访问的数据都位于内部 RAM。
如果启用了 :menuitem:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`，请确保回调函数和所访问的数据都位于内部 RAM。
场景二：使用外部参考信号比较两个模拟量
========================================
@@ -535,16 +535,16 @@
电源管理
--------
当启用 :ref:`CONFIG_PM_ENABLE` 后，睡眠和时钟切换可能会影响比较器行为。驱动会在需要时自动持有电源管理锁，因此使能比较器后，系统可能会被阻止进入 light sleep。
当启用 :menuitem:`CONFIG_PM_ENABLE` 后，睡眠和时钟切换可能会影响比较器行为。驱动会在需要时自动持有电源管理锁，因此使能比较器后，系统可能会被阻止进入 light sleep。
如果你的应用比较关注功耗，建议只在确实需要时才使能比较器。
IRAM 安全
---------
如果你希望在 cache 被禁用时，比较器中断仍能正常工作，请启用 :ref:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`。
如果你希望在 cache 被禁用时，比较器中断仍能正常工作，请启用 :menuitem:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`。
如果还希望相关控制函数在这种情况下也可调用，请启用 :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM`。
如果还希望相关控制函数在这种情况下也可调用，请启用 :menuitem:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM`。
以下控制 API 可以放入 IRAM：
@@ -569,11 +569,11 @@ Kconfig 选项
最常用的 Kconfig 选项有：
- :ref:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`
- :menuitem:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`
让默认 ISR 路径在 cache 关闭时仍可工作。如果你的比较器中断需要覆盖 cache-off 场景，应启用此项。
- :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM`
- :menuitem:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM`
将可在 ISR 中调用的运行期控制 API 放入 IRAM，保证这些 API 在 cache 关闭时仍可调用。
- :ref:`CONFIG_ANA_CMPR_ENABLE_DEBUG_LOG`
- :menuitem:`CONFIG_ANA_CMPR_ENABLE_DEBUG_LOG`
打开驱动调试日志，便于联调与问题定位。启用后会增加固件体积和日志输出量。
示例
docs/zh_CN/api-reference/peripherals/camera_driver.rst
+4 -4
View File
@@ -327,8 +327,8 @@ Kconfig 选项
.. list::
:SOC_MIPI_CSI_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE`，详情请参阅 :ref:`cam-thread-safety`。
:SOC_ISP_DVP_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE`，详情请参阅 :ref:`cam-thread-safety`。
:SOC_MIPI_CSI_SUPPORTED: - :menuitem:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE`，详情请参阅 :ref:`cam-thread-safety`。
:SOC_ISP_DVP_SUPPORTED: - :menuitem:`CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE`，详情请参阅 :ref:`cam-thread-safety`。
.. _cam-iram-safe:
@@ -341,8 +341,8 @@ IRAM 安全
.. list::
:SOC_MIPI_CSI_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE`
:SOC_ISP_DVP_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE`
:SOC_MIPI_CSI_SUPPORTED: - :menuitem:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE`
:SOC_ISP_DVP_SUPPORTED: - :menuitem:`CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE`
- 即使 cache 被禁用也能启用中断服务
- 将 ISR 使用的所有函数放入 IRAM
docs/zh_CN/api-reference/peripherals/cordic.rst
+1 -1
View File
@@ -299,7 +299,7 @@ Kconfig 选项
以下 Kconfig 选项可用于配置 CORDIC 驱动：
- :ref:`CONFIG_CORDIC_ONESHOT_CTRL_FUNC_IN_IRAM` - 计算函数放入 IRAM。
- :menuitem:`CONFIG_CORDIC_ONESHOT_CTRL_FUNC_IN_IRAM` - 计算函数放入 IRAM。
API 参考
============
docs/zh_CN/api-reference/peripherals/dac.rst
+6 -6
View File
@@ -83,7 +83,7 @@ DAC 通道可以通过 DMA 连续转换数字信号，这种模式下有三种
.. only:: esp32
在 ESP32 上，DAC 的数字控制器可以在内部连接到 I2S0，并借用其 DMA 进行连续转换。虽然 DAC 转换仅需 8 位数据，但它必须是左移的 8 位（即 16 位中的高 8 位），以满足 I2S 通信格式。默认状态下驱动程序将自动扩充数据至 16 位，如需手动扩充，请在 menuconfig 中禁用 :ref:`CONFIG_DAC_DMA_AUTO_16BIT_ALIGN`。
在 ESP32 上，DAC 的数字控制器可以在内部连接到 I2S0，并借用其 DMA 进行连续转换。虽然 DAC 转换仅需 8 位数据，但它必须是左移的 8 位（即 16 位中的高 8 位），以满足 I2S 通信格式。默认状态下驱动程序将自动扩充数据至 16 位，如需手动扩充，请在 menuconfig 中禁用 :menuitem:`CONFIG_DAC_DMA_AUTO_16BIT_ALIGN`。
DAC 的数字控制器的时钟也来自 I2S0，有以下两种时钟源可选：
@@ -110,7 +110,7 @@ DAC 外设中包含一个余弦波发生器，可以在通道上产生余弦波
电源管理
^^^^^^^^
启用电源管理时（即开启 :ref:`CONFIG_PM_ENABLE`），系统会在进入 Light-sleep 模式前调整或停止 DAC 时钟源，这可能会影响 DAC 信号，从而导致数据无法正确转换。
启用电源管理时（即开启 :menuitem:`CONFIG_PM_ENABLE`），系统会在进入 Light-sleep 模式前调整或停止 DAC 时钟源，这可能会影响 DAC 信号，从而导致数据无法正确转换。
在连续模式下使用 DAC 驱动时，可以通过获取电源管理锁来防止系统在 DMA 或余弦波模式下改变或停止时钟源。时钟源为 APB 时，锁的类型将被设置为 :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_APB_FREQ_MAX`。时钟源为 APLL 时（仅在 DMA 模式下），锁的类型将被设置为 :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_NO_LIGHT_SLEEP`。在进行 DAC 转换时（即 DMA 或余弦波发生器运行时），驱动程序会保证在调用 :cpp:func:`dac_continuous_enable` 后获取电源管理锁。同样地，在调用 :cpp:func:`dac_continuous_disable` 时，驱动程序会释放锁。
@@ -119,7 +119,7 @@ IRAM 安全
默认情况下，由于写入或擦除 flash 等原因导致 cache 被禁用时，DAC 的 DMA 中断将产生延迟，无法及时执行 DMA EOF 中断。
在实时应用中，可通过启用 Kconfig 选项 :ref:`CONFIG_DAC_ISR_IRAM_SAFE` 来避免此种情况发生，启用后：
在实时应用中，可通过启用 Kconfig 选项 :menuitem:`CONFIG_DAC_ISR_IRAM_SAFE` 来避免此种情况发生，启用后：
1. 即使在 cache 被禁用的情况下，也可以启用中断服务。
@@ -137,12 +137,12 @@ IRAM 安全
Kconfig 选项
^^^^^^^^^^^^^
- :ref:`CONFIG_DAC_ISR_IRAM_SAFE` 控制默认 ISR 处理程序在 cache 被禁用时能否继续运行。更多信息可参考 :ref:`dac-iram-safe`。
- :ref:`CONFIG_DAC_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用该选项将增加固件的二进制文件大小。
- :menuitem:`CONFIG_DAC_ISR_IRAM_SAFE` 控制默认 ISR 处理程序在 cache 被禁用时能否继续运行。更多信息可参考 :ref:`dac-iram-safe`。
- :menuitem:`CONFIG_DAC_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用该选项将增加固件的二进制文件大小。
.. only:: esp32
- :ref:`CONFIG_DAC_DMA_AUTO_16BIT_ALIGN` 会在驱动中自动将 8 位数据扩展为 16 位数据，以满足 I2S DMA 格式。
- :menuitem:`CONFIG_DAC_DMA_AUTO_16BIT_ALIGN` 会在驱动中自动将 8 位数据扩展为 16 位数据，以满足 I2S DMA 格式。
应用示例
--------
docs/zh_CN/api-reference/peripherals/ds.rst
+1 -1
View File
@@ -51,7 +51,7 @@ API 函数 :cpp:func:`esp_ds_sign` 和 :cpp:func:`esp_ds_start_sign` 在 RSA_DS
**PSA 密码学驱动程序**
RSA_DS 外设也通过 **PSA Crypto RSA_DS 驱动程序** 对外提供访问接口，因此可以使用标准 PSA API 执行签名（PKCS#1 v1.5 或 PSS）和 RSA 解密（PKCS#1 v1.5 或 OAEP）。在 ``Component config`` > ``mbedTLS`` 中启用 ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``。要在 ESP-TLS 中配合使用 RSA_DS 外设（例如 TLS 客户端认证），请参阅 ESP-TLS 文档中的 :ref:`digital-signature-with-esp-tls`。
RSA_DS 外设也通过 **PSA Crypto RSA_DS 驱动程序** 对外提供访问接口，因此可以使用标准 PSA API 执行签名（PKCS#1 v1.5 或 PSS）和 RSA 解密（PKCS#1 v1.5 或 OAEP）。启用 :menuitem:`CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL`。要在 ESP-TLS 中配合使用 RSA_DS 外设（例如 TLS 客户端认证），请参阅 ESP-TLS 文档中的 :ref:`digital-signature-with-esp-tls`。
.. _configure-the-ds-peripheral:
docs/zh_CN/api-reference/peripherals/ecdsa.rst
+1 -1
View File
@@ -122,7 +122,7 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编
{IDF_TARGET_NAME} 的 ECDSA_DS 外设支持 ECDSA-P192 和 ECDSA-P256 两种曲线操作，但默认仅启用 ECDSA-P256 操作。可以通过以下配置项启用 ECDSA-P192 操作：
- :ref:`CONFIG_ESP_ECDSA_ENABLE_P192_CURVE` 启用对 ECDSA-P192 曲线操作的支持，使设备可以同时执行 192 位和 256 位的 ECDSA 曲线操作。但请注意，如果 eFuse 写保护期间已永久禁用 ECDSA-P192 操作，则启用该配置项也无法重新启用该功能。
- :menuitem:`CONFIG_ESP_ECDSA_ENABLE_P192_CURVE` 启用对 ECDSA-P192 曲线操作的支持，使设备可以同时执行 192 位和 256 位的 ECDSA 曲线操作。但请注意，如果 eFuse 写保护期间已永久禁用 ECDSA-P192 操作，则启用该配置项也无法重新启用该功能。
- :cpp:func:`esp_efuse_enable_ecdsa_p192_curve_mode()` 可用于以编程方式启用 ECDSA-P192 曲线操作。它会向 eFuse 写入相应值，从而使设备支持 P-192 和 P-256 曲线操作。但请注意，若对应的 eFuse 区域已被写保护，则此 API 将调用失败。
docs/zh_CN/api-reference/peripherals/etm.rst
+2 -2
View File
@@ -139,7 +139,7 @@ ETM 通道分析
电源管理
^^^^^^^^
当启用电源管理时，即 :ref:`CONFIG_PM_ENABLE` 打开的时候，系统可能会调整或禁用时钟源，并在进入睡眠前关闭 ETM 外设依赖的电源。这会导致事件和任务之间的连接信息被丢失，ETM 通道在唤醒后无法正常工作。因此，默认情况下，驱动程序会获取电源管理锁，以禁止系统关闭 ETM 外设。
当启用电源管理时，即 :menuitem:`CONFIG_PM_ENABLE` 打开的时候，系统可能会调整或禁用时钟源，并在进入睡眠前关闭 ETM 外设依赖的电源。这会导致事件和任务之间的连接信息被丢失，ETM 通道在唤醒后无法正常工作。因此，默认情况下，驱动程序会获取电源管理锁，以禁止系统关闭 ETM 外设。
.. only:: SOC_ETM_SUPPORT_SLEEP_RETENTION
@@ -161,7 +161,7 @@ ETM 核心驱动程序具备线程安全性。
Kconfig 选项
^^^^^^^^^^^^^^^
- :ref:`CONFIG_ETM_ENABLE_DEBUG_LOG` 用于启用调试日志输出，启用此选项将增加固件的二进制文件大小。
- :menuitem:`CONFIG_ETM_ENABLE_DEBUG_LOG` 用于启用调试日志输出，启用此选项将增加固件的二进制文件大小。
API 参考
-------------
docs/zh_CN/api-reference/peripherals/gptimer.rst
+8 -8
View File
@@ -311,7 +311,7 @@ GPTimer 驱动支持在中断回调函数中调用 :cpp:func:`gptimer_set_alarm_
关于低功耗
----------
当启用电源管理 :ref:`CONFIG_PM_ENABLE` 时，系统在进入睡眠模式前可能会调整或禁用时钟源，从而导致 GPTimer 的计时出错。
当启用电源管理 :menuitem:`CONFIG_PM_ENABLE` 时，系统在进入睡眠模式前可能会调整或禁用时钟源，从而导致 GPTimer 的计时出错。
为了防止这种情况发生， GPTimer 驱动内部创建了一个电源管理锁。当调用 :cpp:func:`gptimer_enable` 函数后，该锁将被激活，确保系统不会进入睡眠模式，从而保持定时器的正确工作。如果需要降低功耗，可以调用 :cpp:func:`gptimer_disable` 函数来释放电源管理锁，使系统能够进入睡眠模式。但是，这样做会导致定时器停止计数，因此在唤醒后需要重新启动定时器。
@@ -338,7 +338,7 @@ GPTimer 驱动支持在中断回调函数中调用 :cpp:func:`gptimer_set_alarm_
关于 Cache 安全
---------------
在文件系统进行 Flash 读写操作时，为了避免 Cache 从 Flash 加载指令和数据时出现错误，系统会暂时禁用 Cache 功能。这会导致 GPTimer 的中断处理程序在此期间无法响应，从而使用户的回调函数无法及时执行。如果希望在 Cache 被禁用期间，中断处理程序仍能正常运行，可以启用 :ref:`CONFIG_GPTIMER_ISR_CACHE_SAFE` 选项。
在文件系统进行 Flash 读写操作时，为了避免 Cache 从 Flash 加载指令和数据时出现错误，系统会暂时禁用 Cache 功能。这会导致 GPTimer 的中断处理程序在此期间无法响应，从而使用户的回调函数无法及时执行。如果希望在 Cache 被禁用期间，中断处理程序仍能正常运行，可以启用 :menuitem:`CONFIG_GPTIMER_ISR_CACHE_SAFE` 选项。
.. note::
@@ -347,18 +347,18 @@ GPTimer 驱动支持在中断回调函数中调用 :cpp:func:`gptimer_set_alarm_
关于性能
--------
为了提升中断处理的实时响应能力， GPTimer 驱动提供了 :ref:`CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM` 选项。启用该选项后，中断处理程序将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令时可能出现的缓存丢失带来的延迟。
为了提升中断处理的实时响应能力， GPTimer 驱动提供了 :menuitem:`CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM` 选项。启用该选项后，中断处理程序将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令时可能出现的缓存丢失带来的延迟。
.. note::
但是，中断处理程序调用的用户回调函数和用户上下文数据仍然可能位于 Flash 中，缓存缺失的问题还是会存在，这需要用户自己将回调函数和数据放入内部 RAM 中，比如使用 :c:macro:`IRAM_ATTR` 和 :c:macro:`DRAM_ATTR`。
前文还提到， GPTimer 驱动允许部分函数在中断上下文中使用。:ref:`CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` 选项可以将这些函数放入 IRAM 中，一来，可以避免缓存缺失带来的性能损失，二来，这些函数在 Cache 关闭期间也能使用。
前文还提到， GPTimer 驱动允许部分函数在中断上下文中使用。:menuitem:`CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` 选项可以将这些函数放入 IRAM 中，一来，可以避免缓存缺失带来的性能损失，二来，这些函数在 Cache 关闭期间也能使用。
其他 Kconfig 选项
-----------------
- :ref:`CONFIG_GPTIMER_ENABLE_DEBUG_LOG` 选项允许强制启用 GPTimer 驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题。
- :menuitem:`CONFIG_GPTIMER_ENABLE_DEBUG_LOG` 选项允许强制启用 GPTimer 驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题。
关于资源消耗
------------
@@ -368,9 +368,9 @@ GPTimer 驱动支持在中断回调函数中调用 :cpp:func:`gptimer_set_alarm_
- 编译器优化等级设置为 ``-Os``，以确保代码尺寸最小化。
- 默认日志等级设置为 ``ESP_LOG_INFO``，以平衡调试信息和性能。
- 关闭以下驱动优化选项：
- :ref:`CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM` - 中断处理程序不放入 IRAM。
- :ref:`CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` - 控制函数不放入 IRAM。
- :ref:`CONFIG_GPTIMER_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
- :menuitem:`CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM` - 中断处理程序不放入 IRAM。
- :menuitem:`CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` - 控制函数不放入 IRAM。
- :menuitem:`CONFIG_GPTIMER_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
**注意，以下数据不是精确值，仅供参考，在不同型号的芯片上，数据会有所出入。**
docs/zh_CN/api-reference/peripherals/i2c.rst
+4 -4
View File
@@ -625,7 +625,7 @@ I2C 从机事件回调函数列表见 :cpp:type:`i2c_slave_event_callbacks_t`。
.. only:: SOC_I2C_SUPPORT_APB
启用电源管理（即打开 :ref:`CONFIG_PM_ENABLE`），系统会在进入 Light-sleep 模式前调整或暂停 I2C FIFO 的时钟源，这可能会导致 I2C 信号改变，传输或接收到无效数据。
启用电源管理（即打开 :menuitem:`CONFIG_PM_ENABLE`），系统会在进入 Light-sleep 模式前调整或暂停 I2C FIFO 的时钟源，这可能会导致 I2C 信号改变，传输或接收到无效数据。
但驱动程序可以通过获取 :cpp:enumerator:`ESP_PM_APB_FREQ_MAX` 类型的电源管理锁来防止系统改变 APB 频率。每当用户创建一个以 :cpp:enumerator:`I2C_CLK_SRC_APB` 为时钟源的 I2C 总线，驱动程序将在开始 I2C 操作时获取电源管理锁，并在结束 I2C 操作时自动释放锁。
@@ -644,7 +644,7 @@ IRAM 安全
默认情况下，若 cache 因写入或擦除 flash 等原因而被禁用时，将推迟 I2C 中断。此时事件回调函数将无法按时执行，会影响实时应用的系统响应。
Kconfig 选项 :ref:`CONFIG_I2C_ISR_IRAM_SAFE` 能够做到以下几点：
Kconfig 选项 :menuitem:`CONFIG_I2C_ISR_IRAM_SAFE` 能够做到以下几点：
1. 即使 cache 被禁用，I2C 中断依旧正常运行。
2. 将 ISR 使用的所有函数放入 IRAM 中。
@@ -678,8 +678,8 @@ I2C 从机操作函数也通过总线操作信号保证线程安全。
Kconfig 选项
^^^^^^^^^^^^
- :ref:`CONFIG_I2C_ISR_IRAM_SAFE` 将在 cache 被禁用时控制默认的 ISR 处理程序正常工作，详情请参阅 :ref:`i2c-iram-safe`。
- :ref:`CONFIG_I2C_ENABLE_DEBUG_LOG` 可启用调试日志，但会增加固件二进制文件大小。
- :menuitem:`CONFIG_I2C_ISR_IRAM_SAFE` 将在 cache 被禁用时控制默认的 ISR 处理程序正常工作，详情请参阅 :ref:`i2c-iram-safe`。
- :menuitem:`CONFIG_I2C_ENABLE_DEBUG_LOG` 可启用调试日志，但会增加固件二进制文件大小。
应用示例
--------
docs/zh_CN/api-reference/peripherals/i2s.rst
+4 -4
View File
@@ -258,7 +258,7 @@ I2S 驱动中的资源可分为三个级别：
电源管理
^^^^^^^^
电源管理启用（即开启 :ref:`CONFIG_PM_ENABLE`）时，系统将在进入 Light-sleep 前调整或停止 I2S 时钟源，这可能会影响 I2S 信号，从而导致传输或接收的数据无效。
电源管理启用（即开启 :menuitem:`CONFIG_PM_ENABLE`）时，系统将在进入 Light-sleep 前调整或停止 I2S 时钟源，这可能会影响 I2S 信号，从而导致传输或接收的数据无效。
I2S 驱动可以获取电源管理锁，从而防止系统设置更改或时钟源被禁用。时钟源为 APB 时，锁的类型将被设置为 :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_APB_FREQ_MAX`。时钟源为 APLL（若支持）时，锁的类型将被设置为 :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_NO_LIGHT_SLEEP`。驱动程序将在调用 :cpp:func:`i2s_channel_enable` 启用通道时获取电源管理锁，并在调用 :cpp:func:`i2s_channel_disable` 禁用通道时释放锁，确保通道运行期间 I2S 时钟源保持稳定。
@@ -416,7 +416,7 @@ IRAM 安全
默认情况下，由于写入或擦除 flash 等原因导致 cache 被禁用时，I2S 中断将产生延迟，无法及时执行 EOF 中断。
在实时应用中，可通过启用 Kconfig 选项 :ref:`CONFIG_I2S_ISR_IRAM_SAFE` 来避免此种情况发生，启用后：
在实时应用中，可通过启用 Kconfig 选项 :menuitem:`CONFIG_I2S_ISR_IRAM_SAFE` 来避免此种情况发生，启用后：
1. 即使在 cache 被禁用的情况下，中断仍可继续运行。
@@ -432,8 +432,8 @@ IRAM 安全
Kconfig 选项
^^^^^^^^^^^^
- :ref:`CONFIG_I2S_ISR_IRAM_SAFE` 控制默认 ISR 处理程序能否在禁用 cache 的情况下工作。更多信息可参考 :ref:`i2s-iram-safe`。
- :ref:`CONFIG_I2S_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用该选项将增加固件的二进制文件大小。
- :menuitem:`CONFIG_I2S_ISR_IRAM_SAFE` 控制默认 ISR 处理程序能否在禁用 cache 的情况下工作。更多信息可参考 :ref:`i2s-iram-safe`。
- :menuitem:`CONFIG_I2S_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用该选项将增加固件的二进制文件大小。
应用实例
--------
docs/zh_CN/api-reference/peripherals/i3c_master.rst
+6 -6
View File
@@ -538,7 +538,7 @@ Cache 安全
关于低功耗
------------
当启用电源管理 :ref:`CONFIG_PM_ENABLE` 时，系统在进入睡眠模式前可能会调整或禁用时钟源，从而导致 I3C 传输出错。
当启用电源管理 :menuitem:`CONFIG_PM_ENABLE` 时，系统在进入睡眠模式前可能会调整或禁用时钟源，从而导致 I3C 传输出错。
为了防止这种情况发生， I3C 驱动内部创建了一个电源管理锁。当调用传输函数后，该锁将被激活，确保系统不会进入睡眠模式，从而保持定时器的正确工作，直至传输完成后，驱动自动释放该锁。使系统能够进入睡眠模式。
@@ -547,9 +547,9 @@ Kconfig 选项
以下 Kconfig 选项可用于配置 I3C 驱动程序：
- :ref:`CONFIG_I3C_MASTER_ISR_CACHE_SAFE`：确保 I3C 中断在缓存被禁用时也能正常工作（例如 SPI Flash 写入时）
- :ref:`CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM`：将 I3C 主机 ISR 处理程序放入 IRAM 以提高性能并减少缓存未命中
- :ref:`CONFIG_I3C_MASTER_ENABLE_DEBUG_LOG`：启用 I3C 调试日志
- :menuitem:`CONFIG_I3C_MASTER_ISR_CACHE_SAFE`：确保 I3C 中断在缓存被禁用时也能正常工作（例如 SPI Flash 写入时）
- :menuitem:`CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM`：将 I3C 主机 ISR 处理程序放入 IRAM 以提高性能并减少缓存未命中
- :menuitem:`CONFIG_I3C_MASTER_ENABLE_DEBUG_LOG`：启用 I3C 调试日志
关于资源消耗
------------
@@ -559,8 +559,8 @@ Kconfig 选项
- 编译器优化等级设置为 ``-Os``，以确保代码尺寸最小化。
- 默认日志等级设置为 ``ESP_LOG_INFO``，以平衡调试信息和性能。
- 关闭以下驱动优化选项：
- :ref:`CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM` - 中断处理程序不放入 IRAM。
- :ref:`CONFIG_I3C_MASTER_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
- :menuitem:`CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM` - 中断处理程序不放入 IRAM。
- :menuitem:`CONFIG_I3C_MASTER_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
**注意，以下数据不是精确值，仅供参考，在不同型号的芯片上，数据会有所出入。**
docs/zh_CN/api-reference/peripherals/isp.rst
+3 -3
View File
@@ -1117,7 +1117,7 @@ ISP HIST 控制器完成亮度统计后，将动态生成特定事件。若想
Kconfig 选项
^^^^^^^^^^^^
- :ref:`CONFIG_ISP_ISR_IRAM_SAFE` 控制默认的 ISR 句柄在 cache 被禁用时是否可以正常工作。
- :menuitem:`CONFIG_ISP_ISR_IRAM_SAFE` 控制默认的 ISR 句柄在 cache 被禁用时是否可以正常工作。
.. _isp-iram-safe:
@@ -1126,7 +1126,7 @@ IRAM 安全
默认情况下，当 cache 因写入或擦除 flash 等原因而被禁用时，ISP 的中断将会延迟。
Kconfig 选项 :ref:`CONFIG_ISP_ISR_IRAM_SAFE` 支持：
Kconfig 选项 :menuitem:`CONFIG_ISP_ISR_IRAM_SAFE` 支持：
- 即使 cache 被禁用也能启用中断
- 将 ISR 使用的所有函数放入 IRAM
@@ -1134,7 +1134,7 @@ Kconfig 选项 :ref:`CONFIG_ISP_ISR_IRAM_SAFE` 支持：
启用上述 Kconfig 选项，保证 cache 被禁用时中断可以正常运行，但这会增加 IRAM 使用量。启用此选项后，当 cache 被禁用时，ISR 回调函数将继续运行。因此，必须确保回调函数及其上下文也是 IRAM 安全的。
Kconfig 选项 :ref:`CONFIG_ISP_CTRL_FUNC_IN_IRAM` 支持：
Kconfig 选项 :menuitem:`CONFIG_ISP_CTRL_FUNC_IN_IRAM` 支持：
- 将一些 ISP 控制函数放入 IRAM，函数列表请参见：
docs/zh_CN/api-reference/peripherals/jpeg.rst
+2 -2
View File
@@ -565,7 +565,7 @@ YUV420
电源管理
^^^^^^^^
当启用电源管理（即设置了 :ref:`CONFIG_PM_ENABLE`）时，系统需要调整或停止 JPEG 的源时钟以进入 Light-sleep 模式，这可能会改变 JPEG 解码器/编码器的处理过程，也可能会导致硬件计算出现意外。为防止以上问题出现，当 JPEG 编码器/解码器工作时，无法进入 Light-sleep 模式。
当启用电源管理（即设置了 :menuitem:`CONFIG_PM_ENABLE`）时，系统需要调整或停止 JPEG 的源时钟以进入 Light-sleep 模式，这可能会改变 JPEG 解码器/编码器的处理过程，也可能会导致硬件计算出现意外。为防止以上问题出现，当 JPEG 编码器/解码器工作时，无法进入 Light-sleep 模式。
每当用户通过 JPEG 进行解码或编码（即调用 :cpp:func:`jpeg_encoder_process` 或 :cpp:func:`jpeg_decoder_process`）时，驱动程序会将电源管理设定为 :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_CPU_FREQ_MAX`，确保获取电源管理锁。一旦编码或解码完成，驱动程序将释放锁，则系统可以进入 Light-sleep 模式。
@@ -591,7 +591,7 @@ JPEG 编解码器通过 2D-DMA 搬运数据，而 JPEG 编解码器 **无法处
Kconfig 选项
^^^^^^^^^^^^
- :ref:`CONFIG_JPEG_ENABLE_DEBUG_LOG` 可启用调试日志，但会增加固件二进制大小。
- :menuitem:`CONFIG_JPEG_ENABLE_DEBUG_LOG` 可启用调试日志，但会增加固件二进制大小。
维护者须知
docs/zh_CN/api-reference/peripherals/lcd/rgb_lcd.rst
+2 -2
View File
@@ -256,7 +256,7 @@ bounce buffer 与 PSRAM frame buffer
.. note::
强烈建议在此模式下启用 Kconfig 选项：:ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`，开启“PSRAM XIP（就地执行）”功能，使 CPU 能从 PSRAM 里而不是主 flash 中提取指令和只读数据。此外，即使想通过 SPI 1 写入主 flash，外部存储器 cache 也不会被禁用，应用程序便能正常显示 OTA 进度条。
强烈建议在此模式下启用 Kconfig 选项：:menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM`，开启“PSRAM XIP（就地执行）”功能，使 CPU 能从 PSRAM 里而不是主 flash 中提取指令和只读数据。此外，即使想通过 SPI 1 写入主 flash，外部存储器 cache 也不会被禁用，应用程序便能正常显示 OTA 进度条。
.. note::
@@ -310,7 +310,7 @@ bounce buffer 与 PSRAM frame buffer
.. note::
虽说在设计良好的嵌入式应用程序中, DMA 传递数据的速度不应该赶不上 LCD 读取数据的速度。但理论上，此种情况还是有可能出现的。在 {IDF_TARGET_NAME} 的硬件中，这种情况会导致 LCD 在 DMA 等待数据时单纯输出 dummy 字节。若以流式传输运行 DMA，则 DMA 会将读取到的数据传输到某个 LCD 地址，同时 LCD 也会将数据输出到某个 LCD 地址，但上述两个地址可能会不同步，导致图像 **永久** 偏移。
为防止类似情况发生，可以启用 :ref:`CONFIG_LCD_RGB_RESTART_IN_VSYNC` 选项，以便驱动程序在 VBlank 中断时自动重启 DMA；或者也可以调用 :cpp:func:`esp_lcd_rgb_panel_restart`，手动重启 DMA。请注意，调用 :cpp:func:`esp_lcd_rgb_panel_restart` 不会立即重启 DMA，DMA 只会在下一个 VSYNC 事件中重启。
为防止类似情况发生，可以启用 :menuitem:`CONFIG_LCD_RGB_RESTART_IN_VSYNC` 选项，以便驱动程序在 VBlank 中断时自动重启 DMA；或者也可以调用 :cpp:func:`esp_lcd_rgb_panel_restart`，手动重启 DMA。请注意，调用 :cpp:func:`esp_lcd_rgb_panel_restart` 不会立即重启 DMA，DMA 只会在下一个 VSYNC 事件中重启。
API 参考
--------
docs/zh_CN/api-reference/peripherals/mcpwm.rst
+6 -6
View File
@@ -983,7 +983,7 @@ MCPWM 捕获通道支持在信号上检测到有效边沿时发送通知。须
电源管理
^^^^^^^^^^^^^^^^
启用电源管理（即开启 :ref:`CONFIG_PM_ENABLE`）时，系统会在进入 Light-sleep 前调整 PLL 和 APB 频率。该操作有可能会改变 MCPWM 定时器的计数步长，导致计时偏差。
启用电源管理（即开启 :menuitem:`CONFIG_PM_ENABLE`）时，系统会在进入 Light-sleep 前调整 PLL 和 APB 频率。该操作有可能会改变 MCPWM 定时器的计数步长，导致计时偏差。
不过，驱动程序可以获取 :cpp:enumerator:`ESP_PM_NO_LIGHT_SLEEP` 类型的电源管理锁，防止系统进入 Light-sleep。每当驱动创建以 PLL 作为时钟源的 MCPWM 定时器实例时，都会在通过 :cpp:func:`mcpwm_timer_enable` 启用定时器时获取电源管理锁。反之，调用 :cpp:func:`mcpwm_timer_disable` 时，驱动程序释放锁。
@@ -1014,7 +1014,7 @@ IRAM 安全
默认情况下，禁用 cache 时，写入/擦除 flash 等原因将导致 MCPWM 中断延迟，事件回调函数也将延迟执行。在实时应用程序中，应避免此类情况。
因此，可以启用 Kconfig 选项 :ref:`CONFIG_MCPWM_ISR_CACHE_SAFE`，该选项：
因此，可以启用 Kconfig 选项 :menuitem:`CONFIG_MCPWM_ISR_CACHE_SAFE`，该选项：
* 支持在禁用 cache 时启用所需中断
* 支持将 ISR 使用的所有函数存放在 IRAM 中 [2]_
@@ -1022,7 +1022,7 @@ IRAM 安全
启用该选项可以保证 cache 禁用时的中断运行，但会相应增加 IRAM 占用。
另一个 Kconfig 选项 :ref:`CONFIG_MCPWM_CTRL_FUNC_IN_IRAM` 也支持将常用的 IO 控制函数存放在 IRAM 中，以保证在禁用 cache 时可以正常使用函数。IO 控制函数如下所示：
另一个 Kconfig 选项 :menuitem:`CONFIG_MCPWM_CTRL_FUNC_IN_IRAM` 也支持将常用的 IO 控制函数存放在 IRAM 中，以保证在禁用 cache 时可以正常使用函数。IO 控制函数如下所示：
- :cpp:func:`mcpwm_comparator_set_compare_value`
- :cpp:func:`mcpwm_timer_set_period`
@@ -1048,9 +1048,9 @@ IRAM 安全
Kconfig 选项
^^^^^^^^^^^^^^^
- :ref:`CONFIG_MCPWM_ISR_CACHE_SAFE` 控制默认 ISR 处理程序能否在禁用 cache 的情况下工作。更多信息请参见 :ref:`mcpwm-iram-safe`。
- :ref:`CONFIG_MCPWM_CTRL_FUNC_IN_IRAM` 控制 MCPWM 控制函数的存放位置（IRAM 或 flash）。更多信息请参见 :ref:`mcpwm-iram-safe`。
- :ref:`CONFIG_MCPWM_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用此选项将增加固件的二进制文件大小。
- :menuitem:`CONFIG_MCPWM_ISR_CACHE_SAFE` 控制默认 ISR 处理程序能否在禁用 cache 的情况下工作。更多信息请参见 :ref:`mcpwm-iram-safe`。
- :menuitem:`CONFIG_MCPWM_CTRL_FUNC_IN_IRAM` 控制 MCPWM 控制函数的存放位置（IRAM 或 flash）。更多信息请参见 :ref:`mcpwm-iram-safe`。
- :menuitem:`CONFIG_MCPWM_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用此选项将增加固件的二进制文件大小。
应用示例
--------------------
docs/zh_CN/api-reference/peripherals/parlio/parlio_rx.rst
+9 -9
View File
@@ -336,7 +336,7 @@ ISR 上下文接收
电源管理
^^^^^^^^
当电源管理 :ref:`CONFIG_PM_ENABLE` 被启用的时候，系统在进入睡眠前可能会调整或禁用时钟源，会导致 RX 单元内部的时间基准无法按预期工作。
当电源管理 :menuitem:`CONFIG_PM_ENABLE` 被启用的时候，系统在进入睡眠前可能会调整或禁用时钟源，会导致 RX 单元内部的时间基准无法按预期工作。
为了防止这种情况发生，RX 单元驱动内部创建了一个电源管理锁。锁的类型会根据不同的时钟源来设置。驱动程序将在 :cpp:func:`parlio_rx_unit_enable` 中拿锁，并在 :cpp:func:`parlio_rx_unit_disable` 中释放锁。这意味着，无论电源管理策略如何，在这两个函数之间系统不会进入睡眠模式，时钟源也不会被禁用或调整频率，任何 RX 事务都可以保证正常工作。
@@ -352,7 +352,7 @@ ISR 上下文接收
关于 Cache 安全
^^^^^^^^^^^^^^^
在文件系统进行 Flash 读写操作时，为了避免 Cache 从 Flash 加载指令和数据时出现错误，系统会暂时禁用 Cache 功能。这会导致 RX 单元的中断处理程序在此期间无法响应，从而使用户的回调函数无法及时执行。如果希望在 Cache 被禁用期间，中断处理程序仍能正常运行，可以启用 :ref:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE` 选项。
在文件系统进行 Flash 读写操作时，为了避免 Cache 从 Flash 加载指令和数据时出现错误，系统会暂时禁用 Cache 功能。这会导致 RX 单元的中断处理程序在此期间无法响应，从而使用户的回调函数无法及时执行。如果希望在 Cache 被禁用期间，中断处理程序仍能正常运行，可以启用 :menuitem:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE` 选项。
.. note::
@@ -362,16 +362,16 @@ ISR 上下文接收
.. note::
当启用了以下选项时，系统在进行 Flash 读写操作时不会自动禁用 Cache, 因此无需启用 :ref:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE`。
当启用了以下选项时，系统在进行 Flash 读写操作时不会自动禁用 Cache, 因此无需启用 :menuitem:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE`。
.. list::
:SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
:SOC_SPIRAM_XIP_SUPPORTED: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`
:SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
:SOC_SPIRAM_XIP_SUPPORTED: - :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM`
关于性能
^^^^^^^^
为了提升中断处理的实时响应能力，RX 单元驱动提供了 :ref:`CONFIG_PARLIO_RX_ISR_HANDLER_IN_IRAM` 选项。启用该选项后，中断处理程序将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令时可能出现的缓存丢失带来的延迟。
为了提升中断处理的实时响应能力，RX 单元驱动提供了 :menuitem:`CONFIG_PARLIO_RX_ISR_HANDLER_IN_IRAM` 选项。启用该选项后，中断处理程序将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令时可能出现的缓存丢失带来的延迟。
.. note::
@@ -382,7 +382,7 @@ ISR 上下文接收
其他 Kconfig 选项
^^^^^^^^^^^^^^^^^
- :ref:`CONFIG_PARLIO_ENABLE_DEBUG_LOG` 选项允许强制启用 RX 单元驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题。此选项与 TX 单元驱动程序共用。
- :menuitem:`CONFIG_PARLIO_ENABLE_DEBUG_LOG` 选项允许强制启用 RX 单元驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题。此选项与 TX 单元驱动程序共用。
关于资源消耗
^^^^^^^^^^^^
@@ -392,8 +392,8 @@ ISR 上下文接收
- 编译器优化等级设置为 ``-Os``，以确保代码尺寸最小化。
- 默认日志等级设置为 ``ESP_LOG_INFO``，以平衡调试信息和性能。
- 关闭以下驱动优化选项：
- :ref:`CONFIG_PARLIO_RX_ISR_HANDLER_IN_IRAM` - 中断处理程序不放入 IRAM。
- :ref:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
- :menuitem:`CONFIG_PARLIO_RX_ISR_HANDLER_IN_IRAM` - 中断处理程序不放入 IRAM。
- :menuitem:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
**注意，以下数据不是精确值，仅供参考，在不同型号的芯片和不同版本的 IDF 上，数据会有所出入。**
docs/zh_CN/api-reference/peripherals/parlio/parlio_tx.rst
+9 -9
View File
@@ -332,7 +332,7 @@ TX 单元可以选择各种不同的时钟源，其中外部时钟源较为特
电源管理
^^^^^^^^^^^^^^^^
当电源管理 :ref:`CONFIG_PM_ENABLE` 被启用的时候，系统在进入睡眠前可能会调整或禁用时钟源，会导致 TX 单元内部的时间基准无法按预期工作。
当电源管理 :menuitem:`CONFIG_PM_ENABLE` 被启用的时候，系统在进入睡眠前可能会调整或禁用时钟源，会导致 TX 单元内部的时间基准无法按预期工作。
为了防止这种情况发生， TX 单元驱动内部创建了一个电源管理锁。锁的类型会根据不同的时钟源来设置。驱动程序将在 :cpp:func:`parlio_tx_unit_enable` 中拿锁，并在 :cpp:func:`parlio_tx_unit_disable` 中释放锁。这意味着，无论电源管理策略如何，在这两个函数之间系统不会进入睡眠模式，时钟源也不会被禁用或调整频率，任何 TX 事务都可以保证正常工作。
@@ -348,7 +348,7 @@ TX 单元可以选择各种不同的时钟源，其中外部时钟源较为特
关于 Cache 安全
^^^^^^^^^^^^^^^^
在文件系统进行 Flash 读写操作时，为了避免 Cache 从 Flash 加载指令和数据时出现错误，系统会暂时禁用 Cache 功能。这会导致 TX 单元的中断处理程序在此期间无法响应，从而使用户的回调函数无法及时执行。如果希望在 Cache 被禁用期间，中断处理程序仍能正常运行，可以启用 :ref:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE` 选项。
在文件系统进行 Flash 读写操作时，为了避免 Cache 从 Flash 加载指令和数据时出现错误，系统会暂时禁用 Cache 功能。这会导致 TX 单元的中断处理程序在此期间无法响应，从而使用户的回调函数无法及时执行。如果希望在 Cache 被禁用期间，中断处理程序仍能正常运行，可以启用 :menuitem:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE` 选项。
.. note::
@@ -358,16 +358,16 @@ TX 单元可以选择各种不同的时钟源，其中外部时钟源较为特
.. note::
当启用了以下选项时，系统在进行 Flash 读写操作时不会自动禁用 Cache, 因此无需启用 :ref:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE`。
当启用了以下选项时，系统在进行 Flash 读写操作时不会自动禁用 Cache, 因此无需启用 :menuitem:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE`。
.. list::
:SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
:SOC_SPIRAM_XIP_SUPPORTED: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`
:SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
:SOC_SPIRAM_XIP_SUPPORTED: - :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM`
关于性能
^^^^^^^^
为了提升中断处理的实时响应能力， TX 单元驱动提供了 :ref:`CONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM` 选项。启用该选项后，中断处理程序将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令时可能出现的缓存丢失带来的延迟。
为了提升中断处理的实时响应能力， TX 单元驱动提供了 :menuitem:`CONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM` 选项。启用该选项后，中断处理程序将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令时可能出现的缓存丢失带来的延迟。
.. note::
@@ -376,7 +376,7 @@ TX 单元可以选择各种不同的时钟源，其中外部时钟源较为特
其他 Kconfig 选项
^^^^^^^^^^^^^^^^^
- :ref:`CONFIG_PARLIO_ENABLE_DEBUG_LOG` 选项允许强制启用 TX 单元驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题。此选项与 RX 单元驱动程序共用。
- :menuitem:`CONFIG_PARLIO_ENABLE_DEBUG_LOG` 选项允许强制启用 TX 单元驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题。此选项与 RX 单元驱动程序共用。
关于资源消耗
^^^^^^^^^^^^
@@ -386,8 +386,8 @@ TX 单元可以选择各种不同的时钟源，其中外部时钟源较为特
- 编译器优化等级设置为 ``-Os``，以确保代码尺寸最小化。
- 默认日志等级设置为 ``ESP_LOG_INFO``，以平衡调试信息和性能。
- 关闭以下驱动优化选项：
- :ref:`CONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM` - 中断处理程序不放入 IRAM。
- :ref:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
- :menuitem:`CONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM` - 中断处理程序不放入 IRAM。
- :menuitem:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
**注意，以下数据不是精确值，仅供参考，在不同型号的芯片和不同版本的 IDF 上，数据会有所出入。**
docs/zh_CN/api-reference/peripherals/pcnt.rst
+6 -6
View File
@@ -346,7 +346,7 @@ PCNT 内部的硬件计数器会在计数达到高/低门限的时候自动清
电源管理
^^^^^^^^^^
当电源管理使能（即 :ref:`CONFIG_PM_ENABLE` 开启）时，系统会在进入 Light-sleep 模式之前调整 APB 的频率，这可能导致 PCNT 毛刺滤波器将有效信号误认为噪声。
当电源管理使能（即 :menuitem:`CONFIG_PM_ENABLE` 开启）时，系统会在进入 Light-sleep 模式之前调整 APB 的频率，这可能导致 PCNT 毛刺滤波器将有效信号误认为噪声。
为了防止这种情况发生，驱动程序可以获取类型为 :cpp:enumerator:`ESP_PM_APB_FREQ_MAX` 的电源管理锁，以确保 APB 频率保持不变。该锁在通过 :cpp:func:`pcnt_unit_enable` 使能 PCNT 单元时获取，并在通过 :cpp:func:`pcnt_unit_disable` 禁用单元时释放。
@@ -357,7 +357,7 @@ PCNT 内部的硬件计数器会在计数达到高/低门限的时候自动清
当缓存由于写入/擦除 flash 等原因被禁用时，PCNT 中断会默认被延迟。这会导致报警中断无法及时执行，从而无法满足实时性应用的要求。
Konfig 选项 :ref:`CONFIG_PCNT_ISR_IRAM_SAFE` 可以实现以下功能：
Konfig 选项 :menuitem:`CONFIG_PCNT_ISR_IRAM_SAFE` 可以实现以下功能：
1. 即使缓存被禁用也可以使能中断服务
2. 将 ISR 使用的所有函数都放入 IRAM 中 [2]_
@@ -365,7 +365,7 @@ Konfig 选项 :ref:`CONFIG_PCNT_ISR_IRAM_SAFE` 可以实现以下功能：
这样，在缓存被禁用时，中断也可运行，但是这也会增加 IRAM 的消耗。
另外一个 Konfig 选项 :ref:`CONFIG_PCNT_CTRL_FUNC_IN_IRAM` 也可以把常用的 IO 控制函数放在 IRAM 中。这样，当缓存禁用时，这些函数仍然可以执行。这些 IO 控制函数如下所示：
另外一个 Konfig 选项 :menuitem:`CONFIG_PCNT_CTRL_FUNC_IN_IRAM` 也可以把常用的 IO 控制函数放在 IRAM 中。这样，当缓存禁用时，这些函数仍然可以执行。这些 IO 控制函数如下所示：
- :cpp:func:`pcnt_unit_start`
- :cpp:func:`pcnt_unit_stop`
@@ -393,9 +393,9 @@ Konfig 选项 :ref:`CONFIG_PCNT_ISR_IRAM_SAFE` 可以实现以下功能：
支持的 Kconfig 选项
^^^^^^^^^^^^^^^^^^^^^^
- :ref:`CONFIG_PCNT_CTRL_FUNC_IN_IRAM` 用于确定 PCNT 控制函数的位置（放在 IRAM 还是 flash 中），请参考 :ref:`pcnt-iram-safe` 获取更多信息。
- :ref:`CONFIG_PCNT_ISR_IRAM_SAFE` 用于控制当缓存禁用时，默认的 ISR 句柄是否可以工作，请参考 :ref:`pcnt-iram-safe` 获取更多信息。
- :ref:`CONFIG_PCNT_ENABLE_DEBUG_LOG` 用于使能调试日志输出，而这会增大固件二进制文件。
- :menuitem:`CONFIG_PCNT_CTRL_FUNC_IN_IRAM` 用于确定 PCNT 控制函数的位置（放在 IRAM 还是 flash 中），请参考 :ref:`pcnt-iram-safe` 获取更多信息。
- :menuitem:`CONFIG_PCNT_ISR_IRAM_SAFE` 用于控制当缓存禁用时，默认的 ISR 句柄是否可以工作，请参考 :ref:`pcnt-iram-safe` 获取更多信息。
- :menuitem:`CONFIG_PCNT_ENABLE_DEBUG_LOG` 用于使能调试日志输出，而这会增大固件二进制文件。
应用示例
------------
docs/zh_CN/api-reference/peripherals/rmt.rst
+7 -7
View File
@@ -571,7 +571,7 @@ RMT 编码器是 RMT TX 事务的一部分，用于在特定时间生成正确
电源管理
^^^^^^^^^^^^^^^^
当电源管理 :ref:`CONFIG_PM_ENABLE` 被启用的时候，系统在进入睡眠前可能会调整或禁用时钟源。结果是，RMT 内部的时间基准无法按预期工作。
当电源管理 :menuitem:`CONFIG_PM_ENABLE` 被启用的时候，系统在进入睡眠前可能会调整或禁用时钟源。结果是，RMT 内部的时间基准无法按预期工作。
驱动程序可以通过创建一个电源管理锁来防止上述问题。锁的类型会根据不同的时钟源来设置。驱动程序将在 :cpp:func:`rmt_enable` 中拿锁，并在 :cpp:func:`rmt_disable` 中释放锁。这意味着，无论电源管理策略如何，在这两个函数之间的任何 RMT 事务都可以保证正常工作。在此期间，时钟源不会被禁用或调整频率。
@@ -586,7 +586,7 @@ Cache 安全
默认情况下，禁用 cache 时，写入/擦除主 flash 等原因将导致 RMT 中断延迟，事件回调函数也将延迟执行。在实时应用程序中，应避免此类情况。此外，当 RMT 事务依赖 **交替** 中断连续编码或复制 RMT 符号时，上述中断延迟将导致不可预测的结果。
因此，可以启用 Kconfig 选项 :ref:`CONFIG_RMT_TX_ISR_CACHE_SAFE` 和 :ref:`CONFIG_RMT_RX_ISR_CACHE_SAFE`，该选项：
因此，可以启用 Kconfig 选项 :menuitem:`CONFIG_RMT_TX_ISR_CACHE_SAFE` 和 :menuitem:`CONFIG_RMT_RX_ISR_CACHE_SAFE`，该选项：
1. 支持在禁用 cache 时启用所需中断
2. 支持将 ISR 使用的所有函数存放在 IRAM 中 [2]_
@@ -594,9 +594,9 @@ Cache 安全
启用该选项可以保证 cache 禁用时的中断运行，但会相应增加 IRAM 占用。
请注意，当 :ref:`CONFIG_RMT_TX_ISR_CACHE_SAFE` 使能后，你必须将编码器函数（主要是 :cpp:member:`rmt_encoder_t::encode` 和 :cpp:member:`rmt_encoder_t::reset`）放进 IRAM 中。建议你使用 :c:macro:`RMT_ENCODER_FUNC_ATTR` 来装饰你的编码器函数。
请注意，当 :menuitem:`CONFIG_RMT_TX_ISR_CACHE_SAFE` 使能后，你必须将编码器函数（主要是 :cpp:member:`rmt_encoder_t::encode` 和 :cpp:member:`rmt_encoder_t::reset`）放进 IRAM 中。建议你使用 :c:macro:`RMT_ENCODER_FUNC_ATTR` 来装饰你的编码器函数。
另外一个 Kconfig 选项 :ref:`CONFIG_RMT_RECV_FUNC_IN_IRAM` 可以将 :cpp:func:`rmt_receive` 函数放进内部的 IRAM 中，从而当 flash cache 被关闭的时候，这个函数也能够被使用。
另外一个 Kconfig 选项 :menuitem:`CONFIG_RMT_RECV_FUNC_IN_IRAM` 可以将 :cpp:func:`rmt_receive` 函数放进内部的 IRAM 中，从而当 flash cache 被关闭的时候，这个函数也能够被使用。
.. _rmt-thread-safety:
@@ -615,9 +615,9 @@ RMT 驱动程序会确保工厂函数 :cpp:func:`rmt_new_tx_channel`、:cpp:func
Kconfig 选项
^^^^^^^^^^^^^^^
- :ref:`CONFIG_RMT_TX_ISR_CACHE_SAFE` 和 :ref:`CONFIG_RMT_RX_ISR_CACHE_SAFE` 控制默认 ISR 处理程序能否在禁用 cache 的情况下工作。详情请参阅 :ref:`rmt-cache-safe`。
- :ref:`CONFIG_RMT_ENABLE_DEBUG_LOG` 用于启用调试日志输出，启用此选项将增加固件的二进制文件大小。
- :ref:`CONFIG_RMT_RECV_FUNC_IN_IRAM` 用于控制 RMT 接收函数被链接到系统存储的哪个位置（IRAM 还是 Flash）。详情请参阅 :ref:`rmt-cache-safe`。
- :menuitem:`CONFIG_RMT_TX_ISR_CACHE_SAFE` 和 :menuitem:`CONFIG_RMT_RX_ISR_CACHE_SAFE` 控制默认 ISR 处理程序能否在禁用 cache 的情况下工作。详情请参阅 :ref:`rmt-cache-safe`。
- :menuitem:`CONFIG_RMT_ENABLE_DEBUG_LOG` 用于启用调试日志输出，启用此选项将增加固件的二进制文件大小。
- :menuitem:`CONFIG_RMT_RECV_FUNC_IN_IRAM` 用于控制 RMT 接收函数被链接到系统存储的哪个位置（IRAM 还是 Flash）。详情请参阅 :ref:`rmt-cache-safe`。
应用示例
--------------------
docs/zh_CN/api-reference/peripherals/sdm.rst
+4 -4
View File
@@ -84,7 +84,7 @@ SDM 通道完成任务后，请调用 :cpp:func:`sdm_del_channel` 回收相应
电源管理
^^^^^^^^
启用电源管理（即启用 :ref:`CONFIG_PM_ENABLE`）时，在进入 Light-sleep 模式前，系统会调整 APB 频率，这可能会改变 Sigma-Delta 调制器的采样率。
启用电源管理（即启用 :menuitem:`CONFIG_PM_ENABLE`）时，在进入 Light-sleep 模式前，系统会调整 APB 频率，这可能会改变 Sigma-Delta 调制器的采样率。
但是，通过获取类型为 :cpp:enumerator:`ESP_PM_APB_FREQ_MAX` 的电源管理锁，驱动程序可以防止系统改变 APB 频率。每当驱动程序创建 SDM 通道，且该通道选择 :cpp:enumerator:`SDM_CLK_SRC_APB` 作为其时钟源时，在通过 :cpp:func:`sdm_channel_enable` 启用通道的过程中，驱动程序会确保获取类型为 :cpp:enumerator:`ESP_PM_APB_FREQ_MAX` 的电源管理锁。反之，调用 :cpp:func:`sdm_channel_disable` 禁用通道时，驱动程序释放该锁。
@@ -93,7 +93,7 @@ SDM 通道完成任务后，请调用 :cpp:func:`sdm_del_channel` 回收相应
IRAM 安全
^^^^^^^^^
Kconfig 选项 :ref:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` 支持将常用的 IO 控制函数存放在 IRAM 中，以保证在禁用 cache 时可以正常使用函数。IO 控制函数如下所示：
Kconfig 选项 :menuitem:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` 支持将常用的 IO 控制函数存放在 IRAM 中，以保证在禁用 cache 时可以正常使用函数。IO 控制函数如下所示：
- :cpp:func:`sdm_channel_set_pulse_density`
@@ -115,8 +115,8 @@ Kconfig 选项 :ref:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` 支持将常用的 IO 控制
Kconfig 选项
^^^^^^^^^^^^
- :ref:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` 控制 SDM 通道控制函数的存放位置（IRAM 或 flash）。更多信息请参阅 :ref:`sdm-iram-safe`。
- :ref:`CONFIG_SDM_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用此选项将增加固件的二进制文件大小。
- :menuitem:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` 控制 SDM 通道控制函数的存放位置（IRAM 或 flash）。更多信息请参阅 :ref:`sdm-iram-safe`。
- :menuitem:`CONFIG_SDM_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用此选项将增加固件的二进制文件大小。
.. _convert_to_analog_signal:
docs/zh_CN/api-reference/peripherals/spi_flash/auto_suspend.inc
+6 -6
View File
@@ -19,7 +19,7 @@ flash 自动暂停功能
4. flash 从暂停模式恢复后，支持立即下达另一个暂停命令。
启用 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 后，缓存将保持启用状态，禁用该选项即可禁用缓存。SPI0 和 SPI1 之间的仲裁由硬件决定。当 SPI1 进行读取等耗时较短的操作时，CPU 和缓存将等待至 SPI1 操作完成。然而，在擦除、页面写入或状态寄存器写入等过程中，如 ``SE``、``PP`` 和 ``WRSR``，自动暂停功能将中断正在进行的 flash 操作，使 CPU 得以在有限的时间内读取缓存及 flash 中的数据。
启用 :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 后，缓存将保持启用状态，禁用该选项即可禁用缓存。SPI0 和 SPI1 之间的仲裁由硬件决定。当 SPI1 进行读取等耗时较短的操作时，CPU 和缓存将等待至 SPI1 操作完成。然而，在擦除、页面写入或状态寄存器写入等过程中，如 ``SE``、``PP`` 和 ``WRSR``，自动暂停功能将中断正在进行的 flash 操作，使 CPU 得以在有限的时间内读取缓存及 flash 中的数据。
基于此功能，部分的代码及变量现可存放在 flash/PSRAM 中，同时仍能保证在 flash 擦除期间的正常执行，减少了 IRAM/DRAM 的消耗。
@@ -47,7 +47,7 @@ flash 自动暂停功能
2. ISR 间隔时间 (ISR interval)：由于不能频繁触发 ISR，需格外注意 **ISR 间隔时间减去 ISR 时间后的剩余时间** （图中 b 点至 c 点的距离）。在此期间，SPI1 会发送恢复命令重新启动操作，所需准备时间 ``tsus`` 的典型值约为 **40 us**。如果在 SPI1 完成恢复操作前接收到了新的暂停命令，可能导致 CPU 饥饿，触发 ``TWDT``。
对于第 2 点中所提到的 ``tsus`` 时间可以通过翻阅 flash datasheets 查找，通常在 AC CHARACTERISTICS 章节中。用户需要保证从 datasheets 获得的 ``tsus`` 值不大于 :ref:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` 值。
对于第 2 点中所提到的 ``tsus`` 时间可以通过翻阅 flash datasheets 查找，通常在 AC CHARACTERISTICS 章节中。用户需要保证从 datasheets 获得的 ``tsus`` 值不大于 :menuitem:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` 值。
此外，flash 暂停可能延迟。CPU 和缓存通过 SPI0 频繁访问 flash，且 SPI1 频繁发送暂停命令时，会导致 MSPI 数据传输效率下降。可以通过在内部使用 **锁** 来避免此种情况。当 SPI1 发送暂停命令时，SPI0 将接管内存 SPI 总线并启用锁。SPI0 完成数据传输后，在锁延迟时间结束前，都将保有对内存 SPI 总线的控制权。在此锁延迟期间，如果接收到其他 SPI0 事务，则该 SPI0 事务将正常进行，并开启新一轮锁延迟周期。如无其他 SPI0 事务，则 SPI0 释放内存总线并启动 SPI0/1 仲裁。
@@ -60,7 +60,7 @@ suspend-resume 进阶用法
通常情况下，硬件在发出暂停命令后，会按 ``tsus`` 设定的时间延迟一段时间，再开放内存总线给 SPI0/CPU 使用。该延迟必须按 datasheet 中的最坏情况进行设置，因此在大多数情况下都偏保守。
通过启用 :ref:`CONFIG_SPI_FLASH_AUTO_CHECK_SUSPEND_STATUS` 后，硬件将通过读取 flash 状态寄存器中的 ``WIP`` 位，来判断暂停命令是否真正生效，而不再依据 :ref:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` 给出的固定时间进行等待。由于实际的暂停建立时间通常远小于 datasheet 给出的最大值，所以这种方式可以显著降低暂停过程中的开销，提升整体性能。
通过启用 :menuitem:`CONFIG_SPI_FLASH_AUTO_CHECK_SUSPEND_STATUS` 后，硬件将通过读取 flash 状态寄存器中的 ``WIP`` 位，来判断暂停命令是否真正生效，而不再依据 :menuitem:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` 给出的固定时间进行等待。由于实际的暂停建立时间通常远小于 datasheet 给出的最大值，所以这种方式可以显著降低暂停过程中的开销，提升整体性能。
.. important::
@@ -70,10 +70,10 @@ suspend-resume 进阶用法
通常情况下，硬件在 flash 被暂停后，会自动安排合适的时机发送 resume 命令，让 flash 继续完成原有的擦除/写入操作。这种实现对软件透明，但存在一个副作用：在高优先级任务/中断仍在运行时，硬件可能再次发起 suspend/resume 流程，从而打断这些任务，影响其执行的连续性与时序。
通过启用 :ref:`CONFIG_SPI_FLASH_SOFTWARE_RESUME` 后，硬件自动 resume 功能将被关闭，flash 的恢复操作改由软件在合适的时机主动发出。此时，flash 在被暂停后将一直保持暂停状态，直到软件显式恢复。在 SPI1 的等待空闲流程中，软件会主动检查 flash 的 suspend 状态，若发现处于暂停状态则调用驱动的 resume 接口让 flash 重新开始原有操作。这意味着只有当高优先级任务或中断真正完成、软件回到 SPI1 操作上下文时，才会发出 resume，从而避免 suspend-resume 行为在高优先级路径上反复抢占总线。
通过启用 :menuitem:`CONFIG_SPI_FLASH_SOFTWARE_RESUME` 后，硬件自动 resume 功能将被关闭，flash 的恢复操作改由软件在合适的时机主动发出。此时，flash 在被暂停后将一直保持暂停状态，直到软件显式恢复。在 SPI1 的等待空闲流程中，软件会主动检查 flash 的 suspend 状态，若发现处于暂停状态则调用驱动的 resume 接口让 flash 重新开始原有操作。这意味着只有当高优先级任务或中断真正完成、软件回到 SPI1 操作上下文时，才会发出 resume，从而避免 suspend-resume 行为在高优先级路径上反复抢占总线。
由于该机制依赖软件层在确定的执行点完成 resume，且当前实现没有针对多核做相应保护，因此该选项有以下限制：
- 仅支持单核场景，需要使能 :ref:`CONFIG_FREERTOS_UNICORE`。
- 属于实验性功能，需要使能 :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` 后才能可见。
- 仅支持单核场景，需要使能 :menuitem:`CONFIG_FREERTOS_UNICORE`。
- 属于实验性功能，需要使能 :menuitem:`CONFIG_IDF_EXPERIMENTAL_FEATURES` 后才能可见。
- 该功能会提升中断响应的连续性，提升应用的性能。但同时，单次操作 flash 的耗时会上升。
docs/zh_CN/api-reference/peripherals/spi_flash/index.rst
+11 -11
View File
@@ -118,7 +118,7 @@ SPI flash 容量
SPI flash 容量由引导加载程序镜像头部（烧录偏移量为 0x1000）的一个字段进行配置。
默认情况下，引导加载程序被写入 flash 时，``esptool`` 会自动检测 SPI flash 容量，同时使用正确容量更新引导加载程序的头部。也可以在工程配置中设置 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`，生成固定的 flash 容量。
默认情况下，引导加载程序被写入 flash 时，``esptool`` 会自动检测 SPI flash 容量，同时使用正确容量更新引导加载程序的头部。也可以在工程配置中设置 :menuitem:`CONFIG_ESPTOOLPY_FLASHSIZE`，生成固定的 flash 容量。
如需在运行时覆盖已配置的 flash 容量，请配置 ``g_rom_flashchip`` 结构中的 ``chip_size``。``esp_flash_*`` 函数使用此容量（于软件和 ROM 中）进行边界检查。
@@ -254,16 +254,16 @@ OS 函数层目前支持访问锁和延迟的方法。
顶层 API 将芯片驱动和 OS 函数封装成一个完整的组件，并提供参数检查。
使用 OS 函数还可以在一定程度上避免在擦除大块 flash 区域时出现看门狗超时的情况。在这段时间内，CPU 将被 flash 擦除任务占用，从而阻止其他任务的执行，包括为看门狗定时器 (WDT) 供电的空闲任务。若已选中配置选项 :ref:`CONFIG_ESP_TASK_WDT_PANIC`，并且 flash 操作时间长于看门狗的超时时间，系统将重新启动。
使用 OS 函数还可以在一定程度上避免在擦除大块 flash 区域时出现看门狗超时的情况。在这段时间内，CPU 将被 flash 擦除任务占用，从而阻止其他任务的执行，包括为看门狗定时器 (WDT) 供电的空闲任务。若已选中配置选项 :menuitem:`CONFIG_ESP_TASK_WDT_PANIC`，并且 flash 操作时间长于看门狗的超时时间，系统将重新启动。
不过，由于不同的 flash 芯片擦除时间不同，flash 驱动几乎无法兼容，很难完全规避超时的风险，这一点需要格外注意。请遵照以下指南：
1. 建议启用 :ref:`CONFIG_SPI_FLASH_YIELD_DURING_ERASE` 选项，允许调度器在擦除 flash 时进行重新调度。此外，还可以使用下列参数。
1. 建议启用 :menuitem:`CONFIG_SPI_FLASH_YIELD_DURING_ERASE` 选项，允许调度器在擦除 flash 时进行重新调度。此外，还可以使用下列参数。
- 在 menuconfig 中增加 :ref:`CONFIG_SPI_FLASH_ERASE_YIELD_TICKS` 或减少 :ref:`CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS` 的时间。
- 在 menuconfig 中增加 :ref:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` 的时间，以设置更长的看门狗超时周期。然而，看门狗超时周期拉长后，可能无法再检测到以前可检测到的超时。
- 在 menuconfig 中增加 :menuitem:`CONFIG_SPI_FLASH_ERASE_YIELD_TICKS` 或减少 :menuitem:`CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS` 的时间。
- 在 menuconfig 中增加 :menuitem:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` 的时间，以设置更长的看门狗超时周期。然而，看门狗超时周期拉长后，可能无法再检测到以前可检测到的超时。
1. 请注意，在进行长时间的 SPI flash 操作时，启用 :ref:`CONFIG_ESP_TASK_WDT_PANIC` 选项将会在超时时触发紧急处理程序。不过，启用该选项也可以帮助处理应用程序中的意外异常，请根据实际情况决定是否需要启用这个选项。
1. 请注意，在进行长时间的 SPI flash 操作时，启用 :menuitem:`CONFIG_ESP_TASK_WDT_PANIC` 选项将会在超时时触发紧急处理程序。不过，启用该选项也可以帮助处理应用程序中的意外异常，请根据实际情况决定是否需要启用这个选项。
2. 在开发过程中，请根据项目对擦除 flash 的具体要求和时间限制，谨慎进行 flash 操作。在配置 flash 擦除超时周期时，请在实际产品要求的基础上留出合理的冗余时间，从而提高产品的可靠性。
@@ -285,7 +285,7 @@ flash 操作完成后，CPU A 上的函数将设置另一标志位，即 ``s_fla
另外，所有 API 函数均受互斥量 ``s_flash_op_mutex`` 保护。
在单核环境中（启用 :ref:`CONFIG_FREERTOS_UNICORE`），需要禁用上述两个 cache，以防发生 CPU 间通信。
在单核环境中（启用 :menuitem:`CONFIG_FREERTOS_UNICORE`），需要禁用上述两个 cache，以防发生 CPU 间通信。
.. only:: SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND
@@ -294,13 +294,13 @@ flash 操作完成后，CPU A 上的函数将设置另一标志位，即 ``s_fla
flash 驱动的内部存储优化
-----------------------------
ESP-IDF 提供了优化 IRAM 使用的选项。通过禁用 :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 选项，可以选择性地将某些函数地放入 flash，使 SPI flash 操作函数在 flash 中执行，而不是从 IRAM 中执行。这种方式能够节省 IRAM 内存，用于其他对时间敏感的函数或任务。
ESP-IDF 提供了优化 IRAM 使用的选项。通过禁用 :menuitem:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 选项，可以选择性地将某些函数地放入 flash，使 SPI flash 操作函数在 flash 中执行，而不是从 IRAM 中执行。这种方式能够节省 IRAM 内存，用于其他对时间敏感的函数或任务。
然而，这种方式对 flash 性能具有一定的影响。与 IRAM 中的函数相比，放在 flash 中的函数执行时间可能略有增加。因此对于具有严格时序要求或严重依赖 SPI flash 操作的应用程序，采取此方式前需进行权衡。
.. note::
未启用 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 时，不应禁用 :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM`，否则会导致严重崩溃。关于 flash 挂起功能，请参阅 :ref:`auto-suspend`。
未启用 :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 时，不应禁用 :menuitem:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM`，否则会导致严重崩溃。关于 flash 挂起功能，请参阅 :ref:`auto-suspend`。
资源消耗
^^^^^^^^^^^^
@@ -309,7 +309,7 @@ flash 操作完成后，CPU A 上的函数将设置另一标志位，即 ``s_fla
**请注意，以下数据并非精确值，仅供参考；不同芯片型号可能会有所差异。**
启用 :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 时的资源消耗如下表所示：
启用 :menuitem:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 时的资源消耗如下表所示：
.. list-table:: 选项启用时的资源消耗
:widths: 20 10 10 10 10 10 10 10 10 10
@@ -346,7 +346,7 @@ flash 操作完成后，CPU A 上的函数将设置另一标志位，即 ``s_fla
- 247
- 247
禁用 :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 时的资源消耗如下表所示：
禁用 :menuitem:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 时的资源消耗如下表所示：
.. list-table:: 选项禁用时的资源消耗
:widths: 20 10 10 10 10 10 10 10 10 10
docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst
+1 -1
View File
@@ -19,7 +19,7 @@ SPI0/1 总线上可能发生三种活动：
.. list::
- 调用非加密 SPI flash 读取 API（:cpp:func:`esp_flash_read` 等）
:esp32: - 或 SPI1 总线上的其他驱动程序用于用户定义的 SPI 操作（启用实验性功能 :ref:`CONFIG_SPI_FLASH_SHARE_SPI1_BUS`）
:esp32: - 或 SPI1 总线上的其他驱动程序用于用户定义的 SPI 操作（启用实验性功能 :menuitem:`CONFIG_SPI_FLASH_SHARE_SPI1_BUS`）
- 缓存读取（通过 SPI0）。以下 API 和操作可以触发缓存读取：
docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst
+11 -11
View File
@@ -6,7 +6,7 @@ SPI Flash API ESP-IDF 版本与芯片 ROM 版本的对比
.. toctree::
:maxdepth: 1
芯片 ROM 中有一组 SPI flash 驱动程序，可以通过启用 :ref:`CONFIG_SPI_FLASH_ROM_IMPL` 来使用。大多数 ESP-IDF SPI flash 驱动程序的代码都在内部 RAM 中，因此启用此选项可以释放一些内部 RAM 的占用量。请注意，如果启用此选项，一些 ESP-IDF 中的 SPI flash 驱动程序功能和错误修复可能不会体现在芯片 ROM 版本中。
芯片 ROM 中有一组 SPI flash 驱动程序，可以通过启用 :menuitem:`CONFIG_SPI_FLASH_ROM_IMPL` 来使用。大多数 ESP-IDF SPI flash 驱动程序的代码都在内部 RAM 中，因此启用此选项可以释放一些内部 RAM 的占用量。请注意，如果启用此选项，一些 ESP-IDF 中的 SPI flash 驱动程序功能和错误修复可能不会体现在芯片 ROM 版本中。
ESP-IDF 支持但不包含在芯片 ROM 中的功能
@@ -17,16 +17,16 @@ ESP-IDF 支持但不包含在芯片 ROM 中的功能
- 八线 flash 芯片。详情请参阅 :ref:`oct-flash-doc`。
- Flash 的 32 位地址。请注意，此功能为可选功能，详情请参阅 :ref:`32-bit-flash-doc`。
- TH flash 芯片。
- Kconfig 选项 :ref:`CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED`。
- :ref:`CONFIG_SPI_FLASH_VERIFY_WRITE`，启用此选项可检测错误写入。
- :ref:`CONFIG_SPI_FLASH_LOG_FAILED_WRITE`，启用此选项会打印错误写入。
- :ref:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`，启用此选项会检查是否将 0 写入为 1。
- :ref:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`，启用此选项会检查是否对某些受保护的区域（如引导加载程序、分区表或应用程序本身）进行了 flash 编程。
- :ref:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`，启用此选项以收集 ESP-IDF SPI flash 驱动程序 API 的性能数据。
- :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`，启用此选项可在 flash 短时操作时自动挂起或恢复 flash 长时操作。请注意，此功能为可选功能，详情请参阅 :ref:`auto-suspend-intro`。
- :ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`，启用此选项可在休眠时配置 flash 进入 deep power-down 模式以降低功耗。请注意，此功能为可选功能，详情请参阅 :ref:`deep-power-down-mode`。
:ESP_ROM_HAS_SPI_FLASH_MMAP and SOC_SPIRAM_XIP_SUPPORTED and not esp32s3: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`，启用该选项后，可将外部 PSRAM 用作指令 cache 和只读数据 cache。但请注意，ROM 中的某些函数不支持此用法，而 ESP-IDF 提供了这些 ROM 函数的替代版本。
:esp32s3: - 启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 和 :ref:`CONFIG_SPIRAM_RODATA` 后，可将外部 PSRAM 用作指令 cache 和只读数据 cache。但请注意，ROM 中的某些函数不支持此用法，而 ESP-IDF 提供了这些 ROM 函数的替代版本。
- Kconfig 选项 :menuitem:`CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED`。
- :menuitem:`CONFIG_SPI_FLASH_VERIFY_WRITE`，启用此选项可检测错误写入。
- :menuitem:`CONFIG_SPI_FLASH_LOG_FAILED_WRITE`，启用此选项会打印错误写入。
- :menuitem:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`，启用此选项会检查是否将 0 写入为 1。
- :menuitem:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`，启用此选项会检查是否对某些受保护的区域（如引导加载程序、分区表或应用程序本身）进行了 flash 编程。
- :menuitem:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`，启用此选项以收集 ESP-IDF SPI flash 驱动程序 API 的性能数据。
- :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND`，启用此选项可在 flash 短时操作时自动挂起或恢复 flash 长时操作。请注意，此功能为可选功能，详情请参阅 :ref:`auto-suspend-intro`。
- :menuitem:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`，启用此选项可在休眠时配置 flash 进入 deep power-down 模式以降低功耗。请注意，此功能为可选功能，详情请参阅 :ref:`deep-power-down-mode`。
:ESP_ROM_HAS_SPI_FLASH_MMAP and SOC_SPIRAM_XIP_SUPPORTED and not esp32s3: - :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM`，启用该选项后，可将外部 PSRAM 用作指令 cache 和只读数据 cache。但请注意，ROM 中的某些函数不支持此用法，而 ESP-IDF 提供了这些 ROM 函数的替代版本。
:esp32s3: - 启用 :menuitem:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 和 :menuitem:`CONFIG_SPIRAM_RODATA` 后，可将外部 PSRAM 用作指令 cache 和只读数据 cache。但请注意，ROM 中的某些函数不支持此用法，而 ESP-IDF 提供了这些 ROM 函数的替代版本。
在 ESP-IDF 中引入，但不包含在芯片 ROM 中的错误修复
--------------------------------------------------
docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst
+7 -7
View File
@@ -94,7 +94,7 @@ QSPI flash 芯片的高性能模式
启用高性能模式的方法：
1. 取消选择 :ref:`CONFIG_ESPTOOLPY_OCT_FLASH` 和 :ref:`CONFIG_ESPTOOLPY_FLASH_MODE_AUTO_DETECT`。高性能模式不用于八线 flash，启用相关选项可能会导致无法使用高性能模式。
1. 取消选择 :menuitem:`CONFIG_ESPTOOLPY_OCT_FLASH` 和 :menuitem:`CONFIG_ESPTOOLPY_FLASH_MODE_AUTO_DETECT`。高性能模式不用于八线 flash，启用相关选项可能会导致无法使用高性能模式。
2. 启用 ``CONFIG_SPI_FLASH_HPM_ENA`` 选项。
@@ -108,13 +108,13 @@ QSPI flash 芯片的高性能模式
通过以下方式检查引导加载程序是否支持 `DC Aware`：
- 如果启动了新项目，建议通过在引导加载程序菜单中选择 :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` 选项来启用 `DC Aware`。请注意，此选项无法通过 OTA 修改，因为支持代码在引导加载程序中。
- 如果启动了新项目，建议通过在引导加载程序菜单中选择 :menuitem:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` 选项来启用 `DC Aware`。请注意，此选项无法通过 OTA 修改，因为支持代码在引导加载程序中。
- 如果想在现有项目中通过 OTA 来更新 `HPM-DC` 配置选项，请检查用于构建引导加载程序的 sdkconfig 文件（升级 ESP-IDF 版本可能会使此文件与用于构建引导加载程序的文件不同）：
- 对于最新版本的 ESP-IDF（v4.4.7+、v5.0.7+、v5.1.4+、v5.2 及以上），如果选择了 :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE`，则引导加载程序支持 `DC Aware`。
- 对于最新版本的 ESP-IDF（v4.4.7+、v5.0.7+、v5.1.4+、v5.2 及以上），如果选择了 :menuitem:`CONFIG_BOOTLOADER_FLASH_DC_AWARE`，则引导加载程序支持 `DC Aware`。
- 对于某些范围内的 ESP-IDF 版本（v4.4.4-v4.4.6、v5.0-v5.0.6 和 v5.1-v5.1.3），如果选择了 ``CONFIG_ESPTOOLPY_FLASHFREQ_120M``，则引导加载程序支持 `DC Aware`。此时，可启用 :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` 进行确认（不会影响实际应用中的引导加载程序）。
- 对于某些范围内的 ESP-IDF 版本（v4.4.4-v4.4.6、v5.0-v5.0.6 和 v5.1-v5.1.3），如果选择了 ``CONFIG_ESPTOOLPY_FLASHFREQ_120M``，则引导加载程序支持 `DC Aware`。此时，可启用 :menuitem:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` 进行确认（不会影响实际应用中的引导加载程序）。
- 对于低于 v4.4.4 的 ESP-IDF 版本，引导加载程序不支持 `DC Aware`。
@@ -185,12 +185,12 @@ QSPI flash 芯片的 32 位地址支持
默认情况下，上述超过 16 MB 内存的 flash 区域可用于数据存储，例如使用文件系统。
*实验性功能*：如需在超过 16 MB 的四线 flash 区域实现完整支持（包括代码执行和数据访问），请启用以下实验性配置选项：
- :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES`
- :ref:`CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH`
- :menuitem:`CONFIG_IDF_EXPERIMENTAL_FEATURES`
- :menuitem:`CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH`
请注意，此选项为实验性功能，无法在所有四线 flash 芯片上稳定使用。详情请咨询 `乐鑫商务部 <https://www.espressif.com/zh-hans/contact-us/sales-questions>`_。
对于八线 flash 芯片，如果启用了 :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`，则该功能默认启用。
对于八线 flash 芯片，如果启用了 :menuitem:`CONFIG_ESPTOOLPY_OCT_FLASH`，则该功能默认启用。
.. _oct-flash-doc:
docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst
+2 -2
View File
@@ -159,7 +159,7 @@
.. important::
flash 芯片的硬件设计各不相同，因此启用 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 选项暂停 flash 时应仔细且系统地进行测试。如果想在量产过程中使用挂起功能，请联系 `乐鑫商务部 <https://www.espressif.com/zh-hans/contact-us/sales-questions>`_。
flash 芯片的硬件设计各不相同，因此启用 :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 选项暂停 flash 时应仔细且系统地进行测试。如果想在量产过程中使用挂起功能，请联系 `乐鑫商务部 <https://www.espressif.com/zh-hans/contact-us/sales-questions>`_。
.. code-block:: c
@@ -232,7 +232,7 @@
- 步骤 5：在 cache 被禁用时，通过 ``linker.lf`` 文件把要使用的所有芯片驱动程序放入内部 RAM 中。详情请参阅 :doc:`/api-guides/linker-script-generation`。请确保 ``linker.lf`` 包含了你添加的所有源文件。
- 步骤 6：在项目中添加一个新的组件，例如 ``custom_chip_driver``。在 ``custom_chip_driver/chip_drivers.c`` 文件中将芯片对象列在 ``default_registered_chips`` 下。启用 :ref:`CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST` 配置选项，防止编译和链接由 ESP-IDF 提供的默认芯片驱动程序列表 ``default_registered_chips``；相反，链接器会搜索由你自定义的同名结构体 ``default_registered_chips``。详情请参阅 :example_file:`storage/custom_flash_driver/components/custom_chip_driver/chip_drivers.c`。
- 步骤 6：在项目中添加一个新的组件，例如 ``custom_chip_driver``。在 ``custom_chip_driver/chip_drivers.c`` 文件中将芯片对象列在 ``default_registered_chips`` 下。启用 :menuitem:`CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST` 配置选项，防止编译和链接由 ESP-IDF 提供的默认芯片驱动程序列表 ``default_registered_chips``；相反，链接器会搜索由你自定义的同名结构体 ``default_registered_chips``。详情请参阅 :example_file:`storage/custom_flash_driver/components/custom_chip_driver/chip_drivers.c`。
- 步骤 7：构建项目，你将看到新的 flash 驱动程序。
docs/zh_CN/api-reference/peripherals/spi_flash/xip_from_psram.inc
+1 -1
View File
@@ -3,7 +3,7 @@
从 PSRAM 执行代码功能
----------------------
选择 :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` 配置以启用此模式。在此模式下，代码从 PSRAM 执行，在大多数情况下，缓存不会在写入 API 期间被禁用。
选择 :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM` 配置以启用此模式。在此模式下，代码从 PSRAM 执行，在大多数情况下，缓存不会在写入 API 期间被禁用。
在此模式下，flash ``.text`` 段（用于指令）和 flash ``.rodata`` 段（用于只读数据）将在启动时加载到 PSRAM。相应的虚拟地址将映射到 PSRAM。您无需确保在 flash 被擦除/编程时执行的代码/数据位于 IRAM 中。
docs/zh_CN/api-reference/peripherals/spi_master.rst
+4 -4
View File
@@ -580,7 +580,7 @@ GPIO 矩阵与 IO_MUX 管脚
- 使用 DMA 的轮询传输事务：{IDF_TARGET_MAX_TRANS_TIME_POLL_DMA} µs。
- 使用 CPU 的轮询传输事务：{IDF_TARGET_MAX_TRANS_TIME_POLL_CPU} µs。
请注意，以上数据测试时，:ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` 选项处于启用状态，SPI 传输事务相关的代码放置在 IRAM 中。若关闭此选项（例如为了节省 IRAM），可能影响传输事务持续时间。
请注意，以上数据测试时，:menuitem:`CONFIG_SPI_MASTER_ISR_IN_IRAM` 选项处于启用状态，SPI 传输事务相关的代码放置在 IRAM 中。若关闭此选项（例如为了节省 IRAM），可能影响传输事务持续时间。
SPI 时钟频率
^^^^^^^^^^^^^^^^^^^
@@ -636,11 +636,11 @@ GPSPI 外设的时钟源可以通过设置 :cpp:member:`spi_device_interface_con
缓存缺失
^^^^^^^^^^
默认配置只将 ISR 置于 IRAM 中。其他 SPI 相关功能，包括驱动本身和回调都可能发生缓存缺失，需等待代码从 flash 中读取。为避免缓存缺失，可参考 :ref:`CONFIG_SPI_MASTER_IN_IRAM`，将整个 SPI 驱动置入 IRAM，并将整个回调及其 callee 函数一起置入 IRAM。
默认配置只将 ISR 置于 IRAM 中。其他 SPI 相关功能，包括驱动本身和回调都可能发生缓存缺失，需等待代码从 flash 中读取。为避免缓存缺失，可参考 :menuitem:`CONFIG_SPI_MASTER_IN_IRAM`，将整个 SPI 驱动置入 IRAM，并将整个回调及其 callee 函数一起置入 IRAM。
.. note::
SPI 驱动是基于 FreeRTOS 的 API 实现的，在使用 :ref:`CONFIG_SPI_MASTER_IN_IRAM` 时，应启用 :ref:`CONFIG_FREERTOS_IN_IRAM`。
SPI 驱动是基于 FreeRTOS 的 API 实现的，在使用 :menuitem:`CONFIG_SPI_MASTER_IN_IRAM` 时，应启用 :menuitem:`CONFIG_FREERTOS_IN_IRAM`。
单个中断传输事务传输 n 字节的总成本为 **20+8n/Fspi[MHz]** [µs]，故传输速度为 **n/(20+8n/Fspi)**。8 MHz 时钟速度的传输速度见下表。
@@ -681,7 +681,7 @@ GPSPI 外设的时钟源可以通过设置 :cpp:member:`spi_device_interface_con
传输事务长度较短时将提高传输事务间隔成本，因此应尽可能将几个短传输事务压缩成一个传输事务，以提升传输速度。
注意，ISR 在 flash 操作期间默认处于禁用状态。要在 flash 操作期间继续发送传输事务，请启用 :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM`，并在 :cpp:member:`spi_bus_config_t::intr_flags` 中设置 :c:macro:`ESP_INTR_FLAG_IRAM`。此时，flash 操作前列队的传输事务将由 ISR 并行处理。此外，每个设备的回调和它们的 ``callee`` 函数都应该在 IRAM 中，避免回调因缓存丢失而崩溃。详情请参阅 :ref:`iram-safe-interrupt-handlers`。
注意，ISR 在 flash 操作期间默认处于禁用状态。要在 flash 操作期间继续发送传输事务，请启用 :menuitem:`CONFIG_SPI_MASTER_ISR_IN_IRAM`，并在 :cpp:member:`spi_bus_config_t::intr_flags` 中设置 :c:macro:`ESP_INTR_FLAG_IRAM`。此时，flash 操作前列队的传输事务将由 ISR 并行处理。此外，每个设备的回调和它们的 ``callee`` 函数都应该在 IRAM 中，避免回调因缓存丢失而崩溃。详情请参阅 :ref:`iram-safe-interrupt-handlers`。
.. only:: esp32h2
docs/zh_CN/api-reference/peripherals/temp_sensor.rst
+1 -1
View File
@@ -142,7 +142,7 @@
默认情况下，禁用 cache 时，写入/擦除 flash 等原因将导致温度传感器中断延迟，事件回调函数也将延迟执行。在实时应用程序中，应避免此类情况。
因此，可以启用 Kconfig 选项 :ref:`CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE`，该选项：
因此，可以启用 Kconfig 选项 :menuitem:`CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE`，该选项：
1. 支持在禁用 cache 时启用所需中断
2. 支持将 ISR 使用的所有函数存放在 IRAM 中
docs/zh_CN/api-reference/peripherals/twai.rst
+9 -9
View File
@@ -371,7 +371,7 @@ TWAI控制器能够检测由于总线干扰产生的/损坏的不符合帧格式
关于低功耗
----------
当启用电源管理 :ref:`CONFIG_PM_ENABLE` 时，系统在进入睡眠模式前可能会调整或关闭时钟源，从而导致 TWAI 出错。为了防止这种情况发生，驱动内部使用电源锁管理。当调用 :cpp:func:`twai_node_enable` 函数后，该锁将被激活，确保系统不会进入睡眠模式，从而保持 TWAI 功能正常。如果需要降低功耗，可以调用 :cpp:func:`twai_node_disable` 函数来释放电源管理锁，使系统能够进入睡眠模式，睡眠期间 TWAI 控制器也将停止工作。
当启用电源管理 :menuitem:`CONFIG_PM_ENABLE` 时，系统在进入睡眠模式前可能会调整或关闭时钟源，从而导致 TWAI 出错。为了防止这种情况发生，驱动内部使用电源锁管理。当调用 :cpp:func:`twai_node_enable` 函数后，该锁将被激活，确保系统不会进入睡眠模式，从而保持 TWAI 功能正常。如果需要降低功耗，可以调用 :cpp:func:`twai_node_disable` 函数来释放电源管理锁，使系统能够进入睡眠模式，睡眠期间 TWAI 控制器也将停止工作。
.. only:: SOC_TWAI_SUPPORT_SLEEP_RETENTION
@@ -380,12 +380,12 @@ TWAI控制器能够检测由于总线干扰产生的/损坏的不符合帧格式
{IDF_TARGET_NAME} 支持在 **Light Sleep** 期间将 TWAI 控制器断电以进一步降低功耗，并在唤醒后自动恢复。即程序不需要在 **Light Sleep** 唤醒后重新配置 TWAI。
启用选项 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，并在初始化 TWAI 节点时，将 :cpp:member:`twai_onchip_node_config_t::flags::sleep_allow_pd` 设置为 ``true`` 即可启用该功能，否则 TWAI 控制器在 **Light Sleep** 期间将保持供电。它可以帮助降低轻度睡眠时的功耗，但需要花费一些额外的存储来保存寄存器的配置。
启用选项 :menuitem:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，并在初始化 TWAI 节点时，将 :cpp:member:`twai_onchip_node_config_t::flags::sleep_allow_pd` 设置为 ``true`` 即可启用该功能，否则 TWAI 控制器在 **Light Sleep** 期间将保持供电。它可以帮助降低轻度睡眠时的功耗，但需要花费一些额外的存储来保存寄存器的配置。
关于 Cache 安全
---------------
在进行 Flash 写操作时，为了避免 Cache 从 Flash 加载指令和数据时出现错误，系统会暂时禁用 Cache 功能。这会导致存放在 Flash 上的中断处理程序在此期间无法响应。如果希望在 Cache 被禁用期间，中断处理程序仍能正常运行，可以启用 :ref:`CONFIG_TWAI_ISR_CACHE_SAFE` 选项。
在进行 Flash 写操作时，为了避免 Cache 从 Flash 加载指令和数据时出现错误，系统会暂时禁用 Cache 功能。这会导致存放在 Flash 上的中断处理程序在此期间无法响应。如果希望在 Cache 被禁用期间，中断处理程序仍能正常运行，可以启用 :menuitem:`CONFIG_TWAI_ISR_CACHE_SAFE` 选项。
.. note::
@@ -399,9 +399,9 @@ TWAI控制器能够检测由于总线干扰产生的/损坏的不符合帧格式
关于性能
--------
为了提升中断处理的实时响应能力， 驱动提供了 :ref:`CONFIG_TWAI_ISR_IN_IRAM` 选项。启用该选项后，中断处理程序和接收操作将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令带来的延迟。
为了提升中断处理的实时响应能力， 驱动提供了 :menuitem:`CONFIG_TWAI_ISR_IN_IRAM` 选项。启用该选项后，中断处理程序和接收操作将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令带来的延迟。
对于需要高性能发送操作的应用，驱动还提供了 :ref:`CONFIG_TWAI_IO_FUNC_IN_IRAM` 选项，用于将发送函数放置在 IRAM 中。这对于在用户任务中频繁调用 :cpp:func:`twai_node_transmit` 的时间关键应用特别有效。
对于需要高性能发送操作的应用，驱动还提供了 :menuitem:`CONFIG_TWAI_IO_FUNC_IN_IRAM` 选项，用于将发送函数放置在 IRAM 中。这对于在用户任务中频繁调用 :cpp:func:`twai_node_transmit` 的时间关键应用特别有效。
.. note::
@@ -416,8 +416,8 @@ TWAI控制器能够检测由于总线干扰产生的/损坏的不符合帧格式
- 默认日志等级设置为 ``ESP_LOG_INFO``，以平衡调试信息和性能。
- 关闭以下驱动优化选项：
- :ref:`CONFIG_TWAI_ISR_IN_IRAM` - 中断处理程序不放入 IRAM。
- :ref:`CONFIG_TWAI_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
- :menuitem:`CONFIG_TWAI_ISR_IN_IRAM` - 中断处理程序不放入 IRAM。
- :menuitem:`CONFIG_TWAI_ISR_CACHE_SAFE` - 不启用 Cache 安全选项。
**注意，以下数据仅供参考，不是精确值，在不同芯片上会有所出入。**
@@ -431,7 +431,7 @@ TWAI控制器能够检测由于总线干扰产生的/损坏的不符合帧格式
| soc | 64 | 0 | 0 | 0 | 0 | 64 | 64 | 0 |
+-----------------+------------+-------+------+-------+-------+-------+---------+-------+
打开 :ref:`CONFIG_TWAI_ISR_IN_IRAM` 优化选项的消耗情况：
打开 :menuitem:`CONFIG_TWAI_ISR_IN_IRAM` 优化选项的消耗情况：
+-----------------+------------+-------+------+-------+-------+-------+---------+-------+
| Component Layer | Total Size | DIRAM | .bss | .data | .text | Flash | .rodata | .text |
@@ -448,7 +448,7 @@ TWAI控制器能够检测由于总线干扰产生的/损坏的不符合帧格式
其他 Kconfig 选项
-----------------
- :ref:`CONFIG_TWAI_ENABLE_DEBUG_LOG` 选项允许强制启用 TWAI 驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题。
- :menuitem:`CONFIG_TWAI_ENABLE_DEBUG_LOG` 选项允许强制启用 TWAI 驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题。
应用示例
========
docs/zh_CN/api-reference/peripherals/uhci.rst
+6 -6
View File
@@ -241,7 +241,7 @@ RX 事件数据在 :cpp:type:`uhci_rx_event_data_t` 中定义：
关于低功耗
^^^^^^^^^^^^^^^^
当启用电源管理时（即开启 :ref:`CONFIG_PM_ENABLE`），系统在进入睡眠前可能会调整或禁用时钟源。因此，UHCI 内部的 FIFO 可能无法正常工作。
当启用电源管理时（即开启 :menuitem:`CONFIG_PM_ENABLE`），系统在进入睡眠前可能会调整或禁用时钟源。因此，UHCI 内部的 FIFO 可能无法正常工作。
通过创建电源管理锁，驱动程序可以避免上述问题. 驱动会根据不同的时钟源设置锁的类型. 驱动程序将在 :cpp:func:`uhci_receive` 或 :cpp:func:`uhci_transmit` 中获取锁，并在事务完成中断中释放锁。这意味着，这两个函数之间的任何 UHCI 事务都能保证正常稳定运行。
@@ -250,7 +250,7 @@ RX 事件数据在 :cpp:type:`uhci_rx_event_data_t` 中定义：
默认情况下，当由于写入或擦除主 Flash 导致缓存被禁用时，UHCI 所依赖的中断会被延迟. 因此，事务完成中断可能无法及时处理，这在实时应用中是不可接受的。更糟糕的是，当 UHCI 事务依赖 **乒乓** 中断来连续编码或复制 UHCI 缓冲区时，延迟的中断可能会导致不可预测的结果。
通过启用 Kconfig 选项 :ref:`CONFIG_UHCI_ISR_CACHE_SAFE`，可实现以下功能：
通过启用 Kconfig 选项 :menuitem:`CONFIG_UHCI_ISR_CACHE_SAFE`，可实现以下功能：
1. 即使缓存被禁用，中断也能被及时处理。
2. 将 ISR 使用的所有函数放入 IRAM [1]_
@@ -265,7 +265,7 @@ RX 事件数据在 :cpp:type:`uhci_rx_event_data_t` 中定义：
**请注意以下数据仅供参考，不同芯片型号可能会有所不同.**
启用 :ref:`CONFIG_UHCI_ISR_CACHE_SAFE` 时的资源消耗：
启用 :menuitem:`CONFIG_UHCI_ISR_CACHE_SAFE` 时的资源消耗：
.. list-table:: 资源消耗
:widths: 10 10 10 10 10 10 10 10 10
@@ -290,7 +290,7 @@ RX 事件数据在 :cpp:type:`uhci_rx_event_data_t` 中定义：
- 175
- 175
禁用 :ref:`CONFIG_UHCI_ISR_CACHE_SAFE` 时的资源消耗：
禁用 :menuitem:`CONFIG_UHCI_ISR_CACHE_SAFE` 时的资源消耗：
.. list-table:: 资源消耗
:widths: 10 10 10 10 10 10 10 10 10 10
@@ -320,7 +320,7 @@ RX 事件数据在 :cpp:type:`uhci_rx_event_data_t` 中定义：
关于性能
^^^^^^^^
为了提升中断处理的实时响应能力， UHCI 驱动提供了 :ref:`CONFIG_UHCI_ISR_HANDLER_IN_IRAM` 选项。启用该选项后，中断处理程序将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令时可能出现的缓存丢失带来的延迟。
为了提升中断处理的实时响应能力， UHCI 驱动提供了 :menuitem:`CONFIG_UHCI_ISR_HANDLER_IN_IRAM` 选项。启用该选项后，中断处理程序将被放置在内部 RAM 中运行，从而减少了从 Flash 加载指令时可能出现的缓存丢失带来的延迟。
.. note::
@@ -334,7 +334,7 @@ RX 事件数据在 :cpp:type:`uhci_rx_event_data_t` 中定义：
其他 Kconfig 选项
^^^^^^^^^^^^^^^^^^^^^
- :ref:`CONFIG_UHCI_ENABLE_DEBUG_LOG` 选项允许强制启用 UHCI 驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题，但会增加固件二进制文件的大小。
- :menuitem:`CONFIG_UHCI_ENABLE_DEBUG_LOG` 选项允许强制启用 UHCI 驱动的所有调试日志，无论全局日志级别设置如何。启用此选项可以帮助开发人员在调试过程中获取更详细的日志信息，从而更容易定位和解决问题，但会增加固件二进制文件的大小。
应用示例
--------------------