1 // Copyright 2015-2020 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #include "esp_types.h" 18 #include "esp_err.h" 19 #include "esp_osal/esp_osal.h" 20 #include "esp_osal/semphr.h" 21 #include "soc/i2s_periph.h" 22 #include "soc/rtc_periph.h" 23 #include "soc/soc_caps.h" 24 #include "hal/i2s_hal.h" 25 #include "hal/i2s_types.h" 26 #include "driver/periph_ctrl.h" 27 #include "esp_intr_alloc.h" 28 #if SOC_I2S_SUPPORTS_ADC_DAC 29 #include "driver/adc.h" 30 #endif 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 #define I2S_PIN_NO_CHANGE (-1) /*!< Use in i2s_pin_config_t for pins which should not be changed */ 37 38 typedef intr_handle_t i2s_isr_handle_t; 39 40 /** 41 * @brief Set I2S pin number 42 * 43 * @note 44 * The I2S peripheral output signals can be connected to multiple GPIO pads. 45 * However, the I2S peripheral input signal can only be connected to one GPIO pad. 46 * 47 * @param i2s_num I2S_NUM_0 or I2S_NUM_1 48 * 49 * @param pin I2S Pin structure, or NULL to set 2-channel 8-bit internal DAC pin configuration (GPIO25 & GPIO26) 50 * 51 * Inside the pin configuration structure, set I2S_PIN_NO_CHANGE for any pin where 52 * the current configuration should not be changed. 53 * 54 * @note if *pin is set as NULL, this function will initialize both of the built-in DAC channels by default. 55 * if you don't want this to happen and you want to initialize only one of the DAC channels, you can call i2s_set_dac_mode instead. 56 * 57 * @return 58 * - ESP_OK Success 59 * - ESP_ERR_INVALID_ARG Parameter error 60 * - ESP_FAIL IO error 61 */ 62 esp_err_t i2s_set_pin(i2s_port_t i2s_num, const i2s_pin_config_t *pin); 63 64 #if SOC_I2S_SUPPORTS_PDM 65 /** 66 * @brief Set PDM mode down-sample rate 67 * In PDM RX mode, there would be 2 rounds of downsample process in hardware. 68 * In the first downsample process, the sampling number can be 16 or 8. 69 * In the second downsample process, the sampling number is fixed as 8. 70 * So the clock frequency in PDM RX mode would be (fpcm * 64) or (fpcm * 128) accordingly. 71 * @param i2s_num I2S_NUM_0, I2S_NUM_1 72 * @param dsr i2s RX down sample rate for PDM mode. 73 * 74 * @note After calling this function, it would call i2s_set_clk inside to update the clock frequency. 75 * Please call this function after I2S driver has been initialized. 76 * 77 * @return 78 * - ESP_OK Success 79 * - ESP_ERR_INVALID_ARG Parameter error 80 * - ESP_ERR_NO_MEM Out of memory 81 */ 82 esp_err_t i2s_set_pdm_rx_down_sample(i2s_port_t i2s_num, i2s_pdm_dsr_t dsr); 83 #endif 84 85 /** 86 * @brief Set I2S dac mode, I2S built-in DAC is disabled by default 87 * 88 * @param dac_mode DAC mode configurations - see i2s_dac_mode_t 89 * 90 * @note Built-in DAC functions are only supported on I2S0 for current ESP32 chip. 91 * If either of the built-in DAC channel are enabled, the other one can not 92 * be used as RTC DAC function at the same time. 93 * 94 * @return 95 * - ESP_OK Success 96 * - ESP_ERR_INVALID_ARG Parameter error 97 */ 98 esp_err_t i2s_set_dac_mode(i2s_dac_mode_t dac_mode); 99 100 /** 101 * @brief Install and start I2S driver. 102 * 103 * @param i2s_num I2S_NUM_0, I2S_NUM_1 104 * 105 * @param i2s_config I2S configurations - see i2s_config_t struct 106 * 107 * @param queue_size I2S event queue size/depth. 108 * 109 * @param i2s_queue I2S event queue handle, if set NULL, driver will not use an event queue. 110 * 111 * This function must be called before any I2S driver read/write operations. 112 * 113 * @return 114 * - ESP_OK Success 115 * - ESP_ERR_INVALID_ARG Parameter error 116 * - ESP_ERR_NO_MEM Out of memory 117 */ 118 esp_err_t i2s_driver_install(i2s_port_t i2s_num, const i2s_config_t *i2s_config, int queue_size, void* i2s_queue); 119 120 /** 121 * @brief Uninstall I2S driver. 122 * 123 * @param i2s_num I2S_NUM_0, I2S_NUM_1 124 * 125 * @return 126 * - ESP_OK Success 127 * - ESP_ERR_INVALID_ARG Parameter error 128 */ 129 esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num); 130 131 /** 132 * @brief Write data to I2S DMA transmit buffer. 133 * 134 * @param i2s_num I2S_NUM_0, I2S_NUM_1 135 * 136 * @param src Source address to write from 137 * 138 * @param size Size of data in bytes 139 * 140 * @param[out] bytes_written Number of bytes written, if timeout, the result will be less than the size passed in. 141 * 142 * @param ticks_to_wait TX buffer wait timeout in RTOS ticks. If this 143 * many ticks pass without space becoming available in the DMA 144 * transmit buffer, then the function will return (note that if the 145 * data is written to the DMA buffer in pieces, the overall operation 146 * may still take longer than this timeout.) Pass portMAX_DELAY for no 147 * timeout. 148 * 149 * @return 150 * - ESP_OK Success 151 * - ESP_ERR_INVALID_ARG Parameter error 152 */ 153 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); 154 155 /** 156 * @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. 157 * 158 * @param i2s_num I2S_NUM_0, I2S_NUM_1 159 * 160 * @param src Source address to write from 161 * 162 * @param size Size of data in bytes 163 * 164 * @param src_bits Source audio bit 165 * 166 * @param aim_bits Bit wanted, no more than 32, and must be greater than src_bits 167 * 168 * @param[out] bytes_written Number of bytes written, if timeout, the result will be less than the size passed in. 169 * 170 * @param ticks_to_wait TX buffer wait timeout in RTOS ticks. If this 171 * many ticks pass without space becoming available in the DMA 172 * transmit buffer, then the function will return (note that if the 173 * data is written to the DMA buffer in pieces, the overall operation 174 * may still take longer than this timeout.) Pass portMAX_DELAY for no 175 * timeout. 176 * 177 * Format of the data in source buffer is determined by the I2S 178 * configuration (see i2s_config_t). 179 * 180 * @return 181 * - ESP_OK Success 182 * - ESP_ERR_INVALID_ARG Parameter error 183 */ 184 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); 185 186 /** 187 * @brief Read data from I2S DMA receive buffer 188 * 189 * @param i2s_num I2S_NUM_0, I2S_NUM_1 190 * 191 * @param dest Destination address to read into 192 * 193 * @param size Size of data in bytes 194 * 195 * @param[out] bytes_read Number of bytes read, if timeout, bytes read will be less than the size passed in. 196 * 197 * @param ticks_to_wait RX buffer wait timeout in RTOS ticks. If this many ticks pass without bytes becoming available in the DMA receive buffer, then the function will return (note that if data is read from the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout. 198 * 199 * @note If the built-in ADC mode is enabled, we should call i2s_adc_enable and i2s_adc_disable around the whole reading process, 200 * to prevent the data getting corrupted. 201 * 202 * @return 203 * - ESP_OK Success 204 * - ESP_ERR_INVALID_ARG Parameter error 205 */ 206 esp_err_t i2s_read(i2s_port_t i2s_num, void *dest, size_t size, size_t *bytes_read, TickType_t ticks_to_wait); 207 208 /** 209 * @brief Set sample rate used for I2S RX and TX. 210 * 211 * The bit clock rate is determined by the sample rate and i2s_config_t configuration parameters (number of channels, bits_per_sample). 212 * 213 * `bit_clock = rate * (number of channels) * bits_per_sample` 214 * 215 * @param i2s_num I2S_NUM_0, I2S_NUM_1 216 * 217 * @param rate I2S sample rate (ex: 8000, 44100...) 218 * 219 * @return 220 * - ESP_OK Success 221 * - ESP_ERR_INVALID_ARG Parameter error 222 * - ESP_ERR_NO_MEM Out of memory 223 */ 224 esp_err_t i2s_set_sample_rates(i2s_port_t i2s_num, uint32_t rate); 225 226 /** 227 * @brief Stop I2S driver 228 * 229 * There is no need to call i2s_stop() before calling i2s_driver_uninstall(). 230 * 231 * Disables I2S TX/RX, until i2s_start() is called. 232 * 233 * @param i2s_num I2S_NUM_0, I2S_NUM_1 234 * 235 * @return 236 * - ESP_OK Success 237 * - ESP_ERR_INVALID_ARG Parameter error 238 */ 239 esp_err_t i2s_stop(i2s_port_t i2s_num); 240 241 /** 242 * @brief Start I2S driver 243 * 244 * It is not necessary to call this function after i2s_driver_install() (it is started automatically), however it is necessary to call it after i2s_stop(). 245 * 246 * 247 * @param i2s_num I2S_NUM_0, I2S_NUM_1 248 * 249 * @return 250 * - ESP_OK Success 251 * - ESP_ERR_INVALID_ARG Parameter error 252 */ 253 esp_err_t i2s_start(i2s_port_t i2s_num); 254 255 /** 256 * @brief Zero the contents of the TX DMA buffer. 257 * 258 * Pushes zero-byte samples into the TX DMA buffer, until it is full. 259 * 260 * @param i2s_num I2S_NUM_0, I2S_NUM_1 261 * 262 * @return 263 * - ESP_OK Success 264 * - ESP_ERR_INVALID_ARG Parameter error 265 */ 266 esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num); 267 268 /** 269 * @brief Set clock & bit width used for I2S RX and TX. 270 * 271 * Similar to i2s_set_sample_rates(), but also sets bit width. 272 * 273 * @param i2s_num I2S_NUM_0, I2S_NUM_1 274 * 275 * @param rate I2S sample rate (ex: 8000, 44100...) 276 * 277 * @param bits I2S bit width (I2S_BITS_PER_SAMPLE_16BIT, I2S_BITS_PER_SAMPLE_24BIT, I2S_BITS_PER_SAMPLE_32BIT) 278 * 279 * @param ch I2S channel, (I2S_CHANNEL_MONO, I2S_CHANNEL_STEREO) 280 * 281 * @return 282 * - ESP_OK Success 283 * - ESP_ERR_INVALID_ARG Parameter error 284 * - ESP_ERR_NO_MEM Out of memory 285 */ 286 esp_err_t i2s_set_clk(i2s_port_t i2s_num, uint32_t rate, i2s_bits_per_sample_t bits, i2s_channel_t ch); 287 288 /** 289 * @brief get clock set on particular port number. 290 * 291 * @param i2s_num I2S_NUM_0, I2S_NUM_1 292 * 293 * @return 294 * - actual clock set by i2s driver 295 */ 296 float i2s_get_clk(i2s_port_t i2s_num); 297 298 #if SOC_I2S_SUPPORTS_ADC_DAC 299 /** 300 * @brief Set built-in ADC mode for I2S DMA, this function will initialize ADC pad, 301 * and set ADC parameters. 302 * @note In this mode, the ADC maximum sampling rate is 150KHz. Set the sampling rate through ``i2s_config_t``. 303 * @param adc_unit SAR ADC unit index 304 * @param adc_channel ADC channel index 305 * @return 306 * - ESP_OK Success 307 * - ESP_ERR_INVALID_ARG Parameter error 308 */ 309 esp_err_t i2s_set_adc_mode(adc_unit_t adc_unit, adc1_channel_t adc_channel); 310 311 /** 312 * @brief Start to use I2S built-in ADC mode 313 * @note This function would acquire the lock of ADC to prevent the data getting corrupted 314 * during the I2S peripheral is being used to do fully continuous ADC sampling. 315 * 316 * @param i2s_num i2s port index 317 * @return 318 * - ESP_OK Success 319 * - ESP_ERR_INVALID_ARG Parameter error 320 * - ESP_ERR_INVALID_STATE Driver state error 321 */ 322 esp_err_t i2s_adc_enable(i2s_port_t i2s_num); 323 324 /** 325 * @brief Stop to use I2S built-in ADC mode 326 * @param i2s_num i2s port index 327 * @note This function would release the lock of ADC so that other tasks can use ADC. 328 * @return 329 * - ESP_OK Success 330 * - ESP_ERR_INVALID_ARG Parameter error 331 * - ESP_ERR_INVALID_STATE Driver state error 332 */ 333 esp_err_t i2s_adc_disable(i2s_port_t i2s_num); 334 #endif 335 336 #ifdef __cplusplus 337 } 338 #endif 339