feat(i2s): support sleep retention

Author: L-KAYA

components/esp_driver_i2s/i2s_common.c

@@ -41,6 +41,7 @@
 
 #include "esp_private/i2s_platform.h"
 #include "esp_private/esp_clk.h"
+#include "esp_private/sleep_retention.h"
 
 #include "driver/gpio.h"
 #include "esp_private/gpio.h"
@@ -85,6 +86,34 @@ inline void *i2s_dma_calloc(i2s_chan_handle_t handle, size_t num, size_t size)
     Scope: This file only
  ----------------------------------------------------------------------------*/
 
+#if I2S_USE_RETENTION_LINK
+static esp_err_t s_i2s_create_sleep_retention_link_cb(void *arg)
+{
+    i2s_controller_t *i2s_obj = (i2s_controller_t *)arg;
+    ESP_RETURN_ON_ERROR(sleep_retention_entries_create(i2s_reg_retention_info[i2s_obj->id].entry_array,
+                                                       i2s_reg_retention_info[i2s_obj->id].array_size,
+                                                       REGDMA_LINK_PRI_I2S, i2s_obj->slp_retention_mod),
+                        TAG, "create retention link failed");
+    return ESP_OK;
+}
+
+static void s_i2s_create_retention_module(i2s_controller_t *i2s_obj)
+{
+    sleep_retention_module_t module = i2s_obj->slp_retention_mod;
+
+    _lock_acquire(&i2s_obj->mutex);
+    if (i2s_obj->retention_link_created == false) {
+        if (sleep_retention_module_allocate(module) != ESP_OK) {
+            // even though the sleep retention module create failed, I2S driver should still work, so just warning here
+            ESP_LOGW(TAG, "create retention module failed, power domain can't turn off");
+        } else {
+            i2s_obj->retention_link_created = true;
+        }
+    }
+    _lock_release(&i2s_obj->mutex);
+}
+#endif // I2S_USE_RETENTION_LINK
+
 static void i2s_tx_channel_start(i2s_chan_handle_t handle)
 {
     i2s_hal_tx_reset(&(handle->controller->hal));
@@ -175,6 +204,14 @@ static esp_err_t i2s_destroy_controller_obj(i2s_controller_t **i2s_obj)
 #if SOC_I2S_HW_VERSION_1
     i2s_ll_enable_dma((*i2s_obj)->hal.dev, false);
 #endif
+#if I2S_USE_RETENTION_LINK
+    if ((*i2s_obj)->slp_retention_mod) {
+        if ((*i2s_obj)->retention_link_created) {
+            sleep_retention_module_free((*i2s_obj)->slp_retention_mod);
+        }
+        sleep_retention_module_deinit((*i2s_obj)->slp_retention_mod);
+    }
+#endif  // I2S_USE_RETENTION_LINK
     free(*i2s_obj);
     *i2s_obj = NULL;
     return i2s_platform_release_occupation(I2S_CTLR_HP, id);
@@ -219,6 +256,25 @@ static i2s_controller_t *i2s_acquire_controller_obj(int id)
             adc_ll_digi_set_data_source(0);
         }
 #endif
+
+#if I2S_USE_RETENTION_LINK
+        sleep_retention_module_t module = i2s_periph_signal[id].retention_module;
+        sleep_retention_module_init_param_t init_param = {
+            .cbs = {
+                .create = {
+                    .handle = s_i2s_create_sleep_retention_link_cb,
+                    .arg = i2s_obj,
+                },
+            },
+            .depends = BIT(SLEEP_RETENTION_MODULE_CLOCK_SYSTEM)
+        };
+        if (sleep_retention_module_init(module, &init_param) == ESP_OK) {
+            i2s_obj->slp_retention_mod = module;
+        } else {
+            // even the sleep retention module init failed, I2S driver should still work, so just warning here
+            ESP_LOGW(TAG, "init sleep retention failed for I2S%d, power domain may be turned off during sleep", id);
+        }
+#endif  // I2S_USE_RETENTION_LINK
     } else {
         free(pre_alloc);
         portENTER_CRITICAL(&g_i2s.spinlock);
@@ -879,6 +935,9 @@ esp_err_t i2s_new_channel(const i2s_chan_config_t *chan_cfg, i2s_chan_handle_t *
     ESP_RETURN_ON_FALSE(chan_cfg->id < SOC_I2S_NUM || chan_cfg->id == I2S_NUM_AUTO, ESP_ERR_INVALID_ARG, TAG, "invalid I2S port id");
     ESP_RETURN_ON_FALSE(chan_cfg->dma_desc_num >= 2, ESP_ERR_INVALID_ARG, TAG, "there should be at least 2 DMA buffers");
     ESP_RETURN_ON_FALSE(chan_cfg->intr_priority >= 0 && chan_cfg->intr_priority <= 7, ESP_ERR_INVALID_ARG, TAG, "intr_priority should be within 0~7");
+#if !SOC_I2S_SUPPORT_SLEEP_RETENTION
+    ESP_RETURN_ON_FALSE(!chan_cfg->backup_before_sleep, ESP_ERR_NOT_SUPPORTED, TAG, "register back up is not supported");
+#endif
 
     esp_err_t ret = ESP_OK;
     i2s_controller_t *i2s_obj = NULL;
@@ -937,6 +996,11 @@ esp_err_t i2s_new_channel(const i2s_chan_config_t *chan_cfg, i2s_chan_handle_t *
     if ((tx_handle != NULL) && (rx_handle != NULL)) {
         i2s_obj->full_duplex = true;
     }
+#if I2S_USE_RETENTION_LINK
+    if (chan_cfg->backup_before_sleep) {
+        s_i2s_create_retention_module(i2s_obj);
+    }
+#endif
 
     return ESP_OK;
     /* i2s_obj allocated but register channel failed */

components/esp_driver_i2s/i2s_private.h

@@ -6,6 +6,7 @@
 
 #pragma once
 
+#include <sys/lock.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/semphr.h"
 #include "freertos/queue.h"
@@ -25,6 +26,7 @@
 #endif
 #include "esp_private/periph_ctrl.h"
 #include "esp_private/esp_gpio_reserve.h"
+#include "esp_private/sleep_retention.h"
 #include "esp_pm.h"
 #include "esp_err.h"
 #include "sdkconfig.h"
@@ -56,6 +58,8 @@ extern "C" {
 #define I2S_RCC_ATOMIC()
 #endif
 
+#define I2S_USE_RETENTION_LINK  (SOC_I2S_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP)
+
 #define I2S_NULL_POINTER_CHECK(tag, p)          ESP_RETURN_ON_FALSE((p), ESP_ERR_INVALID_ARG, tag, "input parameter '"#p"' is NULL")
 
 /**
@@ -130,6 +134,9 @@ typedef struct {
     bool                    full_duplex;    /*!< is full_duplex */
     i2s_chan_handle_t       tx_chan;        /*!< tx channel handler */
     i2s_chan_handle_t       rx_chan;        /*!< rx channel handler */
+    _lock_t                 mutex;          /*!< mutex for controller */
+    sleep_retention_module_t slp_retention_mod; /*!< Sleep retention module */
+    bool                    retention_link_created;  /*!< Whether the retention link is created */
     int                     mclk;           /*!< MCK out pin, shared by tx/rx*/
 #if CONFIG_IDF_TARGET_ESP32
     esp_clock_output_mapping_handle_t mclk_out_hdl; /*!< The handle of MCLK output signal */

components/esp_driver_i2s/include/driver/i2s_common.h

@@ -26,6 +26,7 @@ extern "C" {
     .dma_frame_num = 240, \
     .auto_clear_after_cb = false, \
     .auto_clear_before_cb = false, \
+    .backup_before_sleep = false, \
     .intr_priority = 0, \
 }
 
@@ -73,6 +74,9 @@ typedef struct {
     bool                auto_clear_before_cb; /*!< Set to auto clear DMA TX buffer before `on_sent` callback, I2S will always send zero automatically if no data to send
                                              *   So that user can access data in the callback that just finished to send.
                                              */
+    bool                backup_before_sleep; /*!< If set, the driver will backup/restore the I2S registers before/after entering/exist sleep mode.
+                                              By this approach, the system can power off I2S's power domain.
+                                              This can save power, but at the expense of more RAM being consumed */
     int                 intr_priority;      /*!< I2S interrupt priority, range [0, 7], if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3) */
 } i2s_chan_config_t;
 

components/esp_driver_i2s/test_apps/i2s/main/CMakeLists.txt

@@ -6,6 +6,10 @@ if(CONFIG_SOC_I2S_SUPPORTS_ETM AND CONFIG_SOC_GPIO_SUPPORT_ETM)
     set(srcs ${srcs} "test_i2s_etm.c")
 endif()
 
+if(CONFIG_SOC_I2S_SUPPORT_SLEEP_RETENTION)
+    list(APPEND srcs "test_i2s_slp_retention.c")
+endif()
+
 idf_component_register(SRCS ${srcs}
-                       PRIV_REQUIRES unity esp_driver_pcnt spi_flash esp_driver_gpio esp_driver_i2s
+                       PRIV_REQUIRES unity esp_driver_pcnt spi_flash esp_driver_gpio esp_driver_i2s esp_driver_uart
                        WHOLE_ARCHIVE)

components/esp_driver_i2s/test_apps/i2s/main/test_i2s.c

@@ -94,7 +94,7 @@ static void i2s_test_io_config(int mode)
     }
 }
 
-static void i2s_read_write_test(i2s_chan_handle_t tx_chan, i2s_chan_handle_t rx_chan)
+void i2s_read_write_test(i2s_chan_handle_t tx_chan, i2s_chan_handle_t rx_chan)
 {
 #define I2S_SEND_BUF_LEN    100
 #define I2S_RECV_BUF_LEN    10000

components/esp_driver_i2s/test_apps/i2s/main/test_i2s_slp_retention.c

@@ -0,0 +1,101 @@
+/*
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <stdio.h>
+#include <string.h>
+#include "sdkconfig.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "unity.h"
+#include "unity_test_utils.h"
+#include "driver/i2s_std.h"
+#include "driver/uart.h"
+#include "soc/i2s_struct.h"
+#include "esp_sleep.h"
+#include "esp_private/sleep_cpu.h"
+#include "esp_private/esp_sleep_internal.h"
+#include "esp_private/esp_pmu.h"
+#include "../../test_inc/test_i2s.h"
+
+#if SOC_I2S_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+
+extern void i2s_read_write_test(i2s_chan_handle_t tx_chan, i2s_chan_handle_t rx_chan);
+
+static void test_i2s_enter_light_sleep(int sec)
+{
+    esp_sleep_context_t sleep_ctx;
+    esp_sleep_set_sleep_context(&sleep_ctx);
+    printf("Entering light sleep for %d seconds\n", sec);
+#if ESP_SLEEP_POWER_DOWN_CPU
+    printf("Enable CPU power down\n");
+    TEST_ESP_OK(sleep_cpu_configure(true));
+#endif
+    uart_wait_tx_idle_polling(CONFIG_ESP_CONSOLE_UART_NUM);
+    TEST_ESP_OK(esp_sleep_enable_timer_wakeup(sec * 1000 * 1000));
+    TEST_ESP_OK(esp_light_sleep_start());
+
+#if ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(false));
+#endif
+    printf("Woke up from light sleep\n");
+
+    TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_request_result);
+    TEST_ASSERT_EQUAL(PMU_SLEEP_PD_TOP, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+    esp_sleep_set_sleep_context(NULL);
+}
+
+TEST_CASE("I2S_sleep_retention_test", "[i2s]")
+{
+    i2s_chan_handle_t tx_handle;
+    i2s_chan_handle_t rx_handle;
+
+    i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(I2S_NUM_0, I2S_ROLE_MASTER);
+    chan_cfg.backup_before_sleep = true;
+    i2s_std_config_t std_cfg = {
+        .clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(SAMPLE_RATE),
+        .slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(SAMPLE_BITS, I2S_SLOT_MODE_STEREO),
+        .gpio_cfg = I2S_TEST_MASTER_DEFAULT_PIN,
+    };
+    std_cfg.gpio_cfg.din = std_cfg.gpio_cfg.dout;
+    TEST_ESP_OK(i2s_new_channel(&chan_cfg, &tx_handle, &rx_handle));
+    TEST_ESP_OK(i2s_channel_init_std_mode(tx_handle, &std_cfg));
+    TEST_ESP_OK(i2s_channel_init_std_mode(rx_handle, &std_cfg));
+
+    /* I2S retention is depended on GDMA retention.
+     * Only take two registers as sample to check the I2S retention when GDMA retention has not been supported. */
+#if !SOC_GDMA_SUPPORT_SLEEP_RETENTION
+    i2s_tx_conf_reg_t tx_reg_before_slp = I2S0.tx_conf;
+    i2s_rx_conf_reg_t rx_reg_before_slp = I2S0.rx_conf;
+#endif
+
+    /* Enter light sleep and wake up after 1 second */
+    test_i2s_enter_light_sleep(1);
+
+#if SOC_GDMA_SUPPORT_SLEEP_RETENTION
+    /* Check whether I2S can work correctly after light sleep */
+    TEST_ESP_OK(i2s_channel_enable(tx_handle));
+    TEST_ESP_OK(i2s_channel_enable(rx_handle));
+    i2s_read_write_test(tx_handle, rx_handle);
+#else
+    /* Only check whether the register values are restored if GDMA retention has not been supported */
+    i2s_tx_conf_reg_t tx_reg_after_slp = I2S0.tx_conf;
+    i2s_rx_conf_reg_t rx_reg_after_slp = I2S0.rx_conf;
+
+    TEST_ASSERT_EQUAL_UINT32(tx_reg_before_slp.val, tx_reg_after_slp.val);
+    TEST_ASSERT_EQUAL_UINT32(rx_reg_before_slp.val, rx_reg_after_slp.val);
+
+    TEST_ESP_OK(i2s_channel_enable(tx_handle));
+    TEST_ESP_OK(i2s_channel_enable(rx_handle));
+#endif
+
+    printf("I2S works as expected after light sleep\n");
+
+    TEST_ESP_OK(i2s_channel_disable(tx_handle));
+    TEST_ESP_OK(i2s_channel_disable(rx_handle));
+    TEST_ESP_OK(i2s_del_channel(tx_handle));
+    TEST_ESP_OK(i2s_del_channel(rx_handle));
+}
+
+#endif  // SOC_I2S_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP

components/esp_driver_i2s/test_apps/i2s/pytest_i2s.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 import pytest
 from pytest_embedded import Dut

components/esp_driver_i2s/test_apps/i2s/sdkconfig.ci.release

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

components/esp_driver_i2s/test_apps/i2s/sdkconfig.defaults

@@ -1,2 +1,4 @@
 CONFIG_I2S_ENABLE_DEBUG_LOG=y
 CONFIG_ESP_TASK_WDT_EN=n
+# primitives for checking sleep internal state
+CONFIG_ESP_SLEEP_DEBUG=y

components/soc/esp32/i2s_periph.c

@@ -29,7 +29,6 @@ const i2s_signal_conn_t i2s_periph_signal[SOC_I2S_NUM] = {
         .data_in_sig  = I2S0I_DATA_IN15_IDX,
 
         .irq          = ETS_I2S0_INTR_SOURCE,
-        .module       = PERIPH_I2S0_MODULE,
     },
     {
         .mck_out_sig  = -1, // Unavailable
@@ -49,6 +48,5 @@ const i2s_signal_conn_t i2s_periph_signal[SOC_I2S_NUM] = {
         .data_in_sig  = I2S1I_DATA_IN15_IDX,
 
         .irq          = ETS_I2S1_INTR_SOURCE,
-        .module       = PERIPH_I2S1_MODULE,
     }
 };