Kinetis SDK v.2.0 API Reference Manual  Rev. 0
Freescale Semiconductor, Inc.
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
SAI: Serial Audio Interface

Overview

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

Overview

SAI driver includes functional APIs and transactional APIs.

Functional APIs are feature/property target low level APIs. Functional APIs can be used for SAI initialization/configuration/operation for optimization/customization purpose. 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 are transaction 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

sai_handle_t g_saiTxHandle;
sai_config_t user_config;
sai_transfer_t sendXfer;
volatile bool txFinished;
volatile bool rxFinished;
const uint8_t sendData[] = [......];
void SAI_UserCallback(sai_handle_t *handle, status_t status, void *userData)
{
userData = userData;
if (kStatus_SAI_TxIdle == status)
{
txFinished = true;
}
}
void main(void)
{
//...
SAI_TxGetDefaultConfig(&user_config);
SAI_TxInit(SAI0, &user_config);
SAI_TransferTxCreateHandle(SAI0, &g_saiHandle, SAI_UserCallback, NULL);
//Configure sai format
SAI_TransferTxSetTransferFormat(SAI0, &g_saiHandle, mclkSource, mclk);
// Prepare to send.
sendXfer.data = sendData
sendXfer.dataSize = sizeof(sendData)/sizeof(sendData[0]);
txFinished = false;
// Send out.
SAI_TransferSendNonBlocking(SAI0, &g_saiHandle, &sendXfer);
// Wait send finished.
while (!txFinished)
{
}
// ...
}

SAI Send/receive using a DMA method

sai_handle_t g_saiHandle;
dma_handle_t g_saiTxDmaHandle;
dma_handle_t g_saiRxDmaHandle;
sai_config_t user_config;
sai_transfer_t sendXfer;
volatile bool txFinished;
uint8_t sendData[] = ...;
void SAI_UserCallback(sai_handle_t *handle, status_t status, void *userData)
{
userData = userData;
if (kStatus_SAI_TxIdle == status)
{
txFinished = true;
}
}
void main(void)
{
//...
SAI_TxGetDefaultConfig(&user_config);
SAI_TxInit(SAI0, &user_config);
// Sets up the DMA.
DMAMUX_Init(DMAMUX0);
DMAMUX_SetSource(DMAMUX0, SAI_TX_DMA_CHANNEL, SAI_TX_DMA_REQUEST);
DMAMUX_EnableChannel(DMAMUX0, SAI_TX_DMA_CHANNEL);
DMA_Init(DMA0);
/* Creates the DMA handle.
DMA_CreateHandle(&g_saiTxDmaHandle, DMA0, SAI_TX_DMA_CHANNEL);
SAI_TransferTxCreateHandleDMA(SAI0, &g_saiTxDmaHandle, SAI_UserCallback, NULL);
// Prepares to send.
sendXfer.data = sendData
sendXfer.dataSize = sizeof(sendData)/sizeof(sendData[0]);
txFinished = false;
// Sends out.
SAI_TransferSendDMA(&g_saiHandle, &sendXfer);
// Waits for send to complete.
while (!txFinished)
{
}
// ...
}

Modules

 SAI DMA Driver
 
 SAI eDMA Driver
 

Files

file  fsl_sai.h
 

Data Structures

struct  sai_config_t
 SAI user configure 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_MonoLeft,
  kSAI_MonoRight
}
 Mono or stereo audio format. 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
}
 The SAI interrupt enable flag. More...
 
enum  _sai_dma_enable_t { kSAI_FIFOWarningDMAEnable = I2S_TCSR_FWDE_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_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_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, 0))
 Version 2.1.0.
 

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 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 SAI Tx. More...
 
void SAI_RxEnable (I2S_Type *base, bool enable)
 Enables/disables 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...
 

Interrupts

static void SAI_TxEnableInterrupts (I2S_Type *base, uint32_t mask)
 Enables SAI Tx interrupt requests. More...
 
static void SAI_RxEnableInterrupts (I2S_Type *base, uint32_t mask)
 Enables SAI Rx interrupt requests. More...
 
static void SAI_TxDisableInterrupts (I2S_Type *base, uint32_t mask)
 Disables SAI Tx interrupt requests. More...
 
static void SAI_RxDisableInterrupts (I2S_Type *base, uint32_t mask)
 Disables SAI Rx interrupt requests. More...
 

DMA Control

static void SAI_TxEnableDMA (I2S_Type *base, uint32_t mask, bool enable)
 Enables/disables SAI Tx DMA requests. More...
 
static void SAI_RxEnableDMA (I2S_Type *base, uint32_t mask, bool enable)
 Enables/disables 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 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 the current IRQ 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/32bits.
 
sai_mono_stereo_t stereo
 Mono or stereo.
 
uint32_t masterClockHz
 Master clock frequency in Hz.
 
uint8_t channel
 Data channel used in transfer. More...
 
sai_protocol_t protocol
 Which audio protocol used.
 

Field Documentation

uint8_t sai_transfer_format_t::channel
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/32bits.
 
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.
 

Macro Definition Documentation

#define SAI_XFER_QUEUE_SIZE   (4)

Enumeration Type Documentation

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.

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.

Enumerator
kSAI_Master 

Master mode.

kSAI_Slave 

Slave mode.

Enumerator
kSAI_Stereo 

Stereo sound.

kSAI_MonoLeft 

Only left channel have sound.

kSAI_MonoRight 

Only Right channel have sound.

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.

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.

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.

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.

Enumerator
kSAI_FIFOWarningDMAEnable 

FIFO warning 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_FIFOWarningFlag 

FIFO warning flag.

Enumerator
kSAI_ResetTypeSoftware 

Software reset, reset the logic state.

kSAI_ResetTypeFIFO 

FIFO reset, reset the FIFO read and write pointer.

kSAI_ResetAll 

All reset.

Enumerator
kSAI_SampleRate8KHz 

Sample rate 8000Hz.

kSAI_SampleRate11025Hz 

Sample rate 11025Hz.

kSAI_SampleRate12KHz 

Sample rate 12000Hz.

kSAI_SampleRate16KHz 

Sample rate 16000Hz.

kSAI_SampleRate22050Hz 

Sample rate 22050Hz.

kSAI_SampleRate24KHz 

Sample rate 24000Hz.

kSAI_SampleRate32KHz 

Sample rate 32000Hz.

kSAI_SampleRate44100Hz 

Sample rate 44100Hz.

kSAI_SampleRate48KHz 

Sample rate 48000Hz.

kSAI_SampleRate96KHz 

Sample rate 96000Hz.

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
baseSAI base pointer
configSAI configure 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
baseSAI base pointer
configSAI configure 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(). Example:

Parameters
configpointer 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(). Example:

Parameters
configpointer 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
baseSAI 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
baseSAI 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
baseSAI base pointer
void SAI_TxEnable ( I2S_Type *  base,
bool  enable 
)
Parameters
baseSAI base pointer
enableTrue means enable SAI Tx, false means disable.
void SAI_RxEnable ( I2S_Type *  base,
bool  enable 
)
Parameters
baseSAI base pointer
enableTrue means enable SAI Rx, false means disable.
static uint32_t SAI_TxGetStatusFlag ( I2S_Type *  base)
inlinestatic
Parameters
baseSAI 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
baseSAI base pointer
maskState 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
baseSAI 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
baseSAI base pointer
maskState mask. It can be a combination of the following source if defined:
  • kSAI_WordStartFlag
  • kSAI_SyncErrorFlag
  • kSAI_FIFOErrorFlag
static void SAI_TxEnableInterrupts ( I2S_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseSAI base pointer
maskinterrupt source The parameter can be a combination of the following source if defined:
  • kSAI_WordStartInterruptEnable
  • kSAI_SyncErrorInterruptEnable
  • kSAI_FIFOWarningInterruptEnable
  • kSAI_FIFORequestInterruptEnable
  • kSAI_FIFOErrorInterruptEnable
static void SAI_RxEnableInterrupts ( I2S_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseSAI base pointer
maskinterrupt source The parameter can be a combination of the following source if defined:
  • kSAI_WordStartInterruptEnable
  • kSAI_SyncErrorInterruptEnable
  • kSAI_FIFOWarningInterruptEnable
  • kSAI_FIFORequestInterruptEnable
  • kSAI_FIFOErrorInterruptEnable
static void SAI_TxDisableInterrupts ( I2S_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseSAI base pointer
maskinterrupt source The parameter can be a combination of the following source if defined:
  • kSAI_WordStartInterruptEnable
  • kSAI_SyncErrorInterruptEnable
  • kSAI_FIFOWarningInterruptEnable
  • kSAI_FIFORequestInterruptEnable
  • kSAI_FIFOErrorInterruptEnable
static void SAI_RxDisableInterrupts ( I2S_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseSAI base pointer
maskinterrupt source The parameter can be a combination of the following source 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
baseSAI base pointer
maskDMA source The parameter can be combination of the following source if defined:
  • kSAI_FIFOWarningDMAEnable
  • kSAI_FIFORequestDMAEnable
enableTrue means enable DMA, false means disable DMA.
static void SAI_RxEnableDMA ( I2S_Type *  base,
uint32_t  mask,
bool  enable 
)
inlinestatic
Parameters
baseSAI base pointer
maskDMA source The parameter can be a combination of the following source if defined:
  • kSAI_FIFOWarningDMAEnable
  • kSAI_FIFORequestDMAEnable
enableTrue 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 SAI DMA transfer configuration.

Parameters
baseSAI base pointer.
channelWhich 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 SAI DMA transfer configuration.

Parameters
baseSAI base pointer.
channelWhich 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
baseSAI base pointer.
formatPointer to SAI audio data format structure.
mclkSourceClockHzSAI master clock source frequency in Hz.
bclkSourceClockHzSAI bit clock source frequency in Hz. If bit clock source is master clock, this value should equals to masterClockHz in format.
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
baseSAI base pointer.
formatPointer to SAI audio data format structure.
mclkSourceClockHzSAI master clock source frequency in Hz.
bclkSourceClockHzSAI bit clock source frequency in Hz. If bit clock source is master clock, this value should equals to masterClockHz in format.
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
baseSAI base pointer.
channelData channel used.
bitWidthHow many bits in a audio word, usually 8/16/24/32 bits.
bufferPointer to the data to be written.
sizeBytes to be written.
static void SAI_WriteData ( I2S_Type *  base,
uint32_t  channel,
uint32_t  data 
)
inlinestatic
Parameters
baseSAI base pointer.
channelData channel used.
dataData 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
baseSAI base pointer.
channelData channel used.
bitWidthHow many bits in a audio word, usually 8/16/24/32 bits.
bufferPointer to the data to be read.
sizeBytes to be read.
static uint32_t SAI_ReadData ( I2S_Type *  base,
uint32_t  channel 
)
inlinestatic
Parameters
baseSAI base pointer.
channelData 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 SAI Tx transactional APIs. Call this function one time to get the handle initialized.

Parameters
baseSAI base pointer
handleSAI handle pointer.
callbackpointer to user callback function
userDatauser 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 SAI Rx transactional APIs. Call this function one time to get the handle initialized.

Parameters
baseSAI base pointer.
handleSAI handle pointer.
callbackpointer to user callback function
userDatauser 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
baseSAI base pointer.
handleSAI handle pointer.
formatPointer to SAI audio data format structure.
mclkSourceClockHzSAI master clock source frequency in Hz.
bclkSourceClockHzSAI bit clock source frequency in Hz. If a bit clock source is a master clock, this value should equal to masterClockHz in format.
Returns
Status of this function. Return value is one of 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
baseSAI base pointer.
handleSAI handle pointer.
formatPointer to SAI audio data format structure.
mclkSourceClockHzSAI master clock source frequency in Hz.
bclkSourceClockHzSAI bit clock source frequency in Hz. If bit clock source is master clock, this value should equals to 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
baseSAI base pointer
handlepointer to sai_handle_t structure which stores the transfer state
xferpointer to sai_transfer_t structure
Return values
kStatus_SuccessSuccessfully started the data receive.
kStatus_SAI_TxBusyPrevious receive still not finished.
kStatus_InvalidArgumentThe 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
baseSAI base pointer
handlepointer to sai_handle_t structure which stores the transfer state
xferpointer to sai_transfer_t structure
Return values
kStatus_SuccessSuccessfully started the data receive.
kStatus_SAI_RxBusyPrevious receive still not finished.
kStatus_InvalidArgumentThe input parameter is invalid.
status_t SAI_TransferGetSendCount ( I2S_Type *  base,
sai_handle_t *  handle,
size_t *  count 
)
Parameters
baseSAI base pointer.
handlepointer to sai_handle_t structure which stores the transfer state.
countBytes count sent.
Return values
kStatus_SuccessSucceed get the transfer count.
kStatus_NoTransferInProgressThere is not a non-blocking transaction currently in progress.
status_t SAI_TransferGetReceiveCount ( I2S_Type *  base,
sai_handle_t *  handle,
size_t *  count 
)
Parameters
baseSAI base pointer.
handlepointer to sai_handle_t structure which stores the transfer state.
countBytes count received.
Return values
kStatus_SuccessSucceed get the transfer count.
kStatus_NoTransferInProgressThere 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
baseSAI base pointer.
handlepointer to 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 any time when an interrupt non-blocking transfer initiates to abort the transfer early.
Parameters
baseSAI base pointer
handlepointer to sai_handle_t structure which stores the transfer state.
void SAI_TransferTxHandleIRQ ( I2S_Type *  base,
sai_handle_t *  handle 
)
Parameters
baseSAI base pointer.
handlepointer to sai_handle_t structure.
void SAI_TransferRxHandleIRQ ( I2S_Type *  base,
sai_handle_t *  handle 
)
Parameters
baseSAI base pointer.
handlepointer to sai_handle_t structure.