From ff41b52fc664889dba7e7341a41f1b9b7c9d7662 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Thu, 10 Sep 2026 15:41:03 +0800 Subject: [PATCH] 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/docs_not_updated/esp32h4.txt | 7 ---- .../system/esp_function_with_shared_stack.rst | 5 ++- docs/en/api-reference/system/freertos.rst | 2 +- docs/en/api-reference/system/freertos_idf.rst | 2 +- .../system/inc/power_management_esp32h4.rst | 33 ++++++++++++++++ .../system/inc/power_management_esp32s31.rst | 30 +++++++++++++- docs/en/api-reference/system/intr_alloc.rst | 10 ++++- .../api-reference/system/power_management.rst | 8 ++-- docs/en/api-reference/system/random.rst | 2 +- docs/en/api-reference/system/sleep_modes.rst | 2 +- docs/en/api-reference/system/system_time.rst | 2 +- docs/en/api-reference/system/ulp.rst | 2 +- docs/en/api-reference/system/wdts.rst | 5 +-- .../system/esp_function_with_shared_stack.rst | 5 ++- docs/zh_CN/api-reference/system/freertos.rst | 2 +- .../api-reference/system/freertos_idf.rst | 2 +- .../system/inc/power_management_esp32h4.rst | 39 +++++++++++++++++-- .../system/inc/power_management_esp32s31.rst | 30 +++++++++++++- .../zh_CN/api-reference/system/intr_alloc.rst | 10 ++++- .../api-reference/system/power_management.rst | 10 +++-- docs/zh_CN/api-reference/system/random.rst | 2 +- .../api-reference/system/sleep_modes.rst | 2 +- .../api-reference/system/system_time.rst | 2 +- docs/zh_CN/api-reference/system/ulp.rst | 2 +- docs/zh_CN/api-reference/system/wdts.rst | 5 +-- 25 files changed, 176 insertions(+), 45 deletions(-) diff --git a/docs/docs_not_updated/esp32h4.txt b/docs/docs_not_updated/esp32h4.txt index bf37ad8344c..ff2344df35a 100644 --- a/docs/docs_not_updated/esp32h4.txt +++ b/docs/docs_not_updated/esp32h4.txt @@ -120,13 +120,6 @@ api-reference/peripherals/spi_flash/spi_flash_override_driver.rst api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst api-reference/peripherals/sdmmc_host.rst -api-reference/system/mm_sync.rst -api-reference/system/mm.rst -api-reference/system/esp_https_ota.rst -api-reference/system/sleep_modes.rst -api-reference/system/ota.rst -api-reference/system/inc/power_management_esp32h4.rst -api-reference/system/power_management.rst security/tee/index.rst security/tee/tee-advanced.rst security/tee/tee-sec-storage.rst diff --git a/docs/en/api-reference/system/esp_function_with_shared_stack.rst b/docs/en/api-reference/system/esp_function_with_shared_stack.rst index dc548a10bd6..d96a04aae9b 100644 --- a/docs/en/api-reference/system/esp_function_with_shared_stack.rst +++ b/docs/en/api-reference/system/esp_function_with_shared_stack.rst @@ -15,8 +15,9 @@ A given function can be executed with a user-allocated stack space which is inde .. list:: - Use thread-local storage - :esp32p4: - Use the floating-point unit - :esp32p4: - Use the AI co-processor + :SOC_CPU_HAS_FPU: - Use the floating-point unit + :SOC_CPU_HAS_PIE: - Use the AI co-processor + :SOC_CPU_HAS_DSP: - Use the DSP co-processor - Call vTaskDelete(NULL) to delete the currently running task Furthermore, backtraces will be wrong when called from the function running on the shared stack or any of its callees. The limitations are quite severe, so that we might deprecate :cpp:func:`esp_execute_shared_stack_function` in the future. If you have any use case which can only be implemented using :cpp:func:`esp_execute_shared_stack_function`, please open a `GitHub Issue `_. diff --git a/docs/en/api-reference/system/freertos.rst b/docs/en/api-reference/system/freertos.rst index 61ecb7cf105..bfaf8e3118a 100644 --- a/docs/en/api-reference/system/freertos.rst +++ b/docs/en/api-reference/system/freertos.rst @@ -24,7 +24,7 @@ ESP-IDF FreeRTOS is a FreeRTOS implementation based on Vanilla FreeRTOS v10.5.1, ESP-IDF FreeRTOS is currently the default FreeRTOS implementation for ESP-IDF. -.. only:: not esp32p4 and not esp32h4 +.. only:: not (CONFIG_IDF_TARGET_ARCH_RISCV and SOC_HP_CPU_HAS_MULTIPLE_CORES) .. _amazon_smp_freertos: diff --git a/docs/en/api-reference/system/freertos_idf.rst b/docs/en/api-reference/system/freertos_idf.rst index f28f8b4f268..b8231bb0772 100644 --- a/docs/en/api-reference/system/freertos_idf.rst +++ b/docs/en/api-reference/system/freertos_idf.rst @@ -47,7 +47,7 @@ Although an SMP system allows threads to switch cores, there are scenarios where SMP on an ESP Target ^^^^^^^^^^^^^^^^^^^^ -ESP targets such as ESP32, ESP32-S3, ESP32-P4 and ESP32-H4 are dual-core SMP SoCs. These targets have the following hardware features that make them SMP-capable: +ESP targets with dual HP cores have the following hardware features that make them SMP-capable: - Two identical cores are known as Core 0 and Core 1. This means that the execution of a piece of code is identical regardless of which core it runs on. - Symmetric memory (with some small exceptions). diff --git a/docs/en/api-reference/system/inc/power_management_esp32h4.rst b/docs/en/api-reference/system/inc/power_management_esp32h4.rst index 754feffa033..861c5e8f746 100644 --- a/docs/en/api-reference/system/inc/power_management_esp32h4.rst +++ b/docs/en/api-reference/system/inc/power_management_esp32h4.rst @@ -5,3 +5,36 @@ * - Max CPU Frequency Set - Lock Acquisition - CPU and APB Frequencies + * - :rspan:`2` 96 + - ``ESP_PM_CPU_FREQ_MAX`` acquired + - + - CPU: 96 MHz + - APB: 32 MHz + * - ``ESP_PM_APB_FREQ_MAX`` acquired, ``ESP_PM_CPU_FREQ_MAX`` not acquired + - + - CPU: 32 MHz + - APB: 32 MHz + * - None + - Min values for both frequencies set with :cpp:func:`esp_pm_configure` + * - :rspan:`2` 64 + - ``ESP_PM_CPU_FREQ_MAX`` acquired + - + - CPU: 64 MHz + - APB: 32 MHz + * - ``ESP_PM_APB_FREQ_MAX`` acquired, ``ESP_PM_CPU_FREQ_MAX`` not acquired + - + - CPU: 32 MHz + - APB: 32 MHz + * - None + - Min values for both frequencies set with :cpp:func:`esp_pm_configure` + * - :rspan:`2` 48 + - ``ESP_PM_CPU_FREQ_MAX`` acquired + - + - CPU: 48 MHz + - APB: 24 MHz + * - ``ESP_PM_APB_FREQ_MAX`` acquired, ``ESP_PM_CPU_FREQ_MAX`` not acquired + - + - CPU: 32 MHz + - APB: 32 MHz + * - None + - Min values for both frequencies set with :cpp:func:`esp_pm_configure` diff --git a/docs/en/api-reference/system/inc/power_management_esp32s31.rst b/docs/en/api-reference/system/inc/power_management_esp32s31.rst index 94c835a6e45..43b38bec2f5 100644 --- a/docs/en/api-reference/system/inc/power_management_esp32s31.rst +++ b/docs/en/api-reference/system/inc/power_management_esp32s31.rst @@ -1,3 +1,29 @@ -.. note:: - To be updated. +.. flat-table:: + :widths: 1 3 3 + + * - Max CPU Frequency Set + - Lock Acquisition + - CPU and APB Frequencies + * - :rspan:`2` 320 + - ``ESP_PM_CPU_FREQ_MAX`` acquired + - + - CPU: 320 MHz + - APB: 53.3 MHz + * - ``ESP_PM_APB_FREQ_MAX`` acquired, ``ESP_PM_CPU_FREQ_MAX`` not acquired + - + - CPU: 53.3 MHz + - APB: 53.3 MHz + * - None + - Min values for both frequencies set with :cpp:func:`esp_pm_configure` + * - :rspan:`2` 240 + - ``ESP_PM_CPU_FREQ_MAX`` acquired + - + - CPU: 240 MHz + - APB: 40 MHz + * - ``ESP_PM_APB_FREQ_MAX`` acquired, ``ESP_PM_CPU_FREQ_MAX`` not acquired + - + - CPU: 40 MHz + - APB: 40 MHz + * - None + - Min values for both frequencies set with :cpp:func:`esp_pm_configure` diff --git a/docs/en/api-reference/system/intr_alloc.rst b/docs/en/api-reference/system/intr_alloc.rst index ea66c023dac..e734e2a0446 100644 --- a/docs/en/api-reference/system/intr_alloc.rst +++ b/docs/en/api-reference/system/intr_alloc.rst @@ -22,10 +22,18 @@ Overview The {IDF_TARGET_NAME} has one core, with 28 external asynchronous interrupts. Each interrupt's priority is independently programmable. In addition, there are also 4 core local interrupt sources (CLINT). See **{IDF_TARGET_NAME} Technical Reference Manual** [`PDF <{IDF_TARGET_TRM_EN_URL}#riscvcpu>`__] for more details. -.. only:: esp32p4 or esp32h4 +.. only:: esp32p4 The {IDF_TARGET_NAME} has two cores, with 32 external asynchronous interrupts each. Each interrupt's priority is independently programmable. In addition, there are also 3 core local interrupt sources (CLINT) on each core. See **{IDF_TARGET_NAME} Technical Reference Manual** [`PDF <{IDF_TARGET_TRM_EN_URL}#riscvcpu>`__] for more details. +.. only:: esp32h4 + + The {IDF_TARGET_NAME} has two cores, with 32 external asynchronous interrupts each. Each interrupt's priority is independently programmable. In addition, there are also 2 core local interrupt sources (CLINT) on each core. See **{IDF_TARGET_NAME} Technical Reference Manual** [`PDF <{IDF_TARGET_TRM_EN_URL}#riscvcpu>`__] for more details. + +.. only:: esp32s31 + + The {IDF_TARGET_NAME} has two cores, with 32 external asynchronous interrupts each. Each interrupt's priority is independently programmable. See **{IDF_TARGET_NAME} Technical Reference Manual** [`PDF <{IDF_TARGET_TRM_EN_URL}#riscvcpu>`__] for more details. + .. only:: esp32c5 or esp32c61 The {IDF_TARGET_NAME} has one core, with 32 external asynchronous interrupts. Each interrupt's priority is independently programmable. In addition, there are also 3 core local interrupt sources (CLINT). For details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **High-Performance CPU** [`PDF <{IDF_TARGET_TRM_EN_URL}#riscvcpu>`__]. diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index aabcb3b0326..f8cb54b3913 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -12,7 +12,7 @@ Application components can express their requirements by creating and acquiring For example: -- Driver for a peripheral clocked from APB can request the APB frequency to be set to 80 MHz while the peripheral is used. +- Driver for a peripheral clocked from APB can request the APB frequency to be set to the maximum supported value while the peripheral is used. - RTOS can request the CPU to run at the highest configured frequency while there are tasks ready to run. - A peripheral driver may need interrupts to be enabled, which means it has to request disabling Light-sleep. @@ -63,7 +63,9 @@ 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"} + +{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", esp32h4="48 MHz, 64 MHz, or 96 MHz", esp32s31="240 MHz or 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"} 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. @@ -80,7 +82,7 @@ Power management locks have acquire/release counters. If the lock has been acqui * - ``ESP_PM_CPU_FREQ_MAX`` - Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For {IDF_TARGET_NAME}, this value can be set to {IDF_TARGET_MAX_CPU_FREQ}. * - ``ESP_PM_APB_FREQ_MAX`` - - Requests the APB frequency to be at the maximum supported value. For {IDF_TARGET_NAME}, this is 80 MHz. + - Requests the APB frequency to be at the maximum supported value. For {IDF_TARGET_NAME}, this is {IDF_TARGET_MAX_APB_FREQ}. * - ``ESP_PM_NO_LIGHT_SLEEP`` - Disables automatic switching to Light-sleep. diff --git a/docs/en/api-reference/system/random.rst b/docs/en/api-reference/system/random.rst index 679946935b7..a03df57eb7f 100644 --- a/docs/en/api-reference/system/random.rst +++ b/docs/en/api-reference/system/random.rst @@ -3,7 +3,7 @@ Random Number Generation :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi", esp32h2="Bluetooth or 802.15.4 Thread/Zigbee", esp32h4="Bluetooth or 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee", esp32c5="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee"} +{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi", esp32h2="Bluetooth or 802.15.4 Thread/Zigbee", esp32h4="Bluetooth or 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee", esp32c5="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee", esp32s31="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee"} {IDF_TARGET_RF_IS: default="are", esp32s2="is"} {IDF_TARGET_NAME} contains a hardware random number generator (RNG). You can use the APIs :cpp:func:`esp_random` and :cpp:func:`esp_fill_random` to obtained random values from it. diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index bd26f165f1a..cad65721d29 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -680,7 +680,7 @@ Checking Sleep Wakeup Cause :cpp:func:`esp_sleep_get_wakeup_cause` function can be used to check which wakeup source has triggered wakeup from sleep mode. -.. only:: SOC_TOUCH_SENSOR_SUPPORTED +.. only:: SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP For touchpad, it is possible to identify which touch pin has caused wakeup using :cpp:func:`esp_sleep_get_touchpad_wakeup_status` functions. diff --git a/docs/en/api-reference/system/system_time.rst b/docs/en/api-reference/system/system_time.rst index c368649dec2..4be74d3f8a9 100644 --- a/docs/en/api-reference/system/system_time.rst +++ b/docs/en/api-reference/system/system_time.rst @@ -35,7 +35,7 @@ The RTC timer has the following clock sources: :not esp32c2: - ``External 32 kHz crystal``: Requires a 32 kHz crystal to be connected to the external crystal pins. This source provides a better frequency stability at the expense of a slightly higher (by 1 μA) Deep-sleep current consumption. Refer to the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__ for information on which pins to connect to. - - ``External 32 kHz oscillator``: Allows using a 32 kHz clock generated by an external circuit. The external clock signal must be connected to the external oscillator pin. The input amplitude must ensure that the digital circuit can correctly distinguish between logic high and low levels. Test results show that 1.7 V is the threshold between high and low levels. Therefore, make sure the input waveform has a peak value greater than 1.7 V and a minimum value lower than 1.7 V. For details on pin connections, please refer to the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__. + :not esp32p4 and not esp32s31: - ``External 32 kHz oscillator``: Allows using a 32 kHz clock generated by an external circuit. The external clock signal must be connected to the external oscillator pin. The input amplitude must ensure that the digital circuit can correctly distinguish between logic high and low levels. Test results show that 1.7 V is the threshold between high and low levels. Therefore, make sure the input waveform has a peak value greater than 1.7 V and a minimum value lower than 1.7 V. For details on pin connections, please refer to the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__. :esp32 or esp32s2 or esp32s3 or esp32c2 or esp32c3: - ``Internal 8.5–17.5 MHz oscillator (depending on chip), divided by 256``: Provides better frequency stability than the ``Internal 90–150 kHz RC oscillator`` at the expense of a higher (by 5 μA) Deep-sleep current consumption. It also does not require external components. diff --git a/docs/en/api-reference/system/ulp.rst b/docs/en/api-reference/system/ulp.rst index 25993ed8e6f..4e20dc593d9 100644 --- a/docs/en/api-reference/system/ulp.rst +++ b/docs/en/api-reference/system/ulp.rst @@ -15,7 +15,7 @@ The Ultra Low Power (ULP) coprocessor is designed to perform tasks while the mai - **ULP FSM**: A finite state machine (FSM) based ULP coprocessor. It is suitable for simple tasks, as applications for this type must be written using assembly language or C macros. This type is supported by ESP32, ESP32-S2, and ESP32-S3. - **ULP RISC-V**: A RISC-V based ULP coprocessor. It offers enhanced computational capabilities and flexibility, making it suitable for more complex applications written in C. This type is supported by ESP32-S2 and ESP32-S3. - - **ULP LP Core**: A RISC-V based ULP coprocessor that combines the advantages of the **ULP RISC-V** type with additional features, such as extended memory access, broader peripheral access, a debug module, and an interrupt controller. This coprocessor is capable of operating even when the entire system is active. This type is supported by ESP32-C5, ESP32-C6, ESP32-P4, and upcoming chips. + - **ULP LP Core**: A RISC-V based ULP coprocessor that combines the advantages of the **ULP RISC-V** type with additional features, such as extended memory access, broader peripheral access, a debug module, and an interrupt controller. This coprocessor is capable of operating even when the entire system is active. This type is supported by ESP32-C5, ESP32-C6, ESP32-P4, ESP32-S31, and upcoming chips. NOTE: Chips like ESP32-S2 and ESP32-S3 support both **ULP FSM** and **ULP RISC-V**. User can enable both of them in menuconfig at compile time, and choose which one to use at run time. diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index 8fdcc100e0a..43ec703e428 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -141,13 +141,12 @@ The default timeout period for the TWDT is set using config item :ref:`CONFIG_ES The following config options control TWDT configuration. They are all enabled by default: -{IDF_TARGET_IDLE_TASK:default="Idle task", esp32="CPU0 Idle task", esp32s3="CPU0 Idle task", esp32p4="CPU0 Idle task"} - .. list:: - :ref:`CONFIG_ESP_TASK_WDT_EN` - enables TWDT feature. If this option is disabled, TWDT cannot be used, even if initialized at runtime. - :ref:`CONFIG_ESP_TASK_WDT_INIT` - initializes the TWDT automatically during startup. If this option is disabled, it is still possible to initialize the Task WDT at runtime by calling :cpp:func:`esp_task_wdt_init`. - - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` - subscribes {IDF_TARGET_IDLE_TASK} to the TWDT during startup. If this option is disabled, it is still possible to subscribe the idle task by calling :cpp:func:`esp_task_wdt_init` again, or by using :cpp:func:`esp_task_wdt_add` and passing the idle task handle obtained via :cpp:func:`xTaskGetIdleTaskHandleForCore`. + :not SOC_HP_CPU_HAS_MULTIPLE_CORES: - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` - subscribes Idle task to the TWDT during startup. If this option is disabled, it is still possible to subscribe the idle task by calling :cpp:func:`esp_task_wdt_init` again, or by using :cpp:func:`esp_task_wdt_add` and passing the idle task handle obtained via :cpp:func:`xTaskGetIdleTaskHandleForCore`. + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` - subscribes CPU0 Idle task to the TWDT during startup. If this option is disabled, it is still possible to subscribe the idle task by calling :cpp:func:`esp_task_wdt_init` again, or by using :cpp:func:`esp_task_wdt_add` and passing the idle task handle obtained via :cpp:func:`xTaskGetIdleTaskHandleForCore`. :SOC_HP_CPU_HAS_MULTIPLE_CORES: - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` - Subscribes CPU1 Idle task to the TWDT during startup. diff --git a/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst b/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst index 421407e6580..e1e8f5b4ea2 100644 --- a/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst +++ b/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 `_。 diff --git a/docs/zh_CN/api-reference/system/freertos.rst b/docs/zh_CN/api-reference/system/freertos.rst index b6b62e08afd..1d062074ef8 100644 --- a/docs/zh_CN/api-reference/system/freertos.rst +++ b/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: diff --git a/docs/zh_CN/api-reference/system/freertos_idf.rst b/docs/zh_CN/api-reference/system/freertos_idf.rst index 4b0a3e539f0..49706845089 100644 --- a/docs/zh_CN/api-reference/system/freertos_idf.rst +++ b/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。代码段无论在哪个核上运行，都有相同的执行效果。 - 具有对称内存（除了少数例外情况）。 diff --git a/docs/zh_CN/api-reference/system/inc/power_management_esp32h4.rst b/docs/zh_CN/api-reference/system/inc/power_management_esp32h4.rst index 754feffa033..293eaa2a168 100644 --- a/docs/zh_CN/api-reference/system/inc/power_management_esp32h4.rst +++ b/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` 为二者设置最小值 diff --git a/docs/zh_CN/api-reference/system/inc/power_management_esp32s31.rst b/docs/zh_CN/api-reference/system/inc/power_management_esp32s31.rst index 94c835a6e45..78d991998ea 100644 --- a/docs/zh_CN/api-reference/system/inc/power_management_esp32s31.rst +++ b/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` 为二者设置最小值 diff --git a/docs/zh_CN/api-reference/system/intr_alloc.rst b/docs/zh_CN/api-reference/system/intr_alloc.rst index 850d1ee2862..6b9497c11d5 100644 --- a/docs/zh_CN/api-reference/system/intr_alloc.rst +++ b/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>`__]。 diff --git a/docs/zh_CN/api-reference/system/power_management.rst b/docs/zh_CN/api-reference/system/power_management.rst index a02f8fde083..0709d80f2df 100644 --- a/docs/zh_CN/api-reference/system/power_management.rst +++ b/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 模式。 @@ -61,8 +61,10 @@ 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"} 应用程序可以通过获取或释放管理锁来控制电源管理算法。应用程序获取电源管理锁后，电源管理算法的操作将受到下面的限制。释放电源管理锁后，限制解除。 @@ -79,7 +81,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 模式。 diff --git a/docs/zh_CN/api-reference/system/random.rst b/docs/zh_CN/api-reference/system/random.rst index d825f639ee3..c5fbd44e8b7 100644 --- a/docs/zh_CN/api-reference/system/random.rst +++ b/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` 从中获取随机数值。 diff --git a/docs/zh_CN/api-reference/system/sleep_modes.rst b/docs/zh_CN/api-reference/system/sleep_modes.rst index 9eb1f9ae29a..f3d9804f2f8 100644 --- a/docs/zh_CN/api-reference/system/sleep_modes.rst +++ b/docs/zh_CN/api-reference/system/sleep_modes.rst @@ -680,7 +680,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` 来确认触发唤醒的触摸管脚。 diff --git a/docs/zh_CN/api-reference/system/system_time.rst b/docs/zh_CN/api-reference/system/system_time.rst index dc2bf1035da..32d6a7fe52e 100644 --- a/docs/zh_CN/api-reference/system/system_time.rst +++ b/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）。 diff --git a/docs/zh_CN/api-reference/system/ulp.rst b/docs/zh_CN/api-reference/system/ulp.rst index 08c4a8e0763..7708b3dd063 100644 --- a/docs/zh_CN/api-reference/system/ulp.rst +++ b/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 中同时启用二者，并在运行时选择使用其中一种。 diff --git a/docs/zh_CN/api-reference/system/wdts.rst b/docs/zh_CN/api-reference/system/wdts.rst index b1bd2d7f1ce..239d0926bc0 100644 --- a/docs/zh_CN/api-reference/system/wdts.rst +++ b/docs/zh_CN/api-reference/system/wdts.rst @@ -141,13 +141,12 @@ TWDT 的默认超时时间可以通过 :ref:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` 配 以下配置选项控制 TWDT 配置，默认情况下全部启用： -{IDF_TARGET_IDLE_TASK:default="空闲任务", esp32="CPU0 空闲任务", esp32s3="CPU0 空闲任务"} - .. list:: - :ref:`CONFIG_ESP_TASK_WDT_EN` - 启用 TWDT 功能。如果禁用此选项， TWDT 即使运行时已初始化也无法使用。 - :ref:`CONFIG_ESP_TASK_WDT_INIT` - TWDT 在启动期间自动初始化。禁用此选项时，仍可以调用 :cpp:func:`esp_task_wdt_init` 在运行时初始化 TWDT。 - - :ref:`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: - :ref:`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: - :ref:`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: - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` - CPU1 空闲任务在启动时订阅了 TWDT。