| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
SAI peripheral driver
Synchronous Audio Interface (SAI)

The section describes the programming interface of the SAI Peripheral driver. More...

## Data Structures
struct | sai_user_config_t
| The description structure for the SAI TX/RX module. More...
struct | sai_data_format_t
| Defines the PCM data format. More...
struct | sai_handler_t
| The SAI handler structure. More...

## Macros
#define | USEDMA 1
| Use DMA mode or interrupt mode. More...

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

## Enumerations
enum | sai_status_t { kStatus_SAI_Success = 0U, kStatus_SAI_Fail = 1U, kStatus_SAI_DeviceBusy = 2U }
| Status structure for SAI.

## Functions
sai_status_t | sai_init (sai_handler_t *handler, sai_user_config_t *config)
| Initializes the SAI module. More...
sai_status_t | sai_deinit (sai_handler_t *handler)
| De-initializes the SAI module. More...
sai_status_t | sai_configure_data_format (sai_handler_t *handler, sai_data_format_t *format)
| Configures the PCM data format. More...
void | sai_start_read_data (sai_handler_t *handler)
| Starts reading data from FIFO. More...
void | sai_start_write_data (sai_handler_t *handler)
| Starts writing data to FIFO. More...
static void | sai_stop_read_data (sai_handler_t *handler)
| Stops reading data from FIFO, mainly to disable the DMA or the interrupt request bit. More...
static void | sai_stop_write_data (sai_handler_t *handler)
| Stop write data to FIFO, mainly to disable the DMA or the interrupt request bit. More...
static void | sai_clear_tx_status (sai_handler_t *handler)
| Clears the TX FIFO error flag. More...
static void | sai_clear_rx_status (sai_handler_t *handler)
| Clears the RX FIFO error flag. More...
static uint32_t * | sai_get_fifo_address (sai_handler_t *handler)
| Gets the FIFO address of the data channel. More...
uint32_t | sai_send_data (sai_handler_t *handler, uint8_t *addr, uint32_t len)
| Sends a certain length data. More...
uint32_t | sai_receive_data (sai_handler_t *handler, uint8_t *addr, uint32_t len)
| Receives a certain length data. More...
void | sai_register_callback (sai_handler_t *handler, sai_callback_t callback, void *callback_param)
| Registers the callback function after a transfer. More...

### SAI Driver

# Overview

The SAI driver initializes, configures, starts, and stop SAI. The SAI driver implements functions of configure, send and receive data.

# Initialization

To initialize SAI, call the sai_init() function and pass the parameters needed. The parameter is the sai_handler_t structure and SAI configuration structure. The function opens the clock gate and initializes the SAI modules according to the structure information.

# Configure

Configure is implemented by the sai_configure_data_format() function. To use this function, the users should transfer the audio data format to the SAI module.

# Call diagram

To use the SAI driver, follow these steps:

1. Initialize the SAI module by calling the sai_init() function.
2. Configure the audio data features of SAI by calling the sai_configure_data_foramt() function.
3. Send/receive data by calling the sai_send_data() or the sai_receive_data() functions.
4. Start TX or RX by calling the sai_start_write_data() or the sai_start_read_data() function.
5. Shut down the SAI module by calling the sai_deinit() function.

This is example code to initialize and configure the SAI driver in the DMA mode:
// Initialize handler structure.
sai_handler_t handler;
handler.direction = AUDIO_TX;
handler.instance = 0;
handler.fifo_channel = 0;
//Initialize config structure.
sai_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.mclk_divide_enable = true;
//Data format of audio data
audio_data_format_t format;
format.bits = 16;
format.sample_rate = 44100;
format.mclk = 384 * format->sample_rate;
format.words = 2;
format.watermark = 4;
sai_init(&handler, &tx_config);
sai_configure_data_format(&handler,format);
//option: register callback functions for finished transfer
sai_register_callback(&handler, callback, NULL);
//start send data
sai_send_data(&handler, addr, len);

## Data Structure Documentation

struct sai_user_config_t

### Data Fields
sai_mclk_source_t | mclk_source
| Master clock source. More...
bool | mclk_divide_enable
| Enable the divide of master clock to generate bit clock. More...
sai_sync_mode_t | sync_mode
| Synchronous or asynchronous. More...
sai_bus_t | bus_type
| I2S left, I2S right or I2S type. More...
sai_master_slave_t | slave_master
| Master or slave. More...
sai_bclk_source_t | bclk_source
| Bit clock from master clock or other modules. More...
uint8_t | channel
| Which FIFO is used to transfer. More...

#### Field Documentation

sai_mclk_source_t sai_user_config_t::mclk_source

bool sai_user_config_t::mclk_divide_enable

sai_sync_mode_t sai_user_config_t::sync_mode

sai_bus_t sai_user_config_t::bus_type

sai_master_slave_t sai_user_config_t::slave_master

sai_bclk_source_t sai_user_config_t::bclk_source

uint8_t sai_user_config_t::channel

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
| How many bits in a word.
uint8_t | words
| How many word in a frame.
uint8_t | watermark
| When to send interrupt/DMA request.

struct sai_handler_t

The structure is used in the SAI runtime.

### Data Fields
uint8_t | instance
| SAI instance.
bool | direction
| RX or TX.
uint8_t | fifo_channel
| Which data channel is used.

## Macro Definition Documentation

#define USEDMA 1

## Function Documentation

sai_status_t sai_init | ( | sai_handler_t * | handler,
|  | sai_user_config_t * | config
| ) |  |

This function initializes the SAI registers according to the configuration structure. This function initializes the basic settings for SAI, including some board relevant settings. Notice: This function does not initialize an entire SAI instance. This function only initializes the TX or RX according to the value in the handler.

Parameters

  handler | SAI handler structure pointer.
  config | The configuration structure of SAI.

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

sai_status_t sai_deinit | ( | sai_handler_t * | handler | ) |

This function closes the SAI device. It does not close the entire SAI instance. It only closes the TX or RX according to the value in the handler.

Parameters

  handler | SAI handler structure pointer of the SAI module.

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

sai_status_t sai_configure_data_format | ( | sai_handler_t * | handler,
|  | sai_data_format_t * | format
| ) |  |

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

Parameters

  handler | SAI handler structure pointer 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_start_read_data | ( | sai_handler_t * | handler | ) |

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

Parameters

  handler | SAI handler structure pointer of the SAI module.

void sai_start_write_data | ( | sai_handler_t * | handler | ) |

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

Parameters

  handler | SAI handler structure pointer of the SAI module.

static void sai_stop_read_data | ( | sai_handler_t * | handler | ) |
| inline static

This function provides the method to pause receiving data.

Parameters

  handler | SAI handler structure pointer of the SAI module.

static void sai_stop_write_data | ( | sai_handler_t * | handler | ) |
| inline static

This function provides the method to pause writing data.

Parameters

  handler | SAI handler structure pointer of the SAI module.

static void sai_clear_tx_status | ( | sai_handler_t * | handler | ) |
| inline static

Parameters

  handler | SAI handler structure pointer of the SAI module.

static void sai_clear_rx_status | ( | sai_handler_t * | handler | ) |
| inline static

Parameters

  handler | SAI handler structure pointer of the SAI module.

static uint32_t* sai_get_fifo_address | ( | sai_handler_t * | handler | ) |
| inline static

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

Parameters

  handler | SAI handler structure pointer of the SAI module.

Returns
  Returns the address of the data channel FIFO.

uint32_t sai_send_data | ( | sai_handler_t * | handler,
|  | uint8_t * | addr,
|  | uint32_t | len
| ) |  |

This function sends the data to the TX FIFO. This function starts the transfer, and while finishing the transfer, it calls the callback function registered by users.

Parameters

  handler | SAI handler structure pointer of the SAI module.
  addr | Address of the data which needs to be transferred.
  len | The data length which need to be sent.

Returns
  Returns the length which was sent.

uint32_t sai_receive_data | ( | sai_handler_t * | handler,
|  | uint8_t * | addr,
|  | uint32_t | len
| ) |  |

This function receives the data from the RX FIFO. This function starts the transfer, and while finishing the transfer, it calls the callback function registered by users.

Parameters

  handler | SAI handler structure pointer of the SAI module.
  addr | Address of the data which needs to be transferred.
  len | The data length which needs to be received.

Returns
  Returns the length received.

void sai_register_callback | ( | sai_handler_t * | handler,
|  | sai_callback_t | callback,
|  | void * | callback_param
| ) |  |

This function tells SAI which function needs to be called after a period length transfer.

Parameters

  handler | SAI handler structure pointer of the SAI module.
  callback | Callback function defined by users.
  callback_param | The parameter of the callback function.