feat(i2s): support i2s & apll on esp32s31

components/esp_driver_i2s/i2s_common.c

@@ -792,6 +792,17 @@ esp_err_t i2s_init_dma_intr(i2s_chan_handle_t handle, int intr_flag)
     gdma_trigger_t trig = {0};
 
     switch (port_id) {
+#if I2S_LL_SUPPORT(GDMA_RECOMB)
+    // Minimum support for GDMA channels on esp32s31
+    case I2S_NUM_0:
+        trig.instance_id = SOC_GDMA_TRIG_PERIPH_I2S0CH0;
+        trig.bus_id = SOC_GDMA_TRIG_PERIPH_I2S0CH0_BUS;
+        break;
+    case I2S_NUM_1:
+        trig.instance_id = SOC_GDMA_TRIG_PERIPH_I2S1CH0;
+        trig.bus_id = SOC_GDMA_TRIG_PERIPH_I2S1CH0_BUS;
+        break;
+#else
 #if I2S_LL_GET(INST_NUM) > 2
     case I2S_NUM_2:
         trig = GDMA_MAKE_TRIGGER(GDMA_TRIG_PERIPH_I2S, 2);
@@ -805,6 +816,7 @@ esp_err_t i2s_init_dma_intr(i2s_chan_handle_t handle, int intr_flag)
     case I2S_NUM_0:
         trig = GDMA_MAKE_TRIGGER(GDMA_TRIG_PERIPH_I2S, 0);
         break;
+#endif
     default:
         ESP_LOGE(TAG, "Unsupported I2S port number");
         return ESP_ERR_NOT_SUPPORTED;

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

@@ -19,6 +19,9 @@ components/esp_driver_i2s/test_apps/i2s_multi_dev:
     - if: IDF_TARGET in ["esp32c61"]  # TODO: [ESP32C61] IDF-11442
       temporary: true
       reason: lack of runners
+    - if: IDF_TARGET in ["esp32s31"]
+      temporary: true
+      reason: lack of s31 multi-device runner
   depends_components:
     - esp_driver_i2s
     - esp_driver_dma

components/esp_driver_i2s/test_apps/i2s/README.md

@@ -1,2 +1,2 @@
-| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
-| ----------------- | ----- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- |
+| ----------------- | ----- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |

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

@@ -931,7 +931,7 @@ static void i2s_test_common_sample_rate(i2s_chan_handle_t rx_chan, i2s_std_clk_c
     // 196000 Hz sample rate doesn't support on PLL_96M target
     case_cnt = 15;
 #endif
-#if I2S_LL_SUPPORT_XTAL
+#if I2S_LL_SUPPORT(XTAL)
     // Can't support a very high sample rate while using XTAL as clock source
     if (clk_cfg->clk_src == I2S_CLK_SRC_XTAL) {
         case_cnt = 10;
@@ -982,7 +982,7 @@ TEST_CASE("I2S_default_PLL_clock_test", "[i2s]")
     std_cfg.clk_cfg.clk_src = I2S_LL_DEFAULT_CLK_SRC;
 #endif
     i2s_test_common_sample_rate(rx_handle, &std_cfg.clk_cfg);
-#if I2S_LL_SUPPORT_XTAL
+#if I2S_LL_SUPPORT(XTAL)
     std_cfg.clk_cfg.clk_src = I2S_CLK_SRC_XTAL;
     i2s_test_common_sample_rate(rx_handle, &std_cfg.clk_cfg);
 #endif
@@ -1046,6 +1046,9 @@ TEST_CASE("I2S_package_lost_test", "[i2s]")
         .slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_32BIT, I2S_SLOT_MODE_STEREO),
         .gpio_cfg = I2S_TEST_MASTER_DEFAULT_PIN,
     };
+#if CONFIG_IDF_TARGET_ESP32S31  // esp32s31 doesn't support PLL as clock source, use APLL instead
+    std_cfg.clk_cfg.clk_src = I2S_CLK_SRC_APLL;
+#endif
 
     TEST_ESP_OK(i2s_new_channel(&chan_cfg, NULL, &rx_handle));
     TEST_ESP_OK(i2s_channel_init_std_mode(rx_handle, &std_cfg));

components/esp_driver_i2s/test_apps/i2s/pytest_i2s.py

@@ -3,6 +3,7 @@
 import pytest
 from pytest_embedded import Dut
 from pytest_embedded_idf.utils import idf_parametrize
+from pytest_embedded_idf.utils import soc_filtered_targets
 
 
 @pytest.mark.generic
@@ -16,9 +17,10 @@ from pytest_embedded_idf.utils import idf_parametrize
 )
 @idf_parametrize(
     'target',
-    ['esp32', 'esp32s2', 'esp32c3', 'esp32c6', 'esp32h2', 'esp32p4', 'esp32c61'],
+    soc_filtered_targets('SOC_I2S_SUPPORTED == 1 and IDF_TARGET not in ["esp32c5", "esp32s3"]'),
     indirect=['target'],
 )
+@pytest.mark.temp_skip_ci(targets=['esp32h21', 'esp32h4'], reason='lack of runners')
 def test_i2s(dut: Dut) -> None:
     dut.run_all_single_board_cases()
 

components/esp_driver_i2s/test_apps/i2s_multi_dev/README.md

@@ -1,3 +1,3 @@
-| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 |
+| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 | ESP32-S31 |
-| ----------------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- |
+| ----------------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | --------- |
 

components/esp_driver_i2s/test_apps/i2s_multi_dev/pytest_i2s_multi_dev.py

@@ -7,6 +7,7 @@ from pytest_embedded_idf.utils import soc_filtered_targets
 
 @pytest.mark.generic_multi_device
 @pytest.mark.temp_skip_ci(targets=['esp32c61'], reason='p4 rev3 migration # TODO: IDF-11442')
+@pytest.mark.temp_skip_ci(targets=['esp32s31'], reason='lack of s31 multi-device runner # TODO: IDFCI-10334')
 @pytest.mark.parametrize('count', [2], indirect=True)
 @idf_parametrize('target', soc_filtered_targets('SOC_I2S_SUPPORTS_TDM == 1'), indirect=['target'])
 def test_i2s_multi_dev(case_tester) -> None:  # type: ignore

components/esp_hal_clock/esp32s31/include/hal/clk_tree_ll.h

@@ -16,6 +16,8 @@
 #include "soc/lp_clkrst_struct.h"
 #include "soc/hp_alive_sys_reg.h"
 #include "soc/hp_alive_sys_struct.h"
+#include "hal/regi2c_ctrl.h"
+#include "soc/regi2c_apll.h"
 #include "soc/pmu_reg.h"
 #include "hal/clkout_channel.h"
 #include "hal/assert.h"
@@ -463,7 +465,12 @@ static inline __attribute__((always_inline)) bool clk_ll_mpll_calibration_is_don
  */
 static inline __attribute__((always_inline)) void clk_ll_apll_get_config(uint32_t *o_div, uint32_t *sdm0, uint32_t *sdm1, uint32_t *sdm2)
 {
-    // TODO: IDF-14771, IDF-14750
+    uint32_t apll_sdm = HAL_FORCE_READ_U32_REG_FIELD(LP_CLKRST.apll_sdm, apll_sdm);
+
+    *o_div = HAL_FORCE_READ_U32_REG_FIELD(LP_CLKRST.apll_div, apll_out_div);
+    *sdm0 = apll_sdm & 0xFF;
+    *sdm1 = (apll_sdm >> 8) & 0xFF;
+    *sdm2 = (apll_sdm >> 16) & 0x3F;
 }
 
 /**
@@ -476,7 +483,8 @@ static inline __attribute__((always_inline)) void clk_ll_apll_get_config(uint32_
  */
 static inline __attribute__((always_inline)) void clk_ll_apll_set_config(uint32_t o_div, uint32_t sdm0, uint32_t sdm1, uint32_t sdm2)
 {
-    // TODO: IDF-14771, IDF-14750
+    HAL_FORCE_MODIFY_U32_REG_FIELD(LP_CLKRST.apll_div, apll_out_div, o_div);
+    HAL_FORCE_MODIFY_U32_REG_FIELD(LP_CLKRST.apll_sdm, apll_sdm, (sdm2 << 16) | (sdm1 << 8) | sdm0);
 }
 
 /**
@@ -484,7 +492,9 @@ static inline __attribute__((always_inline)) void clk_ll_apll_set_config(uint32_
  */
 static inline __attribute__((always_inline)) void clk_ll_apll_set_calibration(void)
 {
-    // TODO: IDF-14771, IDF-14750
+    REGI2C_WRITE(I2C_APLL, I2C_APLL_IR_CAL_DELAY, CLK_LL_APLL_CAL_DELAY_1);
+    REGI2C_WRITE(I2C_APLL, I2C_APLL_IR_CAL_DELAY, CLK_LL_APLL_CAL_DELAY_2);
+    REGI2C_WRITE(I2C_APLL, I2C_APLL_IR_CAL_DELAY, CLK_LL_APLL_CAL_DELAY_3);
 }
 
 /**
@@ -494,8 +504,7 @@ static inline __attribute__((always_inline)) void clk_ll_apll_set_calibration(vo
  */
 static inline __attribute__((always_inline)) bool clk_ll_apll_calibration_is_done(void)
 {
-    // TODO: IDF-14771, IDF-14750
+    return REG_GET_BIT(HP_SYS_CLKRST_ANA_PLL_CTRL0_REG, HP_SYS_CLKRST_REG_PLLA_CAL_END);
-    return 0;
 }
 
 /**

components/esp_hal_i2s/esp32/include/hal/i2s_ll.h

@@ -22,6 +22,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_BUS_WIDTH        24
 #define I2S_LL_INST_NUM         2
 #define I2S_LL_TRANS_SIZE_ALIGN_WORD  1  // I2S DMA transfer size must be aligned to word

components/esp_hal_i2s/esp32c3/include/hal/i2s_ll.h

@@ -21,6 +21,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         1
 
 #ifdef __cplusplus

components/esp_hal_i2s/esp32c5/include/hal/i2s_ll.h

@@ -23,6 +23,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         1
 
 #ifdef __cplusplus

components/esp_hal_i2s/esp32c6/include/hal/i2s_ll.h

@@ -22,6 +22,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         1
 
 #ifdef __cplusplus

components/esp_hal_i2s/esp32c61/include/hal/i2s_ll.h

@@ -23,6 +23,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         1
 
 #ifdef __cplusplus

components/esp_hal_i2s/esp32h2/include/hal/i2s_ll.h

@@ -22,6 +22,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         1
 
 #ifdef __cplusplus

components/esp_hal_i2s/esp32h21/include/hal/i2s_ll.h

@@ -22,6 +22,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         1
 
 #ifdef __cplusplus
@@ -247,9 +248,9 @@ static inline void i2s_ll_tx_clk_set_src(i2s_dev_t *hw, i2s_clock_src_t src)
     case I2S_CLK_SRC_PLL_96M:
         PCR.i2s_tx_clkm_conf.i2s_tx_clkm_sel = 1;
         break;
-    // case I2S_CLK_SRC_PLL_64M:
+    case I2S_CLK_SRC_XTAL_X2:
-    //     PCR.i2s_tx_clkm_conf.i2s_tx_clkm_sel = 2;
+        PCR.i2s_tx_clkm_conf.i2s_tx_clkm_sel = 2;
-    //     break;
+        break;
     case I2S_CLK_SRC_EXTERNAL:
         PCR.i2s_tx_clkm_conf.i2s_tx_clkm_sel = 3;
         break;
@@ -275,9 +276,9 @@ static inline void i2s_ll_rx_clk_set_src(i2s_dev_t *hw, i2s_clock_src_t src)
     case I2S_CLK_SRC_PLL_96M:
         PCR.i2s_rx_clkm_conf.i2s_rx_clkm_sel = 1;
         break;
-    // case I2S_CLK_SRC_PLL_64M:
+    case I2S_CLK_SRC_XTAL_X2:
-    //     PCR.i2s_rx_clkm_conf.i2s_rx_clkm_sel = 2;
+        PCR.i2s_rx_clkm_conf.i2s_rx_clkm_sel = 2;
-    //     break;
+        break;
     case I2S_CLK_SRC_EXTERNAL:
         PCR.i2s_rx_clkm_conf.i2s_rx_clkm_sel = 3;
         break;

components/esp_hal_i2s/esp32h4/include/hal/i2s_ll.h

@@ -23,6 +23,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         1
 
 #ifdef __cplusplus
@@ -251,9 +252,9 @@ static inline void i2s_ll_tx_clk_set_src(i2s_dev_t *hw, i2s_clock_src_t src)
     case I2S_CLK_SRC_PLL_96M:
         PCR.i2s_tx_clkm_conf.i2s_tx_clkm_sel = 1;
         break;
-    // case I2S_CLK_SRC_PLL_64M:
+    case I2S_CLK_SRC_XTAL_X2:
-    //     PCR.i2s_tx_clkm_conf.i2s_tx_clkm_sel = 2;
+        PCR.i2s_tx_clkm_conf.i2s_tx_clkm_sel = 2;
-    //     break;
+        break;
     case I2S_CLK_SRC_EXTERNAL:
         PCR.i2s_tx_clkm_conf.i2s_tx_clkm_sel = 3;
         break;
@@ -279,9 +280,9 @@ static inline void i2s_ll_rx_clk_set_src(i2s_dev_t *hw, i2s_clock_src_t src)
     case I2S_CLK_SRC_PLL_96M:
         PCR.i2s_rx_clkm_conf.i2s_rx_clkm_sel = 1;
         break;
-    // case I2S_CLK_SRC_PLL_64M:
+    case I2S_CLK_SRC_XTAL_X2:
-    //     PCR.i2s_rx_clkm_conf.i2s_rx_clkm_sel = 2;
+        PCR.i2s_rx_clkm_conf.i2s_rx_clkm_sel = 2;
-    //     break;
+        break;
     case I2S_CLK_SRC_EXTERNAL:
         PCR.i2s_rx_clkm_conf.i2s_rx_clkm_sel = 3;
         break;

components/esp_hal_i2s/esp32p4/include/hal/i2s_ll.h

@@ -25,6 +25,7 @@
 #include "hal/config.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         3
 
 #ifdef __cplusplus

components/esp_hal_i2s/esp32s2/include/hal/i2s_ll.h

@@ -24,6 +24,7 @@
 #include "hal/assert.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_BUS_WIDTH        24
 #define I2S_LL_INST_NUM         1
 

components/esp_hal_i2s/esp32s3/include/hal/i2s_ll.h

@@ -21,6 +21,7 @@
 #include "hal/hal_utils.h"
 
 #define I2S_LL_GET(_attr)       I2S_LL_ ## _attr
+#define I2S_LL_SUPPORT(_feat)   I2S_LL_SUPPORT_ ## _feat
 #define I2S_LL_INST_NUM         2
 
 #ifdef __cplusplus

components/esp_hal_i2s/esp32s31/i2s_periph.c

@@ -0,0 +1,112 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "hal/i2s_periph.h"
+#include "soc/i2s_reg.h"
+#include "soc/gpio_sig_map.h"
+#include "soc/lp_gpio_sig_map.h"
+
+/*
+ Bunch of constants for every I2S peripheral: GPIO signals, irqs, hw addr of registers etc
+*/
+const i2s_signal_conn_t i2s_periph_signal[I2S_LL_GET(INST_NUM)] = {
+    [0] = {
+        .mck_out_sig  = I2S0_MCLK_PAD_OUT_IDX,
+        .mck_in_sig   = I2S0_MCLK_PAD_IN_IDX,
+
+        .m_tx_bck_sig = I2S0_O_BCK_PAD_OUT_IDX,
+        .m_rx_bck_sig = I2S0_I_BCK_PAD_OUT_IDX,
+        .m_tx_ws_sig  = I2S0_O_WS_PAD_OUT_IDX,
+        .m_rx_ws_sig  = I2S0_I_WS_PAD_OUT_IDX,
+
+        .s_tx_bck_sig = I2S0_O_BCK_PAD_IN_IDX,
+        .s_rx_bck_sig = I2S0_I_BCK_PAD_IN_IDX,
+        .s_tx_ws_sig  = I2S0_O_WS_PAD_IN_IDX,
+        .s_rx_ws_sig  = I2S0_I_WS_PAD_IN_IDX,
+
+        .data_out_sigs[0] = I2S0_O_SD_PAD_OUT_IDX,
+        .data_out_sigs[1] = I2S0_O_SD1_PAD_OUT_IDX,
+        .data_in_sigs[0]  = I2S0_I_SD_PAD_IN_IDX,
+        .data_in_sigs[1]  = I2S0_I_SD1_PAD_IN_IDX,
+        .data_in_sigs[2]  = I2S0_I_SD2_PAD_IN_IDX,
+        .data_in_sigs[3]  = I2S0_I_SD3_PAD_IN_IDX,
+
+        .irq          = ETS_I2S0_INTR_SOURCE,
+    },
+    [1] = {
+        .mck_out_sig  = I2S1_MCLK_PAD_OUT_IDX,
+        .mck_in_sig   = I2S1_MCLK_PAD_IN_IDX,
+
+        .m_tx_bck_sig = I2S1_O_BCK_PAD_OUT_IDX,
+        .m_rx_bck_sig = I2S1_I_BCK_PAD_OUT_IDX,
+        .m_tx_ws_sig  = I2S1_O_WS_PAD_OUT_IDX,
+        .m_rx_ws_sig  = I2S1_I_WS_PAD_OUT_IDX,
+
+        .s_tx_bck_sig = I2S1_O_BCK_PAD_IN_IDX,
+        .s_rx_bck_sig = I2S1_I_BCK_PAD_IN_IDX,
+        .s_tx_ws_sig  = I2S1_O_WS_PAD_IN_IDX,
+        .s_rx_ws_sig  = I2S1_I_WS_PAD_IN_IDX,
+
+        .data_out_sigs[0] = I2S1_O_SD_PAD_OUT_IDX,
+        .data_out_sigs[1] = -1,
+        .data_in_sigs[0]  = I2S1_I_SD_PAD_IN_IDX,
+        .data_in_sigs[1]  = -1,
+        .data_in_sigs[2]  = -1,
+        .data_in_sigs[3]  = -1,
+
+        .irq          = ETS_I2S1_INTR_SOURCE,
+    },
+};
+
+/**
+ * I2S Registers to be saved during sleep retention
+ * - I2S_RX_CONF_REG
+ * - I2S_TX_CONF_REG
+ * - I2S_RX_CONF1_REG
+ * - I2S_TX_CONF1_REG
+ * - I2S_RX_RECOMB_CTRL_REG
+ * - I2S_RX_RECOMB_DMA_CH0_REG
+ * - I2S_RX_RECOMB_DMA_CH1_REG
+ * - I2S_RX_RECOMB_DMA_CH2_REG
+ * - I2S_RX_RECOMB_DMA_CH3_REG
+ * - I2S_TX_PCM2PDM_CONF_REG
+ * - I2S_TX_PCM2PDM_CONF1_REG
+ * - I2S_RX_PDM2PCM_CONF_REG
+ * - I2S_RX_TDM_CTRL_REG
+ * - I2S_TX_TDM_CTRL_REG
+ * - I2S_RXEOF_NUM_REG
+ * - I2S_ETM_CONF_REG
+*/
+#define I2S_RETENTION_REGS_CNT 16
+#define I2S_RETENTION_REGS_BASE(i) I2S_RX_CONF_REG(i)
+static const uint32_t i2s_regs_map[4] = {0x123fff, 0x0, 0x0, 0x0};
+#define I2S_SLEEP_RETENTION_ENTRIES(i2s_port) {  \
+    /* Save/restore the register values */  \
+    [0] = { .config = REGDMA_LINK_ADDR_MAP_INIT(  \
+                REGDMA_I2S_LINK(0x00), \
+                I2S_RETENTION_REGS_BASE(i2s_port),  \
+                I2S_RETENTION_REGS_BASE(i2s_port), \
+                I2S_RETENTION_REGS_CNT, 0, 0, \
+                i2s_regs_map[0], i2s_regs_map[1], \
+                i2s_regs_map[2], i2s_regs_map[3]), \
+            .owner = ENTRY(0)}, \
+};
+
+static const regdma_entries_config_t i2s0_regs_retention[] = I2S_SLEEP_RETENTION_ENTRIES(0);
+static const regdma_entries_config_t i2s1_regs_retention[] = I2S_SLEEP_RETENTION_ENTRIES(1);
+
+const i2s_reg_retention_info_t i2s_reg_retention_info[I2S_LL_GET(INST_NUM)] = {
+    [0] = {
+        .retention_module = SLEEP_RETENTION_MODULE_I2S0,
+        .entry_array = i2s0_regs_retention,
+        .array_size = ARRAY_SIZE(i2s0_regs_retention)
+    },
+    [1] = {
+        .retention_module = SLEEP_RETENTION_MODULE_I2S1,
+        .entry_array = i2s1_regs_retention,
+        .array_size = ARRAY_SIZE(i2s1_regs_retention)
+    },
+};

components/esp_hw_support/port/esp32s31/esp_clk_tree.c

@@ -5,6 +5,7 @@
  */
 
 #include <stdint.h>
+#include <stdatomic.h>
 #include "esp_clk_tree.h"
 #include "esp_err.h"
 #include "esp_check.h"
@@ -16,6 +17,9 @@
 
 ESP_LOG_ATTR_TAG(TAG, "esp_clk_tree");
 
+static _Atomic int16_t s_pll_src_cg_ref_cnt[SOC_MOD_CLK_INVALID] = { 0 };
+static bool s_clk_tree_initialized = false;
+
 esp_err_t esp_clk_tree_src_get_freq_hz(soc_module_clk_t clk_src, esp_clk_tree_src_freq_precision_t precision,
                                        uint32_t *freq_value)
 {
@@ -52,6 +56,9 @@ esp_err_t esp_clk_tree_src_get_freq_hz(soc_module_clk_t clk_src, esp_clk_tree_sr
     case SOC_MOD_CLK_MPLL:
         clk_src_freq = clk_ll_mpll_get_freq_mhz(clk_hal_xtal_get_freq_mhz()) * MHZ;
         break;
+    case SOC_MOD_CLK_APLL:
+        clk_src_freq = clk_hal_apll_get_freq_hz();
+        break;
     case SOC_MOD_CLK_RTC_SLOW:
         clk_src_freq = esp_clk_tree_lp_slow_get_freq_hz(precision);
         break;
@@ -82,9 +89,22 @@ esp_err_t esp_clk_tree_src_get_freq_hz(soc_module_clk_t clk_src, esp_clk_tree_sr
 
 esp_err_t esp_clk_tree_src_set_freq_hz(soc_module_clk_t clk_src, uint32_t expt_freq_value, uint32_t *ret_freq_value)
 {
-    /* TODO: [ESP32S31] IDF-14733 */
+    ESP_RETURN_ON_FALSE(clk_src > 0 && clk_src < SOC_MOD_CLK_INVALID, ESP_ERR_INVALID_ARG, TAG, "unknown clk src");
-    (void)clk_src; (void)expt_freq_value; (void)ret_freq_value;
+    ESP_RETURN_ON_FALSE(expt_freq_value > 0, ESP_ERR_INVALID_ARG, TAG, "invalid frequency");
-    return ESP_ERR_NOT_SUPPORTED;
+
+    uint32_t real_freq_value = 0;
+    esp_err_t ret = ESP_OK;
+    switch (clk_src) {
+    case SOC_MOD_CLK_APLL:
+        ret = esp_clk_tree_apll_freq_set(expt_freq_value, &real_freq_value);
+        break;
+    default:
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+    if (ret_freq_value) {
+        *ret_freq_value = real_freq_value;
+    }
+    return ret;
 }
 
 static int16_t s_cpll_ref_cnt = 0;
@@ -102,6 +122,7 @@ void esp_clk_tree_initialize(void)
 
     // Gating
     // flash clock source is set to BBPLL in bootloader
+    s_clk_tree_initialized = true;
 }
 
 bool esp_clk_tree_enable_power(soc_root_clk_circuit_t clk_circuit, bool enable)
@@ -134,6 +155,49 @@ bool esp_clk_tree_enable_power(soc_root_clk_circuit_t clk_circuit, bool enable)
 
 esp_err_t esp_clk_tree_enable_src(soc_module_clk_t clk_src, bool enable)
 {
+    if (clk_src < 1 || clk_src >= SOC_MOD_CLK_INVALID) {
+        // some conditions is legal, e.g. -1 means external clock source
+        return ESP_OK;
+    }
+
+    if (!s_clk_tree_initialized) {
+        return ESP_OK;
+    }
+
+    // These clock sources have their own reference counting
+    switch (clk_src) {
+    case SOC_MOD_CLK_APLL:
+        if (enable) {
+            esp_clk_tree_apll_acquire();
+        } else {
+            esp_clk_tree_apll_release();
+        }
+        return ESP_OK;
+    case SOC_MOD_CLK_MPLL:
+        if (enable) {
+            return esp_clk_tree_mpll_acquire();
+        } else {
+            esp_clk_tree_mpll_release();
+        }
+        return ESP_OK;
+    default:
+        break;
+    }
+
+    // Other clock sources use the global reference counting
+    int16_t prev_ref_cnt = 0;
+    if (enable) {
+        prev_ref_cnt = atomic_fetch_add(&s_pll_src_cg_ref_cnt[clk_src], 1);
+    } else {
+        prev_ref_cnt = atomic_fetch_sub(&s_pll_src_cg_ref_cnt[clk_src], 1);
+        if (prev_ref_cnt <= 0) {
+            ESP_EARLY_LOGW(TAG, "soc_module_clk_t %d disabled multiple times!!", clk_src);
+            atomic_store(&s_pll_src_cg_ref_cnt[clk_src], 0);
+            return ESP_OK;
+        }
+    }
+
     // TODO: IDF-15502
+
     return ESP_OK;
 }

components/esp_hw_support/port/esp32s31/rtc_clk.c

@@ -592,7 +592,18 @@ uint32_t rtc_clk_apll_coeff_calc(uint32_t freq, uint32_t *_o_div, uint32_t *_sdm
 
 void rtc_clk_apll_coeff_set(uint32_t o_div, uint32_t sdm0, uint32_t sdm1, uint32_t sdm2)
 {
-    // TODO: IDF-14771, IDF-14750
+    clk_ll_apll_set_config(o_div, sdm0, sdm1, sdm2);
+
+    /* calibration */
+    ANALOG_CLOCK_ENABLE();
+    clk_ll_apll_set_calibration();
+
+    /* wait for calibration end */
+    while (!clk_ll_apll_calibration_is_done()) {
+        /* use esp_rom_delay_us so the RTC bus doesn't get flooded */
+        esp_rom_delay_us(1);
+    }
+    ANALOG_CLOCK_DISABLE();
 }
 
 void rtc_dig_clk8m_enable(void)

components/soc/esp32h21/include/soc/clk_tree_defs.h

@@ -486,7 +486,7 @@ typedef enum {
 typedef enum {
     I2S_CLK_SRC_DEFAULT = SOC_MOD_CLK_PLL_F96M,                 /*!< Select PLL_F96M as the default source clock */
     I2S_CLK_SRC_PLL_96M = SOC_MOD_CLK_PLL_F96M,                 /*!< Select PLL_F96M as the source clock */
-    I2S_CLK_SRC_PLL_64M = SOC_MOD_CLK_XTAL_X2_F64M,             /*!< Select XTAL_X2_F64M as the source clock */
+    I2S_CLK_SRC_XTAL_X2 = SOC_MOD_CLK_XTAL_X2_F64M,             /*!< Select XTAL_X2_F64M as the source clock */
     I2S_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                        /*!< Select XTAL as the source clock */
     I2S_CLK_SRC_EXTERNAL = -1,                                  /*!< Select external clock as source clock */
 } soc_periph_i2s_clk_src_t;

components/soc/esp32h4/include/soc/clk_tree_defs.h

@@ -452,7 +452,7 @@ typedef enum {
 typedef enum {
     I2S_CLK_SRC_DEFAULT = SOC_MOD_CLK_PLL_F96M,                 /*!< Select PLL_F96M as the default source clock */
     I2S_CLK_SRC_PLL_96M = SOC_MOD_CLK_PLL_F96M,                 /*!< Select PLL_F96M as the source clock */
-    I2S_CLK_SRC_PLL_64M = SOC_MOD_CLK_XTAL_X2_F64M,          /*!< Select XTAL_X2_F64M as the source clock */
+    I2S_CLK_SRC_XTAL_X2 = SOC_MOD_CLK_XTAL_X2_F64M,          /*!< Select XTAL_X2_F64M as the source clock */
     I2S_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                        /*!< Select XTAL as the source clock */
     I2S_CLK_SRC_EXTERNAL = -1,                                  /*!< Select external clock as source clock */
 } soc_periph_i2s_clk_src_t;

components/soc/esp32s31/include/soc/Kconfig.soc_caps.in

@@ -111,6 +111,10 @@ config SOC_RMT_SUPPORTED
     bool
     default y
 
+config SOC_I2S_SUPPORTED
+    bool
+    default y
+
 config SOC_SDM_SUPPORTED
     bool
     default y
@@ -911,6 +915,10 @@ config SOC_CLK_RC_FAST_SUPPORT_CALIBRATION
     bool
     default y
 
+config SOC_CLK_APLL_SUPPORTED
+    bool
+    default y
+
 config SOC_CLK_MPLL_SUPPORTED
     bool
     default y
@@ -927,6 +935,10 @@ config SOC_CLK_LP_FAST_SUPPORT_XTAL
     bool
     default y
 
+config SOC_CLK_ANA_I2C_MST_HAS_ROOT_GATE
+    bool
+    default y
+
 config SOC_RCC_IS_INDEPENDENT
     bool
     default y
@@ -1198,3 +1210,75 @@ config SOC_BLE_SUBRATE_SUPPORTED
 config SOC_BLE_PERIODIC_ADV_WITH_RESPONSE
     bool
     default y
+
+config SOC_I2S_NUM
+    int
+    default 2
+
+config SOC_I2S_HW_VERSION_2
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_ETM
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_APLL
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_RTC_FAST
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_EXTERNAL
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_PCM
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_PDM
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_PDM_TX
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_PCM2PDM
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_PDM_RX
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_PDM2PCM
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_PDM_RX_HP_FILTER
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_TX_SYNC_CNT
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_RX_RECOMB
+    bool
+    default y
+
+config SOC_I2S_SUPPORTS_TDM
+    bool
+    default y
+
+config SOC_I2S_PDM_MAX_TX_LINES
+    int
+    default 2
+
+config SOC_I2S_PDM_MAX_RX_LINES
+    int
+    default 4

components/soc/esp32s31/include/soc/clk_tree_defs.h

@@ -476,6 +476,25 @@ typedef enum {
     MCPWM_CARRIER_CLK_SRC_DEFAULT = SOC_MOD_CLK_PLL_F160M,   /*!< Select PLL_F160M as the default choice */
 } soc_periph_mcpwm_carrier_clk_src_t;
 
+//////////////////////////////////////////////////I2S/////////////////////////////////////////////////////////////////
+
+/**
+ * @brief I2S clock source
+ */
+#define SOC_I2S_CLKS {SOC_MOD_CLK_XTAL, SOC_MOD_CLK_APLL, SOC_MOD_CLK_RTC_FAST, I2S_CLK_SRC_EXTERNAL}
+
+/**
+ * @brief I2S clock source enum
+ * @note Enum values are matched with the register field values on purpose
+ */
+typedef enum {
+    I2S_CLK_SRC_DEFAULT = SOC_MOD_CLK_XTAL,                            /*!< Auto select maximum clock source as default source clock */
+    I2S_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                /*!< Select XTAL as the source clock */
+    I2S_CLK_SRC_APLL = SOC_MOD_CLK_APLL,                /*!< Select APLL as the source clock */
+    I2S_CLK_SRC_RTC_FAST = SOC_MOD_CLK_RTC_FAST,        /*!< Select RTC_FAST as the source clock */
+    I2S_CLK_SRC_EXTERNAL = -1,                          /*!< Select external clock as source clock */
+} soc_periph_i2s_clk_src_t;
+
 //////////////////////////////////////////////CLOCK OUTPUT///////////////////////////////////////////////////////////
 typedef enum {
     CLKOUT_SIG_MPLL_500M         = 0,   /*!< MPLL output at 500MHz */

components/soc/esp32s31/include/soc/regi2c_apll.h

@@ -0,0 +1,131 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+/**
+ * @file regi2c_apll.h
+ * @brief Register definitions for audio PLL (APLL)
+ *
+ * This file lists register fields of APLL, located on an internal configuration
+ * bus. These definitions are used via macros defined in regi2c_ctrl.h, by
+ * rtc_clk_apll_freq_set and rtc_clk_apll_enable function in rtc_clk.c.
+ */
+
+#define I2C_APLL            0X0C
+#define I2C_APLL_HOSTID     0
+
+#define I2C_APLL_IR_CAL_DELAY        0
+#define I2C_APLL_IR_CAL_DELAY_MSB    3
+#define I2C_APLL_IR_CAL_DELAY_LSB    0
+
+#define I2C_APLL_IR_CAL_RSTB        0
+#define I2C_APLL_IR_CAL_RSTB_MSB    4
+#define I2C_APLL_IR_CAL_RSTB_LSB    4
+
+#define I2C_APLL_IR_CAL_START        0
+#define I2C_APLL_IR_CAL_START_MSB    5
+#define I2C_APLL_IR_CAL_START_LSB    5
+
+#define I2C_APLL_IR_CAL_UNSTOP        0
+#define I2C_APLL_IR_CAL_UNSTOP_MSB    6
+#define I2C_APLL_IR_CAL_UNSTOP_LSB    6
+
+#define I2C_APLL_OC_ENB_FCAL        0
+#define I2C_APLL_OC_ENB_FCAL_MSB    7
+#define I2C_APLL_OC_ENB_FCAL_LSB    7
+
+#define I2C_APLL_IR_CAL_EXT_CAP        1
+#define I2C_APLL_IR_CAL_EXT_CAP_MSB    4
+#define I2C_APLL_IR_CAL_EXT_CAP_LSB    0
+
+#define I2C_APLL_IR_CAL_ENX_CAP        1
+#define I2C_APLL_IR_CAL_ENX_CAP_MSB    5
+#define I2C_APLL_IR_CAL_ENX_CAP_LSB    5
+
+#define I2C_APLL_OC_LBW        1
+#define I2C_APLL_OC_LBW_MSB    6
+#define I2C_APLL_OC_LBW_LSB    6
+
+#define I2C_APLL_IR_CAL_CK_DIV        2
+#define I2C_APLL_IR_CAL_CK_DIV_MSB    3
+#define I2C_APLL_IR_CAL_CK_DIV_LSB    0
+
+#define I2C_APLL_OC_DCHGP        2
+#define I2C_APLL_OC_DCHGP_MSB    6
+#define I2C_APLL_OC_DCHGP_LSB    4
+
+#define I2C_APLL_OC_ENB_VCON        2
+#define I2C_APLL_OC_ENB_VCON_MSB    7
+#define I2C_APLL_OC_ENB_VCON_LSB    7
+
+#define I2C_APLL_OR_CAL_CAP        3
+#define I2C_APLL_OR_CAL_CAP_MSB    4
+#define I2C_APLL_OR_CAL_CAP_LSB    0
+
+#define I2C_APLL_OR_CAL_UDF        3
+#define I2C_APLL_OR_CAL_UDF_MSB    5
+#define I2C_APLL_OR_CAL_UDF_LSB    5
+
+#define I2C_APLL_OR_CAL_OVF        3
+#define I2C_APLL_OR_CAL_OVF_MSB    6
+#define I2C_APLL_OR_CAL_OVF_LSB    6
+
+#define I2C_APLL_OR_CAL_END        3
+#define I2C_APLL_OR_CAL_END_MSB    7
+#define I2C_APLL_OR_CAL_END_LSB    7
+
+#define I2C_APLL_OR_OUTPUT_DIV        4
+#define I2C_APLL_OR_OUTPUT_DIV_MSB    4
+#define I2C_APLL_OR_OUTPUT_DIV_LSB    0
+
+#define I2C_APLL_OC_TSCHGP        4
+#define I2C_APLL_OC_TSCHGP_MSB    6
+#define I2C_APLL_OC_TSCHGP_LSB    6
+
+#define I2C_APLL_EN_FAST_CAL        4
+#define I2C_APLL_EN_FAST_CAL_MSB    7
+#define I2C_APLL_EN_FAST_CAL_LSB    7
+
+#define I2C_APLL_OC_DHREF_SEL        5
+#define I2C_APLL_OC_DHREF_SEL_MSB    1
+#define I2C_APLL_OC_DHREF_SEL_LSB    0
+
+#define I2C_APLL_OC_DLREF_SEL        5
+#define I2C_APLL_OC_DLREF_SEL_MSB    3
+#define I2C_APLL_OC_DLREF_SEL_LSB    2
+
+#define I2C_APLL_SDM_DITHER        5
+#define I2C_APLL_SDM_DITHER_MSB    4
+#define I2C_APLL_SDM_DITHER_LSB    4
+
+#define I2C_APLL_SDM_STOP        5
+#define I2C_APLL_SDM_STOP_MSB    5
+#define I2C_APLL_SDM_STOP_LSB    5
+
+#define I2C_APLL_SDM_RSTB        5
+#define I2C_APLL_SDM_RSTB_MSB    6
+#define I2C_APLL_SDM_RSTB_LSB    6
+
+#define I2C_APLL_OC_DVDD        6
+#define I2C_APLL_OC_DVDD_MSB    4
+#define I2C_APLL_OC_DVDD_LSB    0
+
+#define I2C_APLL_OC_REF_DIV        6
+#define I2C_APLL_OC_REF_DIV_MSB    7
+#define I2C_APLL_OC_REF_DIV_LSB    5
+
+#define I2C_APLL_DSDM2        7
+#define I2C_APLL_DSDM2_MSB    5
+#define I2C_APLL_DSDM2_LSB    0
+
+#define I2C_APLL_DSDM1        8
+#define I2C_APLL_DSDM1_MSB    7
+#define I2C_APLL_DSDM1_LSB    0
+
+#define I2C_APLL_DSDM0        9
+#define I2C_APLL_DSDM0_MSB    7
+#define I2C_APLL_DSDM0_LSB    0

components/soc/esp32s31/include/soc/soc_caps.h

@@ -58,7 +58,7 @@
 #define SOC_RTC_FAST_MEM_SUPPORTED      1
 #define SOC_RTC_MEM_SUPPORTED           1      // TODO: [ESP32S31] IDF-14645
 #define SOC_RMT_SUPPORTED               1
-// #define SOC_I2S_SUPPORTED               1      // TODO: [ESP32S31] IDF-14771
+#define SOC_I2S_SUPPORTED               1
 #define SOC_SDM_SUPPORTED               1
 #define SOC_GPSPI_SUPPORTED             1
 #define SOC_LEDC_SUPPORTED              1
@@ -390,13 +390,15 @@
 
 #define SOC_CLK_RC_FAST_SUPPORT_CALIBRATION       (1)
 
-// #define SOC_CLK_APLL_SUPPORTED                    (1)     /*!< Support Audio PLL */ // TODO: IDF-14771, IDF-14750
+#define SOC_CLK_APLL_SUPPORTED                    (1)     /*!< Support Audio PLL */
 #define SOC_CLK_MPLL_SUPPORTED                    (1)     /*!< Support MSPI PLL */ // TODO: IDF-14718
 #define SOC_CLK_XTAL32K_SUPPORTED                 (1)     /*!< Support to connect an external low frequency crystal */
 #define SOC_CLK_RC32K_SUPPORTED                   (1)     /*!< Support an internal 32kHz RC oscillator */
 
 #define SOC_CLK_LP_FAST_SUPPORT_XTAL              (1)     /*!< Support XTAL clock as the LP_FAST clock source */
 
+#define SOC_CLK_ANA_I2C_MST_HAS_ROOT_GATE         (1)     /*!< Any regi2c operation needs enable the analog i2c master clock first */
+
 #define SOC_RCC_IS_INDEPENDENT                    1       /*!< Reset and Clock Control has own registers for each module */
 /*-------------------------- Memory CAPS --------------------------*/
 #define SOC_ASYNCHRONOUS_BUS_ERROR_MODE           (1)
@@ -501,3 +503,23 @@
 #define SOC_BLE_SUBRATE_SUPPORTED                   (1)     /*!< Support Bluetooth LE Connection Subrating */
 #define SOC_BLE_PERIODIC_ADV_WITH_RESPONSE          (1)     /*!< Support Bluetooth LE Periodic Advertising with Response (PAwR) */
 // #define SOC_BLE_ISO_SUPPORTED                       (1)     /*!< Support Bluetooth ISO */
+
+/*-------------------------- I2S CAPS ----------------------------------------*/
+#define SOC_I2S_NUM                          (2U)
+#define SOC_I2S_HW_VERSION_2                 (1)
+#define SOC_I2S_SUPPORTS_ETM                  (1)
+#define SOC_I2S_SUPPORTS_APLL                 (1)
+#define SOC_I2S_SUPPORTS_RTC_FAST             (1)     // Support RTC_FAST as I2S clock source
+#define SOC_I2S_SUPPORTS_EXTERNAL             (1)     // Support External clock source
+#define SOC_I2S_SUPPORTS_PCM                  (1)
+#define SOC_I2S_SUPPORTS_PDM                  (1)
+#define SOC_I2S_SUPPORTS_PDM_TX               (1)     // Support to output raw PDM format data
+#define SOC_I2S_SUPPORTS_PCM2PDM              (1)     // Support to write PCM format but output PDM format data with the help of PCM to PDM filter
+#define SOC_I2S_SUPPORTS_PDM_RX               (1)     // Support to input raw PDM format data
+#define SOC_I2S_SUPPORTS_PDM2PCM              (1)     // Support to input PDM format but read PCM format data with the help of PDM to PCM filter (only on I2S0)
+#define SOC_I2S_SUPPORTS_PDM_RX_HP_FILTER    (1)
+#define SOC_I2S_SUPPORTS_TX_SYNC_CNT          (1)     // Support TX synchronization count (ideal_cnt)
+#define SOC_I2S_SUPPORTS_RX_RECOMB            (1)     // Support RX recomb for DMA data format reorganization
+#define SOC_I2S_SUPPORTS_TDM                  (1)
+#define SOC_I2S_PDM_MAX_TX_LINES              (2)     // On I2S0
+#define SOC_I2S_PDM_MAX_RX_LINES              (4)     // On I2S0

components/soc/esp32s31/register/soc/i2s_reg.h

@@ -1,5 +1,5 @@
 /**
- * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
  *
  *  SPDX-License-Identifier: Apache-2.0 OR MIT
  */
@@ -10,10 +10,12 @@
 extern "C" {
 #endif
 
-/** I2S_INT_RAW_REG register
+#define REG_I2S_BASE(i)                         (DR_REG_I2S_BASE + (i) * 0x1000)
+
+/** I2S_INT_RAW_REG(i) register
  *  I2S interrupt raw register, valid in level.
  */
-#define I2S_INT_RAW_REG (DR_REG_I2S_BASE + 0xc)
+#define I2S_INT_RAW_REG(i) (REG_I2S_BASE(i) + 0xc)
 /** I2S_RX_DONE_INT_RAW : RO/WTC/SS; bitpos: [0]; default: 0;
  *  The raw interrupt status bit  for the i2s_rx_done_int interrupt
  */
@@ -50,10 +52,10 @@ extern "C" {
 #define I2S_TX_SYNC_INT_RAW_V  0x00000001U
 #define I2S_TX_SYNC_INT_RAW_S  4
 
-/** I2S_INT_ST_REG register
+/** I2S_INT_ST_REG(i) register
  *  I2S interrupt status register.
  */
-#define I2S_INT_ST_REG (DR_REG_I2S_BASE + 0x10)
+#define I2S_INT_ST_REG(i) (REG_I2S_BASE(i) + 0x10)
 /** I2S_RX_DONE_INT_ST : RO; bitpos: [0]; default: 0;
  *  The masked interrupt status bit  for the i2s_rx_done_int interrupt
  */
@@ -90,10 +92,10 @@ extern "C" {
 #define I2S_TX_SYNC_INT_ST_V  0x00000001U
 #define I2S_TX_SYNC_INT_ST_S  4
 
-/** I2S_INT_ENA_REG register
+/** I2S_INT_ENA_REG(i) register
  *  I2S interrupt enable register.
  */
-#define I2S_INT_ENA_REG (DR_REG_I2S_BASE + 0x14)
+#define I2S_INT_ENA_REG(i) (REG_I2S_BASE(i) + 0x14)
 /** I2S_RX_DONE_INT_ENA : R/W; bitpos: [0]; default: 0;
  *  The interrupt enable bit  for the i2s_rx_done_int interrupt
  */
@@ -130,10 +132,10 @@ extern "C" {
 #define I2S_TX_SYNC_INT_ENA_V  0x00000001U
 #define I2S_TX_SYNC_INT_ENA_S  4
 
-/** I2S_INT_CLR_REG register
+/** I2S_INT_CLR_REG(i) register
  *  I2S interrupt clear register.
  */
-#define I2S_INT_CLR_REG (DR_REG_I2S_BASE + 0x18)
+#define I2S_INT_CLR_REG(i) (REG_I2S_BASE(i) + 0x18)
 /** I2S_RX_DONE_INT_CLR : WT; bitpos: [0]; default: 0;
  *  Set this bit to clear the i2s_rx_done_int interrupt
  */
@@ -170,10 +172,10 @@ extern "C" {
 #define I2S_TX_SYNC_INT_CLR_V  0x00000001U
 #define I2S_TX_SYNC_INT_CLR_S  4
 
-/** I2S_RX_CONF_REG register
+/** I2S_RX_CONF_REG(i) register
  *  I2S RX configure register
  */
-#define I2S_RX_CONF_REG (DR_REG_I2S_BASE + 0x20)
+#define I2S_RX_CONF_REG(i) (REG_I2S_BASE(i) + 0x20)
 /** I2S_RX_RESET : WT; bitpos: [0]; default: 0;
  *  Set this bit to reset receiver
  */
@@ -322,10 +324,10 @@ extern "C" {
 #define I2S_RX_BCK_DIV_NUM_V  0x0000003FU
 #define I2S_RX_BCK_DIV_NUM_S  21
 
-/** I2S_TX_CONF_REG register
+/** I2S_TX_CONF_REG(i) register
  *  I2S TX configure register
  */
-#define I2S_TX_CONF_REG (DR_REG_I2S_BASE + 0x24)
+#define I2S_TX_CONF_REG(i) (REG_I2S_BASE(i) + 0x24)
 /** I2S_TX_RESET : WT; bitpos: [0]; default: 0;
  *  Set this bit to reset transmitter
  */
@@ -498,10 +500,10 @@ extern "C" {
 #define I2S_SIG_LOOPBACK_V  0x00000001U
 #define I2S_SIG_LOOPBACK_S  30
 
-/** I2S_RX_CONF1_REG register
+/** I2S_RX_CONF1_REG(i) register
  *  I2S RX configure register 1
  */
-#define I2S_RX_CONF1_REG (DR_REG_I2S_BASE + 0x28)
+#define I2S_RX_CONF1_REG(i) (REG_I2S_BASE(i) + 0x28)
 /** I2S_RX_TDM_WS_WIDTH : R/W; bitpos: [8:0]; default: 0;
  *  The width of rx_ws_out at idle level in TDM mode is (I2S_RX_TDM_WS_WIDTH[8:0] +1) *
  *  T_bck
@@ -535,10 +537,10 @@ extern "C" {
 #define I2S_RX_TDM_CHAN_BITS_V  0x0000001FU
 #define I2S_RX_TDM_CHAN_BITS_S  27
 
-/** I2S_TX_CONF1_REG register
+/** I2S_TX_CONF1_REG(i) register
  *  I2S TX configure register 1
  */
-#define I2S_TX_CONF1_REG (DR_REG_I2S_BASE + 0x2c)
+#define I2S_TX_CONF1_REG(i) (REG_I2S_BASE(i) + 0x2c)
 /** I2S_TX_TDM_WS_WIDTH : R/W; bitpos: [8:0]; default: 0;
  *  The width of tx_ws_out at idle level in TDM mode is (I2S_TX_TDM_WS_WIDTH[8:0] +1) *
  *  T_bck
@@ -572,10 +574,10 @@ extern "C" {
 #define I2S_TX_TDM_CHAN_BITS_V  0x0000001FU
 #define I2S_TX_TDM_CHAN_BITS_S  27
 
-/** I2S_RX_RECOMB_CTRL_REG register
+/** I2S_RX_RECOMB_CTRL_REG(i) register
  *  I2S RX configure register 1
  */
-#define I2S_RX_RECOMB_CTRL_REG (DR_REG_I2S_BASE + 0x30)
+#define I2S_RX_RECOMB_CTRL_REG(i) (REG_I2S_BASE(i) + 0x30)
 /** I2S_RX_RECOMB_EN : R/W; bitpos: [0]; default: 0;
  *  Set this bit to enable i2s rx data recombination.
  */
@@ -599,10 +601,10 @@ extern "C" {
 #define I2S_RX_RECOMB_UPDATE_V  0x00000001U
 #define I2S_RX_RECOMB_UPDATE_S  31
 
-/** I2S_RX_RECOMB_DMA_CH0_REG register
+/** I2S_RX_RECOMB_DMA_CH0_REG(i) register
  *  I2S RX recombined-dma-channel configuration register
  */
-#define I2S_RX_RECOMB_DMA_CH0_REG (DR_REG_I2S_BASE + 0x34)
+#define I2S_RX_RECOMB_DMA_CH0_REG(i) (REG_I2S_BASE(i) + 0x34)
 /** I2S_RX_RECOMB_DMA_CH0_VALID : R/W; bitpos: [0]; default: 0;
  *  Set this bit to enable the adc-dma-channel.
  */
@@ -634,10 +636,10 @@ extern "C" {
 #define I2S_RX_RECOMB_DMA_CH0_EOF_NUM_V  0x0000FFFFU
 #define I2S_RX_RECOMB_DMA_CH0_EOF_NUM_S  13
 
-/** I2S_RX_RECOMB_DMA_CH1_REG register
+/** I2S_RX_RECOMB_DMA_CH1_REG(i) register
  *  I2S RX recombined-dma-channel configuration register
  */
-#define I2S_RX_RECOMB_DMA_CH1_REG (DR_REG_I2S_BASE + 0x38)
+#define I2S_RX_RECOMB_DMA_CH1_REG(i) (REG_I2S_BASE(i) + 0x38)
 /** I2S_RX_RECOMB_DMA_CH1_VALID : R/W; bitpos: [0]; default: 0;
  *  Set this bit to enable the adc-dma-channel.
  */
@@ -669,10 +671,10 @@ extern "C" {
 #define I2S_RX_RECOMB_DMA_CH1_EOF_NUM_V  0x0000FFFFU
 #define I2S_RX_RECOMB_DMA_CH1_EOF_NUM_S  13
 
-/** I2S_RX_RECOMB_DMA_CH2_REG register
+/** I2S_RX_RECOMB_DMA_CH2_REG(i) register
  *  I2S RX recombined-dma-channel configuration register
  */
-#define I2S_RX_RECOMB_DMA_CH2_REG (DR_REG_I2S_BASE + 0x3c)
+#define I2S_RX_RECOMB_DMA_CH2_REG(i) (REG_I2S_BASE(i) + 0x3c)
 /** I2S_RX_RECOMB_DMA_CH2_VALID : R/W; bitpos: [0]; default: 0;
  *  Set this bit to enable the adc-dma-channel.
  */
@@ -704,10 +706,10 @@ extern "C" {
 #define I2S_RX_RECOMB_DMA_CH2_EOF_NUM_V  0x0000FFFFU
 #define I2S_RX_RECOMB_DMA_CH2_EOF_NUM_S  13
 
-/** I2S_RX_RECOMB_DMA_CH3_REG register
+/** I2S_RX_RECOMB_DMA_CH3_REG(i) register
  *  I2S RX recombined-dma-channel configuration register
  */
-#define I2S_RX_RECOMB_DMA_CH3_REG (DR_REG_I2S_BASE + 0x40)
+#define I2S_RX_RECOMB_DMA_CH3_REG(i) (REG_I2S_BASE(i) + 0x40)
 /** I2S_RX_RECOMB_DMA_CH3_VALID : R/W; bitpos: [0]; default: 0;
  *  Set this bit to enable the adc-dma-channel.
  */
@@ -739,10 +741,10 @@ extern "C" {
 #define I2S_RX_RECOMB_DMA_CH3_EOF_NUM_V  0x0000FFFFU
 #define I2S_RX_RECOMB_DMA_CH3_EOF_NUM_S  13
 
-/** I2S_TX_PCM2PDM_CONF_REG register
+/** I2S_TX_PCM2PDM_CONF_REG(i) register
  *  I2S TX PCM2PDM configuration register
  */
-#define I2S_TX_PCM2PDM_CONF_REG (DR_REG_I2S_BASE + 0x44)
+#define I2S_TX_PCM2PDM_CONF_REG(i) (REG_I2S_BASE(i) + 0x44)
 /** I2S_TX_PDM_SINC_OSR2 : R/W; bitpos: [4:1]; default: 2;
  *  I2S TX PDM OSR2 value
  */
@@ -821,10 +823,10 @@ extern "C" {
 #define I2S_PCM2PDM_CONV_EN_V  0x00000001U
 #define I2S_PCM2PDM_CONV_EN_S  25
 
-/** I2S_TX_PCM2PDM_CONF1_REG register
+/** I2S_TX_PCM2PDM_CONF1_REG(i) register
  *  I2S TX PCM2PDM configuration register
  */
-#define I2S_TX_PCM2PDM_CONF1_REG (DR_REG_I2S_BASE + 0x48)
+#define I2S_TX_PCM2PDM_CONF1_REG(i) (REG_I2S_BASE(i) + 0x48)
 /** I2S_TX_PDM_FP : R/W; bitpos: [9:0]; default: 960;
  *  I2S TX PDM Fp
  */
@@ -856,10 +858,10 @@ extern "C" {
 #define I2S_TX_IIR_HP_MULT12_0_V  0x00000007U
 #define I2S_TX_IIR_HP_MULT12_0_S  23
 
-/** I2S_RX_PDM2PCM_CONF_REG register
+/** I2S_RX_PDM2PCM_CONF_REG(i) register
  *  I2S RX configure register
  */
-#define I2S_RX_PDM2PCM_CONF_REG (DR_REG_I2S_BASE + 0x4c)
+#define I2S_RX_PDM2PCM_CONF_REG(i) (REG_I2S_BASE(i) + 0x4c)
 /** I2S_RX_PDM2PCM_EN : R/W; bitpos: [19]; default: 0;
  *  1: Enable PDM2PCM RX mode. 0: DIsable.
  */
@@ -906,10 +908,10 @@ extern "C" {
 #define I2S_RX_IIR_HP_MULT12_0_V  0x00000007U
 #define I2S_RX_IIR_HP_MULT12_0_S  29
 
-/** I2S_RX_TDM_CTRL_REG register
+/** I2S_RX_TDM_CTRL_REG(i) register
  *  I2S TX TDM mode control register
  */
-#define I2S_RX_TDM_CTRL_REG (DR_REG_I2S_BASE + 0x50)
+#define I2S_RX_TDM_CTRL_REG(i) (REG_I2S_BASE(i) + 0x50)
 /** I2S_RX_TDM_PDM_CHAN0_EN : R/W; bitpos: [0]; default: 1;
  *  1: Enable the valid data input of I2S RX TDM or PDM channel $n. 0:  Disable, just
  *  input 0 in this channel.
@@ -1053,10 +1055,10 @@ extern "C" {
 #define I2S_RX_TDM_BITS_MODE_DET_EN_V  0x00000001U
 #define I2S_RX_TDM_BITS_MODE_DET_EN_S  20
 
-/** I2S_TX_TDM_CTRL_REG register
+/** I2S_TX_TDM_CTRL_REG(i) register
  *  I2S TX TDM mode control register
  */
-#define I2S_TX_TDM_CTRL_REG (DR_REG_I2S_BASE + 0x54)
+#define I2S_TX_TDM_CTRL_REG(i) (REG_I2S_BASE(i) + 0x54)
 /** I2S_TX_TDM_CHAN0_EN : R/W; bitpos: [0]; default: 1;
  *  1: Enable the valid data output of I2S TX TDM channel $n. 0:  Disable, just output
  *  0 in this channel.
@@ -1209,10 +1211,10 @@ extern "C" {
 #define I2S_TX_TDM_BITS_MODE_DET_EN_V  0x00000001U
 #define I2S_TX_TDM_BITS_MODE_DET_EN_S  21
 
-/** I2S_RX_TIMING_REG register
+/** I2S_RX_TIMING_REG(i) register
  *  I2S RX timing control register
  */
-#define I2S_RX_TIMING_REG (DR_REG_I2S_BASE + 0x58)
+#define I2S_RX_TIMING_REG(i) (REG_I2S_BASE(i) + 0x58)
 /** I2S_RX_SD_IN_DM : R/W; bitpos: [1:0]; default: 0;
  *  The delay mode of I2S Rx SD input signal. 0: bypass. 1: delay by pos edge.  2:
  *  delay by neg edge. 3: not used.
@@ -1278,10 +1280,10 @@ extern "C" {
 #define I2S_RX_BCK_IN_DM_V  0x00000003U
 #define I2S_RX_BCK_IN_DM_S  28
 
-/** I2S_TX_TIMING_REG register
+/** I2S_TX_TIMING_REG(i) register
  *  I2S TX timing control register
  */
-#define I2S_TX_TIMING_REG (DR_REG_I2S_BASE + 0x5c)
+#define I2S_TX_TIMING_REG(i) (REG_I2S_BASE(i) + 0x5c)
 /** I2S_TX_SD_OUT_DM : R/W; bitpos: [1:0]; default: 0;
  *  The delay mode of I2S TX SD output signal. 0: bypass. 1: delay by pos edge.  2:
  *  delay by neg edge. 3: not used.
@@ -1331,10 +1333,10 @@ extern "C" {
 #define I2S_TX_BCK_IN_DM_V  0x00000003U
 #define I2S_TX_BCK_IN_DM_S  28
 
-/** I2S_LC_HUNG_CONF_REG register
+/** I2S_LC_HUNG_CONF_REG(i) register
  *  I2S HUNG configure register.
  */
-#define I2S_LC_HUNG_CONF_REG (DR_REG_I2S_BASE + 0x60)
+#define I2S_LC_HUNG_CONF_REG(i) (REG_I2S_BASE(i) + 0x60)
 /** I2S_LC_FIFO_TIMEOUT : R/W; bitpos: [7:0]; default: 16;
  *  the i2s_tx_hung_int interrupt or the i2s_rx_hung_int interrupt will be triggered
  *  when fifo hung counter is equal to this value
@@ -1359,10 +1361,10 @@ extern "C" {
 #define I2S_LC_FIFO_TIMEOUT_ENA_V  0x00000001U
 #define I2S_LC_FIFO_TIMEOUT_ENA_S  11
 
-/** I2S_RXEOF_NUM_REG register
+/** I2S_RXEOF_NUM_REG(i) register
  *  I2S RX data number control register.
  */
-#define I2S_RXEOF_NUM_REG (DR_REG_I2S_BASE + 0x64)
+#define I2S_RXEOF_NUM_REG(i) (REG_I2S_BASE(i) + 0x64)
 /** I2S_RX_EOF_NUM : R/W; bitpos: [15:0]; default: 64;
  *  The receive data bit length is (I2S_RX_BITS_MOD[4:0] + 1) * (REG_RX_EOF_NUM[15:0])
  *  . It will trigger in_suc_eof interrupt in the configured DMA RX channel.
@@ -1372,10 +1374,10 @@ extern "C" {
 #define I2S_RX_EOF_NUM_V  0x0000FFFFU
 #define I2S_RX_EOF_NUM_S  0
 
-/** I2S_CONF_SIGLE_DATA_REG register
+/** I2S_CONF_SIGLE_DATA_REG(i) register
  *  I2S signal data register
  */
-#define I2S_CONF_SIGLE_DATA_REG (DR_REG_I2S_BASE + 0x68)
+#define I2S_CONF_SIGLE_DATA_REG(i) (REG_I2S_BASE(i) + 0x68)
 /** I2S_SINGLE_DATA : R/W; bitpos: [31:0]; default: 0;
  *  The configured constant channel data to be sent out.
  */
@@ -1384,10 +1386,10 @@ extern "C" {
 #define I2S_SINGLE_DATA_V  0xFFFFFFFFU
 #define I2S_SINGLE_DATA_S  0
 
-/** I2S_STATE_REG register
+/** I2S_STATE_REG(i) register
  *  I2S TX status register
  */
-#define I2S_STATE_REG (DR_REG_I2S_BASE + 0x6c)
+#define I2S_STATE_REG(i) (REG_I2S_BASE(i) + 0x6c)
 /** I2S_TX_IDLE : RO; bitpos: [0]; default: 1;
  *  1: i2s_tx is idle state. 0: i2s_tx is working.
  */
@@ -1396,10 +1398,10 @@ extern "C" {
 #define I2S_TX_IDLE_V  0x00000001U
 #define I2S_TX_IDLE_S  0
 
-/** I2S_ETM_CONF_REG register
+/** I2S_ETM_CONF_REG(i) register
  *  I2S ETM configure register
  */
-#define I2S_ETM_CONF_REG (DR_REG_I2S_BASE + 0x70)
+#define I2S_ETM_CONF_REG(i) (REG_I2S_BASE(i) + 0x70)
 /** I2S_ETM_TX_SEND_WORD_NUM : R/W; bitpos: [13:0]; default: 64;
  *  I2S ETM send x words event. When sending word number of
  *  reg_etm_tx_send_word_num[13:0], i2s will trigger an etm event.
@@ -1417,10 +1419,10 @@ extern "C" {
 #define I2S_ETM_RX_RECEIVE_WORD_NUM_V  0x00003FFFU
 #define I2S_ETM_RX_RECEIVE_WORD_NUM_S  14
 
-/** I2S_IDEAL_CNT_REG register
+/** I2S_IDEAL_CNT_REG(i) register
  *  I2S sync counter register
  */
-#define I2S_IDEAL_CNT_REG (DR_REG_I2S_BASE + 0x74)
+#define I2S_IDEAL_CNT_REG(i) (REG_I2S_BASE(i) + 0x74)
 /** I2S_TX_IDEAL_CNT : R/W; bitpos: [30:0]; default: 0;
  *  tx fifo counter ideal value.
  */
@@ -1429,10 +1431,10 @@ extern "C" {
 #define I2S_TX_IDEAL_CNT_V  0x7FFFFFFFU
 #define I2S_TX_IDEAL_CNT_S  0
 
-/** I2S_FIFO_CNT_REG register
+/** I2S_FIFO_CNT_REG(i) register
  *  I2S sync counter register
  */
-#define I2S_FIFO_CNT_REG (DR_REG_I2S_BASE + 0x78)
+#define I2S_FIFO_CNT_REG(i) (REG_I2S_BASE(i) + 0x78)
 /** I2S_TX_FIFO_CNT : RO; bitpos: [30:0]; default: 0;
  *  tx fifo counter value.
  */
@@ -1448,10 +1450,10 @@ extern "C" {
 #define I2S_TX_FIFO_CNT_RST_V  0x00000001U
 #define I2S_TX_FIFO_CNT_RST_S  31
 
-/** I2S_BCK_CNT_REG register
+/** I2S_BCK_CNT_REG(i) register
  *  I2S sync counter register
  */
-#define I2S_BCK_CNT_REG (DR_REG_I2S_BASE + 0x7c)
+#define I2S_BCK_CNT_REG(i) (REG_I2S_BASE(i) + 0x7c)
 /** I2S_TX_BCK_CNT : RO; bitpos: [30:0]; default: 0;
  *  tx bck counter value.
  */
@@ -1467,10 +1469,10 @@ extern "C" {
 #define I2S_TX_BCK_CNT_RST_V  0x00000001U
 #define I2S_TX_BCK_CNT_RST_S  31
 
-/** I2S_CNT_DIFF_REG register
+/** I2S_CNT_DIFF_REG(i) register
  *  I2S sync counter register
  */
-#define I2S_CNT_DIFF_REG (DR_REG_I2S_BASE + 0x80)
+#define I2S_CNT_DIFF_REG(i) (REG_I2S_BASE(i) + 0x80)
 /** I2S_TX_CNT_DIFF : RO; bitpos: [30:0]; default: 0;
  *  tx bck counter value.
  */
@@ -1486,10 +1488,10 @@ extern "C" {
 #define I2S_TX_CNT_DIFF_RST_V  0x00000001U
 #define I2S_TX_CNT_DIFF_RST_S  31
 
-/** I2S_SYNC_SW_THRES_REG register
+/** I2S_SYNC_SW_THRES_REG(i) register
  *  I2S sync counter register
  */
-#define I2S_SYNC_SW_THRES_REG (DR_REG_I2S_BASE + 0x84)
+#define I2S_SYNC_SW_THRES_REG(i) (REG_I2S_BASE(i) + 0x84)
 /** I2S_TX_CNT_DIFF_SW_THRES : R/W; bitpos: [30:0]; default: 0;
  *  tx fifo counter difference software threshold value, when difference larger than
  *  this threshold, interrupt will occur and hardware sync will not be executed.
@@ -1499,10 +1501,10 @@ extern "C" {
 #define I2S_TX_CNT_DIFF_SW_THRES_V  0x7FFFFFFFU
 #define I2S_TX_CNT_DIFF_SW_THRES_S  0
 
-/** I2S_SYNC_HW_THRES_REG register
+/** I2S_SYNC_HW_THRES_REG(i) register
  *  I2S sync counter register
  */
-#define I2S_SYNC_HW_THRES_REG (DR_REG_I2S_BASE + 0x88)
+#define I2S_SYNC_HW_THRES_REG(i) (REG_I2S_BASE(i) + 0x88)
 /** I2S_TX_CNT_DIFF_HW_THRES : R/W; bitpos: [30:0]; default: 0;
  *  tx fifo counter difference hardware threshold value, which means that only when
  *  difference larger than this threshold will hardware start hardware sync.
@@ -1512,10 +1514,10 @@ extern "C" {
 #define I2S_TX_CNT_DIFF_HW_THRES_V  0x7FFFFFFFU
 #define I2S_TX_CNT_DIFF_HW_THRES_S  0
 
-/** I2S_HW_SYNC_CONF_REG register
+/** I2S_HW_SYNC_CONF_REG(i) register
  *  I2S TX hardware sync function configuration register
  */
-#define I2S_HW_SYNC_CONF_REG (DR_REG_I2S_BASE + 0x8c)
+#define I2S_HW_SYNC_CONF_REG(i) (REG_I2S_BASE(i) + 0x8c)
 /** I2S_TX_HW_SYNC_EN : R/W; bitpos: [0]; default: 0;
  *  Configure whether enable i2s tx hardware sync function. 1: Enable. 0: Disable
  */
@@ -1532,10 +1534,10 @@ extern "C" {
 #define I2S_TX_HW_SYNC_SUPPL_MODE_V  0x00000001U
 #define I2S_TX_HW_SYNC_SUPPL_MODE_S  1
 
-/** I2S_HW_SYNC_DATA_REG register
+/** I2S_HW_SYNC_DATA_REG(i) register
  *  I2S TX hardware sync function configuration register
  */
-#define I2S_HW_SYNC_DATA_REG (DR_REG_I2S_BASE + 0x90)
+#define I2S_HW_SYNC_DATA_REG(i) (REG_I2S_BASE(i) + 0x90)
 /** I2S_TX_HW_SYNC_SUPPL_DATA : R/W; bitpos: [31:0]; default: 0;
  *  Configure the i2s tx hardware sync supplementation data when
  *  I2S_TX_HW_SYNC_SUPPL_MODE is 1.
@@ -1545,10 +1547,10 @@ extern "C" {
 #define I2S_TX_HW_SYNC_SUPPL_DATA_V  0xFFFFFFFFU
 #define I2S_TX_HW_SYNC_SUPPL_DATA_S  0
 
-/** I2S_DESTINATION_REG register
+/** I2S_DESTINATION_REG(i) register
  *  I2S TX status register
  */
-#define I2S_DESTINATION_REG (DR_REG_I2S_BASE + 0xf4)
+#define I2S_DESTINATION_REG(i) (REG_I2S_BASE(i) + 0xf4)
 /** I2S_RX_DESTINATION : R/W; bitpos: [0]; default: 0;
  *  Set this bit to configure the data destination of i2s rx. 1: ble. 0: gdma.
  */
@@ -1564,10 +1566,10 @@ extern "C" {
 #define I2S_TX_DESTINATION_V  0x00000001U
 #define I2S_TX_DESTINATION_S  1
 
-/** I2S_CLK_GATE_REG register
+/** I2S_CLK_GATE_REG(i) register
  *  Clock gate register
  */
-#define I2S_CLK_GATE_REG (DR_REG_I2S_BASE + 0xf8)
+#define I2S_CLK_GATE_REG(i) (REG_I2S_BASE(i) + 0xf8)
 /** I2S_CLK_EN : R/W; bitpos: [0]; default: 0;
  *  set this bit to enable clock gate
  */
@@ -1576,10 +1578,10 @@ extern "C" {
 #define I2S_CLK_EN_V  0x00000001U
 #define I2S_CLK_EN_S  0
 
-/** I2S_DATE_REG register
+/** I2S_DATE_REG(i) register
  *  Version control register
  */
-#define I2S_DATE_REG (DR_REG_I2S_BASE + 0xfc)
+#define I2S_DATE_REG(i) (REG_I2S_BASE(i) + 0xfc)
 /** I2S_DATE : R/W; bitpos: [27:0]; default: 38813744;
  *  I2S version control register
  */

components/soc/esp32s31/register/soc/i2s_struct.h

@@ -1282,6 +1282,8 @@ typedef struct {
     volatile i2s_date_reg_t date;
 } i2s_dev_t;
 
+extern i2s_dev_t I2S0;
+extern i2s_dev_t I2S1;
 
 #ifndef __cplusplus
 _Static_assert(sizeof(i2s_dev_t) == 0x100, "Invalid size of i2s_dev_t structure");

docs/en/api-reference/peripherals/i2s.rst

@@ -3,7 +3,7 @@ Inter-IC Sound (I2S)
 
 :link_to_translation:`zh_CN:[中文]`
 
-{IDF_TARGET_I2S_NUM:default="one", esp32="two", esp32s3="two", esp32p4="three"}
+{IDF_TARGET_I2S_NUM:default="one", esp32="two", esp32s3="two", esp32p4="three", esp32s31="two"}
 {IDF_TARGET_I2S_STD_TDM:default="standard and TDM", esp32="standard", esp32s2="standard"}
 
 Introduction
@@ -55,12 +55,14 @@ Clock Source
 
 .. list::
 
-    - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`: Default PLL clock.
+    - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`: Default clock source. The actual source clock depends on the chip. See chip's Technical Reference Manual for details.
     :SOC_I2S_SUPPORTS_PLL_F160M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`: 160 MHz PLL clock.
     :SOC_I2S_SUPPORTS_PLL_F120M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`: 120 MHz PLL clock.
     :SOC_I2S_SUPPORTS_PLL_F96M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`: 96 MHz PLL clock.
     :SOC_I2S_SUPPORTS_PLL_F240M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`: 240 MHz PLL clock.
-    :SOC_I2S_SUPPORTS_APLL: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`: Audio PLL clock, which is more precise than ``I2S_CLK_SRC_PLL_160M`` in high sample rate applications. Its frequency is configurable according to the sample rate. However, if APLL has been occupied by EMAC or other channels, the APLL frequency cannot be changed, and the driver will try to work under this APLL frequency. If this frequency cannot meet the requirements of I2S, the clock configuration will fail.
+    :SOC_I2S_SUPPORTS_APLL: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`: Audio PLL clock. Its frequency is configurable according to the sample rate, which makes it more precise in high sample rate applications. However, if APLL has been occupied by EMAC or other channels, the APLL frequency cannot be changed, and the driver will try to work under this APLL frequency. If this frequency cannot meet the requirements of I2S, the clock configuration will fail.
+    :SOC_I2S_SUPPORTS_RTC_FAST: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_RTC_FAST`: RTC_FAST clock source.
+    :SOC_I2S_SUPPORTS_EXTERNAL: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_EXTERNAL`: External clock source.
 
 Clock Terminology
 ^^^^^^^^^^^^^^^^^

docs/zh_CN/api-reference/peripherals/i2s.rst

@@ -3,7 +3,7 @@ I2S
 
 :link_to_translation:`en:[English]`
 
-{IDF_TARGET_I2S_NUM:default="1", esp32="2", esp32s3="2", esp32p4="3"}
+{IDF_TARGET_I2S_NUM:default="1", esp32="2", esp32s3="2", esp32p4="3", esp32s31="2"}
 {IDF_TARGET_I2S_STD_TDM:default="标准和 TDM", esp32="标准", esp32s2="标准"}
 
 简介
@@ -55,12 +55,14 @@ I2S 时钟
 
 .. list::
 
-    - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`：默认 PLL 时钟。
+    - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`：默认时钟源。实际时钟源取决于具体芯片，详情请参阅芯片技术参考手册。
     :SOC_I2S_SUPPORTS_PLL_F160M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`：160 MHz PLL 时钟。
     :SOC_I2S_SUPPORTS_PLL_F120M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`：120 MHz PLL 时钟。
     :SOC_I2S_SUPPORTS_PLL_F96M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`：96 MHz PLL 时钟。
     :SOC_I2S_SUPPORTS_PLL_F240M: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`：240 MHz PLL 时钟。
-    :SOC_I2S_SUPPORTS_APLL: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`：音频 PLL 时钟，在高采样率应用中比 ``I2S_CLK_SRC_PLL_160M`` 更精确。其频率可根据采样率进行配置，但如果 APLL 已经被 EMAC 或其他通道占用，则无法更改 APLL 频率，驱动程序将尝试在原有 APLL 频率下工作。如果原有 APLL 频率无法满足 I2S 的需求，时钟配置将失败。
+    :SOC_I2S_SUPPORTS_APLL: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_APLL`：音频 PLL 时钟。其频率可根据采样率进行配置，在高采样率应用中精度更高。但如果 APLL 已经被 EMAC 或其他通道占用，则无法更改 APLL 频率，驱动程序将尝试在原有 APLL 频率下工作。如果原有 APLL 频率无法满足 I2S 的需求，时钟配置将失败。
+    :SOC_I2S_SUPPORTS_RTC_FAST: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_RTC_FAST`：RTC_FAST 时钟源。
+    :SOC_I2S_SUPPORTS_EXTERNAL: - :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_EXTERNAL`：外部时钟源。
 
 时钟术语
 ^^^^^^^^

examples/peripherals/.build-test-rules.yml

@@ -231,10 +231,6 @@ examples/peripherals/i2s/i2s_codec/i2s_es7210_tdm:
   disable:
     - if: SOC_I2S_SUPPORTS_TDM != 1 or (SOC_I2C_SUPPORTED != 1 or SOC_GPSPI_SUPPORTED != 1)
       reason: rely on I2S TDM mode to receive audio, I2C to config es7210 and SPI to save audio to SD card
-  disable_test:
-    - if: IDF_TARGET in ["esp32p4", "esp32c61"]
-      temporary: true
-      reason: lack of runners
   depends_components:
     - esp_driver_i2s
     - esp_driver_dma

examples/peripherals/i2s/i2s_basic/i2s_pdm/README.md

@@ -1,5 +1,5 @@
-| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 |
+| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 | ESP32-S31 |
-| ----------------- | ----- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- |
+| ----------------- | ----- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | --------- |
 
 # I2S Basic PDM Mode Example
 

examples/peripherals/i2s/i2s_basic/i2s_pdm/pytest_i2s_pdm.py

@@ -3,15 +3,17 @@
 import pytest
 from pytest_embedded import Dut
 from pytest_embedded_idf.utils import idf_parametrize
+from pytest_embedded_idf.utils import soc_filtered_targets
 
 
 @pytest.mark.generic
 @pytest.mark.parametrize('config', ['pdm_tx'], indirect=True)
 @idf_parametrize(
     'target',
-    ['esp32', 'esp32s3', 'esp32c3', 'esp32c5', 'esp32c6', 'esp32h2', 'esp32p4', 'esp32c61'],
+    soc_filtered_targets('SOC_I2S_SUPPORTS_PDM == 1'),
     indirect=['target'],
 )
+@pytest.mark.temp_skip_ci(targets=['esp32h21', 'esp32h4'], reason='lack of runners')
 def test_i2s_pdm_tx_example(dut: Dut) -> None:
     dut.expect(r'I2S PDM TX example start', timeout=5)
     dut.expect(r'---------------------------', timeout=5)
@@ -33,7 +35,7 @@ def test_i2s_pdm_tx_example(dut: Dut) -> None:
 
 @pytest.mark.generic
 @pytest.mark.parametrize('config', ['pdm_rx'], indirect=True)
-@idf_parametrize('target', ['esp32', 'esp32s3', 'esp32p4'], indirect=['target'])
+@idf_parametrize('target', ['esp32', 'esp32s3', 'esp32s31', 'esp32p4'], indirect=['target'])
 def test_i2s_pdm_rx_example(dut: Dut) -> None:
     dut.expect(r'I2S PDM RX example start', timeout=5)
     dut.expect(r'---------------------------', timeout=5)

examples/peripherals/i2s/i2s_basic/i2s_std/README.md

@@ -1,5 +1,5 @@
-| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
-| ----------------- | ----- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- |
+| ----------------- | ----- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |
 
 # I2S Basic Standard Mode Example
 

examples/peripherals/i2s/i2s_basic/i2s_std/pytest_i2s_std.py

@@ -3,14 +3,16 @@
 import pytest
 from pytest_embedded import Dut
 from pytest_embedded_idf.utils import idf_parametrize
+from pytest_embedded_idf.utils import soc_filtered_targets
 
 
 @pytest.mark.generic
 @idf_parametrize(
     'target',
-    ['esp32', 'esp32s2', 'esp32s3', 'esp32c3', 'esp32c5', 'esp32c6', 'esp32h2', 'esp32p4', 'esp32c61'],
+    soc_filtered_targets('SOC_I2S_SUPPORTED == 1'),
     indirect=['target'],
 )
+@pytest.mark.temp_skip_ci(targets=['esp32h21', 'esp32h4'], reason='lack of runners')
 def test_i2s_basic_example(dut: Dut) -> None:
     dut.expect(r'i2s_common: tx channel is registered on I2S0 successfully', timeout=5)
     dut.expect(r'i2s_common: rx channel is registered on I2S0 successfully', timeout=5)

examples/peripherals/i2s/i2s_basic/i2s_tdm/README.md

@@ -1,5 +1,5 @@
-| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 |
+| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 | ESP32-S31 |
-| ----------------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- |
+| ----------------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | --------- |
 
 # I2S Basic TDM Mode Example
 

examples/peripherals/i2s/i2s_basic/i2s_tdm/pytest_i2s_tdm.py

@@ -3,12 +3,16 @@
 import pytest
 from pytest_embedded import Dut
 from pytest_embedded_idf.utils import idf_parametrize
+from pytest_embedded_idf.utils import soc_filtered_targets
 
 
 @pytest.mark.generic
 @idf_parametrize(
-    'target', ['esp32s3', 'esp32c3', 'esp32c5', 'esp32c6', 'esp32h2', 'esp32p4', 'esp32c61'], indirect=['target']
+    'target',
+    soc_filtered_targets('SOC_I2S_SUPPORTS_TDM == 1'),
+    indirect=['target'],
 )
+@pytest.mark.temp_skip_ci(targets=['esp32h21', 'esp32h4'], reason='lack of runners')
 def test_i2s_tdm_example(dut: Dut) -> None:
     dut.expect(r'i2s_common: tx channel is registered on I2S0 successfully', timeout=5)
     dut.expect(r'i2s_common: rx channel is registered on I2S0 successfully', timeout=5)

examples/peripherals/i2s/i2s_codec/i2s_es7210_tdm/README.md

@@ -1,5 +1,5 @@
-| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 |
+| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 | ESP32-S31 |
-| ----------------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- |
+| ----------------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | --------- |
 
 # I2S TDM Example -- ES7210 4-Ch ADC Codec
 

examples/peripherals/i2s/i2s_codec/i2s_es7210_tdm/pytest_i2s_es7210_tdm.py

@@ -3,10 +3,12 @@
 import pytest
 from pytest_embedded import Dut
 from pytest_embedded_idf.utils import idf_parametrize
+from pytest_embedded_idf.utils import soc_filtered_targets
 
 
 @pytest.mark.generic
-@idf_parametrize('target', ['esp32s3', 'esp32c3', 'esp32c5', 'esp32c6', 'esp32h2'], indirect=['target'])
+@idf_parametrize('target', soc_filtered_targets('SOC_I2S_SUPPORTS_TDM == 1'), indirect=['target'])
+@pytest.mark.temp_skip_ci(targets=['esp32h21', 'esp32h4'], reason='lack of runners')
 def test_i2s_es7210_tdm_example(dut: Dut) -> None:
     dut.expect_exact('example: Create I2S receive channel')
     dut.expect_exact('example: Configure I2S receive channel to TDM mode')

examples/peripherals/i2s/i2s_codec/i2s_es8311/README.md

@@ -1,5 +1,5 @@
-| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
-| ----------------- | ----- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- |
+| ----------------- | ----- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |
 
 # I2S ES8311 Example
 

examples/peripherals/i2s/i2s_codec/i2s_es8311/pytest_i2s_es8311.py

@@ -3,14 +3,16 @@
 import pytest
 from pytest_embedded import Dut
 from pytest_embedded_idf.utils import idf_parametrize
+from pytest_embedded_idf.utils import soc_filtered_targets
 
 
 @pytest.mark.generic
 @idf_parametrize(
     'target',
-    ['esp32', 'esp32s2', 'esp32s3', 'esp32c3', 'esp32c5', 'esp32c6', 'esp32h2', 'esp32p4', 'esp32c61'],
+    soc_filtered_targets('SOC_I2S_SUPPORTED == 1'),
     indirect=['target'],
 )
+@pytest.mark.temp_skip_ci(targets=['esp32h21', 'esp32h4'], reason='lack of runners')
 def test_i2s_es8311_example_generic(dut: Dut) -> None:
     dut.expect('i2s es8311 codec example start')
     dut.expect('-----------------------------')

examples/peripherals/i2s/i2s_examples_common/i2s_example_pins.h

@@ -38,7 +38,7 @@ extern "C" {
 #define EXAMPLE_I2S_DOUT_IO2        GPIO_NUM_22     // I2S data out io number
 #define EXAMPLE_I2S_DIN_IO2         GPIO_NUM_23     // I2S data in io number
 
-#elif CONFIG_IDF_TARGET_ESP32S3
+#elif CONFIG_IDF_TARGET_ESP32S3 || CONFIG_IDF_TARGET_ESP32S31
 #define EXAMPLE_I2S_BCLK_IO1        GPIO_NUM_2      // I2S bit clock io number
 #define EXAMPLE_I2S_WS_IO1          GPIO_NUM_3      // I2S word select io number
 #define EXAMPLE_I2S_DOUT_IO1        GPIO_NUM_4      // I2S data out io number