Merge branch 'feat/support_software_trigger_retention' into 'master'

feat(esp_hw_support): support software trigger regdma retention

Closes PM-199

See merge request espressif/esp-idf!32789

Author: esp-wzh

components/esp_driver_gptimer/include/esp_private/gptimer.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -42,6 +42,16 @@ esp_err_t gptimer_get_intr_handle(gptimer_handle_t timer, intr_handle_t *ret_int
  */
 esp_err_t gptimer_get_pm_lock(gptimer_handle_t timer, esp_pm_lock_handle_t *ret_pm_lock);
 
+/**
+ * @brief Get the group_id from the timer handle
+ *
+ * @param[in] timer Timer handle created by `gptimer_new_timer()`
+ * @return
+ *      - ESP_OK: Get GPTimer group_id from handler successfully
+ *      - ESP_ERR_INVALID_ARG: Get GPTimer group_id failed because of invalid argument
+ */
+esp_err_t gptimer_get_group_id(gptimer_handle_t timer, int *group_id);
+
 #ifdef __cplusplus
 }
 #endif

components/esp_driver_gptimer/src/gptimer_common.c

@@ -226,3 +226,10 @@ esp_err_t gptimer_get_pm_lock(gptimer_handle_t timer, esp_pm_lock_handle_t *ret_
     *ret_pm_lock = timer->pm_lock;
     return ESP_OK;
 }
+
+int gptimer_get_group_id(gptimer_handle_t timer, int *group_id)
+{
+    ESP_RETURN_ON_FALSE(timer && group_id, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
+    *group_id = timer->group->group_id;
+    return ESP_OK;
+}

components/esp_driver_gptimer/test_apps/gptimer/main/CMakeLists.txt

@@ -1,5 +1,6 @@
 set(srcs "test_app_main.c"
-         "test_gptimer.c")
+         "test_gptimer.c"
+         "test_gptimer_sleep.c")
 
 if(CONFIG_GPTIMER_ISR_IRAM_SAFE)
     list(APPEND srcs "test_gptimer_iram.c")
@@ -9,10 +10,6 @@ if(CONFIG_SOC_TIMER_SUPPORT_ETM)
     list(APPEND srcs "test_gptimer_etm.c")
 endif()
 
-if(CONFIG_SOC_LIGHT_SLEEP_SUPPORTED AND CONFIG_PM_ENABLE)
-    list(APPEND srcs "test_gptimer_sleep.c")
-endif()
-
 # In order for the cases defined by `TEST_CASE` to be linked into the final elf,
 # the component can be registered as WHOLE_ARCHIVE
 idf_component_register(SRCS ${srcs}

components/esp_driver_gptimer/test_apps/gptimer/main/test_gptimer_sleep.c

@@ -15,8 +15,20 @@
 #include "esp_private/sleep_cpu.h"
 #include "esp_private/esp_sleep_internal.h"
 #include "esp_private/esp_pmu.h"
+#if !SOC_LIGHT_SLEEP_SUPPORTED
+#include "esp_private/gptimer.h"
+#include "esp_private/sleep_retention.h"
+#include "hal/timer_ll.h"
+#include "hal/wdt_hal.h"
+#endif
+
+#if CONFIG_GPTIMER_ISR_IRAM_SAFE
+#define TEST_ALARM_CALLBACK_ATTR IRAM_ATTR
+#else
+#define TEST_ALARM_CALLBACK_ATTR
+#endif // CONFIG_GPTIMER_ISR_IRAM_SAFE
 
-static bool test_gptimer_alarm_stop_callback(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_data)
+static TEST_ALARM_CALLBACK_ATTR bool test_gptimer_alarm_stop_callback(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_data)
 {
     TaskHandle_t task_handle = (TaskHandle_t)user_data;
     BaseType_t high_task_wakeup;
@@ -25,6 +37,62 @@ static bool test_gptimer_alarm_stop_callback(gptimer_handle_t timer, const gptim
     return high_task_wakeup == pdTRUE;
 }
 
+/**
+ * @brief This function abstracts the behavior of performing the Backup-Reset-Restore process on the specified
+ *        Timer group and is used as a helper function to test the retention function of the driver.
+ *        If light-sleep feature is supported, this function will enter and exit a real light sleep or PD_TOP
+ *        light sleep. Otherwise, it will trigger retention by software and reset the timer module to simulate
+ *        a light-sleep in/out process to verify the driver's support for GPTimer sleep retention.
+ *
+ * @param timer Timer handle to be reset, created by `gptimer_new_timer()`
+ * @param back_up_before_sleep Whether to back up GPTimer registers before sleep
+ */
+static void test_gptimer_survival_after_sleep_helper(gptimer_handle_t timer, bool back_up_before_sleep)
+{
+#if SOC_LIGHT_SLEEP_SUPPORTED
+    esp_sleep_context_t sleep_ctx;
+    esp_sleep_set_sleep_context(&sleep_ctx);
+    printf("go to light sleep for 2 seconds\r\n");
+#if ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(true));
+#endif
+    TEST_ESP_OK(esp_sleep_enable_timer_wakeup(2 * 1000 * 1000));
+    TEST_ESP_OK(esp_light_sleep_start());
+
+    printf("Waked up! Let's see if GPTimer driver can still work...\r\n");
+#if ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(false));
+#endif
+
+    printf("check if the sleep happened as expected\r\n");
+    TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_request_result);
+#if SOC_TIMER_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    if (back_up_before_sleep) {
+        // Verify that when GPTimer retention is configured and sleep is requested,
+        // the TOP power domain should be allowed to power down.
+        TEST_ASSERT_EQUAL(PMU_SLEEP_PD_TOP, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+    } else {
+        // Verify that when GPTimer retention is not configured and sleep is requested, the TOP power
+        // domain should not be allowed to power down to ensure the peripheral context is not lost.
+        TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+    }
+#endif
+    esp_sleep_set_sleep_context(NULL);
+#elif SOC_TIMER_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    if (back_up_before_sleep) {
+        printf("Back up the timer group context in use and then reset it\r\n");
+        sleep_retention_do_extra_retention(true);
+
+        int group_id;
+        gptimer_get_group_id(timer, &group_id);
+        _timer_ll_reset_register(group_id);
+
+        printf("Reset done! Let's restore its context and see if its driver can still work...\r\n");
+        sleep_retention_do_extra_retention(false);
+    }
+#endif
+}
+
 /**
  * @brief Test the GPTimer driver can still work after light sleep
  *
@@ -67,28 +135,7 @@ static void test_gptimer_sleep_retention(bool back_up_before_sleep)
     // Note: don't enable the gptimer before going to sleep, ensure no power management lock is acquired by it
     TEST_ESP_OK(gptimer_disable(timer));
 
-    esp_sleep_context_t sleep_ctx;
-    esp_sleep_set_sleep_context(&sleep_ctx);
-    printf("go to light sleep for 2 seconds\r\n");
-#if ESP_SLEEP_POWER_DOWN_CPU
-    TEST_ESP_OK(sleep_cpu_configure(true));
-#endif
-    TEST_ESP_OK(esp_sleep_enable_timer_wakeup(2 * 1000 * 1000));
-    TEST_ESP_OK(esp_light_sleep_start());
-
-    printf("Waked up! Let's see if GPTimer driver can still work...\r\n");
-#if ESP_SLEEP_POWER_DOWN_CPU
-    TEST_ESP_OK(sleep_cpu_configure(false));
-#endif
-
-    printf("check if the sleep happened as expected\r\n");
-    TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_request_result);
-#if SOC_TIMER_SUPPORT_SLEEP_RETENTION
-    if (back_up_before_sleep) {
-        TEST_ASSERT_EQUAL(PMU_SLEEP_PD_TOP, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
-    }
-#endif
-    esp_sleep_set_sleep_context(NULL);
+    test_gptimer_survival_after_sleep_helper(timer, back_up_before_sleep);
 
     uint64_t count_value_after_sleep = 0;
     TEST_ESP_OK(gptimer_get_raw_count(timer, &count_value_after_sleep));

components/esp_hw_support/include/esp_private/esp_pau.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -77,6 +77,16 @@ void pau_regdma_trigger_extra_link_backup(void);
  */
 void pau_regdma_trigger_extra_link_restore(void);
 
+#if SOC_PAU_IN_TOP_DOMAIN
+/**
+ * @brief Rentention link entry selection, enable or disable the retention
+ *        link entry configuration in always-on domain
+ *
+ * @param enable Set true to use always-on domain link configuration instead
+ */
+void pau_regdma_enable_aon_link_entry(bool enable);
+#endif
+
 #ifdef __cplusplus
 }
 #endif

components/esp_hw_support/include/esp_private/sleep_retention.h

@@ -164,15 +164,13 @@ uint32_t sleep_retention_get_inited_modules(void);
  */
 uint32_t sleep_retention_get_created_modules(void);
 
-#if SOC_PM_RETENTION_HAS_CLOCK_BUG
 /**
  * @brief Software trigger REGDMA to do extra linked list retention
  *
  * @param backup_or_restore true for backup register context to memory
  *                          or false for restore to register from memory
  */
 void sleep_retention_do_extra_retention(bool backup_or_restore);
-#endif
 
 #if SOC_PM_RETENTION_SW_TRIGGER_REGDMA
 /**

components/esp_hw_support/modem_clock.c

@@ -458,7 +458,7 @@ void modem_clock_deselect_lp_clock_source(periph_module_t module)
     case PERIPH_BT_MODULE:
         modem_clock_hal_deselect_all_ble_rtc_timer_lpclk_source(MODEM_CLOCK_instance()->hal);
         modem_clock_hal_enable_ble_rtc_timer_clock(MODEM_CLOCK_instance()->hal, false);
-#if SOC_BLE_USE_WIFI_PWR_CLK_WORKAROUND
+#if SOC_BLE_USE_WIFI_PWR_CLK_WORKAROUND && SOC_LIGHT_SLEEP_SUPPORTED  // TODO: [ESP32C5] IDF-8643
         if (efuse_hal_chip_revision() != 0) {
             if (last_src == MODEM_CLOCK_LPCLK_SRC_MAIN_XTAL) {
                 pmu_sleep_enable_hp_sleep_sysclk(false);

components/esp_hw_support/port/pau_regdma.c

@@ -15,6 +15,10 @@
 #include "esp_private/esp_pau.h"
 #include "esp_private/periph_ctrl.h"
 
+#if SOC_PAU_IN_TOP_DOMAIN
+#include "hal/lp_sys_ll.h"
+#endif
+
 static __attribute__((unused)) const char *TAG = "pau_regdma";
 
 typedef struct {
@@ -107,3 +111,10 @@ void IRAM_ATTR pau_regdma_trigger_extra_link_restore(void)
     pau_hal_start_regdma_extra_link(PAU_instance()->hal, false);
     pau_hal_stop_regdma_extra_link(PAU_instance()->hal);
 }
+
+#if SOC_PAU_IN_TOP_DOMAIN
+void pau_regdma_enable_aon_link_entry(bool enable)
+{
+    lp_sys_ll_set_pau_aon_bypass(enable);
+}
+#endif

components/esp_hw_support/sleep_retention.c

@@ -21,6 +21,10 @@
 #include "sdkconfig.h"
 #include "esp_pmu.h"
 
+#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
+#include "hal/cache_ll.h"
+#endif
+
 static __attribute__((unused)) const char *TAG = "sleep";
 
 struct sleep_retention_module_object {
@@ -183,9 +187,7 @@ typedef struct {
 
     struct sleep_retention_module_object instance[32];
 
-#if SOC_PM_RETENTION_HAS_CLOCK_BUG
 #define EXTRA_LINK_NUM  (REGDMA_LINK_ENTRY_NUM - 1)
-#endif
 } sleep_retention_t;
 
 static DRAM_ATTR __attribute__((unused)) sleep_retention_t s_retention = {
@@ -312,6 +314,7 @@ void sleep_retention_dump_entries(FILE *out)
             regdma_link_dump(out, s_retention.lists[s_retention.highpri].entries[entry], entry);
         }
     }
+    fflush(out);
     _lock_release_recursive(&s_retention.lock);
 }
 
@@ -770,22 +773,28 @@ esp_err_t sleep_retention_module_free(sleep_retention_module_t module)
     return err;
 }
 
-#if SOC_PM_RETENTION_HAS_CLOCK_BUG
 void IRAM_ATTR sleep_retention_do_extra_retention(bool backup_or_restore)
 {
     if (s_retention.highpri < SLEEP_RETENTION_REGDMA_LINK_HIGHEST_PRIORITY ||
         s_retention.highpri > SLEEP_RETENTION_REGDMA_LINK_LOWEST_PRIORITY) {
         return;
     }
+#if SOC_PAU_IN_TOP_DOMAIN
+    pau_regdma_enable_aon_link_entry(false);
+#endif
     // Set extra linked list head pointer to hardware
     pau_regdma_set_extra_link_addr(s_retention.lists[s_retention.highpri].entries[EXTRA_LINK_NUM]);
+#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
+    /* Data of retention link may be temporarily stored in L1 DCache, which is not accessible by
+       REGDMA, write it back to L2MEM before starting REGDMA. */
+    cache_ll_writeback_all(CACHE_LL_LEVEL_INT_MEM, CACHE_TYPE_DATA, CACHE_LL_ID_ALL);
+#endif
     if (backup_or_restore) {
         pau_regdma_trigger_extra_link_backup();
     } else {
         pau_regdma_trigger_extra_link_restore();
     }
 }
-#endif
 
 #if SOC_PM_RETENTION_SW_TRIGGER_REGDMA
 void IRAM_ATTR sleep_retention_do_system_retention(bool backup_or_restore)

components/hal/esp32c5/pau_hal.c

@@ -40,7 +40,10 @@ void pau_hal_start_regdma_extra_link(pau_hal_context_t *hal, bool backup_or_rest
     pau_ll_clear_regdma_backup_done_intr_state(hal->dev);
     /* The link 3 of REGDMA is reserved, we use it as an extra linked list to
      * provide backup and restore services for BLE, IEEE802.15.4 and possibly
-     * other modules */
+     * other modules.
+     * It is also used as software trigger REGDMA to backup and restore, and is
+     * used by the UT to test module driver retention function.
+     */
     pau_ll_select_regdma_entry_link(hal->dev, 3);
     pau_ll_set_regdma_entry_link_backup_direction(hal->dev, backup_or_restore);
     pau_ll_set_regdma_entry_link_backup_start_enable(hal->dev);