Merge branch 'feat/support_tg_retention_v5.3' into 'release/v5.3'

change(esp_hw_support): do TG WDT/Timer retention by needs (v5.3)

See merge request espressif/esp-idf!31486

Author: jack0c

components/driver/i2c/i2c.c

@@ -280,7 +280,7 @@ static void i2c_hw_enable(i2c_port_t i2c_num)
 static esp_err_t i2c_sleep_retention_init(void *arg)
 {
     i2c_port_t i2c_num = *(i2c_port_t *)arg;
-    esp_err_t ret = sleep_retention_entries_create(i2c_regs_retention[i2c_num].link_list, i2c_regs_retention[i2c_num].link_num, REGDMA_LINK_PRI_7, I2C_SLEEP_RETENTION_MODULE(i2c_num));
+    esp_err_t ret = sleep_retention_entries_create(i2c_regs_retention[i2c_num].link_list, i2c_regs_retention[i2c_num].link_num, REGDMA_LINK_PRI_I2C, I2C_SLEEP_RETENTION_MODULE(i2c_num));
     ESP_RETURN_ON_ERROR(ret, I2C_TAG, "failed to allocate mem for sleep retention");
     return ret;
 }

components/esp_driver_gptimer/include/driver/gptimer.h

@@ -28,6 +28,9 @@ typedef struct {
                                               if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3) */
     struct {
         uint32_t intr_shared: 1;         /*!< Set true, the timer interrupt number can be shared with other peripherals */
+        uint32_t backup_before_sleep: 1; /*!< If set, the driver will backup/restore the GPTimer registers before/after entering/exist sleep mode.
+                                              By this approach, the system can power off GPTimer's power domain.
+                                              This can save power, but at the expense of more RAM being consumed */
     } flags;                             /*!< GPTimer config flags*/
 } gptimer_config_t;
 

components/esp_driver_gptimer/src/gptimer.c

@@ -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
  */
@@ -30,6 +30,10 @@
 #include "esp_clk_tree.h"
 #include "gptimer_priv.h"
 
+#if GPTIMER_USE_RETENTION_LINK
+#include "esp_private/sleep_retention.h"
+#endif
+
 static const char *TAG = "gptimer";
 
 #if SOC_PERIPH_CLK_CTRL_SHARED
@@ -52,6 +56,37 @@ static void gptimer_release_group_handle(gptimer_group_t *group);
 static esp_err_t gptimer_select_periph_clock(gptimer_t *timer, gptimer_clock_source_t src_clk, uint32_t resolution_hz);
 static void gptimer_default_isr(void *args);
 
+#if GPTIMER_USE_RETENTION_LINK
+static esp_err_t sleep_tg_timer_retention_link_cb(void *arg)
+{
+    uint32_t group_id = *(uint32_t *)arg;
+    esp_err_t err = sleep_retention_entries_create(tg_timer_regs_retention[group_id].link_list,
+                                                   tg_timer_regs_retention[group_id].link_num,
+                                                   REGDMA_LINK_PRI_6,
+                                                   (group_id == 0) ? SLEEP_RETENTION_MODULE_TG0_TIMER : SLEEP_RETENTION_MODULE_TG1_TIMER);
+    if (err == ESP_OK) {
+        ESP_LOGD(TAG, "Timer group %ld retention initialization", group_id);
+    }
+    ESP_RETURN_ON_ERROR(err, TAG, "Failed to create sleep retention linked list for timer group %ld", group_id);
+    return err;
+}
+
+static void gptimer_create_retention_module(gptimer_group_t *group)
+{
+    _lock_acquire(&s_platform.mutex);
+    int group_id = group->group_id;
+    if ((group->sleep_retention_initialized == true) && (group->retention_link_created == false)) {
+        esp_err_t err = sleep_retention_module_allocate((group_id == 0) ? SLEEP_RETENTION_MODULE_TG0_TIMER : SLEEP_RETENTION_MODULE_TG1_TIMER);
+        if (err != ESP_OK) {
+            ESP_LOGW(TAG, "Failed to allocate sleep retention linked list for timer group %d retention, power domain can't turn off", group_id);
+        } else {
+            group->retention_link_created = true;
+        }
+    }
+    _lock_release(&s_platform.mutex);
+}
+#endif
+
 static esp_err_t gptimer_register_to_group(gptimer_t *timer)
 {
     gptimer_group_t *group = NULL;
@@ -129,6 +164,12 @@ esp_err_t gptimer_new_timer(const gptimer_config_t *config, gptimer_handle_t *re
     int group_id = group->group_id;
     int timer_id = timer->timer_id;
 
+#if GPTIMER_USE_RETENTION_LINK
+    if (config->flags.backup_before_sleep != 0) {
+        gptimer_create_retention_module(group);
+    }
+#endif // GPTIMER_USE_RETENTION_LINK
+
     // initialize HAL layer
     timer_hal_init(&timer->hal, group_id, timer_id);
     // select clock source, set clock resolution
@@ -404,7 +445,6 @@ static gptimer_group_t *gptimer_acquire_group_handle(int group_id)
         // someone acquired the group handle means we have a new object that refer to this group
         s_platform.group_ref_counts[group_id]++;
     }
-    _lock_release(&s_platform.mutex);
 
     if (new_group) {
         // !!! HARDWARE SHARED RESOURCE !!!
@@ -417,7 +457,28 @@ static gptimer_group_t *gptimer_acquire_group_handle(int group_id)
             }
         }
         ESP_LOGD(TAG, "new group (%d) @%p", group_id, group);
+#if GPTIMER_USE_RETENTION_LINK
+        if (group->sleep_retention_initialized != true) {
+            sleep_retention_module_init_param_t init_param = {
+                .cbs = {
+                    .create = {
+                        .handle = sleep_tg_timer_retention_link_cb,
+                        .arg = &group_id
+                    },
+                },
+                .depends = BIT(SLEEP_RETENTION_MODULE_CLOCK_SYSTEM)
+            };
+            esp_err_t err = sleep_retention_module_init((group_id == 0) ? SLEEP_RETENTION_MODULE_TG0_TIMER : SLEEP_RETENTION_MODULE_TG1_TIMER, &init_param);
+
+            if (err == ESP_OK) {
+                group->sleep_retention_initialized = true;
+            } else {
+                ESP_LOGW(TAG, "Failed to allocate sleep retention linked list for timer group %d retention", group_id);
+            }
+        }
+#endif // GPTIMER_USE_RETENTION_LINK
     }
+    _lock_release(&s_platform.mutex);
 
     return group;
 }
@@ -434,7 +495,6 @@ static void gptimer_release_group_handle(gptimer_group_t *group)
         do_deinitialize = true;
         s_platform.groups[group_id] = NULL;
     }
-    _lock_release(&s_platform.mutex);
 
     if (do_deinitialize) {
         // disable bus clock for the timer group
@@ -443,9 +503,18 @@ static void gptimer_release_group_handle(gptimer_group_t *group)
                 timer_ll_enable_bus_clock(group_id, false);
             }
         }
+#if GPTIMER_USE_RETENTION_LINK
+        if (group->retention_link_created) {
+            sleep_retention_module_free((group_id == 0) ? SLEEP_RETENTION_MODULE_TG0_TIMER : SLEEP_RETENTION_MODULE_TG1_TIMER);
+        }
+        if (group->sleep_retention_initialized) {
+            sleep_retention_module_deinit((group_id == 0) ? SLEEP_RETENTION_MODULE_TG0_TIMER : SLEEP_RETENTION_MODULE_TG1_TIMER);
+        }
+#endif
         free(group);
         ESP_LOGD(TAG, "del group (%d)", group_id);
     }
+    _lock_release(&s_platform.mutex);
 }
 
 static esp_err_t gptimer_select_periph_clock(gptimer_t *timer, gptimer_clock_source_t src_clk, uint32_t resolution_hz)

components/esp_driver_gptimer/src/gptimer_priv.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
  */
@@ -39,12 +39,18 @@ extern "C" {
 
 #define GPTIMER_PM_LOCK_NAME_LEN_MAX 16
 
+#define GPTIMER_USE_RETENTION_LINK  (SOC_TIMER_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP)
+
 typedef struct gptimer_t gptimer_t;
 
 typedef struct gptimer_group_t {
     int group_id;
     portMUX_TYPE spinlock; // to protect per-group register level concurrent access
     gptimer_t *timers[SOC_TIMER_GROUP_TIMERS_PER_GROUP];
+#if GPTIMER_USE_RETENTION_LINK
+    bool sleep_retention_initialized;           // mark if the retention link is initialized
+    bool retention_link_created;                // mark if the retention link is created
+#endif
 } gptimer_group_t;
 
 typedef enum {

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

@@ -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
  */
@@ -13,6 +13,15 @@
 #include "soc/soc_caps.h"
 #include "esp_attr.h"
 
+#if CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP && SOC_TIMER_SUPPORT_SLEEP_RETENTION
+#include "esp_random.h"
+#include "esp_rom_uart.h"
+#include "esp_sleep.h"
+#include "esp_private/esp_sleep_internal.h"
+#include "esp_private/sleep_cpu.h"
+#include "esp_private/esp_pmu.h"
+#endif
+
 #if CONFIG_GPTIMER_ISR_IRAM_SAFE
 #define TEST_ALARM_CALLBACK_ATTR IRAM_ATTR
 #else
@@ -596,3 +605,82 @@ TEST_CASE("gptimer_trig_alarm_with_old_count", "[gptimer]")
     TEST_ESP_OK(gptimer_disable(timer));
     TEST_ESP_OK(gptimer_del_timer(timer));
 }
+
+#if CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP && SOC_TIMER_SUPPORT_SLEEP_RETENTION
+static gptimer_handle_t timers[SOC_TIMER_GROUP_TOTAL_TIMERS];
+static uint32_t timer_resolution_hz[SOC_TIMER_GROUP_TOTAL_TIMERS];
+
+static void test_gptimer_retention(gptimer_config_t *timer_config)
+{
+    for (int i = 0; i < SOC_TIMER_GROUP_TOTAL_TIMERS; i++) {
+        TEST_ESP_OK(gptimer_new_timer(timer_config, &timers[i]));
+        TEST_ESP_OK(gptimer_get_resolution(timers[i], &timer_resolution_hz[i]));
+
+        unsigned long long count_start_value = 0, count_end_value = 0;
+
+        // Let gptimer run for a while
+        TEST_ESP_OK(gptimer_enable(timers[i]));
+        TEST_ESP_OK(gptimer_start(timers[i]));
+        vTaskDelay((esp_random() % 500) / portTICK_PERIOD_MS);
+        TEST_ESP_OK(gptimer_stop(timers[i]));
+        TEST_ESP_OK(gptimer_disable(timers[i]));
+        TEST_ESP_OK(gptimer_get_raw_count(timers[i], &count_start_value));
+
+        esp_sleep_context_t sleep_ctx;
+        esp_sleep_set_sleep_context(&sleep_ctx);
+        TEST_ESP_OK(sleep_cpu_configure(true));
+        esp_rom_output_tx_wait_idle(0);
+        esp_sleep_enable_timer_wakeup(50 * 1000);
+        esp_light_sleep_start();
+
+        if (timer_config->flags.backup_before_sleep) {
+            TEST_ASSERT_EQUAL(PMU_SLEEP_PD_TOP, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+        } else {
+            TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+        }
+
+        TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_request_result);
+
+        TEST_ESP_OK(gptimer_enable(timers[i]));
+        TEST_ESP_OK(gptimer_start(timers[i]));
+
+        uint32_t random_time_ms = 500 + esp_random() % 2000;
+        vTaskDelay(random_time_ms / portTICK_PERIOD_MS);
+        TEST_ESP_OK(gptimer_get_raw_count(timers[i], &count_end_value));
+
+        // Error tolerance is 2%
+        TEST_ASSERT_UINT_WITHIN(random_time_ms / 50, random_time_ms, 1000 * (count_end_value - count_start_value) / (unsigned long long)timer_resolution_hz[i]);
+
+        TEST_ESP_OK(gptimer_stop(timers[i]));
+        TEST_ESP_OK(gptimer_disable(timers[i]));
+        TEST_ESP_OK(gptimer_del_timer(timers[i]));
+        TEST_ESP_OK(sleep_cpu_configure(false));
+    }
+}
+
+TEST_CASE("gptimer context kept after peripheral powerdown lightsleep with backup_before_sleep enable", "[gptimer]")
+{
+    printf("install gptimer driver\r\n");
+    gptimer_config_t timer_config = {
+        .resolution_hz = 10 * 1000, // 10KHz, 1 tick = 0.1ms
+        .clk_src = GPTIMER_CLK_SRC_DEFAULT,
+        .direction = GPTIMER_COUNT_UP,
+        .flags.backup_before_sleep = true
+    };
+
+    test_gptimer_retention(&timer_config);
+}
+
+TEST_CASE("gptimer context kept after peripheral powerdown lightsleep with backup_before_sleep disable", "[gptimer]")
+{
+    printf("install gptimer driver\r\n");
+    gptimer_config_t timer_config = {
+        .resolution_hz = 10 * 1000, // 10KHz, 1 tick = 0.1ms
+        .clk_src = GPTIMER_CLK_SRC_DEFAULT,
+        .direction = GPTIMER_COUNT_UP,
+        .flags.backup_before_sleep = false
+    };
+
+    test_gptimer_retention(&timer_config);
+}
+#endif

components/esp_driver_gptimer/test_apps/gptimer/sdkconfig.ci.release

@@ -4,3 +4,6 @@ CONFIG_PM_DFS_INIT_AUTO=y
 CONFIG_COMPILER_OPTIMIZATION_SIZE=y
 CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_SIZE=y
 CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT=y
+# For TASK WDT timer PD_TOP sleep retention test
+CONFIG_ESP_SLEEP_DEBUG=y
+CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP=y

components/esp_driver_i2c/i2c_common.c

@@ -52,7 +52,7 @@ static esp_err_t s_i2c_sleep_retention_init(void *arg)
 {
     i2c_bus_t *bus = (i2c_bus_t *)arg;
     i2c_port_num_t port_num = bus->port_num;
-    esp_err_t ret = sleep_retention_entries_create(i2c_regs_retention[port_num].link_list, i2c_regs_retention[port_num].link_num, REGDMA_LINK_PRI_7, I2C_SLEEP_RETENTION_MODULE(port_num));
+    esp_err_t ret = sleep_retention_entries_create(i2c_regs_retention[port_num].link_list, i2c_regs_retention[port_num].link_num, REGDMA_LINK_PRI_I2C, I2C_SLEEP_RETENTION_MODULE(port_num));
     ESP_RETURN_ON_ERROR(ret, TAG, "failed to allocate mem for sleep retention");
     return ret;
 }

components/esp_hw_support/include/esp_private/esp_regdma.h

@@ -22,8 +22,6 @@ extern "C" {
 #if SOC_PAU_SUPPORTED
 #include "hal/pau_types.h"
 
-#define REGDMA_LINK_DBG 0       /* Enable REGDMA link info dump apis*/
-
 /**
  * @brief Create a REGDMA continuous type linked list node without retention buffer and the retention buffer is passed in by the caller
  * @param  backup  Register address to be backed up by REGDMA

components/esp_hw_support/lowpower/cpu_retention/port/esp32c3/sleep_cpu.c

@@ -14,7 +14,6 @@
 #include "esp_check.h"
 #include "esp_sleep.h"
 #include "esp_log.h"
-#include "esp_crc.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "esp_heap_caps.h"

components/esp_hw_support/lowpower/cpu_retention/port/esp32c5/sleep_cpu.c

@@ -14,7 +14,7 @@
 #include "esp_check.h"
 #include "esp_sleep.h"
 #include "esp_log.h"
-#include "esp_crc.h"
+#include "esp_rom_crc.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "esp_heap_caps.h"
@@ -391,12 +391,12 @@ static IRAM_ATTR void cpu_domain_dev_regs_restore(cpu_domain_dev_sleep_frame_t *
 #if CONFIG_PM_CHECK_SLEEP_RETENTION_FRAME
 static IRAM_ATTR void update_retention_frame_crc(uint32_t *frame_ptr, uint32_t frame_check_size, uint32_t *frame_crc_ptr)
 {
-    *(frame_crc_ptr) = esp_crc32_le(0, (void *)frame_ptr, frame_check_size);
+    *(frame_crc_ptr) = esp_rom_crc32_le(0, (void *)frame_ptr, frame_check_size);
 }
 
 static IRAM_ATTR void validate_retention_frame_crc(uint32_t *frame_ptr, uint32_t frame_check_size, uint32_t *frame_crc_ptr)
 {
-    if(*(frame_crc_ptr) != esp_crc32_le(0, (void *)(frame_ptr), frame_check_size)){
+    if(*(frame_crc_ptr) != esp_rom_crc32_le(0, (void *)(frame_ptr), frame_check_size)){
         // resume uarts
         for (int i = 0; i < SOC_UART_NUM; ++i) {
             if (!uart_ll_is_enabled(i)) {