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

## Overview

## Data Structures

struct | sai_dma_handle_t
| SAI DMA transfer handle, users should not touch the content of the handle. More...

## Typedefs

typedef void(* | sai_dma_callback_t )(I2S_Type *base, sai_dma_handle_t *handle, status_t status, void *userData)
| Define SAI DMA callback.

## DMA Transactional

void | SAI_TransferTxCreateHandleDMA (I2S_Type *base, sai_dma_handle_t *handle, sai_dma_callback_t callback, void *userData, dma_handle_t *dmaHandle)
| Initializes the SAI master DMA handle. More...
void | SAI_TransferRxCreateHandleDMA (I2S_Type *base, sai_dma_handle_t *handle, sai_dma_callback_t callback, void *userData, dma_handle_t *dmaHandle)
| Initializes the SAI slave DMA handle. More...
void | SAI_TransferTxSetFormatDMA (I2S_Type *base, sai_dma_handle_t *handle, sai_transfer_format_t *format, uint32_t mclkSourceClockHz, uint32_t bclkSourceClockHz)
| Configures the SAI Tx audio format. More...
void | SAI_TransferRxSetFormatDMA (I2S_Type *base, sai_dma_handle_t *handle, sai_transfer_format_t *format, uint32_t mclkSourceClockHz, uint32_t bclkSourceClockHz)
| Configures the SAI Rx audio format. More...
status_t | SAI_TransferSendDMA (I2S_Type *base, sai_dma_handle_t *handle, sai_transfer_t *xfer)
| Performs a non-blocking SAI transfer using DMA. More...
status_t | SAI_TransferReceiveDMA (I2S_Type *base, sai_dma_handle_t *handle, sai_transfer_t *xfer)
| Performs a non-blocking SAI transfer using DMA. More...
void | SAI_TransferAbortSendDMA (I2S_Type *base, sai_dma_handle_t *handle)
| Aborts a SAI transfer using DMA. More...
void | SAI_TransferAbortReceiveDMA (I2S_Type *base, sai_dma_handle_t *handle)
| Aborts a SAI transfer using DMA. More...
status_t | SAI_TransferGetSendCountDMA (I2S_Type *base, sai_dma_handle_t *handle, size_t *count)
| Gets byte count sent by SAI. More...
status_t | SAI_TransferGetReceiveCountDMA (I2S_Type *base, sai_dma_handle_t *handle, size_t *count)
| Gets byte count received by SAI. More...

## Data Structure Documentation

struct _sai_dma_handle

### Data Fields

dma_handle_t * | dmaHandle
| DMA handler for SAI send.
uint8_t | bytesPerFrame
| Bytes in a frame.
uint8_t | channel
| Which Data channel SAI use.
uint32_t | state
| SAI DMA transfer internal state.
sai_dma_callback_t | callback
| Callback for users while transfer finish or error occured.
void * | userData
| User callback parameter.
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

sai_transfer_t sai_dma_handle_t::saiQueue[SAI_XFER_QUEUE_SIZE]

volatile uint8_t sai_dma_handle_t::queueUser

## Function Documentation

void SAI_TransferTxCreateHandleDMA | ( | I2S_Type * | base,
|  | sai_dma_handle_t * | handle,
|  | sai_dma_callback_t | callback,
|  | void * | userData,
|  | dma_handle_t * | dmaHandle
| ) |  |

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 DMA handle pointer.
  base | SAI peripheral base address.
  callback | Pointer to user callback function.
  userData | User parameter passed to the callback function.
  dmaHandle | DMA handle pointer, this handle shall be static allocated by users.

void SAI_TransferRxCreateHandleDMA | ( | I2S_Type * | base,
|  | sai_dma_handle_t * | handle,
|  | sai_dma_callback_t | callback,
|  | void * | userData,
|  | dma_handle_t * | dmaHandle
| ) |  |

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 DMA handle pointer.
  base | SAI peripheral base address.
  callback | Pointer to user callback function.
  userData | User parameter passed to the callback function.
  dmaHandle | DMA handle pointer, this handle shall be static allocated by users.

void SAI_TransferTxSetFormatDMA | ( | I2S_Type * | base,
|  | sai_dma_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 eDMA parameter according to the format.

Parameters

  base | SAI base pointer.
  handle | SAI DMA 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 arguments is invalid.

void SAI_TransferRxSetFormatDMA | ( | I2S_Type * | base,
|  | sai_dma_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 eDMA parameter according to format.

Parameters

  base | SAI base pointer.
  handle | SAI DMA 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 arguments is invalid.

status_t SAI_TransferSendDMA | ( | I2S_Type * | base,
|  | sai_dma_handle_t * | handle,
|  | sai_transfer_t * | xfer
| ) |  |

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

Parameters

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

Return values

  kStatus_Success | Successfully start the data receive.
  kStatus_SAI_TxBusy | Previous receive still not finished.
  kStatus_InvalidArgument | The input parameter is invalid.

status_t SAI_TransferReceiveDMA | ( | I2S_Type * | base,
|  | sai_dma_handle_t * | handle,
|  | sai_transfer_t * | xfer
| ) |  |

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

Parameters

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

Return values

  kStatus_Success | Successfully start the data receive.
  kStatus_SAI_RxBusy | Previous receive still not finished.
  kStatus_InvalidArgument | The input parameter is invalid.

void SAI_TransferAbortSendDMA | ( | I2S_Type * | base,
|  | sai_dma_handle_t * | handle
| ) |  |

Parameters

  base | SAI base pointer.
  handle | SAI DMA handle pointer.

void SAI_TransferAbortReceiveDMA | ( | I2S_Type * | base,
|  | sai_dma_handle_t * | handle
| ) |  |

Parameters

  base | SAI base pointer.
  handle | SAI DMA handle pointer.

status_t SAI_TransferGetSendCountDMA | ( | I2S_Type * | base,
|  | sai_dma_handle_t * | handle,
|  | size_t * | count
| ) |  |

Parameters

  base | SAI base pointer.
  handle | SAI DMA handle pointer.
  count | Bytes count sent by SAI.

Return values

  kStatus_Success | Succeed get the transfer count.
  kStatus_NoTransferInProgress | There is not a non-blocking transaction currently in progress.

status_t SAI_TransferGetReceiveCountDMA | ( | I2S_Type * | base,
|  | sai_dma_handle_t * | handle,
|  | size_t * | count
| ) |  |

Parameters

  base | SAI base pointer.
  handle | SAI DMA handle pointer.
  count | Bytes count received by SAI.

Return values

  kStatus_Success | Succeed get the transfer count.
  kStatus_NoTransferInProgress | There is not a non-blocking transaction currently in progress.