Merge branch 'feature/support_i2s_retention' into 'master'

feat(i2s): support sleep retention

Closes IDF-8468, IDF-9754, IDF-9783, and IDF-10343

See merge request espressif/esp-idf!33529

Author: L-KAYA

components/esp_driver_i2s/i2s_common.c

@@ -41,6 +41,9 @@
 
 #include "esp_private/i2s_platform.h"
 #include "esp_private/esp_clk.h"
+#if SOC_I2S_SUPPORT_SLEEP_RETENTION
+#include "esp_private/sleep_retention.h"
+#endif
 
 #include "driver/gpio.h"
 #include "esp_private/gpio.h"
@@ -85,6 +88,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 +206,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 +258,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_reg_retention_info[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 +937,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->allow_pd, 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 +998,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->allow_pd) {
+        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,9 @@
 #endif
 #include "esp_private/periph_ctrl.h"
 #include "esp_private/esp_gpio_reserve.h"
+#if SOC_I2S_SUPPORT_SLEEP_RETENTION
+#include "esp_private/sleep_retention.h"
+#endif
 #include "esp_pm.h"
 #include "esp_err.h"
 #include "sdkconfig.h"
@@ -56,6 +60,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 +136,11 @@ 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 */
+#if SOC_I2S_SUPPORT_SLEEP_RETENTION
+    sleep_retention_module_t slp_retention_mod; /*!< Sleep retention module */
+    bool                    retention_link_created;  /*!< Whether the retention link is created */
+#endif
     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, \
+    .allow_pd = false, \
     .intr_priority = 0, \
 }
 
@@ -73,6 +74,10 @@ 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                allow_pd;           /*!< Set to allow power down. When this flag 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/.build-test-rules.yml

@@ -3,10 +3,6 @@
 components/esp_driver_i2s/test_apps/i2s:
   disable:
     - if: SOC_I2S_SUPPORTED != 1
-  disable_test:
-    - if: IDF_TARGET == "esp32c5"
-      temporary: true
-      reason: target test failed  # TODO [ESP32C5] IDF-10343
   depends_components:
     - esp_driver_i2s
     - esp_driver_pcnt

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

@@ -1,11 +1,12 @@
 set(srcs "test_app_main.c"
          "test_i2s.c"
-         "test_i2s_iram.c")
+         "test_i2s_iram.c"
+         "test_i2s_sleep.c")
 
 if(CONFIG_SOC_I2S_SUPPORTS_ETM AND CONFIG_SOC_GPIO_SUPPORT_ETM)
     set(srcs ${srcs} "test_i2s_etm.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
@@ -776,7 +776,7 @@ static void i2s_test_common_sample_rate(i2s_chan_handle_t rx_chan, i2s_std_clk_c
         printf("[%"PRIu32" Hz] %d pulses, expected %d, err %d\n", test_freq[i], real_pulse, expt_pulse, real_pulse - expt_pulse);
         TEST_ESP_OK(i2s_channel_disable(rx_chan));
         // Check if the error between real pulse number and expected pulse number is within 1%
-        TEST_ASSERT_INT_WITHIN(expt_pulse * 0.01, expt_pulse, real_pulse);
+        TEST_ASSERT_INT_WITHIN(expt_pulse * 0.02, expt_pulse, real_pulse);
     }
     TEST_ESP_OK(pcnt_del_channel(pcnt_chan));
     TEST_ESP_OK(pcnt_unit_stop(pcnt_unit));

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

@@ -0,0 +1,145 @@
+/*
+ * 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"
+
+#define TEST_I2S_PD_SLEEP   (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 s_test_i2s_enter_light_sleep(int sec, bool allow_power_down)
+{
+    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);
+#if SOC_I2S_SUPPORT_SLEEP_RETENTION
+    // check if the power domain also is powered down
+    TEST_ASSERT_EQUAL(allow_power_down ? PMU_SLEEP_PD_TOP : 0, (sleep_ctx.sleep_flags) & PMU_SLEEP_PD_TOP);
+#endif
+    esp_sleep_set_sleep_context(NULL);
+}
+
+static void s_test_i2s_sleep(i2s_chan_handle_t tx_handle, i2s_chan_handle_t rx_handle, bool allow_power_down)
+{
+    /* Enter light sleep before I2S channel enabled and wake up after 1 second */
+    s_test_i2s_enter_light_sleep(1, allow_power_down);
+    /* 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);
+}
+
+static void s_test_i2s_power_on_sleep(i2s_chan_handle_t tx_handle, i2s_chan_handle_t rx_handle)
+{
+    s_test_i2s_sleep(tx_handle, rx_handle, false);
+}
+
+#if TEST_I2S_PD_SLEEP
+static void s_test_i2s_power_down_sleep(i2s_chan_handle_t tx_handle, i2s_chan_handle_t rx_handle)
+{
+#if SOC_GDMA_SUPPORT_SLEEP_RETENTION
+    s_test_i2s_sleep(tx_handle, rx_handle, true);
+#else
+    /* 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. */
+    i2s_tx_conf_reg_t tx_reg_before_slp = I2S0.tx_conf;
+    i2s_rx_conf_reg_t rx_reg_before_slp = I2S0.rx_conf;
+    /* Enter light sleep before I2S channel enabled and wake up after 1 second */
+    s_test_i2s_enter_light_sleep(1, true);
+    /* 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));
+
+    tx_reg_before_slp.val = I2S0.tx_conf.val;
+    rx_reg_before_slp.val = I2S0.rx_conf.val;
+    /* Enter light sleep before I2S channel enabled and wake up after 1 second */
+    s_test_i2s_enter_light_sleep(1, true);
+    /* Only check whether the register values are restored if GDMA retention has not been supported */
+    tx_reg_after_slp.val = I2S0.tx_conf.val;
+    rx_reg_after_slp.val = I2S0.rx_conf.val;
+
+    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);
+#endif  // SOC_GDMA_SUPPORT_SLEEP_RETENTION
+}
+#endif  // TEST_I2S_PD_SLEEP
+
+void test_i2s_sleep_usability(bool allow_power_down)
+{
+    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.allow_pd = allow_power_down;
+    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));
+
+    if (!allow_power_down) {
+        s_test_i2s_power_on_sleep(tx_handle, rx_handle);
+    }
+#if TEST_I2S_PD_SLEEP
+    else {
+        s_test_i2s_power_down_sleep(tx_handle, 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));
+}
+
+TEST_CASE("I2S_light_sleep_usability_test", "[i2s]")
+{
+    printf("\nTesting I2S power on light sleep...\n");
+    test_i2s_sleep_usability(false);
+#if TEST_I2S_PD_SLEEP
+    printf("\nTesting I2S power down light sleep...\n");
+    test_i2s_sleep_usability(true);
+#endif
+}

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
@@ -7,7 +7,7 @@
 @pytest.mark.esp32
 @pytest.mark.esp32s2
 @pytest.mark.esp32c3
-# @pytest.mark.esp32c5  # TODO: [ESP32C5] IDF-10343
+@pytest.mark.esp32c5
 @pytest.mark.esp32c6
 @pytest.mark.esp32s3
 @pytest.mark.esp32h2

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