Event subtype gives more detailed information about the event.
Two subtypes (basic and IPSEC packet) are introduced initially.
Later on, other packet producing APIs (crypto, comp, etc) may
also produce packet events with additional subtypes.
Signed-off-by: Petri Savolainen <petri.savolai...@linaro.org>
---
include/odp/api/spec/event.h | 80 ++++++++++++++++++++--
include/odp/arch/default/api/abi/event.h | 9 ++-
.../include/odp/api/plat/event_types.h | 8 ++-
3 files changed, 89 insertions(+), 8 deletions(-)
diff --git a/include/odp/api/spec/event.h b/include/odp/api/spec/event.h
index f22efce5..2ad3ce84 100644
--- a/include/odp/api/spec/event.h
+++ b/include/odp/api/spec/event.h
@@ -37,21 +37,91 @@ extern "C" {
/**
* @typedef odp_event_type_t
- * ODP event types:
- * ODP_EVENT_BUFFER, ODP_EVENT_PACKET, ODP_EVENT_TIMEOUT,
- * ODP_EVENT_CRYPTO_COMPL, ODP_EVENT_IPSEC_RESULT, ODP_EVENT_IPSEC_STATUS
+ * 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_CRYPTO_COMPL
+ * - Crypto completion event (odp_crypto_compl_t)
+ * - ODP_EVENT_IPSEC_STATUS
+ * - IPSEC status update event (odp_ipsec_status_t)
*/
/**
- * Get event type
+ * @typedef odp_event_subtype_t
+ * Event subtype
*
- * @param event Event handle
+ * 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_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
+ */
+
+/**
+ * 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);
/**
+ * 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);
+
+/**
+ * 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);
+
+/**
* Get printable value for an odp_event_t
*
* @param hdl odp_event_t handle to be printed
diff --git a/include/odp/arch/default/api/abi/event.h
b/include/odp/arch/default/api/abi/event.h
index 87220d63..ab3c0f75 100644
--- a/include/odp/arch/default/api/abi/event.h
+++ b/include/odp/arch/default/api/abi/event.h
@@ -29,10 +29,15 @@ typedef enum odp_event_type_t {
ODP_EVENT_PACKET = 2,
ODP_EVENT_TIMEOUT = 3,
ODP_EVENT_CRYPTO_COMPL = 4,
- ODP_EVENT_IPSEC_RESULT = 5,
- ODP_EVENT_IPSEC_STATUS = 6
+ ODP_EVENT_IPSEC_STATUS = 5
} odp_event_type_t;
+typedef enum odp_event_subtype_t {
+ ODP_EVENT_NO_SUBTYPE = 0,
+ ODP_EVENT_PACKET_BASIC = 1,
+ ODP_EVENT_PACKET_IPSEC = 2
+} odp_event_subtype_t;
+
/**
* @}
*/
diff --git a/platform/linux-generic/include/odp/api/plat/event_types.h
b/platform/linux-generic/include/odp/api/plat/event_types.h
index 0f517834..5b3a07e3 100644
--- a/platform/linux-generic/include/odp/api/plat/event_types.h
+++ b/platform/linux-generic/include/odp/api/plat/event_types.h
@@ -39,9 +39,15 @@ typedef enum odp_event_type_t {
ODP_EVENT_PACKET = 2,
ODP_EVENT_TIMEOUT = 3,
ODP_EVENT_CRYPTO_COMPL = 4,
- ODP_EVENT_IPSEC_RESULT = 5
+ ODP_EVENT_IPSEC_STATUS = 5
} odp_event_type_t;
+typedef enum odp_event_subtype_t {
+ ODP_EVENT_NO_SUBTYPE = 0,
+ ODP_EVENT_PACKET_BASIC = 1,
+ ODP_EVENT_PACKET_IPSEC = 2
+} odp_event_subtype_t;
+
/**
* @}
*/
--
2.13.0
