From f33188fb35ddca4c23c092791cea19ec253e3f89 Mon Sep 17 00:00:00 2001 From: Lou Tianhao Date: Wed, 26 Jul 2023 11:01:36 +0800 Subject: [PATCH] docs(pm/sleep): rewrite_all_low_to_any_low_when_not_esp32 --- components/esp_hw_support/include/esp_sleep.h | 23 +++++++++++++------ docs/en/api-reference/system/sleep_modes.rst | 23 +++++++++++++++++-- .../api-reference/system/sleep_modes.rst | 23 +++++++++++++++++-- 3 files changed, 58 insertions(+), 11 deletions(-) diff --git a/components/esp_hw_support/include/esp_sleep.h b/components/esp_hw_support/include/esp_sleep.h index f0f3f26ab9..1456eca80c 100644 --- a/components/esp_hw_support/include/esp_sleep.h +++ b/components/esp_hw_support/include/esp_sleep.h @@ -261,18 +261,27 @@ esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t gpio_num, int level); * @note Internal pullups and pulldowns don't work when RTC peripherals are * shut down. In this case, external resistors need to be added. * Alternatively, RTC peripherals (and pullups/pulldowns) may be - * kept enabled using esp_sleep_pd_config function. + * kept enabled using esp_sleep_pd_config function. If we turn off the + * ``RTC_PERIPH`` domain or certain chips lack the ``RTC_PERIPH`` domain, + * we will use the HOLD feature to maintain the pull-up and pull-down on + * the pins during sleep. HOLD feature will be acted on the pin internally + * before the system entering sleep, and this can further reduce power consumption. * * @param mask bit mask of GPIO numbers which will cause wakeup. Only GPIOs * which have RTC functionality can be used in this bit map. * For different SoCs, the related GPIOs are: - * - ESP32: 0, 2, 4, 12-15, 25-27, 32-39; - * - ESP32-S2: 0-21; - * - ESP32-S3: 0-21. - * - ESP32-C6: 0-7. + * - ESP32: 0, 2, 4, 12-15, 25-27, 32-39 + * - ESP32-S2: 0-21 + * - ESP32-S3: 0-21 + * - ESP32-C6: 0-7 + * - ESP32-H2: 7-14 * @param mode select logic function used to determine wakeup condition: - * - ESP_EXT1_WAKEUP_ALL_LOW: wake up when all selected GPIOs are low - * - ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high + * When target chip is ESP32: + * - ESP_EXT1_WAKEUP_ALL_LOW: wake up when all selected GPIOs are low + * - ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high + * When target chip is ESP32-S2, ESP32-S3, ESP32-C6 or ESP32-H2: + * - ESP_EXT1_WAKEUP_ANY_LOW: wake up when any of the selected GPIOs is low + * - ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high * @return * - ESP_OK on success * - ESP_ERR_INVALID_ARG if any of the selected GPIOs is not an RTC GPIO, diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index 4a922dcbd5..709aa944d9 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -84,7 +84,7 @@ RTC peripherals or RTC memories don't need to be powered on during sleep in this :cpp:func:`esp_sleep_enable_touchpad_wakeup` function can be used to enable this wakeup source. -.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP or SOC_PM_SUPPORT_EXT1_WAKEUP +.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP External Wakeup (ext0) ^^^^^^^^^^^^^^^^^^^^^^ @@ -101,20 +101,39 @@ RTC peripherals or RTC memories don't need to be powered on during sleep in this .. warning:: After waking up from sleep, the IO pad used for wakeup will be configured as RTC IO. Therefore, before using this pad as digital GPIO, users need to reconfigure it using :cpp:func:`rtc_gpio_deinit` function. +.. only:: SOC_PM_SUPPORT_EXT1_WAKEUP + External Wakeup (ext1) ^^^^^^^^^^^^^^^^^^^^^^ The RTC controller contains the logic to trigger wakeup using multiple RTC GPIOs. One of the following two logic functions can be used to trigger wakeup: + .. only:: esp32 + - wake up if any of the selected pins is high (``ESP_EXT1_WAKEUP_ANY_HIGH``) - wake up if all the selected pins are low (``ESP_EXT1_WAKEUP_ALL_LOW``) - This wakeup source is implemented by the RTC controller. As such, RTC peripherals and RTC memories can be powered down in this mode. However, if RTC peripherals are powered down, internal pullup and pulldown resistors will be disabled. To use internal pullup or pulldown resistors, request the RTC peripherals power domain to be kept on during sleep, and configure pullup/pulldown resistors using ``rtc_gpio_`` functions before entering sleep:: + .. only:: esp32s2 or esp32s3 or esp32c6 or esp32h2 + + - wake up if any of the selected pins is high (``ESP_EXT1_WAKEUP_ANY_HIGH``) + - wake up if any of the selected pins is low (``ESP_EXT1_WAKEUP_ANY_LOW``) + + This wakeup source is implemented by the RTC controller. As such, RTC peripherals and RTC memories can be powered down in this mode. However, if RTC peripherals are powered down, internal pullup and pulldown resistors will be disabled if we don't use the HOLD feature. To use internal pullup or pulldown resistors, request the RTC peripherals power domain to be kept on during sleep, and configure pullup/pulldown resistors using ``rtc_gpio_`` functions before entering sleep:: esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON); rtc_gpio_pullup_dis(gpio_num); rtc_gpio_pulldown_en(gpio_num); + If we turn off the ``RTC_PERIPH`` domain, we will use the HOLD feature to maintain the pull-up and pull-down on the pins during sleep. HOLD feature will be acted on the pin internally before the system entering sleep, and this can further reduce power consumption:: + + rtc_gpio_pullup_dis(gpio_num); + rtc_gpio_pulldown_en(gpio_num); + + If certain chips lack the ``RTC_PERIPH`` domain, we can only use the HOLD feature to maintain the pull-up and pull-down on the pins during sleep:: + + gpio_pullup_dis(gpio_num); + gpio_pulldown_en(gpio_num); + .. warning:: - To use the EXT1 wakeup, the IO pad(s) are configured as RTC IO. Therefore, before using these pads as digital GPIOs, users need to reconfigure them by calling the :cpp:func:`rtc_gpio_deinit` function. diff --git a/docs/zh_CN/api-reference/system/sleep_modes.rst b/docs/zh_CN/api-reference/system/sleep_modes.rst index 7d8753aeb6..805ff70e4e 100644 --- a/docs/zh_CN/api-reference/system/sleep_modes.rst +++ b/docs/zh_CN/api-reference/system/sleep_modes.rst @@ -84,7 +84,7 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒 可调用 :cpp:func:`esp_sleep_enable_touchpad_wakeup` 函数来启用该唤醒源。 -.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP or SOC_PM_SUPPORT_EXT1_WAKEUP +.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP 外部唤醒 (ext0) ^^^^^^^^^^^^^^^^^^^^^^ @@ -101,20 +101,39 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒 .. warning:: 从睡眠模式中唤醒后，用于唤醒的 IO pad 将被配置为 RTC IO。因此，在将该 pad 用作数字 GPIO 之前，请调用 :cpp:func:`rtc_gpio_deinit` 函数对其进行重新配置。 +.. only:: SOC_PM_SUPPORT_EXT1_WAKEUP + 外部唤醒 (ext1) ^^^^^^^^^^^^^^^^^^^^^^ RTC 控制器中包含使用多个 RTC GPIO 触发唤醒的逻辑。您可以从以下两个逻辑函数中选择其一，用于触发唤醒： + .. only:: esp32 + - 当任意一个所选管脚为高电平时唤醒(ESP_EXT1_WAKEUP_ANY_HIGH) - 当所有所选管脚为低电平时唤醒 (ESP_EXT1_WAKEUP_ALL_LOW) - 此唤醒源由 RTC 控制器实现。这种模式下的 RTC 外设和 RTC 内存可以被断电。但如果 RTC 外设被断电，内部上拉和下拉电阻将被禁用。想要使用内部上拉和下拉电阻，需要 RTC 外设电源域在睡眠期间保持开启，并在进入睡眠前使用函数 ``rtc_gpio_`` 配置上拉或下拉电阻。 + .. only:: esp32s2 or esp32s3 or esp32c6 or esp32h2 + + - 当任意一个所选管脚为高电平时唤醒(ESP_EXT1_WAKEUP_ANY_HIGH) + - 当任意一个所选管脚为低电平时唤醒(ESP_EXT1_WAKEUP_ANY_LOW) + + 此唤醒源由 RTC 控制器实现。这种模式下的 RTC 外设和 RTC 内存可以被断电。然而，如果RTC外设被断电，如果我们不使用 HOLD 功能，内部上拉和下拉电阻将被禁用。想要使用内部上拉和下拉电阻，需要 RTC 外设电源域在睡眠期间保持开启，并在进入睡眠前使用函数 ``rtc_gpio_`` 配置上拉或下拉电阻。 esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON); gpio_pullup_dis(gpio_num); gpio_pulldown_en(gpio_num); + 如果我们关闭 ``RTC_PERIPH`` 域，我们将使用 HOLD 功能在睡眠期间维持引脚上的上拉和下拉电阻。所选管脚的 HOLD 功能会在系统真正进入睡眠前被开启，这有助于进一步减小睡眠时的功耗。 + + rtc_gpio_pullup_dis(gpio_num); + rtc_gpio_pulldown_en(gpio_num); + + 如果某些芯片缺少 ``RTC_PERIPH`` 域，我们只能使用 HOLD 功能来在睡眠期间维持引脚上的上拉和下拉电阻。 + + gpio_pullup_dis(gpio_num); + gpio_pulldown_en(gpio_num); + .. warning:: - 使用 EXT1 唤醒源时，用于唤醒的 IO pad 将被配置为 RTC IO。因此，在将该 pad 用作数字 GPIO 之前，请调用 :cpp:func:`rtc_gpio_deinit` 函数对其进行重新配置。