Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-09-22 13:01:16 +03:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Add target-specific power-management frequencies and capability
conditions so later chips do not need chip-by-chip list updates.
This commit is contained in:
Marius Vikhammer
2026-09-10 15:41:03 +08:00
parent 52ea19338a
commit fec0755681
25 changed files with 173 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/en/api-reference/system/esp_function_with_shared_stack.rst
View File

@@ -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 <https://github.com/espressif/esp-idf/issues>`_.

2
docs/en/api-reference/system/freertos.rst
View File

@@ -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:

2
docs/en/api-reference/system/freertos_idf.rst
View File

@@ -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).

33
docs/en/api-reference/system/inc/power_management_esp32h4.rst
View File

@@ -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`

30
docs/en/api-reference/system/inc/power_management_esp32s31.rst
View File

@@ -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`

10
docs/en/api-reference/system/intr_alloc.rst
View File

@@ -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>`__].

7
docs/en/api-reference/system/power_management.rst
View File

@@ -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.
@@ -64,7 +64,8 @@ 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.
@@ -81,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.

2
docs/en/api-reference/system/random.rst
View File

@@ -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.

2
docs/en/api-reference/system/sleep_modes.rst
View File

@@ -695,7 +695,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.

2
docs/en/api-reference/system/system_time.rst
View File

@@ -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.

2
docs/en/api-reference/system/ulp.rst
View File

@@ -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.

5
docs/en/api-reference/system/wdts.rst
View File

@@ -141,13 +141,12 @@ The default timeout period for the TWDT is set using config item :menuitem:`CONF
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::
- :menuitem:`CONFIG_ESP_TASK_WDT_EN` - enables TWDT feature. If this option is disabled, TWDT cannot be used, even if initialized at runtime.
- :menuitem:`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`.
- :menuitem:`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: - :menuitem:`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: - :menuitem:`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: - :menuitem:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` - Subscribes CPU1 Idle task to the TWDT during startup.