Merge branch 'fix/sdio_slave_add_pm_lock_v5.4' into 'release/v5.4'

fix(sdio_slave): fix issue that auto light sleep can happen SDIO slave enabled (v5.4)

See merge request espressif/esp-idf!34646

Author: ginkgm

components/esp_driver_sdio/src/sdio_slave.c

@@ -76,20 +76,24 @@ The driver of FIFOs works as below:
 */
 
 #include <string.h>
-#include "driver/sdio_slave.h"
-#include "soc/sdio_slave_periph.h"
-#include "esp_log.h"
-#include "esp_intr_alloc.h"
-#include "freertos/FreeRTOS.h"
+
 #include "soc/soc_memory_layout.h"
 #include "soc/gpio_periph.h"
 #include "soc/soc_caps.h"
+#include "soc/sdio_slave_periph.h"
 #include "esp_cpu.h"
+#include "esp_intr_alloc.h"
+#include "esp_log.h"
+#include "hal/sdio_slave_hal.h"
+#include "hal/gpio_hal.h"
+#include "freertos/FreeRTOS.h"
 #include "freertos/semphr.h"
 #include "esp_private/periph_ctrl.h"
+#if CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+#include "esp_private/sleep_retention.h"
+#endif
 #include "driver/gpio.h"
-#include "hal/sdio_slave_hal.h"
-#include "hal/gpio_hal.h"
+#include "driver/sdio_slave.h"
 
 #define SDIO_SLAVE_CHECK(res, str, ret_val) do { if(!(res)){\
     SDIO_SLAVE_LOGE("%s", str);\
@@ -365,6 +369,13 @@ esp_err_t sdio_slave_initialize(sdio_slave_config_t *config)
     }
     context.intr_handle = intr_handle;
 
+#if CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    r = sleep_retention_power_lock_acquire();
+    if (r != ESP_OK) {
+        return r;
+    }
+#endif
+
     r = sdio_slave_hw_init(config);
     if (r != ESP_OK) {
         return r;
@@ -378,6 +389,11 @@ void sdio_slave_deinit(void)
 {
     sdio_slave_hw_deinit();
 
+#if CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    esp_err_t r = sleep_retention_power_lock_release();
+    assert(r == ESP_OK);
+#endif
+
     //unregister all buffers registered but returned (not loaded)
     recv_desc_t *temp_desc;
     recv_desc_t *desc;

components/esp_driver_sdio/test_apps/.build-test-rules.yml

@@ -1,14 +1,17 @@
 components/esp_driver_sdio/test_apps/sdio/sdio_common_tests/host_sdmmc:
   enable:
     - if: IDF_TARGET == "esp32"
-      temporary: false
       reason: always use ESP32 SDMMC as host
   depends_components:
     - sdmmc
     - esp_driver_sdmmc
     - esp_driver_sdio
 
 components/esp_driver_sdio/test_apps/sdio/sdio_common_tests/sdio:
+  enable:
+  # There is no retention support for SDIO slave, just build and test if driver can forbid from auto light sleep.
+    - if: CONFIG_NAME == "sleep_retention" and SOC_PAU_SUPPORTED == 1
+    - if: CONFIG_NAME != "sleep_retention"
   disable:
     - if: SOC_SDIO_SLAVE_SUPPORTED != 1
   depends_components:

components/esp_driver_sdio/test_apps/sdio/sdio_common_tests/host_sdmmc/main/test_sdio_sdhost.c

@@ -418,6 +418,20 @@ TEST_CASE("SDIO_SDMMC: test to host", "[sdio]")
     test_to_host(true);
 }
 
+TEST_CASE("SDIO_SDMMC: test sleep retention", "[sdio_retention]")
+{
+    essl_handle_t handle = NULL;
+    test_sdio_param_t test_param = {
+        .host_flags = SDMMC_HOST_FLAG_4BIT | SDMMC_HOST_FLAG_ALLOC_ALIGNED_BUF,
+        .max_freq_khz = SDMMC_FREQ_HIGHSPEED,
+    };
+    //essl init and sdmmc init
+    s_master_init(&test_param, &handle, NULL);
+
+    s_send_finish_test(handle);
+    s_master_deinit();
+}
+
 TEST_CASE("SDIO_SDMMC: test to host (Performance)", "[sdio_speed]")
 {
     test_to_host(false);

components/esp_driver_sdio/test_apps/sdio/sdio_common_tests/pytest_sdio.py

@@ -1,13 +1,30 @@
-# SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: CC0-1.0
-
 import os.path
+from typing import List
 from typing import Tuple
 
 import pytest
 from pytest_embedded_idf import IdfDut
 
 
+def parameter_expand(existing_parameters: List[List[str]], value_list: List[str]) -> List[List[str]]:
+    ret = []
+    for param in existing_parameters:
+        ret.extend([param + [value] for value in value_list])
+
+    return ret
+
+
+esp32_32_param = [[f'{os.path.join(os.path.dirname(__file__), "host_sdmmc")}|{os.path.join(os.path.dirname(__file__), "sdio")}', 'esp32|esp32']]
+esp32_c6_param = [[f'{os.path.join(os.path.dirname(__file__), "host_sdmmc")}|{os.path.join(os.path.dirname(__file__), "sdio")}', 'esp32|esp32c6']]
+
+esp32_param_default = [pytest.param(*param) for param in parameter_expand(esp32_32_param, ['default|default'])]
+c6_param_default = [pytest.param(*param) for param in parameter_expand(esp32_c6_param, ['default|default'])]
+
+c6_param_retention = [pytest.param(*param) for param in parameter_expand(esp32_c6_param, ['default|sleep_retention'])]
+
+
 # Normal tests
 def test_sdio_flow(dut:Tuple[IdfDut, IdfDut]) -> None:
     dut[1].expect('Press ENTER to see the list of tests')
@@ -24,23 +41,15 @@ def test_sdio_flow(dut:Tuple[IdfDut, IdfDut]) -> None:
 @pytest.mark.esp32c6
 @pytest.mark.sdio_multidev_32_c6
 @pytest.mark.parametrize('count', [2,], indirect=True)
-@pytest.mark.parametrize('app_path, target', [
-    pytest.param(
-        f'{os.path.join(os.path.dirname(__file__), "host_sdmmc")}|{os.path.join(os.path.dirname(__file__), "sdio")}',
-        'esp32|esp32c6'),
-], indirect=True)
+@pytest.mark.parametrize('app_path, target, config', c6_param_default, indirect=True)
 def test_sdio_esp32_esp32c6(dut:Tuple[IdfDut, IdfDut]) -> None:
     test_sdio_flow(dut)
 
 
 @pytest.mark.esp32
 @pytest.mark.sdio_master_slave
 @pytest.mark.parametrize('count', [2,], indirect=True)
-@pytest.mark.parametrize('app_path, target', [
-    pytest.param(
-        f'{os.path.join(os.path.dirname(__file__), "host_sdmmc")}|{os.path.join(os.path.dirname(__file__), "sdio")}',
-        'esp32|esp32'),
-], indirect=True)
+@pytest.mark.parametrize('app_path, target, config', esp32_param_default, indirect=True)
 def test_sdio_esp32_esp32(dut:Tuple[IdfDut, IdfDut]) -> None:
     test_sdio_flow(dut)
 
@@ -68,23 +77,15 @@ def test_sdio_speed_frhost_flow(dut:Tuple[IdfDut, IdfDut], expected_4b_speed:int
 @pytest.mark.esp32c6
 @pytest.mark.sdio_multidev_32_c6
 @pytest.mark.parametrize('count', [2,], indirect=True)
-@pytest.mark.parametrize('app_path, target', [
-    pytest.param(
-        f'{os.path.join(os.path.dirname(__file__), "host_sdmmc")}|{os.path.join(os.path.dirname(__file__), "sdio")}',
-        'esp32|esp32c6'),
-], indirect=True)
+@pytest.mark.parametrize('app_path, target, config', c6_param_default, indirect=True)
 def test_sdio_speed_frhost_esp32_esp32c6(dut:Tuple[IdfDut, IdfDut]) -> None:
     test_sdio_speed_frhost_flow(dut, 10000, 4000)
 
 
 @pytest.mark.esp32
 @pytest.mark.sdio_master_slave
 @pytest.mark.parametrize('count', [2,], indirect=True)
-@pytest.mark.parametrize('app_path, target', [
-    pytest.param(
-        f'{os.path.join(os.path.dirname(__file__), "host_sdmmc")}|{os.path.join(os.path.dirname(__file__), "sdio")}',
-        'esp32|esp32'),
-], indirect=True)
+@pytest.mark.parametrize('app_path, target, config', esp32_param_default, indirect=True)
 def test_sdio_speed_frhost_esp32_esp32(dut:Tuple[IdfDut, IdfDut]) -> None:
     test_sdio_speed_frhost_flow(dut, 12200, 4000)
 
@@ -112,22 +113,35 @@ def test_sdio_speed_tohost_flow(dut:Tuple[IdfDut, IdfDut], expected_4b_speed:int
 @pytest.mark.esp32c6
 @pytest.mark.sdio_multidev_32_c6
 @pytest.mark.parametrize('count', [2,], indirect=True)
-@pytest.mark.parametrize('app_path, target', [
-    pytest.param(
-        f'{os.path.join(os.path.dirname(__file__), "host_sdmmc")}|{os.path.join(os.path.dirname(__file__), "sdio")}',
-        'esp32|esp32c6'),
-], indirect=True)
+@pytest.mark.parametrize('app_path, target, config', c6_param_default, indirect=True)
 def test_sdio_speed_tohost_esp32_esp32c6(dut:Tuple[IdfDut, IdfDut]) -> None:
     test_sdio_speed_tohost_flow(dut, 9000, 4000)
 
 
 @pytest.mark.esp32
 @pytest.mark.sdio_master_slave
 @pytest.mark.parametrize('count', [2,], indirect=True)
-@pytest.mark.parametrize('app_path, target', [
-    pytest.param(
-        f'{os.path.join(os.path.dirname(__file__), "host_sdmmc")}|{os.path.join(os.path.dirname(__file__), "sdio")}',
-        'esp32|esp32'),
-], indirect=True)
+@pytest.mark.parametrize('app_path, target, config', esp32_param_default, indirect=True)
 def test_sdio_speed_tohost_esp32_esp32(dut:Tuple[IdfDut, IdfDut]) -> None:
     test_sdio_speed_tohost_flow(dut, 12200, 4000)
+
+
+# Retention tests
+def test_sdio_retention(dut:Tuple[IdfDut, IdfDut]) -> None:
+    dut[1].expect('Press ENTER to see the list of tests')
+    dut[1].write('[sdio_retention]')
+    dut[1].expect('test_sdio: slave ready')
+
+    dut[0].expect('Press ENTER to see the list of tests')
+    dut[0].write('[sdio_retention]')
+
+    dut[1].expect_unity_test_output()
+    dut[0].expect_unity_test_output()
+
+
+@pytest.mark.esp32c6
+@pytest.mark.sdio_multidev_32_c6
+@pytest.mark.parametrize('count', [2,], indirect=True)
+@pytest.mark.parametrize('app_path, target, config', c6_param_retention, indirect=True)
+def test_sdio_retention_esp32_esp32c6(dut:Tuple[IdfDut, IdfDut]) -> None:
+    test_sdio_retention(dut)

components/esp_driver_sdio/test_apps/sdio/sdio_common_tests/sdio/main/CMakeLists.txt

@@ -2,5 +2,5 @@ set(srcs "test_app_main.c"
          "test_sdio_slave.c")
 
 idf_component_register(SRCS ${srcs}
-                       PRIV_REQUIRES test_driver_utils driver
+                       PRIV_REQUIRES test_driver_utils driver esp_hw_support
                        WHOLE_ARCHIVE)

components/esp_driver_sdio/test_apps/sdio/sdio_common_tests/sdio/main/test_sdio_slave.c

@@ -305,6 +305,31 @@ TEST_CASE("SDIO_Slave: test to host", "[sdio]")
     test_to_host();
 }
 
+#if SOC_PAU_SUPPORTED
+#include "esp_private/sleep_sys_periph.h"
+#include "esp_private/sleep_retention.h"
+
+TEST_CASE("SDIO_Slave: test sleep retention", "[sdio_retention]")
+{
+    TEST_ASSERT_EQUAL_INT32(true, peripheral_domain_pd_allowed());
+    sleep_retention_dump_modules(stdout);
+
+    s_slave_init(SDIO_SLAVE_SEND_STREAM);
+    TEST_ESP_OK(sdio_slave_start());
+    ESP_LOGI(TAG, "slave ready");
+
+    TEST_ASSERT_EQUAL_INT32(false, peripheral_domain_pd_allowed());
+    sleep_retention_dump_modules(stdout);
+
+    wait_for_finish(&s_test_slv_ctx);
+
+    sdio_slave_stop();
+    sdio_slave_deinit();
+
+    TEST_ASSERT_EQUAL_INT32(true, peripheral_domain_pd_allowed());
+}
+#endif
+
 TEST_CASE("SDIO_Slave: test to host (Performance)", "[sdio_speed]")
 {
     test_to_host();

components/esp_driver_sdio/test_apps/sdio/sdio_common_tests/sdio/sdkconfig.ci.sleep_retention

@@ -0,0 +1,4 @@
+CONFIG_PM_ENABLE=y
+CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP=y
+CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP=y
+CONFIG_FREERTOS_USE_TICKLESS_IDLE=y

components/esp_hw_support/include/esp_private/sleep_retention.h

@@ -59,6 +59,11 @@ typedef enum {
  */
 esp_err_t sleep_retention_entries_create(const sleep_retention_entries_config_t retent[], int num, regdma_link_priority_t priority, sleep_retention_module_t module);
 
+/**
+ * @brief Dump the initialization status of all modules.
+*/
+void sleep_retention_dump_modules(FILE *out);
+
 /**
  * @brief Dump all runtime sleep retention linked lists
  */
@@ -139,6 +144,23 @@ esp_err_t sleep_retention_module_allocate(sleep_retention_module_t module);
  */
 esp_err_t sleep_retention_module_free(sleep_retention_module_t module);
 
+/**
+ * @brief Force take the power lock so that during sleep the power domain won't be powered off.
+ *
+ * @return
+ *      - ESP_OK if success
+ *      - other value when the internal `sleep_retention_module_init` fails.
+*/
+esp_err_t sleep_retention_power_lock_acquire(void);
+
+/**
+ * @brief Release the power lock so that the peripherals' power domain can be powered off.
+ *        Please note that there is an internal reference counter and the power domain will be kept on until same number
+ *        of `sleep_retention_power_lock_release` is called as `sleep_retention_power_lock_acquire`.
+ * @return always ESP_OK
+*/
+esp_err_t sleep_retention_power_lock_release(void);
+
 /**
  * @brief Get all initialized modules that require sleep retention
  *

components/esp_hw_support/sleep_retention.c

@@ -29,6 +29,8 @@
 #endif
 
 static __attribute__((unused)) const char *TAG = "sleep";
+static int acquire_cnt; //for the force acquire lock
+
 
 struct sleep_retention_module_object {
     sleep_retention_module_callbacks_t cbs;         /* A callback list that can extend more sleep retention event callbacks */
@@ -319,6 +321,23 @@ static void sleep_retention_entries_stats(void)
     _lock_release_recursive(&s_retention.lock);
 }
 
+void sleep_retention_dump_modules(FILE *out)
+{
+    uint32_t inited_modules = sleep_retention_get_inited_modules();
+    uint32_t created_modules = sleep_retention_get_created_modules();
+    for (int i = SLEEP_RETENTION_MODULE_MIN; i <= SLEEP_RETENTION_MODULE_MAX; i++) {
+        bool inited = (inited_modules & BIT(i)) != 0;
+        bool created = (created_modules & BIT(i)) != 0;
+        bool is_top = (TOP_DOMAIN_PERIPHERALS_BM & BIT(i)) != 0;
+
+        const char* status = !inited? "-":
+                        created? "CREATED":
+                                "INITED";
+        const char* domain = is_top? "TOP": "-";
+        fprintf(out, "%2d: %4s %8s\n", i, domain, status);
+    }
+}
+
 void sleep_retention_dump_entries(FILE *out)
 {
     _lock_acquire_recursive(&s_retention.lock);
@@ -820,6 +839,42 @@ esp_err_t sleep_retention_module_free(sleep_retention_module_t module)
     return err;
 }
 
+static esp_err_t empty_create(void *args)
+{
+    return ESP_OK;
+}
+
+esp_err_t sleep_retention_power_lock_acquire(void)
+{
+    _lock_acquire_recursive(&s_retention.lock);
+    if (acquire_cnt == 0) {
+        sleep_retention_module_init_param_t init_param = {
+            .cbs = { .create = {.handle = empty_create},},
+        };
+        esp_err_t ret = sleep_retention_module_init(SLEEP_RETENTION_MODULE_NULL, &init_param);
+        if (ret != ESP_OK) {
+            _lock_release_recursive(&s_retention.lock);
+            return ret;
+        }
+    }
+    acquire_cnt++;
+    _lock_release_recursive(&s_retention.lock);
+    return ESP_OK;
+}
+
+esp_err_t sleep_retention_power_lock_release(void)
+{
+    esp_err_t ret = ESP_OK;
+    _lock_acquire_recursive(&s_retention.lock);
+    acquire_cnt--;
+    assert(acquire_cnt >= 0);
+    if (acquire_cnt == 0) {
+        ret = sleep_retention_module_deinit(SLEEP_RETENTION_MODULE_NULL);
+    }
+    _lock_release_recursive(&s_retention.lock);
+    return ret;
+}
+
 void IRAM_ATTR sleep_retention_do_extra_retention(bool backup_or_restore)
 {
     if (s_retention.highpri < SLEEP_RETENTION_REGDMA_LINK_HIGHEST_PRIORITY ||

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

@@ -42,6 +42,11 @@ components/esp_hw_support/test_apps/rtc_power_modes:
       temporary: true
       reason: the other targets are not tested yet
 
+components/esp_hw_support/test_apps/sleep_retention:
+  enable:
+    - if: SOC_PAU_SUPPORTED == 1 and CONFIG_NAME != "xip_psram"
+    - if: SOC_PAU_SUPPORTED == 1 and (SOC_SPIRAM_XIP_SUPPORTED == 1 and CONFIG_NAME == "xip_psram")
+
 components/esp_hw_support/test_apps/vad_wakeup:
   disable:
     - if: SOC_LP_VAD_SUPPORTED != 1