Overview

This section describes the programming interface of the SAI Peripheral driver. The SAI driver initializes, configures, starts, and stops the SAI. The SAI driver also implements configuration functions, sends, and receives data.

SAI Initialization

To initialize SAI, call the SAI_DRV_TxInit() or SAI_DRV_RxInit() functions and pass the SAI instance and SAI configuration structure parameters. The function opens the clock gate and initializes the SAI modules according to the structure information.

SAI Configuration

Configuration is implemented by the SAI_DRV_TxConfigDataFormat() function. To use this function, transfer the audio data format to the SAI module.

SAI Call diagram

To use the SAI driver, follow these steps and use transmit as an example:

Initialize the SAI module by calling the SAI_DRV_TxInit() function.
Configure the audio data features of SAI by calling the SAI_DRV_TxConfigDataFormat() function.
Send/receive data by calling the SAI_DRV_SendDataInt() or the SAI_DRV_SendDataDma() functions.
Stop transmit or receive by calling the SAI_DRV_TxStopModule() or the SAI_DRV_RxStopModule() function.
Shut down the SAI module by calling the SAI_DRV_TxDeinit() function.

This is example code to initialize and configure the SAI driver in DMA mode:

//Initialize configuration structure.
sai_user_config_t tx_config;
tx_config.bus_type = kSaiBusI2SLeft;
tx_config.channel = 0;
tx_config.slave_master = kSaiMaster;
tx_config.sync_mode = kSaiModeAsync;
tx_config.bclk_source = kSaiBclkSourceMclkDiv;
tx_config.mclk_source = kSaiMclkSourceSysclk;
tx_config.watermark = 4;
tx_config.dma_source = kDmaRequestMux0I2S0Tx;
//SAI state, used for driver internal logic.
sai_state_t tx_state;
//Data format of audio data
audio_data_format_t format;
format.bits = 16;
format.sample_rate = 44100;
format.mclk = 384 * format->sample_rate;
format.mono_stereo = kSaiStereo;
//Initialize SAI transmit.
SAI_DRV_TxInit(instance, &tx_config, &tx_state);
//Configure the data format of SAI transmit.
SAI_DRV_TxConfigDataFormat(instance,&format);
//option: register callback functions for finished transfer
SAI_DRV_TxRegisterCallback(instance, callback, callback_param);
//start send data
SAI_DRV_SendDataDma(instance, addr, len);
.....
//Stop transmit.
SAI_DRV_TxStopModule(instance);
//De-initialize transmit.
SAI_DRv_TxDeinit(instance);

When using DMA to transfer data, ensure that data is consistent because of cache for memory. In other words, when reading data from memory, the application should ensure that data from or to the memory device is not cached.

Files
file	fsl_sai_driver.h

Data Structures
struct	sai_data_format_t
	Defines the PCM data format. More...

struct	sai_state_t
	SAI internal state Users should allocate and transfer memory to the PD during the initialization function. More...

struct	sai_user_config_t
	The description structure for the SAI transmit/receive module. More...

Typedefs
typedef void(*	sai_callback_t )(void *parameter)
	SAI callback function.

Enumerations
enum	sai_status_t
	Status structure for SAI.

Functions
sai_status_t	SAI_DRV_TxInit (uint32_t instance, sai_user_config_t config, sai_state_t state)
	Initializes the SAI module. More...

sai_status_t	SAI_DRV_RxInit (uint32_t instance, sai_user_config_t config, sai_state_t state)
	Initializes the SAI receive module. More...

void	SAI_DRV_TxGetDefaultSetting (sai_user_config_t *config)
	Gets the default setting of the user configuration. More...

void	SAI_DRV_RxGetDefaultSetting (sai_user_config_t *config)
	Gets the default settings of the user configuration. More...

sai_status_t	SAI_DRV_TxDeinit (uint32_t instance)
	De-initializes the SAI transmit module. More...

sai_status_t	SAI_DRV_RxDeinit (uint32_t instance)
	Deinitializes the SAI receive module. More...

sai_status_t	SAI_DRV_TxConfigDataFormat (uint32_t instance, sai_data_format_t *format)
	Configures the audio data format of the transmit. More...

sai_status_t	SAI_DRV_RxConfigDataFormat (uint32_t instance, sai_data_format_t *format)
	Configures the audio data format of the receive. More...

void	SAI_DRV_TxStartModule (uint32_t instance)
	Starts the transmit transfer. More...

void	SAI_DRV_RxStartModule (uint32_t instance)
	Starts the receive process. More...

void	SAI_DRV_TxStopModule (uint32_t instance)
	Stops writing data to FIFO to disable the DMA or the interrupt request bit. More...

void	SAI_DRV_RxStopModule (uint32_t instance)
	Stops receiving data from FIFO to disable the DMA or the interrupt request bit. More...

void	SAI_DRV_TxSetIntCmd (uint32_t instance, bool enable)
	Enables or disables the transmit interrupt source. More...

void	SAI_DRV_RxSetIntCmd (uint32_t instance, bool enable)
	Enables or disables the receive interrupt source. More...

void	SAI_DRV_TxSetDmaCmd (uint32_t instance, bool enable)
	Enables or disables the transmit DMA source. More...

void	SAI_DRV_RxSetDmaCmd (uint32_t instance, bool enable)
	Enables or disables the receive interrupt source. More...

static uint32_t	SAI_DRV_TxGetFifoAddr (uint32_t instance, uint32_t fifo_channel)
	Gets the transmit FIFO address of the data channel. More...

static uint32_t	SAI_DRV_RxGetFifoAddr (uint32_t instance, uint32_t fifo_channel)
	Gets the receive FIFO address of the data channel. More...

uint32_t	SAI_DRV_SendDataInt (uint32_t instance, uint8_t *addr, uint32_t len)
	Sends data using interrupts. More...

uint32_t	SAI_DRV_ReceiveDataInt (uint32_t instance, uint8_t *addr, uint32_t len)
	Receives data a certain length using interrupt way. More...

uint32_t	SAI_DRV_SendDataDma (uint32_t instance, uint8_t *addr, uint32_t len)
	Sends data of a certain length using the DMA method. More...

uint32_t	SAI_DRV_ReceiveDataDma (uint32_t instance, uint8_t *addr, uint32_t len)
	Receives data using the DMA. More...

void	SAI_DRV_TxRegisterCallback (uint32_t instance, sai_callback_t callback, void *callback_param)
	Registers the callback function after completing a send. More...

void	SAI_DRV_RxRegisterCallback (uint32_t instance, sai_callback_t callback, void *callback_param)
	Registers the callback function after completing a receive. More...

void	SAI_DRV_TxIRQHandler (uint32_t instance)
	Default SAI transmit interrupt handler. More...

void	SAI_DRV_RxIRQHandler (uint32_t instance)
	Default SAI receive interrupt handler. More...

Data Structure Documentation

struct sai_data_format_t

Data Fields
uint32_t	sample_rate
	Sample rate of the PCM file.

uint32_t	mclk
	Master clock frequency.

uint8_t	bits
	Number of bits in a word.

sai_mono_stereo_t	mono_stereo
	Number of words in a frame.

struct sai_state_t

Note: During the SAI execution, users should not free the state. Otherwise, the driver malfunctions.

struct sai_user_config_t

Data Fields
sai_mclk_source_t	mclk_source
	Master clock source.

uint8_t	channel
	Which FIFO is used to transfer.

sai_sync_mode_t	sync_mode
	Synchronous or asynchronous.

sai_protocol_t	protocol
	I2S left, I2S right, or I2S type.

sai_master_slave_t	slave_master
	Master or slave.

sai_bclk_source_t	bclk_source
	Bit clock from master clock or other modules.

uint32_t	dma_source
	The DMA request source.

Function Documentation

sai_status_t SAI_DRV_TxInit	(	uint32_t	instance,
		sai_user_config_t *	config,
		sai_state_t *	state
	)

This function initializes the SAI registers according to the configuration structure. This function also initializes the basic SAI settings including board-relevant settings. Notice: This function does not initialize an entire SAI instance. It only initializes the transmit according to the value in the handler.

Parameters

instance	SAI module instance.
config	The configuration structure of SAI.
state	Pointer of SAI run state structure.

Returns: Return kStatus_SAI_Success while the initialize success and kStatus_SAI_Fail if failed.

sai_status_t SAI_DRV_RxInit	(	uint32_t	instance,
		sai_user_config_t *	config,
		sai_state_t *	state
	)

This function initializes the SAI registers according to the configuration structure. This function also initializes the basic SAI settings including board-relevant settings. Note that this function does not initialize an entire SAI instance. This function only initializes the transmit according to the value in the handler.

Parameters

instance	SAI module instance.
config	The configuration structure of SAI.
state	Pointer of SAI run state structure.

Returns: Return kStatus_SAI_Success while the initialize success and kStatus_SAI_Fail if failed.

void SAI_DRV_TxGetDefaultSetting ( sai_user_config_t * config )

The default settings for SAI are:

Audio protocol is I2S format
Watermark is 4
Use SAI0
Channel is channel0
SAI as master
MCLK from system core clock
Transmit is in an asynchronous mode
Parameters

config Pointer of user configure structure.

void SAI_DRV_RxGetDefaultSetting ( sai_user_config_t * config )

The default settings for SAI are: Audio protocol is I2S format Watermark is 4 Use SAI0 Data channel is channel0 SAI as master MCLK from system core clock Receive is in synchronous way

Parameters

config Pointer of user configure structure.

sai_status_t SAI_DRV_TxDeinit ( uint32_t instance )

This function closes the SAI transmit device, but does not close the entire SAI instance. It only closes the clock gate while both transmit and receive are closed in the same instance.

Parameters

instance SAI module instance.

Returns: Return kStatus_SAI_Success while the process success and kStatus_SAI_Fail if failed.

sai_status_t SAI_DRV_RxDeinit ( uint32_t instance )

This function closes the SAI receive device, but does not close the entire SAI instance. It only closes the clock gate while both transmit and receive are closed in the same instance.

Parameters

instance SAI module instance.

Returns: Return kStatus_SAI_Success while the process success and kStatus_SAI_Fail if failed.

sai_status_t SAI_DRV_TxConfigDataFormat	(	uint32_t	instance,
		sai_data_format_t *	format
	)

The function configures an audio sample rate, data bits, and a channel number.

Parameters

instance	SAI module instance.
format	PCM data format structure pointer.

Returns: Return kStatus_SAI_Success while the process success and kStatus_SAI_Fail if failed.

sai_status_t SAI_DRV_RxConfigDataFormat	(	uint32_t	instance,
		sai_data_format_t *	format
	)

The function configures an audio sample rate, data bits, and a channel number.

Parameters

instance	SAI module instance of the SAI module.
format	PCM data format structure pointer.

Returns: Return kStatus_SAI_Success while the process success and kStatus_SAI_Fail if failed.

void SAI_DRV_TxStartModule ( uint32_t instance )

The function enables the interrupt/DMA request source and the transmit channel.

Parameters

instance SAI module instance.

void SAI_DRV_RxStartModule ( uint32_t instance )

The function enables the interrupt/DMA request source and the transmit channel.

Parameters

instance SAI module instance of the SAI module.

void SAI_DRV_TxStopModule ( uint32_t instance )

This function provides the method to pause writing data.

Parameters

instance SAI module instance.

void SAI_DRV_RxStopModule ( uint32_t instance )

This function provides the method to pause writing data.

Parameters

instance SAI module instance.

void SAI_DRV_TxSetIntCmd	(	uint32_t	instance,
		bool	enable
	)

Parameters

instance	SAI module instance.
enable	True means enable interrupt source, false means disable interrupt source.

void SAI_DRV_RxSetIntCmd	(	uint32_t	instance,
		bool	enable
	)

Parameters

instance	SAI module instance.
enable	True means enable interrupt source, false means disable interrupt source.

void SAI_DRV_TxSetDmaCmd	(	uint32_t	instance,
		bool	enable
	)

Parameters

instance	SAI module instance.
enable	True means enable DMA source, false means disable DMA source.

void SAI_DRV_RxSetDmaCmd	(	uint32_t	instance,
		bool	enable
	)

Parameters

instance	SAI module instance.
enable	True means enable DMA source, false means disable DMA source.

static uint32_t SAI_DRV_TxGetFifoAddr	(	uint32_t	instance,
		uint32_t	fifo_channel
	)

inlinestatic

This function is mainly used for the DMA settings which the DMA configuration needs for the SAI source/destination address.

Parameters

instance	SAI module instance of the SAI module.
fifo_channel	FIFO channel of SAI transmit.

Returns: Returns the address of the data channel FIFO.

static uint32_t SAI_DRV_RxGetFifoAddr	(	uint32_t	instance,
		uint32_t	fifo_channel
	)

inlinestatic

This function is mainly used for the DMA settings which the DMA configuration needs for the SAI source/destination address.

Parameters

instance	SAI module instance of the SAI module.
fifo_channel	FIFO channel of SAI receive.

Returns: Returns the address of the data channel FIFO.

uint32_t SAI_DRV_SendDataInt	(	uint32_t	instance,
		uint8_t *	addr,
		uint32_t	len
	)

This function sends data to the transmit FIFO. This function starts the transfer, and, while finishing the transfer, calls the callback function registered by users. This function is an un-blocking function.

Parameters

instance	SAI module instance of the SAI module.
addr	Address of the data which needs to be transferred.
len	The number of bytes which need to be sent.

Returns: Returns the length which was sent.

uint32_t SAI_DRV_ReceiveDataInt	(	uint32_t	instance,
		uint8_t *	addr,
		uint32_t	len
	)

This function receives the data from the receive FIFO. This function starts the transfer, and, while finishing the transfer, calls the callback function registered by the user. This function is an un-blocking function.

Parameters

instance	SAI module instance.
addr	Address of the data which needs to be transferred.
len	The number of bytes to receive.

Returns: Returns the length received.

uint32_t SAI_DRV_SendDataDma	(	uint32_t	instance,
		uint8_t *	addr,
		uint32_t	len
	)

This function sends the data to the transmit FIFO. It starts the transfer, and, while finishing the transfer, calls the callback function registered by users. This function is an a-sync function.

Parameters

instance	SAI module instance of the SAI module.
addr	Address of the data which needs to be transferred.
len	The number of bytes which need to be sent.

Returns: Returns the length which was sent.

uint32_t SAI_DRV_ReceiveDataDma	(	uint32_t	instance,
		uint8_t *	addr,
		uint32_t	len
	)

This function receives the data from the receive FIFO. It starts the transfer, and, while finishing the transfer, calls the callback function registered by the user. This function is an a-sync function.

Parameters

instance	SAI module instance.
addr	Address of the data which needs to be transferred.
len	The number of bytes to receive.

Returns: Returns the length received.

void SAI_DRV_TxRegisterCallback	(	uint32_t	instance,
		sai_callback_t	callback,
		void *	callback_param
	)

This function tells the SAI which function needs to be called after a period length sending. This callback function is used for non-blocking sending.

Parameters

instance	SAI module instance.
callback	Callback function defined by users.
callback_param	The parameter of the callback function.

void SAI_DRV_RxRegisterCallback	(	uint32_t	instance,
		sai_callback_t	callback,
		void *	callback_param
	)

This function tells the SAI which function needs to be called after a period length receive. This callback function is used for non-blocking receiving.

Parameters

instance	SAI module instance.
callback	Callback function defined by users.
callback_param	The parameter of the callback function.

void SAI_DRV_TxIRQHandler ( uint32_t instance )

This function sends data in the interrupt and checks the FIFO error.

Parameters

instance SAI module instance.

void SAI_DRV_RxIRQHandler ( uint32_t instance )

This function receives data in the interrupt and checks the FIFO error.

Parameters

instance SAI module instance.

Overview

SAI Initialization

SAI Configuration

SAI Call diagram

Files

Data Structures

Typedefs

Enumerations

Functions

Data Structure Documentation

Data Fields

Data Fields

Function Documentation