1 /*
2 * Copyright (c) 2015, Freescale Semiconductor, Inc.
3 * Copyright 2016-2022 NXP
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 */
8
9 #ifndef _FSL_SAI_H_
10 #define _FSL_SAI_H_
11
12 #include "fsl_common.h"
13
14 /*!
15 * @addtogroup sai_driver SAI Driver
16 * @{
17 */
18
19 /*******************************************************************************
20 * Definitions
21 ******************************************************************************/
22
23 /*! @name Driver version */
24 /*@{*/
25 #define FSL_SAI_DRIVER_VERSION (MAKE_VERSION(2, 3, 8)) /*!< Version 2.3.8 */
26 /*@}*/
27
28 /*! @brief _sai_status_t, SAI return status.*/
29 enum
30 {
31 kStatus_SAI_TxBusy = MAKE_STATUS(kStatusGroup_SAI, 0), /*!< SAI Tx is busy. */
32 kStatus_SAI_RxBusy = MAKE_STATUS(kStatusGroup_SAI, 1), /*!< SAI Rx is busy. */
33 kStatus_SAI_TxError = MAKE_STATUS(kStatusGroup_SAI, 2), /*!< SAI Tx FIFO error. */
34 kStatus_SAI_RxError = MAKE_STATUS(kStatusGroup_SAI, 3), /*!< SAI Rx FIFO error. */
35 kStatus_SAI_QueueFull = MAKE_STATUS(kStatusGroup_SAI, 4), /*!< SAI transfer queue is full. */
36 kStatus_SAI_TxIdle = MAKE_STATUS(kStatusGroup_SAI, 5), /*!< SAI Tx is idle */
37 kStatus_SAI_RxIdle = MAKE_STATUS(kStatusGroup_SAI, 6) /*!< SAI Rx is idle */
38 };
39
40 /*! @brief _sai_channel_mask,.sai channel mask value, actual channel numbers is depend soc specific */
41 enum
42 {
43 kSAI_Channel0Mask = 1 << 0U, /*!< channel 0 mask value */
44 kSAI_Channel1Mask = 1 << 1U, /*!< channel 1 mask value */
45 kSAI_Channel2Mask = 1 << 2U, /*!< channel 2 mask value */
46 kSAI_Channel3Mask = 1 << 3U, /*!< channel 3 mask value */
47 kSAI_Channel4Mask = 1 << 4U, /*!< channel 4 mask value */
48 kSAI_Channel5Mask = 1 << 5U, /*!< channel 5 mask value */
49 kSAI_Channel6Mask = 1 << 6U, /*!< channel 6 mask value */
50 kSAI_Channel7Mask = 1 << 7U, /*!< channel 7 mask value */
51 };
52
53 /*! @brief Define the SAI bus type */
54 typedef enum _sai_protocol
55 {
56 kSAI_BusLeftJustified = 0x0U, /*!< Uses left justified format.*/
57 kSAI_BusRightJustified, /*!< Uses right justified format. */
58 kSAI_BusI2S, /*!< Uses I2S format. */
59 kSAI_BusPCMA, /*!< Uses I2S PCM A format.*/
60 kSAI_BusPCMB /*!< Uses I2S PCM B format. */
61 } sai_protocol_t;
62
63 /*! @brief Master or slave mode */
64 typedef enum _sai_master_slave
65 {
66 kSAI_Master = 0x0U, /*!< Master mode include bclk and frame sync */
67 kSAI_Slave = 0x1U, /*!< Slave mode include bclk and frame sync */
68 kSAI_Bclk_Master_FrameSync_Slave = 0x2U, /*!< bclk in master mode, frame sync in slave mode */
69 kSAI_Bclk_Slave_FrameSync_Master = 0x3U, /*!< bclk in slave mode, frame sync in master mode */
70 } sai_master_slave_t;
71
72 /*! @brief Mono or stereo audio format */
73 typedef enum _sai_mono_stereo
74 {
75 kSAI_Stereo = 0x0U, /*!< Stereo sound. */
76 kSAI_MonoRight, /*!< Only Right channel have sound. */
77 kSAI_MonoLeft /*!< Only left channel have sound. */
78 } sai_mono_stereo_t;
79
80 /*! @brief SAI data order, MSB or LSB */
81 typedef enum _sai_data_order
82 {
83 kSAI_DataLSB = 0x0U, /*!< LSB bit transferred first */
84 kSAI_DataMSB /*!< MSB bit transferred first */
85 } sai_data_order_t;
86
87 /*! @brief SAI clock polarity, active high or low */
88 typedef enum _sai_clock_polarity
89 {
90 kSAI_PolarityActiveHigh = 0x0U, /*!< Drive outputs on rising edge */
91 kSAI_PolarityActiveLow = 0x1U, /*!< Drive outputs on falling edge */
92 kSAI_SampleOnFallingEdge = 0x0U, /*!< Sample inputs on falling edge */
93 kSAI_SampleOnRisingEdge = 0x1U, /*!< Sample inputs on rising edge */
94 } sai_clock_polarity_t;
95
96 /*! @brief Synchronous or asynchronous mode */
97 typedef enum _sai_sync_mode
98 {
99 kSAI_ModeAsync = 0x0U, /*!< Asynchronous mode */
100 kSAI_ModeSync, /*!< Synchronous mode (with receiver or transmit) */
101 #if defined(FSL_FEATURE_SAI_HAS_SYNC_WITH_ANOTHER_SAI) && (FSL_FEATURE_SAI_HAS_SYNC_WITH_ANOTHER_SAI)
102 kSAI_ModeSyncWithOtherTx, /*!< Synchronous with another SAI transmit */
103 kSAI_ModeSyncWithOtherRx /*!< Synchronous with another SAI receiver */
104 #endif /* FSL_FEATURE_SAI_HAS_SYNC_WITH_ANOTHER_SAI */
105 } sai_sync_mode_t;
106
107 #if !(defined(FSL_FEATURE_SAI_HAS_NO_MCR_MICS) && (FSL_FEATURE_SAI_HAS_NO_MCR_MICS))
108 /*! @brief Mater clock source */
109 typedef enum _sai_mclk_source
110 {
111 kSAI_MclkSourceSysclk = 0x0U, /*!< Master clock from the system clock */
112 kSAI_MclkSourceSelect1, /*!< Master clock from source 1 */
113 kSAI_MclkSourceSelect2, /*!< Master clock from source 2 */
114 kSAI_MclkSourceSelect3 /*!< Master clock from source 3 */
115 } sai_mclk_source_t;
116 #endif
117
118 /*! @brief Bit clock source */
119 typedef enum _sai_bclk_source
120 {
121 kSAI_BclkSourceBusclk = 0x0U, /*!< Bit clock using bus clock */
122 /* General device bit source definition */
123 kSAI_BclkSourceMclkOption1 = 0x1U, /*!< Bit clock MCLK option 1 */
124 kSAI_BclkSourceMclkOption2 = 0x2U, /*!< Bit clock MCLK option2 */
125 kSAI_BclkSourceMclkOption3 = 0x3U, /*!< Bit clock MCLK option3 */
126 /* Kinetis device bit clock source definition */
127 kSAI_BclkSourceMclkDiv = 0x1U, /*!< Bit clock using master clock divider */
128 kSAI_BclkSourceOtherSai0 = 0x2U, /*!< Bit clock from other SAI device */
129 kSAI_BclkSourceOtherSai1 = 0x3U /*!< Bit clock from other SAI device */
130 } sai_bclk_source_t;
131
132 /*! @brief _sai_interrupt_enable_t, The SAI interrupt enable flag */
133 enum
134 {
135 kSAI_WordStartInterruptEnable =
136 I2S_TCSR_WSIE_MASK, /*!< Word start flag, means the first word in a frame detected */
137 kSAI_SyncErrorInterruptEnable = I2S_TCSR_SEIE_MASK, /*!< Sync error flag, means the sync error is detected */
138 kSAI_FIFOWarningInterruptEnable = I2S_TCSR_FWIE_MASK, /*!< FIFO warning flag, means the FIFO is empty */
139 kSAI_FIFOErrorInterruptEnable = I2S_TCSR_FEIE_MASK, /*!< FIFO error flag */
140 #if defined(FSL_FEATURE_SAI_HAS_FIFO) && (FSL_FEATURE_SAI_HAS_FIFO)
141 kSAI_FIFORequestInterruptEnable = I2S_TCSR_FRIE_MASK, /*!< FIFO request, means reached watermark */
142 #endif /* FSL_FEATURE_SAI_HAS_FIFO */
143 };
144
145 /*! @brief _sai_dma_enable_t, The DMA request sources */
146 enum
147 {
148 kSAI_FIFOWarningDMAEnable = I2S_TCSR_FWDE_MASK, /*!< FIFO warning caused by the DMA request */
149 #if defined(FSL_FEATURE_SAI_HAS_FIFO) && (FSL_FEATURE_SAI_HAS_FIFO)
150 kSAI_FIFORequestDMAEnable = I2S_TCSR_FRDE_MASK, /*!< FIFO request caused by the DMA request */
151 #endif /* FSL_FEATURE_SAI_HAS_FIFO */
152 };
153
154 /*! @brief _sai_flags, The SAI status flag */
155 enum
156 {
157 kSAI_WordStartFlag = I2S_TCSR_WSF_MASK, /*!< Word start flag, means the first word in a frame detected */
158 kSAI_SyncErrorFlag = I2S_TCSR_SEF_MASK, /*!< Sync error flag, means the sync error is detected */
159 kSAI_FIFOErrorFlag = I2S_TCSR_FEF_MASK, /*!< FIFO error flag */
160 #if defined(FSL_FEATURE_SAI_HAS_FIFO) && (FSL_FEATURE_SAI_HAS_FIFO)
161 kSAI_FIFORequestFlag = I2S_TCSR_FRF_MASK, /*!< FIFO request flag. */
162 #endif /* FSL_FEATURE_SAI_HAS_FIFO */
163 kSAI_FIFOWarningFlag = I2S_TCSR_FWF_MASK, /*!< FIFO warning flag */
164 };
165
166 /*! @brief The reset type */
167 typedef enum _sai_reset_type
168 {
169 kSAI_ResetTypeSoftware = I2S_TCSR_SR_MASK, /*!< Software reset, reset the logic state */
170 kSAI_ResetTypeFIFO = I2S_TCSR_FR_MASK, /*!< FIFO reset, reset the FIFO read and write pointer */
171 kSAI_ResetAll = I2S_TCSR_SR_MASK | I2S_TCSR_FR_MASK /*!< All reset. */
172 } sai_reset_type_t;
173
174 #if defined(FSL_FEATURE_SAI_HAS_FIFO_PACKING) && FSL_FEATURE_SAI_HAS_FIFO_PACKING
175 /*!
176 * @brief The SAI packing mode
177 * The mode includes 8 bit and 16 bit packing.
178 */
179 typedef enum _sai_fifo_packing
180 {
181 kSAI_FifoPackingDisabled = 0x0U, /*!< Packing disabled */
182 kSAI_FifoPacking8bit = 0x2U, /*!< 8 bit packing enabled */
183 kSAI_FifoPacking16bit = 0x3U /*!< 16bit packing enabled */
184 } sai_fifo_packing_t;
185 #endif /* FSL_FEATURE_SAI_HAS_FIFO_PACKING */
186
187 /*! @brief SAI user configuration structure */
188 typedef struct _sai_config
189 {
190 sai_protocol_t protocol; /*!< Audio bus protocol in SAI */
191 sai_sync_mode_t syncMode; /*!< SAI sync mode, control Tx/Rx clock sync */
192 #if defined(FSL_FEATURE_SAI_HAS_MCR) && (FSL_FEATURE_SAI_HAS_MCR)
193 bool mclkOutputEnable; /*!< Master clock output enable, true means master clock divider enabled */
194 #if !(defined(FSL_FEATURE_SAI_HAS_NO_MCR_MICS) && (FSL_FEATURE_SAI_HAS_NO_MCR_MICS))
195 sai_mclk_source_t mclkSource; /*!< Master Clock source */
196 #endif /* FSL_FEATURE_SAI_HAS_MCR */
197 #endif
198 sai_bclk_source_t bclkSource; /*!< Bit Clock source */
199 sai_master_slave_t masterSlave; /*!< Master or slave */
200 } sai_config_t;
201
202 #ifndef SAI_XFER_QUEUE_SIZE
203 /*!@brief SAI transfer queue size, user can refine it according to use case. */
204 #define SAI_XFER_QUEUE_SIZE (4U)
205 #endif
206
207 /*! @brief Audio sample rate */
208 typedef enum _sai_sample_rate
209 {
210 kSAI_SampleRate8KHz = 8000U, /*!< Sample rate 8000 Hz */
211 kSAI_SampleRate11025Hz = 11025U, /*!< Sample rate 11025 Hz */
212 kSAI_SampleRate12KHz = 12000U, /*!< Sample rate 12000 Hz */
213 kSAI_SampleRate16KHz = 16000U, /*!< Sample rate 16000 Hz */
214 kSAI_SampleRate22050Hz = 22050U, /*!< Sample rate 22050 Hz */
215 kSAI_SampleRate24KHz = 24000U, /*!< Sample rate 24000 Hz */
216 kSAI_SampleRate32KHz = 32000U, /*!< Sample rate 32000 Hz */
217 kSAI_SampleRate44100Hz = 44100U, /*!< Sample rate 44100 Hz */
218 kSAI_SampleRate48KHz = 48000U, /*!< Sample rate 48000 Hz */
219 kSAI_SampleRate96KHz = 96000U, /*!< Sample rate 96000 Hz */
220 kSAI_SampleRate192KHz = 192000U, /*!< Sample rate 192000 Hz */
221 kSAI_SampleRate384KHz = 384000U, /*!< Sample rate 384000 Hz */
222 } sai_sample_rate_t;
223
224 /*! @brief Audio word width */
225 typedef enum _sai_word_width
226 {
227 kSAI_WordWidth8bits = 8U, /*!< Audio data width 8 bits */
228 kSAI_WordWidth16bits = 16U, /*!< Audio data width 16 bits */
229 kSAI_WordWidth24bits = 24U, /*!< Audio data width 24 bits */
230 kSAI_WordWidth32bits = 32U /*!< Audio data width 32 bits */
231 } sai_word_width_t;
232
233 #if defined(FSL_FEATURE_SAI_HAS_CHANNEL_MODE) && FSL_FEATURE_SAI_HAS_CHANNEL_MODE
234 /*! @brief sai data pin state definition */
235 typedef enum _sai_data_pin_state
236 {
237 kSAI_DataPinStateTriState =
238 0U, /*!< transmit data pins are tri-stated when slots are masked or channels are disabled */
239 kSAI_DataPinStateOutputZero = 1U, /*!< transmit data pins are never tri-stated and will output zero when slots
240 are masked or channel disabled */
241 } sai_data_pin_state_t;
242 #endif
243
244 #if defined(FSL_FEATURE_SAI_HAS_FIFO_COMBINE_MODE) && FSL_FEATURE_SAI_HAS_FIFO_COMBINE_MODE
245 /*! @brief sai fifo combine mode definition */
246 typedef enum _sai_fifo_combine
247 {
248 kSAI_FifoCombineDisabled = 0U, /*!< sai fifo combine mode disabled */
249 kSAI_FifoCombineModeEnabledOnRead, /*!< sai fifo combine mode enabled on FIFO reads */
250 kSAI_FifoCombineModeEnabledOnWrite, /*!< sai fifo combine mode enabled on FIFO write */
251 kSAI_FifoCombineModeEnabledOnReadWrite, /*!< sai fifo combined mode enabled on FIFO read/writes */
252 } sai_fifo_combine_t;
253 #endif
254
255 /*! @brief sai transceiver type */
256 typedef enum _sai_transceiver_type
257 {
258 kSAI_Transmitter = 0U, /*!< sai transmitter */
259 kSAI_Receiver = 1U, /*!< sai receiver */
260 } sai_transceiver_type_t;
261
262 /*! @brief sai frame sync len */
263 typedef enum _sai_frame_sync_len
264 {
265 kSAI_FrameSyncLenOneBitClk = 0U, /*!< 1 bit clock frame sync len for DSP mode */
266 kSAI_FrameSyncLenPerWordWidth = 1U, /*!< Frame sync length decided by word width */
267 } sai_frame_sync_len_t;
268
269 /*! @brief sai transfer format */
270 typedef struct _sai_transfer_format
271 {
272 uint32_t sampleRate_Hz; /*!< Sample rate of audio data */
273 uint32_t bitWidth; /*!< Data length of audio data, usually 8/16/24/32 bits */
274 sai_mono_stereo_t stereo; /*!< Mono or stereo */
275 #if defined(FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER) && (FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER)
276 uint32_t masterClockHz; /*!< Master clock frequency in Hz */
277 #endif /* FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER */
278 #if defined(FSL_FEATURE_SAI_HAS_FIFO) && (FSL_FEATURE_SAI_HAS_FIFO)
279 uint8_t watermark; /*!< Watermark value */
280 #endif /* FSL_FEATURE_SAI_HAS_FIFO */
281
282 /* for the multi channel usage, user can provide channelMask Oonly, then sai driver will handle
283 * other parameter carefully, such as
284 * channelMask = kSAI_Channel0Mask | kSAI_Channel1Mask | kSAI_Channel4Mask
285 * then in SAI_RxSetFormat/SAI_TxSetFormat function, channel/endChannel/channelNums will be calculated.
286 * for the single channel usage, user can provide channel or channel mask only, such as,
287 * channel = 0 or channelMask = kSAI_Channel0Mask.
288 */
289 uint8_t channel; /*!< Transfer start channel */
290 uint8_t channelMask; /*!< enabled channel mask value, reference _sai_channel_mask */
291 uint8_t endChannel; /*!< end channel number */
292 uint8_t channelNums; /*!< Total enabled channel numbers */
293
294 sai_protocol_t protocol; /*!< Which audio protocol used */
295 bool isFrameSyncCompact; /*!< True means Frame sync length is configurable according to bitWidth, false means frame
296 sync length is 64 times of bit clock. */
297 } sai_transfer_format_t;
298
299 #if (defined(FSL_FEATURE_SAI_HAS_MCR) && (FSL_FEATURE_SAI_HAS_MCR)) || \
300 (defined(FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER) && (FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER))
301 /*! @brief master clock configurations */
302 typedef struct _sai_master_clock
303 {
304 #if defined(FSL_FEATURE_SAI_HAS_MCR) && (FSL_FEATURE_SAI_HAS_MCR)
305 bool mclkOutputEnable; /*!< master clock output enable */
306 #if !(defined(FSL_FEATURE_SAI_HAS_NO_MCR_MICS) && (FSL_FEATURE_SAI_HAS_NO_MCR_MICS))
307 sai_mclk_source_t mclkSource; /*!< Master Clock source */
308 #endif
309 #endif
310
311 #if (defined(FSL_FEATURE_SAI_HAS_MCR) && (FSL_FEATURE_SAI_HAS_MCR)) || \
312 (defined(FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER) && (FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER))
313 uint32_t mclkHz; /*!< target mclk frequency */
314 uint32_t mclkSourceClkHz; /*!< mclk source frequency*/
315 #endif
316 } sai_master_clock_t;
317 #endif
318
319 /*! @brief sai fifo feature*/
320 #if (defined(FSL_FEATURE_SAI_HAS_FIFO_FUNCTION_AFTER_ERROR) && FSL_FEATURE_SAI_HAS_FIFO_FUNCTION_AFTER_ERROR) || \
321 (defined(FSL_FEATURE_SAI_HAS_FIFO_COMBINE_MODE) && FSL_FEATURE_SAI_HAS_FIFO_COMBINE_MODE) || \
322 (defined(FSL_FEATURE_SAI_HAS_FIFO_PACKING) && FSL_FEATURE_SAI_HAS_FIFO_PACKING) || \
323 (defined(FSL_FEATURE_SAI_HAS_FIFO) && (FSL_FEATURE_SAI_HAS_FIFO))
324 #define FSL_SAI_HAS_FIFO_EXTEND_FEATURE 1
325 #else
326 #define FSL_SAI_HAS_FIFO_EXTEND_FEATURE 0
327 #endif
328
329 #if FSL_SAI_HAS_FIFO_EXTEND_FEATURE
330 /*! @brief sai fifo configurations */
331 typedef struct _sai_fifo
332 {
333 #if defined(FSL_FEATURE_SAI_HAS_FIFO_FUNCTION_AFTER_ERROR) && FSL_FEATURE_SAI_HAS_FIFO_FUNCTION_AFTER_ERROR
334 bool fifoContinueOneError; /*!< fifo continues when error occur */
335 #endif
336
337 #if defined(FSL_FEATURE_SAI_HAS_FIFO_COMBINE_MODE) && FSL_FEATURE_SAI_HAS_FIFO_COMBINE_MODE
338 sai_fifo_combine_t fifoCombine; /*!< fifo combine mode */
339 #endif
340
341 #if defined(FSL_FEATURE_SAI_HAS_FIFO_PACKING) && FSL_FEATURE_SAI_HAS_FIFO_PACKING
342 sai_fifo_packing_t fifoPacking; /*!< fifo packing mode */
343 #endif
344 #if defined(FSL_FEATURE_SAI_HAS_FIFO) && (FSL_FEATURE_SAI_HAS_FIFO)
345 uint8_t fifoWatermark; /*!< fifo watermark */
346 #endif
347 } sai_fifo_t;
348 #endif
349
350 /*! @brief sai bit clock configurations */
351 typedef struct _sai_bit_clock
352 {
353 bool bclkSrcSwap; /*!< bit clock source swap */
354 bool bclkInputDelay; /*!< bit clock actually used by the transmitter is delayed by the pad output delay,
355 this has effect of decreasing the data input setup time, but increasing the data output valid
356 time .*/
357 sai_clock_polarity_t bclkPolarity; /*!< bit clock polarity */
358 sai_bclk_source_t bclkSource; /*!< bit Clock source */
359 } sai_bit_clock_t;
360
361 /*! @brief sai frame sync configurations */
362 typedef struct _sai_frame_sync
363 {
364 uint8_t frameSyncWidth; /*!< frame sync width in number of bit clocks */
365 bool frameSyncEarly; /*!< TRUE is frame sync assert one bit before the first bit of frame
366 FALSE is frame sync assert with the first bit of the frame */
367
368 #if defined(FSL_FEATURE_SAI_HAS_ON_DEMAND_MODE) && FSL_FEATURE_SAI_HAS_ON_DEMAND_MODE
369 bool frameSyncGenerateOnDemand; /*!< internal frame sync is generated when FIFO waring flag is clear */
370 #endif
371
372 sai_clock_polarity_t frameSyncPolarity; /*!< frame sync polarity */
373
374 } sai_frame_sync_t;
375
376 /*! @brief sai serial data configurations */
377 typedef struct _sai_serial_data
378 {
379 #if defined(FSL_FEATURE_SAI_HAS_CHANNEL_MODE) && FSL_FEATURE_SAI_HAS_CHANNEL_MODE
380 sai_data_pin_state_t dataMode; /*!< sai data pin state when slots masked or channel disabled */
381 #endif
382
383 sai_data_order_t dataOrder; /*!< configure whether the LSB or MSB is transmitted first */
384 uint8_t dataWord0Length; /*!< configure the number of bits in the first word in each frame */
385 uint8_t dataWordNLength; /*!< configure the number of bits in the each word in each frame, except the first word */
386 uint8_t dataWordLength; /*!< used to record the data length for dma transfer */
387 uint8_t
388 dataFirstBitShifted; /*!< Configure the bit index for the first bit transmitted for each word in the frame */
389 uint8_t dataWordNum; /*!< configure the number of words in each frame */
390 uint32_t dataMaskedWord; /*!< configure whether the transmit word is masked */
391 } sai_serial_data_t;
392
393 /*! @brief sai transceiver configurations */
394 typedef struct _sai_transceiver
395 {
396 sai_serial_data_t serialData; /*!< serial data configurations */
397 sai_frame_sync_t frameSync; /*!< ws configurations */
398 sai_bit_clock_t bitClock; /*!< bit clock configurations */
399 #if FSL_SAI_HAS_FIFO_EXTEND_FEATURE
400 sai_fifo_t fifo; /*!< fifo configurations */
401 #endif
402 sai_master_slave_t masterSlave; /*!< transceiver is master or slave */
403
404 sai_sync_mode_t syncMode; /*!< transceiver sync mode */
405
406 uint8_t startChannel; /*!< Transfer start channel */
407 uint8_t channelMask; /*!< enabled channel mask value, reference _sai_channel_mask */
408 uint8_t endChannel; /*!< end channel number */
409 uint8_t channelNums; /*!< Total enabled channel numbers */
410
411 } sai_transceiver_t;
412
413 /*! @brief SAI transfer structure */
414 typedef struct _sai_transfer
415 {
416 uint8_t *data; /*!< Data start address to transfer. */
417 size_t dataSize; /*!< Transfer size. */
418 } sai_transfer_t;
419
420 typedef struct _sai_handle sai_handle_t;
421
422 /*! @brief SAI transfer callback prototype */
423 typedef void (*sai_transfer_callback_t)(I2S_Type *base, sai_handle_t *handle, status_t status, void *userData);
424
425 /*! @brief SAI handle structure */
426 struct _sai_handle
427 {
428 I2S_Type *base; /*!< base address */
429
430 uint32_t state; /*!< Transfer status */
431 sai_transfer_callback_t callback; /*!< Callback function called at transfer event*/
432 void *userData; /*!< Callback parameter passed to callback function*/
433 uint8_t bitWidth; /*!< Bit width for transfer, 8/16/24/32 bits */
434
435 /* for the multi channel usage, user can provide channelMask Oonly, then sai driver will handle
436 * other parameter carefully, such as
437 * channelMask = kSAI_Channel0Mask | kSAI_Channel1Mask | kSAI_Channel4Mask
438 * then in SAI_RxSetFormat/SAI_TxSetFormat function, channel/endChannel/channelNums will be calculated.
439 * for the single channel usage, user can provide channel or channel mask only, such as,
440 * channel = 0 or channelMask = kSAI_Channel0Mask.
441 */
442 uint8_t channel; /*!< Transfer start channel */
443 uint8_t channelMask; /*!< enabled channel mask value, refernece _sai_channel_mask */
444 uint8_t endChannel; /*!< end channel number */
445 uint8_t channelNums; /*!< Total enabled channel numbers */
446
447 sai_transfer_t saiQueue[SAI_XFER_QUEUE_SIZE]; /*!< Transfer queue storing queued transfer */
448 size_t transferSize[SAI_XFER_QUEUE_SIZE]; /*!< Data bytes need to transfer */
449 volatile uint8_t queueUser; /*!< Index for user to queue transfer */
450 volatile uint8_t queueDriver; /*!< Index for driver to get the transfer data and size */
451 #if defined(FSL_FEATURE_SAI_HAS_FIFO) && (FSL_FEATURE_SAI_HAS_FIFO)
452 uint8_t watermark; /*!< Watermark value */
453 #endif
454 };
455
456 /*******************************************************************************
457 * API
458 ******************************************************************************/
459
460 #if defined(__cplusplus)
461 extern "C" {
462 #endif /*_cplusplus*/
463
464 /*!
465 * @name Initialization and deinitialization
466 * @{
467 */
468
469 /*!
470 * @brief Initializes the SAI Tx peripheral.
471 * @deprecated Do not use this function. It has been superceded by @ref SAI_Init
472 *
473 * Ungates the SAI clock, resets the module, and configures SAI Tx with a configuration structure.
474 * The configuration structure can be custom filled or set with default values by
475 * SAI_TxGetDefaultConfig().
476 *
477 * @note This API should be called at the beginning of the application to use
478 * the SAI driver. Otherwise, accessing the SAIM module can cause a hard fault
479 * because the clock is not enabled.
480 *
481 * @param base SAI base pointer
482 * @param config SAI configuration structure.
483 */
484 void SAI_TxInit(I2S_Type *base, const sai_config_t *config);
485
486 /*!
487 * @brief Initializes the SAI Rx peripheral.
488 * @deprecated Do not use this function. It has been superceded by @ref SAI_Init
489 *
490 * Ungates the SAI clock, resets the module, and configures the SAI Rx with a configuration structure.
491 * The configuration structure can be custom filled or set with default values by
492 * SAI_RxGetDefaultConfig().
493 *
494 * @note This API should be called at the beginning of the application to use
495 * the SAI driver. Otherwise, accessing the SAI module can cause a hard fault
496 * because the clock is not enabled.
497 *
498 * @param base SAI base pointer
499 * @param config SAI configuration structure.
500 */
501 void SAI_RxInit(I2S_Type *base, const sai_config_t *config);
502
503 /*!
504 * @brief Sets the SAI Tx configuration structure to default values.
505 * @deprecated Do not use this function. It has been superceded by
506 * @ref SAI_GetClassicI2SConfig, @ref SAI_GetLeftJustifiedConfig , @ref SAI_GetRightJustifiedConfig, @ref
507 SAI_GetDSPConfig, @ref SAI_GetTDMConfig
508 *
509 * This API initializes the configuration structure for use in SAI_TxConfig().
510 * The initialized structure can remain unchanged in SAI_TxConfig(), or it can be modified
511 * before calling SAI_TxConfig().
512 * This is an example.
513 @code
514 sai_config_t config;
515 SAI_TxGetDefaultConfig(&config);
516 @endcode
517 *
518 * @param config pointer to master configuration structure
519 */
520 void SAI_TxGetDefaultConfig(sai_config_t *config);
521
522 /*!
523 * @brief Sets the SAI Rx configuration structure to default values.
524 * @deprecated Do not use this function. It has been superceded by
525 * @ref SAI_GetClassicI2SConfig, @ref SAI_GetLeftJustifiedConfig , @ref SAI_GetRightJustifiedConfig, @ref
526 SAI_GetDSPConfig, @ref SAI_GetTDMConfig
527 *
528 * This API initializes the configuration structure for use in SAI_RxConfig().
529 * The initialized structure can remain unchanged in SAI_RxConfig() or it can be modified
530 * before calling SAI_RxConfig().
531 * This is an example.
532 @code
533 sai_config_t config;
534 SAI_RxGetDefaultConfig(&config);
535 @endcode
536 *
537 * @param config pointer to master configuration structure
538 */
539 void SAI_RxGetDefaultConfig(sai_config_t *config);
540
541 /*!
542 * @brief Initializes the SAI peripheral.
543 *
544 * This API gates the SAI clock. The SAI module can't operate unless SAI_Init is called to enable the clock.
545 *
546 * @param base SAI base pointer.
547 */
548 void SAI_Init(I2S_Type *base);
549
550 /*!
551 * @brief De-initializes the SAI peripheral.
552 *
553 * This API gates the SAI clock. The SAI module can't operate unless SAI_TxInit
554 * or SAI_RxInit is called to enable the clock.
555 *
556 * @param base SAI base pointer.
557 */
558 void SAI_Deinit(I2S_Type *base);
559
560 /*!
561 * @brief Resets the SAI Tx.
562 *
563 * This function enables the software reset and FIFO reset of SAI Tx. After reset, clear the reset bit.
564 *
565 * @param base SAI base pointer
566 */
567 void SAI_TxReset(I2S_Type *base);
568
569 /*!
570 * @brief Resets the SAI Rx.
571 *
572 * This function enables the software reset and FIFO reset of SAI Rx. After reset, clear the reset bit.
573 *
574 * @param base SAI base pointer
575 */
576 void SAI_RxReset(I2S_Type *base);
577
578 /*!
579 * @brief Enables/disables the SAI Tx.
580 *
581 * @param base SAI base pointer.
582 * @param enable True means enable SAI Tx, false means disable.
583 */
584 void SAI_TxEnable(I2S_Type *base, bool enable);
585
586 /*!
587 * @brief Enables/disables the SAI Rx.
588 *
589 * @param base SAI base pointer.
590 * @param enable True means enable SAI Rx, false means disable.
591 */
592 void SAI_RxEnable(I2S_Type *base, bool enable);
593
594 /*!
595 * @brief Set Rx bit clock direction.
596 *
597 * Select bit clock direction, master or slave.
598 *
599 * @param base SAI base pointer.
600 * @param masterSlave reference sai_master_slave_t.
601 */
SAI_TxSetBitClockDirection(I2S_Type * base,sai_master_slave_t masterSlave)602 static inline void SAI_TxSetBitClockDirection(I2S_Type *base, sai_master_slave_t masterSlave)
603 {
604 if (masterSlave == kSAI_Master)
605 {
606 base->TCR2 |= I2S_TCR2_BCD_MASK;
607 }
608 else
609 {
610 base->TCR2 &= ~I2S_TCR2_BCD_MASK;
611 }
612 }
613
614 /*!
615 * @brief Set Rx bit clock direction.
616 *
617 * Select bit clock direction, master or slave.
618 *
619 * @param base SAI base pointer.
620 * @param masterSlave reference sai_master_slave_t.
621 */
SAI_RxSetBitClockDirection(I2S_Type * base,sai_master_slave_t masterSlave)622 static inline void SAI_RxSetBitClockDirection(I2S_Type *base, sai_master_slave_t masterSlave)
623 {
624 if (masterSlave == kSAI_Master)
625 {
626 base->RCR2 |= I2S_RCR2_BCD_MASK;
627 }
628 else
629 {
630 base->RCR2 &= ~I2S_RCR2_BCD_MASK;
631 }
632 }
633
634 /*!
635 * @brief Set Rx frame sync direction.
636 *
637 * Select frame sync direction, master or slave.
638 *
639 * @param base SAI base pointer.
640 * @param masterSlave reference sai_master_slave_t.
641 */
SAI_RxSetFrameSyncDirection(I2S_Type * base,sai_master_slave_t masterSlave)642 static inline void SAI_RxSetFrameSyncDirection(I2S_Type *base, sai_master_slave_t masterSlave)
643 {
644 if (masterSlave == kSAI_Master)
645 {
646 base->RCR4 |= I2S_RCR4_FSD_MASK;
647 }
648 else
649 {
650 base->RCR4 &= ~I2S_RCR4_FSD_MASK;
651 }
652 }
653
654 /*!
655 * @brief Set Tx frame sync direction.
656 *
657 * Select frame sync direction, master or slave.
658 *
659 * @param base SAI base pointer.
660 * @param masterSlave reference sai_master_slave_t.
661 */
SAI_TxSetFrameSyncDirection(I2S_Type * base,sai_master_slave_t masterSlave)662 static inline void SAI_TxSetFrameSyncDirection(I2S_Type *base, sai_master_slave_t masterSlave)
663 {
664 if (masterSlave == kSAI_Master)
665 {
666 base->TCR4 |= I2S_TCR4_FSD_MASK;
667 }
668 else
669 {
670 base->TCR4 &= ~I2S_TCR4_FSD_MASK;
671 }
672 }
673
674 /*!
675 * @brief Transmitter bit clock rate configurations.
676 *
677 * @param base SAI base pointer.
678 * @param sourceClockHz Bit clock source frequency.
679 * @param sampleRate Audio data sample rate.
680 * @param bitWidth Audio data bitWidth.
681 * @param channelNumbers Audio channel numbers.
682 */
683 void SAI_TxSetBitClockRate(
684 I2S_Type *base, uint32_t sourceClockHz, uint32_t sampleRate, uint32_t bitWidth, uint32_t channelNumbers);
685
686 /*!
687 * @brief Receiver bit clock rate configurations.
688 *
689 * @param base SAI base pointer.
690 * @param sourceClockHz Bit clock source frequency.
691 * @param sampleRate Audio data sample rate.
692 * @param bitWidth Audio data bitWidth.
693 * @param channelNumbers Audio channel numbers.
694 */
695 void SAI_RxSetBitClockRate(
696 I2S_Type *base, uint32_t sourceClockHz, uint32_t sampleRate, uint32_t bitWidth, uint32_t channelNumbers);
697
698 /*!
699 * @brief Transmitter Bit clock configurations.
700 *
701 * @param base SAI base pointer.
702 * @param masterSlave master or slave.
703 * @param config bit clock other configurations, can be NULL in slave mode.
704 */
705 void SAI_TxSetBitclockConfig(I2S_Type *base, sai_master_slave_t masterSlave, sai_bit_clock_t *config);
706
707 /*!
708 * @brief Receiver Bit clock configurations.
709 *
710 * @param base SAI base pointer.
711 * @param masterSlave master or slave.
712 * @param config bit clock other configurations, can be NULL in slave mode.
713 */
714 void SAI_RxSetBitclockConfig(I2S_Type *base, sai_master_slave_t masterSlave, sai_bit_clock_t *config);
715
716 #if (defined(FSL_FEATURE_SAI_HAS_MCR) && (FSL_FEATURE_SAI_HAS_MCR)) || \
717 (defined(FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER) && (FSL_FEATURE_SAI_HAS_MCLKDIV_REGISTER))
718 /*!
719 * @brief Master clock configurations.
720 *
721 * @param base SAI base pointer.
722 * @param config master clock configurations.
723 */
724 void SAI_SetMasterClockConfig(I2S_Type *base, sai_master_clock_t *config);
725 #endif
726
727 #if FSL_SAI_HAS_FIFO_EXTEND_FEATURE
728 /*!
729 * @brief SAI transmitter fifo configurations.
730 *
731 * @param base SAI base pointer.
732 * @param config fifo configurations.
733 */
734 void SAI_TxSetFifoConfig(I2S_Type *base, sai_fifo_t *config);
735
736 /*!
737 * @brief SAI receiver fifo configurations.
738 *
739 * @param base SAI base pointer.
740 * @param config fifo configurations.
741 */
742 void SAI_RxSetFifoConfig(I2S_Type *base, sai_fifo_t *config);
743 #endif
744
745 /*!
746 * @brief SAI transmitter Frame sync configurations.
747 *
748 * @param base SAI base pointer.
749 * @param masterSlave master or slave.
750 * @param config frame sync configurations, can be NULL in slave mode.
751 */
752 void SAI_TxSetFrameSyncConfig(I2S_Type *base, sai_master_slave_t masterSlave, sai_frame_sync_t *config);
753
754 /*!
755 * @brief SAI receiver Frame sync configurations.
756 *
757 * @param base SAI base pointer.
758 * @param masterSlave master or slave.
759 * @param config frame sync configurations, can be NULL in slave mode.
760 */
761 void SAI_RxSetFrameSyncConfig(I2S_Type *base, sai_master_slave_t masterSlave, sai_frame_sync_t *config);
762
763 /*!
764 * @brief SAI transmitter Serial data configurations.
765 *
766 * @param base SAI base pointer.
767 * @param config serial data configurations.
768 */
769 void SAI_TxSetSerialDataConfig(I2S_Type *base, sai_serial_data_t *config);
770
771 /*!
772 * @brief SAI receiver Serial data configurations.
773 *
774 * @param base SAI base pointer.
775 * @param config serial data configurations.
776 */
777 void SAI_RxSetSerialDataConfig(I2S_Type *base, sai_serial_data_t *config);
778
779 /*!
780 * @brief SAI transmitter configurations.
781 *
782 * @param base SAI base pointer.
783 * @param config transmitter configurations.
784 */
785 void SAI_TxSetConfig(I2S_Type *base, sai_transceiver_t *config);
786
787 /*!
788 * @brief SAI receiver configurations.
789 *
790 * @param base SAI base pointer.
791 * @param config receiver configurations.
792 */
793 void SAI_RxSetConfig(I2S_Type *base, sai_transceiver_t *config);
794
795 /*!
796 * @brief Get classic I2S mode configurations.
797 *
798 * @param config transceiver configurations.
799 * @param bitWidth audio data bitWidth.
800 * @param mode audio data channel.
801 * @param saiChannelMask mask value of the channel to be enable.
802 */
803 void SAI_GetClassicI2SConfig(sai_transceiver_t *config,
804 sai_word_width_t bitWidth,
805 sai_mono_stereo_t mode,
806 uint32_t saiChannelMask);
807
808 /*!
809 * @brief Get left justified mode configurations.
810 *
811 * @param config transceiver configurations.
812 * @param bitWidth audio data bitWidth.
813 * @param mode audio data channel.
814 * @param saiChannelMask mask value of the channel to be enable.
815 */
816 void SAI_GetLeftJustifiedConfig(sai_transceiver_t *config,
817 sai_word_width_t bitWidth,
818 sai_mono_stereo_t mode,
819 uint32_t saiChannelMask);
820
821 /*!
822 * @brief Get right justified mode configurations.
823 *
824 * @param config transceiver configurations.
825 * @param bitWidth audio data bitWidth.
826 * @param mode audio data channel.
827 * @param saiChannelMask mask value of the channel to be enable.
828 */
829 void SAI_GetRightJustifiedConfig(sai_transceiver_t *config,
830 sai_word_width_t bitWidth,
831 sai_mono_stereo_t mode,
832 uint32_t saiChannelMask);
833
834 /*!
835 * @brief Get TDM mode configurations.
836 *
837 * @param config transceiver configurations.
838 * @param frameSyncWidth length of frame sync.
839 * @param bitWidth audio data word width.
840 * @param dataWordNum word number in one frame.
841 * @param saiChannelMask mask value of the channel to be enable.
842 */
843 void SAI_GetTDMConfig(sai_transceiver_t *config,
844 sai_frame_sync_len_t frameSyncWidth,
845 sai_word_width_t bitWidth,
846 uint32_t dataWordNum,
847 uint32_t saiChannelMask);
848
849 /*!
850 * @brief Get DSP mode configurations.
851 *
852 * @note DSP mode is also called PCM mode which support MODE A and MODE B,
853 * DSP/PCM MODE A configuration flow. RX is similiar but uses SAI_RxSetConfig instead of SAI_TxSetConfig:
854 * @code
855 * SAI_GetDSPConfig(config, kSAI_FrameSyncLenOneBitClk, bitWidth, kSAI_Stereo, channelMask)
856 * config->frameSync.frameSyncEarly = true;
857 * SAI_TxSetConfig(base, config)
858 * @endcode
859 *
860 * DSP/PCM MODE B configuration flow for TX. RX is similiar but uses SAI_RxSetConfig instead of SAI_TxSetConfig:
861 * @code
862 * SAI_GetDSPConfig(config, kSAI_FrameSyncLenOneBitClk, bitWidth, kSAI_Stereo, channelMask)
863 * SAI_TxSetConfig(base, config)
864 * @endcode
865 *
866 * @param config transceiver configurations.
867 * @param frameSyncWidth length of frame sync.
868 * @param bitWidth audio data bitWidth.
869 * @param mode audio data channel.
870 * @param saiChannelMask mask value of the channel to enable.
871 */
872 void SAI_GetDSPConfig(sai_transceiver_t *config,
873 sai_frame_sync_len_t frameSyncWidth,
874 sai_word_width_t bitWidth,
875 sai_mono_stereo_t mode,
876 uint32_t saiChannelMask);
877 /*! @} */
878
879 /*!
880 * @name Status
881 * @{
882 */
883
884 /*!
885 * @brief Gets the SAI Tx status flag state.
886 *
887 * @param base SAI base pointer
888 * @return SAI Tx status flag value. Use the Status Mask to get the status value needed.
889 */
SAI_TxGetStatusFlag(I2S_Type * base)890 static inline uint32_t SAI_TxGetStatusFlag(I2S_Type *base)
891 {
892 return base->TCSR;
893 }
894
895 /*!
896 * @brief Clears the SAI Tx status flag state.
897 *
898 * @param base SAI base pointer
899 * @param mask State mask. It can be a combination of the following source if defined:
900 * @arg kSAI_WordStartFlag
901 * @arg kSAI_SyncErrorFlag
902 * @arg kSAI_FIFOErrorFlag
903 */
SAI_TxClearStatusFlags(I2S_Type * base,uint32_t mask)904 static inline void SAI_TxClearStatusFlags(I2S_Type *base, uint32_t mask)
905 {
906 base->TCSR = ((base->TCSR & 0xFFE3FFFFU) | mask);
907 }
908
909 /*!
910 * @brief Gets the SAI Tx status flag state.
911 *
912 * @param base SAI base pointer
913 * @return SAI Rx status flag value. Use the Status Mask to get the status value needed.
914 */
SAI_RxGetStatusFlag(I2S_Type * base)915 static inline uint32_t SAI_RxGetStatusFlag(I2S_Type *base)
916 {
917 return base->RCSR;
918 }
919
920 /*!
921 * @brief Clears the SAI Rx status flag state.
922 *
923 * @param base SAI base pointer
924 * @param mask State mask. It can be a combination of the following sources if defined.
925 * @arg kSAI_WordStartFlag
926 * @arg kSAI_SyncErrorFlag
927 * @arg kSAI_FIFOErrorFlag
928 */
SAI_RxClearStatusFlags(I2S_Type * base,uint32_t mask)929 static inline void SAI_RxClearStatusFlags(I2S_Type *base, uint32_t mask)
930 {
931 base->RCSR = ((base->RCSR & 0xFFE3FFFFU) | mask);
932 }
933
934 /*!
935 * @brief Do software reset or FIFO reset .
936 *
937 * FIFO reset means clear all the data in the FIFO, and make the FIFO pointer both to 0.
938 * Software reset means clear the Tx internal logic, including the bit clock, frame count etc. But software
939 * reset will not clear any configuration registers like TCR1~TCR5.
940 * This function will also clear all the error flags such as FIFO error, sync error etc.
941 *
942 * @param base SAI base pointer
943 * @param tresetType Reset type, FIFO reset or software reset
944 */
945 void SAI_TxSoftwareReset(I2S_Type *base, sai_reset_type_t resetType);
946
947 /*!
948 * @brief Do software reset or FIFO reset .
949 *
950 * FIFO reset means clear all the data in the FIFO, and make the FIFO pointer both to 0.
951 * Software reset means clear the Rx internal logic, including the bit clock, frame count etc. But software
952 * reset will not clear any configuration registers like RCR1~RCR5.
953 * This function will also clear all the error flags such as FIFO error, sync error etc.
954 *
955 * @param base SAI base pointer
956 * @param resetType Reset type, FIFO reset or software reset
957 */
958 void SAI_RxSoftwareReset(I2S_Type *base, sai_reset_type_t resetType);
959
960 /*!
961 * @brief Set the Tx channel FIFO enable mask.
962 *
963 * @param base SAI base pointer
964 * @param mask Channel enable mask, 0 means all channel FIFO disabled, 1 means channel 0 enabled,
965 * 3 means both channel 0 and channel 1 enabled.
966 */
967 void SAI_TxSetChannelFIFOMask(I2S_Type *base, uint8_t mask);
968
969 /*!
970 * @brief Set the Rx channel FIFO enable mask.
971 *
972 * @param base SAI base pointer
973 * @param mask Channel enable mask, 0 means all channel FIFO disabled, 1 means channel 0 enabled,
974 * 3 means both channel 0 and channel 1 enabled.
975 */
976 void SAI_RxSetChannelFIFOMask(I2S_Type *base, uint8_t mask);
977
978 /*!
979 * @brief Set the Tx data order.
980 *
981 * @param base SAI base pointer
982 * @param order Data order MSB or LSB
983 */
984 void SAI_TxSetDataOrder(I2S_Type *base, sai_data_order_t order);
985
986 /*!
987 * @brief Set the Rx data order.
988 *
989 * @param base SAI base pointer
990 * @param order Data order MSB or LSB
991 */
992 void SAI_RxSetDataOrder(I2S_Type *base, sai_data_order_t order);
993
994 /*!
995 * @brief Set the Tx data order.
996 *
997 * @param base SAI base pointer
998 * @param polarity
999 */
1000 void SAI_TxSetBitClockPolarity(I2S_Type *base, sai_clock_polarity_t polarity);
1001
1002 /*!
1003 * @brief Set the Rx data order.
1004 *
1005 * @param base SAI base pointer
1006 * @param polarity
1007 */
1008 void SAI_RxSetBitClockPolarity(I2S_Type *base, sai_clock_polarity_t polarity);
1009
1010 /*!
1011 * @brief Set the Tx data order.
1012 *
1013 * @param base SAI base pointer
1014 * @param polarity
1015 */
1016 void SAI_TxSetFrameSyncPolarity(I2S_Type *base, sai_clock_polarity_t polarity);
1017
1018 /*!
1019 * @brief Set the Rx data order.
1020 *
1021 * @param base SAI base pointer
1022 * @param polarity
1023 */
1024 void SAI_RxSetFrameSyncPolarity(I2S_Type *base, sai_clock_polarity_t polarity);
1025
1026 #if defined(FSL_FEATURE_SAI_HAS_FIFO_PACKING) && FSL_FEATURE_SAI_HAS_FIFO_PACKING
1027 /*!
1028 * @brief Set Tx FIFO packing feature.
1029 *
1030 * @param base SAI base pointer.
1031 * @param pack FIFO pack type. It is element of sai_fifo_packing_t.
1032 */
1033 void SAI_TxSetFIFOPacking(I2S_Type *base, sai_fifo_packing_t pack);
1034
1035 /*!
1036 * @brief Set Rx FIFO packing feature.
1037 *
1038 * @param base SAI base pointer.
1039 * @param pack FIFO pack type. It is element of sai_fifo_packing_t.
1040 */
1041 void SAI_RxSetFIFOPacking(I2S_Type *base, sai_fifo_packing_t pack);
1042 #endif /* FSL_FEATURE_SAI_HAS_FIFO_PACKING */
1043
1044 #if defined(FSL_FEATURE_SAI_HAS_FIFO_FUNCTION_AFTER_ERROR) && FSL_FEATURE_SAI_HAS_FIFO_FUNCTION_AFTER_ERROR
1045 /*!
1046 * @brief Set Tx FIFO error continue.
1047 *
1048 * FIFO error continue mode means SAI will keep running while FIFO error occurred. If this feature
1049 * not enabled, SAI will hang and users need to clear FEF flag in TCSR register.
1050 *
1051 * @param base SAI base pointer.
1052 * @param isEnabled Is FIFO error continue enabled, true means enable, false means disable.
1053 */
SAI_TxSetFIFOErrorContinue(I2S_Type * base,bool isEnabled)1054 static inline void SAI_TxSetFIFOErrorContinue(I2S_Type *base, bool isEnabled)
1055 {
1056 if (isEnabled)
1057 {
1058 base->TCR4 |= I2S_TCR4_FCONT_MASK;
1059 }
1060 else
1061 {
1062 base->TCR4 &= ~I2S_TCR4_FCONT_MASK;
1063 }
1064 }
1065
1066 /*!
1067 * @brief Set Rx FIFO error continue.
1068 *
1069 * FIFO error continue mode means SAI will keep running while FIFO error occurred. If this feature
1070 * not enabled, SAI will hang and users need to clear FEF flag in RCSR register.
1071 *
1072 * @param base SAI base pointer.
1073 * @param isEnabled Is FIFO error continue enabled, true means enable, false means disable.
1074 */
SAI_RxSetFIFOErrorContinue(I2S_Type * base,bool isEnabled)1075 static inline void SAI_RxSetFIFOErrorContinue(I2S_Type *base, bool isEnabled)
1076 {
1077 if (isEnabled)
1078 {
1079 base->RCR4 |= I2S_RCR4_FCONT_MASK;
1080 }
1081 else
1082 {
1083 base->RCR4 &= ~I2S_RCR4_FCONT_MASK;
1084 }
1085 }
1086 #endif
1087
1088 /*! @} */
1089
1090 /*!
1091 * @name Interrupts
1092 * @{
1093 */
1094
1095 /*!
1096 * @brief Enables the SAI Tx interrupt requests.
1097 *
1098 * @param base SAI base pointer
1099 * @param mask interrupt source
1100 * The parameter can be a combination of the following sources if defined.
1101 * @arg kSAI_WordStartInterruptEnable
1102 * @arg kSAI_SyncErrorInterruptEnable
1103 * @arg kSAI_FIFOWarningInterruptEnable
1104 * @arg kSAI_FIFORequestInterruptEnable
1105 * @arg kSAI_FIFOErrorInterruptEnable
1106 */
SAI_TxEnableInterrupts(I2S_Type * base,uint32_t mask)1107 static inline void SAI_TxEnableInterrupts(I2S_Type *base, uint32_t mask)
1108 {
1109 base->TCSR = ((base->TCSR & 0xFFE3FFFFU) | mask);
1110 }
1111
1112 /*!
1113 * @brief Enables the SAI Rx interrupt requests.
1114 *
1115 * @param base SAI base pointer
1116 * @param mask interrupt source
1117 * The parameter can be a combination of the following sources if defined.
1118 * @arg kSAI_WordStartInterruptEnable
1119 * @arg kSAI_SyncErrorInterruptEnable
1120 * @arg kSAI_FIFOWarningInterruptEnable
1121 * @arg kSAI_FIFORequestInterruptEnable
1122 * @arg kSAI_FIFOErrorInterruptEnable
1123 */
SAI_RxEnableInterrupts(I2S_Type * base,uint32_t mask)1124 static inline void SAI_RxEnableInterrupts(I2S_Type *base, uint32_t mask)
1125 {
1126 base->RCSR = ((base->RCSR & 0xFFE3FFFFU) | mask);
1127 }
1128
1129 /*!
1130 * @brief Disables the SAI Tx interrupt requests.
1131 *
1132 * @param base SAI base pointer
1133 * @param mask interrupt source
1134 * The parameter can be a combination of the following sources if defined.
1135 * @arg kSAI_WordStartInterruptEnable
1136 * @arg kSAI_SyncErrorInterruptEnable
1137 * @arg kSAI_FIFOWarningInterruptEnable
1138 * @arg kSAI_FIFORequestInterruptEnable
1139 * @arg kSAI_FIFOErrorInterruptEnable
1140 */
SAI_TxDisableInterrupts(I2S_Type * base,uint32_t mask)1141 static inline void SAI_TxDisableInterrupts(I2S_Type *base, uint32_t mask)
1142 {
1143 base->TCSR = ((base->TCSR & 0xFFE3FFFFU) & (~mask));
1144 }
1145
1146 /*!
1147 * @brief Disables the SAI Rx interrupt requests.
1148 *
1149 * @param base SAI base pointer
1150 * @param mask interrupt source
1151 * The parameter can be a combination of the following sources if defined.
1152 * @arg kSAI_WordStartInterruptEnable
1153 * @arg kSAI_SyncErrorInterruptEnable
1154 * @arg kSAI_FIFOWarningInterruptEnable
1155 * @arg kSAI_FIFORequestInterruptEnable
1156 * @arg kSAI_FIFOErrorInterruptEnable
1157 */
SAI_RxDisableInterrupts(I2S_Type * base,uint32_t mask)1158 static inline void SAI_RxDisableInterrupts(I2S_Type *base, uint32_t mask)
1159 {
1160 base->RCSR = ((base->RCSR & 0xFFE3FFFFU) & (~mask));
1161 }
1162
1163 /*! @} */
1164
1165 /*!
1166 * @name DMA Control
1167 * @{
1168 */
1169
1170 /*!
1171 * @brief Enables/disables the SAI Tx DMA requests.
1172 * @param base SAI base pointer
1173 * @param mask DMA source
1174 * The parameter can be combination of the following sources if defined.
1175 * @arg kSAI_FIFOWarningDMAEnable
1176 * @arg kSAI_FIFORequestDMAEnable
1177 * @param enable True means enable DMA, false means disable DMA.
1178 */
SAI_TxEnableDMA(I2S_Type * base,uint32_t mask,bool enable)1179 static inline void SAI_TxEnableDMA(I2S_Type *base, uint32_t mask, bool enable)
1180 {
1181 if (enable)
1182 {
1183 base->TCSR = ((base->TCSR & 0xFFE3FFFFU) | mask);
1184 }
1185 else
1186 {
1187 base->TCSR = ((base->TCSR & 0xFFE3FFFFU) & (~mask));
1188 }
1189 }
1190
1191 /*!
1192 * @brief Enables/disables the SAI Rx DMA requests.
1193 * @param base SAI base pointer
1194 * @param mask DMA source
1195 * The parameter can be a combination of the following sources if defined.
1196 * @arg kSAI_FIFOWarningDMAEnable
1197 * @arg kSAI_FIFORequestDMAEnable
1198 * @param enable True means enable DMA, false means disable DMA.
1199 */
SAI_RxEnableDMA(I2S_Type * base,uint32_t mask,bool enable)1200 static inline void SAI_RxEnableDMA(I2S_Type *base, uint32_t mask, bool enable)
1201 {
1202 if (enable)
1203 {
1204 base->RCSR = ((base->RCSR & 0xFFE3FFFFU) | mask);
1205 }
1206 else
1207 {
1208 base->RCSR = ((base->RCSR & 0xFFE3FFFFU) & (~mask));
1209 }
1210 }
1211
1212 /*!
1213 * @brief Gets the SAI Tx data register address.
1214 *
1215 * This API is used to provide a transfer address for the SAI DMA transfer configuration.
1216 *
1217 * @param base SAI base pointer.
1218 * @param channel Which data channel used.
1219 * @return data register address.
1220 */
SAI_TxGetDataRegisterAddress(I2S_Type * base,uint32_t channel)1221 static inline uintptr_t SAI_TxGetDataRegisterAddress(I2S_Type *base, uint32_t channel)
1222 {
1223 return (uintptr_t)(&(base->TDR)[channel]);
1224 }
1225
1226 /*!
1227 * @brief Gets the SAI Rx data register address.
1228 *
1229 * This API is used to provide a transfer address for the SAI DMA transfer configuration.
1230 *
1231 * @param base SAI base pointer.
1232 * @param channel Which data channel used.
1233 * @return data register address.
1234 */
SAI_RxGetDataRegisterAddress(I2S_Type * base,uint32_t channel)1235 static inline uintptr_t SAI_RxGetDataRegisterAddress(I2S_Type *base, uint32_t channel)
1236 {
1237 return (uintptr_t)(&(base->RDR)[channel]);
1238 }
1239
1240 /*! @} */
1241
1242 /*!
1243 * @name Bus Operations
1244 * @{
1245 */
1246
1247 /*!
1248 * @brief Configures the SAI Tx audio format.
1249 * @deprecated Do not use this function. It has been superceded by @ref SAI_TxSetConfig
1250 *
1251 * The audio format can be changed at run-time. This function configures the sample rate and audio data
1252 * format to be transferred.
1253 *
1254 * @param base SAI base pointer.
1255 * @param format Pointer to the SAI audio data format structure.
1256 * @param mclkSourceClockHz SAI master clock source frequency in Hz.
1257 * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If the bit clock source is a master
1258 * clock, this value should equal the masterClockHz.
1259 */
1260 void SAI_TxSetFormat(I2S_Type *base,
1261 sai_transfer_format_t *format,
1262 uint32_t mclkSourceClockHz,
1263 uint32_t bclkSourceClockHz);
1264
1265 /*!
1266 * @brief Configures the SAI Rx audio format.
1267 * @deprecated Do not use this function. It has been superceded by @ref SAI_RxSetConfig
1268 *
1269 * The audio format can be changed at run-time. This function configures the sample rate and audio data
1270 * format to be transferred.
1271 *
1272 * @param base SAI base pointer.
1273 * @param format Pointer to the SAI audio data format structure.
1274 * @param mclkSourceClockHz SAI master clock source frequency in Hz.
1275 * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If the bit clock source is a master
1276 * clock, this value should equal the masterClockHz.
1277 */
1278 void SAI_RxSetFormat(I2S_Type *base,
1279 sai_transfer_format_t *format,
1280 uint32_t mclkSourceClockHz,
1281 uint32_t bclkSourceClockHz);
1282
1283 /*!
1284 * @brief Sends data using a blocking method.
1285 *
1286 * @note This function blocks by polling until data is ready to be sent.
1287 *
1288 * @param base SAI base pointer.
1289 * @param channel Data channel used.
1290 * @param bitWidth How many bits in an audio word; usually 8/16/24/32 bits.
1291 * @param buffer Pointer to the data to be written.
1292 * @param size Bytes to be written.
1293 */
1294 void SAI_WriteBlocking(I2S_Type *base, uint32_t channel, uint32_t bitWidth, uint8_t *buffer, uint32_t size);
1295
1296 /*!
1297 * @brief Sends data to multi channel using a blocking method.
1298 *
1299 * @note This function blocks by polling until data is ready to be sent.
1300 *
1301 * @param base SAI base pointer.
1302 * @param channel Data channel used.
1303 * @param channelMask channel mask.
1304 * @param bitWidth How many bits in an audio word; usually 8/16/24/32 bits.
1305 * @param buffer Pointer to the data to be written.
1306 * @param size Bytes to be written.
1307 */
1308 void SAI_WriteMultiChannelBlocking(
1309 I2S_Type *base, uint32_t channel, uint32_t channelMask, uint32_t bitWidth, uint8_t *buffer, uint32_t size);
1310
1311 /*!
1312 * @brief Writes data into SAI FIFO.
1313 *
1314 * @param base SAI base pointer.
1315 * @param channel Data channel used.
1316 * @param data Data needs to be written.
1317 */
SAI_WriteData(I2S_Type * base,uint32_t channel,uint32_t data)1318 static inline void SAI_WriteData(I2S_Type *base, uint32_t channel, uint32_t data)
1319 {
1320 base->TDR[channel] = data;
1321 }
1322
1323 /*!
1324 * @brief Receives data using a blocking method.
1325 *
1326 * @note This function blocks by polling until data is ready to be sent.
1327 *
1328 * @param base SAI base pointer.
1329 * @param channel Data channel used.
1330 * @param bitWidth How many bits in an audio word; usually 8/16/24/32 bits.
1331 * @param buffer Pointer to the data to be read.
1332 * @param size Bytes to be read.
1333 */
1334 void SAI_ReadBlocking(I2S_Type *base, uint32_t channel, uint32_t bitWidth, uint8_t *buffer, uint32_t size);
1335
1336 /*!
1337 * @brief Receives multi channel data using a blocking method.
1338 *
1339 * @note This function blocks by polling until data is ready to be sent.
1340 *
1341 * @param base SAI base pointer.
1342 * @param channel Data channel used.
1343 * @param channelMask channel mask.
1344 * @param bitWidth How many bits in an audio word; usually 8/16/24/32 bits.
1345 * @param buffer Pointer to the data to be read.
1346 * @param size Bytes to be read.
1347 */
1348 void SAI_ReadMultiChannelBlocking(
1349 I2S_Type *base, uint32_t channel, uint32_t channelMask, uint32_t bitWidth, uint8_t *buffer, uint32_t size);
1350
1351 /*!
1352 * @brief Reads data from the SAI FIFO.
1353 *
1354 * @param base SAI base pointer.
1355 * @param channel Data channel used.
1356 * @return Data in SAI FIFO.
1357 */
SAI_ReadData(I2S_Type * base,uint32_t channel)1358 static inline uint32_t SAI_ReadData(I2S_Type *base, uint32_t channel)
1359 {
1360 return base->RDR[channel];
1361 }
1362
1363 /*! @} */
1364
1365 /*!
1366 * @name Transactional
1367 * @{
1368 */
1369
1370 /*!
1371 * @brief Initializes the SAI Tx handle.
1372 *
1373 * This function initializes the Tx handle for the SAI Tx transactional APIs. Call
1374 * this function once to get the handle initialized.
1375 *
1376 * @param base SAI base pointer
1377 * @param handle SAI handle pointer.
1378 * @param callback Pointer to the user callback function.
1379 * @param userData User parameter passed to the callback function
1380 */
1381 void SAI_TransferTxCreateHandle(I2S_Type *base, sai_handle_t *handle, sai_transfer_callback_t callback, void *userData);
1382
1383 /*!
1384 * @brief Initializes the SAI Rx handle.
1385 *
1386 * This function initializes the Rx handle for the SAI Rx transactional APIs. Call
1387 * this function once to get the handle initialized.
1388 *
1389 * @param base SAI base pointer.
1390 * @param handle SAI handle pointer.
1391 * @param callback Pointer to the user callback function.
1392 * @param userData User parameter passed to the callback function.
1393 */
1394 void SAI_TransferRxCreateHandle(I2S_Type *base, sai_handle_t *handle, sai_transfer_callback_t callback, void *userData);
1395
1396 /*!
1397 * @brief SAI transmitter transfer configurations.
1398 *
1399 * This function initializes the Tx, include bit clock, frame sync, master clock, serial data and fifo
1400 * configurations.
1401 *
1402 * @param base SAI base pointer.
1403 * @param handle SAI handle pointer.
1404 * @param config tranmitter configurations.
1405 */
1406 void SAI_TransferTxSetConfig(I2S_Type *base, sai_handle_t *handle, sai_transceiver_t *config);
1407
1408 /*!
1409 * @brief SAI receiver transfer configurations.
1410 *
1411 * This function initializes the Rx, include bit clock, frame sync, master clock, serial data and fifo
1412 * configurations.
1413 *
1414 * @param base SAI base pointer.
1415 * @param handle SAI handle pointer.
1416 * @param config receiver configurations.
1417 */
1418 void SAI_TransferRxSetConfig(I2S_Type *base, sai_handle_t *handle, sai_transceiver_t *config);
1419
1420 /*!
1421 * @brief Configures the SAI Tx audio format.
1422 * @deprecated Do not use this function. It has been superceded by @ref SAI_TransferTxSetConfig
1423 *
1424 * The audio format can be changed at run-time. This function configures the sample rate and audio data
1425 * format to be transferred.
1426 *
1427 * @param base SAI base pointer.
1428 * @param handle SAI handle pointer.
1429 * @param format Pointer to the SAI audio data format structure.
1430 * @param mclkSourceClockHz SAI master clock source frequency in Hz.
1431 * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If a bit clock source is a master
1432 * clock, this value should equal the masterClockHz in format.
1433 * @return Status of this function. Return value is the status_t.
1434 */
1435 status_t SAI_TransferTxSetFormat(I2S_Type *base,
1436 sai_handle_t *handle,
1437 sai_transfer_format_t *format,
1438 uint32_t mclkSourceClockHz,
1439 uint32_t bclkSourceClockHz);
1440
1441 /*!
1442 * @brief Configures the SAI Rx audio format.
1443 * @deprecated Do not use this function. It has been superceded by @ref SAI_TransferRxSetConfig
1444 *
1445 * The audio format can be changed at run-time. This function configures the sample rate and audio data
1446 * format to be transferred.
1447 *
1448 * @param base SAI base pointer.
1449 * @param handle SAI handle pointer.
1450 * @param format Pointer to the SAI audio data format structure.
1451 * @param mclkSourceClockHz SAI master clock source frequency in Hz.
1452 * @param bclkSourceClockHz SAI bit clock source frequency in Hz. If a bit clock source is a master
1453 * clock, this value should equal the masterClockHz in format.
1454 * @return Status of this function. Return value is one of status_t.
1455 */
1456 status_t SAI_TransferRxSetFormat(I2S_Type *base,
1457 sai_handle_t *handle,
1458 sai_transfer_format_t *format,
1459 uint32_t mclkSourceClockHz,
1460 uint32_t bclkSourceClockHz);
1461
1462 /*!
1463 * @brief Performs an interrupt non-blocking send transfer on SAI.
1464 *
1465 * @note This API returns immediately after the transfer initiates.
1466 * Call the SAI_TxGetTransferStatusIRQ to poll the transfer status and check whether
1467 * the transfer is finished. If the return status is not kStatus_SAI_Busy, the transfer
1468 * is finished.
1469 *
1470 * @param base SAI base pointer.
1471 * @param handle Pointer to the sai_handle_t structure which stores the transfer state.
1472 * @param xfer Pointer to the sai_transfer_t structure.
1473 * @retval kStatus_Success Successfully started the data receive.
1474 * @retval kStatus_SAI_TxBusy Previous receive still not finished.
1475 * @retval kStatus_InvalidArgument The input parameter is invalid.
1476 */
1477 status_t SAI_TransferSendNonBlocking(I2S_Type *base, sai_handle_t *handle, sai_transfer_t *xfer);
1478
1479 /*!
1480 * @brief Performs an interrupt non-blocking receive transfer on SAI.
1481 *
1482 * @note This API returns immediately after the transfer initiates.
1483 * Call the SAI_RxGetTransferStatusIRQ to poll the transfer status and check whether
1484 * the transfer is finished. If the return status is not kStatus_SAI_Busy, the transfer
1485 * is finished.
1486 *
1487 * @param base SAI base pointer
1488 * @param handle Pointer to the sai_handle_t structure which stores the transfer state.
1489 * @param xfer Pointer to the sai_transfer_t structure.
1490 * @retval kStatus_Success Successfully started the data receive.
1491 * @retval kStatus_SAI_RxBusy Previous receive still not finished.
1492 * @retval kStatus_InvalidArgument The input parameter is invalid.
1493 */
1494 status_t SAI_TransferReceiveNonBlocking(I2S_Type *base, sai_handle_t *handle, sai_transfer_t *xfer);
1495
1496 /*!
1497 * @brief Gets a set byte count.
1498 *
1499 * @param base SAI base pointer.
1500 * @param handle Pointer to the sai_handle_t structure which stores the transfer state.
1501 * @param count Bytes count sent.
1502 * @retval kStatus_Success Succeed get the transfer count.
1503 * @retval kStatus_NoTransferInProgress There is not a non-blocking transaction currently in progress.
1504 */
1505 status_t SAI_TransferGetSendCount(I2S_Type *base, sai_handle_t *handle, size_t *count);
1506
1507 /*!
1508 * @brief Gets a received byte count.
1509 *
1510 * @param base SAI base pointer.
1511 * @param handle Pointer to the sai_handle_t structure which stores the transfer state.
1512 * @param count Bytes count received.
1513 * @retval kStatus_Success Succeed get the transfer count.
1514 * @retval kStatus_NoTransferInProgress There is not a non-blocking transaction currently in progress.
1515 */
1516 status_t SAI_TransferGetReceiveCount(I2S_Type *base, sai_handle_t *handle, size_t *count);
1517
1518 /*!
1519 * @brief Aborts the current send.
1520 *
1521 * @note This API can be called any time when an interrupt non-blocking transfer initiates
1522 * to abort the transfer early.
1523 *
1524 * @param base SAI base pointer.
1525 * @param handle Pointer to the sai_handle_t structure which stores the transfer state.
1526 */
1527 void SAI_TransferAbortSend(I2S_Type *base, sai_handle_t *handle);
1528
1529 /*!
1530 * @brief Aborts the current IRQ receive.
1531 *
1532 * @note This API can be called when an interrupt non-blocking transfer initiates
1533 * to abort the transfer early.
1534 *
1535 * @param base SAI base pointer
1536 * @param handle Pointer to the sai_handle_t structure which stores the transfer state.
1537 */
1538 void SAI_TransferAbortReceive(I2S_Type *base, sai_handle_t *handle);
1539
1540 /*!
1541 * @brief Terminate all SAI send.
1542 *
1543 * This function will clear all transfer slots buffered in the sai queue. If users only want to abort the
1544 * current transfer slot, please call SAI_TransferAbortSend.
1545 *
1546 * @param base SAI base pointer.
1547 * @param handle SAI eDMA handle pointer.
1548 */
1549 void SAI_TransferTerminateSend(I2S_Type *base, sai_handle_t *handle);
1550
1551 /*!
1552 * @brief Terminate all SAI receive.
1553 *
1554 * This function will clear all transfer slots buffered in the sai queue. If users only want to abort the
1555 * current transfer slot, please call SAI_TransferAbortReceive.
1556 *
1557 * @param base SAI base pointer.
1558 * @param handle SAI eDMA handle pointer.
1559 */
1560 void SAI_TransferTerminateReceive(I2S_Type *base, sai_handle_t *handle);
1561
1562 /*!
1563 * @brief Tx interrupt handler.
1564 *
1565 * @param base SAI base pointer.
1566 * @param handle Pointer to the sai_handle_t structure.
1567 */
1568 void SAI_TransferTxHandleIRQ(I2S_Type *base, sai_handle_t *handle);
1569
1570 /*!
1571 * @brief Tx interrupt handler.
1572 *
1573 * @param base SAI base pointer.
1574 * @param handle Pointer to the sai_handle_t structure.
1575 */
1576 void SAI_TransferRxHandleIRQ(I2S_Type *base, sai_handle_t *handle);
1577
1578 /*! @} */
1579
1580 #if defined(__cplusplus)
1581 }
1582 #endif /*_cplusplus*/
1583
1584 /*! @} */
1585
1586 #endif /* _FSL_SAI_H_ */
