S32 SDK

Detailed Description

This module covers the functionality of the Synchronous Audio Interface (SAI) peripheral driver.

The SAI driver implements communication using the SAI module in the S32K148 processor.

Features

How to integrate SAI in your application

In order to use the SAI driver it must be first initialized in either transmit or receive mode, using functions SAI_DRV_TxInit() or SAI_DRV_RxInit(). Once initialized, it cannot be initialized again for the same SAI module instance until it is de-initialized, using SAI_DRV_TxDeinit() or SAI_DRV_RxDeinit(). Different SAI module instances can function independently of each other.

In each mode (transmit/receive) are available two types of transfers: blocking and non-blocking. The functions which initiate blocking transfers will configure the time out for transmission. If time expires SAI_DRV_SendBlocking/SAI_DRV_ReceiveBlocking will return error and the transmission will be aborted.

Important Notes

Example code

/* sai0 configuration structure */
sai_user_config_t sai0_InitConfig0;
/* Driver state structure */
sai_state_t SAI0TxState;
/* Fill configuration structure with I2S settings */
SAI_DRV_GetDefaultConfig(&sai0_InitConfig0);
/* Provide two data buffer for left and right channel */
uint16_t* sendData[2U] = {LeftData, RightData};
/* Initialize transmitter for SAI0 */
SAI_DRV_TxInit(0U, &sai0_InitConfig0, &SAI0TxState);
/* Send blocking, timeout is 10ms */
status_t ret = SAI_DRV_SendBlocking(0U, (uint8_t**) sendData, sendBufferSize, 10U);

Data Structures

struct  sai_xfer_state_t
 Transmit or receive state. More...
 
struct  sai_state_t
 Structure for internal use. This structure is used by the driver for its internal logic. It must be provided by the application through the initialize functions, then it cannot be freed until the driver is de-initialized using Deinit functions. The application should make no assumptions about the content of this structure. More...
 
struct  sai_user_config_t
 User config structure. More...
 

Macros

#define SAI_CHANNEL_0   0x1
 
#define SAI_CHANNEL_1   0x2
 
#define SAI_CHANNEL_2   0x4
 
#define SAI_CHANNEL_3   0x8
 

Typedefs

typedef void(* sai_transfer_callback_t) (uint8_t channel, sai_report_type_t report, status_t status)
 Sai callback function type for nonblock transfer, also called to report events (sai_report_type_t). More...
 

Enumerations

enum  sai_report_type_t { SAI_FRAME_START = 0, SAI_RUN_ERROR, SAI_SYNC_ERROR, SAI_TRANSFER_COMPLETE }
 Report to enable. More...
 
enum  sai_transfer_type_t { SAI_INTERRUPT = 0U, SAI_DMA }
 Transfer type. More...
 
enum  sai_mux_mode_t { SAI_MUX_DISABLED = 0U, SAI_MUX_LINE = 1U, SAI_MUX_MEM = 2U }
 Data mux line or mux memory. More...
 
enum  sai_sync_mode_t { SAI_ASYNC = 0U, SAI_SYNC_WITH_OTHER = 1U }
 SAI run in sync or async mode. More...
 
enum  sai_master_clk_source_t { SAI_BUS_CLK = 0U, SAI_EXTERNAL_CLK = 1U, SAI_SOSC_CLK = 2U }
 Select master clock. More...
 
enum  sai_mask_mode_t { SAI_MASK_TRISTATE = 0U, SAI_MASK_ZERO = 1U }
 Data line state for masked word, or if data line is disabled. More...
 

SAI Driver

void SAI_DRV_TxInit (uint32_t instNum, const sai_user_config_t *saiUserConfig, sai_state_t *StateAlloc)
 Initialize the transmitter of driver. More...
 
void SAI_DRV_RxInit (uint32_t instNum, const sai_user_config_t *saiUserConfig, sai_state_t *StateAlloc)
 Initialize the receiver of driver. More...
 
void SAI_DRV_TxDeinit (uint32_t instNum)
 De-initialize transmitter. More...
 
void SAI_DRV_RxDeinit (uint32_t instNum)
 De-initialize receiver. More...
 
uint32_t SAI_DRV_TxGetBitClockFreq (uint32_t instNum)
 Return true bit clock frequency of transmitter. More...
 
uint32_t SAI_DRV_RxGetBitClockFreq (uint32_t instNum)
 Return true bit clock frequency of receiver. More...
 
uint32_t SAI_DRV_TxGetBitClockDiv (uint32_t instNum)
 Return true bit clock divisor of transmitter. More...
 
uint32_t SAI_DRV_RxGetBitClockDiv (uint32_t instNum)
 Return true bit clock divisor of receiver. More...
 
void SAI_DRV_TxSetNextMaskWords (uint32_t instNum, uint16_t Words)
 Set masked word index of subsequent frames for transmitter. More...
 
void SAI_DRV_RxSetNextMaskWords (uint32_t instNum, uint16_t Words)
 Set masked word index of subsequent frames for receiver. More...
 
status_t SAI_DRV_SendBlocking (uint32_t instNum, const uint8_t *data[], uint32_t count, uint32_t timeout)
 Send a block of data, return when transfer complete. More...
 
void SAI_DRV_Send (uint32_t instNum, const uint8_t *data[], uint32_t count)
 Send a block of data, return immidiately. More...
 
status_t SAI_DRV_GetSendingStatus (uint32_t instNum, uint32_t *countRemain)
 Get status of a non-blocking transfer. More...
 
void SAI_DRV_AbortSending (uint32_t instNum)
 Abort an ongoing transfer. More...
 
status_t SAI_DRV_ReceiveBlocking (uint32_t instNum, uint8_t *data[], uint32_t count, uint32_t timeout)
 Receive a block of data, return when transfer complete. More...
 
void SAI_DRV_Receive (uint32_t instNum, uint8_t *data[], uint32_t count)
 Receive a block of data, return immidiately. More...
 
status_t SAI_DRV_GetReceivingStatus (uint32_t instNum, uint32_t *countRemain)
 Get status of a non-blocking transfer. More...
 
void SAI_DRV_AbortReceiving (uint32_t instNum)
 Abort an ongoing transfer. More...
 
void SAI_DRV_GetDefaultConfig (sai_user_config_t *uc)
 Get default config structure for I2S standard. Init config structure for I2S interface: Interrupt mode, internal generated bit clock 1.4112 MHz, 16 bit word, 2 channel 1 data line (data line 0),. More...
 

Macro Definition Documentation

#define SAI_CHANNEL_0   0x1

Definition at line 46 of file sai_driver.h.

#define SAI_CHANNEL_1   0x2

Definition at line 47 of file sai_driver.h.

#define SAI_CHANNEL_2   0x4

Definition at line 48 of file sai_driver.h.

#define SAI_CHANNEL_3   0x8

Definition at line 49 of file sai_driver.h.

Typedef Documentation

typedef void(* sai_transfer_callback_t) (uint8_t channel, sai_report_type_t report, status_t status)

Sai callback function type for nonblock transfer, also called to report events (sai_report_type_t).

Definition at line 90 of file sai_driver.h.

Enumeration Type Documentation

Data line state for masked word, or if data line is disabled.

Enumerator
SAI_MASK_TRISTATE 

Line is in high z state

SAI_MASK_ZERO 

Line is output zero

Definition at line 134 of file sai_driver.h.

Select master clock.

Enumerator
SAI_BUS_CLK 

Master clock is module bus clock

SAI_EXTERNAL_CLK 

Master clock is from external

SAI_SOSC_CLK 

Master clock is system sosc clock

Definition at line 125 of file sai_driver.h.

Data mux line or mux memory.

Enumerator
SAI_MUX_DISABLED 

Each data line is a channel, uses a seperate memory block

SAI_MUX_LINE 

Words on data line is alternated between channels, each channel data is a seperate memory block

SAI_MUX_MEM 

Words in memory block is alternated between channels, each channel data is on a seperate data line.

Definition at line 81 of file sai_driver.h.

Report to enable.

Enumerator
SAI_FRAME_START 

Indicate a frame start

SAI_RUN_ERROR 

Overrun/underrun error

SAI_SYNC_ERROR 

Frame sync error

SAI_TRANSFER_COMPLETE 

Non blocking transfer completed

Definition at line 63 of file sai_driver.h.

SAI run in sync or async mode.

Enumerator
SAI_ASYNC 

Independent clock

SAI_SYNC_WITH_OTHER 

Bit clock and frame sync is taken from transmitter/receiver

Definition at line 117 of file sai_driver.h.

Transfer type.

Enumerator
SAI_INTERRUPT 

Transfer type is interrupt

SAI_DMA 

Transfer type is DMA

Definition at line 73 of file sai_driver.h.

Function Documentation

void SAI_DRV_AbortReceiving ( uint32_t  instNum)

Abort an ongoing transfer.

Parameters
[in]instNumPeripheral instance number
void SAI_DRV_AbortSending ( uint32_t  instNum)

Abort an ongoing transfer.

Parameters
[in]instNumPeripheral instance number
void SAI_DRV_GetDefaultConfig ( sai_user_config_t uc)

Get default config structure for I2S standard. Init config structure for I2S interface: Interrupt mode, internal generated bit clock 1.4112 MHz, 16 bit word, 2 channel 1 data line (data line 0),.

Parameters
[out]ucPointer to config structure to fill in
status_t SAI_DRV_GetReceivingStatus ( uint32_t  instNum,
uint32_t *  countRemain 
)

Get status of a non-blocking transfer.

Parameters
[in]instNumPeripheral instance number
[out]countRemainNumber of elements remain for each channel. This parameter can be NULL
Returns
Status of the transfer, can be success, aborted or busy. Note that aborted status can imply a timed out blocking transfer, not only user abort.
status_t SAI_DRV_GetSendingStatus ( uint32_t  instNum,
uint32_t *  countRemain 
)

Get status of a non-blocking transfer.

Parameters
[in]instNumPeripheral instance number
[out]countRemainNumber of elements remain for each channel. This parameter can be NULL
Returns
Status of the transfer, can be success, aborted or busy. Note that aborted status can imply a timed out blocking transfer, not only user abort.
void SAI_DRV_Receive ( uint32_t  instNum,
uint8_t *  data[],
uint32_t  count 
)

Receive a block of data, return immidiately.

When transfer completed, the callback function will be executed. User should use this callback function to immidiately start another transfer to avoid data overrun error.

Parameters
[in]instNumPeripheral instance number
[out]dataArray of pointer to each data block to transfer, each data block corresponds to an enabled channels If mux memory is selected, only first data block is used
[in]countNumber of elements to transfer for each channel
status_t SAI_DRV_ReceiveBlocking ( uint32_t  instNum,
uint8_t *  data[],
uint32_t  count,
uint32_t  timeout 
)

Receive a block of data, return when transfer complete.

Should be called immidiately after a transfer complete to avoid data overrun error.

Parameters
[in]instNumPeripheral instance number
[out]dataArray of pointer to each data block to transfer, each data block corresponds to an enabled channels If mux memory is selected, only first data block is used
[in]countNumber of elements to transfer for each channel
[in]timeoutTimeout to return when transfer take too long.
Returns
Success, error or timeout status.
void SAI_DRV_RxDeinit ( uint32_t  instNum)

De-initialize receiver.

This function de-initializes driver. The driver can't be used again until reinitialized. The context structure is no longer needed by the driver and can be freed after calling this function.

Parameters
[in]instNumPeripheral instance number
uint32_t SAI_DRV_RxGetBitClockDiv ( uint32_t  instNum)

Return true bit clock divisor of receiver.

Only used when bit clock is internal and master clock is external

Parameters
[in]instNumPeripheral instance number
Returns
Divisor factor
uint32_t SAI_DRV_RxGetBitClockFreq ( uint32_t  instNum)

Return true bit clock frequency of receiver.

Only used when master clock and bit clock is internal

Parameters
[in]instNumPeripheral instance number
Returns
Frequency in hertz
void SAI_DRV_RxInit ( uint32_t  instNum,
const sai_user_config_t saiUserConfig,
sai_state_t StateAlloc 
)

Initialize the receiver of driver.

Parameters
[in]instNumPeripheral instance number
[in]saiUserConfigPointer to the user configuration structure. The function reads configuration data from this structure and initializes the driver accordingly. The application may free this structure after the function returns.
[in]StateAllocPointer to the state structure. The driver uses this memory area for its internal logic. The application must make no assumptions about the content of this structure, and must not free this memory until the driver is de-initialized.
void SAI_DRV_RxSetNextMaskWords ( uint32_t  instNum,
uint16_t  Words 
)

Set masked word index of subsequent frames for receiver.

Set masked words of subsequent frames. Each bit is a masked word. Should be called in frame start event callback or in four bit clock cycles after Rx init.

Parameters
[in]instNumPeripheral instance number
[in]WordIndexWord index to mask
void SAI_DRV_Send ( uint32_t  instNum,
const uint8_t *  data[],
uint32_t  count 
)

Send a block of data, return immidiately.

When transfer completed, the callback function will be executed. User should use this callback function to immidiately start an other transfer to avoid data underrun error.

Parameters
[in]instNumPeripheral instance number
[in]dataArray of pointer to each data block to transfer, each data block corresponds to an enabled channels If mux memory is selected, only first data block is used
[in]countNumber of elements to transfer for each channel
status_t SAI_DRV_SendBlocking ( uint32_t  instNum,
const uint8_t *  data[],
uint32_t  count,
uint32_t  timeout 
)

Send a block of data, return when transfer complete.

Should be called immidiately after a transfer complete to avoid data underrun error.

Parameters
[in]instNumPeripheral instance number
[in]dataArray of pointer to each data block to transfer, each data block corresponds to an enabled channels If mux memory is selected, only first data block is used
[in]countNumber of elements to transfer for each channel
[in]timeoutTimeout to return when transfer take too long.
Returns
Success, error or timeout status.
void SAI_DRV_TxDeinit ( uint32_t  instNum)

De-initialize transmitter.

This function de-initializes driver. The driver can't be used again until reinitialized. The context structure is no longer needed by the driver and can be freed after calling this function.

Parameters
[in]instNumPeripheral instance number
uint32_t SAI_DRV_TxGetBitClockDiv ( uint32_t  instNum)

Return true bit clock divisor of transmitter.

Only used when bit clock is internal and master clock is external

Parameters
[in]instNumPeripheral instance number
Returns
Frequency in hertz
uint32_t SAI_DRV_TxGetBitClockFreq ( uint32_t  instNum)

Return true bit clock frequency of transmitter.

Only used when master clock and bit clock is internal

Parameters
[in]instNumPeripheral instance number
void SAI_DRV_TxInit ( uint32_t  instNum,
const sai_user_config_t saiUserConfig,
sai_state_t StateAlloc 
)

Initialize the transmitter of driver.

Parameters
[in]instNumPeripheral instance number
[in]saiUserConfigPointer to the user configuration structure. The function reads configuration data from this structure and initializes the driver accordingly. The application may free this structure after the function returns.
[in]StateAllocPointer to the state structure. The driver uses this memory area for its internal logic. The application must make no assumptions about the content of this structure, and must not free this memory until the driver is de-initialized.
void SAI_DRV_TxSetNextMaskWords ( uint32_t  instNum,
uint16_t  Words 
)

Set masked word index of subsequent frames for transmitter.

Each bit is a masked word. Should be called in frame start event callback or in four bit clock cycles after Tx init.

Parameters
[in]instNumPeripheral instance number
[in]WordIndexWord index to mask
Returns
Divisor factor