docs(system): update API references for H4 and S31

Add target-specific power-management frequencies and capability
conditions so later chips do not need chip-by-chip list updates.

docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst

@@ -15,8 +15,9 @@
   .. list::
 
      - 使用线程局部存储 (TLS)
-     :esp32p4: - 使用浮点运算器 (FPU)
-     :esp32p4: - 使用 AI 协处理器
+     :SOC_CPU_HAS_FPU: - 使用浮点运算器 (FPU)
+     :SOC_CPU_HAS_PIE: - 使用 AI 协处理器
+     :SOC_CPU_HAS_DSP: - 使用 DSP 协处理器
      - 调用 vTaskDelete(NULL) 删除当前运行的任务
 
   此外，从共享堆栈上运行的函数中，或该函数调用的任何函数中调用回溯，回溯信息都可能不正确。这方面的限制十分严格，因此将来 :cpp:func:`esp_execute_shared_stack_function` 可能会被弃用。如有用例必须使用 :cpp:func:`esp_execute_shared_stack_function` 函数才能实现，请提交 `GitHub Issue <https://github.com/espressif/esp-idf/issues>`_。

docs/zh_CN/api-reference/system/freertos.rst

@@ -24,7 +24,7 @@ ESP-IDF FreeRTOS
 
         ESP-IDF FreeRTOS 是目前 ESP-IDF 默认的 FreeRTOS 实现。
 
-.. only:: not esp32p4 and not esp32h4
+.. only:: not (CONFIG_IDF_TARGET_ARCH_RISCV and SOC_HP_CPU_HAS_MULTIPLE_CORES)
 
     .. _amazon_smp_freertos:
 

docs/zh_CN/api-reference/system/freertos_idf.rst

@@ -47,7 +47,7 @@ IDF FreeRTOS 源代码基于 Vanilla FreeRTOS v10.5.1，但内核行为和 API
 ESP 芯片上的 SMP
 ^^^^^^^^^^^^^^^^
 
-ESP32、ESP32-S3、ESP32-P4 和 ESP32-H4 等 ESP 芯片是双核 SMP SoC，具有以下硬件特性以支持 SMP：
+具有双高性能核的 ESP 芯片具备以下硬件特性以支持 SMP：
 
 - 具有两个完全相同的核，分别称为核 0 和核 1。代码段无论在哪个核上运行，都有相同的执行效果。
 - 具有对称内存（除了少数例外情况）。

docs/zh_CN/api-reference/system/inc/power_management_esp32h4.rst

@@ -2,6 +2,39 @@
 .. flat-table::
     :widths: 1 3 3
 
-    * - Max CPU Frequency Set
-      - Lock Acquisition
-      - CPU and APB Frequencies
+    * - CPU 最高频率
+      - 电源管理锁获取情况
+      - APB 频率和 CPU 频率
+    * - :rspan:`2` 96
+      - 获取 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 96 MHz
+        - APB: 32 MHz
+    * - 获取 ``ESP_PM_APB_FREQ_MAX``，未获得 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 32 MHz
+        - APB: 32 MHz
+    * - 无
+      - 使用 :cpp:func:`esp_pm_configure` 为二者设置最小值
+    * - :rspan:`2` 64
+      - 获取 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 64 MHz
+        - APB: 32 MHz
+    * - 获取 ``ESP_PM_APB_FREQ_MAX``，未获得 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 32 MHz
+        - APB: 32 MHz
+    * - 无
+      - 使用 :cpp:func:`esp_pm_configure` 为二者设置最小值
+    * - :rspan:`2` 48
+      - 获取 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 48 MHz
+        - APB: 24 MHz
+    * - 获取 ``ESP_PM_APB_FREQ_MAX``，未获得 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 32 MHz
+        - APB: 32 MHz
+    * - 无
+      - 使用 :cpp:func:`esp_pm_configure` 为二者设置最小值

docs/zh_CN/api-reference/system/inc/power_management_esp32s31.rst

@@ -1,3 +1,29 @@
-.. note::
 
-    To be updated.
+.. flat-table::
+    :widths: 1 3 3
+
+    * - CPU 最高频率
+      - 电源管理锁获取情况
+      - APB 频率和 CPU 频率
+    * - :rspan:`2` 320
+      - 获取 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 320 MHz
+        - APB: 53.3 MHz
+    * - 获取 ``ESP_PM_APB_FREQ_MAX``，未获得 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 53.3 MHz
+        - APB: 53.3 MHz
+    * - 无
+      - 使用 :cpp:func:`esp_pm_configure` 为二者设置最小值
+    * - :rspan:`2` 240
+      - 获取 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 240 MHz
+        - APB: 40 MHz
+    * - 获取 ``ESP_PM_APB_FREQ_MAX``，未获得 ``ESP_PM_CPU_FREQ_MAX``
+      -
+        - CPU: 40 MHz
+        - APB: 40 MHz
+    * - 无
+      - 使用 :cpp:func:`esp_pm_configure` 为二者设置最小值

docs/zh_CN/api-reference/system/intr_alloc.rst

@@ -22,10 +22,18 @@
 
     {IDF_TARGET_NAME} 有一个核，28 个外部异步中断。每个中断的优先级别都可独立地通过编程设置。此外，还有 4 个核心本地中断源 (CLINT)。详细信息请参见 **{IDF_TARGET_NAME} 技术参考手册** [`PDF <{IDF_TARGET_TRM_CN_URL}#riscvcpu>`__]。
 
-.. only:: esp32p4 or esp32h4
+.. only:: esp32p4
 
     {IDF_TARGET_NAME} 有两个核，每个核有 32 个外部异步中断。每个中断的优先级别都可独立地通过编程设置。此外，每个核还有 3 个核心本地中断源 (CLINT)。详细信息请参见 **{IDF_TARGET_NAME} 技术参考手册** [`PDF <{IDF_TARGET_TRM_CN_URL}#riscvcpu>`__]。
 
+.. only:: esp32h4
+
+    {IDF_TARGET_NAME} 有两个核，每个核有 32 个外部异步中断。每个中断的优先级别都可独立地通过编程设置。此外，每个核还有 2 个核心本地中断源 (CLINT)。详细信息请参见 **{IDF_TARGET_NAME} 技术参考手册** [`PDF <{IDF_TARGET_TRM_CN_URL}#riscvcpu>`__]。
+
+.. only:: esp32s31
+
+    {IDF_TARGET_NAME} 有两个核，每个核有 32 个外部异步中断。每个中断的优先级别都可独立地通过编程设置。详细信息请参见 **{IDF_TARGET_NAME} 技术参考手册** [`PDF <{IDF_TARGET_TRM_CN_URL}#riscvcpu>`__]。
+
 .. only:: esp32c5 or esp32c61
 
     {IDF_TARGET_NAME} 有一个核，32 个外部异步中断。每个中断的优先级别都可独立地通过编程设置。此外，还有 3 个核心本地中断源 (CLINT)。详细信息请参见 **{IDF_TARGET_NAME} 技术参考手册** > **高性能处理器** [`PDF <{IDF_TARGET_TRM_CN_URL}#riscvcpu>`__]。

docs/zh_CN/api-reference/system/power_management.rst

@@ -12,7 +12,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
 
 例如：
 
-- 对于从 APB 获得时钟频率的外设，其驱动可以要求在使用该外设时，将 APB 频率设置为 80 MHz。
+- 对于从 APB 获得时钟频率的外设，其驱动可以要求在使用该外设时，将 APB 频率设置为芯片支持的最大值。
 - RTOS 可以要求 CPU 在有任务准备开始运行时以最高配置频率工作。
 - 一些外设可能需要中断才能启用，因此其驱动也会要求禁用 Light-sleep 模式。
 
@@ -64,7 +64,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"}
+{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", esp32h4="48 MHz, 64 MHz, 或 96 MHz", esp32s31="240 MHz 或 320 MHz"}
+{IDF_TARGET_MAX_APB_FREQ: default="80 MHz", esp32c2="40 MHz", esp32c5="40 MHz", esp32c6="40 MHz", esp32c61="40 MHz", esp32h2="32 MHz", esp32h21="32 MHz", esp32h4="32 MHz", esp32p4="90 MHz", esp32s31="53.3 MHz"}
 
 应用程序可以通过获取或释放管理锁来控制电源管理算法。应用程序获取电源管理锁后，电源管理算法的操作将受到下面的限制。释放电源管理锁后，限制解除。
 
@@ -81,7 +82,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
   * - ``ESP_PM_CPU_FREQ_MAX``
     - 请求使用 :cpp:func:`esp_pm_configure` 将 CPU 频率设置为最大值。{IDF_TARGET_NAME} 可以将该值设置为 {IDF_TARGET_MAX_CPU_FREQ}。
   * - ``ESP_PM_APB_FREQ_MAX``
-    - 请求将 APB 频率设置为最大值，{IDF_TARGET_NAME} 支持的最大频率为 80 MHz。
+    - 请求将 APB 频率设置为最大值，{IDF_TARGET_NAME} 支持的最大频率为 {IDF_TARGET_MAX_APB_FREQ}。
   * - ``ESP_PM_NO_LIGHT_SLEEP``
     - 禁止自动切换至 Light-sleep 模式。
 

docs/zh_CN/api-reference/system/random.rst

@@ -3,7 +3,7 @@
 
 :link_to_translation:`en:[English]`
 
-{IDF_TARGET_RF_NAME: default="Wi-Fi 或蓝牙", esp32s2="Wi-Fi", esp32h2="蓝牙或 802.15.4 Thread/Zigbee", esp32h4="蓝牙或 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee", esp32c5="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee"}
+{IDF_TARGET_RF_NAME: default="Wi-Fi 或蓝牙", esp32s2="Wi-Fi", esp32h2="蓝牙或 802.15.4 Thread/Zigbee", esp32h4="蓝牙或 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee", esp32c5="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee", esp32s31="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee"}
 {IDF_TARGET_RF_IS: default="已启用", esp32s2="已启用"}
 
 {IDF_TARGET_NAME} 中包含一个硬件随机数发生器 (RNG)，可以调用 API :cpp:func:`esp_random` 和 :cpp:func:`esp_fill_random` 从中获取随机数值。

docs/zh_CN/api-reference/system/sleep_modes.rst

@@ -695,7 +695,7 @@ UART 输出处理
 
 :cpp:func:`esp_sleep_get_wakeup_cause` 函数可用于检测是何种唤醒源在睡眠期间被触发。
 
-.. only:: SOC_TOUCH_SENSOR_SUPPORTED
+.. only:: SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP
 
     对于触摸传感器唤醒源，可以调用函数 :cpp:func:`esp_sleep_get_touchpad_wakeup_status` 来确认触发唤醒的触摸管脚。
 

docs/zh_CN/api-reference/system/system_time.rst

@@ -35,7 +35,7 @@ RTC 定时器有以下时钟源：
 
     :not esp32c2: - ``外部 32 kHz 无源晶振``：需要将一个 32 kHz 晶振连接到外部晶振管脚。频率稳定性更高，但在 Deep-sleep 模式下电流消耗略高（比默认模式高 1 μA）。管脚连接的相关信息请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__。
 
-    - ``外部 32 kHz 有源晶振``：允许使用由外部电路产生的 32 kHz 时钟。外部时钟信号必须连接到外部振荡器管脚。输入振幅必须保证数字电路能够正确识别电平高低。测试结果表明，1.7 V 为高低电平的分界点，因此需确保输入波形的峰值大于 1.7 V，谷值小于 1.7 V。管脚连接的相关信息请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__。
+    :not esp32p4 and not esp32s31: - ``外部 32 kHz 有源晶振``：允许使用由外部电路产生的 32 kHz 时钟。外部时钟信号必须连接到外部振荡器管脚。输入振幅必须保证数字电路能够正确识别电平高低。测试结果表明，1.7 V 为高低电平的分界点，因此需确保输入波形的峰值大于 1.7 V，谷值小于 1.7 V。管脚连接的相关信息请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__。
 
     :esp32 or esp32s2 or esp32s3 or esp32c2 or esp32c3: - ``内置 8.5～17.5 MHz 振荡器（频率取决于芯片型号）的 256 分频时钟``：频率稳定性优于 ``内置 90～150 kHz RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。
 

docs/zh_CN/api-reference/system/ulp.rst

@@ -15,7 +15,7 @@ ULP（Ultra Low Power，超低功耗）协处理器可在主 CPU 处于深度睡
 
     - **ULP FSM**：基于有限状态机 (FSM) 的协处理器。适用于简单任务，相关应用需使用汇编语言或 C 语言宏编写。ESP32、ESP32-S2 和 ESP32-S3 支持此类型。
     - **ULP RISC-V**：基于 RISC-V 架构的协处理器。提供更强的计算能力和灵活性，适合运行用 C 语言编写的复杂应用。ESP32-S2 和 ESP32-S3 支持此类型。
-    - **ULP LP Core**：基于 RISC-V 架构的增强型协处理器，兼具 **ULP RISC-V** 的优势，并新增扩展内存访问、更广泛的外设访问、调试模块和中断控制器等功能。该处理器甚至可在全系统运行时工作。ESP32-C5、ESP32-C6、ESP32-P4 及后续芯片支持此类型。
+    - **ULP LP Core**：基于 RISC-V 架构的增强型协处理器，兼具 **ULP RISC-V** 的优势，并新增扩展内存访问、更广泛的外设访问、调试模块和中断控制器等功能。该处理器甚至可在全系统运行时工作。ESP32-C5、ESP32-C6、ESP32-P4、ESP32-S31 及后续芯片支持此类型。
 
     注意：ESP32-S2、ESP32-S3 等芯片同时支持 **ULP FSM** 和 **ULP RISC-V**。用户可在编译时在 menuconfig 中同时启用二者，并在运行时选择使用其中一种。
 

docs/zh_CN/api-reference/system/wdts.rst

@@ -141,13 +141,12 @@ TWDT 的默认超时时间可以通过 :menuitem:`CONFIG_ESP_TASK_WDT_TIMEOUT_S`
 
 以下配置选项控制 TWDT 配置，默认情况下全部启用：
 
-{IDF_TARGET_IDLE_TASK:default="空闲任务", esp32="CPU0 空闲任务", esp32s3="CPU0 空闲任务"}
-
 .. list::
 
     - :menuitem:`CONFIG_ESP_TASK_WDT_EN` - 启用 TWDT 功能。如果禁用此选项， TWDT 即使运行时已初始化也无法使用。
     - :menuitem:`CONFIG_ESP_TASK_WDT_INIT` - TWDT 在启动期间自动初始化。禁用此选项时，仍可以调用 :cpp:func:`esp_task_wdt_init` 在运行时初始化 TWDT。
-    - :menuitem:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` - 在启动期间将 {IDF_TARGET_IDLE_TASK}注册到 TWDT。如果禁用此选项。如果禁用此选项，仍然可以通过再次调用 :cpp:func:`esp_task_wdt_init`，或者使用 :cpp:func:`esp_task_wdt_add` 并传入通过 :cpp:func:`xTaskGetIdleTaskHandleForCore` 获取的空闲任务句柄来订阅空闲任务。
+    :not SOC_HP_CPU_HAS_MULTIPLE_CORES: - :menuitem:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` - 在启动期间将空闲任务注册到 TWDT。如果禁用此选项，仍然可以通过再次调用 :cpp:func:`esp_task_wdt_init`，或者使用 :cpp:func:`esp_task_wdt_add` 并传入通过 :cpp:func:`xTaskGetIdleTaskHandleForCore` 获取的空闲任务句柄来订阅空闲任务。
+    :SOC_HP_CPU_HAS_MULTIPLE_CORES: - :menuitem:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` - 在启动期间将 CPU0 空闲任务注册到 TWDT。如果禁用此选项，仍然可以通过再次调用 :cpp:func:`esp_task_wdt_init`，或者使用 :cpp:func:`esp_task_wdt_add` 并传入通过 :cpp:func:`xTaskGetIdleTaskHandleForCore` 获取的空闲任务句柄来订阅空闲任务。
     :SOC_HP_CPU_HAS_MULTIPLE_CORES: - :menuitem:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` - CPU1 空闲任务在启动时订阅了 TWDT。