feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

Merge branch 'docs/fix_i2s_tdm_programming_guide' into 'master'

Browse Source 
docs(i2s): fix i2s capability in doc and code

Closes IDF-11854

See merge request espressif/esp-idf!36815
This commit is contained in:
Kevin (Lao Kaiyao)
2025-02-13 14:49:59 +08:00
parent 9184f62853 d4481517f7
commit c542692cc2
13 changed files with 80 additions and 389 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

76
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;
}
/**
@@ -946,80 +945,9 @@ static inline uint32_t i2s_ll_tx_get_pdm_fs(i2s_dev_t *hw)
*/
static inline void i2s_ll_rx_enable_pdm(i2s_dev_t *hw, bool pdm_enable)
{
(void)pdm_enable;
hw->rx_conf.rx_pdm_en = 0;
hw->rx_conf.rx_tdm_en = 1;
hw->rx_pdm2pcm_conf.rx_pdm2pcm_en = pdm_enable;
}
/**
* @brief Configure RX PDM downsample
*
* @param hw Peripheral I2S hardware instance address.
* @param dsr PDM downsample configuration parameter
*/
static inline void i2s_ll_rx_set_pdm_dsr(i2s_dev_t *hw, i2s_pdm_dsr_t dsr)
{
hw->rx_pdm2pcm_conf.rx_pdm_sinc_dsr_16_en = dsr;
}
/**
* @brief Get RX PDM downsample configuration
*
* @param hw Peripheral I2S hardware instance address.
* @param dsr Pointer to accept PDM downsample configuration
*/
static inline void i2s_ll_rx_get_pdm_dsr(i2s_dev_t *hw, i2s_pdm_dsr_t *dsr)
{
*dsr = (i2s_pdm_dsr_t)hw->rx_pdm2pcm_conf.rx_pdm_sinc_dsr_16_en;
}
/**
* @brief Configure RX PDM amplify number
* @note This is the amplification number of the digital amplifier,
* which is added after the PDM to PCM conversion result and mainly used for
* amplify the small PDM signal under the VAD scenario
* pcm_result = pdm_input * amplify_num
* pcm_result = 0 if amplify_num = 0
*
* @param hw Peripheral I2S hardware instance address.
* @param amp_num PDM RX amplify number
*/
static inline void i2s_ll_rx_set_pdm_amplify_num(i2s_dev_t *hw, uint32_t amp_num)
{
hw->rx_pdm2pcm_conf.rx_pdm2pcm_amplify_num = amp_num;
}
/**
* @brief Set I2S RX PDM high pass filter param0
*
* @param hw Peripheral I2S hardware instance address.
* @param param The fourth parameter of PDM RX IIR_HP filter stage 1 is (504 + I2S_RX_IIR_HP_MULT12_0[2:0])
*/
static inline void i2s_ll_rx_set_pdm_hp_filter_param0(i2s_dev_t *hw, uint32_t param)
{
hw->rx_pdm2pcm_conf.rx_iir_hp_mult12_0 = param;
}
/**
* @brief Set I2S RX PDM high pass filter param5
*
* @param hw Peripheral I2S hardware instance address.
* @param param The fourth parameter of PDM RX IIR_HP filter stage 2 is (504 + I2S_RX_IIR_HP_MULT12_5[2:0])
*/
static inline void i2s_ll_rx_set_pdm_hp_filter_param5(i2s_dev_t *hw, uint32_t param)
{
hw->rx_pdm2pcm_conf.rx_iir_hp_mult12_5 = param;
}
/**
* @brief Enable I2S RX PDM high pass filter
*
* @param hw Peripheral I2S hardware instance address.
* @param enable Set true to enable I2S RX PDM high pass filter, set false to bypass it
*/
static inline void i2s_ll_rx_enable_pdm_hp_filter(i2s_dev_t *hw, bool enable)
{
hw->rx_pdm2pcm_conf.rx_pdm_hp_bypass = !enable;
}
/**

81
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
*/
@@ -941,88 +941,13 @@ static inline uint32_t i2s_ll_tx_get_pdm_fs(i2s_dev_t *hw)
* @brief Enable RX PDM mode.
*
* @param hw Peripheral I2S hardware instance address.
* @param pdm2pcm Set true to RX enable PDM mode
* @param pdm2pcm Set true to RX enable PDM mode (ignored)
*/
static inline void i2s_ll_rx_enable_pdm(i2s_dev_t *hw, bool pdm2pcm)
{
(void)pdm2pcm;
hw->rx_conf.rx_pdm_en = 0;
hw->rx_conf.rx_tdm_en = 1;
hw->rx_pdm2pcm_conf.rx_pdm2pcm_en = pdm2pcm;
}
/**
* @brief Configure RX PDM downsample
*
* @param hw Peripheral I2S hardware instance address.
* @param dsr PDM downsample configuration parameter
*/
static inline void i2s_ll_rx_set_pdm_dsr(i2s_dev_t *hw, i2s_pdm_dsr_t dsr)
{
hw->rx_pdm2pcm_conf.rx_pdm_sinc_dsr_16_en = dsr;
}
/**
* @brief Get RX PDM downsample configuration
*
* @param hw Peripheral I2S hardware instance address.
* @param dsr Pointer to accept PDM downsample configuration
*/
static inline void i2s_ll_rx_get_pdm_dsr(i2s_dev_t *hw, i2s_pdm_dsr_t *dsr)
{
*dsr = (i2s_pdm_dsr_t)hw->rx_pdm2pcm_conf.rx_pdm_sinc_dsr_16_en;
}
/**
* @brief Configure RX PDM amplify number
* @note This is the amplification number of the digital amplifier,
* which is added after the PDM to PCM conversion result and mainly used for
* amplify the small PDM signal under the VAD scenario
* pcm_result = pdm_input * amplify_num
* pcm_result = 0 if amplify_num = 0
*
* @param hw Peripheral I2S hardware instance address.
* @param amp_num PDM RX amplify number
*/
static inline void i2s_ll_rx_set_pdm_amplify_num(i2s_dev_t *hw, uint32_t amp_num)
{
hw->rx_pdm2pcm_conf.rx_pdm2pcm_amplify_num = amp_num;
}
/**
* @brief Set I2S RX PDM high pass filter param0 (only for compatibility)
*
* @param hw Peripheral I2S hardware instance address.
* @param param no effect
*/
static inline void i2s_ll_rx_set_pdm_hp_filter_param0(i2s_dev_t *hw, uint32_t param)
{
// Can't configure HP filter param on this target
(void) hw;
(void) param;
}
/**
* @brief Set I2S RX PDM high pass filter param5 (only for compatibility)
*
* @param hw Peripheral I2S hardware instance address.
* @param param no effect
*/
static inline void i2s_ll_rx_set_pdm_hp_filter_param5(i2s_dev_t *hw, uint32_t param)
{
// Can't configure HP filter param on this target
(void) hw;
(void) param;
}
/**
* @brief Enable I2S RX PDM high pass filter
*
* @param hw Peripheral I2S hardware instance address.
* @param enable Set true to enable I2S RX PDM high pass filter, set false to bypass it
*/
static inline void i2s_ll_rx_enable_pdm_hp_filter(i2s_dev_t *hw, bool enable)
{
hw->rx_pdm2pcm_conf.rx_pdm_hp_bypass = !enable;
}
/**

8
components/soc/esp32c5/include/soc/Kconfig.soc_caps.in
View File

@@ -723,14 +723,6 @@ 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

2
components/soc/esp32c5/include/soc/soc_caps.h
View File

@@ -297,8 +297,6 @@
#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
#define SOC_I2S_SUPPORTS_PDM_RX_HP_FILTER (1)
#define SOC_I2S_SUPPORTS_TX_SYNC_CNT (1)
#define SOC_I2S_PDM_MAX_TX_LINES (2)
#define SOC_I2S_PDM_MAX_RX_LINES (1U)

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;

8
components/soc/esp32c61/include/soc/Kconfig.soc_caps.in
View File

@@ -599,14 +599,6 @@ 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

2
components/soc/esp32c61/include/soc/soc_caps.h
View File

@@ -250,8 +250,6 @@
#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
#define SOC_I2S_SUPPORTS_PDM_RX_HP_FILTER (1)
#define SOC_I2S_SUPPORTS_TX_SYNC_CNT (1)
#define SOC_I2S_PDM_MAX_TX_LINES (2)
#define SOC_I2S_PDM_MAX_RX_LINES (1U)

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;

49
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 I2S 0 none
ESP32-S3 I2S 0/1 I2S 0 I2S 0 I2S 0/1 I2S 0/1 none none
ESP32-H2 I2S 0 I2S 0 none I2S 0 I2S 0 none none
ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 I2S 0~2 none none
ESP32-C5 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 none none
ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 none none
ESP32-C5 I2S 0 I2S 0 none I2S 0 I2S 0 none none
ESP32-C61 I2S 0 I2S 0 none I2S 0 I2S 0 none none
========= ======== ============ ============ ========= ======== ======== ==========
.. note::
@@ -190,7 +180,6 @@ In standard mode, there are always two sound channels, i.e., the left and right
As for the slot configuration of raw PDM format, you can use the helper macros like :c:macro:`I2S_PDM_TX_SLOT_RAW_FMT_DEFAULT_CONFIG` or :c:macro:`I2S_PDM_TX_SLOT_RAW_FMT_DAC_DEFAULT_CONFIG`.
.. only:: SOC_I2S_SUPPORTS_PCM2PDM
PDM TX Mode in PCM Format (with PCM-to-PDM Converter)
@@ -905,7 +894,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.

49
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="标准"}
简介
----
@@ -18,7 +19,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**：位时钟线。用于数据线的位时钟。
@@ -57,10 +58,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::
@@ -78,27 +81,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 的需求，时钟配置将失败。
时钟术语
^^^^^^^^
@@ -131,8 +121,8 @@ ESP32-C6 I2S 0 I2S 0 无 I2S 0 I2S 0 无
ESP32-S3 I2S 0/1 I2S 0 I2S 0 I2S 0/1 I2S 0/1 无 无
ESP32-H2 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 I2S 0~2 无 无
ESP32-C5 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无 无
ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无 无
ESP32-C5 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
ESP32-C61 I2S 0 I2S 0 无 I2S 0 I2S 0 无 无
========= ======== ========== ========== =========== ========== ======== ===========
.. note::
@@ -157,7 +147,6 @@ ESP32-C61 I2S 0 I2S 0 I2S 0 I2S 0 I2S 0 无
.. wavedrom:: /../_static/diagrams/i2s/std_pcm.json
.. only:: SOC_I2S_SUPPORTS_PDM
PDM 模式
@@ -905,7 +894,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 通道逐个进行声道和时钟配置。