 |
RTEMS 6.3
|
|
RTEMS 6.3
|
Topics | |
| Support for DMAMOV CCR | |
Data Structures | |
| struct | ALT_DMA_PROGRAM_s |
Macros | |
| #define | ALT_DMA_PROGRAM_CACHE_LINE_SIZE (32) |
| #define | ALT_DMA_PROGRAM_CACHE_LINE_COUNT (16) |
| #define | ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE (ALT_DMA_PROGRAM_CACHE_LINE_SIZE * ALT_DMA_PROGRAM_CACHE_LINE_COUNT) |
Typedefs | |
| typedef struct ALT_DMA_PROGRAM_s | ALT_DMA_PROGRAM_t |
| typedef enum ALT_DMA_PROGRAM_REG_e | ALT_DMA_PROGRAM_REG_t |
| typedef enum ALT_DMA_PROGRAM_INST_MOD_e | ALT_DMA_PROGRAM_INST_MOD_t |
Enumerations | |
| enum | ALT_DMA_PROGRAM_REG_e { ALT_DMA_PROGRAM_REG_SAR = 0x0 , ALT_DMA_PROGRAM_REG_DAR = 0x2 , ALT_DMA_PROGRAM_REG_CCR = 0x1 } |
| enum | ALT_DMA_PROGRAM_INST_MOD_e { ALT_DMA_PROGRAM_INST_MOD_NONE , ALT_DMA_PROGRAM_INST_MOD_SINGLE , ALT_DMA_PROGRAM_INST_MOD_BURST , ALT_DMA_PROGRAM_INST_MOD_PERIPH } |
This API provides functions for dynamically defining and assembling microcode programs for execution on the DMA controller.
The microcode program assembly API provides users with the ability to develop highly optimized and tailored algorithms for data transfer between SoC FPGA IP blocks and/or system memory.
The same microcode program assembly facilities are also used to implement the functions found in the HWLIB Common DMA Operations functional API.
An ALT_DMA_PROGRAM_t structure is used to contain and assemble a DMA microcode program. The storage for an ALT_DMA_PROGRAM_t stucture is allocated from used specified system memory. Once a microcode program has been assembled in a ALT_DMA_PROGRAM_t it may be excecuted on a designated DMA channel thread. The microcode program may be rerun on any DMA channel thread whenever required as long as the integrity of the ALT_DMA_PROGRAM_t containing the program is maintained.
| #define ALT_DMA_PROGRAM_CACHE_LINE_COUNT (16) |
This preprocessor declares the DMA channel thread microcode instruction cache line count. Thus the total size of the cache is the cache line size multipled by the cache line count. Programs larger than the cache size risk having a cache miss while executing.
| #define ALT_DMA_PROGRAM_CACHE_LINE_SIZE (32) |
This preprocessor declares the DMA channel thread microcode instruction cache line width in bytes. It is recommended that the program buffers be sized to a multiple of the cache line size. This will allow for the most efficient microcode speed and space utilization.
| #define ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE (ALT_DMA_PROGRAM_CACHE_LINE_SIZE * ALT_DMA_PROGRAM_CACHE_LINE_COUNT) |
This preprocessor definition determines the size of the program buffer within the ALT_DMA_PROGRAM_t structure. This size should provide adequate size for most DMA microcode programs. If calls within this API are reporting out of memory response codes, consider increasing the provisioned program buffersize.
To specify another DMA microcode program buffer size, redefine the macro below by defining ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE to another size in your Makefile. It is recommended that the size be a multiple of the microcode engine cache line size. See ALT_DMA_PROGRAM_CACHE_LINE_SIZE for more information. The largest supported buffer size is 65536 bytes.
| typedef enum ALT_DMA_PROGRAM_INST_MOD_e ALT_DMA_PROGRAM_INST_MOD_t |
This type definition enumerates the instruction modifier options available for use with selected DMA microcode instructions.
The enumerations values are context dependent upon the instruction being modified.
For the DMALD[S|B], DMALDP<S|B>, DMAST[S|B], and DMASTP<S|B> microcode instructions, the enumeration ALT_DMA_PROGRAM_INST_MOD_SINGLE specifies the S option modifier while the enumeration ALT_DMA_PROGRAM_INST_MOD_BURST specifies the B option modifier. The enumeration ALT_DMA_PROGRAM_INST_MOD_NONE specifies that no modifier is present for instructions where use of [S|B] is optional.
For the DMAWFP microcode instruction, the enumerations ALT_DMA_PROGRAM_INST_MOD_SINGLE, ALT_DMA_PROGRAM_INST_MOD_BURST, or ALT_DMA_PROGRAM_INST_MOD_PERIPH each specify one of the corresponding options <single|burst|periph>.
| typedef enum ALT_DMA_PROGRAM_REG_e ALT_DMA_PROGRAM_REG_t |
This type definition enumerates the DMA controller register names for use in microcode program definition.
| typedef struct ALT_DMA_PROGRAM_s ALT_DMA_PROGRAM_t |
This type defines the structure used to assemble and contain a microcode program which can be executed by the DMA controller. The internal members are undocumented and should not be altered outside of this API.
This type definition enumerates the instruction modifier options available for use with selected DMA microcode instructions.
The enumerations values are context dependent upon the instruction being modified.
For the DMALD[S|B], DMALDP<S|B>, DMAST[S|B], and DMASTP<S|B> microcode instructions, the enumeration ALT_DMA_PROGRAM_INST_MOD_SINGLE specifies the S option modifier while the enumeration ALT_DMA_PROGRAM_INST_MOD_BURST specifies the B option modifier. The enumeration ALT_DMA_PROGRAM_INST_MOD_NONE specifies that no modifier is present for instructions where use of [S|B] is optional.
For the DMAWFP microcode instruction, the enumerations ALT_DMA_PROGRAM_INST_MOD_SINGLE, ALT_DMA_PROGRAM_INST_MOD_BURST, or ALT_DMA_PROGRAM_INST_MOD_PERIPH each specify one of the corresponding options <single|burst|periph>.
| ALT_STATUS_CODE alt_dma_program_clear | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
This function clears the existing DMA microcode program in the given program buffer.
| pgm | A pointer to a DMA program buffer structure. |
| ALT_E_SUCCESS | The operation was successful. |
| ALT_E_ERROR | Details about error status code. |
| ALT_STATUS_CODE alt_dma_program_DMAADDH | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_REG_t | addr_reg, | ||
| uint16_t | val ) |
Assembles a DMAADDH (Add Halfword) instruction into the microcode program buffer. This instruction uses 3 bytes of buffer space.
| pgm | The DMA program buffer to contain the assembled instruction. |
| addr_reg | The channel address register (ALT_DMA_PROGRAM_REG_DAR or ALT_DMA_PROGRAM_REG_SAR) to add the value to. |
| val | The 16-bit unsigned value to add to the channel address register. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid channel register specified. |
| ALT_STATUS_CODE alt_dma_program_DMAADNH | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_REG_t | addr_reg, | ||
| uint16_t | val ) |
Assembles a DMAADNH (Add Negative Halfword) instruction into the microcode program buffer. This instruction uses 3 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| addr_reg | The channel address register (ALT_DMA_PROGRAM_REG_DAR or ALT_DMA_PROGRAM_REG_SAR) to add the value to. |
| val | The 16-bit unsigned value to add to the channel address register. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid channel register specified. |
| ALT_STATUS_CODE alt_dma_program_DMAEND | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
Assembles a DMAEND (End) instruction into the microcode program buffer. This instruction uses 1 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_STATUS_CODE alt_dma_program_DMAFLUSHP | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PERIPH_t | periph ) |
Assembles a DMAFLUSHP (Flush Peripheral) instruction into the microcode program buffer. This instruction uses 2 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| periph | The peripheral to flush. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid peripheral specified. |
| ALT_STATUS_CODE alt_dma_program_DMAGO | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_CHANNEL_t | channel, | ||
| uint32_t | val, | ||
| ALT_DMA_SECURITY_t | sec ) |
Assembles a DMAGO (Go) instruction into the microcode program buffer. This instruction uses 6 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| channel | The stopped channel to act upon. |
| val | The value to write to the channel program counter register. |
| sec | The security state for the operation. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid channel or security specified. |
| ALT_STATUS_CODE alt_dma_program_DMAKILL | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
Assembles a DMAKILL (Kill) instruction into the microcode program buffer. This instruction uses 1 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_STATUS_CODE alt_dma_program_DMALD | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_INST_MOD_t | mod ) |
Assembles a DMALD (Load) instruction into the microcode program buffer. This instruction uses 1 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| mod | The program instruction modifier for the type of transfer. Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and ALT_DMA_PROGRAM_INST_MOD_BURST are valid options. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid instruction modifier specified. |
| ALT_STATUS_CODE alt_dma_program_DMALDP | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_INST_MOD_t | mod, | ||
| ALT_DMA_PERIPH_t | periph ) |
Assembles a DMALDP (Load and notify Peripheral) instruction into the microcode program buffer. This instruction uses 2 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| mod | The program instruction modifier for the type of transfer. Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and ALT_DMA_PROGRAM_INST_MOD_BURST are valid options. |
| periph | The peripheral to notify. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid instruction modifier or peripheral specified. |
| ALT_STATUS_CODE alt_dma_program_DMALP | ( | ALT_DMA_PROGRAM_t * | pgm, |
| uint32_t | iterations ) |
Assembles a DMALP (Loop) instruction into the microcode program buffer. This instruction uses 2 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| iterations | The number of iterations to run for. Valid values are 1 - 256. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid iterations specified. |
| ALT_E_BAD_OPERATION | All loop registers are in use. |
| ALT_STATUS_CODE alt_dma_program_DMALPEND | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_INST_MOD_t | mod ) |
Assembles a DMALPEND (Loop End) instruction into the microcode program buffer. This instruction uses 2 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| mod | The program instruction modifier for the loop terminator. Only ALT_DMA_PROGRAM_INST_MOD_NONE, ALT_DMA_PROGRAM_INST_MOD_SINGLE and ALT_DMA_PROGRAM_INST_MOD_BURST are valid options. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid instruction modifier specified. |
| ALT_E_ARG_RANGE | Loop size is too large to be supported. |
| ALT_E_BAD_OPERATION | A valid DMALP or DMALPFE was not added to the program buffer before adding this DMALPEND instruction. |
| ALT_STATUS_CODE alt_dma_program_DMALPFE | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
Assembles a DMALPFE (Loop Forever) instruction into the microcode program buffer. No instruction is added to the buffer but a previous DMALPEND to create an infinite loop.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_STATUS_CODE alt_dma_program_DMAMOV | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_REG_t | chan_reg, | ||
| uint32_t | val ) |
Assembles a DMAMOV (Move) instruction into the microcode program buffer. This instruction uses 6 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| chan_reg | The channel non-looping register (ALT_DMA_PROGRAM_REG_SAR, ALT_DMA_PROGRAM_REG_DAR or ALT_DMA_PROGRAM_REG_CCR) to copy the value to. |
| val | The value to write to the specified register. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid channel register specified. |
| ALT_STATUS_CODE alt_dma_program_DMANOP | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
Assembles a DMANOP (No Operation) instruction into the microcode program buffer. This instruction uses 1 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_STATUS_CODE alt_dma_program_DMARMB | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
Assembles a DMARMB (Read Memory Barrier) instruction into the microcode program buffer. This instruction uses 1 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_STATUS_CODE alt_dma_program_DMASEV | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_EVENT_t | evt ) |
Assembles a DMASEV (Send Event) instruction into the microcode program buffer. This instruction uses 2 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| evt | The event to send. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid event specified. |
| ALT_STATUS_CODE alt_dma_program_DMAST | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_INST_MOD_t | mod ) |
Assembles a DMAST (Store) instruction into the microcode program buffer. This instruction uses 1 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| mod | The program instruction modifier for the type of transfer. Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and ALT_DMA_PROGRAM_INST_MOD_BURST are valid options. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_STATUS_CODE alt_dma_program_DMASTP | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_INST_MOD_t | mod, | ||
| ALT_DMA_PERIPH_t | periph ) |
Assembles a DMASTP (Store and notify Peripheral) instruction into the microcode program buffer. This instruction uses 2 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| mod | The program instruction modifier for the type of transfer. Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and ALT_DMA_PROGRAM_INST_MOD_BURST are valid options. |
| periph | The peripheral to notify. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid instruction modifier or peripheral specified. |
| ALT_STATUS_CODE alt_dma_program_DMASTZ | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
Assembles a DMASTZ (Store Zero) instruction into the microcode program buffer. This instruction uses 1 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_STATUS_CODE alt_dma_program_DMAWFE | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_EVENT_t | evt, | ||
| bool | invalid ) |
Assembles a DMAWFE (Wait For Event) instruction into the microcode program buffer. This instruction uses 2 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| evt | The event to wait for. |
| invalid | If invalid is set to true, the instruction will be configured to invalidate the instruction cache for the current DMA thread. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid event specified. |
| ALT_STATUS_CODE alt_dma_program_DMAWFP | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PERIPH_t | periph, | ||
| ALT_DMA_PROGRAM_INST_MOD_t | mod ) |
Assembles a DMAWFP (Wait for Peripheral) instruction into the microcode program buffer. This instruction uses 2 bytes of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| periph | The peripheral to wait on. |
| mod | The program instruction modifier for the type of transfer. Only ALT_DMA_PROGRAM_INST_MOD_SINGLE, ALT_DMA_PROGRAM_INST_MOD_BURST, or ALT_DMA_PROGRAM_INST_MOD_PERIPH are valid options. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_E_BAD_ARG | Invalid peripheral or instruction modifier specified. |
| ALT_STATUS_CODE alt_dma_program_DMAWMB | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
Assembles a DMAWMB (Write Memory Barrier) instruction into the microcode program buffer. This instruction uses 1 byte of buffer space.
| pgm | The DMA programm buffer to contain the assembled instruction. |
| ALT_E_SUCCESS | Successful instruction assembly status. |
| ALT_E_DMA_BUF_OVF | DMA program buffer overflow. |
| ALT_STATUS_CODE alt_dma_program_init | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
This function initializes a system memory buffer for use as a DMA microcode program buffer. This should be the first API call made on the program buffer type.
| pgm | A pointer to a DMA program buffer structure. |
| ALT_E_SUCCESS | The operation was successful. |
| ALT_E_ERROR | Details about error status code |
| ALT_STATUS_CODE alt_dma_program_progress_reg | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_REG_t | reg, | ||
| uint32_t | current, | ||
| uint32_t * | progress ) |
This function reports the number bytes incremented for the register specified. The purpose is to determine the progress of an ongoing DMA transfer.
It is implemented by calculating the difference of the programmed SAR or DAR with the current channel SAR or DAR register value.
| pgm | A pointer to a DMA program buffer structure. |
| channel | The channel that the program is running on. |
| reg | Register to change the value for. Valid for only ALT_DMA_PROGRAM_REG_SAR and ALT_DMA_PROGRAM_REG_DAR. |
| current | The current snapshot value of the register read from the DMA channel. |
| progress | [out] A pointer to a memory location that will be used to store the number of bytes transfered. |
| ALT_E_SUCCESS | The operation was successful. |
| ALT_E_ERROR | Details about error status code. |
| ALT_E_BAD_ARG | The specified channel is invalid, the specified register is invalid, or the DMAMOV for the specified register has not yet been assembled in the current program buffer. |
| ALT_STATUS_CODE alt_dma_program_uninit | ( | ALT_DMA_PROGRAM_t * | pgm | ) |
This function verifies that the DMA microcode program buffer is no longer in use and performs any needed uninitialization steps.
| pgm | A pointer to a DMA program buffer structure. |
| ALT_E_SUCCESS | The operation was successful. |
| ALT_E_ERROR | Details about error status code |
| ALT_STATUS_CODE alt_dma_program_update_reg | ( | ALT_DMA_PROGRAM_t * | pgm, |
| ALT_DMA_PROGRAM_REG_t | reg, | ||
| uint32_t | val ) |
This function updates a pre-existing DMAMOV value affecting the SAR or DAR registers. This allows for pre-assembled programs that can be used on different source and destination addresses.
| pgm | A pointer to a DMA program buffer structure. |
| reg | Register to change the value for. Valid for only ALT_DMA_PROGRAM_REG_SAR and ALT_DMA_PROGRAM_REG_DAR. |
| val | The value to update to. |
| ALT_E_SUCCESS | The operation was successful. |
| ALT_E_ERROR | Details about error status code. |
| ALT_E_BAD_ARG | The specified register is invalid or the DMAMOV for the specified register has not yet been assembled in the current program buffer. |
| ALT_STATUS_CODE alt_dma_program_validate | ( | const ALT_DMA_PROGRAM_t * | pgm | ) |
This function validate that the given DMA microcode program buffer contains a well formed program. If caches are enabled, the program buffer contents will be cleaned to RAM.
| pgm | A pointer to a DMA program buffer structure. |
| ALT_E_SUCCESS | The given program is well formed. |
| ALT_E_ERROR | The given program is not well formed. |
| ALT_E_TMO | The cache operation timed out. |
1.18.0