All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
DSPI DMA Driver
DSPI: Serial Peripheral Interface Driver

## Overview

This section describes the programming interface of the DSPI DMA Peripheral driver. The DSPI DMA driver configures the DSPI module and provides the functional and transactional interfaces to build the DSPI application.

## Data Structures

struct | dspi_master_dma_handle_t
| DSPI master DMA transfer handle structure used for transactional API. More...
struct | dspi_slave_dma_handle_t
| DSPI slave DMA transfer handle structure used for transactional API. More...

## Typedefs

typedef void(* | dspi_master_dma_transfer_callback_t )(SPI_Type *base, dspi_master_dma_handle_t *handle, status_t status, void *userData)
| Completion callback function pointer type. More...
typedef void(* | dspi_slave_dma_transfer_callback_t )(SPI_Type *base, dspi_slave_dma_handle_t *handle, status_t status, void *userData)
| Completion callback function pointer type. More...

## Functions

void | DSPI_MasterTransferCreateHandleDMA (SPI_Type *base, dspi_master_dma_handle_t *handle, dspi_master_dma_transfer_callback_t callback, void *userData, dma_handle_t *dmaRxRegToRxDataHandle, dma_handle_t *dmaTxDataToIntermediaryHandle, dma_handle_t *dmaIntermediaryToTxRegHandle)
| Initializes the DSPI master DMA handle. More...
status_t | DSPI_MasterTransferDMA (SPI_Type *base, dspi_master_dma_handle_t *handle, dspi_transfer_t *transfer)
| DSPI master transfers data using DMA. More...
void | DSPI_MasterTransferAbortDMA (SPI_Type *base, dspi_master_dma_handle_t *handle)
| DSPI master aborts a transfer which is using DMA. More...
status_t | DSPI_MasterTransferGetCountDMA (SPI_Type *base, dspi_master_dma_handle_t *handle, size_t *count)
| Gets the master DMA transfer remaining bytes. More...
void | DSPI_SlaveTransferCreateHandleDMA (SPI_Type *base, dspi_slave_dma_handle_t *handle, dspi_slave_dma_transfer_callback_t callback, void *userData, dma_handle_t *dmaRxRegToRxDataHandle, dma_handle_t *dmaTxDataToTxRegHandle)
| Initializes the DSPI slave DMA handle. More...
status_t | DSPI_SlaveTransferDMA (SPI_Type *base, dspi_slave_dma_handle_t *handle, dspi_transfer_t *transfer)
| DSPI slave transfers data using DMA. More...
void | DSPI_SlaveTransferAbortDMA (SPI_Type *base, dspi_slave_dma_handle_t *handle)
| DSPI slave aborts a transfer which is using DMA. More...
status_t | DSPI_SlaveTransferGetCountDMA (SPI_Type *base, dspi_slave_dma_handle_t *handle, size_t *count)
| Gets the slave DMA transfer remaining bytes. More...

## Data Structure Documentation

struct _dspi_master_dma_handle

Forward declaration of the DSPI DMA master handle typedefs.

### Data Fields

uint32_t | bitsPerFrame
| Desired number of bits per frame. More...
volatile uint32_t | command
| Desired data command. More...
volatile uint32_t | lastCommand
| Desired last data command. More...
uint8_t | fifoSize
| FIFO dataSize. More...
volatile bool | isPcsActiveAfterTransfer
| Is PCS signal keep active after the last frame transfer. More...
volatile bool | isThereExtraByte
| Is there extra byte. More...
uint8_t *volatile | txData
| Send buffer. More...
uint8_t *volatile | rxData
| Receive buffer. More...
volatile size_t | remainingSendByteCount
| Number of bytes remaining to send. More...
volatile size_t | remainingReceiveByteCount
| Number of bytes remaining to receive. More...
size_t | totalByteCount
| Number of transfer bytes.
uint32_t | rxBuffIfNull
| Used if there is not rxData for DMA purpose. More...
uint32_t | txBuffIfNull
| Used if there is not txData for DMA purpose. More...
volatile uint8_t | state
| DSPI transfer state , _dspi_transfer_state. More...
dspi_master_dma_transfer_callback_t | callback
| Completion callback. More...
void * | userData
| Callback user data. More...
dma_handle_t * | dmaRxRegToRxDataHandle
| dma_handle_t handle point used for RxReg to RxData buff
dma_handle_t * | dmaTxDataToIntermediaryHandle
| dma_handle_t handle point used for TxData to Intermediary
dma_handle_t * | dmaIntermediaryToTxRegHandle
| dma_handle_t handle point used for Intermediary to TxReg

#### Field Documentation

uint32_t dspi_master_dma_handle_t::bitsPerFrame

volatile uint32_t dspi_master_dma_handle_t::command

volatile uint32_t dspi_master_dma_handle_t::lastCommand

uint8_t dspi_master_dma_handle_t::fifoSize

volatile bool dspi_master_dma_handle_t::isPcsActiveAfterTransfer

volatile bool dspi_master_dma_handle_t::isThereExtraByte

uint8_t* volatile dspi_master_dma_handle_t::txData

uint8_t* volatile dspi_master_dma_handle_t::rxData

volatile size_t dspi_master_dma_handle_t::remainingSendByteCount

volatile size_t dspi_master_dma_handle_t::remainingReceiveByteCount

uint32_t dspi_master_dma_handle_t::rxBuffIfNull

uint32_t dspi_master_dma_handle_t::txBuffIfNull

volatile uint8_t dspi_master_dma_handle_t::state

dspi_master_dma_transfer_callback_t dspi_master_dma_handle_t::callback

void* dspi_master_dma_handle_t::userData

struct _dspi_slave_dma_handle

Forward declaration of the DSPI DMA slave handle typedefs.

### Data Fields

uint32_t | bitsPerFrame
| Desired number of bits per frame. More...
volatile bool | isThereExtraByte
| Is there extra byte. More...
uint8_t *volatile | txData
| Send buffer. More...
uint8_t *volatile | rxData
| Receive buffer. More...
volatile size_t | remainingSendByteCount
| Number of bytes remaining to send. More...
volatile size_t | remainingReceiveByteCount
| Number of bytes remaining to receive. More...
size_t | totalByteCount
| Number of transfer bytes.
uint32_t | rxBuffIfNull
| Used if there is not rxData for DMA purpose. More...
uint32_t | txBuffIfNull
| Used if there is not txData for DMA purpose. More...
uint32_t | txLastData
| Used if there is an extra byte when 16 bits per frame for DMA purpose. More...
volatile uint8_t | state
| DSPI transfer state. More...
uint32_t | errorCount
| Error count for slave transfer. More...
dspi_slave_dma_transfer_callback_t | callback
| Completion callback. More...
void * | userData
| Callback user data. More...
dma_handle_t * | dmaRxRegToRxDataHandle
| dma_handle_t handle point used for RxReg to RxData buff
dma_handle_t * | dmaTxDataToTxRegHandle
| dma_handle_t handle point used for TxData to TxReg

#### Field Documentation

uint32_t dspi_slave_dma_handle_t::bitsPerFrame

volatile bool dspi_slave_dma_handle_t::isThereExtraByte

uint8_t* volatile dspi_slave_dma_handle_t::txData

uint8_t* volatile dspi_slave_dma_handle_t::rxData

volatile size_t dspi_slave_dma_handle_t::remainingSendByteCount

volatile size_t dspi_slave_dma_handle_t::remainingReceiveByteCount

uint32_t dspi_slave_dma_handle_t::rxBuffIfNull

uint32_t dspi_slave_dma_handle_t::txBuffIfNull

uint32_t dspi_slave_dma_handle_t::txLastData

volatile uint8_t dspi_slave_dma_handle_t::state

uint32_t dspi_slave_dma_handle_t::errorCount

dspi_slave_dma_transfer_callback_t dspi_slave_dma_handle_t::callback

void* dspi_slave_dma_handle_t::userData

## Typedef Documentation

typedef void(* dspi_master_dma_transfer_callback_t)(SPI_Type *base, dspi_master_dma_handle_t *handle, status_t status, void *userData)

Parameters

  base | DSPI peripheral base address.
  handle | Pointer to the handle for the DSPI master.
  status | Success or error code describing whether the transfer completed.
  userData | Arbitrary pointer-dataSized value passed from the application.

typedef void(* dspi_slave_dma_transfer_callback_t)(SPI_Type *base, dspi_slave_dma_handle_t *handle, status_t status, void *userData)

Parameters

  base | DSPI peripheral base address.
  handle | Pointer to the handle for the DSPI slave.
  status | Success or error code describing whether the transfer completed.
  userData | Arbitrary pointer-dataSized value passed from the application.

## Function Documentation

void DSPI_MasterTransferCreateHandleDMA | ( | SPI_Type * | base,
|  | dspi_master_dma_handle_t * | handle,
|  | dspi_master_dma_transfer_callback_t | callback,
|  | void * | userData,
|  | dma_handle_t * | dmaRxRegToRxDataHandle,
|  | dma_handle_t * | dmaTxDataToIntermediaryHandle,
|  | dma_handle_t * | dmaIntermediaryToTxRegHandle
| ) |  |

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

Note that DSPI DMA has a separated (Rx and Tx as two sources) or shared (Rx and Tx is the same source) DMA request source. (1) For a separated DMA request source, enable and set the Rx DMAMUX source for dmaRxRegToRxDataHandle and Tx DMAMUX source for dmaIntermediaryToTxRegHandle. (2) For a shared DMA request source, enable and set the Rx/Rx DMAMUX source for dmaRxRegToRxDataHandle.

Parameters

  base | DSPI peripheral base address.
  handle | DSPI handle pointer to dspi_master_dma_handle_t.
  callback | DSPI callback.
  userData | callback function parameter.
  dmaRxRegToRxDataHandle | dmaRxRegToRxDataHandle pointer to dma_handle_t.
  dmaTxDataToIntermediaryHandle | dmaTxDataToIntermediaryHandle pointer to dma_handle_t.
  dmaIntermediaryToTxRegHandle | dmaIntermediaryToTxRegHandle pointer to dma_handle_t.

status_t DSPI_MasterTransferDMA | ( | SPI_Type * | base,
|  | dspi_master_dma_handle_t * | handle,
|  | dspi_transfer_t * | transfer
| ) |  |

This function transfers data using DMA. This is a non-blocking function, which returns right away. When all data is transferred, the callback function is called.

Note that master DMA transfer cannot support the transfer_size of 1 when the bitsPerFrame is greater than 8.

Parameters

  base | DSPI peripheral base address.
  handle | pointer to dspi_master_dma_handle_t structure which stores the transfer state.
  transfer | pointer to dspi_transfer_t structure.

Returns
  status of status_t.

void DSPI_MasterTransferAbortDMA | ( | SPI_Type * | base,
|  | dspi_master_dma_handle_t * | handle
| ) |  |

This function aborts a transfer which is using DMA.

Parameters

  base | DSPI peripheral base address.
  handle | pointer to dspi_master_dma_handle_t structure which stores the transfer state.

status_t DSPI_MasterTransferGetCountDMA | ( | SPI_Type * | base,
|  | dspi_master_dma_handle_t * | handle,
|  | size_t * | count
| ) |  |

This function gets the master DMA transfer remaining bytes.

Parameters

  base | DSPI peripheral base address.
  handle | pointer to dspi_master_dma_handle_t structure which stores the transfer state.
  count | number point of bytes transferred so far by the non-blocking transaction.

Returns
  status of status_t.

void DSPI_SlaveTransferCreateHandleDMA | ( | SPI_Type * | base,
|  | dspi_slave_dma_handle_t * | handle,
|  | dspi_slave_dma_transfer_callback_t | callback,
|  | void * | userData,
|  | dma_handle_t * | dmaRxRegToRxDataHandle,
|  | dma_handle_t * | dmaTxDataToTxRegHandle
| ) |  |

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

Note that DSPI DMA has a separated (Rx and Tx as two sources) or shared (Rx and Tx is the same source) DMA request source. (1) For a separated DMA request source, enable and set the Rx DMAMUX source for dmaRxRegToRxDataHandle and Tx DMAMUX source for dmaTxDataToTxRegHandle. (2) For a shared DMA request source, enable and set the Rx/Rx DMAMUX source for dmaRxRegToRxDataHandle.

Parameters

  base | DSPI peripheral base address.
  handle | DSPI handle pointer to dspi_slave_dma_handle_t.
  callback | DSPI callback.
  userData | callback function parameter.
  dmaRxRegToRxDataHandle | dmaRxRegToRxDataHandle pointer to dma_handle_t.
  dmaTxDataToTxRegHandle | dmaTxDataToTxRegHandle pointer to dma_handle_t.

status_t DSPI_SlaveTransferDMA | ( | SPI_Type * | base,
|  | dspi_slave_dma_handle_t * | handle,
|  | dspi_transfer_t * | transfer
| ) |  |

This function transfers data using DMA. This is a non-blocking function, which returns right away. When all data is transferred, the callback function is called.

Note that the slave DMA transfer cannot support the transfer_size of 1 when the bitsPerFrame is greater than 8.

Parameters

  base | DSPI peripheral base address.
  handle | pointer to dspi_slave_dma_handle_t structure which stores the transfer state.
  transfer | pointer to dspi_transfer_t structure.

Returns
  status of status_t.

void DSPI_SlaveTransferAbortDMA | ( | SPI_Type * | base,
|  | dspi_slave_dma_handle_t * | handle
| ) |  |

This function aborts a transfer which is using DMA.

Parameters

  base | DSPI peripheral base address.
  handle | pointer to dspi_slave_dma_handle_t structure which stores the transfer state.

status_t DSPI_SlaveTransferGetCountDMA | ( | SPI_Type * | base,
|  | dspi_slave_dma_handle_t * | handle,
|  | size_t * | count
| ) |  |

This function gets the slave DMA transfer remaining bytes.

Parameters

  base | DSPI peripheral base address.
  handle | pointer to dspi_slave_dma_handle_t structure which stores the transfer state.
  count | number point of bytes transferred so far by the non-blocking transaction.

Returns
  status of status_t.