Overview

The MCUXpresso SDK provides a peripheral driver for the Serial Audio Interface (SAI) module of MCUXpresso SDK devices.

SAI driver includes functional APIs and transactional APIs.

Functional APIs target low-level APIs. Functional APIs can be used for SAI initialization, configuration and operation, and for optimization and customization purposes. Using the functional API requires the knowledge of the SAI peripheral and how to organize functional APIs to meet the application requirements. All functional API use the peripheral base address as the first parameter. SAI functional operation groups provide the functional API set.

Transactional APIs target high-level APIs. Transactional APIs can be used to enable the peripheral and in the application if the code size and performance of transactional APIs satisfy the requirements. If the code size and performance are a critical requirement, see the transactional API implementation and write a custom code. All transactional APIs use the sai_handle_t as the first parameter. Initialize the handle by calling the SAI_TransferTxCreateHandle() or SAI_TransferRxCreateHandle() API.

Transactional APIs support asynchronous transfer. This means that the functions SAI_TransferSendNonBlocking() and SAI_TransfferReceiveNonBlocking() set up the interrupt for data transfer. When the transfer completes, the upper layer is notified through a callback function with the kStatus_SAI_TxIdle and kStatus_SAI_RxIdle status.

Typical use case

SAI Send/receive using an interrupt method

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/sai

SAI Send/receive using a DMA method

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/sai

Modules
	SAI DMA Driver

	SAI SDMA Driver

	SAI eDMA Driver

Data Structures
struct	sai_config_t
	SAI user configuration structure. More...

struct	sai_transfer_format_t
	sai transfer format More...

struct	sai_transfer_t
	SAI transfer structure. More...

struct	sai_handle_t
	SAI handle structure. More...

Macros
#define	SAI_XFER_QUEUE_SIZE (4)
	SAI transfer queue size, user can refine it according to use case. More...

Typedefs
typedef void(*	sai_transfer_callback_t )(I2S_Type base, sai_handle_t handle, status_t status, void *userData)
	SAI transfer callback prototype.

Enumerations
enum	_sai_status_t { kStatus_SAI_TxBusy = MAKE_STATUS(kStatusGroup_SAI, 0), kStatus_SAI_RxBusy = MAKE_STATUS(kStatusGroup_SAI, 1), kStatus_SAI_TxError = MAKE_STATUS(kStatusGroup_SAI, 2), kStatus_SAI_RxError = MAKE_STATUS(kStatusGroup_SAI, 3), kStatus_SAI_QueueFull = MAKE_STATUS(kStatusGroup_SAI, 4), kStatus_SAI_TxIdle = MAKE_STATUS(kStatusGroup_SAI, 5), kStatus_SAI_RxIdle = MAKE_STATUS(kStatusGroup_SAI, 6) }
	SAI return status. More...

enum	sai_protocol_t { kSAI_BusLeftJustified = 0x0U, kSAI_BusRightJustified, kSAI_BusI2S, kSAI_BusPCMA, kSAI_BusPCMB }
	Define the SAI bus type. More...

enum	sai_master_slave_t { kSAI_Master = 0x0U, kSAI_Slave = 0x1U }
	Master or slave mode. More...

enum	sai_mono_stereo_t { kSAI_Stereo = 0x0U, kSAI_MonoRight, kSAI_MonoLeft }
	Mono or stereo audio format. More...

enum	sai_data_order_t { kSAI_DataLSB = 0x0U, kSAI_DataMSB }
	SAI data order, MSB or LSB. More...

enum	sai_clock_polarity_t { kSAI_PolarityActiveHigh = 0x0U, kSAI_PolarityActiveLow }
	SAI clock polarity, active high or low. More...

enum	sai_sync_mode_t { kSAI_ModeAsync = 0x0U, kSAI_ModeSync, kSAI_ModeSyncWithOtherTx, kSAI_ModeSyncWithOtherRx }
	Synchronous or asynchronous mode. More...

enum	sai_mclk_source_t { kSAI_MclkSourceSysclk = 0x0U, kSAI_MclkSourceSelect1, kSAI_MclkSourceSelect2, kSAI_MclkSourceSelect3 }
	Mater clock source. More...

enum	sai_bclk_source_t { kSAI_BclkSourceBusclk = 0x0U, kSAI_BclkSourceMclkDiv, kSAI_BclkSourceOtherSai0, kSAI_BclkSourceOtherSai1 }
	Bit clock source. More...

enum	_sai_interrupt_enable_t { kSAI_WordStartInterruptEnable, kSAI_SyncErrorInterruptEnable = I2S_TCSR_SEIE_MASK, kSAI_FIFOWarningInterruptEnable = I2S_TCSR_FWIE_MASK, kSAI_FIFOErrorInterruptEnable = I2S_TCSR_FEIE_MASK, kSAI_FIFORequestInterruptEnable = I2S_TCSR_FRIE_MASK }
	The SAI interrupt enable flag. More...

enum	_sai_dma_enable_t { kSAI_FIFOWarningDMAEnable = I2S_TCSR_FWDE_MASK, kSAI_FIFORequestDMAEnable = I2S_TCSR_FRDE_MASK }
	The DMA request sources. More...

enum	_sai_flags { kSAI_WordStartFlag = I2S_TCSR_WSF_MASK, kSAI_SyncErrorFlag = I2S_TCSR_SEF_MASK, kSAI_FIFOErrorFlag = I2S_TCSR_FEF_MASK, kSAI_FIFORequestFlag = I2S_TCSR_FRF_MASK, kSAI_FIFOWarningFlag = I2S_TCSR_FWF_MASK }
	The SAI status flag. More...

enum	sai_reset_type_t { kSAI_ResetTypeSoftware = I2S_TCSR_SR_MASK, kSAI_ResetTypeFIFO = I2S_TCSR_FR_MASK, kSAI_ResetAll = I2S_TCSR_SR_MASK \| I2S_TCSR_FR_MASK }
	The reset type. More...

enum	sai_fifo_packing_t { kSAI_FifoPackingDisabled = 0x0U, kSAI_FifoPacking8bit = 0x2U, kSAI_FifoPacking16bit = 0x3U }
	The SAI packing mode The mode includes 8 bit and 16 bit packing. More...

enum	sai_sample_rate_t { kSAI_SampleRate8KHz = 8000U, kSAI_SampleRate11025Hz = 11025U, kSAI_SampleRate12KHz = 12000U, kSAI_SampleRate16KHz = 16000U, kSAI_SampleRate22050Hz = 22050U, kSAI_SampleRate24KHz = 24000U, kSAI_SampleRate32KHz = 32000U, kSAI_SampleRate44100Hz = 44100U, kSAI_SampleRate48KHz = 48000U, kSAI_SampleRate96KHz = 96000U }
	Audio sample rate. More...

enum	sai_word_width_t { kSAI_WordWidth8bits = 8U, kSAI_WordWidth16bits = 16U, kSAI_WordWidth24bits = 24U, kSAI_WordWidth32bits = 32U }
	Audio word width. More...

Driver version
#define	FSL_SAI_DRIVER_VERSION (MAKE_VERSION(2, 1, 4))
	Version 2.1.4.

Initialization and deinitialization
void	SAI_TxInit (I2S_Type base, const sai_config_t config)
	Initializes the SAI Tx peripheral. More...

void	SAI_RxInit (I2S_Type base, const sai_config_t config)
	Initializes the SAI Rx peripheral. More...

void	SAI_TxGetDefaultConfig (sai_config_t *config)
	Sets the SAI Tx configuration structure to default values. More...

void	SAI_RxGetDefaultConfig (sai_config_t *config)
	Sets the SAI Rx configuration structure to default values. More...

void	SAI_Deinit (I2S_Type *base)
	De-initializes the SAI peripheral. More...

void	SAI_TxReset (I2S_Type *base)
	Resets the SAI Tx. More...

void	SAI_RxReset (I2S_Type *base)
	Resets the SAI Rx. More...

void	SAI_TxEnable (I2S_Type *base, bool enable)
	Enables/disables the SAI Tx. More...

void	SAI_RxEnable (I2S_Type *base, bool enable)
	Enables/disables the SAI Rx. More...

Status
static uint32_t	SAI_TxGetStatusFlag (I2S_Type *base)
	Gets the SAI Tx status flag state. More...

static void	SAI_TxClearStatusFlags (I2S_Type *base, uint32_t mask)
	Clears the SAI Tx status flag state. More...

static uint32_t	SAI_RxGetStatusFlag (I2S_Type *base)
	Gets the SAI Tx status flag state. More...

static void	SAI_RxClearStatusFlags (I2S_Type *base, uint32_t mask)
	Clears the SAI Rx status flag state. More...

void	SAI_TxSoftwareReset (I2S_Type *base, sai_reset_type_t type)
	Do software reset or FIFO reset . More...

void	SAI_RxSoftwareReset (I2S_Type *base, sai_reset_type_t type)
	Do software reset or FIFO reset . More...

void	SAI_TxSetChannelFIFOMask (I2S_Type *base, uint8_t mask)
	Set the Tx channel FIFO enable mask. More...

void	SAI_RxSetChannelFIFOMask (I2S_Type *base, uint8_t mask)
	Set the Rx channel FIFO enable mask. More...

void	SAI_TxSetDataOrder (I2S_Type *base, sai_data_order_t order)
	Set the Tx data order. More...

void	SAI_RxSetDataOrder (I2S_Type *base, sai_data_order_t order)
	Set the Rx data order. More...

void	SAI_TxSetBitClockPolarity (I2S_Type *base, sai_clock_polarity_t polarity)
	Set the Tx data order. More...

void	SAI_RxSetBitClockPolarity (I2S_Type *base, sai_clock_polarity_t polarity)
	Set the Rx data order. More...

void	SAI_TxSetFrameSyncPolarity (I2S_Type *base, sai_clock_polarity_t polarity)
	Set the Tx data order. More...

void	SAI_RxSetFrameSyncPolarity (I2S_Type *base, sai_clock_polarity_t polarity)
	Set the Rx data order. More...

void	SAI_TxSetFIFOPacking (I2S_Type *base, sai_fifo_packing_t pack)
	Set Tx FIFO packing feature. More...

void	SAI_RxSetFIFOPacking (I2S_Type *base, sai_fifo_packing_t pack)
	Set Rx FIFO packing feature. More...

static void	SAI_TxSetFIFOErrorContinue (I2S_Type *base, bool isEnabled)
	Set Tx FIFO error continue. More...

static void	SAI_RxSetFIFOErrorContinue (I2S_Type *base, bool isEnabled)
	Set Rx FIFO error continue. More...

Interrupts
static void	SAI_TxEnableInterrupts (I2S_Type *base, uint32_t mask)
	Enables the SAI Tx interrupt requests. More...

static void	SAI_RxEnableInterrupts (I2S_Type *base, uint32_t mask)
	Enables the SAI Rx interrupt requests. More...

static void	SAI_TxDisableInterrupts (I2S_Type *base, uint32_t mask)
	Disables the SAI Tx interrupt requests. More...

static void	SAI_RxDisableInterrupts (I2S_Type *base, uint32_t mask)
	Disables the SAI Rx interrupt requests. More...

DMA Control
static void	SAI_TxEnableDMA (I2S_Type *base, uint32_t mask, bool enable)
	Enables/disables the SAI Tx DMA requests. More...

static void	SAI_RxEnableDMA (I2S_Type *base, uint32_t mask, bool enable)
	Enables/disables the SAI Rx DMA requests. More...

static uint32_t	SAI_TxGetDataRegisterAddress (I2S_Type *base, uint32_t channel)
	Gets the SAI Tx data register address. More...

static uint32_t	SAI_RxGetDataRegisterAddress (I2S_Type *base, uint32_t channel)
	Gets the SAI Rx data register address. More...

Bus Operations
void	SAI_TxSetFormat (I2S_Type base, sai_transfer_format_t format, uint32_t mclkSourceClockHz, uint32_t bclkSourceClockHz)
	Configures the SAI Tx audio format. More...

void	SAI_RxSetFormat (I2S_Type base, sai_transfer_format_t format, uint32_t mclkSourceClockHz, uint32_t bclkSourceClockHz)
	Configures the SAI Rx audio format. More...

void	SAI_WriteBlocking (I2S_Type base, uint32_t channel, uint32_t bitWidth, uint8_t buffer, uint32_t size)
	Sends data using a blocking method. More...

static void	SAI_WriteData (I2S_Type *base, uint32_t channel, uint32_t data)
	Writes data into SAI FIFO. More...

void	SAI_ReadBlocking (I2S_Type base, uint32_t channel, uint32_t bitWidth, uint8_t buffer, uint32_t size)
	Receives data using a blocking method. More...

static uint32_t	SAI_ReadData (I2S_Type *base, uint32_t channel)
	Reads data from the SAI FIFO. More...

Transactional
void	SAI_TransferTxCreateHandle (I2S_Type base, sai_handle_t handle, sai_transfer_callback_t callback, void *userData)
	Initializes the SAI Tx handle. More...

void	SAI_TransferRxCreateHandle (I2S_Type base, sai_handle_t handle, sai_transfer_callback_t callback, void *userData)
	Initializes the SAI Rx handle. More...

status_t	SAI_TransferTxSetFormat (I2S_Type base, sai_handle_t handle, sai_transfer_format_t *format, uint32_t mclkSourceClockHz, uint32_t bclkSourceClockHz)
	Configures the SAI Tx audio format. More...

status_t	SAI_TransferRxSetFormat (I2S_Type base, sai_handle_t handle, sai_transfer_format_t *format, uint32_t mclkSourceClockHz, uint32_t bclkSourceClockHz)
	Configures the SAI Rx audio format. More...

status_t	SAI_TransferSendNonBlocking (I2S_Type base, sai_handle_t handle, sai_transfer_t *xfer)
	Performs an interrupt non-blocking send transfer on SAI. More...

status_t	SAI_TransferReceiveNonBlocking (I2S_Type base, sai_handle_t handle, sai_transfer_t *xfer)
	Performs an interrupt non-blocking receive transfer on SAI. More...

status_t	SAI_TransferGetSendCount (I2S_Type base, sai_handle_t handle, size_t *count)
	Gets a set byte count. More...

status_t	SAI_TransferGetReceiveCount (I2S_Type base, sai_handle_t handle, size_t *count)
	Gets a received byte count. More...

void	SAI_TransferAbortSend (I2S_Type base, sai_handle_t handle)
	Aborts the current send. More...

void	SAI_TransferAbortReceive (I2S_Type base, sai_handle_t handle)
	Aborts the current IRQ receive. More...

void	SAI_TransferTerminateSend (I2S_Type base, sai_handle_t handle)
	Terminate all SAI send. More...

void	SAI_TransferTerminateReceive (I2S_Type base, sai_handle_t handle)
	Terminate all SAI receive. More...

void	SAI_TransferTxHandleIRQ (I2S_Type base, sai_handle_t handle)
	Tx interrupt handler. More...

void	SAI_TransferRxHandleIRQ (I2S_Type base, sai_handle_t handle)
	Tx interrupt handler. More...

Data Structure Documentation

struct sai_config_t

Data Fields
sai_protocol_t	protocol
	Audio bus protocol in SAI.

sai_sync_mode_t	syncMode
	SAI sync mode, control Tx/Rx clock sync.

sai_mclk_source_t	mclkSource
	Master Clock source.

sai_bclk_source_t	bclkSource
	Bit Clock source.

sai_master_slave_t	masterSlave
	Master or slave.

struct sai_transfer_format_t

Data Fields
uint32_t	sampleRate_Hz
	Sample rate of audio data.

uint32_t	bitWidth
	Data length of audio data, usually 8/16/24/32 bits.

sai_mono_stereo_t	stereo
	Mono or stereo.

uint32_t	masterClockHz
	Master clock frequency in Hz.

uint8_t	watermark
	Watermark value.

uint8_t	channel
	Data channel used in transfer. More...

sai_protocol_t	protocol
	Which audio protocol used.

bool	isFrameSyncCompact
	True means Frame sync length is configurable according to bitWidth, false means frame sync length is 64 times of bit clock. More...

Field Documentation

uint8_t sai_transfer_format_t::channel

bool sai_transfer_format_t::isFrameSyncCompact

struct sai_transfer_t

Data Fields
uint8_t *	data
	Data start address to transfer. More...

size_t	dataSize
	Transfer size. More...

Field Documentation

uint8_t* sai_transfer_t::data

size_t sai_transfer_t::dataSize

struct _sai_handle

Data Fields
uint32_t	state
	Transfer status.

sai_transfer_callback_t	callback
	Callback function called at transfer event.

void *	userData
	Callback parameter passed to callback function.

uint8_t	bitWidth
	Bit width for transfer, 8/16/24/32 bits.

uint8_t	channel
	Transfer channel.

sai_transfer_t	saiQueue [SAI_XFER_QUEUE_SIZE]
	Transfer queue storing queued transfer.

size_t	transferSize [SAI_XFER_QUEUE_SIZE]
	Data bytes need to transfer.

volatile uint8_t	queueUser
	Index for user to queue transfer.

volatile uint8_t	queueDriver
	Index for driver to get the transfer data and size.

uint8_t	watermark
	Watermark value.

Macro Definition Documentation

#define SAI_XFER_QUEUE_SIZE (4)

Enumeration Type Documentation

enum _sai_status_t

Enumerator
kStatus_SAI_TxBusy	SAI Tx is busy.
kStatus_SAI_RxBusy	SAI Rx is busy.
kStatus_SAI_TxError	SAI Tx FIFO error.
kStatus_SAI_RxError	SAI Rx FIFO error.
kStatus_SAI_QueueFull	SAI transfer queue is full.
kStatus_SAI_TxIdle	SAI Tx is idle.
kStatus_SAI_RxIdle	SAI Rx is idle.

enum sai_protocol_t

Enumerator
kSAI_BusLeftJustified	Uses left justified format.
kSAI_BusRightJustified	Uses right justified format.
kSAI_BusI2S	Uses I2S format.
kSAI_BusPCMA	Uses I2S PCM A format.
kSAI_BusPCMB	Uses I2S PCM B format.

enum sai_master_slave_t

Enumerator
kSAI_Master	Master mode.
kSAI_Slave	Slave mode.

enum sai_mono_stereo_t

Enumerator
kSAI_Stereo	Stereo sound.
kSAI_MonoRight	Only Right channel have sound.
kSAI_MonoLeft	Only left channel have sound.

enum sai_data_order_t

Enumerator
kSAI_DataLSB	LSB bit transferred first.
kSAI_DataMSB	MSB bit transferred first.

enum sai_clock_polarity_t

Enumerator
kSAI_PolarityActiveHigh	Clock active high.
kSAI_PolarityActiveLow	Clock active low.

enum sai_sync_mode_t

Enumerator
kSAI_ModeAsync	Asynchronous mode.
kSAI_ModeSync	Synchronous mode (with receiver or transmit)
kSAI_ModeSyncWithOtherTx	Synchronous with another SAI transmit.
kSAI_ModeSyncWithOtherRx	Synchronous with another SAI receiver.

enum sai_mclk_source_t

Enumerator
kSAI_MclkSourceSysclk	Master clock from the system clock.
kSAI_MclkSourceSelect1	Master clock from source 1.
kSAI_MclkSourceSelect2	Master clock from source 2.
kSAI_MclkSourceSelect3	Master clock from source 3.

enum sai_bclk_source_t

Enumerator
kSAI_BclkSourceBusclk	Bit clock using bus clock.
kSAI_BclkSourceMclkDiv	Bit clock using master clock divider.
kSAI_BclkSourceOtherSai0	Bit clock from other SAI device.
kSAI_BclkSourceOtherSai1	Bit clock from other SAI device.

enum _sai_interrupt_enable_t

Enumerator
kSAI_WordStartInterruptEnable	Word start flag, means the first word in a frame detected.
kSAI_SyncErrorInterruptEnable	Sync error flag, means the sync error is detected.
kSAI_FIFOWarningInterruptEnable	FIFO warning flag, means the FIFO is empty.
kSAI_FIFOErrorInterruptEnable	FIFO error flag.
kSAI_FIFORequestInterruptEnable	FIFO request, means reached watermark.

enum _sai_dma_enable_t

Enumerator
kSAI_FIFOWarningDMAEnable	FIFO warning caused by the DMA request.
kSAI_FIFORequestDMAEnable	FIFO request caused by the DMA request.

enum _sai_flags

Enumerator
kSAI_WordStartFlag	Word start flag, means the first word in a frame detected.
kSAI_SyncErrorFlag	Sync error flag, means the sync error is detected.
kSAI_FIFOErrorFlag	FIFO error flag.
kSAI_FIFORequestFlag	FIFO request flag.
kSAI_FIFOWarningFlag	FIFO warning flag.

enum sai_reset_type_t

Enumerator
kSAI_ResetTypeSoftware	Software reset, reset the logic state.
kSAI_ResetTypeFIFO	FIFO reset, reset the FIFO read and write pointer.
kSAI_ResetAll	All reset.

enum sai_fifo_packing_t

Enumerator
kSAI_FifoPackingDisabled	Packing disabled.
kSAI_FifoPacking8bit	8 bit packing enabled
kSAI_FifoPacking16bit	16bit packing enabled

enum sai_sample_rate_t

Enumerator
kSAI_SampleRate8KHz	Sample rate 8000 Hz.
kSAI_SampleRate11025Hz	Sample rate 11025 Hz.
kSAI_SampleRate12KHz	Sample rate 12000 Hz.
kSAI_SampleRate16KHz	Sample rate 16000 Hz.
kSAI_SampleRate22050Hz	Sample rate 22050 Hz.
kSAI_SampleRate24KHz	Sample rate 24000 Hz.
kSAI_SampleRate32KHz	Sample rate 32000 Hz.
kSAI_SampleRate44100Hz	Sample rate 44100 Hz.
kSAI_SampleRate48KHz	Sample rate 48000 Hz.
kSAI_SampleRate96KHz	Sample rate 96000 Hz.

enum sai_word_width_t

Enumerator
kSAI_WordWidth8bits	Audio data width 8 bits.
kSAI_WordWidth16bits	Audio data width 16 bits.
kSAI_WordWidth24bits	Audio data width 24 bits.
kSAI_WordWidth32bits	Audio data width 32 bits.

Function Documentation

void SAI_TxInit	(	I2S_Type *	base,
		const sai_config_t *	config
	)

Ungates the SAI clock, resets the module, and configures SAI Tx with a configuration structure. The configuration structure can be custom filled or set with default values by SAI_TxGetDefaultConfig().

Note: This API should be called at the beginning of the application to use the SAI driver. Otherwise, accessing the SAIM module can cause a hard fault because the clock is not enabled.

Parameters

base	SAI base pointer
config	SAI configuration structure.

void SAI_RxInit	(	I2S_Type *	base,
		const sai_config_t *	config
	)

Ungates the SAI clock, resets the module, and configures the SAI Rx with a configuration structure. The configuration structure can be custom filled or set with default values by SAI_RxGetDefaultConfig().

Note: This API should be called at the beginning of the application to use the SAI driver. Otherwise, accessing the SAI module can cause a hard fault because the clock is not enabled.

Parameters

base	SAI base pointer
config	SAI configuration structure.

void SAI_TxGetDefaultConfig ( sai_config_t * config )

This API initializes the configuration structure for use in SAI_TxConfig(). The initialized structure can remain unchanged in SAI_TxConfig(), or it can be modified before calling SAI_TxConfig(). This is an example.

sai_config_t config;

SAI_TxGetDefaultConfig(&config);

Parameters

config pointer to master configuration structure

void SAI_RxGetDefaultConfig ( sai_config_t * config )

This API initializes the configuration structure for use in SAI_RxConfig(). The initialized structure can remain unchanged in SAI_RxConfig() or it can be modified before calling SAI_RxConfig(). This is an example.

sai_config_t config;

SAI_RxGetDefaultConfig(&config);

Parameters

config pointer to master configuration structure

void SAI_Deinit ( I2S_Type * base )

This API gates the SAI clock. The SAI module can't operate unless SAI_TxInit or SAI_RxInit is called to enable the clock.

Parameters

base	SAI base pointer

void SAI_TxReset ( I2S_Type * base )

This function enables the software reset and FIFO reset of SAI Tx. After reset, clear the reset bit.

Parameters

base	SAI base pointer

void SAI_RxReset ( I2S_Type * base )

This function enables the software reset and FIFO reset of SAI Rx. After reset, clear the reset bit.

Parameters

base	SAI base pointer

void SAI_TxEnable	(	I2S_Type *	base,
		bool	enable
	)

Parameters

base	SAI base pointer
enable	True means enable SAI Tx, false means disable.

void SAI_RxEnable	(	I2S_Type *	base,
		bool	enable
	)

Parameters

base	SAI base pointer
enable	True means enable SAI Rx, false means disable.

static uint32_t SAI_TxGetStatusFlag ( I2S_Type * base )

inlinestatic

Parameters

base	SAI base pointer

Returns: SAI Tx status flag value. Use the Status Mask to get the status value needed.

static void SAI_TxClearStatusFlags	(	I2S_Type *	base,
		uint32_t	mask
	)

inlinestatic

Parameters

base	SAI base pointer
mask	State mask. It can be a combination of the following source if defined: kSAI_WordStartFlag kSAI_SyncErrorFlag kSAI_FIFOErrorFlag

static uint32_t SAI_RxGetStatusFlag ( I2S_Type * base )

inlinestatic

Parameters

base	SAI base pointer

Returns: SAI Rx status flag value. Use the Status Mask to get the status value needed.

static void SAI_RxClearStatusFlags	(	I2S_Type *	base,
		uint32_t	mask
	)

inlinestatic

Parameters

base	SAI base pointer
mask	State mask. It can be a combination of the following sources if defined. kSAI_WordStartFlag kSAI_SyncErrorFlag kSAI_FIFOErrorFlag

void SAI_TxSoftwareReset	(	I2S_Type *	base,
		sai_reset_type_t	type
	)

FIFO reset means clear all the data in the FIFO, and make the FIFO pointer both to 0. Software reset means claer the Tx internal logic, including the bit clock, frame count etc. But software reset will not clear any configuration registers like TCR1~TCR5. This function will also clear all the error flags such as FIFO error, sync error etc.

Parameters

base	SAI base pointer
type	Reset type, FIFO reset or software reset

void SAI_RxSoftwareReset	(	I2S_Type *	base,
		sai_reset_type_t	type
	)

FIFO reset means clear all the data in the FIFO, and make the FIFO pointer both to 0. Software reset means claer the Rx internal logic, including the bit clock, frame count etc. But software reset will not clear any configuration registers like RCR1~RCR5. This function will also clear all the error flags such as FIFO error, sync error etc.

Parameters

base	SAI base pointer
type	Reset type, FIFO reset or software reset

void SAI_TxSetChannelFIFOMask	(	I2S_Type *	base,
		uint8_t	mask
	)

Parameters

base	SAI base pointer
mask	Channel enable mask, 0 means all channel FIFO disabled, 1 means channel 0 enabled, 3 means both channel 0 and channel 1 enabled.

void SAI_RxSetChannelFIFOMask	(	I2S_Type *	base,
		uint8_t	mask
	)

Parameters

base	SAI base pointer
mask	Channel enable mask, 0 means all channel FIFO disabled, 1 means channel 0 enabled, 3 means both channel 0 and channel 1 enabled.

void SAI_TxSetDataOrder	(	I2S_Type *	base,
		sai_data_order_t	order
	)

Parameters

base	SAI base pointer
order	Data order MSB or LSB

void SAI_RxSetDataOrder	(	I2S_Type *	base,
		sai_data_order_t	order
	)

Parameters

base	SAI base pointer
order	Data order MSB or LSB

void SAI_TxSetBitClockPolarity	(	I2S_Type *	base,
		sai_clock_polarity_t	polarity
	)

Parameters

base	SAI base pointer
order	Data order MSB or LSB

void SAI_RxSetBitClockPolarity	(	I2S_Type *	base,
		sai_clock_polarity_t	polarity
	)

Parameters

base	SAI base pointer
order	Data order MSB or LSB

void SAI_TxSetFrameSyncPolarity	(	I2S_Type *	base,
		sai_clock_polarity_t	polarity
	)

Parameters

base	SAI base pointer
order	Data order MSB or LSB

void SAI_RxSetFrameSyncPolarity	(	I2S_Type *	base,
		sai_clock_polarity_t	polarity
	)

Parameters

base	SAI base pointer
order	Data order MSB or LSB

void SAI_TxSetFIFOPacking	(	I2S_Type *	base,
		sai_fifo_packing_t	pack
	)

Parameters

base	SAI base pointer.
pack	FIFO pack type. It is element of sai_fifo_packing_t.

void SAI_RxSetFIFOPacking	(	I2S_Type *	base,
		sai_fifo_packing_t	pack
	)

Parameters

base	SAI base pointer.
pack	FIFO pack type. It is element of sai_fifo_packing_t.

static void SAI_TxSetFIFOErrorContinue	(	I2S_Type *	base,
		bool	isEnabled
	)

inlinestatic

FIFO error continue mode means SAI will keep running while FIFO error occured. If this feature not enabled, SAI will hang and users need to clear FEF flag in TCSR register.

Parameters

base	SAI base pointer.
isEnabled	Is FIFO error continue enabled, true means enable, false means disable.

static void SAI_RxSetFIFOErrorContinue	(	I2S_Type *	base,
		bool	isEnabled
	)

inlinestatic

FIFO error continue mode means SAI will keep running while FIFO error occured. If this feature not enabled, SAI will hang and users need to clear FEF flag in RCSR register.

Parameters

base	SAI base pointer.
isEnabled	Is FIFO error continue enabled, true means enable, false means disable.

static void SAI_TxEnableInterrupts	(	I2S_Type *	base,
		uint32_t	mask
	)

inlinestatic

Parameters

base	SAI base pointer
mask	interrupt source The parameter can be a combination of the following sources if defined. kSAI_WordStartInterruptEnable kSAI_SyncErrorInterruptEnable kSAI_FIFOWarningInterruptEnable kSAI_FIFORequestInterruptEnable kSAI_FIFOErrorInterruptEnable

static void SAI_RxEnableInterrupts	(	I2S_Type *	base,
		uint32_t	mask
	)

inlinestatic

Parameters

base	SAI base pointer
mask	interrupt source The parameter can be a combination of the following sources if defined. kSAI_WordStartInterruptEnable kSAI_SyncErrorInterruptEnable kSAI_FIFOWarningInterruptEnable kSAI_FIFORequestInterruptEnable kSAI_FIFOErrorInterruptEnable

static void SAI_TxDisableInterrupts	(	I2S_Type *	base,
		uint32_t	mask
	)

inlinestatic

Parameters

base	SAI base pointer
mask	interrupt source The parameter can be a combination of the following sources if defined. kSAI_WordStartInterruptEnable kSAI_SyncErrorInterruptEnable kSAI_FIFOWarningInterruptEnable kSAI_FIFORequestInterruptEnable kSAI_FIFOErrorInterruptEnable

static void SAI_RxDisableInterrupts	(	I2S_Type *	base,
		uint32_t	mask
	)

inlinestatic

Parameters

base	SAI base pointer
mask	interrupt source The parameter can be a combination of the following sources if defined. kSAI_WordStartInterruptEnable kSAI_SyncErrorInterruptEnable kSAI_FIFOWarningInterruptEnable kSAI_FIFORequestInterruptEnable kSAI_FIFOErrorInterruptEnable

static void SAI_TxEnableDMA	(	I2S_Type *	base,
		uint32_t	mask,
		bool	enable
	)

inlinestatic

Parameters

base	SAI base pointer
mask	DMA source The parameter can be combination of the following sources if defined. kSAI_FIFOWarningDMAEnable kSAI_FIFORequestDMAEnable
enable	True means enable DMA, false means disable DMA.

static void SAI_RxEnableDMA	(	I2S_Type *	base,
		uint32_t	mask,
		bool	enable
	)

inlinestatic

Parameters

base	SAI base pointer
mask	DMA source The parameter can be a combination of the following sources if defined. kSAI_FIFOWarningDMAEnable kSAI_FIFORequestDMAEnable
enable	True means enable DMA, false means disable DMA.

static uint32_t SAI_TxGetDataRegisterAddress	(	I2S_Type *	base,
		uint32_t	channel
	)

inlinestatic

This API is used to provide a transfer address for the SAI DMA transfer configuration.

Parameters

base	SAI base pointer.
channel	Which data channel used.

Returns: data register address.

static uint32_t SAI_RxGetDataRegisterAddress	(	I2S_Type *	base,
		uint32_t	channel
	)

inlinestatic

This API is used to provide a transfer address for the SAI DMA transfer configuration.

Parameters

base	SAI base pointer.
channel	Which data channel used.

Returns: data register address.

void SAI_TxSetFormat	(	I2S_Type *	base,
		sai_transfer_format_t *	format,
		uint32_t	mclkSourceClockHz,
		uint32_t	bclkSourceClockHz
	)

The audio format can be changed at run-time. This function configures the sample rate and audio data format to be transferred.

Parameters

base	SAI base pointer.
format	Pointer to the SAI audio data format structure.
mclkSourceClockHz	SAI master clock source frequency in Hz.
bclkSourceClockHz	SAI bit clock source frequency in Hz. If the bit clock source is a master clock, this value should equal the masterClockHz.

void SAI_RxSetFormat	(	I2S_Type *	base,
		sai_transfer_format_t *	format,
		uint32_t	mclkSourceClockHz,
		uint32_t	bclkSourceClockHz
	)

The audio format can be changed at run-time. This function configures the sample rate and audio data format to be transferred.

Parameters

base	SAI base pointer.
format	Pointer to the SAI audio data format structure.
mclkSourceClockHz	SAI master clock source frequency in Hz.
bclkSourceClockHz	SAI bit clock source frequency in Hz. If the bit clock source is a master clock, this value should equal the masterClockHz.

void SAI_WriteBlocking	(	I2S_Type *	base,
		uint32_t	channel,
		uint32_t	bitWidth,
		uint8_t *	buffer,
		uint32_t	size
	)

Note: This function blocks by polling until data is ready to be sent.

Parameters

base	SAI base pointer.
channel	Data channel used.
bitWidth	How many bits in an audio word; usually 8/16/24/32 bits.
buffer	Pointer to the data to be written.
size	Bytes to be written.

static void SAI_WriteData	(	I2S_Type *	base,
		uint32_t	channel,
		uint32_t	data
	)

inlinestatic

Parameters

base	SAI base pointer.
channel	Data channel used.
data	Data needs to be written.

void SAI_ReadBlocking	(	I2S_Type *	base,
		uint32_t	channel,
		uint32_t	bitWidth,
		uint8_t *	buffer,
		uint32_t	size
	)

Note: This function blocks by polling until data is ready to be sent.

Parameters

base	SAI base pointer.
channel	Data channel used.
bitWidth	How many bits in an audio word; usually 8/16/24/32 bits.
buffer	Pointer to the data to be read.
size	Bytes to be read.

static uint32_t SAI_ReadData	(	I2S_Type *	base,
		uint32_t	channel
	)

inlinestatic

Parameters

base	SAI base pointer.
channel	Data channel used.

Returns: Data in SAI FIFO.

void SAI_TransferTxCreateHandle	(	I2S_Type *	base,
		sai_handle_t *	handle,
		sai_transfer_callback_t	callback,
		void *	userData
	)

This function initializes the Tx handle for the SAI Tx transactional APIs. Call this function once to get the handle initialized.

Parameters

base	SAI base pointer
handle	SAI handle pointer.
callback	Pointer to the user callback function.
userData	User parameter passed to the callback function

void SAI_TransferRxCreateHandle	(	I2S_Type *	base,
		sai_handle_t *	handle,
		sai_transfer_callback_t	callback,
		void *	userData
	)

This function initializes the Rx handle for the SAI Rx transactional APIs. Call this function once to get the handle initialized.

Parameters

base	SAI base pointer.
handle	SAI handle pointer.
callback	Pointer to the user callback function.
userData	User parameter passed to the callback function.

status_t SAI_TransferTxSetFormat	(	I2S_Type *	base,
		sai_handle_t *	handle,
		sai_transfer_format_t *	format,
		uint32_t	mclkSourceClockHz,
		uint32_t	bclkSourceClockHz
	)

The audio format can be changed at run-time. This function configures the sample rate and audio data format to be transferred.

Parameters

base	SAI base pointer.
handle	SAI handle pointer.
format	Pointer to the SAI audio data format structure.
mclkSourceClockHz	SAI master clock source frequency in Hz.
bclkSourceClockHz	SAI bit clock source frequency in Hz. If a bit clock source is a master clock, this value should equal the masterClockHz in format.

Returns: Status of this function. Return value is the status_t.

status_t SAI_TransferRxSetFormat	(	I2S_Type *	base,
		sai_handle_t *	handle,
		sai_transfer_format_t *	format,
		uint32_t	mclkSourceClockHz,
		uint32_t	bclkSourceClockHz
	)

The audio format can be changed at run-time. This function configures the sample rate and audio data format to be transferred.

Parameters

base	SAI base pointer.
handle	SAI handle pointer.
format	Pointer to the SAI audio data format structure.
mclkSourceClockHz	SAI master clock source frequency in Hz.
bclkSourceClockHz	SAI bit clock source frequency in Hz. If a bit clock source is a master clock, this value should equal the masterClockHz in format.

Returns: Status of this function. Return value is one of status_t.

status_t SAI_TransferSendNonBlocking	(	I2S_Type *	base,
		sai_handle_t *	handle,
		sai_transfer_t *	xfer
	)

Note: This API returns immediately after the transfer initiates. Call the SAI_TxGetTransferStatusIRQ to poll the transfer status and check whether the transfer is finished. If the return status is not kStatus_SAI_Busy, the transfer is finished.

Parameters

base	SAI base pointer.
handle	Pointer to the sai_handle_t structure which stores the transfer state.
xfer	Pointer to the sai_transfer_t structure.

Return values

kStatus_Success	Successfully started the data receive.
kStatus_SAI_TxBusy	Previous receive still not finished.
kStatus_InvalidArgument	The input parameter is invalid.

status_t SAI_TransferReceiveNonBlocking	(	I2S_Type *	base,
		sai_handle_t *	handle,
		sai_transfer_t *	xfer
	)

Note: This API returns immediately after the transfer initiates. Call the SAI_RxGetTransferStatusIRQ to poll the transfer status and check whether the transfer is finished. If the return status is not kStatus_SAI_Busy, the transfer is finished.

Parameters

base	SAI base pointer
handle	Pointer to the sai_handle_t structure which stores the transfer state.
xfer	Pointer to the sai_transfer_t structure.

Return values

kStatus_Success	Successfully started the data receive.
kStatus_SAI_RxBusy	Previous receive still not finished.
kStatus_InvalidArgument	The input parameter is invalid.

status_t SAI_TransferGetSendCount	(	I2S_Type *	base,
		sai_handle_t *	handle,
		size_t *	count
	)

Parameters

base	SAI base pointer.
handle	Pointer to the sai_handle_t structure which stores the transfer state.
count	Bytes count sent.

Return values

kStatus_Success	Succeed get the transfer count.
kStatus_NoTransferInProgress	There is not a non-blocking transaction currently in progress.

status_t SAI_TransferGetReceiveCount	(	I2S_Type *	base,
		sai_handle_t *	handle,
		size_t *	count
	)

Parameters

base	SAI base pointer.
handle	Pointer to the sai_handle_t structure which stores the transfer state.
count	Bytes count received.

Return values

kStatus_Success	Succeed get the transfer count.
kStatus_NoTransferInProgress	There is not a non-blocking transaction currently in progress.

void SAI_TransferAbortSend	(	I2S_Type *	base,
		sai_handle_t *	handle
	)

Note: This API can be called any time when an interrupt non-blocking transfer initiates to abort the transfer early.

Parameters

base	SAI base pointer.
handle	Pointer to the sai_handle_t structure which stores the transfer state.

void SAI_TransferAbortReceive	(	I2S_Type *	base,
		sai_handle_t *	handle
	)

Note: This API can be called when an interrupt non-blocking transfer initiates to abort the transfer early.

Parameters

base	SAI base pointer
handle	Pointer to the sai_handle_t structure which stores the transfer state.

void SAI_TransferTerminateSend	(	I2S_Type *	base,
		sai_handle_t *	handle
	)

This function will clear all transfer slots buffered in the sai queue. If users only want to abort the current transfer slot, please call SAI_TransferAbortSend.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.

void SAI_TransferTerminateReceive	(	I2S_Type *	base,
		sai_handle_t *	handle
	)

This function will clear all transfer slots buffered in the sai queue. If users only want to abort the current transfer slot, please call SAI_TransferAbortReceive.

Parameters

base	SAI base pointer.
handle	SAI eDMA handle pointer.

void SAI_TransferTxHandleIRQ	(	I2S_Type *	base,
		sai_handle_t *	handle
	)

Parameters

base	SAI base pointer.
handle	Pointer to the sai_handle_t structure.

void SAI_TransferRxHandleIRQ	(	I2S_Type *	base,
		sai_handle_t *	handle
	)

Parameters

base	SAI base pointer.
handle	Pointer to the sai_handle_t structure.

Overview

Typical use case

SAI Send/receive using an interrupt method

SAI Send/receive using a DMA method

Modules

Data Structures

Macros

Typedefs

Enumerations

Driver version

Initialization and deinitialization

Status

Interrupts

DMA Control

Bus Operations

Transactional

Data Structure Documentation

Data Fields

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation