Merge branch 'doc/add_wakeup_source_usage_precautions' into 'master'

change(doc): added more usage notes about PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP

Closes IDF-12166

See merge request espressif/esp-idf!36879

Author: esp-wzh

components/esp_hw_support/include/esp_sleep.h

@@ -433,8 +433,10 @@ __attribute__((deprecated("please use 'esp_sleep_enable_ext1_wakeup_io' and 'esp
  *
  * This function enables an IO pin to wake up the chip from deep sleep.
  *
- * @note This function does not modify pin configuration. The pins are
- *       configured inside esp_deep_sleep_start, immediately before entering sleep mode.
+ * @note 1.This function does not modify pin configuration. The pins are configured
+ *          inside `esp_deep_sleep_start`, immediately before entering sleep mode.
+ *       2.This function is also applicable to waking up the lightsleep when the peripheral
+ *         power domain is powered off, see PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP in menuconfig.
  *
  * @note You don't need to worry about pull-up or pull-down resistors before
  *       using this function because the ESP_SLEEP_GPIO_ENABLE_INTERNAL_RESISTORS
@@ -469,11 +471,17 @@ esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepslee
  * wakeup level, for each GPIO which is used for wakeup.
  * Then call this function to enable wakeup feature.
  *
- * @note On ESP32, GPIO wakeup source can not be used together with touch or ULP wakeup sources.
+ * @note 1. On ESP32, GPIO wakeup source can not be used together with touch or ULP wakeup sources.
+ *       2. If PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP is enabled (if target supported),
+ *          this API is unavailable since the GPIO module is powered down during sleep.
+ *          You can use `esp_deep_sleep_enable_gpio_wakeup` instead, or use EXT1 wakeup source
+ *          by `esp_sleep_enable_ext1_wakeup_io` to achieve the same function.
+ *          (Only GPIOs which have RTC functionality can be used)
  *
  * @return
  *      - ESP_OK on success
  *      - ESP_ERR_INVALID_STATE if wakeup triggers conflict
+ *      - ESP_ERR_NOT_SUPPORTED if GPIO wakeup source is not available
  */
 esp_err_t esp_sleep_enable_gpio_wakeup(void);
 
@@ -485,12 +493,15 @@ esp_err_t esp_sleep_enable_gpio_wakeup(void);
  * Wakeup from light sleep takes some time, so not every character sent
  * to the UART can be received by the application.
  *
- * @note ESP32 does not support wakeup from UART2.
+ * @note 1. ESP32 does not support wakeup from UART2.
+ *       2. If PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP is enabled (if target supported),
+ *          this API is unavailable since the UART module is powered down during sleep.
  *
  * @param uart_num  UART port to wake up from
  * @return
  *      - ESP_OK on success
  *      - ESP_ERR_INVALID_ARG if wakeup from given UART is not supported
+ *      - ESP_ERR_NOT_SUPPORTED if UART wakeup source is not available
  */
 esp_err_t esp_sleep_enable_uart_wakeup(int uart_num);
 

components/esp_hw_support/sleep_modes.c

@@ -2055,6 +2055,10 @@ esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepslee
 
 esp_err_t esp_sleep_enable_gpio_wakeup(void)
 {
+#if CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    ESP_LOGE(TAG, "%s wakeup source is not available if the peripheral power domain is powered down in sleep", "GPIO");
+    return ESP_ERR_NOT_SUPPORTED;
+#endif
 #if CONFIG_IDF_TARGET_ESP32
     if (s_config.wakeup_triggers & (RTC_TOUCH_TRIG_EN | RTC_ULP_TRIG_EN)) {
         ESP_LOGE(TAG, "Conflicting wake-up triggers: touch / ULP");
@@ -2067,6 +2071,10 @@ esp_err_t esp_sleep_enable_gpio_wakeup(void)
 
 esp_err_t esp_sleep_enable_uart_wakeup(int uart_num)
 {
+#if CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    ESP_LOGE(TAG, "%s wakeup source is not available if the peripheral power domain is powered down in sleep", "UART");
+    return ESP_ERR_NOT_SUPPORTED;
+#endif
     if (uart_num == UART_NUM_0) {
         s_config.wakeup_triggers |= RTC_UART0_TRIG_EN;
     } else if (uart_num == UART_NUM_1) {

components/esp_pm/Kconfig

@@ -146,12 +146,17 @@ menu "Power Management"
         select PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP if !SOC_CPU_IN_TOP_DOMAIN
         default n #TODO: enable by default if periph init/deinit management supported (WIFI-5252)
         help
-            If enabled, digital peripherals will be powered down in light sleep, it will reduce sleep
-            current consumption by about 100 uA. Chip will save/restore register context at sleep/wake
-            time to keep the system running. Enabling this option will increase static RAM and heap usage,
-            the actual cost depends on the peripherals you have initialized. In order to save/restore the
-            context of the necessary hardware for FreeRTOS to run, it will need at least 4.55 KB free heap
-            at sleep time. Otherwise sleep will not power down the peripherals.
+            If enabled, digital peripherals will be powered down in light sleep, all related peripherals will
+            not be available during sleep, including wake-up sources from the peripherals (For detailed availability
+            information, see the note of the corresponding wakeup source enable function).
+            The chip will automatically save/restore register context during sleep/wakeup to make the upper layer
+            user unaware of the peripheral powerdown during sleep. Enabling this option will increase static RAM and
+            heap usage but will also significantly reduce power.
+            consumption during lightsleep, the actual memory cost depends on the peripherals you have initialized,
+            for specific power consumption data in this mode, please refer to Electrical Characteristics section
+            in the chip datasheet.
+            (In order to save/restore the context of the necessary hardware for FreeRTOS to run, it will need
+            at least 4.55 KB free heap at sleep time. Otherwise sleep will not power down the peripherals.)
 
             Note1: Please use this option with caution, the current IDF does not support the retention of
             all peripherals. When the digital peripherals are powered off and a sleep and wake-up is completed,