Merge branch 'feat/sub_power_modes_docs' into 'master'

sleep_modes: add docs and test app for sub power modes on S2, S3, C2, C3.

See merge request espressif/esp-idf!23142

components/esp_hw_support/.build-test-rules.yml

@@ -17,19 +17,31 @@ components/esp_hw_support/test_apps/etm:
 components/esp_hw_support/test_apps/host_test_linux:
   enable:
     - if: IDF_TARGET == "linux"
+
 components/esp_hw_support/test_apps/mspi:
   disable:
     - if: IDF_TARGET != "esp32s3"
+
 components/esp_hw_support/test_apps/mspi_psram_with_dfs:
   disable:
     - if: IDF_TARGET != "esp32s3"
 
+components/esp_hw_support/test_apps/rtc_8md256:
+  disable:
+    - if: SOC_RTC_SLOW_CLK_SUPPORT_RC_FAST_D256 != 1
+
 components/esp_hw_support/test_apps/rtc_clk:
   disable:
     - if: IDF_TARGET in ["esp32c6", "esp32h2"]
       temporary: true
       reason: Unsupported on C6 for now. TODO IDF-5645
 
+components/esp_hw_support/test_apps/rtc_power_modes:
+  enable:
+    - if: IDF_TARGET in ["esp32s2", "esp32s3", "esp32c2", "esp32c3"]
+      temporary: true
+      reason: the other targets are not tested yet
+
 components/esp_hw_support/test_apps/security_support/esp_hw_support_unity_tests:
   disable_test:
     - if: IDF_TARGET in ["esp32h2"]

components/esp_hw_support/test_apps/rtc_power_modes/README.md

@@ -0,0 +1,13 @@
+| Supported Targets | ESP32-C2 | ESP32-C3 | ESP32-S2 | ESP32-S3 |
+| ----------------- | -------- | -------- | -------- | -------- |
+
+# RTC power test
+
+This test app is to enter different sub power modes we have, so that the power consumption under different power modes can be measured.
+
+See the api-reference/system/sleep_modes chapter in the Programming Guide for the details of these power modes.
+
+(ESP32 to be added)
+Changes:
+- ESP32: DS 8M, DS Default, LS 8M, LS Default
+- dbg_atten_slp NODROP when using INT8M as slow src on ESP32

components/esp_hw_support/test_apps/rtc_power_modes/main/test_rtc_power.c

@@ -17,6 +17,7 @@
 #include "driver/ledc.h"
 #include "soc/rtc.h"
 #include "esp_private/esp_sleep_internal.h"
+#include "sdkconfig.h"
 
 static const char TAG[] = "rtc_power";
 
@@ -27,35 +28,41 @@ static void test_deepsleep(void)
     esp_deep_sleep_start();
 }
 
-TEST_CASE("Power Test: Deepsleep (with ADC/TSEN in monitor)", "[pm]")
+// Deepsleep (with 8MD256 or ADC/TSEN in monitor)
+TEST_CASE("Power Test: DSLP_8MD256", "[pm]")
 {
-    rtc_dig_clk8m_disable();    //This is workaround for bootloader not disable 8M as digital clock source
-
     esp_sleep_enable_adc_tsens_monitor(true);
-    test_deepsleep();
-}
-
-TEST_CASE("Power Test: Deepsleep (default)", "[pm]")
-{
-    rtc_dig_clk8m_disable();    //This is workaround for bootloader not disable 8M as digital clock source
 
     test_deepsleep();
 }
 
-TEST_CASE("Power Test: Deepsleep (ultra-low power)", "[pm]")
+#if !CONFIG_RTC_CLK_SRC_INT_8MD256
+// Deepsleep (default)
+TEST_CASE("Power Test: DSLP_DEFAULT", "[pm]")
 {
-    rtc_dig_clk8m_disable();    //This is workaround for bootloader not disable 8M as digital clock source
+    esp_sleep_enable_adc_tsens_monitor(false); //This is the default option. Add this line to avoid the case executing this case directly after the DSLP_8MD256 case.
+
+    test_deepsleep();
+}
+
+// Deepsleep (ultra-low power)
+TEST_CASE("Power Test: DSLP_ULTRA_LOW", "[pm]")
+{
+    esp_sleep_enable_adc_tsens_monitor(false); //This is the default option. Add this line to avoid the case executing this case directly after the DSLP_8MD256 case.
 
     extern void rtc_sleep_enable_ultra_low(bool);
     rtc_sleep_enable_ultra_low(true);
+
     test_deepsleep();
 }
+#endif //!CONFIG_RTC_CLK_SRC_INT_8MD256
 
 static void test_lightsleep(void)
 {
     esp_sleep_enable_timer_wakeup(2000000);
+    int count = 5;
 
-    while (true) {
+    while (count--) {
         printf("Entering light sleep\n");
         /* To make sure the complete line is printed before entering sleep mode,
          * need to wait until UART TX FIFO is empty:
@@ -81,40 +88,54 @@ static void test_lightsleep(void)
     }
 }
 
-TEST_CASE("Power Test: Lightsleep (XTAL 40M)", "[pm]")
+// Lightsleep (XTAL 40M)
+TEST_CASE("Power Test: LSLP_XTAL_FPU", "[pm]")
 {
-    rtc_dig_clk8m_disable();    //This is workaround for bootloader not disable 8M as digital clock source
-
     esp_sleep_pd_config(ESP_PD_DOMAIN_XTAL, ESP_PD_OPTION_ON);
+
     test_lightsleep();
 }
 
-TEST_CASE("Power Test: Lightsleep (8M by digital)", "[pm]")
+// Lightsleep (8M by digital)
+TEST_CASE("Power Test: LSLP_LEDC8M", "[pm]")
 {
-    rtc_dig_clk8m_disable();    //This is workaround for bootloader not disable 8M as digital clock source
-
     ledc_timer_config_t config = {
         .speed_mode = LEDC_LOW_SPEED_MODE,
         .duty_resolution = LEDC_TIMER_12_BIT,
         .timer_num = 0,
-        .freq_hz = 2 * 1000,
+        .freq_hz = 200,
         .clk_cfg = LEDC_USE_RC_FAST_CLK,
     };
     ledc_timer_config(&config);
+
     test_lightsleep();
 }
 
-TEST_CASE("Power Test: Lightsleep (with ADC/TSEN in monitor)", "[pm]")
+// Lightsleep (8MD256)
+TEST_CASE("Power Test: LSLP_8MD256", "[pm]")
 {
-    rtc_dig_clk8m_disable();    //This is workaround for bootloader not disable 8M as digital clock source
+#if !CONFIG_RTC_CLK_SRC_INT_8MD256
+    TEST_FAIL_MESSAGE("This mode requires Kconfig option CONFIG_RTC_CLK_SRC_INT_8MD256 selected");
+#endif
 
+    test_lightsleep();
+}
+
+#if !CONFIG_RTC_CLK_SRC_INT_8MD256
+// Lightsleep (with ADC/TSEN in monitor)
+TEST_CASE("Power Test: LSLP_ADC_TSENS", "[pm]")
+{
     extern void esp_sleep_enable_adc_tsens_monitor(bool);
     esp_sleep_enable_adc_tsens_monitor(true);
+
     test_lightsleep();
 }
 
-TEST_CASE("Power Test: Lightsleep (default)", "[pm]")
+// Lightsleep (default)
+TEST_CASE("Power Test: LSLP_DEFAULT", "[pm]")
 {
-    rtc_dig_clk8m_disable();    //This is workaround for bootloader not disable 8M as digital clock source
+    esp_sleep_enable_adc_tsens_monitor(false); //This is the default option. Add this line to avoid the case executing this case directly after the DSLP_8MD256 case.
+
     test_lightsleep();
 }
+#endif //!CONFIG_RTC_CLK_SRC_INT_8MD256

components/esp_system/.build-test-rules.yml

@@ -7,13 +7,3 @@ components/esp_system/test_apps/esp_system_unity_tests:
 components/esp_system/test_apps/linux_apis:
   enable:
     - if: IDF_TARGET == "linux"
-
-components/esp_system/test_apps/rtc_8md256:
-  disable:
-    - if: SOC_RTC_SLOW_CLK_SUPPORT_RC_FAST_D256 != 1
-
-components/esp_system/test_apps/rtc_power_modes:
-  enable:
-    - if: IDF_TARGET == "esp32s3"
-      temporary: true
-      reason: the other targets are not tested yet

components/esp_system/test_apps/rtc_power_modes/README.md

@@ -1,19 +0,0 @@
-| Supported Targets | ESP32-S3 |
-| ----------------- | -------- |
-
-# RTC power test
-
-This test app is to enter 7 different sub power modes we have, so that the power consumption under different power modes can be measured.
-
-Currently there are 6 sub power modes, 3 for deepsleep and 3 for lightsleep. Show as below (priority from high to low).
-
-## Deepsleep
-1. Mode for ADC/Temp Sensor in monitor mode (ULP). To enable this mode, call `esp_sleep_enable_adc_tsens_monitor`.
-2. Default mode.
-3. Ultra low power mode. To enable this mode, call `rtc_sleep_enable_ultra_low`. Note if mode 1 has higher priority than this.
-
-## Lightsleep
-1. Mode for using 40 MHz XTAL in lightsleep. To enable this mode, call `esp_sleep_pd_config(ESP_PD_DOMAIN_XTAL, ESP_PD_OPTION_ON)`.
-2. Mode for using 8M clock by digital system (peripherals). To enable this mode, initialize LEDC with 8M clock source.
-3. Mode for ADC/Temp Sensor in monitor mode (ULP). To enable this mdoe, call `esp_sleep_enable_adc_tsens_monitor`.
-4. Default mode.

docs/en/api-reference/system/sleep_modes.rst

@@ -50,6 +50,73 @@ In Deep-sleep mode, the CPUs, most of the RAM, and all digital peripherals that
 
     If Wi-Fi connections need to be maintained, enable Wi-Fi Modem-sleep mode and automatic Light-sleep feature (see :doc:`Power Management APIs <power_management>`). This will allow the system to wake up from sleep automatically when required by the Wi-Fi driver, thereby maintaining a connection to the AP.
 
+.. only:: esp32s2 or esp32s3 or esp32c2 or esp32c3
+
+    Sub Sleep Modes
+    ^^^^^^^^^^^^^^^
+
+    Tables below list the sub sleep modes (columns), and the features they support (rows). Mode that support more features may consume more power during sleep mode. The sleep system automatically selects the mode that satisfies all the features required by the user while consuming least power.
+
+    Deep-sleep:
+
+    +-----------------------------------+----------------+--------------+-----------------+
+    |                                   | DSLP_ULTRA_LOW | DSLP_DEFAULT | DSLP_8MD256 /   |
+    |                                   |                |              | DSLP_ADC_TSENS  |
+    +===================================+================+==============+=================+
+    | ULP/Touch sensor (S2, S3 only)    | Y              | Y            | Y               |
+    +-----------------------------------+----------------+--------------+-----------------+
+    | RTC IO input/RTC mem at high temp |                | Y            | Y               |
+    +-----------------------------------+----------------+--------------+-----------------+
+    | ADC_TSEN_MONITOR                  |                |              | Y               |
+    +-----------------------------------+----------------+--------------+-----------------+
+    | 8MD256                            |                |              | Y               |
+    +-----------------------------------+----------------+--------------+-----------------+
+
+    Features:
+
+    1. 8MD256: Use 8MD256 as the clock source for RTC Slow. Controlled by Kconfig option `CONFIG_RTC_CLK_SRC_INT_8MD256`.
+
+    2. ADC_TSEN_MONITOR: Use ADC/Temperature Sensor in monitor mode (controlled by ULP). Enabled by :cpp:func:`ulp_adc_init` API or its higher level APIs. Only available for chips with monitor modes (S2 and S3).
+
+    3. RTC IO input/RTC mem at high temp: Use RTC IO as input pins, or use RTC memory in high temperature. The chip can go into the ultra low power mode when these features are disabled. Controlled by API :cpp:func:`rtc_sleep_enable_ultra_low`. (Experimental)
+
+    Light-sleep:
+
+    +-----------------------------------+--------------+----------------+-------------+---------------+
+    |                                   | LSLP_DEFAULT | LSLP_ADC_TSENS | LSLP_8MD256 | LSLP_LEDC8M / |
+    |                                   |              |                |             | LSLP_XTAL_FPU |
+    +===================================+==============+================+=============+===============+
+    | ULP/Touch sensor (S2, S3 only)    | Y            | Y              | Y           | Y             |
+    +-----------------------------------+--------------+----------------+-------------+---------------+
+    | RTC IO input/RTC mem at high temp | Y            | Y              | Y           | Y             |
+    +-----------------------------------+--------------+----------------+-------------+---------------+
+    | ADC_TSEN_MONITOR                  |              | Y              | Y           | Y             |
+    +-----------------------------------+--------------+----------------+-------------+---------------+
+    | 8MD256                            |              |                | Y           | Y             |
+    +-----------------------------------+--------------+----------------+-------------+---------------+
+    | dig 8M                            |              |                |             | Y             |
+    +-----------------------------------+--------------+----------------+-------------+---------------+
+    | XTAL                              |              |                |             | Y             |
+    +-----------------------------------+--------------+----------------+-------------+---------------+
+
+    Features: (See also the 8MD256 and ADC_TSEN_MONITOR feature for deep-sleep)
+
+    1. XTAL: Keep XTAL on during light-sleep. Controlled by `ESP_PD_DOMAIN_XTAL` power domain.
+
+    2. dig 8M: 8M RC clock source used by digital peripherals. Currently only LEDC will use this clock source during light-sleep. When LEDC selects this clock source, this feature is automatically enabled.
+
+    .. only:: esp32s2
+
+        {IDF_TARGET_NAME} uses the same power mode for LSLP_8MD256, LSLP_LEDC8M and LSLP_XTAL_FPU.
+
+    .. only:: esp32s3
+
+        Default mode of {IDF_TARGET_NAME} already supports the ADC_TSEN_MONITOR feature.
+
+    .. only:: esp32c2 or esp32c3
+
+        {IDF_TARGET_NAME} doesn't have ADC_TSEN_MONITOR mode. There is no LSLP_ADC_TSENS mode either.
+
 .. _api-reference-wakeup-source:
 
 Wakeup Sources
@@ -100,8 +167,8 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
 
     :cpp:func:`esp_sleep_enable_ext0_wakeup` function can be used to enable this wakeup source.
 
-    .. warning:: 
+    .. 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