RTEMS  5.0.0
Functions

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:

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

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:

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
channelThe DMA channel thread to use for the transfer.
programAn allocated DMA program buffer to use for the life of the transfer.
destThe destination memory address to copy to.
srcThe source memory address to copy from.
sizeThe size of the transfer in bytes.
send_evtIf set to true, the DMA engine will be instructed to send an event upon completion or fault.
evtIf send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
channelThe DMA channel thread to use for the transfer.
programAn allocated DMA program buffer to use for the life of the transfer.
destThe destination peripheral to copy memory to.
srcThe source memory address to copy from.
sizeThe size of the transfer in bytes.
periph_infoA 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_evtIf set to true, the DMA engine will be instructed to send an event upon completion or fault.
evtIf send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
channelThe DMA channel thread to use for the transfer.
programAn allocated DMA program buffer to use for the life of the transfer.
dst_regThe address of the register to write buffer to.
src_bufThe address of the memory buffer for the data.
countThe number of transfers to make.
register_width_bitsThe width of the register to transfer to in bits. Valid values are 8, 16, 32, and 64.
send_evtIf set to true, the DMA engine will be instructed to send an event upon completion or fault.
evtIf send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
channelThe DMA channel thread to use for the transfer.
programAn allocated DMA program buffer to use for the life of the transfer.
destThe destination memory address to copy to.
srcThe source peripheral to copy memory from.
sizeThe size of the transfer in bytes.
periph_infoA 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_evtIf set to true, the DMA engine will be instructed to send an event upon completion or fault.
evtIf send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
channelThe DMA channel thread to use for the transfer.
programAn allocated DMA program buffer to use for the life of the transfer.
dst_bufThe address of the memory buffer to copy to.
src_regThe address of the keyhole register to read from.
countThe number of transfers to make.
register_width_bitsThe width of the register to transfer to in bits. Valid values are 8, 16, 32, and 64.
send_evtIf set to true, the DMA engine will be instructed to send an event upon completion or fault.
evtIf send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
channelThe DMA channel thread to use for the transfer.
programAn allocated DMA program buffer to use for the life of the transfer.
bufThe buffer memory address to zero out.
sizeThe size of the buffer in bytes.
send_evtIf set to true, the DMA engine will be instructed to send an event upon completion or fault.
evtIf send_evt is true, the event specified will be sent. Otherwise the parameter is ignored.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given channel or event identifier (if used) is invalid.