diff options
Diffstat (limited to 'include/odp/api/spec/event.h')
| -rw-r--r-- | include/odp/api/spec/event.h | 243 |
1 files changed, 222 insertions, 21 deletions
diff --git a/include/odp/api/spec/event.h b/include/odp/api/spec/event.h index fdfa52d1c..e5684c634 100644 --- a/include/odp/api/spec/event.h +++ b/include/odp/api/spec/event.h @@ -1,55 +1,182 @@ -/* Copyright (c) 2015, Linaro Limited - * All rights reserved. - * - * SPDX-License-Identifier: BSD-3-Clause +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2015-2018 Linaro Limited + * Copyright (c) 2022-2024 Nokia */ - /** * @file * * ODP event */ -#ifndef ODP_API_EVENT_H_ -#define ODP_API_EVENT_H_ +#ifndef ODP_API_SPEC_EVENT_H_ +#define ODP_API_SPEC_EVENT_H_ #include <odp/visibility_begin.h> #ifdef __cplusplus extern "C" { #endif -/** @defgroup odp_event ODP EVENT - * Operations on an event. +#include <odp/api/event_types.h> +#include <odp/api/packet_types.h> +#include <odp/api/pool_types.h> + +/** @addtogroup odp_event + * Generic event metadata and operations. * @{ */ +/** + * Event type of an event + * + * Event type specifies purpose and general format of an event. + * + * @param event Event handle + * + * @return Event type + */ +odp_event_type_t odp_event_type(odp_event_t event); /** - * @typedef odp_event_t - * ODP event + * Event subtype of an event + * + * Event subtype expands event type specification by providing more detailed + * purpose and format of an event. + * + * @param event Event handle + * + * @return Event subtype */ +odp_event_subtype_t odp_event_subtype(odp_event_t event); /** - * @def ODP_EVENT_INVALID - * Invalid event + * Event type and subtype of an event + * + * Returns event type and outputs event subtype. + * + * @param event Event handle + * @param[out] subtype Pointer to event subtype for output + * + * @return Event type */ +odp_event_type_t odp_event_types(odp_event_t event, + odp_event_subtype_t *subtype); /** - * @typedef odp_event_type_t - * ODP event types: - * ODP_EVENT_BUFFER, ODP_EVENT_PACKET, ODP_EVENT_TIMEOUT, - * ODP_EVENT_CRYPTO_COMPL + * 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. + * + * @param event Array of event handles + * @param[out] type Event type array for output + * @param[out] subtype Event subtype array for output, or NULL + * @param num Number of events, event types, and optionally subtypes */ +void odp_event_types_multi(const odp_event_t event[], odp_event_type_t type[], + odp_event_subtype_t subtype[], int num); /** - * Get event type + * Event type of multiple events * - * @param event Event handle + * Returns the number of first events in the array which have the same event + * type. Outputs the event type of those events. * - * @return Event type + * @param event Array of event handles + * @param num Number of events (> 0) + * @param[out] type Event type pointer for output + * + * @return Number of first events (1 ... num) with the same event type + * (includes event[0]) */ -odp_event_type_t odp_event_type(odp_event_t event); +int odp_event_type_multi(const odp_event_t event[], int num, + odp_event_type_t *type); + +/** + * 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. + * + * @param event Event handle + * + * @return Pool handle or ODP_POOL_INVALID depending on event type + */ +odp_pool_t odp_event_pool(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. + * + * @param event Event handle + * + * @return Pointer to the user area of the event + * @retval NULL The event does not have user area + */ +void *odp_event_user_area(odp_event_t event); + +/** + * 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. + * + * @param event Event handle + * @param[out] flag User 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. + * + * @return Pointer to the user area of the event + * @retval NULL The event does not have user area + */ +void *odp_event_user_area_and_flag(odp_event_t event, int *flag); + +/** + * 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. + * + * @param event Event handle + * @param val New value for the flag. Zero clears the flag, other values set the flag. + */ +void odp_event_user_flag_set(odp_event_t event, int val); + +/** + * 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. + * + * @param event Array of event handles + * @param[out] packet Packet handle array for output + * @param[out] remain Event handle array for output of remaining, non-packet + * events + * @param num Number of events (> 0) + * + * @return Number of packets outputted (0 ... num) + */ +int odp_event_filter_packet(const odp_event_t event[], + odp_packet_t packet[], + odp_event_t remain[], int num); /** * Get printable value for an odp_event_t @@ -65,6 +192,20 @@ odp_event_type_t odp_event_type(odp_event_t event); uint64_t odp_event_to_u64(odp_event_t hdl); /** + * 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. + * + * @param event Event handle + * + * @retval 1 Event handle represents a valid event. + * @retval 0 Event handle does not represent a valid event. + */ +int odp_event_is_valid(odp_event_t event); + +/** * Free event * * Frees the event based on its type. Results are undefined if event @@ -76,6 +217,66 @@ uint64_t odp_event_to_u64(odp_event_t hdl); void odp_event_free(odp_event_t event); /** + * Free multiple events + * + * Otherwise like odp_event_free(), but frees multiple events to their + * originating pools. + * + * @param event Array of event handles + * @param num Number of events to free + */ +void odp_event_free_multi(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. + * + * @param event Array of event handles + * @param num Number of events to free + */ +void odp_event_free_sp(const odp_event_t event[], int num); + +/** + * 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(). + * + * @param event Event handle + * + * @return Flow id of the event + * + */ +uint32_t odp_event_flow_id(odp_event_t event); + +/** + * 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. + * + * @param event Event handle + * @param flow_id Flow event id to be set. + */ +void odp_event_flow_id_set(odp_event_t event, uint32_t flow_id); + +/** * @} */ |