rte_event_..._adapter.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

🎀 NAME 🎀

So this whole vibe is rte_event_crypto_adapter.h — that's the header, and it lives in the Library Functions Manual as rte_event_..._adapter.h(3). Keep that name handy bestie, it's how you'll find it. 💅

✨ SYNOPSIS ✨

#include <stdint.h>
#include 'rte_eventdev.h'

🌸 Data Structures 🌸

  • struct rte_event_crypto_request
  • union rte_event_crypto_metadata
  • struct rte_event_crypto_adapter_conf
  • struct rte_event_crypto_adapter_runtime_params
  • struct rte_event_crypto_adapter_queue_conf
  • struct rte_event_crypto_adapter_vector_limits
  • struct rte_event_crypto_adapter_stats

✨ Macros ✨

#define RTE_EVENT_CRYPTO_ADAPTER_EVENT_VECTOR   0x1

🦋 Typedefs 🦋

typedef int(* rte_event_crypto_adapter_conf_cb) (uint8_t id, uint8_t
    dev_id, struct rte_event_crypto_adapter_conf *conf, void *arg)

💫 Enumerations 💫

enum rte_event_crypto_adapter_mode { RTE_EVENT_CRYPTO_ADAPTER_OP_NEW,
    RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD }

🔥 Functions 🔥

int rte_event_crypto_adapter_create_ext (uint8_t id, uint8_t dev_id,
    rte_event_crypto_adapter_conf_cb conf_cb, enum
    rte_event_crypto_adapter_mode mode, void *conf_arg)
int rte_event_crypto_adapter_create (uint8_t id, uint8_t dev_id, struct
    rte_event_port_conf *port_config, enum rte_event_crypto_adapter_mode
    mode)
int rte_event_crypto_adapter_free (uint8_t id)
int rte_event_crypto_adapter_queue_pair_add (uint8_t id, uint8_t
    cdev_id, int32_t queue_pair_id, const struct
    rte_event_crypto_adapter_queue_conf *conf)
int rte_event_crypto_adapter_queue_pair_del (uint8_t id, uint8_t
    cdev_id, int32_t queue_pair_id)
int rte_event_crypto_adapter_start (uint8_t id)
int rte_event_crypto_adapter_stop (uint8_t id)
int rte_event_crypto_adapter_stats_get (uint8_t id, struct
    rte_event_crypto_adapter_stats *stats)
int rte_event_crypto_adapter_stats_reset (uint8_t id)
int rte_event_crypto_adapter_service_id_get (uint8_t id, uint32_t
    *service_id)
int rte_event_crypto_adapter_event_port_get (uint8_t id, uint8_t
    *event_port_id)
__rte_experimental int rte_event_crypto_adapter_runtime_params_init
    (struct rte_event_crypto_adapter_runtime_params *params)
__rte_experimental int rte_event_crypto_adapter_runtime_params_set
    (uint8_t id, struct rte_event_crypto_adapter_runtime_params *params)
__rte_experimental int rte_event_crypto_adapter_runtime_params_get
    (uint8_t id, struct rte_event_crypto_adapter_runtime_params *params)
int rte_event_crypto_adapter_vector_limits_get (uint8_t dev_id, uint16_t
    cdev_id, struct rte_event_crypto_adapter_vector_limits *limits)
static uint16_t rte_event_crypto_adapter_enqueue (uint8_t dev_id,
    uint8_t port_id, struct rte_event ev[], uint16_t nb_events)

💜 Detailed Description 💜

RTE Event crypto adapter

Okay so picture this: the eventdev library ships a couple of adapters, right? Their whole job is to bridge between different components and give you a brand new event source. The event crypto adapter is one of those little connectors, and it's here to bridge between event devices and crypto devices. 🌉

What it actually does: the crypto adapter lets you enqueue/dequeue crypto operations to and from the event device. That packet flow between the crypto device and the event device can be done with both SW and HW based transfer mechanisms — bestie it's flexible like that. For SW based packet transfer the adapter uses an EAL service core function, and for HW based packet transfer it uses the eventdev PMD functions to configure the connection between the crypto device and the event device.

Now here's the choose-your-own-adventure part: the application can either submit a crypto operation directly to the crypto device, or send it to the crypto adapter via eventdev, and that decision hinges on the RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability. First mode = event new (RTE_EVENT_CRYPTO_ADAPTER_OP_NEW), second mode = event forward (RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD). You pick your mode when you create the adapter, no cap. And the split of responsibility? In the former mode it's an application responsibility to enable ingress packet ordering; in the latter mode it's the adapter's responsibility. Teamwork, but like, the other kind.

✨ Working model of RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode ✨

           +--------------+         +--------------+
           |              |         | Crypto stage |
           | Application  |---[2]-->| + enqueue to |
           |              |         |   cryptodev  |
           +--------------+         +--------------+
               ^   ^                       |
               |   |                      [3]
              [6] [1]                      |
               |   |                       |
           +--------------+                |
           |              |                |
           | Event device |                |
           |              |                |
           +--------------+                |
                  ^                        |
                  |                        |
                 [5]                       |
                  |                        v
           +--------------+         +--------------+
           |              |         |              |
           |Crypto adapter|<--[4]---|  Cryptodev   |
           |              |         |              |
           +--------------+         +--------------+
  1. Application dequeues events from the previous stage.
  2. Application prepares the crypto operations.
  3. Crypto operations are submitted to cryptodev by application.
  4. Crypto adapter dequeues crypto completions from cryptodev.
  5. Crypto adapter enqueues events to the eventdev.
  6. Application dequeues from eventdev and prepare for further processing.

In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, the application submits crypto operations directly to the crypto device. Then the adapter dequeues crypto completions from the crypto device and enqueues events to the event device. Here's the tea though — this mode does not ensure ingress ordering, if the application directly enqueues to cryptodev without going through crypto/atomic stage, i.e. removing item [1] and [2]. Events dequeued from the adapter will be treated as new events. And in this mode the application needs to specify event information (response information), which is needed to enqueue an event after the crypto operation is completed. Don't forget it! 😭

💫 Working model of RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode 💫

           +--------------+         +--------------+
   --[1]-->|              |---[2]-->|  Application |
           | Event device |         |      in      |
   <--[8]--|              |<--[3]---| Ordered stage|
           +--------------+         +--------------+
               ^      |
               |     [4]
              [7]     |
               |      v
          +----------------+       +--------------+
          |                |--[5]->|              |
          | Crypto adapter |       |   Cryptodev  |
          |                |<-[6]--|              |
          +----------------+       +--------------+
  1. Events from the previous stage.
  2. Application in ordered stage dequeues events from eventdev.
  3. Application enqueues crypto operations as events to eventdev.
  4. Crypto adapter dequeues event from eventdev.
  5. Crypto adapter submits crypto operations to cryptodev (Atomic stage).
  6. Crypto adapter dequeues crypto completions from cryptodev
  7. Crypto adapter enqueues events to the eventdev
  8. Events to the next stage

In the RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode, if the HW supports the RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability, the application can directly submit the crypto operations to the cryptodev. But if it doesn't? Then the application retrieves the crypto adapter's event port using the rte_event_crypto_adapter_event_port_get() API. After that it links its event queue to this port and starts enqueuing crypto operations as events to the eventdev. The adapter then dequeues the events and submits the crypto operations to the cryptodev, and once the crypto completions land, the adapter enqueues events to the event device. Use this mode when ingress packet ordering is needed, periodt. Events dequeued from the adapter will be treated as forwarded events. And in this mode, the application needs to specify the cryptodev ID and queue pair ID (request information) needed to enqueue a crypto operation, in addition to the event information (response information) needed to enqueue an event after the crypto operation has completed. Two things, not one. Bestie write it down. 📝

The event crypto adapter provides common APIs to configure the packet flow from the crypto device to event devices for both SW and HW based transfers. The crypto event adapter's functions are:

  • rte_event_crypto_adapter_create_ext()
  • rte_event_crypto_adapter_create()
  • rte_event_crypto_adapter_free()
  • rte_event_crypto_adapter_queue_pair_add()
  • rte_event_crypto_adapter_queue_pair_del()
  • rte_event_crypto_adapter_start()
  • rte_event_crypto_adapter_stop()
  • rte_event_crypto_adapter_stats_get()
  • rte_event_crypto_adapter_stats_reset()
  • rte_event_crypto_adapter_runtime_params_get()
  • rte_event_crypto_adapter_runtime_params_init()
  • rte_event_crypto_adapter_runtime_params_set()

The application creates an instance using rte_event_crypto_adapter_create() or rte_event_crypto_adapter_create_ext(). Pick your fighter. 🥊

Cryptodev queue pair addition/deletion is done using the rte_event_crypto_adapter_queue_pair_xxx() APIs. And heads up: if the HW supports the RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND capability, then event information must be passed to the add API. Non-negotiable, it's giving requirement energy.

The SW adapter or HW PMD uses rte_crypto_op::sess_type to decide whether request/response(private) data is located in the crypto/security session or at an offset in the rte_crypto_op. 👀

For session-based operations, the set and get API provides a mechanism for an application to store and retrieve the data information stored along with the crypto session. The RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA capability indicates whether HW or SW supports this feature.

For session-less mode, the adapter gets the private data information placed along with the struct rte_crypto_op. The rte_crypto_op::private_data_offset provides an offset to locate the request/response information in the rte_crypto_op. And btw, this offset is counted from the start of the rte_crypto_op including initialization vector (IV). 🧚

Definition in file rte_event_crypto_adapter.h.

🌈 Macro Definition Documentation 🌈

#define RTE_EVENT_CRYPTO_ADAPTER_EVENT_VECTOR 0x1

This flag indicates that crypto operations processed on the crypto adapter need to be vectorized. 🦋

See also

rte_event_crypto_adapter_queue_conf::flags

Definition at line 284 of file rte_event_crypto_adapter.h.

🎀 Typedef Documentation 🎀

typedef int(* rte_event_crypto_adapter_conf_cb) (uint8_t id, uint8_t dev_id, struct rte_event_crypto_adapter_conf *conf, void *arg)

Okay bestie, so this one is a function type — the callback you hand over when you want to configure an adapter. It's used to fill in the members of the struct rte_event_crypto_adapter_conf, and here's the tea: this callback gets invoked when a SW service is created for packet transfer from a cryptodev queue pair over to the event device. 🦋

And when does that SW service actually get born? Inside the rte_event_crypto_adapter_queue_pair_add() function — but only if you actually need SW-based packet transfers from a cryptodev queue pair to the event device. No need, no callback. Simple as that. ✨

Parameters

  • id — the adapter identifier.
  • dev_id — the event device identifier.
  • conf — the structure that this callback is supposed to populate. That's literally its whole job, no cap.
  • arg — the argument handed to the callback. This is the exact same thing as the conf_arg you passed into rte_event_crypto_adapter_create_ext().

Defined at line 377 of file rte_event_crypto_adapter.h. 💅

🔥 Enumeration Type Documentation 🔥

enum rte_event_crypto_adapter_mode

Crypto event adapter mode 👑 — aka, pick your fighter. It's giving "choose your own adventure" but for the adapter.

Enumerator

  • RTE_EVENT_CRYPTO_ADAPTER_OP_NEW — start the crypto adapter in event new mode. ✨

See also: RTE_EVENT_OP_NEW. The application submits crypto operations to the cryptodev. The adapter only dequeues the crypto completions from the cryptodev and enqueues events to the eventdev. It minds its own business fr fr. 🫶

  • RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD — start the crypto adapter in event forward mode. 🔥

See also: RTE_EVENT_OP_FORWARD. The application submits crypto requests as events — either to the crypto adapter or to the crypto device, and which one depends on the RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability. Crypto completions get enqueued back to the eventdev by the crypto adapter. That's the whole loop, and it ate. 💖

Defined at line 181 of file rte_event_crypto_adapter.h.

🌸 Function Documentation 🌸

rte_event_crypto_adapter_create_ext 💫

Bestie, this one spins up a shiny new event crypto adapter with the identifier you picked. Signature goes a lil something like this:

int rte_event_crypto_adapter_create_ext (uint8_t id, uint8_t dev_id,
    rte_event_crypto_adapter_conf_cb conf_cb, enum
    rte_event_crypto_adapter_mode mode, void * conf_arg)

Parameters

  • id — adapter identifier, its lil name tag basically 🏷️
  • dev_id — event device identifier.
  • conf_cb — callback function that fills in members of a struct rte_event_crypto_adapter_conf struct passed into it.
  • mode — flag to indicate the mode of the adapter.
See also: rte_event_crypto_adapter_mode 👀
  • conf_arg — argument that is passed to the conf_cb function.

Returns

  • 0: success, we ate 💅
  • <0: error code on failure 😭

rte_event_crypto_adapter_create ✨

Create a new event crypto adapter with the specified identifier, fr fr. This function uses an internal configuration function that creates an event port. This default function reconfigures the event device with an additional event port and set up the event port using the port_config parameter passed into this function. In case the application needs more control in configuration of the service, it should use the rte_event_crypto_adapter_create_ext() version. iykyk.

When this API is used for creating adapter instance, rte_event_dev_config::nb_event_ports is automatically incremented, and the event device is reconfigured with additional event port during service initialization. This event device reconfigure logic also increments the rte_event_dev_config::nb_single_link_event_port_queues parameter if the adapter event port config is of type RTE_EVENT_PORT_CFG_SINGLE_LINK.

Application no longer needs to account for rte_event_dev_config::nb_event_ports and rte_event_dev_config::nb_single_link_event_port_queues parameters required for crypto adapter in event device configuration when the adapter is created with this API. No cap, it handles it for u 🫶

int rte_event_crypto_adapter_create (uint8_t id, uint8_t dev_id, struct
    rte_event_port_conf * port_config, enum rte_event_crypto_adapter_mode
    mode)

Parameters

  • id — adapter identifier.
  • dev_id — event device identifier.
  • port_config — argument of type rte_event_port_conf that is passed to the conf_cb function.
  • mode — flag to indicate the mode of the adapter.
See also: rte_event_crypto_adapter_mode 🌈

Returns

  • 0: success ✨
  • <0: error code on failure 💀

rte_event_crypto_adapter_free 🦋

Free an event crypto adapter. Let it gooo 🎀

int rte_event_crypto_adapter_free (uint8_t id)

Parameters

  • id — adapter identifier.

Returns

  • 0: success.
  • <0: error code on failure. If the adapter still has queue pairs added to it, the function returns -EBUSY. So like, empty it out first bestie, it's giving clingy 👑

rte_event_crypto_adapter_queue_pair_add 🔥

Add a queue pair to an event crypto adapter.

int rte_event_crypto_adapter_queue_pair_add (uint8_t id, uint8_t cdev_id,
    int32_t queue_pair_id, const struct rte_event_crypto_adapter_queue_conf
    * conf)

Parameters

  • id — adapter identifier.
  • cdev_id — cryptodev identifier.
  • queue_pair_id — cryptodev queue pair identifier. If queue_pair_id is set -1, adapter adds all the pre configured queue pairs to the instance. iconic behaviour honestly.
  • conf — additional configuration structure of type rte_event_crypto_adapter_queue_conf.

Returns

  • 0: success, queue pair added correctly 🥳
  • <0: error code on failure 😭

rte_event_crypto_adapter_queue_pair_del 🙈

Delete a queue pair from an event crypto adapter.

int rte_event_crypto_adapter_queue_pair_del (uint8_t id, uint8_t cdev_id,
    int32_t queue_pair_id)

Parameters

  • id — adapter identifier.
  • cdev_id — cryptodev identifier.
  • queue_pair_id — cryptodev queue pair identifier.

Returns

  • 0: success, queue pair deleted successfully 💅
  • <0: error code on failure 💀

rte_event_crypto_adapter_start ⭐

Start event crypto adapter. Go girl, go 🏁

int rte_event_crypto_adapter_start (uint8_t id)

Parameters

  • id — adapter identifier.

Returns

  • 0: success, adapter started successfully ✨
  • <0: error code on failure 😭

Note

The eventdev and cryptodev to which the event_crypto_adapter is connected needs to be started before calling rte_event_crypto_adapter_start(). Like, do the prerequisites first bestie, don't skip steps 🚨

rte_event_crypto_adapter_stop 🛑

Stop event crypto adapter.

int rte_event_crypto_adapter_stop (uint8_t id)

Parameters

  • id — adapter identifier.

Returns

  • 0: success, adapter stopped successfully.
  • <0: error code on failure.

rte_event_crypto_adapter_stats_get 📊

Retrieve statistics for an adapter.

int rte_event_crypto_adapter_stats_get (uint8_t id, struct
    rte_event_crypto_adapter_stats * stats)

Parameters

  • id — adapter identifier.
  • stats — a pointer to structure used to retrieve statistics for an adapter.

Returns

  • 0: success, retrieved successfully.
  • <0: error code on failure.

rte_event_crypto_adapter_stats_reset 🧼

Reset statistics for an adapter. Fresh start energy 🌸

int rte_event_crypto_adapter_stats_reset (uint8_t id)

Parameters

  • id — adapter identifier.

Returns

  • 0: success, statistics reset successfully.
  • <0: error code on failure.

rte_event_crypto_adapter_service_id_get 🆔

Retrieve the service ID of an adapter. If the adapter doesn't use a rte_service function, this function returns -ESRCH.

int rte_event_crypto_adapter_service_id_get (uint8_t id, uint32_t *
    service_id)

Parameters

  • id — adapter identifier.
  • service_id — a pointer to a uint32_t, to be filled in with the service id.

Returns

  • 0: success.
  • <0: error code on failure. If the adapter doesn't use a rte_service function, this function returns -ESRCH. Not found bestie, it's giving ghosted 👻

rte_event_crypto_adapter_event_port_get 🎯

Retrieve the event port of an adapter.

int rte_event_crypto_adapter_event_port_get (uint8_t id, uint8_t *
    event_port_id)

Parameters

  • id — adapter identifier.
  • event_port_id — application links its event queue to this adapter port which is used in RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.

Returns

  • 0: success.
  • <0: error code on failure.

rte_event_crypto_adapter_runtime_params_init 💖

__rte_experimental — yes it's experimental, handle with care bestie 🧪

Initialize the adapter runtime configuration parameters.

__rte_experimental int rte_event_crypto_adapter_runtime_params_init (struct
    rte_event_crypto_adapter_runtime_params * params)

Parameters

  • params — a pointer to structure of type struct rte_event_crypto_adapter_runtime_params.

Returns

  • 0: success.
  • <0: error code on failure.

rte_event_crypto_adapter_runtime_params_set 🔧

__rte_experimental — experimental era, we're in it 🧪

Set the adapter runtime configuration parameters.

__rte_experimental int rte_event_crypto_adapter_runtime_params_set (uint8_t
    id, struct rte_event_crypto_adapter_runtime_params * params)

Parameters

  • id — adapter identifier.
  • params — a pointer to structure of type struct rte_event_crypto_adapter_runtime_params with configuration parameter values. The reserved fields of this structure must be initialized to zero and the valid fields need to be set appropriately. This struct can be initialized using rte_event_crypto_adapter_runtime_params_init() API to default values or application may reset this struct and update required fields. Do not skip the zeroing, that's not a vibe 🙅‍♀️

Returns

  • 0: success.
  • <0: error code on failure.

rte_event_crypto_adapter_runtime_params_get 📥

__rte_experimental — still experimental, still cute 🧪

Get the adapter runtime configuration parameters.

__rte_experimental int rte_event_crypto_adapter_runtime_params_get (uint8_t
    id, struct rte_event_crypto_adapter_runtime_params * params)

Parameters

  • id — adapter identifier.
  • params — a pointer to structure of type struct rte_event_crypto_adapter_runtime_params containing valid adapter parameters when return value is 0.

Returns

  • 0: success.
  • <0: error code on failure.

rte_event_crypto_adapter_vector_limits_get 🧮

Retrieve vector limits for a given event dev and crypto dev pair. The glow-up of limits, honestly.

int rte_event_crypto_adapter_vector_limits_get (uint8_t dev_id, uint16_t
    cdev_id, struct rte_event_crypto_adapter_vector_limits * limits)
See also: rte_event_crypto_adapter_vector_limits 👀

Parameters

  • dev_id — event device identifier.
  • cdev_id — crypto device identifier.
  • limits — a pointer to rte_event_crypto_adapter_vector_limits structure that has to be filled.

Returns

  • 0: success.
  • <0: error code on failure.

rte_event_crypto_adapter_enqueue 🚀

[inline], [static], and honestly main character energy. Enqueue a burst of crypto operations as event objects supplied in rte_event structure on an event crypto adapter designated by its event dev_id through the event port specified by port_id. This function is supported if the eventdev PMD has the RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability flag set.

The nb_events parameter is the number of event objects to enqueue which are supplied in the ev array of rte_event structure.

The rte_event_crypto_adapter_enqueue() function returns the number of event objects it actually enqueued. A return value equal to nb_events means that all event objects have been enqueued. Full send, everything landed 💅

uint16_t rte_event_crypto_adapter_enqueue (uint8_t dev_id, uint8_t port_id,
    struct rte_event ev[], uint16_t nb_events) [inline],  [static]

Parameters

  • dev_id — the identifier of the device.
  • port_id — the identifier of the event port.
  • ev — points to an array of nb_events objects of type rte_event structure which contain the event object enqueue operations to be processed.
  • nb_events — the number of event objects to enqueue, typically number of rte_event_port_attr_get(...RTE_EVENT_PORT_ATTR_ENQ_DEPTH...) available for this port.

Returns

The number of event objects actually enqueued on the event device. The return value can be less than the value of the nb_events parameter when the event devices queue is full or if invalid parameters are specified in a rte_event. If the return value is less than nb_events, the remaining events at the end of ev[] are not consumed and the caller has to take care of them, and rte_errno is set accordingly. Possible errno values include:

  • EINVAL — the port ID is invalid, device ID is invalid, an event's queue ID is invalid, or an event's sched type doesn't match the capabilities of the destination queue.
  • ENOSPC — the event port was backpressured and unable to enqueue one or more events. This error code is only applicable to closed systems. It's full full, no room bestie 😤
Definition at line 757 of file rte_event_crypto_adapter.h. Go look, it's right there 🫶

👑 Author 👑

Generated automatically by Doxygen for DPDK from the source code. We love a robot doing the most 🤖💖

And that's a wrap on this whole page, bestie! This footer was brought to you by DPDK Version 25.11.3, and yes, this is the rte_event_..._adapter.h(3) manual page in all its glory. Read it, love it, ship it. Periodt. 💅🌈✨

📦 where this page comes from