| 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 | Variables
Soundcard (SND)

The Kinetis SDK provides both HAL and Peripheral drivers for the Soundcard (SND) block of Kinetis devices. More...

## Data Structures
struct | snd_state_t
| Soundcard status includes the information which the application can see. More...
struct | audio_ctrl_operation_t
| The operations of an audio controller, for example SAI, SSI and so on. More...
struct | audio_codec_operation_t
| Audio codec operation structure. More...
struct | audio_controller_t
| The definition of the audio device which may be a controller. More...
struct | audio_codec_t
| The Codec structure. More...
struct | audio_buffer_t
| Audio buffer structure. More...
struct | sound_card_t
| A sound card includes the audio controller and a Codec. More...

## Macros
#define | AUDIO_CONTROLLER AUDIO_CONTROLLER_SAI
| Define audio controller sai.
#define | AUDIO_CONTROLLER_SAI 1
#define | AUDIO_CODEC AUDIO_CODEC_SGTL5000
| Define audio codec sgtl5000.
#define | AUDIO_CODEC_SGTL5000 1
#define | AUDIO_BUFFER_BLOCK_SIZE 128
| Buffer block size setting.
#define | AUDIO_BUFFER_BLOCK 2
| Buffer block number setting.
#define | AUDIO_BUFFER_SIZE (AUDIO_BUFFER_BLOCK * AUDIO_BUFFER_BLOCK_SIZE)
#define | AUDIO_TX 1
| Audio transfer direction Tx.
#define | AUDIO_RX 0
| Audio transfer direction Rx.

## Typedefs
typedef sai_handler_t | ctrl_handler_t
typedef sai_user_config_t | ctrl_config_t
typedef sai_data_format_t | ctrl_data_format_t
typedef sai_callback_t | ctrl_callback_t
typedef sai_status_t | ctrl_status_t
typedef sgtl_handler_t | codec_handler_t
typedef sgtl_status_t | codec_status_t

## Enumerations
enum | snd_status_t { kStatus_SND_Success = 0U, kStatus_SND_Fail = 1U, kStatus_SND_DmaFail = 2U, kStatus_SND_CtrlFail = 3U, kStatus_SND_CodecFail = 4U, kStatus_SND_BufferAllocateFail = 5U }
| Soundcard return status. More...

## Functions
snd_status_t | snd_init (sound_card_t *card, void *ctrl_config, void *codec_config)
| Initializes the Soundcard. More...
snd_status_t | snd_deinit (sound_card_t *card)
| Deinitializes the sound card instance. More...
snd_status_t | snd_data_format_configure (sound_card_t *card, ctrl_data_format_t *format)
| Configures the audio data format running in the Soundcard. More...
uint32_t | snd_update_tx_status (sound_card_t *card, uint32_t len)
| Updates the status of the TX. More...
uint32_t | snd_update_rx_status (sound_card_t *card, uint32_t len)
| Updates status of the RX. More...
void | snd_get_status (snd_state_t *status, sound_card_t *card)
| Gets the status of the Soundcard. More...
void | snd_start_tx (sound_card_t *card)
| Starts the Soundcard TX process. More...
void | snd_start_rx (sound_card_t *card)
| Starts the Soundcard RX process. More...
static void | snd_stop_tx (sound_card_t *card)
| Stops Soundcard TX process. More...
static void | snd_stop_rx (sound_card_t *card)
| Stops the Soundcard RX process. More...
void | snd_wait_event (sound_card_t *card)
| Waits for the semaphore of the write/read data from the internal buffer. More...

## Variables
audio_ctrl_operation_t | g_sai_ops
audio_codec_operation_t | g_sgtl_ops

### Soundcard Driver

# Overview

The Soundcard is used to handle both audio controller and audio Codec. It provides an easy way to initialize, configure and handle(read/write) the Soundcard.

# Initialization

A Soundcard includes a controller and a Codec (SAI + sgtl5000). Application needs to prepare the configuration structure for SAI and SGTL5000, and then call the snd_init() to finish the initialization.

# Configuration

The configuration includes the static configuration and dynamic configuration. Static configuration is configuring the SAI features. Dynamic configuration is configuring the audio data format (sample rate and bit depth).

# Call diagram

To use the SAI driver, user should follow these steps:

1. Initialize the Soundcard by calling the snd_init() function.
2. Configure the audio data format information of the Soundcard by calling the snd_data_format_configure() function.
3. Update the status of the Soundcard after copying into/output from the buffer by calling the snd_update_status() function.
4. Start the TX/RX by calling the snd_start_tx() or the snd_start_rx() function.
5. Stop by calling the snd_stop_tx() or snd_stop_rx() functions.
6. Close the devices by calling the snd_deinit() function.

This is an example code to initialize and configure the SAI driver in the DMA mode:
sound_card_t g_card;
static audio_data_format_t *format;
static sai_config_t tx_config;
void snd_card_config(void)
{
/* SAI configuration */
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;
sai_handler_t *tx_handler = (sai_handler_t *) mem_allocate_zero(sizeof(sai_handler_t));
g_card.controller.handler = tx_handler;
tx_handler->direction = AUDIO_TX;
tx_handler->instance = 0;
tx_handler->fifo_channel = 0;
g_card.controller.ops = &g_sai_ops;
#if USEDMA
g_card.controller.dma_source = kDmaRequestMux0I2S0Tx;
#endif
sgtl_handler_t *codec_handler = (sgtl_handler_t *) mem_allocate_zero(sizeof(sgtl_handler_t));
g_card.codec.handler = codec_handler;
g_card.codec.ops = &g_sgtl_ops;
}
// Initialize the Soundcard basically
snd_init(&g_card);
// Configure the audio data format for TX
snd_data_format_configure(&g_card,format);
// Copy data to SAI buffer
snd_wait_event(&g_card);
snd_get_status(&tx_status, &g_card);
memcpy(tx_status.input_address, pData, tx_status.size);
snd_update_tx_status(&g_card, tx_status.size);

## Data Structure Documentation

struct snd_state_t

This structure is the interface between the driver and the application. The application can get the information where and when to input/output data.

### Data Fields
uint32_t | size
| The size of a block.
uint32_t | empty_block
| How many blocks are empty.
uint32_t | full_block
| How many blocks are full.
uint8_t * | input_address
| The input address.
uint8_t * | output_address
| The output address.

struct audio_ctrl_operation_t

The operation includes the basic initialize, configure, send, receive and so on.

### Data Fields
ctrl_status_t(* | ctrl_init )(ctrl_handler_t *param, ctrl_config_t *config)
| Initializes the controller. More...
ctrl_status_t(* | ctrl_deinit )(ctrl_handler_t *param)
| Deinitializes the controller. More...
ctrl_status_t(* | ctrl_config_data_format )(ctrl_handler_t *param, ctrl_data_format_t *format)
| Configures the audio data format. More...
void(* | ctrl_start_write )(ctrl_handler_t *param)
| Used in a start transfer or a resume transfer.
void(* | ctrl_start_read )(ctrl_handler_t *param)
| Used in a start receive or a resume receive.
void(* | ctrl_stop_write )(ctrl_handler_t *param)
| Used in the stop transfer.
void(* | ctrl_stop_read )(ctrl_handler_t *param)
| Used in the stop receive.
uint32_t(* | ctrl_send_data )(ctrl_handler_t *param, uint8_t *addr, uint32_t len)
| Sends data function.
uint32_t(* | ctrl_receive_data )(ctrl_handler_t *param, uint8_t *addr, uint32_t len)
| Receives data.
void(* | ctrl_register_callback )(ctrl_handler_t *param, ctrl_callback_t callback, void *callback_param)
| Registers a callback function. More...
uint32_t *(* | ctrl_get_fifo_address )(ctrl_handler_t *param)
| Gets the FIFO address.

#### Field Documentation

ctrl_status_t(* audio_ctrl_operation_t::ctrl_init)(ctrl_handler_t *param, ctrl_config_t *config)

ctrl_status_t(* audio_ctrl_operation_t::ctrl_deinit)(ctrl_handler_t *param)

ctrl_status_t(* audio_ctrl_operation_t::ctrl_config_data_format)(ctrl_handler_t *param, ctrl_data_format_t *format)

void(* audio_ctrl_operation_t::ctrl_register_callback)(ctrl_handler_t *param, ctrl_callback_t callback, void *callback_param)

struct audio_codec_operation_t

### Data Fields
codec_status_t(* | codec_init )(codec_handler_t *param, void *config)
| Codec initialize function.
codec_status_t(* | codec_deinit )(codec_handler_t *param)
| Codec deinitialize function.
codec_status_t(* | codec_config_data_format )(codec_handler_t *param, uint32_t mclk, uint32_t sample_rate, uint8_t bits)
| Configures data format. More...

#### Field Documentation

codec_status_t(* audio_codec_operation_t::codec_config_data_format)(codec_handler_t *param, uint32_t mclk, uint32_t sample_rate, uint8_t bits)

struct audio_controller_t

### Data Fields
void * | handler
audio_ctrl_operation_t * | ops
| Operations including the initialize, configure, etc. More...

#### Field Documentation

audio_ctrl_operation_t* audio_controller_t::ops

struct audio_codec_t

### Data Fields
void * | handler
| Codec instance.
audio_codec_operation_t * | ops
| Operations. More...

#### Field Documentation

audio_codec_operation_t* audio_codec_t::ops

struct audio_buffer_t

### Data Fields
uint8_t * | buff
| Buffer address.
uint8_t | blocks
| Block number of the buffer. More...
uint16_t | size
| The size of a block.
uint32_t | requested
| The request data number to transfer.
uint32_t | queued
| Data which is in buffer, but not processed. More...
uint32_t | processed
| Data which is put into the FIFO. More...
uint8_t | input_index
| Buffer input block index. More...
uint8_t | output_index
| Buffer output block index. More...
uint8_t * | input_curbuff
| Buffer input address. More...
uint8_t * | output_curbuff
| Buffer output address. More...
uint32_t | empty_block
| Empty block number. More...
uint32_t | full_block
| Full block numbers. More...
uint32_t | fifo_error
| FIFO error numbers. More...
uint32_t | buffer_error
| Buffer error numbers. More...
sync_object_t | sem
| Semaphores to control the data flow. More...
bool | first_io
| Means the first time the transfer.

#### Field Documentation

uint8_t audio_buffer_t::blocks

uint32_t audio_buffer_t::queued

uint32_t audio_buffer_t::processed

This is used to judge if the SAI is under run.

uint8_t audio_buffer_t::input_index

uint8_t audio_buffer_t::output_index

uint8_t* audio_buffer_t::input_curbuff

uint8_t* audio_buffer_t::output_curbuff

uint32_t audio_buffer_t::empty_block

uint32_t audio_buffer_t::full_block

uint32_t audio_buffer_t::fifo_error

uint32_t audio_buffer_t::buffer_error

sync_object_t audio_buffer_t::sem

struct sound_card_t

### Data Fields
audio_controller_t | controller
| Controller.
audio_codec_t | codec
| Codec.
audio_buffer_t | buffer
| Audio buffer managed by Soundcard. More...
bool | direction
| TX or RX.

#### Field Documentation

audio_buffer_t sound_card_t::buffer

## Enumeration Type Documentation

enum snd_status_t

Enumerator
kStatus_SND_Success | Execute successfully.
kStatus_SND_Fail | Execute fail.
kStatus_SND_DmaFail | DMA operation fail.
kStatus_SND_CtrlFail | Audio controller operation fail.
kStatus_SND_CodecFail | Audio codec operation fail.
kStatus_SND_BufferAllocateFail | Buffer allocate failure.

## Function Documentation

snd_status_t snd_init | ( | sound_card_t * | card,
|  | void * | ctrl_config,
|  | void * | codec_config
| ) |  |

The function initializes the controller and the Codec.

The function initializes the generic layer structure, for example the buffer and the status structure, then the function calls the initialize functions of the controller and the Codec.

Parameters

  card | Soundcard pointer
  ctrl_config | The configuration structure of the audio controller
  codec_config | The configuration structure of the audio Codec

Returns
  Return kStatus_SND_Success while the initialize success and kStatus_SND_fail if failed.

snd_status_t snd_deinit | ( | sound_card_t * | card | ) |

The function calls the Codec and controller deinitialization function and frees the buffer controlled by the sound card. The function should be used at the end of the application. If the playback/record is paused, you shouldn't use the function. Instead, you should use the snd_stop_tx/snd_stop_rx instead.

Parameters

  card | Soundcard pointer

Returns
  Return kStatus_SND_Success while the initialize success and kStatus_SND_fail if failed.

snd_status_t snd_data_format_configure | ( | sound_card_t * | card,
|  | ctrl_data_format_t * | format
| ) |  |

This function can make the application change the data format during the run time. This function cannot be called while TCSR.TE or RCSR.RE is enabled. This function can change the sample rate, bit depth(i.e. 16-bit).

Parameters

  card | Soundcard pointer
  format | Data format used in the sound card

Returns
  Return kStatus_SND_Success while the initialize success and kStatus_SND_fail if failed.

uint32_t snd_update_tx_status | ( | sound_card_t * | card,
|  | uint32_t | len
| ) |  |

This function should be called after the application copied data into the buffer provided by the Soundcard. The Soundcard does not help users copy data to the internal buffer. This operation should be done by the applications. Soundcard provides an interface ,snd_get_status(), for an application to get the information about the internal buffer status, including the starting address and empty blocks and so on.

Parameters

  card | Soundcard pointer
  len | Data size of the data to write

Returns
  The size which has been written.

uint32_t snd_update_rx_status | ( | sound_card_t * | card,
|  | uint32_t | len
| ) |  |

This function should be called after the application copied data from the buffer provided by the Soundcard. The Soundcard does not help applications to copy data from the internal buffer. This operation should be done by applications. The Soundcard provides an interface snd_get_status() for applications to get the information about the internal buffer status, including the starting address and full blocks and so on.

Parameters

  card | Soundcard pointer
  len | Data size of data to read

Returns
  The data size which has been read.

void snd_get_status | ( | snd_state_t * | status,
|  | sound_card_t * | card
| ) |  |

Each time the application wants to write/read data from the internal buffer, it should call this function to get the status of the internal buffer. This function copies data to the

Parameters

  status,from | the structure. The user can get the information about where to write/read data and how much data can be read/written.
  card | Soundcard pointer
  status | Pointer of the audio_status_t structure
  card | Soundcard pointer

void snd_start_tx | ( | sound_card_t * | card | ) |

This function starts the TX process of the Soundcard. This function enables the DMA/interrupt request source and enables the TX and the bit clock of the TX. Note that this function can be used both in the beginning of the SAI transfer and also resume the transfer.

Parameters

  card | Soundcard pointer

void snd_start_rx | ( | sound_card_t * | card | ) |

This function starts the RX process of the Soundcard. This function is the same as the snd_start_tx. It is used in the beginning of the Soundcard RX transfer and also resume RX.

Parameters

  card | Soundcard pointer

static void snd_stop_tx | ( | sound_card_t * | card | ) |
| inline static

This function stops the transfer of the Soundcard TX. Note that this function does not close the audio controller. It disables the DMA/interrupt request source. Therefore, this function can be used to pause the audio play.

Parameters

  card | Soundcard pointer

static void snd_stop_rx | ( | sound_card_t * | card | ) |
| inline static

This function is the same as the snd_stop_tx, used to stop the RX process. This function also disables the DMA/interrupt source.

Parameters

  card | Soundcard pointer

void snd_wait_event | ( | sound_card_t * | card | ) |

Application should call this function before write/read data from the Soundcard buffer. Before application writes data to the Soundcard buffer, the buffer must have free space for the new data, or it causes data loss. This function waits for the semaphore which represents free space in the Soundcard buffer. Similarly to the reading data from the Soundcard buffer, effective data must be in the buffer. This function waits for that semaphore.

Parameters

  card | Soundcard pointer