RTEMS: DMA API for Standard Operations

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Functions
DMA API for Standard Operations
Board Support Packages » ARM » Intel Cyclone V » Contributed Code » DMA Controller API

## Functions
ALT_STATUS_CODE | alt_dma_memory_to_memory (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *program, void *dest, const void *src, size_t size, bool send_evt, ALT_DMA_EVENT_t evt)
ALT_STATUS_CODE | alt_dma_zero_to_memory (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *program, void *buf, size_t size, bool send_evt, ALT_DMA_EVENT_t evt)
ALT_STATUS_CODE | alt_dma_memory_to_register (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *program, void *dst_reg, const void *src_buf, size_t count, uint32_t register_width_bits, bool send_evt, ALT_DMA_EVENT_t evt)
ALT_STATUS_CODE | alt_dma_register_to_memory (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *program, void *dst_buf, const void *src_reg, size_t count, uint32_t register_width_bits, bool send_evt, ALT_DMA_EVENT_t evt)
ALT_STATUS_CODE | alt_dma_memory_to_periph (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *program, ALT_DMA_PERIPH_t dest, const void *src, size_t size, void *periph_info, bool send_evt, ALT_DMA_EVENT_t evt)
ALT_STATUS_CODE | alt_dma_periph_to_memory (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *program, void *dest, ALT_DMA_PERIPH_t src, size_t size, void *periph_info, bool send_evt, ALT_DMA_EVENT_t evt)

## Detailed Description

The functions in this group provide common DMA operations for common bulk data transfers between:

- Memory to Memory
- Zero to Memory
- Memory to Peripheral
- Peripheral to Memory

All DMA operations are asynchronous. The following are the ways to receive notification of a DMA transfer complete operation:

- Use alt_dma_channel_state_get() and poll for the ALT_DMA_CHANNEL_STATE_STOPPED status.
- In conjunction with the interrupt API, use DMA events to signal an interrupt. The event first must be configured to signal an interrupt using alt_dma_event_int_select(). Configure the DMA program to send an event.
- Construct a custom program which waits for a particular event number by assemblying a DMAWFE using alt_dma_program_DMAWFE(). Then run the custom program on a different channel. The custom program will wait until the DMA program sends the event. Configure the DMA program to send an event.

Cache related maintenance on the source and/or destinatino buffer are not handled the DMA API and are the responsibility of the programmer. This is because the DMA API does not have visibility into the current configuration of the MMU or know about any special considerations regarding the source and/or destination memory. The following are some example scenarios and cache maintenance related precautions that may need to be taken:

- alt_dma_memory_to_memory(): Source buffer should be cleaned or purged, destination buffer should be invalidated.
- alt_dma_zero_to_memory(): Destination buffer should be invalidated.
- alt_dma_memory_to_register(): Source buffer should be cleaned or purged.
- alt_dma_register_to_memory(): Destination buffer should be invalidated.
- alt_dma_memory_to_periph(): Source buffer should be cleaned or purged.
- alt_dma_periph_to_memory(): Destination buffer should be invalidated.

## Function Documentation

## ◆ alt_dma_memory_to_memory()

ALT_STATUS_CODE alt_dma_memory_to_memory | ( | ALT_DMA_CHANNEL_t | channel,
|  | ALT_DMA_PROGRAM_t * | program,
|  | void * | dest,
|  | const void * | src,
|  | size_t | size,
|  | bool | send_evt,
|  | ALT_DMA_EVENT_t | evt
| ) |  |

Uses the DMA engine to asynchronously copy the specified memory from the given source address to the given destination address.

Overlapping memory regions are not supported.

Parameters

  channel | The DMA channel thread to use for the transfer.
  program | An allocated DMA program buffer to use for the life of the transfer.
  dest | The destination memory address to copy to.
  src | The source memory address to copy from.
  size | The size of the transfer in bytes.
  send_evt | If set to true, the DMA engine will be instructed to send an event upon completion or fault.
  evt | If send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The given channel or event identifier (if used) is invalid, or the memory regions specified are overlapping.

## ◆ alt_dma_memory_to_periph()

ALT_STATUS_CODE alt_dma_memory_to_periph | ( | ALT_DMA_CHANNEL_t | channel,
|  | ALT_DMA_PROGRAM_t * | program,
|  | ALT_DMA_PERIPH_t | dest,
|  | const void * | src,
|  | size_t | size,
|  | void * | periph_info,
|  | bool | send_evt,
|  | ALT_DMA_EVENT_t | evt
| ) |  |

Uses the DMA engine to asynchronously copy memory from the given source address to the specified peripheral. Because different peripheral has different characteristics, individual peripherals need to be explicitly supported.

The following lists the peripheral IDs supported by this API:

- ALT_DMA_PERIPH_QSPI_FLASH_TX
- ALT_DMA_PERIPH_UART0_TX
- ALT_DMA_PERIPH_UART1_TX

Parameters

  channel | The DMA channel thread to use for the transfer.
  program | An allocated DMA program buffer to use for the life of the transfer.
  dest | The destination peripheral to copy memory to.
  src | The source memory address to copy from.
  size | The size of the transfer in bytes.
  periph_info | A pointer to a peripheral specific data structure. The following list shows what data structure should be used for peripherals: ALT_DMA_PERIPH_QSPI_FLASH_TX: This parameter is ignored. ALT_DMA_PERIPH_UART0_TX: Use a pointer to the ALT_16550_HANDLE_t used to interact with that UART. ALT_DMA_PERIPH_UART1_TX: Use a pointer to the ALT_16550_HANDLE_t used to interact with that UART.
  send_evt | If set to true, the DMA engine will be instructed to send an event upon completion or fault.
  evt | If send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The given channel, peripheral, or event identifier (if used) is invalid.

## ◆ alt_dma_memory_to_register()

ALT_STATUS_CODE alt_dma_memory_to_register | ( | ALT_DMA_CHANNEL_t | channel,
|  | ALT_DMA_PROGRAM_t * | program,
|  | void * | dst_reg,
|  | const void * | src_buf,
|  | size_t | count,
|  | uint32_t | register_width_bits,
|  | bool | send_evt,
|  | ALT_DMA_EVENT_t | evt
| ) |  |

Uses the DMA engine to asynchronously transfer the contents of a memory buffer to a keyhole register.

Parameters

  channel | The DMA channel thread to use for the transfer.
  program | An allocated DMA program buffer to use for the life of the transfer.
  dst_reg | The address of the register to write buffer to.
  src_buf | The address of the memory buffer for the data.
  count | The number of transfers to make.
  register_width_bits | The width of the register to transfer to in bits. Valid values are 8, 16, 32, and 64.
  send_evt | If set to true, the DMA engine will be instructed to send an event upon completion or fault.
  evt | If send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The given channel, event identifier (if used), or register width are invalid, or if the destination register or source buffer is unaligned to the register width.

## ◆ alt_dma_periph_to_memory()

ALT_STATUS_CODE alt_dma_periph_to_memory | ( | ALT_DMA_CHANNEL_t | channel,
|  | ALT_DMA_PROGRAM_t * | program,
|  | void * | dest,
|  | ALT_DMA_PERIPH_t | src,
|  | size_t | size,
|  | void * | periph_info,
|  | bool | send_evt,
|  | ALT_DMA_EVENT_t | evt
| ) |  |

Uses the DMA engine to copy memory from the specified peripheral to the given destination address. Because different peripheral has different characteristics, individual peripherals need to be explicitly supported.

The following lists the peripheral IDs supported by this API:

- ALT_DMA_PERIPH_QSPI_FLASH_RX
- ALT_DMA_PERIPH_UART0_RX
- ALT_DMA_PERIPH_UART1_RX

Parameters

  channel | The DMA channel thread to use for the transfer.
  program | An allocated DMA program buffer to use for the life of the transfer.
  dest | The destination memory address to copy to.
  src | The source peripheral to copy memory from.
  size | The size of the transfer in bytes.
  periph_info | A pointer to a peripheral specific data structure. The following list shows what data structure should be used for peripherals: ALT_DMA_PERIPH_QSPI_FLASH_RX: This parameter is ignored. ALT_DMA_PERIPH_UART0_RX: Use a pointer to the ALT_16550_HANDLE_t used to interact with that UART. ALT_DMA_PERIPH_UART1_RX: Use a pointer to the ALT_16550_HANDLE_t used to interact with that UART.
  send_evt | If set to true, the DMA engine will be instructed to send an event upon completion or fault.
  evt | If send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The given channel, peripheral, or event identifier (if used) is invalid.

## ◆ alt_dma_register_to_memory()

ALT_STATUS_CODE alt_dma_register_to_memory | ( | ALT_DMA_CHANNEL_t | channel,
|  | ALT_DMA_PROGRAM_t * | program,
|  | void * | dst_buf,
|  | const void * | src_reg,
|  | size_t | count,
|  | uint32_t | register_width_bits,
|  | bool | send_evt,
|  | ALT_DMA_EVENT_t | evt
| ) |  |

Uses the DMA engine to asynchronously transfer the contents of a keyhole register to a memory buffer.

Parameters

  channel | The DMA channel thread to use for the transfer.
  program | An allocated DMA program buffer to use for the life of the transfer.
  dst_buf | The address of the memory buffer to copy to.
  src_reg | The address of the keyhole register to read from.
  count | The number of transfers to make.
  register_width_bits | The width of the register to transfer to in bits. Valid values are 8, 16, 32, and 64.
  send_evt | If set to true, the DMA engine will be instructed to send an event upon completion or fault.
  evt | If send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The given channel, event identifier (if used), or register width are invalid, or if the destination buffer or source register is unaligned to the register width.

## ◆ alt_dma_zero_to_memory()

ALT_STATUS_CODE alt_dma_zero_to_memory | ( | ALT_DMA_CHANNEL_t | channel,
|  | ALT_DMA_PROGRAM_t * | program,
|  | void * | buf,
|  | size_t | size,
|  | bool | send_evt,
|  | ALT_DMA_EVENT_t | evt
| ) |  |

Uses the DMA engine to asynchronously zero out the specified memory buffer.

Parameters

  channel | The DMA channel thread to use for the transfer.
  program | An allocated DMA program buffer to use for the life of the transfer.
  buf | The buffer memory address to zero out.
  size | The size of the buffer in bytes.
  send_evt | If set to true, the DMA engine will be instructed to send an event upon completion or fault.
  evt | If send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The given channel or event identifier (if used) is invalid.