espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-08-01 19:54:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'bugfix/fix_i2s_std_initializer_order_for_cpp_compiler_v5.4' into 'release/v5.4'

Browse Source 
fix(i2s): fixed i2s_std initializer order for cpp compiler (v5.4)

See merge request espressif/esp-idf!37047
This commit is contained in:
Jiang Jiang Jian
2025-02-21 11:48:58 +08:00
parent 6150ea9a43 b18506da8b
commit aa97a0fc3c
13 changed files with 142 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
components/esp_driver_i2s/include/driver/i2s_pdm.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/

2
components/esp_driver_i2s/include/driver/i2s_std.h
View File

@@ -215,8 +215,8 @@ extern "C" {
#define I2S_STD_CLK_DEFAULT_CONFIG(rate) { \
.sample_rate_hz = rate, \
.clk_src = I2S_CLK_SRC_DEFAULT, \
.mclk_multiple = I2S_MCLK_MULTIPLE_256, \
.ext_clk_freq_hz = 0, \
.mclk_multiple = I2S_MCLK_MULTIPLE_256, \
}
#endif

32
components/esp_driver_i2s/test_apps/i2s/main/test_i2s.c
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -986,3 +986,33 @@ TEST_CASE("I2S_asynchronous_read_write", "[i2s]")
TEST_ASSERT(received);
}
#if SOC_I2S_SUPPORTS_PDM2PCM
TEST_CASE("I2S_PDM2PCM_existence_test", "[i2s]")
{
i2s_chan_handle_t rx_handle;
i2s_chan_config_t rx_chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(I2S_NUM_AUTO, I2S_ROLE_MASTER);
TEST_ESP_OK(i2s_new_channel(&rx_chan_cfg, NULL, &rx_handle));
i2s_pdm_rx_config_t pdm_rx_cfg = {
.clk_cfg = I2S_PDM_RX_CLK_DEFAULT_CONFIG(16000),
.slot_cfg = I2S_PDM_RX_SLOT_PCM_FMT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_MONO),
.gpio_cfg = {
.clk = MASTER_BCK_IO,
.din = DATA_IN_IO,
.invert_flags = {
.clk_inv = false,
},
},
};
TEST_ESP_OK(i2s_channel_init_pdm_rx_mode(rx_handle, &pdm_rx_cfg));
TEST_ESP_OK(i2s_channel_enable(rx_handle));
uint8_t *r_buf[64] = {};
size_t r_bytes = 0;
// If PDM2PCM is not supported in the hardware, it will fail to read.
TEST_ESP_OK(i2s_channel_read(rx_handle, r_buf, 64, &r_bytes, 1000));
TEST_ESP_OK(i2s_channel_disable(rx_handle));
TEST_ESP_OK(i2s_del_channel(rx_handle));
}
#endif

3
components/hal/esp32c5/include/hal/i2s_ll.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -743,7 +743,6 @@ static inline void i2s_ll_rx_enable_tdm(i2s_dev_t *hw)
{
hw->rx_conf.rx_pdm_en = false;
hw->rx_conf.rx_tdm_en = true;
hw->rx_pdm2pcm_conf.rx_pdm2pcm_en = false;
}
/**

2
components/hal/esp32c61/include/hal/i2s_ll.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/

52
components/soc/esp32c5/register/soc/i2s_reg.h
View File

@@ -1,5 +1,5 @@
/**
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -836,56 +836,6 @@ 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 configure register
*/
#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.
*/
#define I2S_RX_PDM2PCM_EN (BIT(19))
#define I2S_RX_PDM2PCM_EN_M (I2S_RX_PDM2PCM_EN_V << I2S_RX_PDM2PCM_EN_S)
#define I2S_RX_PDM2PCM_EN_V 0x00000001U
#define I2S_RX_PDM2PCM_EN_S 19
/** I2S_RX_PDM_SINC_DSR_16_EN : R/W; bitpos: [20]; default: 0;
* Configure the down sampling rate of PDM RX filter group1 module. 1: The down
* sampling rate is 128. 0: down sampling rate is 64.
*/
#define I2S_RX_PDM_SINC_DSR_16_EN (BIT(20))
#define I2S_RX_PDM_SINC_DSR_16_EN_M (I2S_RX_PDM_SINC_DSR_16_EN_V << I2S_RX_PDM_SINC_DSR_16_EN_S)
#define I2S_RX_PDM_SINC_DSR_16_EN_V 0x00000001U
#define I2S_RX_PDM_SINC_DSR_16_EN_S 20
/** I2S_RX_PDM2PCM_AMPLIFY_NUM : R/W; bitpos: [24:21]; default: 1;
* Configure PDM RX amplify number.
*/
#define I2S_RX_PDM2PCM_AMPLIFY_NUM 0x0000000FU
#define I2S_RX_PDM2PCM_AMPLIFY_NUM_M (I2S_RX_PDM2PCM_AMPLIFY_NUM_V << I2S_RX_PDM2PCM_AMPLIFY_NUM_S)
#define I2S_RX_PDM2PCM_AMPLIFY_NUM_V 0x0000000FU
#define I2S_RX_PDM2PCM_AMPLIFY_NUM_S 21
/** I2S_RX_PDM_HP_BYPASS : R/W; bitpos: [25]; default: 0;
* I2S PDM RX bypass hp filter or not.
*/
#define I2S_RX_PDM_HP_BYPASS (BIT(25))
#define I2S_RX_PDM_HP_BYPASS_M (I2S_RX_PDM_HP_BYPASS_V << I2S_RX_PDM_HP_BYPASS_S)
#define I2S_RX_PDM_HP_BYPASS_V 0x00000001U
#define I2S_RX_PDM_HP_BYPASS_S 25
/** I2S_RX_IIR_HP_MULT12_5 : R/W; bitpos: [28:26]; default: 6;
* The fourth parameter of PDM RX IIR_HP filter stage 2 is (504 +
* LP_I2S_RX_IIR_HP_MULT12_5[2:0])
*/
#define I2S_RX_IIR_HP_MULT12_5 0x00000007U
#define I2S_RX_IIR_HP_MULT12_5_M (I2S_RX_IIR_HP_MULT12_5_V << I2S_RX_IIR_HP_MULT12_5_S)
#define I2S_RX_IIR_HP_MULT12_5_V 0x00000007U
#define I2S_RX_IIR_HP_MULT12_5_S 26
/** I2S_RX_IIR_HP_MULT12_0 : R/W; bitpos: [31:29]; default: 7;
* The fourth parameter of PDM RX IIR_HP filter stage 1 is (504 +
* LP_I2S_RX_IIR_HP_MULT12_0[2:0])
*/
#define I2S_RX_IIR_HP_MULT12_0 0x00000007U
#define I2S_RX_IIR_HP_MULT12_0_M (I2S_RX_IIR_HP_MULT12_0_V << I2S_RX_IIR_HP_MULT12_0_S)
#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 TX TDM mode control register
*/

41
components/soc/esp32c5/register/soc/i2s_struct.h
View File

@@ -1,5 +1,5 @@
/**
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -295,43 +295,6 @@ typedef union {
uint32_t val;
} i2s_rx_recomb_dma_chn_reg_t;
/** Type of rx_pdm2pcm_conf register
* I2S RX configure register
*/
typedef union {
struct {
uint32_t reserved_0:19;
/** rx_pdm2pcm_en : R/W; bitpos: [19]; default: 0;
* 1: Enable PDM2PCM RX mode. 0: DIsable.
*/
uint32_t rx_pdm2pcm_en:1;
/** rx_pdm_sinc_dsr_16_en : R/W; bitpos: [20]; default: 0;
* Configure the down sampling rate of PDM RX filter group1 module. 1: The down
* sampling rate is 128. 0: down sampling rate is 64.
*/
uint32_t rx_pdm_sinc_dsr_16_en:1;
/** rx_pdm2pcm_amplify_num : R/W; bitpos: [24:21]; default: 1;
* Configure PDM RX amplify number.
*/
uint32_t rx_pdm2pcm_amplify_num:4;
/** rx_pdm_hp_bypass : R/W; bitpos: [25]; default: 0;
* I2S PDM RX bypass hp filter or not.
*/
uint32_t rx_pdm_hp_bypass:1;
/** rx_iir_hp_mult12_5 : R/W; bitpos: [28:26]; default: 6;
* The fourth parameter of PDM RX IIR_HP filter stage 2 is (504 +
* LP_I2S_RX_IIR_HP_MULT12_5[2:0])
*/
uint32_t rx_iir_hp_mult12_5:3;
/** rx_iir_hp_mult12_0 : R/W; bitpos: [31:29]; default: 7;
* The fourth parameter of PDM RX IIR_HP filter stage 1 is (504 +
* LP_I2S_RX_IIR_HP_MULT12_0[2:0])
*/
uint32_t rx_iir_hp_mult12_0:3;
};
uint32_t val;
} i2s_rx_pdm2pcm_conf_reg_t;
/** Type of rx_tdm_ctrl register
* I2S TX TDM mode control register
*/
@@ -1038,7 +1001,7 @@ typedef struct {
volatile i2s_rx_recomb_dma_chn_reg_t rx_recomb_dma_ch[4];
volatile i2s_tx_pcm2pdm_conf_reg_t tx_pcm2pdm_conf;
volatile i2s_tx_pcm2pdm_conf1_reg_t tx_pcm2pdm_conf1;
volatile i2s_rx_pdm2pcm_conf_reg_t rx_pdm2pcm_conf;
uint32_t reserved_048;
volatile i2s_rx_tdm_ctrl_reg_t rx_tdm_ctrl;
volatile i2s_tx_tdm_ctrl_reg_t tx_tdm_ctrl;
volatile i2s_rx_timing_reg_t rx_timing;

36
components/soc/esp32c61/register/soc/i2s_reg.h
View File

@@ -1,5 +1,5 @@
/**
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -661,40 +661,6 @@ 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 configure register
*/
#define I2S_RX_PDM2PCM_CONF_REG (DR_REG_I2S_BASE + 0x48)
/** I2S_RX_PDM2PCM_EN : R/W; bitpos: [19]; default: 0;
* 1: Enable PDM2PCM RX mode. 0: DIsable.
*/
#define I2S_RX_PDM2PCM_EN (BIT(19))
#define I2S_RX_PDM2PCM_EN_M (I2S_RX_PDM2PCM_EN_V << I2S_RX_PDM2PCM_EN_S)
#define I2S_RX_PDM2PCM_EN_V 0x00000001U
#define I2S_RX_PDM2PCM_EN_S 19
/** I2S_RX_PDM_SINC_DSR_16_EN : R/W; bitpos: [20]; default: 0;
* Configure the down sampling rate of PDM RX filter group1 module. 1: The down
* sampling rate is 128. 0: down sampling rate is 64.
*/
#define I2S_RX_PDM_SINC_DSR_16_EN (BIT(20))
#define I2S_RX_PDM_SINC_DSR_16_EN_M (I2S_RX_PDM_SINC_DSR_16_EN_V << I2S_RX_PDM_SINC_DSR_16_EN_S)
#define I2S_RX_PDM_SINC_DSR_16_EN_V 0x00000001U
#define I2S_RX_PDM_SINC_DSR_16_EN_S 20
/** I2S_RX_PDM2PCM_AMPLIFY_NUM : R/W; bitpos: [24:21]; default: 1;
* Configure PDM RX amplify number.
*/
#define I2S_RX_PDM2PCM_AMPLIFY_NUM 0x0000000FU
#define I2S_RX_PDM2PCM_AMPLIFY_NUM_M (I2S_RX_PDM2PCM_AMPLIFY_NUM_V << I2S_RX_PDM2PCM_AMPLIFY_NUM_S)
#define I2S_RX_PDM2PCM_AMPLIFY_NUM_V 0x0000000FU
#define I2S_RX_PDM2PCM_AMPLIFY_NUM_S 21
/** I2S_RX_PDM_HP_BYPASS : R/W; bitpos: [25]; default: 0;
* I2S PDM RX bypass hp filter or not.
*/
#define I2S_RX_PDM_HP_BYPASS (BIT(25))
#define I2S_RX_PDM_HP_BYPASS_M (I2S_RX_PDM_HP_BYPASS_V << I2S_RX_PDM_HP_BYPASS_S)
#define I2S_RX_PDM_HP_BYPASS_V 0x00000001U
#define I2S_RX_PDM_HP_BYPASS_S 25
/** I2S_RX_TDM_CTRL_REG register
* I2S TX TDM mode control register
*/

33
components/soc/esp32c61/register/soc/i2s_struct.h
View File

@@ -1,5 +1,5 @@
/**
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -240,34 +240,6 @@ typedef union {
uint32_t val;
} i2s_rx_conf1_reg_t;
/** Type of rx_pdm2pcm_conf register
* I2S RX configure register
*/
typedef union {
struct {
uint32_t reserved_0:19;
/** rx_pdm2pcm_en : R/W; bitpos: [19]; default: 0;
* 1: Enable PDM2PCM RX mode. 0: DIsable.
*/
uint32_t rx_pdm2pcm_en:1;
/** rx_pdm_sinc_dsr_16_en : R/W; bitpos: [20]; default: 0;
* Configure the down sampling rate of PDM RX filter group1 module. 1: The down
* sampling rate is 128. 0: down sampling rate is 64.
*/
uint32_t rx_pdm_sinc_dsr_16_en:1;
/** rx_pdm2pcm_amplify_num : R/W; bitpos: [24:21]; default: 1;
* Configure PDM RX amplify number.
*/
uint32_t rx_pdm2pcm_amplify_num:4;
/** rx_pdm_hp_bypass : R/W; bitpos: [25]; default: 0;
* I2S PDM RX bypass hp filter or not.
*/
uint32_t rx_pdm_hp_bypass:1;
uint32_t reserved_26:6;
};
uint32_t val;
} i2s_rx_pdm2pcm_conf_reg_t;
/** Type of rx_tdm_ctrl register
* I2S TX TDM mode control register
*/
@@ -973,8 +945,7 @@ typedef struct {
uint32_t reserved_030[4];
volatile i2s_tx_pcm2pdm_conf_reg_t tx_pcm2pdm_conf;
volatile i2s_tx_pcm2pdm_conf1_reg_t tx_pcm2pdm_conf1;
volatile i2s_rx_pdm2pcm_conf_reg_t rx_pdm2pcm_conf;
uint32_t reserved_04c;
uint32_t reserved_048[2];
volatile i2s_rx_tdm_ctrl_reg_t rx_tdm_ctrl;
volatile i2s_tx_tdm_ctrl_reg_t tx_tdm_ctrl;
volatile i2s_rx_timing_reg_t rx_timing;

48
docs/en/api-reference/peripherals/i2s.rst
View File

@@ -3,7 +3,8 @@ Inter-IC Sound (I2S)
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_I2S_NUM:default="one", esp32="two", esp32s3="two"}
{IDF_TARGET_I2S_NUM:default="one", esp32="two", esp32s3="two", esp32p4="three"}
{IDF_TARGET_I2S_STD_TDM:default="standard and TDM", esp32="standard", esp32s2="standard"}
Introduction
------------
@@ -18,7 +19,7 @@ I2S (Inter-IC Sound) is a synchronous serial communication protocol usually used
{IDF_TARGET_NAME} contains {IDF_TARGET_I2S_NUM} I2S peripheral(s). These peripherals can be configured to input and output sample data via the I2S driver.
An I2S bus that communicates in standard or TDM mode consists of the following lines:
An I2S bus that communicates in {IDF_TARGET_I2S_STD_TDM} mode consists of the following lines:
- **MCLK:** Master clock line. It is an optional signal depending on the slave side, mainly used for offering a reference clock to the I2S slave device.
- **BCLK:** Bit clock line. The bit clock for data line.
@@ -57,10 +58,12 @@ I2S File Structure
**Public headers that need to be included in the I2S application are as follows:**
- ``i2s.h``: The header file that provides legacy I2S APIs (for apps using legacy driver).
- ``i2s_std.h``: The header file that provides standard communication mode specific APIs (for apps using new driver with standard mode).
- ``i2s_pdm.h``: The header file that provides PDM communication mode specific APIs (for apps using new driver with PDM mode).
- ``i2s_tdm.h``: The header file that provides TDM communication mode specific APIs (for apps using new driver with TDM mode).
.. list::
- ``i2s.h``: The header file that provides legacy I2S APIs (for apps using legacy driver).
- ``i2s_std.h``: The header file that provides standard communication mode specific APIs (for apps using new driver with standard mode).
:SOC_I2S_SUPPORTS_PDM: - ``i2s_pdm.h``: The header file that provides PDM communication mode specific APIs (for apps using new driver with PDM mode).
:SOC_I2S_SUPPORTS_TDM: - ``i2s_tdm.h``: The header file that provides TDM communication mode specific APIs (for apps using new driver with TDM mode).
.. note::
@@ -78,27 +81,14 @@ I2S Clock
Clock Source
^^^^^^^^^^^^
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`: Default PLL clock.
.. list::
.. only:: SOC_I2S_SUPPORTS_PLL_F160M
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`: 160 MHz PLL clock.
.. only:: SOC_I2S_SUPPORTS_PLL_F120M
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`: 120 MHz PLL clock.
.. only:: SOC_I2S_SUPPORTS_PLL_F96M
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`: 96 MHz PLL clock.
.. only:: SOC_I2S_SUPPORTS_PLL_F240M
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`: 240 MHz PLL clock.
.. only:: 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.
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`: Default PLL clock.
: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.
Clock Terminology
^^^^^^^^^^^^^^^^^
@@ -131,8 +121,8 @@ ESP32-C6 I2S 0 I2S 0 none I2S 0 none none
ESP32-S3 I2S 0/1 I2S 0 I2S 0 I2S 0/1 none none
ESP32-H2 I2S 0 I2S 0 none I2S 0 none none
ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 none none
ESP32-C5 I2S 0 I2S 0 I2S 0 I2S 0 none none
ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 none none
ESP32-C5 I2S 0 I2S 0 none I2S 0 none none
ESP32-C61 I2S 0 I2S 0 none I2S 0 none none
========= ======== ======== ======== ======== ======== ==========
Standard Mode
@@ -847,7 +837,7 @@ Here is the table of the data received in the buffer with different :cpp:member:
Full-duplex
^^^^^^^^^^^
Full-duplex mode registers TX and RX channel in an I2S port at the same time, and the channels share the BCLK and WS signals. Currently, STD and TDM communication modes supports full-duplex mode in the following way, but PDM full-duplex is not supported because due to different PDM TX and RX clocks.
Full-duplex mode registers TX and RX channel in an I2S port at the same time, and the channels share the BCLK and WS signals. Currently, {IDF_TARGET_I2S_STD_TDM} communication modes supports full-duplex mode in the following way, but PDM full-duplex is not supported because due to different PDM TX and RX clocks.
Note that one handle can only stand for one channel. Therefore, it is still necessary to configure the slot and clock for both TX and RX channels one by one.

48
docs/zh_CN/api-reference/peripherals/i2s.rst
View File

@@ -3,7 +3,8 @@ I2S
:link_to_translation:`en:[English]`
{IDF_TARGET_I2S_NUM:default="1", esp32="2", esp32s3="2"}
{IDF_TARGET_I2S_NUM:default="1", esp32="2", esp32s3="2", esp32p4="3"}
{IDF_TARGET_I2S_STD_TDM:default="标准和 TDM", esp32="标准", esp32s2="标准"}
简介
----
@@ -12,7 +13,7 @@ I2S（Inter-IC Sound，集成电路内置音频总线）是一种同步串行通
{IDF_TARGET_NAME} 包含 {IDF_TARGET_I2S_NUM} 个 I2S 外设。通过配置这些外设，可以借助 I2S 驱动来输入和输出采样数据。
标准或 TDM 通信模式下的 I2S 总线包含以下几条线路：
{IDF_TARGET_I2S_STD_TDM} 模式下的 I2S 总线包含以下几条线路：
- **MCLK**：主时钟线。该信号线可选，具体取决于从机，主要用于向 I2S 从机提供参考时钟。
- **BCLK**：位时钟线。用于数据线的位时钟。
@@ -51,10 +52,12 @@ I2S 文件结构
**需要包含在 I2S 应用中的公共头文件如下所示：**
- ``i2s.h``：提供原有 I2S API（用于使用原有驱动的应用）。
- ``i2s_std.h``：提供标准通信模式的 API（用于使用标准模式的新驱动程序的应用）。
- ``i2s_pdm.h``：提供 PDM 通信模式的 API（用于使用 PDM 模式的新驱动程序的应用）。
- ``i2s_tdm.h``：提供 TDM 通信模式的 API（用于使用 TDM 模式的新驱动的应用）。
.. list::
- ``i2s.h``：提供原有 I2S API（用于使用原有驱动的应用）。
- ``i2s_std.h``：提供标准通信模式的 API（用于使用标准模式的新驱动程序的应用）。
:SOC_I2S_SUPPORTS_PDM: - ``i2s_pdm.h``：提供 PDM 通信模式的 API（用于使用 PDM 模式的新驱动程序的应用）。
:SOC_I2S_SUPPORTS_TDM: - ``i2s_tdm.h``：提供 TDM 通信模式的 API（用于使用 TDM 模式的新驱动的应用）。
.. note::
@@ -72,27 +75,14 @@ I2S 时钟
时钟源
^^^^^^
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`：默认 PLL 时钟。
.. list::
.. only:: SOC_I2S_SUPPORTS_PLL_F160M
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_160M`：160 MHz PLL 时钟。
.. only:: SOC_I2S_SUPPORTS_PLL_F120M
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_120M`：120 MHz PLL 时钟。
.. only:: SOC_I2S_SUPPORTS_PLL_F96M
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_96M`：96 MHz PLL 时钟。
.. only:: SOC_I2S_SUPPORTS_PLL_F240M
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_PLL_240M`：240 MHz PLL 时钟。
.. only:: 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 的需求，时钟配置将失败。
- :cpp:enumerator:`i2s_clock_src_t::I2S_CLK_SRC_DEFAULT`：默认 PLL 时钟。
: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 的需求，时钟配置将失败。
时钟术语
^^^^^^^^
@@ -125,8 +115,8 @@ ESP32-C6 I2S 0 I2S 0 无 I2S 0 无 无
ESP32-S3 I2S 0/1 I2S 0 I2S 0 I2S 0/1 无 无
ESP32-H2 I2S 0 I2S 0 无 I2S 0 无 无
ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 无 无
ESP32-C5 I2S 0 I2S 0 I2S 0 I2S 0 无 无
ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 无 无
ESP32-C5 I2S 0 I2S 0 无 I2S 0 无 无
ESP32-C61 I2S 0 I2S 0 无 I2S 0 无 无
========= ======== ======== ======== ======== ======== ==========
标准模式
@@ -841,7 +831,7 @@ STD RX 模式
全双工
^^^^^^
全双工模式可以在 I2S 端口中同时注册 TX 和 RX 通道，同时通道共享 BCLK 和 WS 信号。目前，STD 和 TDM 通信模式支持以下方式的全双工通信，但不支持 PDM 全双工模式，因为 PDM 模式下 TX 和 RX 通道的时钟不同。
全双工模式可以在 I2S 端口中同时注册 TX 和 RX 通道，同时通道共享 BCLK 和 WS 信号。目前，{IDF_TARGET_I2S_STD_TDM} 通信模式支持以下方式的全双工通信，但不支持 PDM 全双工模式，因为 PDM 模式下 TX 和 RX 通道的时钟不同。
请注意，一个句柄只能代表一个通道，因此仍然需要对 TX 和 RX 通道逐个进行声道和时钟配置。

6
tools/test_apps/system/cxx_build_test/main/CMakeLists.txt
View File

@@ -7,11 +7,15 @@ if(CONFIG_SOC_I2C_SUPPORTED)
list(APPEND srcs test_i2c_lcd.cpp)
endif()
if(CONFIG_SOC_I2S_SUPPORTED)
list(APPEND srcs test_i2s.cpp)
endif()
if(CONFIG_SOC_TWAI_SUPPORTED)
list(APPEND srcs test_twai.cpp)
endif()
idf_component_register(SRCS "${srcs}"
INCLUDE_DIRS "."
PRIV_REQUIRES driver esp_lcd
PRIV_REQUIRES driver esp_lcd esp_driver_i2s
REQUIRES soc)

58
tools/test_apps/system/cxx_build_test/main/test_i2s.cpp Normal file
View File

@@ -0,0 +1,58 @@
/*
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#include "soc/soc_caps.h"
#include "driver/i2s_std.h"
#if SOC_I2S_SUPPORTS_TDM
#include "driver/i2s_tdm.h"
#endif
#if SOC_I2S_SUPPORTS_PDM
#include "driver/i2s_pdm.h"
#endif
/**
* Check that C-style designated initializers are valid in C++ file.
*/
void test_i2s_initializers(void)
{
i2s_std_clk_config_t std_clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(16000);
i2s_std_slot_config_t std_philips_slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO);
i2s_std_slot_config_t std_msb_slot_cfg = I2S_STD_MSB_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO);
i2s_std_slot_config_t std_pcm_slot_cfg = I2S_STD_PCM_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO);
(void) std_clk_cfg;
(void) std_philips_slot_cfg;
(void) std_msb_slot_cfg;
(void) std_pcm_slot_cfg;
#if SOC_I2S_SUPPORTS_TDM
i2s_tdm_clk_config_t tdm_clk_cfg = I2S_TDM_CLK_DEFAULT_CONFIG(16000);
i2s_tdm_slot_config_t tdm_philips_slot_cfg = I2S_TDM_PHILIPS_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO, (i2s_tdm_slot_mask_t)0x03);
i2s_tdm_slot_config_t tdm_msb_slot_cfg = I2S_TDM_MSB_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO, (i2s_tdm_slot_mask_t)0x03);
i2s_tdm_slot_config_t tdm_pcm_s_slot_cfg = I2S_TDM_PCM_SHORT_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO, (i2s_tdm_slot_mask_t)0x03);
i2s_tdm_slot_config_t tdm_pcm_l_slot_cfg = I2S_TDM_PCM_LONG_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO, (i2s_tdm_slot_mask_t)0x03);
(void) tdm_clk_cfg;
(void) tdm_philips_slot_cfg;
(void) tdm_msb_slot_cfg;
(void) tdm_pcm_s_slot_cfg;
(void) tdm_pcm_l_slot_cfg;
#endif
#if SOC_I2S_SUPPORTS_PDM_RX
i2s_pdm_rx_clk_config_t pdm_rx_clk_cfg = I2S_PDM_RX_CLK_DEFAULT_CONFIG(16000);
i2s_pdm_rx_slot_config_t pdm_rx_pcm_slot_cfg = I2S_PDM_RX_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO);
(void) pdm_rx_clk_cfg;
(void) pdm_rx_pcm_slot_cfg;
#endif
#if SOC_I2S_SUPPORTS_PDM_TX
i2s_pdm_tx_clk_config_t pdm_tx_clk_cfg = I2S_PDM_TX_CLK_DEFAULT_CONFIG(16000);
i2s_pdm_tx_clk_config_t pdm_tx_dac_clk_cfg = I2S_PDM_TX_CLK_DAC_DEFAULT_CONFIG(16000);
i2s_pdm_tx_slot_config_t pdm_tx_pcm_slot_cfg = I2S_PDM_TX_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO);
(void) pdm_tx_clk_cfg;
(void) pdm_tx_dac_clk_cfg;
(void) pdm_tx_pcm_slot_cfg;
#if SOC_I2S_HW_VERSION_2
i2s_pdm_tx_slot_config_t pdm_tx_pcm_dac_slot_cfg = I2S_PDM_TX_SLOT_DAC_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO);
(void) pdm_tx_pcm_dac_slot_cfg;
#endif
#endif
}