1 /* 2 * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * This file is for the backward compatible to the deprecated I2S APIs, 9 * The deprecated APIs will no longer supported in the future 10 * Please refer to "hal/i2s_types.h" for the latest I2S driver types 11 * Note that only one set of I2S APIs is allowed to be used at the same time 12 */ 13 #pragma once 14 15 #include "hal/i2s_types.h" 16 #include "driver/i2s_types.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 /******************** Deprecated Types **********************/ 22 #define I2S_PIN_NO_CHANGE (-1) /*!< Used in i2s_pin_config_t for pins which should not be changed */ 23 24 /** 25 * @brief I2S bit width per sample. 26 */ 27 typedef enum { 28 I2S_BITS_PER_SAMPLE_8BIT = 8, /*!< data bit-width: 8 */ 29 I2S_BITS_PER_SAMPLE_16BIT = 16, /*!< data bit-width: 16 */ 30 I2S_BITS_PER_SAMPLE_24BIT = 24, /*!< data bit-width: 24 */ 31 I2S_BITS_PER_SAMPLE_32BIT = 32, /*!< data bit-width: 32 */ 32 } i2s_bits_per_sample_t; 33 34 /** 35 * @brief I2S bit width per chan. 36 */ 37 typedef enum { 38 I2S_BITS_PER_CHAN_DEFAULT = (0), /*!< channel bit-width equals to data bit-width */ 39 I2S_BITS_PER_CHAN_8BIT = (8), /*!< channel bit-width: 8 */ 40 I2S_BITS_PER_CHAN_16BIT = (16), /*!< channel bit-width: 16 */ 41 I2S_BITS_PER_CHAN_24BIT = (24), /*!< channel bit-width: 24 */ 42 I2S_BITS_PER_CHAN_32BIT = (32), /*!< channel bit-width: 32 */ 43 } i2s_bits_per_chan_t; 44 45 /** 46 * @brief I2S channel. 47 */ 48 typedef enum { 49 I2S_CHANNEL_MONO = 1, /*!< I2S channel (mono), one channel activated. In this mode, you only need to send one channel data but the fifo will copy same data for the other unactivated channels automatically, then both channels will transmit same data. */ 50 I2S_CHANNEL_STEREO = 2, /*!< I2S channel (stereo), two (or more) channels activated. In this mode, these channels will transmit different data. */ 51 #if SOC_I2S_SUPPORTS_TDM 52 // Bit map of activated chan. 53 // There are 16 channels in TDM mode. 54 // For TX module, only the activated channel send the audio data, the unactivated channel send a constant(configurable) or will be skiped if 'skip_msk' is set. 55 // For RX module, only receive the audio data in activated channels, the data in unactivated channels will be ignored. 56 // the bit map of activated channel can not exceed the maximum enabled channel number (i.e. 0x10000 << total_chan_num). 57 // e.g: active_chan_mask = (I2S_TDM_ACTIVE_CH0 | I2S_TDM_ACTIVE_CH3), here the active_chan_number is 2 and total_chan_num is not supposed to be smaller than 4. 58 I2S_TDM_ACTIVE_CH0 = (0x1 << 16), /*!< I2S channel 0 activated */ 59 I2S_TDM_ACTIVE_CH1 = (0x1 << 17), /*!< I2S channel 1 activated */ 60 I2S_TDM_ACTIVE_CH2 = (0x1 << 18), /*!< I2S channel 2 activated */ 61 I2S_TDM_ACTIVE_CH3 = (0x1 << 19), /*!< I2S channel 3 activated */ 62 I2S_TDM_ACTIVE_CH4 = (0x1 << 20), /*!< I2S channel 4 activated */ 63 I2S_TDM_ACTIVE_CH5 = (0x1 << 21), /*!< I2S channel 5 activated */ 64 I2S_TDM_ACTIVE_CH6 = (0x1 << 22), /*!< I2S channel 6 activated */ 65 I2S_TDM_ACTIVE_CH7 = (0x1 << 23), /*!< I2S channel 7 activated */ 66 I2S_TDM_ACTIVE_CH8 = (0x1 << 24), /*!< I2S channel 8 activated */ 67 I2S_TDM_ACTIVE_CH9 = (0x1 << 25), /*!< I2S channel 9 activated */ 68 I2S_TDM_ACTIVE_CH10 = (0x1 << 26), /*!< I2S channel 10 activated */ 69 I2S_TDM_ACTIVE_CH11 = (0x1 << 27), /*!< I2S channel 11 activated */ 70 I2S_TDM_ACTIVE_CH12 = (0x1 << 28), /*!< I2S channel 12 activated */ 71 I2S_TDM_ACTIVE_CH13 = (0x1 << 29), /*!< I2S channel 13 activated */ 72 I2S_TDM_ACTIVE_CH14 = (0x1 << 30), /*!< I2S channel 14 activated */ 73 I2S_TDM_ACTIVE_CH15 = (0x1 << 31), /*!< I2S channel 15 activated */ 74 #endif 75 } i2s_channel_t; 76 77 /** 78 * @brief I2S communication standard format 79 */ 80 typedef enum { 81 I2S_COMM_FORMAT_STAND_I2S = 0X01, /*!< I2S communication I2S Philips standard, data launch at second BCK*/ 82 I2S_COMM_FORMAT_STAND_MSB = 0X02, /*!< I2S communication MSB alignment standard, data launch at first BCK*/ 83 I2S_COMM_FORMAT_STAND_PCM_SHORT = 0x04, /*!< PCM Short standard, also known as DSP mode. The period of synchronization signal (WS) is 1 bck cycle.*/ 84 I2S_COMM_FORMAT_STAND_PCM_LONG = 0x0C, /*!< PCM Long standard. The period of synchronization signal (WS) is channel_bit*bck cycles.*/ 85 I2S_COMM_FORMAT_STAND_MAX, /*!< standard max*/ 86 87 //old definition will be removed in the future. 88 I2S_COMM_FORMAT_I2S __attribute__((deprecated)) = 0x01, /*!< I2S communication format I2S, correspond to `I2S_COMM_FORMAT_STAND_I2S`*/ 89 I2S_COMM_FORMAT_I2S_MSB __attribute__((deprecated)) = 0x01, /*!< I2S format MSB, (I2S_COMM_FORMAT_I2S |I2S_COMM_FORMAT_I2S_MSB) correspond to `I2S_COMM_FORMAT_STAND_I2S`*/ 90 I2S_COMM_FORMAT_I2S_LSB __attribute__((deprecated)) = 0x02, /*!< I2S format LSB, (I2S_COMM_FORMAT_I2S |I2S_COMM_FORMAT_I2S_LSB) correspond to `I2S_COMM_FORMAT_STAND_MSB`*/ 91 I2S_COMM_FORMAT_PCM __attribute__((deprecated)) = 0x04, /*!< I2S communication format PCM, correspond to `I2S_COMM_FORMAT_STAND_PCM_SHORT`*/ 92 I2S_COMM_FORMAT_PCM_SHORT __attribute__((deprecated)) = 0x04, /*!< PCM Short, (I2S_COMM_FORMAT_PCM | I2S_COMM_FORMAT_PCM_SHORT) correspond to `I2S_COMM_FORMAT_STAND_PCM_SHORT`*/ 93 I2S_COMM_FORMAT_PCM_LONG __attribute__((deprecated)) = 0x08, /*!< PCM Long, (I2S_COMM_FORMAT_PCM | I2S_COMM_FORMAT_PCM_LONG) correspond to `I2S_COMM_FORMAT_STAND_PCM_LONG`*/ 94 } i2s_comm_format_t; 95 96 /** 97 * @brief I2S channel format type 98 */ 99 typedef enum { 100 I2S_CHANNEL_FMT_RIGHT_LEFT, /*!< Separated left and right channel */ 101 I2S_CHANNEL_FMT_ALL_RIGHT, /*!< Load right channel data in both two channels */ 102 I2S_CHANNEL_FMT_ALL_LEFT, /*!< Load left channel data in both two channels */ 103 I2S_CHANNEL_FMT_ONLY_RIGHT, /*!< Only load data in right channel (mono mode) */ 104 I2S_CHANNEL_FMT_ONLY_LEFT, /*!< Only load data in left channel (mono mode) */ 105 #if SOC_I2S_SUPPORTS_TDM 106 // Multiple channels are available with TDM feature 107 I2S_CHANNEL_FMT_MULTIPLE, /*!< More than two channels are used */ 108 #endif 109 } i2s_channel_fmt_t; 110 111 /** 112 * @brief I2S Mode 113 */ 114 typedef enum { 115 I2S_MODE_MASTER = (0x1 << 0), /*!< Master mode*/ 116 I2S_MODE_SLAVE = (0x1 << 1), /*!< Slave mode*/ 117 I2S_MODE_TX = (0x1 << 2), /*!< TX mode*/ 118 I2S_MODE_RX = (0x1 << 3), /*!< RX mode*/ 119 #if SOC_I2S_SUPPORTS_DAC 120 //built-in DAC functions are only supported on I2S0 for ESP32 chip. 121 I2S_MODE_DAC_BUILT_IN = (0x1 << 4), /*!< Output I2S data to built-in DAC, no matter the data format is 16bit or 32 bit, the DAC module will only take the 8bits from MSB*/ 122 #endif // SOC_I2S_SUPPORTS_DAC 123 #if SOC_I2S_SUPPORTS_ADC 124 I2S_MODE_ADC_BUILT_IN = (0x1 << 5), /*!< Input I2S data from built-in ADC, each data can be 12-bit width at most*/ 125 #endif // SOC_I2S_SUPPORTS_ADC 126 // PDM functions are only supported on I2S0 (all chips). 127 I2S_MODE_PDM = (0x1 << 6), /*!< I2S PDM mode*/ 128 } i2s_mode_t; 129 130 #if SOC_I2S_SUPPORTS_DAC 131 /** 132 * @brief I2S DAC mode for i2s_set_dac_mode. 133 * 134 * @note Built-in DAC functions are only supported on I2S0 for current ESP32 chip. 135 */ 136 typedef enum { 137 I2S_DAC_CHANNEL_DISABLE = 0, /*!< Disable I2S built-in DAC signals*/ 138 I2S_DAC_CHANNEL_RIGHT_EN = 1, /*!< Enable I2S built-in DAC right channel, maps to DAC channel 0 on GPIO25*/ 139 I2S_DAC_CHANNEL_LEFT_EN = 2, /*!< Enable I2S built-in DAC left channel, maps to DAC channel 1 on GPIO26*/ 140 I2S_DAC_CHANNEL_BOTH_EN = 0x3, /*!< Enable both of the I2S built-in DAC channels.*/ 141 I2S_DAC_CHANNEL_MAX = 0x4, /*!< I2S built-in DAC mode max index*/ 142 } i2s_dac_mode_t; 143 #endif //SOC_I2S_SUPPORTS_DAC 144 145 /** 146 * @brief I2S event queue types 147 */ 148 typedef enum { 149 I2S_EVENT_DMA_ERROR, /*!< I2S DMA has no next descriptor for sending or receiving */ 150 I2S_EVENT_TX_DONE, /*!< I2S DMA finished sending one DMA buffer */ 151 I2S_EVENT_RX_DONE, /*!< I2S DMA finished receiving one DMA buffer */ 152 I2S_EVENT_TX_Q_OVF, /*!< I2S DMA sending queue overflowed, the oldest data has been overwritten by the new data in the DMA buffer */ 153 I2S_EVENT_RX_Q_OVF, /*!< I2S DMA receive queue overflowed, the oldest data has been overwritten by the new data in the DMA buffer */ 154 } i2s_event_type_t; 155 156 /** 157 * @brief Event structure used in I2S event queue 158 */ 159 typedef struct { 160 i2s_event_type_t type; /*!< I2S event type */ 161 size_t size; /*!< I2S data size for I2S_DATA event*/ 162 } i2s_event_t; 163 164 /** 165 * @brief I2S GPIO pins configuration 166 */ 167 typedef struct { 168 int mck_io_num; /*!< MCK pin, output */ 169 int bck_io_num; /*!< BCK pin, input in slave role, output in master role */ 170 int ws_io_num; /*!< WS pin, input in slave role, output in master role */ 171 int data_out_num; /*!< DATA pin, output */ 172 int data_in_num; /*!< DATA pin, input */ 173 } i2s_pin_config_t; 174 175 #if SOC_I2S_SUPPORTS_PCM 176 /** 177 * @brief I2S PCM configuration 178 * 179 */ 180 typedef struct { 181 i2s_pcm_compress_t pcm_type; /*!< I2S PCM a/u-law decompress or compress type */ 182 } i2s_pcm_cfg_t; 183 #endif 184 185 #if SOC_I2S_SUPPORTS_PDM_TX 186 /** 187 * @brief Default I2S PDM Up-Sampling Rate configuration 188 */ 189 #define I2S_PDM_DEFAULT_UPSAMPLE_CONFIG(rate) { \ 190 .sample_rate = rate, \ 191 .fp = 960, \ 192 .fs = (rate) / 100, \ 193 } 194 195 /** 196 * @brief I2S PDM up-sample rate configuration 197 * @note TX PDM can only be set to the following two up-sampling rate configurations: 198 * 1: fp = 960, fs = sample_rate / 100, in this case, Fpdm = 128*48000 199 * 2: fp = 960, fs = 480, in this case, Fpdm = 128*Fpcm = 128*sample_rate 200 * If the pdm receiver do not care the pdm serial clock, it's recommended set Fpdm = 128*48000. 201 * Otherwise, the second configuration should be applied. 202 */ 203 typedef struct { 204 int sample_rate; /*!< I2S PDM sample rate */ 205 int fp; /*!< I2S PDM TX up-sampling parameter. Normally it should be set to 960 */ 206 int fs; /*!< I2S PDM TX up-sampling parameter. When it is set to 480, the pdm clock frequency Fpdm = 128 * sample_rate, when it is set to sample_rate / 100， Fpdm will be fixed to 128*48000 */ 207 } i2s_pdm_tx_upsample_cfg_t; 208 #endif 209 210 211 /** 212 * @brief I2S driver configuration parameters 213 * 214 */ 215 typedef struct { 216 217 i2s_mode_t mode; /*!< I2S work mode */ 218 uint32_t sample_rate; /*!< I2S sample rate */ 219 i2s_bits_per_sample_t bits_per_sample; /*!< I2S sample bits in one channel */ 220 i2s_channel_fmt_t channel_format; /*!< I2S channel format.*/ 221 i2s_comm_format_t communication_format; /*!< I2S communication format */ 222 int intr_alloc_flags; /*!< Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info */ 223 union { 224 int dma_desc_num; /*!< The total number of descriptors used by I2S DMA to receive/transmit data */ 225 int dma_buf_count __attribute__((deprecated)); /*!< This is an alias to 'dma_desc_num' for backward compatibility */ 226 }; 227 union { 228 int dma_frame_num; /*!< Frame number for one-time sampling. Frame here means the total data from all the channels in a WS cycle */ 229 int dma_buf_len __attribute__((deprecated)); /*!< This is an alias to 'dma_frame_num' for backward compatibility */ 230 }; 231 bool use_apll; /*!< I2S using APLL as main I2S clock, enable it to get accurate clock */ 232 bool tx_desc_auto_clear; /*!< I2S auto clear tx descriptor if there is underflow condition (helps in avoiding noise in case of data unavailability) */ 233 int fixed_mclk; /*!< I2S using fixed MCLK output. If use_apll = true and fixed_mclk > 0, then the clock output for i2s is fixed and equal to the fixed_mclk value. If fixed_mclk set, mclk_multiple won't take effect */ 234 i2s_mclk_multiple_t mclk_multiple; /*!< The multiple of I2S master clock(MCLK) to sample rate */ 235 i2s_bits_per_chan_t bits_per_chan; /*!< I2S total bits in one channel， only take effect when larger than 'bits_per_sample', default '0' means equal to 'bits_per_sample' */ 236 237 #if SOC_I2S_SUPPORTS_TDM 238 i2s_channel_t chan_mask; /*!< I2S active channel bit mask, set value in `i2s_channel_t` to enable specific channel, the bit map of active channel can not exceed (0x1<<total_chan). */ 239 uint32_t total_chan; /*!< I2S Total number of channels. If it is smaller than the biggest active channel number, it will be set to this number automatically. */ 240 bool left_align; /*!< Set to enable left alignment */ 241 bool big_edin; /*!< Set to enable big endian */ 242 bool bit_order_msb; /*!< Set to enable msb order */ 243 bool skip_msk; /*!< Set to enable skip mask. If it is enabled, only the data of the enabled channels will be sent, otherwise all data stored in DMA TX buffer will be sent */ 244 #endif // SOC_I2S_SUPPORTS_TDM 245 246 } i2s_driver_config_t; 247 248 typedef i2s_driver_config_t i2s_config_t; // for backward compatible 249 250 #ifdef __cplusplus 251 } 252 #endif 253
