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_STATUS_CODE | alt_dma_memory_to_memory (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *program, void *va_dest, const void *va_src, size_t size, ALT_DMA_EVENT_t evt, const uint64_t *ttb, const ALT_MMU_TCR_INFO_t *ttbconfig) |
|
ALT_STATUS_CODE | alt_dma_zero_to_memory (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *program, void *buf, size_t size, ALT_DMA_EVENT_t evt, const uint64_t *ttb, const ALT_MMU_TCR_INFO_t *ttbconfig) |
|
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, ALT_DMA_EVENT_t evt, const uint64_t *ttb, const ALT_MMU_TCR_INFO_t *ttbconfig) |
|
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, ALT_DMA_EVENT_t evt, const uint64_t *ttb, const ALT_MMU_TCR_INFO_t *ttbconfig) |
|
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, ALT_DMA_EVENT_t evt, const uint64_t *ttb, const ALT_MMU_TCR_INFO_t *ttbconfig) |
|
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, ALT_DMA_EVENT_t evt, const uint64_t *ttb, const ALT_MMU_TCR_INFO_t *ttbconfig) |
|
struct ALT_DMA_PERIPH_INFO_I2C_s |
This type defines the structure used by alt_dma_memory_to_periph() and alt_dma_periph_to_memory() for the periph_info pointer when transfering to or from I2C peripherals. The fields of this structure should be filled out appropriately then used as in those functions.
It is necessary for the contents of the structure to be undisturbed while the DMA transfer is in progress. Thus if it is allocated on the stack, it will need to be in scope until the DMA operation completes or fails.
Data Fields |
ALT_I2C_DEV_t * |
i2c_dev |
The I2C device handle. |
bool |
issue_restart |
When the I2C controller is configured as bus master, this indicates that the transfer should issue a RESTART at the start of the transfer. When configured as bus slave, this parameter is ignored. |
bool |
issue_stop |
When the I2C controller is configured as bus master, this indicates that the transfer should issue a STOP at the end of the transfer. When configured as bus slave, this parameter is ignored. |
uint32_t |
scratch |
Scratch space used by the I2C DMA implementation. |
This type defines the structure used by alt_dma_memory_to_periph() and alt_dma_periph_to_memory() for the periph_info pointer when transfering to or from I2C peripherals. The fields of this structure should be filled out appropriately then used as in those functions.
It is necessary for the contents of the structure to be undisturbed while the DMA transfer is in progress. Thus if it is allocated on the stack, it will need to be in scope until the DMA operation completes or fails.
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. |
va_dest | The destination memory address to copy to. |
va_src | The source memory address to copy from. |
size | The size of the transfer in bytes. |
evt | The event specified will be sent. For no event, use ALT_DMA_EVENT_NONE |
ttb | - translation table pointer. This is the value used when setting up the mmu initially. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. To get the ttb of the current context, you can call alt_mmu_read_ttb() |
ttbconfig | - configured system ttb configuration. This is usually set up once at init time, and is needed for figuring out the physical locations of va's. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. Otherwize, this can be found by calling alt_mmu_query_ttbconfig() |
- 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. |
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. |
evt | The event specified will be sent. For no event, use ALT_DMA_EVENT_NONE |
ttb | - translation table pointer. This is the value used when setting up the mmu initially. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. To get the ttb of the current context, you can call alt_mmu_read_ttb() |
ttbconfig | - configured system ttb configuration. This is usually set up once at init time, and is needed for figuring out the physical locations of va's. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. Otherwize, this can be found by calling alt_mmu_query_ttbconfig() |
- 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. |
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, |
|
|
ALT_DMA_EVENT_t |
evt, |
|
|
const uint64_t * |
ttb, |
|
|
const ALT_MMU_TCR_INFO_t * |
ttbconfig |
|
) |
| |
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. |
evt | The event specified will be sent. For no event, use ALT_DMA_EVENT_NONE |
ttb | - translation table pointer. This is the value used when setting up the mmu initially. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. To get the ttb of the current context, you can call alt_mmu_read_ttb() |
ttbconfig | - configured system ttb configuration. This is usually set up once at init time, and is needed for figuring out the physical locations of va's. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. Otherwize, this can be found by calling alt_mmu_query_ttbconfig() |
- 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_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, |
|
|
ALT_DMA_EVENT_t |
evt, |
|
|
const uint64_t * |
ttb, |
|
|
const ALT_MMU_TCR_INFO_t * |
ttbconfig |
|
) |
| |
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. |
evt | The event specified will be sent. For no event, use ALT_DMA_EVENT_NONE |
ttb | - translation table pointer. This is the value used when setting up the mmu initially. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. To get the ttb of the current context, you can call alt_mmu_read_ttb() |
ttbconfig | - configured system ttb configuration. This is usually set up once at init time, and is needed for figuring out the physical locations of va's. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. Otherwize, this can be found by calling alt_mmu_query_ttbconfig() |
- 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_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, |
|
|
ALT_DMA_EVENT_t |
evt, |
|
|
const uint64_t * |
ttb, |
|
|
const ALT_MMU_TCR_INFO_t * |
ttbconfig |
|
) |
| |
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_I2C0_TX
- ALT_DMA_PERIPH_I2C1_TX
- ALT_DMA_PERIPH_I2C2_TX
- ALT_DMA_PERIPH_I2C3_TX
- ALT_DMA_PERIPH_QSPI_FLASH_TX - (Not available on soc_s10)
- 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_I2C0_TX:
- ALT_DMA_PERIPH_I2C1_TX:
- ALT_DMA_PERIPH_I2C2_TX:
- ALT_DMA_PERIPH_I2C3_TX: Use a pointer to a filled out ALT_DMA_PERIPH_INFO_I2C_t structure.
- ALT_DMA_PERIPH_QSPI_FLASH_TX: This parameter is ignored.
- ALT_DMA_PERIPH_UART0_TX:
- ALT_DMA_PERIPH_UART1_TX: Use a pointer to the ALT_16550_HANDLE_t used to interact with that UART.
|
evt | The event specified will be sent. For no event, use ALT_DMA_EVENT_NONE |
ttb | - translation table pointer. This is the value used when setting up the mmu initially. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. To get the ttb of the current context, you can call alt_mmu_read_ttb() |
ttbconfig | - configured system ttb configuration. This is usually set up once at init time, and is needed for figuring out the physical locations of va's. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. Otherwize, this can be found by calling alt_mmu_query_ttbconfig() |
- 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_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, |
|
|
ALT_DMA_EVENT_t |
evt, |
|
|
const uint64_t * |
ttb, |
|
|
const ALT_MMU_TCR_INFO_t * |
ttbconfig |
|
) |
| |
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_I2C0_RX
- ALT_DMA_PERIPH_I2C1_RX
- ALT_DMA_PERIPH_I2C2_RX
- ALT_DMA_PERIPH_I2C3_RX
- ALT_DMA_PERIPH_QSPI_FLASH_RX (not available on soc_s10)
- 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_I2C0_RX:
- ALT_DMA_PERIPH_I2C1_RX:
- ALT_DMA_PERIPH_I2C2_RX:
- ALT_DMA_PERIPH_I2C3_RX: Use a pointer to a filled out ALT_DMA_PERIPH_INFO_I2C_t structure.
- ALT_DMA_PERIPH_QSPI_FLASH_RX: This parameter is ignored.
- ALT_DMA_PERIPH_UART0_RX:
- ALT_DMA_PERIPH_UART1_RX: Use a pointer to the ALT_16550_HANDLE_t used to interact with that UART.
|
evt | The event specified will be sent. For no event, use ALT_DMA_EVENT_NONE |
ttb | - translation table pointer. This is the value used when setting up the mmu initially. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. To get the ttb of the current context, you can call alt_mmu_read_ttb() |
ttbconfig | - configured system ttb configuration. This is usually set up once at init time, and is needed for figuring out the physical locations of va's. If the mmu is disabled, or a 1:1 va-pa mapping is done, you can pass NULL to avoid memory translations. Otherwize, this can be found by calling alt_mmu_query_ttbconfig() |
- 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. |