RTEMS: DMA Controller Programming API

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
DMA Controller Programming API
Board Support Packages » ARM » Intel Cyclone V » Contributed Code

## Modules
| 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 }

## Functions
ALT_STATUS_CODE | alt_dma_program_init (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_uninit (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_clear (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_validate (const ALT_DMA_PROGRAM_t *pgm)
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)
ALT_STATUS_CODE | alt_dma_program_update_reg (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_REG_t reg, uint32_t val)
ALT_STATUS_CODE | alt_dma_program_DMAADDH (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_REG_t addr_reg, uint16_t val)
ALT_STATUS_CODE | alt_dma_program_DMAADNH (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_REG_t addr_reg, uint16_t val)
ALT_STATUS_CODE | alt_dma_program_DMAEND (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_DMAFLUSHP (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PERIPH_t periph)
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)
ALT_STATUS_CODE | alt_dma_program_DMAKILL (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_DMALD (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_INST_MOD_t mod)
ALT_STATUS_CODE | alt_dma_program_DMALDP (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_INST_MOD_t mod, ALT_DMA_PERIPH_t periph)
ALT_STATUS_CODE | alt_dma_program_DMALP (ALT_DMA_PROGRAM_t *pgm, uint32_t iterations)
ALT_STATUS_CODE | alt_dma_program_DMALPEND (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_INST_MOD_t mod)
ALT_STATUS_CODE | alt_dma_program_DMALPFE (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_DMAMOV (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_REG_t chan_reg, uint32_t val)
ALT_STATUS_CODE | alt_dma_program_DMANOP (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_DMARMB (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_DMASEV (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_EVENT_t evt)
ALT_STATUS_CODE | alt_dma_program_DMAST (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_INST_MOD_t mod)
ALT_STATUS_CODE | alt_dma_program_DMASTP (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PROGRAM_INST_MOD_t mod, ALT_DMA_PERIPH_t periph)
ALT_STATUS_CODE | alt_dma_program_DMASTZ (ALT_DMA_PROGRAM_t *pgm)
ALT_STATUS_CODE | alt_dma_program_DMAWFE (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_EVENT_t evt, bool invalid)
ALT_STATUS_CODE | alt_dma_program_DMAWFP (ALT_DMA_PROGRAM_t *pgm, ALT_DMA_PERIPH_t periph, ALT_DMA_PROGRAM_INST_MOD_t mod)
ALT_STATUS_CODE | alt_dma_program_DMAWMB (ALT_DMA_PROGRAM_t *pgm)

## Detailed Description

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.

## Macro Definition Documentation

## ◆ ALT_DMA_PROGRAM_CACHE_LINE_COUNT

#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.

## ◆ ALT_DMA_PROGRAM_CACHE_LINE_SIZE

#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.

## ◆ ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE

#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 Documentation

## ◆ ALT_DMA_PROGRAM_INST_MOD_t

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>.

## ◆ ALT_DMA_PROGRAM_REG_t

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.

## ◆ ALT_DMA_PROGRAM_t

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.

## Enumeration Type Documentation

## ◆ ALT_DMA_PROGRAM_INST_MOD_e

enum ALT_DMA_PROGRAM_INST_MOD_e

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>.

Enumerator
ALT_DMA_PROGRAM_INST_MOD_NONE | This DMA instruction modifier specifies that no special modifier is added to the instruction.
ALT_DMA_PROGRAM_INST_MOD_SINGLE | Depending on the DMA microcode instruction modified, this modifier specifies S case for a [S|B] or a <single> for a <single|burst|periph>.
ALT_DMA_PROGRAM_INST_MOD_BURST | Depending on the DMA microcode instruction modified, this modifier specifies B case for a [S|B] or a <burst> for a <single|burst|periph>.
ALT_DMA_PROGRAM_INST_MOD_PERIPH | This DMA instruction modifier specifies a <periph> for a <single|burst|periph>.

## ◆ ALT_DMA_PROGRAM_REG_e

enum ALT_DMA_PROGRAM_REG_e

This type definition enumerates the DMA controller register names for use in microcode program definition.

Enumerator
ALT_DMA_PROGRAM_REG_SAR | Source Address Register
ALT_DMA_PROGRAM_REG_DAR | Destination Address Register
ALT_DMA_PROGRAM_REG_CCR | Channel Control Register

## Function Documentation

## ◆ alt_dma_program_clear()

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.

Parameters

  pgm | A pointer to a DMA program buffer structure.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | Details about error status code.

## ◆ alt_dma_program_DMAADDH()

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.

Parameters

  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.

Return values

  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_dma_program_DMAADNH()

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.

Parameters

  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.

Return values

  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_dma_program_DMAEND()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.

## ◆ alt_dma_program_DMAFLUSHP()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.
  periph | The peripheral to flush.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.
  ALT_E_BAD_ARG | Invalid peripheral specified.

## ◆ alt_dma_program_DMAGO()

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.

Parameters

  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.

Return values

  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_dma_program_DMAKILL()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.

## ◆ alt_dma_program_DMALD()

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.

Parameters

  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.

Return values

  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_dma_program_DMALDP()

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.

Parameters

  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.

Return values

  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_dma_program_DMALP()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.
  iterations | The number of iterations to run for. Valid values are 1 - 256.

Return values

  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_dma_program_DMALPEND()

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.

Parameters

  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.

Return values

  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_dma_program_DMALPFE()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.

## ◆ alt_dma_program_DMAMOV()

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.

Parameters

  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.

Return values

  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_dma_program_DMANOP()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.

## ◆ alt_dma_program_DMARMB()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.

## ◆ alt_dma_program_DMASEV()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.
  evt | The event to send.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.
  ALT_E_BAD_ARG | Invalid event specified.

## ◆ alt_dma_program_DMAST()

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.

Parameters

  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.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.

## ◆ alt_dma_program_DMASTP()

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.

Parameters

  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.

Return values

  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_dma_program_DMASTZ()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.

## ◆ alt_dma_program_DMAWFE()

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.

Parameters

  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.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.
  ALT_E_BAD_ARG | Invalid event specified.

## ◆ alt_dma_program_DMAWFP()

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.

Parameters

  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.

Return values

  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_dma_program_DMAWMB()

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.

Parameters

  pgm | The DMA programm buffer to contain the assembled instruction.

Return values

  ALT_E_SUCCESS | Successful instruction assembly status.
  ALT_E_DMA_BUF_OVF | DMA program buffer overflow.

## ◆ alt_dma_program_init()

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.

Parameters

  pgm | A pointer to a DMA program buffer structure.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | Details about error status code

## ◆ alt_dma_program_progress_reg()

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.

Parameters

  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.

Return values

  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_dma_program_uninit()

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.

Parameters

  pgm | A pointer to a DMA program buffer structure.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | Details about error status code

## ◆ alt_dma_program_update_reg()

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.

Parameters

  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.

Return values

  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_dma_program_validate()

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.

Parameters

  pgm | A pointer to a DMA program buffer structure.

Return values

  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.