PSDK QNX API Guide
UDMA Driver Event API

Files

file  udma_event.h
 UDMA event related parameters and API.
 

Data Structures

struct  Udma_EventPrms
 UDMA event related parameters. More...
 
struct  Udma_EventRxFlowIdFwStatus
 UDMAP receive flow id firewall status. More...
 
struct  Udma_EventHandle
 UDMA event object. More...
 

Macros

#define UDMA_EVENT_INVALID   ((uint32_t) 0xFFFFU)
 Macro used to specify that event ID is invalid. More...
 
#define UDMA_INTR_INVALID   ((uint32_t) 0xFFFF0000U)
 Macro used to specify that interrupt number is invalid. More...
 
#define UDMA_CORE_INTR_ANY   ((uint32_t) 0xFFFF0001U)
 Macro used to specify any available free core interrupt while requesting one. Used in the API Udma_eventRegister. More...
 
#define UDMA_MAX_EVENTS_PER_VINTR   (64U)
 Max events per IA VINTR. More...
 

Variables

uint32_t Udma_EventPrms::eventType
 
uint32_t Udma_EventPrms::eventMode
 
Udma_ChHandle Udma_EventPrms::chHandle
 
Udma_RingHandle Udma_EventPrms::ringHandle
 
Udma_EventHandle Udma_EventPrms::masterEventHandle
 
Udma_EventCallback Udma_EventPrms::eventCb
 
uint32_t Udma_EventPrms::intrPriority
 
void * Udma_EventPrms::appData
 
uint32_t Udma_EventPrms::osalRegisterDisable
 
uint32_t Udma_EventPrms::preferredCoreIntrNum
 
Udma_RingMonHandle Udma_EventPrms::monHandle
 
volatile uint64_t * Udma_EventPrms::intrStatusReg
 
volatile uint64_t * Udma_EventPrms::intrClearReg
 
uint64_t Udma_EventPrms::intrMask
 
uint32_t Udma_EventPrms::vintrNum
 
uint32_t Udma_EventPrms::coreIntrNum
 
uint32_t Udma_EventRxFlowIdFwStatus::isException
 
uint32_t Udma_EventRxFlowIdFwStatus::flowId
 
uint32_t Udma_EventRxFlowIdFwStatus::chNum
 
Udma_DrvHandle Udma_EventHandle::drvHandle
 
Udma_EventPrms Udma_EventHandle::eventPrms
 
uint32_t Udma_EventHandle::globalEvent
 
uint32_t Udma_EventHandle::vintrNum
 
uint32_t Udma_EventHandle::vintrBitNum
 
uint32_t Udma_EventHandle::irIntrNum
 
uint32_t Udma_EventHandle::coreIntrNum
 
Udma_EventHandle Udma_EventHandle::nextEvent
 
Udma_EventHandle Udma_EventHandle::prevEvent
 
HwiP_Handle Udma_EventHandle::hwiHandle
 
uint64_t Udma_EventHandle::vintrBitAllocFlag
 
volatile CSL_intaggr_imapRegs_gevi * Udma_EventHandle::pIaGeviRegs
 
volatile CSL_intaggr_intrRegs_vint * Udma_EventHandle::pIaVintrRegs
 
uint32_t Udma_EventHandle::eventInitDone
 

UDMA Event Mode

UDMA event mode.

typedef void(* Udma_EventCallback) (Udma_EventHandle eventHandle, uint32_t eventType, void *appData)
 UDMA event callback function. More...
 
int32_t Udma_eventRegister (Udma_DrvHandle drvHandle, Udma_EventHandle eventHandle, Udma_EventPrms *eventPrms)
 UDMA event registration. More...
 
int32_t Udma_eventUnRegister (Udma_EventHandle eventHandle)
 UDMA unregister event. More...
 
uint32_t Udma_eventGetId (Udma_EventHandle eventHandle)
 Returns the event ID allocated for this event. More...
 
int32_t Udma_eventDisable (Udma_EventHandle eventHandle)
 Disable the event at interrupt aggregator. More...
 
int32_t Udma_eventEnable (Udma_EventHandle eventHandle)
 Enable the event at interrupt aggregator. More...
 
Udma_EventHandle Udma_eventGetGlobalHandle (Udma_DrvHandle drvHandle)
 Get the global event handle of the driver handle. More...
 
int32_t Udma_eventGetRxFlowIdFwStatus (Udma_EventHandle eventHandle, Udma_EventRxFlowIdFwStatus *status)
 Get the UDMA flow ID firewall status. This API will clear the status bit (RFLOWFWSTAT) by calling TISCI API. More...
 
void UdmaEventPrms_init (Udma_EventPrms *eventPrms)
 Udma_EventPrms structure init function. More...
 
#define UDMA_EVENT_MODE_EXCLUSIVE   ((uint32_t) 0x0001U)
 Event is exclusively allocated at Interrupt Aggregator. More...
 
#define UDMA_EVENT_MODE_SHARED   ((uint32_t) 0x0002U)
 Event is shared at Interrupt Aggregator and could be shared with any other events. More...
 

UDMA Event Type

UDMA events supported.

#define UDMA_EVENT_TYPE_DMA_COMPLETION   ((uint32_t) 0x0001U)
 DMA completion event. Incase of TX/RX channel usage through ring, this represents the completion queue ring event and the application can dequeue the descriptor post this event. More...
 
#define UDMA_EVENT_TYPE_TEARDOWN_PACKET   ((uint32_t) 0x0002U)
 DMA teardown completion event. Incase of TX/RX channel usage through ring, this represents the in-complete descriptor queued to the TD CQ ring during teardown operation. Note: This doesn't represent teardown completion of the channel. More...
 
#define UDMA_EVENT_TYPE_TR   ((uint32_t) 0x0003U)
 TR event to IA. More...
 
#define UDMA_EVENT_TYPE_RING   ((uint32_t) 0x0004U)
 Ring event used for getting callback when entries are there to be popped from ring. This is added to support usecases where the user can independently allocate and configure ring and requires callback when hardware occupancy in the ring goes to non-zero. Note: This is not tied to any channel handle. And hence the chHandle in the event params can be set to NULL (Ignored by driver) More...
 
#define UDMA_EVENT_TYPE_MASTER   ((uint32_t) 0x0005U)
 Event type used to register master event without providing source type like ring, DMA etc... This event type can be used to register the master event which reserves the IA and IR interrupt to a core without reserving global event ID and IMAP programming. Post this, the handle can be passed to masterEventHandle for other event registeration to share the same IA and IR. More...
 
#define UDMA_EVENT_TYPE_ERR_OUT_OF_RANGE_FLOW   ((uint32_t) 0x0006U)
 Event type used to register an event for trapping an out of range flow ID received on a packet. More...
 
#define UDMA_EVENT_TYPE_RING_MON   ((uint32_t) 0x0007U)
 Ring monitor event used for getting callback when ring monitor event criteria is met. More...
 

Detailed Description

This is UDMA driver event related configuration parameters and API

Macro Definition Documentation

◆ UDMA_EVENT_INVALID

#define UDMA_EVENT_INVALID   ((uint32_t) 0xFFFFU)

Macro used to specify that event ID is invalid.

◆ UDMA_INTR_INVALID

#define UDMA_INTR_INVALID   ((uint32_t) 0xFFFF0000U)

Macro used to specify that interrupt number is invalid.

◆ UDMA_CORE_INTR_ANY

#define UDMA_CORE_INTR_ANY   ((uint32_t) 0xFFFF0001U)

Macro used to specify any available free core interrupt while requesting one. Used in the API Udma_eventRegister.

◆ UDMA_MAX_EVENTS_PER_VINTR

#define UDMA_MAX_EVENTS_PER_VINTR   (64U)

Max events per IA VINTR.

◆ UDMA_EVENT_TYPE_DMA_COMPLETION

#define UDMA_EVENT_TYPE_DMA_COMPLETION   ((uint32_t) 0x0001U)

DMA completion event. Incase of TX/RX channel usage through ring, this represents the completion queue ring event and the application can dequeue the descriptor post this event.

◆ UDMA_EVENT_TYPE_TEARDOWN_PACKET

#define UDMA_EVENT_TYPE_TEARDOWN_PACKET   ((uint32_t) 0x0002U)

DMA teardown completion event. Incase of TX/RX channel usage through ring, this represents the in-complete descriptor queued to the TD CQ ring during teardown operation. Note: This doesn't represent teardown completion of the channel.

◆ UDMA_EVENT_TYPE_TR

#define UDMA_EVENT_TYPE_TR   ((uint32_t) 0x0003U)

TR event to IA.

This programs the channels event steering register with IA global event number to generate anytime the required event generation criteria specified in a TR are met. This can be used to get intermediate event or interrupt based on the event type programmed in the TR.

In case of TX and RX channel, this programs the correspinding UDMAP channel OES register. In case of blockcopy, this programs the UDMAP RX channel OES register. In case of external DRU channel, this programs the DRU OES register.

◆ UDMA_EVENT_TYPE_RING

#define UDMA_EVENT_TYPE_RING   ((uint32_t) 0x0004U)

Ring event used for getting callback when entries are there to be popped from ring. This is added to support usecases where the user can independently allocate and configure ring and requires callback when hardware occupancy in the ring goes to non-zero. Note: This is not tied to any channel handle. And hence the chHandle in the event params can be set to NULL (Ignored by driver)

Caution: Ring event will be triggered only when a transition from empty to non-empty ring occupancy occurs. Subsequent increment in ring occupancy will not trigger an event/interrupt. The user should take care of this behavior when dealing with multiple entires in a ring i.e. when a callback occurs, the user should dequeue as much as possible till the dequeue returns UDMA_ETIMEOUT and should not assume multiple callbacks will occur for each ring element (push from HW/SW).

◆ UDMA_EVENT_TYPE_MASTER

#define UDMA_EVENT_TYPE_MASTER   ((uint32_t) 0x0005U)

Event type used to register master event without providing source type like ring, DMA etc... This event type can be used to register the master event which reserves the IA and IR interrupt to a core without reserving global event ID and IMAP programming. Post this, the handle can be passed to masterEventHandle for other event registeration to share the same IA and IR.

◆ UDMA_EVENT_TYPE_ERR_OUT_OF_RANGE_FLOW

#define UDMA_EVENT_TYPE_ERR_OUT_OF_RANGE_FLOW   ((uint32_t) 0x0006U)

Event type used to register an event for trapping an out of range flow ID received on a packet.

Note: This is a global event per UDMA instance (Main and MCU separately) and is common for all flow/channel in an UDMA instance. Hence this should be registered only once per system (by a master core) to handle flow error events.

◆ UDMA_EVENT_TYPE_RING_MON

#define UDMA_EVENT_TYPE_RING_MON   ((uint32_t) 0x0007U)

Ring monitor event used for getting callback when ring monitor event criteria is met.

Note: Not all modes of ring monitor generate events. Only the mode TISCI_MSG_VALUE_RM_MON_MODE_THRESHOLD generate event based on the low and high threshold programmed. In this case, the same event gets generated when both low and high thresholds are crossed.

When user want to get only the low threshold event, the high threshold can be programmed a value which is greater than than the ring element count When user want to get only the high threshold event, the low threshold can be programmed zero.

◆ UDMA_EVENT_MODE_EXCLUSIVE

#define UDMA_EVENT_MODE_EXCLUSIVE   ((uint32_t) 0x0001U)

Event is exclusively allocated at Interrupt Aggregator.

◆ UDMA_EVENT_MODE_SHARED

#define UDMA_EVENT_MODE_SHARED   ((uint32_t) 0x0002U)

Event is shared at Interrupt Aggregator and could be shared with any other events.

Typedef Documentation

◆ Udma_EventCallback

typedef void(* Udma_EventCallback) (Udma_EventHandle eventHandle, uint32_t eventType, void *appData)

UDMA event callback function.

Parameters
eventHandle[IN] UDMA event handle
eventType[IN] Event that occurred
appData[IN] Callback pointer passed during event register

Function Documentation

◆ Udma_eventRegister()

int32_t Udma_eventRegister ( Udma_DrvHandle  drvHandle,
Udma_EventHandle  eventHandle,
Udma_EventPrms eventPrms 
)

UDMA event registration.

Register event based on UDMA channel based and event parameters.

Note: In case of devices like AM64x in which teardown is not supported, for UDMA_EVENT_TYPE_TEARDOWN_PACKET it will return gracefully, after populating eventHandle with DrvHandle and eventPrms. Since the params InstType in drvHandle and evenType in eventPrms are needed to bypass the eventReset of this particular event in Udma_eventUnRegister (because only eventHandle is passed to Udma_eventUnRegister) It wont allocate the resources/configure the event.

Also, In case of devices like AM64x where there is no ring monitor, for UDMA_EVENT_TYPE_RING_MON this function will return error.

Requirement: DOX_REQ_TAG(PDK-2596)

Parameters
drvHandle[IN] UDMA driver handle pointer passed during Udma_init
eventHandle[IN/OUT] UDMA event handle. The caller need to allocate memory for this object and pass this pointer to all further APIs. The caller should not change any parameters as this is owned and maintained by the driver.
eventPrms[IN] UDMA event parameters. This parameter can't be NULL.
Returns
Udma_ErrorCodes

◆ Udma_eventUnRegister()

int32_t Udma_eventUnRegister ( Udma_EventHandle  eventHandle)

UDMA unregister event.

Unregister the event and frees all associated resources.

Note: In case of shared event, the master event should be unregistered last compared to other shared events since the resource is owned by the master event. This function returns error for master event if any other shared resource is still not unregistered.

In case of Ring / DMA Completion events, All the unprocessed descriptors in the ring / processed descriptors returned to the ring, should be dequeued using Udma_ringFlushRaw / Udma_ringDequeueRaw before unregistering these events. This function returns error when the ring occupancy is non-zero. This is to make sure that there is no resource leak, because unregistering these events will reset the ring.

In case of devices like AM64x in which teardown is not supported, for UDMA_EVENT_TYPE_TEARDOWN_PACKET it will return gracefully, without doing anything.

Also, In case of devices like AM64x where there is no ring monitor, for UDMA_EVENT_TYPE_RING_MON this function will return error.

Requirement: DOX_REQ_TAG(PDK-2597)

Parameters
eventHandle[IN] UDMA event handle. This parameter can't be NULL.
Returns
Udma_ErrorCodes

◆ Udma_eventGetId()

uint32_t Udma_eventGetId ( Udma_EventHandle  eventHandle)

Returns the event ID allocated for this event.

Requirement: DOX_REQ_TAG(PDK-2598)

Parameters
eventHandle[IN] UDMA event handle. This parameter can't be NULL.
Returns
the event ID on success or UDMA_EVENT_INVALID on error

◆ Udma_eventDisable()

int32_t Udma_eventDisable ( Udma_EventHandle  eventHandle)

Disable the event at interrupt aggregator.

Requirement: DOX_REQ_TAG(PDK-3583)

Parameters
eventHandle[IN] UDMA event handle. This parameter can't be NULL.
Returns
Udma_ErrorCodes

◆ Udma_eventEnable()

int32_t Udma_eventEnable ( Udma_EventHandle  eventHandle)

Enable the event at interrupt aggregator.

Note: By default the event will be enabled at the time of registration. This is API is used to enable the event again after a call to Udma_eventDisable API

Requirement: DOX_REQ_TAG(PDK-3583)

Parameters
eventHandle[IN] UDMA event handle. This parameter can't be NULL.
Returns
Udma_ErrorCodes

◆ Udma_eventGetGlobalHandle()

Udma_EventHandle Udma_eventGetGlobalHandle ( Udma_DrvHandle  drvHandle)

Get the global event handle of the driver handle.

Requirement: DOX_REQ_TAG(PDK-2621)

Parameters
drvHandle[IN] UDMA driver handle pointer passed during Udma_init
Returns
Returns global event handle else NULL on error

◆ Udma_eventGetRxFlowIdFwStatus()

int32_t Udma_eventGetRxFlowIdFwStatus ( Udma_EventHandle  eventHandle,
Udma_EventRxFlowIdFwStatus status 
)

Get the UDMA flow ID firewall status. This API will clear the status bit (RFLOWFWSTAT) by calling TISCI API.

Requirement: DOX_REQ_TAG(PDK-3706)

Parameters
eventHandle[IN] UDMA event handle. This parameter can't be NULL.
status[OUT] RX flow ID firewall status return structure. This parameter can't be NULL.
Returns
Udma_ErrorCodes

◆ UdmaEventPrms_init()

void UdmaEventPrms_init ( Udma_EventPrms eventPrms)

Udma_EventPrms structure init function.

Parameters
eventPrms[IN] Pointer to Udma_EventPrms structure.

Variable Documentation

◆ eventType

uint32_t Udma_EventPrms::eventType

[IN] Event type to register. Refer Udma_EventType

◆ eventMode

uint32_t Udma_EventPrms::eventMode

[IN] Event mode - exclusive or shared. Refer Udma_EventMode. This parameter should be set to UDMA_EVENT_MODE_SHARED for UDMA_EVENT_TYPE_MASTER event type.

◆ chHandle

Udma_ChHandle Udma_EventPrms::chHandle

[IN] Channel handle when the event type is one of below

◆ ringHandle

Udma_RingHandle Udma_EventPrms::ringHandle

[IN] Ring handle when the event type is one of below

◆ masterEventHandle

Udma_EventHandle Udma_EventPrms::masterEventHandle

[IN] Master event handle used to share the IA register when the event mode is set to UDMA_EVENT_MODE_SHARED. This is typically used to share multiple events from same source like same peripheral to one IA register which eventually routes to a single core interrupt. For the first(or master) event this should be set to NULL. The driver will allocate the required resources (IA/IR) for the first event. For the subsequent shared event registration, the master event handle should be passed as reference and the driver will allocate only the IA status bits. At a maximum UDMA_MAX_EVENTS_PER_VINTR number of events can be shared. Beyond that the driver will return error. This parameter should be set to NULL for UDMA_EVENT_TYPE_MASTER event type.

◆ eventCb

Udma_EventCallback Udma_EventPrms::eventCb

[IN] When callback function is set (non-NULL), the driver will allocate core level interrupt through Interrupt Router and the function will be called when the registered event occurs. When set to NULL, the API will only allocate event and no interrupt routing is performed. Note: In case of shared events (multiple events mapped to same interrupt), the driver will call the callbacks in the order of event registration. This parameter should be set to NULL for UDMA_EVENT_TYPE_MASTER event type.

◆ intrPriority

uint32_t Udma_EventPrms::intrPriority

[IN] Priority of interrupt to register with OSAL. The interpretation depends on the OSAL implementation

◆ appData

void* Udma_EventPrms::appData

[IN] Application/caller context pointer passed back in the event callback function. This could be used by the caller to identify the channel/event for which the callback is called. This can be set to NULL, if not required by caller.

◆ osalRegisterDisable

uint32_t Udma_EventPrms::osalRegisterDisable

[IN] This flag is used to control whether the the interrupt needs to be registered with OSAL. In case AUTOSAR MCAL, interrupt registration is done by the integration layer at the start of the system init. Hence this flag is provided.

Note: The osal interrupt registration is expected only for the master event.

eventCb parameter can be NULL when this flag is set to UTRUE as no interrupt registration is done

UTRUE - Disable osal registration UFALSE - Enable osal registration. This should be used by all TI-RTOS application.

◆ preferredCoreIntrNum

uint32_t Udma_EventPrms::preferredCoreIntrNum

[IN] Preferred core interrupt number which goes to a core.

If set to UDMA_CORE_INTR_ANY, will allocate from free pool. Else will try to allocate the mentioned interrupt itself.

◆ monHandle

Udma_RingMonHandle Udma_EventPrms::monHandle

[IN] Ring monitor handle when the event type is one of below

◆ intrStatusReg

volatile uint64_t* Udma_EventPrms::intrStatusReg

[OUT] Interrupt status register address of the allocated IA VINT register. This is used to check if interrupt occurred

◆ intrClearReg

volatile uint64_t* Udma_EventPrms::intrClearReg

[OUT] Interrupt clear register address of the allocated IA VINT register. This is used to clear if interrupt occurred

◆ intrMask

uint64_t Udma_EventPrms::intrMask

[OUT] Interrupt mask to check and clear

◆ vintrNum [1/2]

uint32_t Udma_EventPrms::vintrNum

[OUT] IA Virtual interrupt number allocated.

◆ coreIntrNum [1/2]

uint32_t Udma_EventPrms::coreIntrNum

[OUT] Core interrupt number allocated. This number can be used to register with the OSAL

Note: Incase of C7x, this represents the GIC SPI events to the CLEC. For routing this event, the driver further uses the Udma_RmInitPrms - 'startC7xCoreIntr' parameter as the start C7x interrupt and assumes that numIrIntr C7x interrupt are used by UDMA driver for one to one mapping. The UDMA driver directly programs the CLEC for this routing

Example: startIrIntr = 700, numIrIntr = 3, startC7xCoreIntr = 32

First Event registration: CLEC input : 700+1024-32 CLEC output : 32 OSAL registration : 32

Second Event registration: CLEC input : 701+1024-32 CLEC output : 33 OSAL registration : 33

◆ isException

uint32_t Udma_EventRxFlowIdFwStatus::isException

This is set whenever the Flow ID firewall detects a Flow ID is out of range for an incoming packet.

◆ flowId

uint32_t Udma_EventRxFlowIdFwStatus::flowId

[OUT] The flow ID that was received on the trapped packet

◆ chNum

uint32_t Udma_EventRxFlowIdFwStatus::chNum

[OUT] The channel index on which the trapped packet was received

◆ drvHandle

Udma_DrvHandle Udma_EventHandle::drvHandle

Pointer to global driver handle.

◆ eventPrms

Udma_EventPrms Udma_EventHandle::eventPrms

Event parameters passed during event registeration.

◆ globalEvent

uint32_t Udma_EventHandle::globalEvent

Allocated IA global event.

◆ vintrNum [2/2]

uint32_t Udma_EventHandle::vintrNum

Allocated IA VINT register.

◆ vintrBitNum

uint32_t Udma_EventHandle::vintrBitNum

Allocated IA VINT bit number - 0 to 63.

◆ irIntrNum

uint32_t Udma_EventHandle::irIntrNum

Allocated interrupt router number. In case of devices like AM64x, where there are no Interrupt Routers, irIntrNum refers to coreIntrNum number itself.

◆ coreIntrNum [2/2]

uint32_t Udma_EventHandle::coreIntrNum

Allocated core interrupt number.

◆ nextEvent

Udma_EventHandle Udma_EventHandle::nextEvent

Pointer to next event - used in shared event for traversing in ISR

◆ prevEvent

Udma_EventHandle Udma_EventHandle::prevEvent

Pointer to previous event - used in shared event for traversing during event un-registration

◆ hwiHandle

HwiP_Handle Udma_EventHandle::hwiHandle

HWI handle.

◆ vintrBitAllocFlag

uint64_t Udma_EventHandle::vintrBitAllocFlag

For master event, this stores the alloc flag for each bit within IA register. This is not used for slave events and is always set to zero

◆ pIaGeviRegs

volatile CSL_intaggr_imapRegs_gevi* Udma_EventHandle::pIaGeviRegs

Pointer to IA global event register overlay

◆ pIaVintrRegs

volatile CSL_intaggr_intrRegs_vint* Udma_EventHandle::pIaVintrRegs

Pointer to IA virtual interrupt register overlay

◆ eventInitDone

uint32_t Udma_EventHandle::eventInitDone

Flag to set the event object is init.