alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'doc/power_management_esp32s2' into 'master'

Browse Source 
docs: describe power management logic for ESP32-S2, fix translation

See merge request espressif/esp-idf!10525
This commit is contained in:
Krzysztof Budzynski 2020-10-16 05:38:28 +08:00
commit 114e4c220f
6 changed files with 139 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/en/api-reference/system/inc/power_management_esp32.rst
View File

@ -1,9 +1,3 @@
ESP32 Power Management Algorithm
--------------------------------
The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is enabled. You can specify the maximum CPU frequency with either :cpp:func:`esp_pm_configure` or :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`.
+---------------+---------------------------------------+-------------------------------------+
| Max CPU | Lock Acquisition | CPU and APB Frequncies |
| Frequency Set | | |
@ -18,8 +12,8 @@ The table below shows how CPU and APB frequencies will be switched if dynamic fr
| 160 | ``ESP_PM_CPU_FREQ_MAX`` acquired | | CPU: 160 MHz |
| | | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | ``ESP_PM_CPU_FREQ_MAX`` acquired, | | CPU: 80 MHz |
| | ``ESP_PM_APB_FREQ_MAX`` not acquired | | APB: 80 MHz |
| | ``ESP_PM_APB_FREQ_MAX`` acquired, | | CPU: 80 MHz |
| | ``ESP_PM_CPU_FREQ_MAX`` not acquired | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | None | Min values for both frequencies set |
| | | with :cpp:func:`esp_pm_configure` |
@ -30,11 +24,3 @@ The table below shows how CPU and APB frequencies will be switched if dynamic fr
| | None | Min values for both frequencies set |
| | | with :cpp:func:`esp_pm_configure` |
+---------------+---------------------------------------+-------------------------------------+
If none of the locks are acquired, and light sleep is enabled in a call to :cpp:func:`esp_pm_configure`, the system will go into light sleep mode. The duration of light sleep will be determined by:
- FreeRTOS tasks blocked with finite timeouts
- Timers registered with :doc:`High resolution timer <esp_timer>` APIs
Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer elapses).

28
docs/en/api-reference/system/inc/power_management_esp32s2_and_later.rst Normal file
View File

@ -0,0 +1,28 @@
+---------------+---------------------------------------+-------------------------------------+
| Max CPU | Lock Acquisition | CPU and APB Frequncies |
| Frequency Set | | |
+---------------+---------------------------------------+-------------------------------------+
| 240 | ``ESP_PM_CPU_FREQ_MAX`` acquired | | CPU: 240 MHz |
| | | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | ``ESP_PM_APB_FREQ_MAX`` acquired, | | CPU: 80 MHz |
| | ``ESP_PM_CPU_FREQ_MAX`` not acquired | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | None | Min values for both frequencies set |
| | | with :cpp:func:`esp_pm_configure` |
+---------------+---------------------------------------+-------------------------------------+
| 160 | ``ESP_PM_CPU_FREQ_MAX`` acquired | | CPU: 160 MHz |
| | | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | ``ESP_PM_APB_FREQ_MAX`` acquired, | | CPU: 80 MHz |
| | ``ESP_PM_CPU_FREQ_MAX`` not acquired | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | None | Min values for both frequencies set |
| | | with :cpp:func:`esp_pm_configure` |
+---------------+---------------------------------------+-------------------------------------+
| 80 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 80 MHz |
| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | None | Min values for both frequencies set |
| | | with :cpp:func:`esp_pm_configure` |
+---------------+---------------------------------------+-------------------------------------+

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

@ -25,7 +25,7 @@ Power management can be enabled at compile time, using the option :ref:`CONFIG_P
Enabling power management features comes at the cost of increased interrupt latency. Extra latency depends on a number of factors, such as the CPU frequency, single/dual core mode, whether or not frequency switch needs to be done. Minimum extra latency is 0.2 us (when the CPU frequency is 240 MHz and frequency scaling is not enabled). Maximum extra latency is 40 us (when frequency scaling is enabled, and a switch from 40 MHz to 80 MHz is performed on interrupt entry).
Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an application by calling the function :cpp:func:`esp_pm_configure`. Its argument is a structure defining the frequency scaling settings, :cpp:class:`esp_pm_config_esp32_t`. In this structure, three fields need to be initialized:
Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an application by calling the function :cpp:func:`esp_pm_configure`. Its argument is a structure defining the frequency scaling settings, :cpp:class:`esp_pm_config_{IDF_TARGET_PATH_NAME}_t`. In this structure, three fields need to be initialized:
- ``max_freq_mhz``: Maximum CPU frequency in MHz, i.e., the frequency used when the ``ESP_PM_CPU_FREQ_MAX`` lock is acquired. This field will usually be set to the default CPU frequency.
- ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated.
@ -62,11 +62,27 @@ Lock Description
``ESP_PM_NO_LIGHT_SLEEP`` Disables automatic switching to light sleep.
============================ ======================================================
{IDF_TARGET_NAME} Power Management Algorithm
---------------------------------------
The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is enabled. You can specify the maximum CPU frequency with either :cpp:func:`esp_pm_configure` or :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ`.
.. only:: esp32
.. include:: inc/power_management_esp32.rst
.. only:: not esp32
.. include:: inc/power_management_esp32s2_and_later.rst
If none of the locks are acquired, and light sleep is enabled in a call to :cpp:func:`esp_pm_configure`, the system will go into light sleep mode. The duration of light sleep will be determined by:
- FreeRTOS tasks blocked with finite timeouts
- Timers registered with :doc:`High resolution timer <esp_timer>` APIs
Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer elapses).
Dynamic Frequency Scaling and Peripheral Drivers
------------------------------------------------
@ -88,30 +104,22 @@ Currently, the following peripheral drivers are aware of DFS and will use the ``
The following drivers will hold the ``ESP_PM_APB_FREQ_MAX`` lock while the driver is enabled:
- **SPI slave**: between calls to :cpp:func:`spi_slave_initialize` and :cpp:func:`spi_slave_free`.
- **Ethernet**: between calls to :cpp:func:`esp_eth_driver_install` and :cpp:func:`esp_eth_driver_uninstall`.
- **WiFi**: between calls to :cpp:func:`esp_wifi_start` and :cpp:func:`esp_wifi_stop`. If modem sleep is enabled, the lock will be released for the periods of time when radio is disabled.
- **TWAI**: between calls to :cpp:func:`twai_driver_install` and :cpp:func:`twai_driver_uninstall`.
.. list::
.. only:: esp32
- **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_LOW_POWER_CLOCK` option is set to "External 32kHz crystal".
- **SPI slave**: between calls to :cpp:func:`spi_slave_initialize` and :cpp:func:`spi_slave_free`.
- **Ethernet**: between calls to :cpp:func:`esp_eth_driver_install` and :cpp:func:`esp_eth_driver_uninstall`.
- **WiFi**: between calls to :cpp:func:`esp_wifi_start` and :cpp:func:`esp_wifi_stop`. If modem sleep is enabled, the lock will be released for the periods of time when radio is disabled.
- **TWAI**: between calls to :cpp:func:`twai_driver_install` and :cpp:func:`twai_driver_uninstall`.
:SOC_BT_SUPPORTED: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_LOW_POWER_CLOCK` option is set to "External 32kHz crystal".
The following peripheral drivers are not aware of DFS yet. Applications need to acquire/release locks themselves, when necessary:
.. only:: esp32
.. list::
- PCNT
- Sigma-delta
- Timer group
- MCPWM
.. only:: esp32s2
- PCNT
- Sigma-delta
- Timer group
:esp32: - MCPWM
API Reference
-------------

27
docs/zh_CN/api-reference/system/inc/power_management_esp32.rst
View File

@ -1 +1,26 @@
.. include:: ../../../en/api-reference/system/inc/power_management_esp32.rst
+---------------+---------------------------------------+-------------------------------------+
| CPU最高频率 | 电源管理锁获取情况 | APB 频率和 CPU 频率 |
| | | |
+---------------+---------------------------------------+-------------------------------------+
| 240 | | 获取 ``ESP_PM_CPU_FREQ_MAX`` | |
| | | 或 ``ESP_PM_APB_FREQ_MAX`` | | CPU: 240 MHz |
| | | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
| | | 为二者设置最小值 |
+---------------+---------------------------------------+-------------------------------------+
| 160 | 获取 ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 160 MHz |
| | | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | | 获取 ``ESP_PM_APB_FREQ_MAX``, | | CPU: 80 MHz |
| | | 未获得 ``ESP_PM_CPU_FREQ_MAX`` | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
| | | 为二者设置最小值 |
+---------------+---------------------------------------+-------------------------------------+
| 80 | | 获取 ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 80 MHz |
| | | 或 ``ESP_PM_APB_FREQ_MAX`` | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
| | | 为二者设置最小值 |
+---------------+---------------------------------------+-------------------------------------+

28
docs/zh_CN/api-reference/system/inc/power_management_esp32s2_and_later.rst Normal file
View File

@ -0,0 +1,28 @@
+---------------+---------------------------------------+-------------------------------------+
| CPU最高频率 | 电源管理锁获取情况 | APB 频率和 CPU 频率 |
| | | |
+---------------+---------------------------------------+-------------------------------------+
| 240 | 获取 ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 240 MHz |
| | | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | | 获取 ``ESP_PM_APB_FREQ_MAX``, | | CPU: 80 MHz |
| | | 未获得 ``ESP_PM_CPU_FREQ_MAX`` | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
| | | 为二者设置最小值 |
+---------------+---------------------------------------+-------------------------------------+
| 160 | 获取 ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 160 MHz |
| | | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | | 获取 ``ESP_PM_APB_FREQ_MAX``, | | CPU: 80 MHz |
| | | 未获得 ``ESP_PM_CPU_FREQ_MAX`` | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
| | | 为二者设置最小值 |
+---------------+---------------------------------------+-------------------------------------+
| 80 | | 获取 ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 80 MHz |
| | | 或 ``ESP_PM_APB_FREQ_MAX`` | | APB: 80 MHz |
+ +---------------------------------------+-------------------------------------+
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
| | | 为二者设置最小值 |
+---------------+---------------------------------------+-------------------------------------+

49
docs/zh_CN/api-reference/system/power_management.rst
View File

@ -25,7 +25,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
启用电源管理功能将会增加中断延迟。额外延迟与多个因素有关，例如：CPU 频率、单/双核模式、是否需要进行频率切换等。CPU 频率为 240 MHz 且未启用频率调节时，最小额外延迟为 0.2 us；如果启用频率调节，且在中断入口将频率由 40 MHz 调节至 80 MHz，则最大额外延迟为 40 us。
应用程序可以通过调用 :cpp:func:`esp_pm_configure` 函数启用动态调频 (DFS) 功能和自动 Light-sleep 模式。此函数的参数为 :cpp:class:`esp_pm_config_esp32_t`，定义了频率调节的相关设置。在此参数结构中，需要初始化下面三个字段：
应用程序可以通过调用 :cpp:func:`esp_pm_configure` 函数启用动态调频 (DFS) 功能和自动 Light-sleep 模式。此函数的参数为 :cpp:class:`esp_pm_config_{IDF_TARGET_PATH_NAME}_t`，定义了频率调节的相关设置。在此参数结构中，需要初始化下面三个字段：
- ``max_freq_mhz``：最大 CPU 频率 (MHz)，即获取 ``ESP_PM_CPU_FREQ_MAX`` 锁后所使用的频率。该字段通常设置为 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ`。
@ -47,21 +47,38 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
电源管理锁设有获取/释放计数器，如果已多次获取电源管理锁，则需要将电源管理锁释放相同次数以解除限制。
ESP32 支持下表中所述的三种电源管理锁。
{IDF_TARGET_NAME} 支持下表中所述的三种电源管理锁。
============================ ======================================================
电源管理锁 描述
============================ ======================================================
``ESP_PM_CPU_FREQ_MAX`` 请求使用 :cpp:func:`esp_pm_configure` 将 CPU 频率设置为最大值。ESP32 可以将该值设置为 80 MHz、160 MHz 或 240 MHz。
``ESP_PM_CPU_FREQ_MAX`` 请求使用 :cpp:func:`esp_pm_configure` 将 CPU 频率设置为最大值。{IDF_TARGET_NAME} 可以将该值设置为 80 MHz、160 MHz 或 240 MHz。
``ESP_PM_APB_FREQ_MAX`` 请求将 APB 频率设置为最大值，ESP32 支持的最大频率为 80 MHz。
``ESP_PM_APB_FREQ_MAX`` 请求将 APB 频率设置为最大值，{IDF_TARGET_NAME} 支持的最大频率为 80 MHz。
``ESP_PM_NO_LIGHT_SLEEP`` 禁止自动切换至 Light-sleep 模式。
============================ ======================================================
{IDF_TARGET_NAME} 电源管理算法
--------------------------------
下表列出了启用动态调频时如何切换 CPU 频率和 APB 频率。您可以使用 :cpp:func:`esp_pm_configure` 或者 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ` 指定 CPU 最大频率。
.. only:: esp32
.. include:: ../../../en/api-reference/system/inc/power_management_esp32.rst
.. include:: inc/power_management_esp32.rst
.. only:: not esp32
.. include:: inc/power_management_esp32s2_and_later.rst
如果没有获取任何管理锁，调用 :cpp:func:`esp_pm_configure` 将启动 Light-sleep 模式。 Light-sleep 模式持续时间由以下因素决定：
- 处于阻塞状态的 FreeRTOS 任务数（有限超时）
- :doc:`高分辨率定时器 <esp_timer>` API 注册的计数器数量
您也可以设置 Light-sleep 模式在最近事件（任务解除阻塞，或计时器超时）之前持续多久才唤醒芯片。
动态调频和外设驱动
------------------------------------------------
@ -83,29 +100,23 @@ ESP32 支持下表中所述的三种电源管理锁。
启用以下驱动程序时，将占用 ``ESP_PM_APB_FREQ_MAX`` 锁：
- **SPI slave**：从调用 :cpp:func:`spi_slave_initialize` 至 :cpp:func:`spi_slave_free` 期间。
- **Ethernet**：从调用 :cpp:func:`esp_eth_driver_install` 至 :cpp:func:`esp_eth_driver_uninstall` 期间。
- **WiFi**：从调用 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间。如果启用了调制解调器睡眠模式，广播关闭时将释放此管理锁。
- **TWAI**：从调用 :cpp:func:`twai_driver_install` 至 :cpp:func:`twai_driver_uninstall` 期间。
.. only:: esp32
.. list::
- **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁。
- **SPI slave**：从调用 :cpp:func:`spi_slave_initialize` 至 :cpp:func:`spi_slave_free` 期间。
- **Ethernet**：从调用 :cpp:func:`esp_eth_driver_install` 至 :cpp:func:`esp_eth_driver_uninstall` 期间。
- **WiFi**：从调用 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间。如果启用了调制解调器睡眠模式，广播关闭时将释放此管理锁。
- **TWAI**：从调用 :cpp:func:`twai_driver_install` 至 :cpp:func:`twai_driver_uninstall` 期间。
:SOC_BT_SUPPORTED: - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁。
以下外设驱动程序无法感知动态调频，应用程序需自己获取/释放管理锁：
.. only:: esp32
- PCNT
- Sigma-delta
- Timer group
- MCPWM
.. only:: esp32s2
.. list::
- PCNT
- Sigma-delta
- Timer group
:esp32: - MCPWM
API 参考