MCUXpresso SDK API Reference Manual: SAI SDMA Driver

| MCUXpresso SDK API Reference Manual Rev 2.11.1 NXP Semiconductors

- Main Page
- Related Pages
- API Reference

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Typedefs
SAI SDMA Driver
SAI: Serial Audio Interface

# Typical use case

More...

## Overview

## Multi fifo transfer use sai sdma driver

## The SDMA multi fifo script support transfer data between multi peripheral fifos and memory, a typical user case is that receiving multi sai channel data and put it into memory as

## | channel 0 | channel 1 | channel 2 | channel 3 | channel 4 | ......... |

Multi fifo script is target to implement above feature, it can supports 1.configurable fifo watermark range from 1~(2^12-1), it is a value of fifo_watermark * channel_numbers 2.configurable fifo numbers, support up to 15 continuous fifos 3.configurable fifo address offset, support address offset up to 64

/* load sdma script */
SDMA_LoadScript()
/* sai multi channel configurations */
SAI_GetClassicI2SConfig(&config, DEMO_AUDIO_BIT_WIDTH, kSAI_Stereo, kSAI_Channel0Mask | kSAI_Channel1Mask | kSAI_Channel2Mask| kSAI_Channel3Mask | kSAI_Channel4Mask);
SAI_TransferRxSetConfigSDMA(SAI, handle, &config);
SAI_TransferReceiveSDMA(SAI, handle, &config);

Transmitting data using multi fifo is same as above.

## Data Structures
struct | sai_sdma_handle_t
| SAI DMA transfer handle, users should not touch the content of the handle. More...

## Typedefs
typedef void(* | sai_sdma_callback_t )(I2S_Type *base, sai_sdma_handle_t *handle, status_t status, void *userData)
| SAI SDMA transfer callback function for finish and error.

## Driver version
#define | FSL_SAI_SDMA_DRIVER_VERSION (MAKE_VERSION(2, 4, 1))
| Version 2.4.1.

## SDMA Transactional
void | SAI_TransferTxCreateHandleSDMA (I2S_Type *base, sai_sdma_handle_t *handle, sai_sdma_callback_t callback, void *userData, sdma_handle_t *dmaHandle, uint32_t eventSource)
| Initializes the SAI SDMA handle. More...
void | SAI_TransferRxCreateHandleSDMA (I2S_Type *base, sai_sdma_handle_t *handle, sai_sdma_callback_t callback, void *userData, sdma_handle_t *dmaHandle, uint32_t eventSource)
| Initializes the SAI Rx SDMA handle. More...
void | SAI_TransferTxSetFormatSDMA (I2S_Type *base, sai_sdma_handle_t *handle, sai_transfer_format_t *format, uint32_t mclkSourceClockHz, uint32_t bclkSourceClockHz)
| Configures the SAI Tx audio format. More...
void | SAI_TransferRxSetFormatSDMA (I2S_Type *base, sai_sdma_handle_t *handle, sai_transfer_format_t *format, uint32_t mclkSourceClockHz, uint32_t bclkSourceClockHz)
| Configures the SAI Rx audio format. More...
status_t | SAI_TransferSendSDMA (I2S_Type *base, sai_sdma_handle_t *handle, sai_transfer_t *xfer)
| Performs a non-blocking SAI transfer using DMA. More...
status_t | SAI_TransferReceiveSDMA (I2S_Type *base, sai_sdma_handle_t *handle, sai_transfer_t *xfer)
| Performs a non-blocking SAI receive using SDMA. More...
void | SAI_TransferAbortSendSDMA (I2S_Type *base, sai_sdma_handle_t *handle)
| Aborts a SAI transfer using SDMA. More...
void | SAI_TransferAbortReceiveSDMA (I2S_Type *base, sai_sdma_handle_t *handle)
| Aborts a SAI receive using SDMA. More...
void | SAI_TransferRxSetConfigSDMA (I2S_Type *base, sai_sdma_handle_t *handle, sai_transceiver_t *saiConfig)
| brief Configures the SAI RX. More...
void | SAI_TransferTxSetConfigSDMA (I2S_Type *base, sai_sdma_handle_t *handle, sai_transceiver_t *saiConfig)
| brief Configures the SAI Tx. More...

## Data Structure Documentation

struct _sai_sdma_handle

### Data Fields
sdma_handle_t * | dmaHandle
| DMA handler for SAI send.
uint8_t | bytesPerFrame
| Bytes in a frame.
uint8_t | channel
| start data channel
uint8_t | channelNums
| total transfer channel numbers, used for multififo
uint8_t | channelMask
| enabled channel mask value, refernece _sai_channel_mask
uint8_t | fifoOffset
| fifo address offset between multifo
uint32_t | count
| The transfer data count in a DMA request.
uint32_t | state
| Internal state for SAI SDMA transfer.
uint32_t | eventSource
| SAI event source number.
sai_sdma_callback_t | callback
| Callback for users while transfer finish or error occurs.
void * | userData
| User callback parameter.
sdma_buffer_descriptor_t | bdPool [SAI_XFER_QUEUE_SIZE]
| BD pool for SDMA transfer. More...
sai_transfer_t | saiQueue [SAI_XFER_QUEUE_SIZE]
| Transfer queue storing queued transfer. More...
size_t | transferSize [SAI_XFER_QUEUE_SIZE]
| Data bytes need to transfer.
volatile uint8_t | queueUser
| Index for user to queue transfer. More...
volatile uint8_t | queueDriver
| Index for driver to get the transfer data and size.

#### Field Documentation

sdma_buffer_descriptor_t sai_sdma_handle_t::bdPool[SAI_XFER_QUEUE_SIZE]

sai_transfer_t sai_sdma_handle_t::saiQueue[SAI_XFER_QUEUE_SIZE]

volatile uint8_t sai_sdma_handle_t::queueUser

## Function Documentation

void SAI_TransferTxCreateHandleSDMA | ( | I2S_Type * | base,
|  | sai_sdma_handle_t * | handle,
|  | sai_sdma_callback_t | callback,
|  | void * | userData,
|  | sdma_handle_t * | dmaHandle,
|  | uint32_t | eventSource
| ) |  |

This function initializes the SAI master DMA handle, which can be used for other SAI master transactional APIs. Usually, for a specified SAI instance, call this API once to get the initialized handle.

Parameters

  base | SAI base pointer.
  handle | SAI SDMA handle pointer.
  base | SAI peripheral base address.
  callback | Pointer to user callback function.
  userData | User parameter passed to the callback function.
  dmaHandle | SDMA handle pointer, this handle shall be static allocated by users.
  eventSource | SAI event source number.

void SAI_TransferRxCreateHandleSDMA | ( | I2S_Type * | base,
|  | sai_sdma_handle_t * | handle,
|  | sai_sdma_callback_t | callback,
|  | void * | userData,
|  | sdma_handle_t * | dmaHandle,
|  | uint32_t | eventSource
| ) |  |

This function initializes the SAI slave DMA handle, which can be used for other SAI master transactional APIs. Usually, for a specified SAI instance, call this API once to get the initialized handle.

Parameters

  base | SAI base pointer.
  handle | SAI SDMA handle pointer.
  base | SAI peripheral base address.
  callback | Pointer to user callback function.
  userData | User parameter passed to the callback function.
  dmaHandle | SDMA handle pointer, this handle shall be static allocated by users.
  eventSource | SAI event source number.

void SAI_TransferTxSetFormatSDMA | ( | I2S_Type * | base,
|  | sai_sdma_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. This function also sets the SDMA parameter according to formatting requirements.

Parameters

  base | SAI base pointer.
  handle | SAI SDMA handle pointer.
  format | Pointer to SAI audio data format structure.
  mclkSourceClockHz | SAI master clock source frequency in Hz.
  bclkSourceClockHz | SAI bit clock source frequency in Hz. If bit clock source is master clock, this value should equals to masterClockHz in format.

Return values

  kStatus_Success | Audio format set successfully.
  kStatus_InvalidArgument | The input argument is invalid.

void SAI_TransferRxSetFormatSDMA | ( | I2S_Type * | base,
|  | sai_sdma_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. This function also sets the SDMA parameter according to formatting requirements.

Parameters

  base | SAI base pointer.
  handle | SAI SDMA handle pointer.
  format | Pointer to SAI audio data format structure.
  mclkSourceClockHz | SAI master clock source frequency in Hz.
  bclkSourceClockHz | SAI bit clock source frequency in Hz. If a bit clock source is the master clock, this value should equal to masterClockHz in format.

Return values

  kStatus_Success | Audio format set successfully.
  kStatus_InvalidArgument | The input argument is invalid.

status_t SAI_TransferSendSDMA | ( | I2S_Type * | base,
|  | sai_sdma_handle_t * | handle,
|  | sai_transfer_t * | xfer
| ) |  |

Note
  This interface returns immediately after the transfer initiates. Call SAI_GetTransferStatus to poll the transfer status and check whether the SAI transfer is finished.

Parameters

  base | SAI base pointer.
  handle | SAI SDMA handle pointer.
  xfer | Pointer to the DMA transfer structure.

Return values

  kStatus_Success | Start a SAI SDMA send successfully.
  kStatus_InvalidArgument | The input argument is invalid.
  kStatus_TxBusy | SAI is busy sending data.

status_t SAI_TransferReceiveSDMA | ( | I2S_Type * | base,
|  | sai_sdma_handle_t * | handle,
|  | sai_transfer_t * | xfer
| ) |  |

Note
  This interface returns immediately after the transfer initiates. Call the SAI_GetReceiveRemainingBytes to poll the transfer status and check whether the SAI transfer is finished.

Parameters

  base | SAI base pointer
  handle | SAI SDMA handle pointer.
  xfer | Pointer to DMA transfer structure.

Return values

  kStatus_Success | Start a SAI SDMA receive successfully.
  kStatus_InvalidArgument | The input argument is invalid.
  kStatus_RxBusy | SAI is busy receiving data.

void SAI_TransferAbortSendSDMA | ( | I2S_Type * | base,
|  | sai_sdma_handle_t * | handle
| ) |  |

Parameters

  base | SAI base pointer.
  handle | SAI SDMA handle pointer.

void SAI_TransferAbortReceiveSDMA | ( | I2S_Type * | base,
|  | sai_sdma_handle_t * | handle
| ) |  |

Parameters

  base | SAI base pointer
  handle | SAI SDMA handle pointer.

void SAI_TransferRxSetConfigSDMA | ( | I2S_Type * | base,
|  | sai_sdma_handle_t * | handle,
|  | sai_transceiver_t * | saiConfig
| ) |  |

param base SAI base pointer. param handle SAI SDMA handle pointer. param saiConig sai configurations.

void SAI_TransferTxSetConfigSDMA | ( | I2S_Type * | base,
|  | sai_sdma_handle_t * | handle,
|  | sai_transceiver_t * | saiConfig
| ) |  |

param base SAI base pointer. param handle SAI SDMA handle pointer. param saiConig sai configurations.