Introduction

This is UDMA driver event related configuration parameters and 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_EventObject
	Opaque UDMA event object. More...

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

void	UdmaEventPrms_init (Udma_EventPrms *eventPrms)
	Udma_EventPrms structure init function. More...

Typedefs
typedef void(*	Udma_EventCallback) (Udma_EventHandle eventHandle, uint32_t eventType, void *appData)
	UDMA event callback function. 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...

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_TEARDOWN_COMPLETION ((uint32_t) 0x0006U)
	DMA channel teardown completion event. Incase of TX/RX channel usage through ring, this represents the teardown completion of the channel. More...

UDMA Event Mode
UDMA event mode.
#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...

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_TEARDOWN_COMPLETION

#define UDMA_EVENT_TYPE_TEARDOWN_COMPLETION ((uint32_t) 0x0006U)

DMA channel teardown completion event. Incase of TX/RX channel usage through ring, this represents the teardown completion of the channel.

◆ 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

◆ UdmaEventPrms_init()

void UdmaEventPrms_init ( Udma_EventPrms * eventPrms )

Udma_EventPrms structure init function.

Parameters

eventPrms [IN] Pointer to Udma_EventPrms structure.

Introduction

Files

Data Structures

Functions

Typedefs

Macros

UDMA Event Type

UDMA Event Mode

Macro Definition Documentation

◆ UDMA_EVENT_INVALID

◆ UDMA_INTR_INVALID

◆ UDMA_CORE_INTR_ANY

◆ UDMA_MAX_EVENTS_PER_VINTR

◆ UDMA_EVENT_TYPE_DMA_COMPLETION

◆ UDMA_EVENT_TYPE_TEARDOWN_PACKET

◆ UDMA_EVENT_TYPE_TR

◆ UDMA_EVENT_TYPE_RING

◆ UDMA_EVENT_TYPE_MASTER

◆ UDMA_EVENT_TYPE_TEARDOWN_COMPLETION

◆ UDMA_EVENT_MODE_EXCLUSIVE

◆ UDMA_EVENT_MODE_SHARED

Typedef Documentation

◆ Udma_EventCallback

Function Documentation

◆ Udma_eventRegister()

◆ Udma_eventUnRegister()

◆ Udma_eventGetId()

◆ Udma_eventDisable()

◆ Udma_eventEnable()

◆ Udma_eventGetGlobalHandle()

◆ UdmaEventPrms_init()