Merge branch 'bugfix/i2s_param_comments' into 'release/v3.0'

modify i2s param and comments

See merge request idf/esp-idf!2266

Author: igrr

components/driver/i2s.c

@@ -1010,6 +1010,12 @@ esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num)
         }
     }
     if (p_i2s_obj[i2s_num]->tx && p_i2s_obj[i2s_num]->tx->buf != NULL && p_i2s_obj[i2s_num]->tx->buf_size != 0) {
+        int bytes_left = 0;
+        bytes_left = (p_i2s_obj[i2s_num]->tx->buf_size - p_i2s_obj[i2s_num]->tx->rw_pos) % 4;
+        if (bytes_left) {
+            size_t zero_bytes = 0, bytes_written;
+            i2s_write(i2s_num, (void *)&zero_bytes, bytes_left, &bytes_written, portMAX_DELAY);
+        }
         for (int i = 0; i < p_i2s_obj[i2s_num]->dma_buf_count; i++) {
             memset(p_i2s_obj[i2s_num]->tx->buf[i], 0, p_i2s_obj[i2s_num]->tx->buf_size);
         }
@@ -1119,9 +1125,9 @@ esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num)
     return ESP_OK;
 }
 
-int i2s_write_bytes(i2s_port_t i2s_num, const char *src, size_t size, TickType_t ticks_to_wait)
+int i2s_write_bytes(i2s_port_t i2s_num, const void *src, size_t size, TickType_t ticks_to_wait)
 {
-    int bytes_written = 0;
+    size_t bytes_written = 0;
     int res = 0;
     res = i2s_write(i2s_num, src, size, &bytes_written, ticks_to_wait);
     if (res != ESP_OK) {
@@ -1131,15 +1137,16 @@ int i2s_write_bytes(i2s_port_t i2s_num, const char *src, size_t size, TickType_t
     }
 }
 
-esp_err_t i2s_write(i2s_port_t i2s_num, const char *src, size_t size, int *bytes_written, TickType_t ticks_to_wait)
+esp_err_t i2s_write(i2s_port_t i2s_num, const void *src, size_t size, size_t *bytes_written, TickType_t ticks_to_wait)
 {
-    char *data_ptr;
+    char *data_ptr, *src_byte;
     int bytes_can_write;
     *bytes_written = 0;
     I2S_CHECK((i2s_num < I2S_NUM_MAX), "i2s_num error", ESP_ERR_INVALID_ARG);
     I2S_CHECK((size < I2S_MAX_BUFFER_SIZE), "size is too large", ESP_ERR_INVALID_ARG);
     I2S_CHECK((p_i2s_obj[i2s_num]->tx), "tx NULL", ESP_ERR_INVALID_ARG);
     xSemaphoreTake(p_i2s_obj[i2s_num]->tx->mux, (portTickType)portMAX_DELAY);
+    src_byte = (char *)src;
     while (size > 0) {
         if (p_i2s_obj[i2s_num]->tx->rw_pos == p_i2s_obj[i2s_num]->tx->buf_size || p_i2s_obj[i2s_num]->tx->curr_ptr == NULL) {
             if (xQueueReceive(p_i2s_obj[i2s_num]->tx->queue, &p_i2s_obj[i2s_num]->tx->curr_ptr, ticks_to_wait) == pdFALSE) {
@@ -1154,17 +1161,17 @@ esp_err_t i2s_write(i2s_port_t i2s_num, const char *src, size_t size, int *bytes
         if (bytes_can_write > size) {
             bytes_can_write = size;
         }
-        memcpy(data_ptr, src, bytes_can_write);
+        memcpy(data_ptr, src_byte, bytes_can_write);
         size -= bytes_can_write;
-        src += bytes_can_write;
+        src_byte += bytes_can_write;
         p_i2s_obj[i2s_num]->tx->rw_pos += bytes_can_write;
         (*bytes_written) += bytes_can_write;
     }
     xSemaphoreGive(p_i2s_obj[i2s_num]->tx->mux);
     return ESP_OK;
 }
 
-esp_err_t i2s_write_expand(i2s_port_t i2s_num, const char *src, int size, int src_bits, int aim_bits, int *bytes_written, TickType_t ticks_to_wait)
+esp_err_t i2s_write_expand(i2s_port_t i2s_num, const void *src, size_t size, size_t src_bits, size_t aim_bits, size_t *bytes_written, TickType_t ticks_to_wait)
 {
     char *data_ptr;
     int bytes_can_write, tail;
@@ -1227,9 +1234,9 @@ esp_err_t i2s_write_expand(i2s_port_t i2s_num, const char *src, int size, int sr
     return ESP_OK;
 }
 
-int i2s_read_bytes(i2s_port_t i2s_num, char* dest, size_t size, TickType_t ticks_to_wait)
+int i2s_read_bytes(i2s_port_t i2s_num, void *dest, size_t size, TickType_t ticks_to_wait)
 {
-    int bytes_read = 0;
+    size_t bytes_read = 0;
     int res = 0;
     res = i2s_read(i2s_num, dest, size, &bytes_read, ticks_to_wait);
     if (res != ESP_OK) {
@@ -1239,11 +1246,12 @@ int i2s_read_bytes(i2s_port_t i2s_num, char* dest, size_t size, TickType_t ticks
     }
 }
 
-esp_err_t i2s_read(i2s_port_t i2s_num, char* dest, size_t size, int *bytes_read, TickType_t ticks_to_wait)
+esp_err_t i2s_read(i2s_port_t i2s_num, void *dest, size_t size, size_t *bytes_read, TickType_t ticks_to_wait)
 {
-    char *data_ptr;
+    char *data_ptr, *dest_byte;
     int bytes_can_read;
     *bytes_read = 0;
+    dest_byte = (char *)dest;
     I2S_CHECK((i2s_num < I2S_NUM_MAX), "i2s_num error", ESP_ERR_INVALID_ARG);
     I2S_CHECK((size < I2S_MAX_BUFFER_SIZE), "size is too large", ESP_ERR_INVALID_ARG);
     I2S_CHECK((p_i2s_obj[i2s_num]->rx), "rx NULL", ESP_ERR_INVALID_ARG);
@@ -1261,90 +1269,40 @@ esp_err_t i2s_read(i2s_port_t i2s_num, char* dest, size_t size, int *bytes_read,
         if (bytes_can_read > size) {
             bytes_can_read = size;
         }
-        memcpy(dest, data_ptr, bytes_can_read);
+        memcpy(dest_byte, data_ptr, bytes_can_read);
         size -= bytes_can_read;
-        dest += bytes_can_read;
+        dest_byte += bytes_can_read;
         p_i2s_obj[i2s_num]->rx->rw_pos += bytes_can_read;
         (*bytes_read) += bytes_can_read;
     }
     xSemaphoreGive(p_i2s_obj[i2s_num]->rx->mux);
     return ESP_OK;
 }
 
-int i2s_push_sample(i2s_port_t i2s_num, const char *sample, TickType_t ticks_to_wait)
+int i2s_push_sample(i2s_port_t i2s_num, const void *sample, TickType_t ticks_to_wait)
 {
-    int bytes_push = 0;
+    size_t bytes_push = 0;
     int res = 0;
-    res = i2s_write_sample(i2s_num, sample, &bytes_push, ticks_to_wait);
+    I2S_CHECK((i2s_num < I2S_NUM_MAX), "i2s_num error", ESP_FAIL);
+    res = i2s_write(i2s_num, sample, p_i2s_obj[i2s_num]->bytes_per_sample, &bytes_push, ticks_to_wait);
     if (res != ESP_OK) {
         return ESP_FAIL;
     } else {
         return bytes_push;
     }
 }
 
-esp_err_t i2s_write_sample(i2s_port_t i2s_num, const char *sample, int *sample_write, TickType_t ticks_to_wait)
-{
-    int i;
-    char *data_ptr;
-    *sample_write = 0;
-    I2S_CHECK((i2s_num < I2S_NUM_MAX), "i2s_num error", ESP_ERR_INVALID_ARG);
-    if (p_i2s_obj[i2s_num]->tx->rw_pos == p_i2s_obj[i2s_num]->tx->buf_size || p_i2s_obj[i2s_num]->tx->curr_ptr == NULL) {
-        if (xQueueReceive(p_i2s_obj[i2s_num]->tx->queue, &p_i2s_obj[i2s_num]->tx->curr_ptr, ticks_to_wait) == pdFALSE) {
-            return *sample_write;
-        }
-        ESP_LOGD(I2S_TAG, "rw_pos: %d, buf_size: %d, curr_ptr: %d", p_i2s_obj[i2s_num]->tx->rw_pos, p_i2s_obj[i2s_num]->tx->buf_size, (int)p_i2s_obj[i2s_num]->tx->curr_ptr);
-        p_i2s_obj[i2s_num]->tx->rw_pos = 0;
-    }
-    data_ptr = (char*)p_i2s_obj[i2s_num]->tx->curr_ptr;
-    data_ptr += p_i2s_obj[i2s_num]->tx->rw_pos;
-    for (i = 0; i < p_i2s_obj[i2s_num]->bytes_per_sample * p_i2s_obj[i2s_num]->channel_num; i++) {
-        *data_ptr++ = *sample++;
-        (*sample_write) += 1;
-    }
-    p_i2s_obj[i2s_num]->tx->rw_pos += (*sample_write);
-    return ESP_OK;
-
-}
-
-int i2s_pop_sample(i2s_port_t i2s_num, char *sample, TickType_t ticks_to_wait)
+int i2s_pop_sample(i2s_port_t i2s_num, void *sample, TickType_t ticks_to_wait)
 {
-    int bytes_pop = 0;
+    size_t bytes_pop = 0;
     int res = 0;
-    res = i2s_read_sample(i2s_num, sample, &bytes_pop, ticks_to_wait);
+    I2S_CHECK((i2s_num < I2S_NUM_MAX), "i2s_num error", ESP_FAIL);
+    res = i2s_read(i2s_num, sample, p_i2s_obj[i2s_num]->bytes_per_sample, &bytes_pop, ticks_to_wait);
     if (res != ESP_OK) {
         return ESP_FAIL;
     } else {
         return bytes_pop;
     }
 }
 
-esp_err_t i2s_read_sample(i2s_port_t i2s_num, char *sample, int *sample_read, TickType_t ticks_to_wait)
-{
-    int i;
-    *sample_read = 0;
-    char *data_ptr;
-    I2S_CHECK((i2s_num < I2S_NUM_MAX), "i2s_num error", ESP_ERR_INVALID_ARG);
-    if (p_i2s_obj[i2s_num]->rx->rw_pos == p_i2s_obj[i2s_num]->rx->buf_size || p_i2s_obj[i2s_num]->rx->curr_ptr == NULL) {
-        if (xQueueReceive(p_i2s_obj[i2s_num]->rx->queue, &p_i2s_obj[i2s_num]->rx->curr_ptr, ticks_to_wait) == pdFALSE) {
-            return *sample_read;
-        }
-        p_i2s_obj[i2s_num]->rx->rw_pos = 0;
-    }
-    data_ptr = (char*)p_i2s_obj[i2s_num]->rx->curr_ptr;
-    data_ptr += p_i2s_obj[i2s_num]->rx->rw_pos;
-    for (i = 0; i < p_i2s_obj[i2s_num]->bytes_per_sample; i++) {
-        *sample++ = *data_ptr++;
-        (*sample_read) += 1;
-    }
-    if (p_i2s_obj[i2s_num]->channel_num == 2) {
-        for (i = 0; i < p_i2s_obj[i2s_num]->bytes_per_sample; i++) {
-            *sample++ = *data_ptr++;
-            (*sample_read) += 1;
-        }
-    }
-
-    p_i2s_obj[i2s_num]->rx->rw_pos += p_i2s_obj[i2s_num]->bytes_per_sample * p_i2s_obj[i2s_num]->channel_num;
-    return ESP_OK;
-}
 

components/driver/include/driver/i2s.h

@@ -269,7 +269,7 @@ esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num);
  *     - The amount of bytes written, if timeout, the result will be less than the size passed in.
  *     - ESP_FAIL  Parameter error
  */
-int i2s_write_bytes(i2s_port_t i2s_num, const char *src, size_t size, TickType_t ticks_to_wait) __attribute__ ((deprecated));
+int i2s_write_bytes(i2s_port_t i2s_num, const void *src, size_t size, TickType_t ticks_to_wait) __attribute__ ((deprecated));
 
 /**
  * @brief Write data to I2S DMA transmit buffer.
@@ -293,7 +293,7 @@ int i2s_write_bytes(i2s_port_t i2s_num, const char *src, size_t size, TickType_t
  *     - ESP_OK               Success
  *     - ESP_ERR_INVALID_ARG  Parameter error
  */
-esp_err_t i2s_write(i2s_port_t i2s_num, const char *src, size_t size, int *bytes_written, TickType_t ticks_to_wait);
+esp_err_t i2s_write(i2s_port_t i2s_num, const void *src, size_t size, size_t *bytes_written, TickType_t ticks_to_wait);
 
 /**
  * @brief Write data to I2S DMA transmit buffer while expanding the number of bits per sample. For example, expanding 16-bit PCM to 32-bit PCM.
@@ -324,7 +324,7 @@ esp_err_t i2s_write(i2s_port_t i2s_num, const char *src, size_t size, int *bytes
  *     - ESP_OK              Success
  *     - ESP_ERR_INVALID_ARG Parameter error
  */
-esp_err_t i2s_write_expand(i2s_port_t i2s_num, const char *src, int size, int src_bits, int aim_bits, int *bytes_written, TickType_t ticks_to_wait);
+esp_err_t i2s_write_expand(i2s_port_t i2s_num, const void *src, size_t size, size_t src_bits, size_t aim_bits, size_t *bytes_written, TickType_t ticks_to_wait);
 
 /**
  * @brief Read data from I2S DMA receive buffer
@@ -336,7 +336,7 @@ esp_err_t i2s_write_expand(i2s_port_t i2s_num, const char *src, int size, int sr
  *     - The amount of bytes read, if timeout, bytes read will be less than the size passed in
  *     - ESP_FAIL  Parameter error
  */
-int i2s_read_bytes(i2s_port_t i2s_num, char* dest, size_t size, TickType_t ticks_to_wait) __attribute__ ((deprecated));
+int i2s_read_bytes(i2s_port_t i2s_num, void *dest, size_t size, TickType_t ticks_to_wait) __attribute__ ((deprecated));
 
 /**
  * @brief Read data from I2S DMA receive buffer
@@ -358,69 +358,43 @@ int i2s_read_bytes(i2s_port_t i2s_num, char* dest, size_t size, TickType_t ticks
  *     - ESP_OK               Success
  *     - ESP_ERR_INVALID_ARG  Parameter error
  */
-esp_err_t i2s_read(i2s_port_t i2s_num, char* dest, size_t size, int *bytes_read, TickType_t ticks_to_wait);
+esp_err_t i2s_read(i2s_port_t i2s_num, void *dest, size_t size, size_t *bytes_read, TickType_t ticks_to_wait);
 
 /**
  * @brief Write a single sample to the I2S DMA TX buffer.
  *
- * This function is deprecated. Use 'i2s_write_sample' instead.
+ * This function is deprecated. Use 'i2s_write' instead.
  * This definition will be removed in a future release.
  *
- * @return
- *     - Number of bytes successfully pushed to DMA buffer, will be either zero or the size of configured sample buffer
- *     - ESP_FAIL Parameter error
- */
-int i2s_push_sample(i2s_port_t i2s_num, const char *sample, TickType_t ticks_to_wait) __attribute__ ((deprecated));
-
- /**
- * @brief Write a single sample to the I2S DMA TX buffer.
- *
- * Size of the sample is determined by the channel_format (mono or stereo)) & bits_per_sample configuration (see i2s_config_t).
- *
- * @param i2s_num            I2S_NUM_0, I2S_NUM_1
- *
- * @param sample             Pointer to buffer containing sample to write. Size of buffer (in bytes) = (number of channels) * bits_per_sample / 8.
+ * @param i2s_num         I2S_NUM_0, I2S_NUM_1
  *
- * @param[out] sample_write  Number of bytes successfully pushed to DMA buffer, will be either zero or the size of configured sample buffer.
+ * @param sample          Buffer to read data. Size of buffer (in bytes) = bits_per_sample / 8.
  *
- * @param ticks_to_wait      Timeout in RTOS ticks. If space is not available in the DMA TX buffer within this period, no data is written and function returns 0.
+ * @param ticks_to_wait   Timeout in RTOS ticks. If a sample is not available in the DMA buffer within this period, no data is read and function returns zero.
  *
  * @return
- *     - ESP_OK              Success
- *     - ESP_ERR_INVALID_ARG Parameter error
- */
-esp_err_t i2s_write_sample(i2s_port_t i2s_num, const char *sample, int *sample_write, TickType_t ticks_to_wait);
-
-/**
- * @brief Read a single sample from the I2S DMA RX buffer.
- *
- * This function is deprecated. Use 'i2s_read_sample' instead.
- * This definition will be removed in a future release.
- *
- * @return
- *     - Number of bytes successfully read from DMA buffer, will be either zero or the size of configured sample buffer
+ *     - Number of bytes successfully pushed to DMA buffer, will be either zero or the size of configured sample buffer (in bytes).
  *     - ESP_FAIL Parameter error
  */
-int i2s_pop_sample(i2s_port_t i2s_num, char *sample, TickType_t ticks_to_wait) __attribute__ ((deprecated));
+int i2s_push_sample(i2s_port_t i2s_num, const void *sample, TickType_t ticks_to_wait) __attribute__ ((deprecated));
 
 /**
  * @brief Read a single sample from the I2S DMA RX buffer.
  *
- * Size of the sample is determined by the channel_format (mono or stereo)) & bits_per_sample configuration (see i2s_config_t).
- *
- * @param i2s_num            I2S_NUM_0, I2S_NUM_1
+ * This function is deprecated. Use 'i2s_read' instead.
+ * This definition will be removed in a future release.
  *
- * @param sample             Buffer sample data will be read into. Size of buffer (in bytes) = (number of channels) * bits_per_sample / 8.
+ * @param i2s_num         I2S_NUM_0, I2S_NUM_1
  *
- * @param[out] sample_read   Number of bytes successfully read from DMA buffer, will be either zero or the size of configured sample buffer.
+ * @param sample          Buffer to write data. Size of buffer (in bytes) = bits_per_sample / 8.
  *
- * @param ticks_to_wait      Timeout in RTOS ticks. If a sample is not available in the DMA buffer within this period, no data is read and function returns zero.
+ * @param ticks_to_wait   Timeout in RTOS ticks. If a sample is not available in the DMA buffer within this period, no data is read and function returns zero.
  *
  * @return
- *     - ESP_OK              Success
- *     - ESP_ERR_INVALID_ARG Parameter error
+ *     - Number of bytes successfully read from DMA buffer, will be either zero or the size of configured sample buffer (in bytes).
+ *     - ESP_FAIL Parameter error
  */
-esp_err_t i2s_read_sample(i2s_port_t i2s_num, char *sample, int *sample_read, TickType_t ticks_to_wait);
+int i2s_pop_sample(i2s_port_t i2s_num, void *sample, TickType_t ticks_to_wait) __attribute__ ((deprecated));
 
 /**
  * @brief Set sample rate used for I2S RX and TX.

examples/bluetooth/a2dp_sink/main/bt_app_av.c

@@ -56,8 +56,8 @@ void bt_app_a2d_cb(esp_a2d_cb_event_t event, esp_a2d_cb_param_t *param)
 
 void bt_app_a2d_data_cb(const uint8_t *data, uint32_t len)
 {
-    int i2s_write_len;
-    i2s_write(0, (const char *)data, len, &i2s_write_len, portMAX_DELAY);
+    size_t bytes_written;
+    i2s_write(0, data, len, &bytes_written, portMAX_DELAY);
     if (++m_pkt_cnt % 100 == 0) {
         ESP_LOGE(BT_AV_TAG, "audio data pkt cnt %u", m_pkt_cnt);
     }

examples/peripherals/i2s/main/i2s_example_main.c

@@ -29,7 +29,7 @@ static void setup_triangle_sine_waves(int bits)
     int *samples_data = malloc(((bits+8)/16)*SAMPLE_PER_CYCLE*4);
     unsigned int i, sample_val;
     double sin_float, triangle_float, triangle_step = (double) pow(2, bits) / SAMPLE_PER_CYCLE;
-    int i2s_bytes_write = 0;
+    size_t i2s_bytes_write = 0;
 
     printf("\r\nTest bits=%d free mem=%d, written data=%d\n", bits, esp_get_free_heap_size(), ((bits+8)/16)*SAMPLE_PER_CYCLE*4);
 
@@ -69,7 +69,7 @@ static void setup_triangle_sine_waves(int bits)
     //         i2s_push_sample(0, &samples_data[i*2], 100);
     // }
     // or write
-    i2s_write(I2S_NUM, (const char *)samples_data, ((bits+8)/16)*SAMPLE_PER_CYCLE*4, &i2s_bytes_write, 100);
+    i2s_write(I2S_NUM, samples_data, ((bits+8)/16)*SAMPLE_PER_CYCLE*4, &i2s_bytes_write, 100);
 
     free(samples_data);
 }

examples/peripherals/i2s_adc_dac/main/app_main.c

@@ -199,15 +199,15 @@ void example_i2s_adc_dac(void*arg)
     example_i2s_init();
     int i2s_read_len = EXAMPLE_I2S_READ_LEN;
     int flash_wr_size = 0;
-    int i2s_bytes_read = 0;
+    size_t bytes_read, bytes_written;
 
     //2. Record audio from ADC and save in flash
 #if RECORD_IN_FLASH_EN
     char* i2s_read_buff = (char*) calloc(i2s_read_len, sizeof(char));
     uint8_t* flash_write_buff = (uint8_t*) calloc(i2s_read_len, sizeof(char));
     while (flash_wr_size < FLASH_RECORD_SIZE) {
         //read data from I2S bus, in this case, from ADC.
-        i2s_read(EXAMPLE_I2S_NUM, (char*) i2s_read_buff, i2s_read_len, &i2s_bytes_read, portMAX_DELAY);
+        i2s_read(EXAMPLE_I2S_NUM, i2s_read_buff, i2s_read_len, &bytes_read, portMAX_DELAY);
         example_disp_buf((uint8_t*) i2s_read_buff, 64);
         //save original data from I2S(ADC) into flash.
         esp_partition_write(data_partition, flash_wr_size, i2s_read_buff, i2s_read_len);
@@ -222,7 +222,6 @@ void example_i2s_adc_dac(void*arg)
 
     uint8_t* flash_read_buff = (uint8_t*) calloc(i2s_read_len, sizeof(char));
     uint8_t* i2s_write_buff = (uint8_t*) calloc(i2s_read_len, sizeof(char));
-    int i2s_write_len = 0;
     while (1) {
 
         //3. Read flash and replay the sound via DAC
@@ -233,7 +232,7 @@ void example_i2s_adc_dac(void*arg)
             //process data and scale to 8bit for I2S DAC.
             example_i2s_adc_data_scale(i2s_write_buff, flash_read_buff, FLASH_SECTOR_SIZE);
             //send data
-            i2s_write(EXAMPLE_I2S_NUM, (char*) i2s_write_buff, FLASH_SECTOR_SIZE, &i2s_write_len, portMAX_DELAY);
+            i2s_write(EXAMPLE_I2S_NUM, i2s_write_buff, FLASH_SECTOR_SIZE, &bytes_written, portMAX_DELAY);
             printf("playing: %d %%\n", rd_offset * 100 / flash_wr_size);
         }
 #endif
@@ -246,7 +245,7 @@ void example_i2s_adc_dac(void*arg)
         while (offset < tot_size) {
             int play_len = ((tot_size - offset) > (4 * 1024)) ? (4 * 1024) : (tot_size - offset);
             int i2s_wr_len = example_i2s_dac_data_scale(i2s_write_buff, (uint8_t*)(audio_table + offset), play_len);
-            i2s_write(EXAMPLE_I2S_NUM, (const char*) i2s_write_buff, i2s_wr_len, &i2s_write_len, portMAX_DELAY);
+            i2s_write(EXAMPLE_I2S_NUM, i2s_write_buff, i2s_wr_len, &bytes_written, portMAX_DELAY);
             offset += play_len;
             example_disp_buf((uint8_t*) i2s_write_buff, 32);
         }