RTEMS  5.0.0
Data Structures | Typedefs | Enumerations | Functions
DMA API for Configuration, Control, and Status

Data Structures

struct  ALT_DMA_CFG_s
 

Typedefs

typedef enum ALT_DMA_MANAGER_STATE_e ALT_DMA_MANAGER_STATE_t
 
typedef enum ALT_DMA_CHANNEL_STATE_e ALT_DMA_CHANNEL_STATE_t
 
typedef enum ALT_DMA_MANAGER_FAULT_e ALT_DMA_MANAGER_FAULT_t
 
typedef enum ALT_DMA_CHANNEL_FAULT_e ALT_DMA_CHANNEL_FAULT_t
 
typedef enum ALT_DMA_EVENT_SELECT_e ALT_DMA_EVENT_SELECT_t
 
typedef enum ALT_DMA_PERIPH_MUX_e ALT_DMA_PERIPH_MUX_t
 
typedef struct ALT_DMA_CFG_s ALT_DMA_CFG_t
 

Enumerations

enum  ALT_DMA_MANAGER_STATE_e {
  ALT_DMA_MANAGER_STATE_STOPPED = 0, ALT_DMA_MANAGER_STATE_EXECUTING = 1, ALT_DMA_MANAGER_STATE_CACHE_MISS = 2, ALT_DMA_MANAGER_STATE_UPDATING_PC = 3,
  ALT_DMA_MANAGER_STATE_WFE = 4, ALT_DMA_MANAGER_STATE_FAULTING = 15
}
 
enum  ALT_DMA_CHANNEL_STATE_e {
  ALT_DMA_CHANNEL_STATE_STOPPED = 0, ALT_DMA_CHANNEL_STATE_EXECUTING = 1, ALT_DMA_CHANNEL_STATE_CACHE_MISS = 2, ALT_DMA_CHANNEL_STATE_UPDATING_PC = 3,
  ALT_DMA_CHANNEL_STATE_WFE = 4, ALT_DMA_CHANNEL_STATE_AT_BARRIER = 5, ALT_DMA_CHANNEL_STATE_WFP = 7, ALT_DMA_CHANNEL_STATE_KILLING = 8,
  ALT_DMA_CHANNEL_STATE_COMPLETING = 9, ALT_DMA_CHANNEL_STATE_FAULTING_COMPLETING = 14, ALT_DMA_CHANNEL_STATE_FAULTING = 15
}
 
enum  ALT_DMA_MANAGER_FAULT_e {
  ALT_DMA_MANAGER_FAULT_DBG_INSTR = (int32_t)(1UL << 30), ALT_DMA_MANAGER_FAULT_INSTR_FETCH_ERR = (int32_t)(1UL << 16), ALT_DMA_MANAGER_FAULT_MGR_EVNT_ERR = (int32_t)(1UL << 5), ALT_DMA_MANAGER_FAULT_DMAGO_ERR = (int32_t)(1UL << 4),
  ALT_DMA_MANAGER_FAULT_OPERAND_INVALID = (int32_t)(1UL << 1), ALT_DMA_MANAGER_FAULT_UNDEF_INSTR = (int32_t)(1UL << 0)
}
 
enum  ALT_DMA_CHANNEL_FAULT_e {
  ALT_DMA_CHANNEL_FAULT_LOCKUP_ERR = (int32_t)(1UL << 31), ALT_DMA_CHANNEL_FAULT_DBG_INSTR = (int32_t)(1UL << 30), ALT_DMA_CHANNEL_FAULT_DATA_READ_ERR = (int32_t)(1UL << 18), ALT_DMA_CHANNEL_FAULT_DATA_WRITE_ERR = (int32_t)(1UL << 17),
  ALT_DMA_CHANNEL_FAULT_INSTR_FETCH_ERR = (int32_t)(1UL << 16), ALT_DMA_CHANNEL_FAULT_ST_DATA_UNAVAILABLE = (int32_t)(1UL << 13), ALT_DMA_CHANNEL_FAULT_MFIFO_ERR = (int32_t)(1UL << 12), ALT_DMA_CHANNEL_FAULT_CH_RDWR_ERR = (int32_t)(1UL << 7),
  ALT_DMA_CHANNEL_FAULT_CH_PERIPH_ERR = (int32_t)(1UL << 6), ALT_DMA_CHANNEL_FAULT_CH_EVNT_ERR = (int32_t)(1UL << 5), ALT_DMA_CHANNEL_FAULT_OPERAND_INVALID = (int32_t)(1UL << 1), ALT_DMA_CHANNEL_FAULT_UNDEF_INSTR = (int32_t)(1UL << 0)
}
 
enum  ALT_DMA_EVENT_SELECT_e { ALT_DMA_EVENT_SELECT_SEND_EVT, ALT_DMA_EVENT_SELECT_SIG_IRQ }
 
enum  ALT_DMA_PERIPH_MUX_e { ALT_DMA_PERIPH_MUX_DEFAULT = 0, ALT_DMA_PERIPH_MUX_FPGA = 1, ALT_DMA_PERIPH_MUX_CAN = 2 }
 

Functions

ALT_STATUS_CODE alt_dma_init (const ALT_DMA_CFG_t *dma_cfg)
 
ALT_STATUS_CODE alt_dma_uninit (void)
 
ALT_STATUS_CODE alt_dma_channel_alloc (ALT_DMA_CHANNEL_t channel)
 
ALT_STATUS_CODE alt_dma_channel_alloc_any (ALT_DMA_CHANNEL_t *allocated)
 
ALT_STATUS_CODE alt_dma_channel_free (ALT_DMA_CHANNEL_t channel)
 
ALT_STATUS_CODE alt_dma_channel_exec (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_t *pgm)
 
ALT_STATUS_CODE alt_dma_channel_kill (ALT_DMA_CHANNEL_t channel)
 
ALT_STATUS_CODE alt_dma_channel_reg_get (ALT_DMA_CHANNEL_t channel, ALT_DMA_PROGRAM_REG_t reg, uint32_t *val)
 
ALT_STATUS_CODE alt_dma_send_event (ALT_DMA_EVENT_t evt_num)
 
ALT_STATUS_CODE alt_dma_manager_state_get (ALT_DMA_MANAGER_STATE_t *state)
 
ALT_STATUS_CODE alt_dma_channel_state_get (ALT_DMA_CHANNEL_t channel, ALT_DMA_CHANNEL_STATE_t *state)
 
ALT_STATUS_CODE alt_dma_manager_fault_status_get (ALT_DMA_MANAGER_FAULT_t *fault)
 
ALT_STATUS_CODE alt_dma_channel_fault_status_get (ALT_DMA_CHANNEL_t channel, ALT_DMA_CHANNEL_FAULT_t *fault)
 
ALT_STATUS_CODE alt_dma_event_int_select (ALT_DMA_EVENT_t evt_num, ALT_DMA_EVENT_SELECT_t opt)
 
ALT_STATUS_CODE alt_dma_event_int_status_get_raw (ALT_DMA_EVENT_t evt_num)
 
ALT_STATUS_CODE alt_dma_int_status_get (ALT_DMA_EVENT_t irq_num)
 
ALT_STATUS_CODE alt_dma_int_clear (ALT_DMA_EVENT_t irq_num)
 

Detailed Description

This API provides functions for configuration, control, and status queries of the DMA controller.

Typedef Documentation

◆ ALT_DMA_CFG_t

typedef struct ALT_DMA_CFG_s ALT_DMA_CFG_t

This type defines the structure used to specify the configuration of the security states and peripheral interface MUX selections for the DMA controller.

◆ ALT_DMA_CHANNEL_FAULT_t

This type definition enumerates the possible fault status that a channel may have as a register mask.

◆ ALT_DMA_CHANNEL_STATE_t

This type definition enumerates the operational states that a DMA channel may have.

◆ ALT_DMA_EVENT_SELECT_t

This type definition enumerates the possible DMA event-interrupt behavior option selections when a DMASEV instruction is executed.

◆ ALT_DMA_MANAGER_FAULT_t

This type definition enumerates the possible fault status that the DMA manager can have as a register mask.

◆ ALT_DMA_MANAGER_STATE_t

This type definition enumerates the operational states that the DMA manager may have.

◆ ALT_DMA_PERIPH_MUX_t

This type enumerates the DMA peripheral interface MUX selection options available.

Enumeration Type Documentation

◆ ALT_DMA_CHANNEL_FAULT_e

This type definition enumerates the possible fault status that a channel may have as a register mask.

Enumerator
ALT_DMA_CHANNEL_FAULT_LOCKUP_ERR 

The DMA channel has locked up due to resource starvation.

ALT_DMA_CHANNEL_FAULT_DBG_INSTR 

The DMA channel abort occured because of an instruction issued through the debug interface.

ALT_DMA_CHANNEL_FAULT_DATA_READ_ERR 

The DMA channel data read AXI bus reponse was not OKAY.

ALT_DMA_CHANNEL_FAULT_DATA_WRITE_ERR 

The DMA channel data write AXI bus response was not OKAY.

ALT_DMA_CHANNEL_FAULT_INSTR_FETCH_ERR 

The DMA channel instruction fetch AXI bus response was not OKAY.

ALT_DMA_CHANNEL_FAULT_ST_DATA_UNAVAILABLE 

The DMA channel MFIFO did not have the data for the DMAST instruction.

ALT_DMA_CHANNEL_FAULT_MFIFO_ERR 

The DMA channel MFIFO is too small to hold the DMALD instruction data, or too small to servic the DMAST instruction request.

ALT_DMA_CHANNEL_FAULT_CH_RDWR_ERR 

The DMA channel in non-secure state attempted to perform a secure read or write.

ALT_DMA_CHANNEL_FAULT_CH_PERIPH_ERR 

The DMA channel in non-secure state attempted to execute the DMAWFP, DMALDP, DMASTP, or DMAFLUSHP instruction involving a secure peripheral.

ALT_DMA_CHANNEL_FAULT_CH_EVNT_ERR 

The DMA channel in non-secure state attempted to execute the DMAWFE or DMASEV instruction for a secure event or secure interrupt (if applicable).

ALT_DMA_CHANNEL_FAULT_OPERAND_INVALID 

The DMA channel attempted to execute an instruction operand that was not valid for the DMA configuration.

ALT_DMA_CHANNEL_FAULT_UNDEF_INSTR 

The DMA channel attempted to execute an undefined instruction.

◆ ALT_DMA_CHANNEL_STATE_e

This type definition enumerates the operational states that a DMA channel may have.

Enumerator
ALT_DMA_CHANNEL_STATE_STOPPED 

Stopped

ALT_DMA_CHANNEL_STATE_EXECUTING 

Executing

ALT_DMA_CHANNEL_STATE_CACHE_MISS 

Cache Miss

ALT_DMA_CHANNEL_STATE_UPDATING_PC 

Updating PC

ALT_DMA_CHANNEL_STATE_WFE 

Waiting for Event

ALT_DMA_CHANNEL_STATE_AT_BARRIER 

At Barrier

ALT_DMA_CHANNEL_STATE_WFP 

Waiting for Peripheral

ALT_DMA_CHANNEL_STATE_KILLING 

Killing

ALT_DMA_CHANNEL_STATE_COMPLETING 

Completing

ALT_DMA_CHANNEL_STATE_FAULTING_COMPLETING 

Faulting Completing

ALT_DMA_CHANNEL_STATE_FAULTING 

Faulting

◆ ALT_DMA_EVENT_SELECT_e

This type definition enumerates the possible DMA event-interrupt behavior option selections when a DMASEV instruction is executed.

Enumerator
ALT_DMA_EVENT_SELECT_SEND_EVT 

If the DMA controller executes DMASEV for the event-interrupt resource then the DMA sends the event to all of the channel threads.

ALT_DMA_EVENT_SELECT_SIG_IRQ 

If the DMA controller executes DMASEV for the event-interrupt resource then the DMA sets the irq[N] HIGH.

◆ ALT_DMA_MANAGER_FAULT_e

This type definition enumerates the possible fault status that the DMA manager can have as a register mask.

Enumerator
ALT_DMA_MANAGER_FAULT_DBG_INSTR 

The DMA manager abort occured because of an instruction issued through the debug interface.

ALT_DMA_MANAGER_FAULT_INSTR_FETCH_ERR 

The DMA manager instruction fetch AXI bus response was not OKAY.

ALT_DMA_MANAGER_FAULT_MGR_EVNT_ERR 

The DMA manager attempted to execute DMAWFE or DMASEV with inappropriate security permissions.

ALT_DMA_MANAGER_FAULT_DMAGO_ERR 

The DMA manager attempted to execute DMAGO with inappropriate security permissions.

ALT_DMA_MANAGER_FAULT_OPERAND_INVALID 

The DMA manager attempted to execute an instruction operand that was not valid for the DMA configuration.

ALT_DMA_MANAGER_FAULT_UNDEF_INSTR 

The DMA manager attempted to execute an undefined instruction.

◆ ALT_DMA_MANAGER_STATE_e

This type definition enumerates the operational states that the DMA manager may have.

Enumerator
ALT_DMA_MANAGER_STATE_STOPPED 

Stopped

ALT_DMA_MANAGER_STATE_EXECUTING 

Executing

ALT_DMA_MANAGER_STATE_CACHE_MISS 

Cache Miss

ALT_DMA_MANAGER_STATE_UPDATING_PC 

Updating PC

ALT_DMA_MANAGER_STATE_WFE 

Waiting for Event

ALT_DMA_MANAGER_STATE_FAULTING 

Faulting

◆ ALT_DMA_PERIPH_MUX_e

This type enumerates the DMA peripheral interface MUX selection options available.

Enumerator
ALT_DMA_PERIPH_MUX_DEFAULT 

Accept the reset default MUX selection

ALT_DMA_PERIPH_MUX_FPGA 

Select FPGA as the peripheral interface

ALT_DMA_PERIPH_MUX_CAN 

Select CAN as the peripheral interface

Function Documentation

◆ alt_dma_channel_alloc()

ALT_STATUS_CODE alt_dma_channel_alloc ( ALT_DMA_CHANNEL_t  channel)

Allocate a DMA channel resource for use.

Parameters
channelA DMA controller channel.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.

◆ alt_dma_channel_alloc_any()

ALT_STATUS_CODE alt_dma_channel_alloc_any ( ALT_DMA_CHANNEL_t allocated)

Allocate a free DMA channel resource for use if there are any.

Parameters
allocated[out] A pointer to an output parameter that will contain the channel allocated.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed. An unallocated channel may not be available at the time of the API call.

◆ alt_dma_channel_exec()

ALT_STATUS_CODE alt_dma_channel_exec ( ALT_DMA_CHANNEL_t  channel,
ALT_DMA_PROGRAM_t pgm 
)

Start execution of a DMA microcode program on the specified DMA channel thread resource.

Parameters
channelThe DMA channel thread used to execute the microcode program.
pgmThe DMA microcode program.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.

◆ alt_dma_channel_fault_status_get()

ALT_STATUS_CODE alt_dma_channel_fault_status_get ( ALT_DMA_CHANNEL_t  channel,
ALT_DMA_CHANNEL_FAULT_t fault 
)

Return the current fault status of the specified DMA channel thread.

Parameters
channelThe DMA channel thread to return the fault status of.
fault[out] Pointer to an output parameter to contain the DMA channel fault status.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given channel identifier is invalid.

◆ alt_dma_channel_free()

ALT_STATUS_CODE alt_dma_channel_free ( ALT_DMA_CHANNEL_t  channel)

Free a DMA channel resource for reuse.

Parameters
channelThe DMA controller channel resource to free.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed. The channel may not be in the STOPPED state.

◆ alt_dma_channel_kill()

ALT_STATUS_CODE alt_dma_channel_kill ( ALT_DMA_CHANNEL_t  channel)

Kill (abort) execution of any microcode program executing on the specified DMA channel thread resource.

Terminates the channel thread of execution by issuing a DMAKILL instruction using the DMA APB slave interface.

Parameters
channelThe DMA channel thread to abort any executing microcode program on.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_TMOTimeout waiting for the channel to change into KILLING or STOPPED state.

◆ alt_dma_channel_reg_get()

ALT_STATUS_CODE alt_dma_channel_reg_get ( ALT_DMA_CHANNEL_t  channel,
ALT_DMA_PROGRAM_REG_t  reg,
uint32_t *  val 
)

Returns the current register value for the given DMA channel.

Parameters
channelThe DMA channel thread to abort any executing microcode program on.
regRegister to get the value for.
val[out] The current value of the requested register.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe specified channel or register is invalid.

◆ alt_dma_channel_state_get()

ALT_STATUS_CODE alt_dma_channel_state_get ( ALT_DMA_CHANNEL_t  channel,
ALT_DMA_CHANNEL_STATE_t state 
)

Returns the current operational state of the specified DMA channel thread.

Parameters
channelThe DMA channel thread to return the operational state of.
state[out] Pointer to an output parameter to contain the DMA channel thread state.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given channel identifier is invalid.

◆ alt_dma_event_int_select()

ALT_STATUS_CODE alt_dma_event_int_select ( ALT_DMA_EVENT_t  evt_num,
ALT_DMA_EVENT_SELECT_t  opt 
)

Select whether the DMA controller sends the specific event to all channel threads or signals an interrupt using the corressponding irq when a DMASEV instruction is executed for the specified event-interrupt resource number.

Parameters
evt_numThe event-interrupt resource number. Valid values are ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT.
optThe desired behavior selection for evt_num when a DMASEV is executed.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given selection identifier is invalid.

◆ alt_dma_event_int_status_get_raw()

ALT_STATUS_CODE alt_dma_event_int_status_get_raw ( ALT_DMA_EVENT_t  evt_num)

Returns the status of the specified event-interrupt resource.

Returns ALT_E_TRUE if event is active or irq[N] is HIGH and returns ALT_E_FALSE if event is inactive or irq[N] is LOW.

Parameters
evt_numThe event-interrupt resource number. Valid values are ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT.
Return values
ALT_E_TRUEEvent is active or irq[N] is HIGH.
ALT_E_FALSEEvent is inactive or irq[N] is LOW.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given event identifier is invalid.

◆ alt_dma_init()

ALT_STATUS_CODE alt_dma_init ( const ALT_DMA_CFG_t dma_cfg)

Initialize the DMA controller.

Initializes the DMA controller by setting the necessary control values to establish the security state and MUXed peripheral request interface selection configurations before taking the DMA controller out of reset.

After the DMA is initialized, the following conditions hold true:

  • All DMA channel threads are in the Stopped state.
  • All DMA channel threads are available for allocation.
  • DMA Manager thread is waiting for an instruction from either APB interface.
  • The security state configurations of the DMA Manager, interrupt outputs, and peripheral request interfaces are established and immutable until the DMA is reset.
  • The MUXed peripheral request interface selection configurations are established and immutable until the DMA is reset.
Parameters
dma_cfgA pointer to a ALT_DMA_CFG_t structure containing the desired DMA controller security state and peripheral request interface MUX selections.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.

◆ alt_dma_int_clear()

ALT_STATUS_CODE alt_dma_int_clear ( ALT_DMA_EVENT_t  irq_num)

Clear the active (HIGH) status of the specified interrupt resource.

If the specified interrupt is HIGH, then sets irq[N] to LOW if the event-interrupt resource is configured (see: alt_dma_event_int_enable()) to signal an interrupt. Otherwise, the status of irq[N] does not change.

Parameters
irq_numThe interrupt resource number. Valid values are ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given event identifier is invalid.

◆ alt_dma_int_status_get()

ALT_STATUS_CODE alt_dma_int_status_get ( ALT_DMA_EVENT_t  irq_num)

Returns the status of the specified interrupt resource.

Returns ALT_E_TRUE if interrupt is active and therfore irq[N] is HIGH and returns ALT_E_FALSE if interrupt is inactive and therfore irq[N] is LOW.

Parameters
irq_numThe interrupt resource number. Valid values are ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT.
Return values
ALT_E_TRUEEvent is active or irq[N] is HIGH.
ALT_E_FALSEEvent is inactive or irq[N] is LOW.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given event identifier is invalid.

◆ alt_dma_manager_fault_status_get()

ALT_STATUS_CODE alt_dma_manager_fault_status_get ( ALT_DMA_MANAGER_FAULT_t fault)

Return the current fault status of the DMA manager thread.

Parameters
fault[out] Pointer to an output parameter to contain the DMA manager fault status.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.

◆ alt_dma_manager_state_get()

ALT_STATUS_CODE alt_dma_manager_state_get ( ALT_DMA_MANAGER_STATE_t state)

Returns the current operational state of the DMA manager thread.

Parameters
state[out] Pointer to an output parameter to contain the DMA channel thread state.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.

◆ alt_dma_send_event()

ALT_STATUS_CODE alt_dma_send_event ( ALT_DMA_EVENT_t  evt_num)

Signals the occurrence of an event or interrupt, using the specified event number.

Causes the CPU to issue a DMASEV instruction using the DMA APB slave interface.

The Interrupt Enable Register (INTEN) register is used to control if each event-interrupt resource is either an event or an interrupt. The INTEN register sets the event-interrupt resource to function as an:

  • Event - The DMAC generates an event for the specified event-interrupt resource. When the DMAC executes a DMAWFE instruction for the same event-interrupt resource then it clears the event.
  • Interrupt - The DMAC sets the IRQ[N] signal high, where evt_num is the number of the specified event resource. The interrupt must be cleared after being handled.

When the configured to generate an event, this function may be used to restart one or more waiting DMA channels (i.e. having executed a DMAWFE instruction).

See the following sections from the ARM DDI 0424C, CoreLink DMA Controller DMA-330 Technical Reference Manual for implementation details and use cases:

  • 2.5.1, Issuing Instructions to the DMAC using a Slave Interface
  • 2.7, Using Events and Interrupts
Parameters
evt_numA DMA event-interrupt resource. Allowable event values may be ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 but ALT_DMA_EVENT_ABORT is not.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given event number is invalid.

◆ alt_dma_uninit()

ALT_STATUS_CODE alt_dma_uninit ( void  )

Uninitializes the DMA controller.

Uninitializes the DMA controller by killing any running channel threads and putting the DMA controller into reset.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.