DMA API for Standard Operations

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.