feat(driver_spi): spi master support sleep retention(recovery)

components/esp_driver_spi/include/driver/spi_common.h

@@ -64,6 +64,7 @@ extern "C"
 #define SPICOMMON_BUSFLAG_IO4_IO7       (1<<8)     ///< Check existing of IO4~IO7 pins. Or indicates IO4~IO7 pins initialized.
 #define SPICOMMON_BUSFLAG_OCTAL         (SPICOMMON_BUSFLAG_QUAD|SPICOMMON_BUSFLAG_IO4_IO7)  ///< Check existing of MOSI/MISO/WP/HD/SPIIO4/SPIIO5/SPIIO6/SPIIO7 pins as output. Or indicates bus able to work under octal mode.
 #define SPICOMMON_BUSFLAG_NATIVE_PINS   SPICOMMON_BUSFLAG_IOMUX_PINS
+#define SPICOMMON_BUSFLAG_SLP_ALLOW_PD  (1<<9)     ///< Allow to power down the peripheral during light sleep, and auto recover then.
 
 /**
  * @brief SPI DMA channels

components/esp_driver_spi/src/gpspi/spi_common.c

@@ -22,6 +22,8 @@
 #include "esp_private/spi_common_internal.h"
 #include "esp_private/spi_share_hw_ctrl.h"
 #include "esp_private/esp_cache_private.h"
+#include "esp_private/sleep_retention.h"
+#include "esp_dma_utils.h"
 #include "hal/spi_hal.h"
 #include "hal/gpio_hal.h"
 #if CONFIG_IDF_TARGET_ESP32
@@ -58,6 +60,7 @@ static const char *SPI_TAG = "spi";
 
 typedef struct {
     int host_id;
+    _lock_t mutex;      // mutex for controller
     spi_destroy_func_t destroy_func;
     void* destroy_arg;
     spi_bus_attr_t bus_attr;
@@ -605,7 +608,8 @@ esp_err_t spicommon_bus_initialize_io(spi_host_device_t host, const spi_bus_conf
     }
 
     uint32_t missing_flag = flags & ~temp_flag;
-    missing_flag &= ~SPICOMMON_BUSFLAG_MASTER;//don't check this flag
+    missing_flag &= ~SPICOMMON_BUSFLAG_MASTER;  //don't check this flag
+    missing_flag &= ~SPICOMMON_BUSFLAG_SLP_ALLOW_PD;
 
     if (missing_flag != 0) {
         //check pins existence
@@ -796,6 +800,16 @@ spi_bus_lock_handle_t spi_bus_lock_get_by_id(spi_host_device_t host_id)
     return bus_ctx[host_id]->bus_attr.lock;
 }
 
+#if SOC_SPI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+static esp_err_t s_bus_create_sleep_retention_cb(void *arg)
+{
+    spicommon_bus_context_t *ctx = arg;
+    return sleep_retention_entries_create(spi_reg_retention_info[ctx->host_id - 1].entry_array,
+                                          spi_reg_retention_info[ctx->host_id - 1].array_size,
+                                          REGDMA_LINK_PRI_GPSPI,
+                                          spi_reg_retention_info[ctx->host_id - 1].module_id);
+}
+#endif  // SOC_SPI_SUPPORT_SLEEP_RETENTION
 //----------------------------------------------------------master bus init-------------------------------------------------------//
 esp_err_t spi_bus_initialize(spi_host_device_t host_id, const spi_bus_config_t *bus_config, spi_dma_chan_t dma_chan)
 {
@@ -861,6 +875,34 @@ esp_err_t spi_bus_initialize(spi_host_device_t host_id, const spi_bus_config_t *
         goto cleanup;
     }
 
+#if SOC_SPI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    sleep_retention_module_init_param_t init_param = {
+        .cbs = {
+            .create = {
+                .handle = s_bus_create_sleep_retention_cb,
+                .arg = ctx,
+            },
+        },
+        .depends = RETENTION_MODULE_BITMAP_INIT(CLOCK_SYSTEM),
+    };
+
+    _lock_acquire(&ctx->mutex);
+    if (sleep_retention_module_init(spi_reg_retention_info[host_id - 1].module_id, &init_param) == ESP_OK) {
+        if ((bus_attr->bus_cfg.flags & SPICOMMON_BUSFLAG_SLP_ALLOW_PD) && (sleep_retention_module_allocate(spi_reg_retention_info[host_id - 1].module_id) != ESP_OK)) {
+            // even though the sleep retention create failed, SPI driver should still work, so just warning here
+            ESP_LOGW(SPI_TAG, "alloc sleep recover failed, peripherals may hold power on");
+        }
+    } else {
+        // even the sleep retention init failed, SPI driver should still work, so just warning here
+        ESP_LOGW(SPI_TAG, "init sleep recover failed, spi may offline after sleep");
+    }
+    _lock_release(&ctx->mutex);
+#else
+    if (bus_attr->bus_cfg.flags & SPICOMMON_BUSFLAG_SLP_ALLOW_PD) {
+        ESP_LOGE(SPI_TAG, "power down peripheral in sleep is not enabled or not supported on your target");
+    }
+#endif  // SOC_SPI_SUPPORT_SLEEP_RETENTION
+
 #ifdef CONFIG_PM_ENABLE
 #if CONFIG_IDF_TARGET_ESP32P4
     // use CPU_MAX lock to ensure PSRAM bandwidth and usability during DFS
@@ -936,9 +978,24 @@ esp_err_t spi_bus_free(spi_host_device_t host_id)
     }
     spicommon_bus_free_io_cfg(&bus_attr->bus_cfg);
 
+#if SOC_SPI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    const periph_retention_module_t retention_id = spi_reg_retention_info[host_id - 1].module_id;
+    _lock_acquire(&ctx->mutex);
+    if (sleep_retention_is_module_created(retention_id)) {
+        assert(sleep_retention_is_module_inited(retention_id));
+        sleep_retention_module_free(retention_id);
+    }
+    if (sleep_retention_is_module_inited(retention_id)) {
+        sleep_retention_module_deinit(retention_id);
+    }
+    _lock_release(&ctx->mutex);
+    _lock_close(&ctx->mutex);
+#endif
+
 #ifdef CONFIG_PM_ENABLE
     esp_pm_lock_delete(bus_attr->pm_lock);
 #endif
+
     spi_bus_deinit_lock(bus_attr->lock);
     if (ctx->dma_ctx) {
         free(ctx->dma_ctx->dmadesc_tx);

components/esp_driver_spi/src/gpspi/spi_master.c

@@ -340,8 +340,7 @@ static esp_err_t spi_master_deinit_driver(void* arg)
     int host_id = host->id;
     SPI_CHECK(is_valid_host(host_id), "invalid host_id", ESP_ERR_INVALID_ARG);
 
-    int x;
-    for (x = 0; x < DEV_NUM_MAX; x++) {
+    for (int x = 0; x < DEV_NUM_MAX; x++) {
         SPI_CHECK(host->device[x] == NULL, "not all CSses freed", ESP_ERR_INVALID_STATE);
     }
 

components/esp_driver_spi/test_apps/master/main/CMakeLists.txt

@@ -8,7 +8,7 @@ set(srcs
 
 # sct test using slave hd APIs, need slave hd support
 # tmp skip sct test under iram_safe, both sct and slave hd are not cleaned
-if(CONFIG_SOC_SPI_SUPPORT_SLAVE_HD_VER2 AND NOT CONFIG_COMPILER_DUMP_RTL_FILES)
+if(CONFIG_SOC_SPI_SUPPORT_SLAVE_HD_VER2 AND CONFIG_SOC_SPI_SCT_SUPPORTED AND NOT CONFIG_COMPILER_DUMP_RTL_FILES)
     list(APPEND srcs "test_spi_master_sct.c")
 endif()
 

components/esp_driver_spi/test_apps/master/main/test_spi_master.c

@@ -19,6 +19,9 @@
 #include "esp_private/cache_utils.h"
 #include "esp_private/spi_common_internal.h"
 #include "esp_private/esp_clk.h"
+#include "esp_private/sleep_cpu.h"
+#include "esp_private/esp_sleep_internal.h"
+#include "esp_private/esp_pmu.h"
 #include "esp_heap_caps.h"
 #include "esp_clk_tree.h"
 #include "esp_timer.h"
@@ -1754,3 +1757,69 @@ static void test_iram_slave_normal(void)
 
 TEST_CASE_MULTIPLE_DEVICES("SPI_Master:IRAM_safe", "[spi_ms]", test_master_iram, test_iram_slave_normal);
 #endif
+
+#if !CONFIG_IDF_TARGET_ESP32P4    // TODO: IDF-7528, IDF-7529
+TEST_CASE("test_spi_master_sleep_retention", "[spi]")
+{
+    // Prepare a TOP PD sleep
+    TEST_ESP_OK(esp_sleep_enable_timer_wakeup(1 * 1000 * 1000));
+#if ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(true));
+#endif
+    esp_sleep_context_t sleep_ctx;
+    esp_sleep_set_sleep_context(&sleep_ctx);
+
+    spi_device_handle_t dev_handle;
+    spi_bus_config_t buscfg = SPI_BUS_TEST_DEFAULT_CONFIG();
+    spi_device_interface_config_t devcfg = SPI_DEVICE_TEST_DEFAULT_CONFIG();
+    buscfg.flags |= SPICOMMON_BUSFLAG_GPIO_PINS;
+    buscfg.flags |= SPICOMMON_BUSFLAG_SLP_ALLOW_PD;
+    uint8_t send[16] = "hello spi x\n";
+    uint8_t recv[16];
+    spi_transaction_t trans_cfg = {
+        .length = 8 * sizeof(send),
+        .tx_buffer = send,
+        .rx_buffer = recv,
+    };
+
+    for (int periph = SPI2_HOST; periph < SPI_HOST_MAX; periph ++) {
+        for (int test_dma = 0; test_dma <= 1; test_dma ++) {
+            int use_dma = SPI_DMA_DISABLED;
+#if SOC_GDMA_SUPPORT_SLEEP_RETENTION    // TODO: IDF-11317 test dma on esp32 and s2
+            use_dma = test_dma ? SPI_DMA_CH_AUTO : SPI_DMA_DISABLED;
+#endif
+            printf("Retention on GPSPI%d with dma: %d\n", periph + 1, use_dma);
+            TEST_ESP_OK(spi_bus_initialize(periph, &buscfg, use_dma));
+            // set spi "self-loop" after bus initialized
+            spitest_gpio_output_sel(buscfg.miso_io_num, FUNC_GPIO, spi_periph_signal[periph].spid_out);
+            TEST_ESP_OK(spi_bus_add_device(periph, &devcfg, &dev_handle));
+
+            for (uint8_t cnt = 0; cnt < 3; cnt ++) {
+                printf("Going into sleep...\n");
+                TEST_ESP_OK(esp_light_sleep_start());
+                printf("Waked up!\n");
+
+                // check if the sleep happened as expected
+                TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_request_result);
+#if SOC_SPI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+                // check if the power domain also is powered down
+                TEST_ASSERT_EQUAL((buscfg.flags & SPICOMMON_BUSFLAG_SLP_ALLOW_PD) ? PMU_SLEEP_PD_TOP : 0, (sleep_ctx.sleep_flags) & PMU_SLEEP_PD_TOP);
+#endif
+                memset(recv, 0, sizeof(recv));
+                send[10] = cnt + 'A';
+                TEST_ESP_OK(spi_device_transmit(dev_handle, &trans_cfg));
+                printf("%s", recv);
+                spitest_cmp_or_dump(trans_cfg.tx_buffer, trans_cfg.rx_buffer, sizeof(send));
+            }
+
+            TEST_ESP_OK(spi_bus_remove_device(dev_handle));
+            TEST_ESP_OK(spi_bus_free(periph));
+        }
+    }
+
+    esp_sleep_set_sleep_context(NULL);
+#if ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(false));
+#endif
+}
+#endif  // !CONFIG_IDF_TARGET_ESP32P4

components/esp_driver_spi/test_apps/master/main/test_spi_master_sct.c

@@ -15,6 +15,9 @@
 #include "esp_heap_caps.h"
 #include "driver/spi_master.h"
 #include "esp_private/spi_master_internal.h"
+#include "esp_private/sleep_cpu.h"
+#include "esp_private/esp_sleep_internal.h"
+#include "esp_private/esp_pmu.h"
 #include "driver/spi_slave_hd.h"
 #include "driver/spi_slave.h"
 #include "soc/spi_pins.h"
@@ -22,7 +25,6 @@
 
 __attribute__((unused)) static const char *TAG = "SCT";
 
-#if (SOC_SPI_SUPPORT_SLAVE_HD_VER2 && SOC_SPI_SCT_SUPPORTED)
 /*-----------------------------------------------------------
  * HD SCT Functional Test
  *-----------------------------------------------------------*/
@@ -230,7 +232,6 @@ TEST_CASE_MULTIPLE_DEVICES("SPI_Master_SCT_HD_Functional", "[spi_ms]", hd_master
 TEST_CASE("spi_master: test_sct_dma_desc_oob_on_tail", "[spi]")
 {
     spi_device_handle_t handle;
-
     spi_bus_config_t buscfg = SPI_BUS_TEST_DEFAULT_CONFIG();
     buscfg.max_transfer_sz = 4092 * 8;
 
@@ -291,4 +292,127 @@ TEST_CASE("spi_master: test_sct_dma_desc_oob_on_tail", "[spi]")
     TEST_ESP_OK(spi_bus_free(SPI2_HOST));
 }
 
-#endif  //#if (SOC_SPI_SUPPORT_SLAVE_HD_VER2 && SOC_SPI_SCT_SUPPORTED)
+/*-----------------------------------------------------------
+ * Sleep Retention Test
+ *-----------------------------------------------------------*/
+#define TEST_SLP_DATA_LEN               64
+//Master write, slave read, wrt slave reg
+#define TEST_SLP_BUF_ID                 12
+#define TEST_SLP_BUF_VAL                0x11223344
+
+static void sleep_master(void)
+{
+    // Prepare a TOP PD sleep
+    TEST_ESP_OK(esp_sleep_enable_timer_wakeup(1 * 1000 * 1000));
+#if ESP_SLEEP_POWER_DOWN_CPU
+    sleep_cpu_configure(true);
+#endif
+    esp_sleep_context_t sleep_ctx;
+    esp_sleep_set_sleep_context(&sleep_ctx);
+
+    spi_device_handle_t handle;
+    spi_bus_config_t buscfg = SPI_BUS_TEST_DEFAULT_CONFIG();
+    buscfg.max_transfer_sz = 4092 * 10;
+#if SOC_SPI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    buscfg.flags |= SPICOMMON_BUSFLAG_SLP_ALLOW_PD;
+#endif
+    spi_device_interface_config_t devcfg = SPI_DEVICE_TEST_DEFAULT_CONFIG();
+    devcfg.command_bits = 8;
+    devcfg.address_bits = 8;
+    devcfg.dummy_bits = 8;
+    devcfg.flags = SPI_DEVICE_HALFDUPLEX;
+    TEST_ESP_OK(spi_bus_initialize(SPI2_HOST, &buscfg, SPI_DMA_CH_AUTO));
+    TEST_ESP_OK(spi_bus_add_device(SPI2_HOST, &devcfg, &handle));
+    TEST_ESP_OK(spi_bus_multi_trans_mode_enable(handle, true));
+    unity_send_signal("Master ready");
+
+    //Test data preparation
+    uint32_t master_tx_val = TEST_SLP_BUF_VAL;
+    uint8_t *master_tx_buf = heap_caps_calloc(1, TEST_SLP_DATA_LEN, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
+    test_fill_random_to_buffers_dualboard(199, master_tx_buf, master_tx_buf, TEST_SLP_DATA_LEN);
+    //---------------------Master TX---------------------------//
+    spi_multi_transaction_t *ret_seg_trans = NULL;
+    spi_multi_transaction_t tx_seg_trans[3] = {
+        {
+            .base = {
+                .cmd = 0x1,
+                .addr = TEST_SLP_BUF_ID,
+                .length = 4 * 8,
+                .tx_buffer = (uint8_t *) &master_tx_val,
+            },
+        },
+        {
+            .base = {
+                .cmd = 0x3,
+                .addr = 0xf2,
+                .length = TEST_SLP_DATA_LEN * 8,
+                .tx_buffer = master_tx_buf,
+            },
+            .dummy_bits = 8,
+        },
+        {
+            .base = {
+                .cmd = 0x7,
+            },
+        },
+    };
+
+    unity_wait_for_signal("Slave ready");
+    printf("Going into sleep with power down ...\n");
+    TEST_ESP_OK(esp_light_sleep_start());
+    printf("Waked up!\n");
+    // check if the sleep happened as expected
+    TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_request_result);
+#if SOC_SPI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    // check if the power domain also is powered down
+    TEST_ASSERT_EQUAL((buscfg.flags & SPICOMMON_BUSFLAG_SLP_ALLOW_PD) ? PMU_SLEEP_PD_TOP : 0, (sleep_ctx.sleep_flags) & PMU_SLEEP_PD_TOP);
+#endif
+    TEST_ESP_OK(spi_device_queue_multi_trans(handle, tx_seg_trans, 3, portMAX_DELAY));
+    TEST_ESP_OK(spi_device_get_multi_trans_result(handle, &ret_seg_trans, portMAX_DELAY));
+    TEST_ASSERT(ret_seg_trans == tx_seg_trans);
+    ESP_LOG_BUFFER_HEX("Master tx", master_tx_buf, TEST_SLP_DATA_LEN);
+
+    free(master_tx_buf);
+    TEST_ESP_OK(spi_bus_multi_trans_mode_enable(handle, false));
+    TEST_ESP_OK(spi_bus_remove_device(handle));
+    TEST_ESP_OK(spi_bus_free(SPI2_HOST));
+    esp_sleep_set_sleep_context(NULL);
+#if ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(false));
+#endif
+}
+
+static void sleep_slave(void)
+{
+    spi_bus_config_t buscfg = SPI_BUS_TEST_DEFAULT_CONFIG();
+    spi_slave_hd_slot_config_t slave_hd_cfg = SPI_SLOT_TEST_DEFAULT_CONFIG();
+    slave_hd_cfg.dma_chan = SPI_DMA_CH_AUTO,
+    TEST_ESP_OK(spi_slave_hd_init(SPI2_HOST, &buscfg, &slave_hd_cfg));
+
+    //Test data preparation
+    uint32_t slave_rx_val = 0;
+    uint8_t *slave_rx_buf = heap_caps_calloc(1, TEST_SLP_DATA_LEN, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
+    uint8_t *master_tx_buf = heap_caps_calloc(1, TEST_SLP_DATA_LEN, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
+    test_fill_random_to_buffers_dualboard(199, master_tx_buf, master_tx_buf, TEST_SLP_DATA_LEN);
+    //---------------------Slave RX---------------------------//
+    spi_slave_hd_data_t *ret_trans = NULL;
+    spi_slave_hd_data_t slave_rx_trans = {
+        .data = slave_rx_buf,
+        .len = TEST_SLP_DATA_LEN,
+    };
+    unity_wait_for_signal("Master ready");
+    TEST_ESP_OK(spi_slave_hd_queue_trans(SPI2_HOST, SPI_SLAVE_CHAN_RX, &slave_rx_trans, portMAX_DELAY));
+    unity_send_signal("Slave ready");
+    TEST_ESP_OK(spi_slave_hd_get_trans_res(SPI2_HOST, SPI_SLAVE_CHAN_RX, &ret_trans, portMAX_DELAY));
+    TEST_ASSERT(ret_trans == &slave_rx_trans);
+
+    spitest_cmp_or_dump(master_tx_buf, slave_rx_buf, TEST_SLP_DATA_LEN);
+    spi_slave_hd_read_buffer(SPI2_HOST, TEST_SLP_BUF_ID, (uint8_t *)&slave_rx_val, 4);
+    ESP_LOGI("Slave", "Slave Reg[%d] value is: 0x%" PRIx32, TEST_SLP_BUF_ID, slave_rx_val);
+    TEST_ASSERT(slave_rx_val == TEST_SLP_BUF_VAL);
+
+    free(master_tx_buf);
+    free(slave_rx_buf);
+    TEST_ESP_OK(spi_slave_hd_deinit(SPI2_HOST));
+}
+TEST_CASE_MULTIPLE_DEVICES("test_spi_master_sct_sleep_retention", "[spi_ms]", sleep_master, sleep_slave);

components/esp_driver_spi/test_apps/master/sdkconfig.ci.defaults

@@ -1,2 +0,0 @@
-# don't delete.
-# used for CI to compile a default config when 'sdkconfig.ci.xxxx' is exist

components/esp_driver_spi/test_apps/master/sdkconfig.ci.release

@@ -1,3 +1,4 @@
+CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP=y
 CONFIG_COMPILER_OPTIMIZATION_SIZE=y
 CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_SIZE=y
 CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT=y

components/esp_driver_spi/test_apps/master/sdkconfig.defaults

@@ -1,2 +1,4 @@
 CONFIG_FREERTOS_HZ=1000
-CONFIG_ESP_TASK_WDT=n
+CONFIG_ESP_TASK_WDT_INIT=n
+# primitives for checking sleep internal state
+CONFIG_ESP_SLEEP_DEBUG=y