API Reference Manual  1.45.0
Macros | Typedefs | Enumerations | Functions
ODP EVENT

API Description

Generic event metadata and operations.

Macros

#define ODP_EVENT_INVALID   ((odp_event_t)0)
 Invalid event.
 

Typedefs

typedef _odp_abi_event_t * odp_event_t
 ODP event.
 

Enumerations

enum  odp_event_type_t {
  ODP_EVENT_BUFFER = 1 , ODP_EVENT_PACKET = 2 , ODP_EVENT_TIMEOUT = 3 , ODP_EVENT_IPSEC_STATUS = 5 ,
  ODP_EVENT_PACKET_VECTOR = 6 , ODP_EVENT_PACKET_TX_COMPL = 7 , ODP_EVENT_DMA_COMPL = 8 , ODP_EVENT_ML_COMPL = 9
}
 Event type. More...
 
enum  odp_event_subtype_t {
  ODP_EVENT_NO_SUBTYPE = 0 , ODP_EVENT_PACKET_BASIC = 1 , ODP_EVENT_PACKET_CRYPTO = 2 , ODP_EVENT_PACKET_IPSEC = 3 ,
  ODP_EVENT_PACKET_COMP = 4 , ODP_EVENT_ML_COMPL_LOAD = 5 , ODP_EVENT_ML_COMPL_RUN = 6
}
 Event subtype. More...
 

Functions

odp_event_type_t odp_event_type (odp_event_t event)
 Event type of an event. More...
 
odp_event_subtype_t odp_event_subtype (odp_event_t event)
 Event subtype of an event. More...
 
odp_event_type_t odp_event_types (odp_event_t event, odp_event_subtype_t *subtype)
 Event type and subtype of an event. More...
 
void odp_event_types_multi (const odp_event_t event[], odp_event_type_t type[], odp_event_subtype_t subtype[], int num)
 Event types and subtypes of multiple events. More...
 
int odp_event_type_multi (const odp_event_t event[], int num, odp_event_type_t *type)
 Event type of multiple events. More...
 
odp_pool_t odp_event_pool (odp_event_t event)
 Event pool. More...
 
void * odp_event_user_area (odp_event_t event)
 Event user area. More...
 
void * odp_event_user_area_and_flag (odp_event_t event, int *flag)
 Event user area and flag. More...
 
void odp_event_user_flag_set (odp_event_t event, int val)
 Set event user flag. More...
 
int odp_event_filter_packet (const odp_event_t event[], odp_packet_t packet[], odp_event_t remain[], int num)
 Filter and convert packet events. More...
 
uint64_t odp_event_to_u64 (odp_event_t hdl)
 Get printable value for an odp_event_t. More...
 
int odp_event_is_valid (odp_event_t event)
 Check that event is valid. More...
 
void odp_event_free (odp_event_t event)
 Free event. More...
 
void odp_event_free_multi (const odp_event_t event[], int num)
 Free multiple events. More...
 
void odp_event_free_sp (const odp_event_t event[], int num)
 Free multiple events to the same pool. More...
 
uint32_t odp_event_flow_id (odp_event_t event)
 Event flow id value. More...
 
void odp_event_flow_id_set (odp_event_t event, uint32_t flow_id)
 Set event flow id value. More...
 

Enumeration Type Documentation

◆ odp_event_type_t

enum odp_event_type_t

Event type.

Event type specifies purpose and general format of an event. It can be checked with odp_event_type() or odp_event_types(). Each event type has functions (e.g. odp_buffer_from_event()) to convert between the generic event handle (odp_event_t) and the type specific handle (e.g. odp_buffer_t). Results are undefined, if conversion function of a wrong event type is used. Application cannot change event type by chaining conversion functions.

List of event types:

  • ODP_EVENT_BUFFER
    • Buffer event (odp_buffer_t) for simple data storage and message passing
  • ODP_EVENT_PACKET
    • Packet event (odp_packet_t) containing packet data and plenty of packet processing related metadata
  • ODP_EVENT_TIMEOUT
    • Timeout event (odp_timeout_t) from a timer
  • ODP_EVENT_IPSEC_STATUS
  • ODP_EVENT_PACKET_VECTOR
    • Vector of packet events (odp_packet_t) as odp_packet_vector_t
  • ODP_EVENT_PACKET_TX_COMPL
    • Packet Tx completion event (odp_packet_tx_compl_t) generated as a result of a Packet Tx completion.
  • ODP_EVENT_DMA_COMPL
    • DMA completion event (odp_dma_compl_t) indicates that a DMA transfer has finished
  • ODP_EVENT_ML_COMPL
    • ML completion event (odp_ml_compl_t) indicates that an ML operation has finished

Definition at line 26 of file api/abi-default/event_types.h.

◆ odp_event_subtype_t

enum odp_event_subtype_t

Event subtype.

Event subtype expands event type specification by providing more detailed purpose and format of an event. It can be checked with odp_event_subtype() or odp_event_types(). Each event subtype may define specific functions (e.g. odp_ipsec_packet_from_event()) to convert between the generic event handle (odp_event_t) and event type specific handle (e.g. odp_packet_t). When subtype is known, these subtype specific functions should be preferred over the event type general function (e.g. odp_packet_from_event()). Results are undefined, if conversion function of a wrong event subtype is used. Application cannot change event subtype by chaining conversion functions.

List of event subtypes:

  • ODP_EVENT_PACKET_BASIC
    • Packet event (odp_packet_t) with basic packet metadata
  • ODP_EVENT_PACKET_COMP
    • Packet event (odp_packet_t) generated as a result of a compression/ decompression operation. It contains compression specific metadata in addition to the basic packet metadata.
  • ODP_EVENT_PACKET_CRYPTO
    • Packet event (odp_packet_t) generated as a result of a Crypto operation. It contains crypto specific metadata in addition to the basic packet metadata.
  • ODP_EVENT_PACKET_IPSEC
    • Packet event (odp_packet_t) generated as a result of an IPsec operation. It contains IPSEC specific metadata in addition to the basic packet metadata.
  • ODP_EVENT_NO_SUBTYPE
    • An event type does not have any subtypes defined
  • ODP_EVENT_ML_COMPL_LOAD
    • ML completion event (odp_ml_compl_t) that contains results from a completed model load or unload operation.
  • ODP_EVENT_ML_COMPL_RUN
    • ML completion event (odp_ml_compl_t) that contains results from a completed model run operation.

Definition at line 37 of file api/abi-default/event_types.h.

Function Documentation

◆ odp_event_type()

odp_event_type_t odp_event_type ( odp_event_t  event)

Event type of an event.

Event type specifies purpose and general format of an event.

Parameters
eventEvent handle
Returns
Event type
Examples
ipsec_api/odp_ipsec.c, odp_bench_buffer.c, odp_bench_timer.c, odp_cpu_bench.c, odp_dmafwd.c, odp_ipfragreass.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_packet_dump.c, odp_ping.c, odp_pktio_perf.c, odp_sched_pktio.c, and odp_timer_simple.c.

◆ odp_event_subtype()

odp_event_subtype_t odp_event_subtype ( odp_event_t  event)

Event subtype of an event.

Event subtype expands event type specification by providing more detailed purpose and format of an event.

Parameters
eventEvent handle
Returns
Event subtype
Examples
odp_bench_buffer.c, and odp_bench_packet.c.

◆ odp_event_types()

odp_event_type_t odp_event_types ( odp_event_t  event,
odp_event_subtype_t *  subtype 
)

Event type and subtype of an event.

Returns event type and outputs event subtype.

Parameters
eventEvent handle
[out]subtypePointer to event subtype for output
Returns
Event type
Examples
ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_bench_buffer.c, and odp_ipsecfwd.c.

◆ odp_event_types_multi()

void odp_event_types_multi ( const odp_event_t  event[],
odp_event_type_t  type[],
odp_event_subtype_t  subtype[],
int  num 
)

Event types and subtypes of multiple events.

Outputs the event types and subtypes (optional) of all given events into the output arrays. Application can pass NULL as 'subtype' parameter if subtype values are not required. The types are written in the same order as input events.

Parameters
eventArray of event handles
[out]typeEvent type array for output
[out]subtypeEvent subtype array for output, or NULL
numNumber of events, event types, and optionally subtypes
Examples
odp_bench_buffer.c.

◆ odp_event_type_multi()

int odp_event_type_multi ( const odp_event_t  event[],
int  num,
odp_event_type_t *  type 
)

Event type of multiple events.

Returns the number of first events in the array which have the same event type. Outputs the event type of those events.

Parameters
eventArray of event handles
numNumber of events (> 0)
[out]typeEvent type pointer for output
Returns
Number of first events (1 ... num) with the same event type (includes event[0])
Examples
odp_bench_buffer.c.

◆ odp_event_pool()

odp_pool_t odp_event_pool ( odp_event_t  event)

Event pool.

Returns handle to the pool where the event was allocated from. If the underlying event type does not have an API for returning pool handle (e.g. ODP_EVENT_IPSEC_STATUS), ODP_POOL_INVALID is returned.

Parameters
eventEvent handle
Returns
Pool handle or ODP_POOL_INVALID depending on event type
Examples
odp_bench_buffer.c, and odp_bench_packet.c.

◆ odp_event_user_area()

void* odp_event_user_area ( odp_event_t  event)

Event user area.

Returns pointer to the user area associated with the event. This maps to the user area of underlying event type (e.g. odp_packet_user_area() for packets). If the event does not have user area, NULL is returned.

Parameters
eventEvent handle
Returns
Pointer to the user area of the event
Return values
NULLThe event does not have user area
Examples
odp_bench_buffer.c, odp_bench_packet.c, and odp_sched_perf.c.

◆ odp_event_user_area_and_flag()

void* odp_event_user_area_and_flag ( odp_event_t  event,
int *  flag 
)

Event user area and flag.

Returns pointer to the user area and outputs value of user flag associated with the event. The user area maps to the user area of underlying event type (e.g. odp_packet_user_area() for packets). If the event does not have user area, NULL is returned.

The user flag maps to the user flag value of underlying event type (e.g. odp_packet_user_flag() for packets). If the event does not have user flag, a negative value is outputted.

Parameters
eventEvent handle
[out]flagUser flag value pointer for output. >0 if user flag is set, 0 if flags is not set, or <0 if event does not have user flag.
Returns
Pointer to the user area of the event
Return values
NULLThe event does not have user area
Examples
odp_bench_buffer.c, and odp_bench_packet.c.

◆ odp_event_user_flag_set()

void odp_event_user_flag_set ( odp_event_t  event,
int  val 
)

Set event user flag.

Set (or clear) the user flag.

The user flag maps to the user flag value of underlying event type (e.g. odp_packet_user_flag() for packets). If the event does not have user flag, nothing is done.

Parameters
eventEvent handle
valNew value for the flag. Zero clears the flag, other values set the flag.
Examples
odp_bench_packet.c.

◆ odp_event_filter_packet()

int odp_event_filter_packet ( const odp_event_t  event[],
odp_packet_t  packet[],
odp_event_t  remain[],
int  num 
)

Filter and convert packet events.

Checks event type of all input events, converts all packet events and outputs packet handles. Returns the number packet handles outputted. Outputs the remaining, non-packet event handles to 'remain' array. Handles are outputted to both arrays in the same order those are stored in 'event' array. Both output arrays must fit 'num' elements.

Parameters
eventArray of event handles
[out]packetPacket handle array for output
[out]remainEvent handle array for output of remaining, non-packet events
numNumber of events (> 0)
Returns
Number of packets outputted (0 ... num)

◆ odp_event_to_u64()

uint64_t odp_event_to_u64 ( odp_event_t  hdl)

Get printable value for an odp_event_t.

Parameters
hdlodp_event_t handle to be printed
Returns
uint64_t value that can be used to print/display this handle
Note
This routine is intended to be used for diagnostic purposes to enable applications to generate a printable value that represents an odp_event_t handle.
Examples
odp_bench_timer.c.

◆ odp_event_is_valid()

int odp_event_is_valid ( odp_event_t  event)

Check that event is valid.

This function can be used for debugging purposes to check if an event handle represents a valid event. The level of error checks depends on the implementation. The call should not crash if the event handle is corrupted.

Parameters
eventEvent handle
Return values
1Event handle represents a valid event.
0Event handle does not represent a valid event.
Examples
odp_bench_buffer.c.

◆ odp_event_free()

void odp_event_free ( odp_event_t  event)

Free event.

Frees the event based on its type. Results are undefined if event type is unknown.

Parameters
eventEvent handle
Examples
ipsec_api/odp_ipsec.c, odp_bench_buffer.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_cpu_bench.c, odp_dma_perf.c, odp_dmafwd.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_packet_dump.c, odp_packet_gen.c, odp_ping.c, odp_pktio_ordered.c, odp_pktio_perf.c, odp_queue_perf.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, and odp_timer_simple.c.

◆ odp_event_free_multi()

void odp_event_free_multi ( const odp_event_t  event[],
int  num 
)

Free multiple events.

Otherwise like odp_event_free(), but frees multiple events to their originating pools.

Parameters
eventArray of event handles
numNumber of events to free
Examples
odp_bench_buffer.c, odp_bench_packet.c, odp_l2fwd.c, odp_sched_perf.c, odp_sched_pktio.c, and odp_simple_pipeline.c.

◆ odp_event_free_sp()

void odp_event_free_sp ( const odp_event_t  event[],
int  num 
)

Free multiple events to the same pool.

Otherwise like odp_event_free_multi(), but all events must be from the same originating pool.

Parameters
eventArray of event handles
numNumber of events to free
Examples
odp_bench_buffer.c, and odp_bench_packet.c.

◆ odp_event_flow_id()

uint32_t odp_event_flow_id ( odp_event_t  event)

Event flow id value.

Returns the flow id value set in the event. Usage of flow id enables scheduler to maintain multiple synchronization contexts per single queue. For example, when multiple flows are assigned to an atomic queue, events of a single flow (events from the same queue with the same flow id value) are guaranteed to be processed by only single thread at a time. For packets received through packet input initial event flow id will be same as flow hash generated for packets. The hash algorithm and therefore the resulting flow id value is implementation specific. Use pktio API configuration options to select the fields used for initial flow id calculation. For all other events initial flow id is zero An application can change event flow id using odp_event_flow_id_set().

Parameters
eventEvent handle
Returns
Flow id of the event
Examples
odp_bench_buffer.c.

◆ odp_event_flow_id_set()

void odp_event_flow_id_set ( odp_event_t  event,
uint32_t  flow_id 
)

Set event flow id value.

Store the event flow id for the event and sets the flow id flag. When scheduler is configured as flow aware, scheduled queue synchronization will be based on this id within each queue. When scheduler is configured as flow unaware, event flow id is ignored by the implementation. The value of flow id must be less than the number of flows configured in the scheduler.

Parameters
eventEvent handle
flow_idFlow event id to be set.
Examples
odp_bench_buffer.c.