Merge branch 'bugfix/i2s_pdm_dac_wrong_clock_freq' into 'master'

i2s_pdm: fix tx frequency limitation

Closes IDFGH-9010

See merge request espressif/esp-idf!21764

components/driver/deprecated/dac_common_legacy.c

@@ -115,7 +115,7 @@ esp_err_t dac_cw_generator_config(dac_cw_config_t *cw)
 {
     ESP_RETURN_ON_FALSE(cw, ESP_ERR_INVALID_ARG, TAG, "invalid clock configuration");
     portENTER_CRITICAL(&rtc_spinlock);
-    /* Enable the rtc8m clock temporary to get the correct frequecy */
+    /* Enable the rtc8m clock temporary to get the correct frequency */
     periph_rtc_dig_clk8m_enable();
     uint32_t rtc_freq = periph_rtc_dig_clk8m_get_freq();
     periph_rtc_dig_clk8m_disable();

components/driver/deprecated/i2s_legacy.c

@@ -1201,6 +1201,7 @@ esp_err_t i2s_set_pdm_tx_up_sample(i2s_port_t i2s_num, const i2s_pdm_tx_upsample
     p_i2s[i2s_num]->clk_cfg.up_sample_fp = upsample_cfg->fp;
     p_i2s[i2s_num]->clk_cfg.up_sample_fs = upsample_cfg->fs;
     i2s_ll_tx_set_pdm_fpfs(p_i2s[i2s_num]->hal.dev, upsample_cfg->fp, upsample_cfg->fs);
+    i2s_ll_tx_set_pdm_over_sample_ratio(p_i2s[i2s_num]->hal.dev, upsample_cfg->fp / upsample_cfg->fs);
     i2s_start(i2s_num);
     xSemaphoreGive(p_i2s[i2s_num]->tx->mux);
     return i2s_set_clk(i2s_num, p_i2s[i2s_num]->clk_cfg.sample_rate_hz, p_i2s[i2s_num]->slot_cfg.data_bit_width, p_i2s[i2s_num]->slot_cfg.slot_mode);

components/driver/i2s/i2s_common.c

@@ -456,7 +456,7 @@ static uint32_t i2s_set_get_apll_freq(uint32_t mclk_freq_hz)
     mclk_div = mclk_div < 2 ? 2 : mclk_div;
     uint32_t expt_freq = mclk_freq_hz * mclk_div;
     if (expt_freq > SOC_APLL_MAX_HZ) {
-        ESP_LOGE(TAG, "The required APLL frequecy exceed its maximum value");
+        ESP_LOGE(TAG, "The required APLL frequency exceed its maximum value");
         return 0;
     }
     uint32_t real_freq = 0;

components/driver/i2s/i2s_pdm.c

@@ -35,7 +35,9 @@ static esp_err_t i2s_pdm_tx_calculate_clock(i2s_chan_handle_t handle, const i2s_
     uint32_t rate = clk_cfg->sample_rate_hz;
     i2s_pdm_tx_clk_config_t *pdm_tx_clk = (i2s_pdm_tx_clk_config_t *)clk_cfg;
 
-    clk_info->bclk = rate * I2S_LL_PDM_BCK_FACTOR * pdm_tx_clk->up_sample_fp / pdm_tx_clk->up_sample_fs;
+    // Over sampling ratio (integer, mostly should be 1 or 2)
+    uint32_t over_sample_ratio = pdm_tx_clk->up_sample_fp / pdm_tx_clk->up_sample_fs;
+    clk_info->bclk = rate * I2S_LL_PDM_BCK_FACTOR * over_sample_ratio;
     clk_info->bclk_div = 8;
     clk_info->mclk = clk_info->bclk * clk_info->bclk_div;
     clk_info->sclk = i2s_get_source_clk_freq(clk_cfg->clk_src, clk_info->mclk);
@@ -43,8 +45,9 @@ static esp_err_t i2s_pdm_tx_calculate_clock(i2s_chan_handle_t handle, const i2s_
 
     /* Check if the configuration is correct */
     ESP_RETURN_ON_FALSE(clk_info->mclk_div, ESP_ERR_INVALID_ARG, TAG, "sample rate is too large");
-    /* Set upsampling configuration */
+    /* Set up sampling configuration */
     i2s_ll_tx_set_pdm_fpfs(handle->controller->hal.dev, pdm_tx_clk->up_sample_fp, pdm_tx_clk->up_sample_fs);
+    i2s_ll_tx_set_pdm_over_sample_ratio(handle->controller->hal.dev, over_sample_ratio);
 
     return ESP_OK;
 }
@@ -53,6 +56,7 @@ static esp_err_t i2s_pdm_tx_set_clock(i2s_chan_handle_t handle, const i2s_pdm_tx
 {
     esp_err_t ret = ESP_OK;
     i2s_pdm_tx_config_t *pdm_tx_cfg = (i2s_pdm_tx_config_t *)(handle->mode_info);
+    ESP_RETURN_ON_FALSE(clk_cfg->up_sample_fs <= 480, ESP_ERR_INVALID_ARG, TAG, "up_sample_fs should be within 480");
 
     i2s_hal_clock_info_t clk_info;
     /* Calculate clock parameters */
@@ -64,7 +68,7 @@ static esp_err_t i2s_pdm_tx_set_clock(i2s_chan_handle_t handle, const i2s_pdm_tx
     /* Set clock configurations in HAL*/
     i2s_hal_set_tx_clock(&handle->controller->hal, &clk_info, clk_cfg->clk_src);
 #if SOC_I2S_HW_VERSION_2
-    /* Work aroud for PDM TX clock, overwrite the raw division directly to reduce the noise
+    /* Work around for PDM TX clock, overwrite the raw division directly to reduce the noise
      * This set of coefficients is a special division to reduce the background noise in PDM TX mode */
     i2s_ll_tx_set_raw_clk_div(handle->controller->hal.dev, 1, 1, 0, 0);
 #endif
@@ -213,7 +217,7 @@ esp_err_t i2s_channel_reconfig_pdm_tx_clock(i2s_chan_handle_t handle, const i2s_
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "invalid state, I2S should be disabled before reconfiguring the clock");
     i2s_pdm_tx_config_t *pdm_tx_cfg = (i2s_pdm_tx_config_t *)handle->mode_info;
     ESP_GOTO_ON_FALSE(pdm_tx_cfg, ESP_ERR_INVALID_STATE, err, TAG, "initialization not complete");
@@ -263,7 +267,7 @@ esp_err_t i2s_channel_reconfig_pdm_tx_slot(i2s_chan_handle_t handle, const i2s_p
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "invalid state, I2S should be disabled before reconfiguring the slot");
 
     i2s_pdm_tx_config_t *pdm_tx_cfg = (i2s_pdm_tx_config_t *)handle->mode_info;
@@ -294,7 +298,7 @@ esp_err_t i2s_channel_reconfig_pdm_tx_gpio(i2s_chan_handle_t handle, const i2s_p
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "This handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "This handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "Invalid state, I2S should be disabled before reconfiguring the gpio");
 
     ESP_GOTO_ON_ERROR(i2s_pdm_tx_set_gpio(handle, gpio_cfg), err, TAG, "set i2s standard slot failed");
@@ -489,7 +493,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_clock(i2s_chan_handle_t handle, const i2s_
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "invalid state, I2S should be disabled before reconfiguring the clock");
     i2s_pdm_rx_config_t *pdm_rx_cfg = (i2s_pdm_rx_config_t *)handle->mode_info;
     ESP_GOTO_ON_FALSE(pdm_rx_cfg, ESP_ERR_INVALID_STATE, err, TAG, "initialization not complete");
@@ -539,7 +543,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_slot(i2s_chan_handle_t handle, const i2s_p
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "invalid state, I2S should be disabled before reconfiguring the slot");
 
     i2s_pdm_rx_config_t *pdm_rx_cfg = (i2s_pdm_rx_config_t *)handle->mode_info;
@@ -569,7 +573,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_p
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "This handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_PDM, ESP_ERR_INVALID_ARG, err, TAG, "This handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "Invalid state, I2S should be disabled before reconfiguring the gpio");
 
     ESP_GOTO_ON_ERROR(i2s_pdm_rx_set_gpio(handle, gpio_cfg), err, TAG, "set i2s standard slot failed");

components/driver/i2s/i2s_private.h

@@ -145,7 +145,7 @@ esp_err_t i2s_free_dma_desc(i2s_chan_handle_t handle);
  * @return
  *      - ESP_OK                Allocate memory success
  *      - ESP_ERR_INVALID_ARG   NULL pointer or bufsize is too big
- *      - ESP_ERR_NO_MEM        No memmory for DMA descriptor and DMA buffer
+ *      - ESP_ERR_NO_MEM        No memory for DMA descriptor and DMA buffer
  */
 esp_err_t i2s_alloc_dma_desc(i2s_chan_handle_t handle, uint32_t num, uint32_t bufsize);
 
@@ -165,7 +165,7 @@ uint32_t i2s_get_buf_size(i2s_chan_handle_t handle, uint32_t data_bit_width, uin
  * @brief Get the frequency of the source clock
  *
  * @param clk_src       clock source
- * @param mclk_freq_hz  Expected mclk frequenct in Hz
+ * @param mclk_freq_hz  Expected mclk frequency in Hz
  * @return
  *      - Actual source clock frequency
  */

components/driver/i2s/i2s_std.c

@@ -259,7 +259,7 @@ esp_err_t i2s_channel_reconfig_std_clock(i2s_chan_handle_t handle, const i2s_std
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_STD, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_STD, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "invalid state, I2S should be disabled before reconfiguring the clock");
 
     i2s_std_config_t *std_cfg = (i2s_std_config_t *)handle->mode_info;
@@ -309,7 +309,7 @@ esp_err_t i2s_channel_reconfig_std_slot(i2s_chan_handle_t handle, const i2s_std_
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_STD, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_STD, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "invalid state, I2S should be disabled before reconfiguring the slot");
 
     i2s_std_config_t *std_cfg = (i2s_std_config_t *)handle->mode_info;
@@ -339,7 +339,7 @@ esp_err_t i2s_channel_reconfig_std_gpio(i2s_chan_handle_t handle, const i2s_std_
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_STD, ESP_ERR_INVALID_ARG, err, TAG, "This handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_STD, ESP_ERR_INVALID_ARG, err, TAG, "This handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "Invalid state, I2S should be disabled before reconfiguring the gpio");
 
     ESP_GOTO_ON_ERROR(i2s_std_set_gpio(handle, gpio_cfg), err, TAG, "set i2s standard slot failed");

components/driver/i2s/i2s_tdm.c

@@ -264,7 +264,7 @@ esp_err_t i2s_channel_reconfig_tdm_clock(i2s_chan_handle_t handle, const i2s_tdm
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_TDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_TDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "invalid state, I2S should be disabled before reconfiguring the clock");
     i2s_tdm_config_t *tdm_cfg = (i2s_tdm_config_t *)handle->mode_info;
     ESP_GOTO_ON_FALSE(tdm_cfg, ESP_ERR_INVALID_STATE, err, TAG, "initialization not complete");
@@ -314,7 +314,7 @@ esp_err_t i2s_channel_reconfig_tdm_slot(i2s_chan_handle_t handle, const i2s_tdm_
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_TDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_TDM, ESP_ERR_INVALID_ARG, err, TAG, "this handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "invalid state, I2S should be disabled before reconfiguring the slot");
 
     i2s_tdm_config_t *tdm_cfg = (i2s_tdm_config_t *)handle->mode_info;
@@ -347,7 +347,7 @@ esp_err_t i2s_channel_reconfig_tdm_gpio(i2s_chan_handle_t handle, const i2s_tdm_
     esp_err_t ret = ESP_OK;
 
     xSemaphoreTake(handle->mutex, portMAX_DELAY);
-    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_TDM, ESP_ERR_INVALID_ARG, err, TAG, "This handle is not working in standard moded");
+    ESP_GOTO_ON_FALSE(handle->mode == I2S_COMM_MODE_TDM, ESP_ERR_INVALID_ARG, err, TAG, "This handle is not working in standard mode");
     ESP_GOTO_ON_FALSE(handle->state == I2S_CHAN_STATE_READY, ESP_ERR_INVALID_STATE, err, TAG, "Invalid state, I2S should be disabled before reconfiguring the gpio");
 
     ESP_GOTO_ON_ERROR(i2s_tdm_set_gpio(handle, gpio_cfg), err, TAG, "set i2s standard slot failed");

components/driver/include/driver/i2s_common.h

@@ -45,7 +45,7 @@ typedef struct {
     i2s_isr_callback_t on_sent;             /**< Callback of data sent event, only for tx channel
                                              *   The event data includes DMA buffer address and size that just finished sending data
                                              */
-    i2s_isr_callback_t on_send_q_ovf;       /**< Callback of sending queue overflowed evnet, only for tx channel
+    i2s_isr_callback_t on_send_q_ovf;       /**< Callback of sending queue overflowed event, only for tx channel
                                              *   The event data includes buffer size that has been overwritten
                                              */
 } i2s_event_callbacks_t;
@@ -130,7 +130,7 @@ esp_err_t i2s_channel_get_info(i2s_chan_handle_t handle, i2s_chan_info_t *chan_i
  * @brief Enable the i2s channel
  * @note  Only allowed to be called when the channel state is READY, (i.e., channel has been initialized, but not started)
  *        the channel will enter RUNNING state once it is enabled successfully.
- * @note  Enbale the channel can start the I2S communication on hardware. It will start outputting bclk and ws signal.
+ * @note  Enable the channel can start the I2S communication on hardware. It will start outputting bclk and ws signal.
  *        For mclk signal, it will start to output when initialization is finished
  *
  * @param[in]   handle      I2S channel handler

components/driver/include/driver/i2s_pdm.h

@@ -89,8 +89,8 @@ typedef struct {
  * @brief I2S PDM RX mode major configuration that including clock/slot/gpio configuration
  */
 typedef struct {
-    i2s_pdm_rx_clk_config_t    clk_cfg;         /*!< PDM RX clock configurations, can be genertated by macro I2S_PDM_RX_CLK_DEFAULT_CONFIG */
-    i2s_pdm_rx_slot_config_t   slot_cfg;        /*!< PDM RX slot configurations, can be genertated by macro I2S_PDM_RX_SLOT_DEFAULT_CONFIG */
+    i2s_pdm_rx_clk_config_t    clk_cfg;         /*!< PDM RX clock configurations, can be generated by macro I2S_PDM_RX_CLK_DEFAULT_CONFIG */
+    i2s_pdm_rx_slot_config_t   slot_cfg;        /*!< PDM RX slot configurations, can be generated by macro I2S_PDM_RX_SLOT_DEFAULT_CONFIG */
     i2s_pdm_rx_gpio_config_t   gpio_cfg;        /*!< PDM RX slot configurations, specified by user */
 } i2s_pdm_rx_config_t;
 
@@ -116,7 +116,7 @@ esp_err_t i2s_channel_init_pdm_rx_mode(i2s_chan_handle_t handle, const i2s_pdm_r
  * @brief Reconfigure the I2S clock for PDM RX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S rx channel handler
  * @param[in]   clk_cfg     PDM RX mode clock configuration, can be generated by `I2S_PDM_RX_CLK_DEFAULT_CONFIG`
@@ -131,7 +131,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_clock(i2s_chan_handle_t handle, const i2s_
  * @brief Reconfigure the I2S slot for PDM RX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S rx channel handler
  * @param[in]   slot_cfg    PDM RX mode slot configuration, can be generated by `I2S_PDM_RX_SLOT_DEFAULT_CONFIG`
@@ -147,7 +147,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_slot(i2s_chan_handle_t handle, const i2s_p
  * @brief Reconfigure the I2S gpio for PDM RX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S rx channel handler
  * @param[in]   gpio_cfg    PDM RX mode gpio configuration, specified by user
@@ -210,7 +210,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_p
  *       2: fp = 960, fs = 480, in this case, Fpdm = 128*Fpcm = 128*sample_rate_hz
  *       If the pdm receiver do not care the pdm serial clock, it's recommended set Fpdm = 128*48000.
  *       Otherwise, the second configuration should be adopted.
- * @param rate sample rate
+ * @param rate sample rate (not suggest to exceed 48000 Hz, otherwise more glitches and noise may appear)
  */
 #define I2S_PDM_TX_CLK_DEFAULT_CONFIG(rate) { \
     .sample_rate_hz = rate, \
@@ -256,7 +256,7 @@ typedef struct {
     i2s_pdm_sig_scale_t     lp_scale;           /*!< Low pass filter scaling value */
     i2s_pdm_sig_scale_t     sinc_scale;         /*!< Sinc filter scaling value */
 #if SOC_I2S_HW_VERSION_2
-    i2s_pdm_tx_line_mode_t  line_mode;          /*!< PDM TX line mode, on-line codec, one-line dac, two-line dac mode can be selected */
+    i2s_pdm_tx_line_mode_t  line_mode;          /*!< PDM TX line mode, one-line codec, one-line dac, two-line dac mode can be selected */
     bool                    hp_en;              /*!< High pass filter enable */
     float                   hp_cut_off_freq_hz; /*!< High pass filter cut-off frequency, range 23.3Hz ~ 185Hz, see cut-off frequency sheet above */
     uint32_t                sd_dither;          /*!< Sigma-delta filter dither */
@@ -269,12 +269,12 @@ typedef struct {
  */
 typedef struct {
     /* General fields */
-    uint32_t                sample_rate_hz;     /*!< I2S sample rate */
+    uint32_t                sample_rate_hz;     /*!< I2S sample rate, not suggest to exceed 48000 Hz, otherwise more glitches and noise may appear */
     i2s_clock_src_t         clk_src;            /*!< Choose clock source */
     i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of mclk to the sample rate */
     /* Particular fields */
     uint32_t                up_sample_fp;       /*!< Up-sampling param fp */
-    uint32_t                up_sample_fs;       /*!< Up-sampling param fs */
+    uint32_t                up_sample_fs;       /*!< Up-sampling param fs, not allowed to be greater than 480 */
 } i2s_pdm_tx_clk_config_t;
 
 /**
@@ -297,8 +297,8 @@ typedef struct {
  * @brief I2S PDM TX mode major configuration that including clock/slot/gpio configuration
  */
 typedef struct {
-    i2s_pdm_tx_clk_config_t    clk_cfg;         /*!< PDM TX clock configurations, can be genertated by macro I2S_PDM_TX_CLK_DEFAULT_CONFIG */
-    i2s_pdm_tx_slot_config_t   slot_cfg;        /*!< PDM TX slot configurations, can be genertated by macro I2S_PDM_TX_SLOT_DEFAULT_CONFIG */
+    i2s_pdm_tx_clk_config_t    clk_cfg;         /*!< PDM TX clock configurations, can be generated by macro I2S_PDM_TX_CLK_DEFAULT_CONFIG */
+    i2s_pdm_tx_slot_config_t   slot_cfg;        /*!< PDM TX slot configurations, can be generated by macro I2S_PDM_TX_SLOT_DEFAULT_CONFIG */
     i2s_pdm_tx_gpio_config_t   gpio_cfg;        /*!< PDM TX gpio configurations, specified by user */
 } i2s_pdm_tx_config_t;
 
@@ -324,7 +324,7 @@ esp_err_t i2s_channel_init_pdm_tx_mode(i2s_chan_handle_t handle, const i2s_pdm_t
  * @brief Reconfigure the I2S clock for PDM TX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S tx channel handler
  * @param[in]   clk_cfg     PDM TX mode clock configuration, can be generated by `I2S_PDM_TX_CLK_DEFAULT_CONFIG`
@@ -339,7 +339,7 @@ esp_err_t i2s_channel_reconfig_pdm_tx_clock(i2s_chan_handle_t handle, const i2s_
  * @brief Reconfigure the I2S slot for PDM TX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S tx channel handler
  * @param[in]   slot_cfg    PDM TX mode slot configuration, can be generated by `I2S_PDM_TX_SLOT_DEFAULT_CONFIG`
@@ -355,7 +355,7 @@ esp_err_t i2s_channel_reconfig_pdm_tx_slot(i2s_chan_handle_t handle, const i2s_p
  * @brief Reconfigure the I2S gpio for PDM TX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S tx channel handler
  * @param[in]   gpio_cfg    PDM TX mode gpio configuration, specified by user

components/driver/include/driver/i2s_std.h

@@ -293,7 +293,7 @@ esp_err_t i2s_channel_init_std_mode(i2s_chan_handle_t handle, const i2s_std_conf
  * @brief Reconfigure the I2S clock for standard mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   clk_cfg     Standard mode clock configuration, can be generated by `I2S_STD_CLK_DEFAULT_CONFIG`
@@ -308,7 +308,7 @@ esp_err_t i2s_channel_reconfig_std_clock(i2s_chan_handle_t handle, const i2s_std
  * @brief Reconfigure the I2S slot for standard mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   slot_cfg    Standard mode slot configuration, can be generated by `I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG`,
@@ -325,7 +325,7 @@ esp_err_t i2s_channel_reconfig_std_slot(i2s_chan_handle_t handle, const i2s_std_
  * @brief Reconfigure the I2S gpio for standard mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   gpio_cfg    Standard mode gpio configuration, specified by user

components/driver/include/driver/i2s_tdm.h

@@ -137,7 +137,7 @@ typedef struct {
     i2s_slot_mode_t         slot_mode;          /*!< Set mono or stereo mode with I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO */
 
     /* Particular fields */
-    i2s_tdm_slot_mask_t     slot_mask;          /*!< Slot mask. Activating slots by setting 1 to corresponding bits. When the activated slots is not consecutive, those data in unactivated slots will be ignored */
+    i2s_tdm_slot_mask_t     slot_mask;          /*!< Slot mask. Activating slots by setting 1 to corresponding bits. When the activated slots is not consecutive, those data in inactivated slots will be ignored */
     uint32_t                ws_width;           /*!< WS signal width (i.e. the number of bclk ticks that ws signal is high) */
     bool                    ws_pol;             /*!< WS signal polarity, set true to enable high lever first */
     bool                    bit_shift;          /*!< Set true to enable bit shift in Philips mode */
@@ -209,7 +209,7 @@ esp_err_t i2s_channel_init_tdm_mode(i2s_chan_handle_t handle, const i2s_tdm_conf
  * @brief Reconfigure the I2S clock for TDM mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   clk_cfg     Standard mode clock configuration, can be generated by `I2S_TDM_CLK_DEFAULT_CONFIG`
@@ -224,7 +224,7 @@ esp_err_t i2s_channel_reconfig_tdm_clock(i2s_chan_handle_t handle, const i2s_tdm
  * @brief Reconfigure the I2S slot for TDM mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   slot_cfg    Standard mode slot configuration, can be generated by `I2S_TDM_PHILIPS_SLOT_DEFAULT_CONFIG`,
@@ -241,7 +241,7 @@ esp_err_t i2s_channel_reconfig_tdm_slot(i2s_chan_handle_t handle, const i2s_tdm_
  * @brief Reconfigure the I2S gpio for TDM mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
  *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfigring
+ * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   gpio_cfg    Standard mode gpio configuration, specified by user

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

@@ -1044,6 +1044,17 @@ static inline void i2s_ll_tx_set_pdm_sd_scale(i2s_dev_t *hw, i2s_pdm_sig_scale_t
     hw->pdm_conf.tx_sigmadelta_in_shift = sig_scale;
 }
 
+/**
+ * @brief Set the PDM TX over sampling ratio
+ *
+ * @param hw  Peripheral I2S hardware instance address.
+ * @param ovr Over sampling ratio
+ */
+static inline void i2s_ll_tx_set_pdm_over_sample_ratio(i2s_dev_t *hw, uint32_t ovr)
+{
+    hw->pdm_conf.tx_sinc_osr2 = ovr;
+}
+
 /**
  * @brief Configure I2S TX PDM sample rate
  *        Fpdm = 64*Fpcm*fp/fs
@@ -1056,7 +1067,6 @@ static inline void i2s_ll_tx_set_pdm_fpfs(i2s_dev_t *hw, uint32_t fp, uint32_t f
 {
     hw->pdm_freq_conf.tx_pdm_fp = fp;
     hw->pdm_freq_conf.tx_pdm_fs = fs;
-    hw->pdm_conf.tx_sinc_osr2 = fp / fs;
 }
 
 /**

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

@@ -877,6 +877,17 @@ static inline void i2s_ll_tx_set_pdm_sd_dither2(i2s_dev_t *hw, uint32_t dither2)
     hw->tx_pcm2pdm_conf.tx_pdm_sigmadelta_dither2 = dither2;
 }
 
+/**
+ * @brief Set the PDM TX over sampling ratio
+ *
+ * @param hw  Peripheral I2S hardware instance address.
+ * @param ovr Over sampling ratio
+ */
+static inline void i2s_ll_tx_set_pdm_over_sample_ratio(i2s_dev_t *hw, uint32_t ovr)
+{
+    hw->tx_pcm2pdm_conf.tx_pdm_sinc_osr2 = ovr;
+}
+
 /**
  * @brief Configure I2S TX PDM sample rate
  *        Fpdm = 64*Fpcm*fp/fs
@@ -889,7 +900,6 @@ static inline void i2s_ll_tx_set_pdm_fpfs(i2s_dev_t *hw, uint32_t fp, uint32_t f
 {
     hw->tx_pcm2pdm_conf1.tx_pdm_fp = fp;
     hw->tx_pcm2pdm_conf1.tx_pdm_fs = fs;
-    hw->tx_pcm2pdm_conf.tx_pdm_sinc_osr2 = fp / fs;
 }
 
 /**

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

@@ -892,6 +892,17 @@ static inline void i2s_ll_tx_set_pdm_sd_dither2(i2s_dev_t *hw, uint32_t dither2)
     hw->tx_pcm2pdm_conf.tx_pdm_sigmadelta_dither2 = dither2;
 }
 
+/**
+ * @brief Set the PDM TX over sampling ratio
+ *
+ * @param hw  Peripheral I2S hardware instance address.
+ * @param ovr Over sampling ratio
+ */
+static inline void i2s_ll_tx_set_pdm_over_sample_ratio(i2s_dev_t *hw, uint32_t ovr)
+{
+    hw->tx_pcm2pdm_conf.tx_pdm_sinc_osr2 = ovr;
+}
+
 /**
  * @brief Configure I2S TX PDM sample rate
  *        Fpdm = 64*Fpcm*fp/fs
@@ -904,7 +915,6 @@ static inline void i2s_ll_tx_set_pdm_fpfs(i2s_dev_t *hw, uint32_t fp, uint32_t f
 {
     hw->tx_pcm2pdm_conf1.tx_pdm_fp = fp;
     hw->tx_pcm2pdm_conf1.tx_pdm_fs = fs;
-    hw->tx_pcm2pdm_conf.tx_pdm_sinc_osr2 = fp / fs;
 }
 
 /**

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

@@ -878,6 +878,17 @@ static inline void i2s_ll_tx_set_pdm_sd_dither2(i2s_dev_t *hw, uint32_t dither2)
     hw->tx_pcm2pdm_conf.tx_pdm_sigmadelta_dither2 = dither2;
 }
 
+/**
+ * @brief Set the PDM TX over sampling ratio
+ *
+ * @param hw  Peripheral I2S hardware instance address.
+ * @param ovr Over sampling ratio
+ */
+static inline void i2s_ll_tx_set_pdm_over_sample_ratio(i2s_dev_t *hw, uint32_t ovr)
+{
+    hw->tx_pcm2pdm_conf.tx_pdm_sinc_osr2 = ovr;
+}
+
 /**
  * @brief Configure I2S TX PDM sample rate
  *        Fpdm = 64*Fpcm*fp/fs
@@ -890,7 +901,6 @@ static inline void i2s_ll_tx_set_pdm_fpfs(i2s_dev_t *hw, uint32_t fp, uint32_t f
 {
     hw->tx_pcm2pdm_conf1.tx_pdm_fp = fp;
     hw->tx_pcm2pdm_conf1.tx_pdm_fs = fs;
-    hw->tx_pcm2pdm_conf.tx_pdm_sinc_osr2 = fp / fs;
 }
 
 /**

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

@@ -780,6 +780,17 @@ static inline void i2s_ll_rx_enable_pdm(i2s_dev_t *hw)
     hw->rx_conf.rx_pdm2pcm_en = true;
 }
 
+/**
+ * @brief Set the PDM TX over sampling ratio
+ *
+ * @param hw  Peripheral I2S hardware instance address.
+ * @param ovr Over sampling ratio
+ */
+static inline void i2s_ll_tx_set_pdm_over_sample_ratio(i2s_dev_t *hw, uint32_t ovr)
+{
+    hw->tx_pcm2pdm_conf.tx_sinc_osr2 = ovr;
+}
+
 /**
  * @brief Configure I2S TX PDM sample rate
  *        Fpdm = 64*Fpcm*fp/fs
@@ -792,7 +803,6 @@ static inline void i2s_ll_tx_set_pdm_fpfs(i2s_dev_t *hw, uint32_t fp, uint32_t f
 {
     hw->tx_pcm2pdm_conf1.tx_pdm_fp = fp;
     hw->tx_pcm2pdm_conf1.tx_pdm_fs = fs;
-    hw->tx_pcm2pdm_conf.tx_sinc_osr2 = fp / fs;
 }
 
 /**

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

@@ -36,7 +36,7 @@ Each I2S controller has the following features that can be configured by the I2S
 
 .. only:: SOC_I2S_HW_VERSION_2
 
-    Each controller has separate rx and tx channel. That means they are able to work under different clock and slot configurations with separate GPIO pins. Note that although the internal MCLK of tx channel and rx channel are separate on a controller, the output MCLK signal can only be attached to one channel. If two different MCLK ouput is required, they must be allocated on different I2S controller.
+    Each controller has separate rx and tx channel. That means they are able to work under different clock and slot configurations with separate GPIO pins. Note that although the internal MCLK of tx channel and rx channel are separate on a controller, the output MCLK signal can only be attached to one channel. If two different MCLK output is required, they must be allocated on different I2S controller.
 
 I2S File Structure
 ------------------
@@ -229,7 +229,7 @@ The ``<mode>`` in the diagram can be replaced by corresponding I2S communication
 Data Transport
 ^^^^^^^^^^^^^^
 
-The data transport of I2S peripheral, including sending and receiving, is realized by DMA. Before transporting data, please call :cpp:func:`i2s_channel_enable` to enable the specific channel. When the sent or received data reach the size of one DMA buffer, ``I2S_OUT_EOF`` or ``I2S_IN_SUC_EOF`` interrupt will be triggered. Note that the DMA buffer size is not equal to :cpp:member:`i2s_chan_config_t::dma_frame_num`, one frame here means all the sampled data in one WS circle. Therefore, ``dma_buffer_size = dma_frame_num * slot_num * slot_bit_width / 8``. For the transmit case, users can input the data by calling :cpp:func:`i2s_channel_write`. This function will help users to copy the data from the source buffer to the DMA tx buffer and wait for the transmition finished. Then it'll repeat until the sent bytes reach the given size. For the receive case, the function :cpp:func:`i2s_channel_read` will wait for receiving the message queue which contains the DMA buffer address, it will help users to copy the data from DMA rx buffer to the destination buffer.
+The data transport of I2S peripheral, including sending and receiving, is realized by DMA. Before transporting data, please call :cpp:func:`i2s_channel_enable` to enable the specific channel. When the sent or received data reach the size of one DMA buffer, ``I2S_OUT_EOF`` or ``I2S_IN_SUC_EOF`` interrupt will be triggered. Note that the DMA buffer size is not equal to :cpp:member:`i2s_chan_config_t::dma_frame_num`, one frame here means all the sampled data in one WS circle. Therefore, ``dma_buffer_size = dma_frame_num * slot_num * slot_bit_width / 8``. For the transmit case, users can input the data by calling :cpp:func:`i2s_channel_write`. This function will help users to copy the data from the source buffer to the DMA tx buffer and wait for the transmission finished. Then it'll repeat until the sent bytes reach the given size. For the receive case, the function :cpp:func:`i2s_channel_read` will wait for receiving the message queue which contains the DMA buffer address, it will help users to copy the data from DMA rx buffer to the destination buffer.
 
 Both :cpp:func:`i2s_channel_write` and :cpp:func:`i2s_channel_read` are blocking functions, they will keep waiting until the whole source buffer are sent or the whole destination buffer loaded, unless they exceed the max blocking time, then the error code `ESP_ERR_TIMEOUT` will return in this case. To send or receive data asynchronously, callbacks can be registered by  :cpp:func:`i2s_channel_register_event_callback`, users are able to access the DMA buffer directly in the callback function instead of transmitting or receiving by the two blocking functions. However, please be aware that it is an interrupt callback, don't do complex logic, floating operation or call non-reentrant functions in the callback.
 
@@ -320,7 +320,7 @@ Here is the table of the real data on the line with different :cpp:member:`i2s_s
 
         It's similar when the data is 32-bit width, but take care when using 8-bit and 24-bit data width. For 8-bit width, the written buffer should still using ``uint16_t`` (i.e. align with 2 bytes), and only the high 8 bits will be valid, the low 8 bits are dropped, and for 24-bit width, the buffer is supposed to use ``uint32_t`` (i.e. align with 4 bytes), and only the high 24 bits valid, the low 8 bits are dropped.
 
-        Another point is that, for the ``8-bit`` and ``16-bit`` mono mode, the real data on the line are swapped. To get the correct sequence, the writting buffer need to swap the data every two bytes.
+        Another point is that, for the ``8-bit`` and ``16-bit`` mono mode, the real data on the line are swapped. To get the correct sequence, the writing buffer need to swap the data every two bytes.
 
 .. only:: esp32s2
 
@@ -342,7 +342,7 @@ Here is the table of the real data on the line with different :cpp:member:`i2s_s
 
     .. note::
 
-        Similar for 8-bit and 32-bit data width, the type of the buffer is better to be ``uint8_t`` and ``uint32_t`` type. But specially, when the data width is 24-bit, the data buffer should aligned with 3-byte(i.e. every 3 bytes stands for a 24-bit data in one slot), additionally, :cpp:member:`i2s_chan_config_t::dma_frame_num`, :cpp:member:`i2s_std_clk_config_t::mclk_multiple` and the writting buffer size should be the multiple of ``3``, otherwise the data on the line or the sample rate will be incorrect.
+        Similar for 8-bit and 32-bit data width, the type of the buffer is better to be ``uint8_t`` and ``uint32_t`` type. But specially, when the data width is 24-bit, the data buffer should aligned with 3-byte(i.e. every 3 bytes stands for a 24-bit data in one slot), additionally, :cpp:member:`i2s_chan_config_t::dma_frame_num`, :cpp:member:`i2s_std_clk_config_t::mclk_multiple` and the writing buffer size should be the multiple of ``3``, otherwise the data on the line or the sample rate will be incorrect.
 
 .. only:: not (esp32 or esp32s2)
 
@@ -364,7 +364,7 @@ Here is the table of the real data on the line with different :cpp:member:`i2s_s
 
     .. note::
 
-        Similar for 8-bit and 32-bit data width, the type of the buffer is better to be ``uint8_t`` and ``uint32_t`` type. But specially, when the data width is 24-bit, the data buffer should aligned with 3-byte(i.e. every 3 bytes stands for a 24-bit data in one slot), additionally, :cpp:member:`i2s_chan_config_t::dma_frame_num`, :cpp:member:`i2s_std_clk_config_t::mclk_multiple` and the writting buffer size should be the multiple of ``3``, otherwise the data on the line or the sample rate will be incorrect.
+        Similar for 8-bit and 32-bit data width, the type of the buffer is better to be ``uint8_t`` and ``uint32_t`` type. But specially, when the data width is 24-bit, the data buffer should aligned with 3-byte(i.e. every 3 bytes stands for a 24-bit data in one slot), additionally, :cpp:member:`i2s_chan_config_t::dma_frame_num`, :cpp:member:`i2s_std_clk_config_t::mclk_multiple` and the writing buffer size should be the multiple of ``3``, otherwise the data on the line or the sample rate will be incorrect.
 
 .. code-block:: c
 
@@ -542,7 +542,7 @@ Here is the table of the data that received in the buffer with different :cpp:me
     Please refer to :ref:`i2s-api-reference-i2s_pdm` for PDM TX API information.
     And for more details, please refer to :component_file:`driver/include/driver/i2s_pdm.h`.
 
-    The PDM data width is fixed to 16-bit, when the data in a ``int16_t`` writting buffer are:
+    The PDM data width is fixed to 16-bit, when the data in a ``int16_t`` writing buffer are:
 
     +--------+--------+--------+--------+--------+--------+--------+--------+--------+
     | data 0 | data 1 | data 2 | data 3 | data 4 | data 5 | data 6 | data 7 |  ...   |
@@ -838,8 +838,8 @@ Here is an example of how to allocate a pair of full-duplex channels:
             },
         },
     };
-    i2s_init_channle(tx_handle, &std_cfg);
-    i2s_init_channle(rx_handle, &std_cfg);
+    i2s_channel_init_std_mode(tx_handle, &std_cfg);
+    i2s_channel_init_std_mode(rx_handle, &std_cfg);
 
     i2s_channel_enable(tx_handle);
     i2s_channel_enable(rx_handle);

examples/peripherals/i2s/common/format_wav.h

@@ -16,7 +16,7 @@ extern "C" {
  *
  * @note See this for reference: http://soundfile.sapp.org/doc/WaveFormat/
  *
- * @note Assignment to variables in this struct directely is only possible for little endian architectures
+ * @note Assignment to variables in this struct directly is only possible for little endian architectures
  *       (including Xtensa & RISC-V)
  */
 typedef struct {

examples/peripherals/i2s/i2s_basic/i2s_pdm/main/i2s_pdm_tx.c

@@ -18,7 +18,7 @@
 #define EXAMPLE_PDM_TX_DOUT_IO          GPIO_NUM_5      // I2S PDM TX data out io number
 
 #define EXAMPLE_PDM_TX_FREQ_HZ          44100           // I2S PDM TX frequency
-#define EXAMPLE_WAVE_AMPTITUDE          (1000.0)        // 1~32767
+#define EXAMPLE_WAVE_AMPLITUDE          (1000.0)        // 1~32767
 #define CONST_PI                        (3.1416f)
 #define EXAMPLE_SINE_WAVE_LEN(tone)     (uint32_t)((EXAMPLE_PDM_TX_FREQ_HZ / (float)tone) + 0.5) // The sample point number per sine wave to generate the tone
 #define EXAMPLE_TONE_LAST_TIME_MS       500
@@ -89,7 +89,7 @@ void i2s_example_pdm_tx_task(void *args)
         int tone_point = EXAMPLE_SINE_WAVE_LEN(tone[tone_select][song[cnt]-1]);
         /* Generate the tone buffer */
         for (int i = 0; i < tone_point; i++) {
-            w_buf[i] =  (int16_t)((sin(2 * (float)i * CONST_PI / tone_point)) * EXAMPLE_WAVE_AMPTITUDE);
+            w_buf[i] =  (int16_t)((sin(2 * (float)i * CONST_PI / tone_point)) * EXAMPLE_WAVE_AMPLITUDE);
         }
         for (int tot_bytes = 0; tot_bytes < EXAMPLE_BYTE_NUM_EVERY_TONE * rhythm[cnt % 7]; tot_bytes += w_bytes) {
             /* Play the tone */

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

@@ -38,7 +38,7 @@ The component can be installed by esp component manager. Since this example alre
 idf.py add-dependency espressif/es7210^1.0.0
 ```
 
-If the dependency is added, you can check `idf_component.yml` for more detail. When building this example or other projects with managed components, the component manager will search for the required components online and download them into the `managed_componets` folder.
+If the dependency is added, you can check `idf_component.yml` for more detail. When building this example or other projects with managed components, the component manager will search for the required components online and download them into the `managed_components` folder.
 
 ### Configure the project
 
@@ -47,7 +47,7 @@ If the dependency is added, you can check `idf_component.yml` for more detail. W
 idf.py set-target TARGET
 ```
 * Change value of `EXAMPLE_I2S_FORMAT` to check I2S driver's functionality on different I2S formats.
-* Change `EXAMPLE_ES7210_MIC_GAIN` and `EXAMPLE_ES7210_MIC_BIAS` accoirding your MIC's specs if needed.
+* Change `EXAMPLE_ES7210_MIC_GAIN` and `EXAMPLE_ES7210_MIC_BIAS` according your MIC's specs if needed.
 * Change `EXAMPLE_ES7210_ADC_VOLUME` if recorded voice is too loud or too quite.
 
 Note: it's better to adjust `EXAMPLE_ES7210_MIC_GAIN` first. If adjusting MIC gain doesn't meet your demand, you can then adjust `EXAMPLE_ES7210_ADC_VOLUME`. That is to say, it's better to adjust analog gain than digital gain.

examples/peripherals/i2s/i2s_codec/i2s_es7210_tdm/main/i2s_es7210_record_example.c

@@ -12,7 +12,7 @@
 #include "es7210.h"
 #include "format_wav.h"
 
-#if CONFIG_IDF_TARGET_ESP32S3 // ESP32-S3-Korvo-1 pinout
+#if CONFIG_IDF_TARGET_ESP32S3 // ESP32-S3-Korvo-1 pin out
 /* I2C port and GPIOs */
 #define EXAMPLE_I2C_NUM            (0)
 #define EXAMPLE_I2C_SDA_IO         (1)
@@ -210,7 +210,7 @@ static esp_err_t record_wav(i2s_chan_handle_t i2s_rx_chan)
 
     /* Write wav header */
     ESP_GOTO_ON_FALSE(fwrite(&wav_header, sizeof(wav_header_t), 1, f), ESP_FAIL, err,
-                      TAG, "error while writting wav header");
+                      TAG, "error while writing wav header");
 
     /* Start recording */
     size_t wav_written = 0;

examples/peripherals/i2s/i2s_codec/i2s_es8311/main/i2s_es8311_example.c

@@ -63,7 +63,7 @@ static esp_err_t es8311_codec_init(void)
     ESP_RETURN_ON_ERROR(es8311_voice_volume_set(es_handle, EXAMPLE_VOICE_VOLUME, NULL), TAG, "set es8311 volume failed");
     ESP_RETURN_ON_ERROR(es8311_microphone_config(es_handle, false), TAG, "set es8311 microphone failed");
 #if CONFIG_EXAMPLE_MODE_ECHO
-    ESP_RETURN_ON_ERROR(es8311_microphone_gain_set(es_handle, EXAMPLE_MIC_GAIN), TAG, "set es8311 microphone gain faield");
+    ESP_RETURN_ON_ERROR(es8311_microphone_gain_set(es_handle, EXAMPLE_MIC_GAIN), TAG, "set es8311 microphone gain failed");
 #endif
     return ESP_OK;
 }
@@ -128,7 +128,7 @@ static void i2s_music(void *args)
         if (bytes_write > 0) {
             ESP_LOGI(TAG, "[music] i2s music played, %d bytes are written.", bytes_write);
         } else {
-            ESP_LOGE(TAG, "[music] i2s music play falied.");
+            ESP_LOGE(TAG, "[music] i2s music play failed.");
             abort();
         }
         vTaskDelay(1000 / portTICK_PERIOD_MS);

examples/peripherals/i2s/i2s_recorder/pytest_i2s_record.py

@@ -7,7 +7,7 @@ from pytest_embedded import Dut
 @pytest.mark.esp32
 @pytest.mark.esp32s3
 @pytest.mark.generic
-def test_i2s_recoder_generic(dut: Dut) -> None:
+def test_i2s_recorder_generic(dut: Dut) -> None:
     dut.expect('PDM microphone recording example start')
     dut.expect('--------------------------------------')
     dut.expect('I \\(([0-9]+)\\) pdm_rec_example: Initializing SD card')