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... | |
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... | |
This is UDMA driver event related configuration parameters and API
#define UDMA_EVENT_INVALID ((uint32_t) 0xFFFFU) |
Macro used to specify that event ID is invalid.
#define UDMA_INTR_INVALID ((uint32_t) 0xFFFF0000U) |
Macro used to specify that interrupt number is invalid.
#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.
#define UDMA_MAX_EVENTS_PER_VINTR (64U) |
Max events per IA VINTR.
#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.
#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.
#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.
#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).
#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.
#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.
#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.
#define UDMA_EVENT_MODE_EXCLUSIVE ((uint32_t) 0x0001U) |
Event is exclusively allocated at Interrupt Aggregator.
#define UDMA_EVENT_MODE_SHARED ((uint32_t) 0x0002U) |
Event is shared at Interrupt Aggregator and could be shared with any other events.
typedef void(* Udma_EventCallback) (Udma_EventHandle eventHandle, uint32_t eventType, void *appData) |
UDMA event callback function.
eventHandle | [IN] UDMA event handle |
eventType | [IN] Event that occurred |
appData | [IN] Callback pointer passed during event register |
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)
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. |
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)
eventHandle | [IN] UDMA event handle. This parameter can't be NULL. |
uint32_t Udma_eventGetId | ( | Udma_EventHandle | eventHandle | ) |
Returns the event ID allocated for this event.
Requirement: DOX_REQ_TAG(PDK-2598)
eventHandle | [IN] UDMA event handle. This parameter can't be NULL. |
int32_t Udma_eventDisable | ( | Udma_EventHandle | eventHandle | ) |
Disable the event at interrupt aggregator.
Requirement: DOX_REQ_TAG(PDK-3583)
eventHandle | [IN] UDMA event handle. This parameter can't be NULL. |
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)
eventHandle | [IN] UDMA event handle. This parameter can't be NULL. |
Udma_EventHandle Udma_eventGetGlobalHandle | ( | Udma_DrvHandle | drvHandle | ) |
Get the global event handle of the driver handle.
Requirement: DOX_REQ_TAG(PDK-2621)
drvHandle | [IN] UDMA driver handle pointer passed during Udma_init |
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)
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. |
void UdmaEventPrms_init | ( | Udma_EventPrms * | eventPrms | ) |
Udma_EventPrms structure init function.
eventPrms | [IN] Pointer to Udma_EventPrms structure. |
uint32_t Udma_EventPrms::eventType |
[IN] Event type to register. Refer Udma_EventType
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.
Udma_ChHandle Udma_EventPrms::chHandle |
[IN] Channel handle when the event type is one of below
Udma_RingHandle Udma_EventPrms::ringHandle |
[IN] Ring handle when the event type is one of below
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.
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.
uint32_t Udma_EventPrms::intrPriority |
[IN] Priority of interrupt to register with OSAL. The interpretation depends on the OSAL implementation
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.
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.
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.
Udma_RingMonHandle Udma_EventPrms::monHandle |
[IN] Ring monitor handle when the event type is one of below
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
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
uint64_t Udma_EventPrms::intrMask |
[OUT] Interrupt mask to check and clear
uint32_t Udma_EventPrms::vintrNum |
[OUT] IA Virtual interrupt number allocated.
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
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.
uint32_t Udma_EventRxFlowIdFwStatus::flowId |
[OUT] The flow ID that was received on the trapped packet
uint32_t Udma_EventRxFlowIdFwStatus::chNum |
[OUT] The channel index on which the trapped packet was received
Udma_DrvHandle Udma_EventHandle::drvHandle |
Pointer to global driver handle.
Udma_EventPrms Udma_EventHandle::eventPrms |
Event parameters passed during event registeration.
uint32_t Udma_EventHandle::globalEvent |
Allocated IA global event.
uint32_t Udma_EventHandle::vintrNum |
Allocated IA VINT register.
uint32_t Udma_EventHandle::vintrBitNum |
Allocated IA VINT bit number - 0 to 63.
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.
uint32_t Udma_EventHandle::coreIntrNum |
Allocated core interrupt number.
Udma_EventHandle Udma_EventHandle::nextEvent |
Pointer to next event - used in shared event for traversing in ISR
Udma_EventHandle Udma_EventHandle::prevEvent |
Pointer to previous event - used in shared event for traversing during event un-registration
HwiP_Handle Udma_EventHandle::hwiHandle |
HWI handle.
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
volatile CSL_intaggr_imapRegs_gevi* Udma_EventHandle::pIaGeviRegs |
Pointer to IA global event register overlay
volatile CSL_intaggr_intrRegs_vint* Udma_EventHandle::pIaVintrRegs |
Pointer to IA virtual interrupt register overlay
uint32_t Udma_EventHandle::eventInitDone |
Flag to set the event object is init.