lib/librte_eventdev/rte_event_crypto_adapter.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2018 Intel Corporation.
   3  * All rights reserved.
   4  */
   5
   6 #ifndef _RTE_EVENT_CRYPTO_ADAPTER_
   7 #define _RTE_EVENT_CRYPTO_ADAPTER_
   8
   9 /**
  10  * @file
  11  *
  12  * RTE Event crypto adapter
  13  *
  14  * Eventdev library provides couple of adapters to bridge between various
  15  * components for providing new event source. The event crypto adapter is
  16  * one of those adapters which is intended to bridge between event devices
  17  * and crypto devices.
  18  *
  19  * The crypto adapter adds support to enqueue/dequeue crypto operations to/
  20  * from event device. The packet flow between crypto device and the event
  21  * device can be accomplished using both SW and HW based transfer mechanisms.
  22  * The adapter uses an EAL service core function for SW based packet transfer
  23  * and uses the eventdev PMD functions to configure HW based packet transfer
  24  * between the crypto device and the event device.
  25  *
  26  * The application can choose to submit a crypto operation directly to
  27  * crypto device or send it to the crypto adapter via eventdev based on
  28  * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
  29  * The first mode is known as the event new(RTE_EVENT_CRYPTO_ADAPTER_OP_NEW)
  30  * mode and the second as the event forward(RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD)
  31  * mode. The choice of mode can be specified while creating the adapter.
  32  * In the former mode, it is an application responsibility to enable ingress
  33  * packet ordering. In the latter mode, it is the adapter responsibility to
  34  * enable the ingress packet ordering.
  35  *
  36  *
  37  * Working model of RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode:
  38  *
  39  *                +--------------+         +--------------+
  40  *                |              |         | Crypto stage |
  41  *                | Application  |---[2]-->| + enqueue to |
  42  *                |              |         |   cryptodev  |
  43  *                +--------------+         +--------------+
  44  *                    ^   ^                       |
  45  *                    |   |                      [3]
  46  *                   [6] [1]                      |
  47  *                    |   |                       |
  48  *                +--------------+                |
  49  *                |              |                |
  50  *                | Event device |                |
  51  *                |              |                |
  52  *                +--------------+                |
  53  *                       ^                        |
  54  *                       |                        |
  55  *                      [5]                       |
  56  *                       |                        v
  57  *                +--------------+         +--------------+
  58  *                |              |         |              |
  59  *                |Crypto adapter|<--[4]---|  Cryptodev   |
  60  *                |              |         |              |
  61  *                +--------------+         +--------------+
  62  *
  63  *
  64  *         [1] Application dequeues events from the previous stage.
  65  *         [2] Application prepares the crypto operations.
  66  *         [3] Crypto operations are submitted to cryptodev by application.
  67  *         [4] Crypto adapter dequeues crypto completions from cryptodev.
  68  *         [5] Crypto adapter enqueues events to the eventdev.
  69  *         [6] Application dequeues from eventdev and prepare for further
  70  *             processing.
  71  *
  72  * In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, application submits crypto
  73  * operations directly to crypto device. The adapter then dequeues crypto
  74  * completions from crypto device and enqueue events to the event device.
  75  * This mode does not ensure ingress ordering, if the application directly
  76  * enqueues to cryptodev without going through crypto/atomic stage i.e.
  77  * removing item [1] and [2].
  78  * Events dequeued from the adapter will be treated as new events.
  79  * In this mode, application needs to specify event information (response
  80  * information) which is needed to enqueue an event after the crypto operation
  81  * is completed.
  82  *
  83  *
  84  * Working model of RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode:
  85  *
  86  *                +--------------+         +--------------+
  87  *        --[1]-->|              |---[2]-->|  Application |
  88  *                | Event device |         |      in      |
  89  *        <--[8]--|              |<--[3]---| Ordered stage|
  90  *                +--------------+         +--------------+
  91  *                    ^      |
  92  *                    |     [4]
  93  *                   [7]     |
  94  *                    |      v
  95  *               +----------------+       +--------------+
  96  *               |                |--[5]->|              |
  97  *               | Crypto adapter |       |   Cryptodev  |
  98  *               |                |<-[6]--|              |
  99  *               +----------------+       +--------------+
 100  *
 101  *
 102  *         [1] Events from the previous stage.
 103  *         [2] Application in ordered stage dequeues events from eventdev.
 104  *         [3] Application enqueues crypto operations as events to eventdev.
 105  *         [4] Crypto adapter dequeues event from eventdev.
 106  *         [5] Crypto adapter submits crypto operations to cryptodev
 107  *             (Atomic stage).
 108  *         [6] Crypto adapter dequeues crypto completions from cryptodev
 109  *         [7] Crypto adapter enqueues events to the eventdev
 110  *         [8] Events to the next stage
 111  *
 112  * In the RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode, if HW supports
 113  * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability the application
 114  * can directly submit the crypto operations to the cryptodev.
 115  * If not, application retrieves crypto adapter's event port using
 116  * rte_event_crypto_adapter_event_port_get() API. Then, links its event
 117  * queue to this port and starts enqueuing crypto operations as events
 118  * to the eventdev. The adapter then dequeues the events and submits the
 119  * crypto operations to the cryptodev. After the crypto completions, the
 120  * adapter enqueues events to the event device.
 121  * Application can use this mode, when ingress packet ordering is needed.
 122  * Events dequeued from the adapter will be treated as forwarded events.
 123  * In this mode, the application needs to specify the cryptodev ID
 124  * and queue pair ID (request information) needed to enqueue a crypto
 125  * operation in addition to the event information (response information)
 126  * needed to enqueue an event after the crypto operation has completed.
 127  *
 128  *
 129  * The event crypto adapter provides common APIs to configure the packet flow
 130  * from the crypto device to event devices for both SW and HW based transfers.
 131  * The crypto event adapter's functions are:
 132  *  - rte_event_crypto_adapter_create_ext()
 133  *  - rte_event_crypto_adapter_create()
 134  *  - rte_event_crypto_adapter_free()
 135  *  - rte_event_crypto_adapter_queue_pair_add()
 136  *  - rte_event_crypto_adapter_queue_pair_del()
 137  *  - rte_event_crypto_adapter_start()
 138  *  - rte_event_crypto_adapter_stop()
 139  *  - rte_event_crypto_adapter_stats_get()
 140  *  - rte_event_crypto_adapter_stats_reset()
 141
 142  * The application creates an instance using rte_event_crypto_adapter_create()
 143  * or rte_event_crypto_adapter_create_ext().
 144  *
 145  * Cryptodev queue pair addition/deletion is done using the
 146  * rte_event_crypto_adapter_queue_pair_xxx() APIs. If HW supports
 147  * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND capability, event
 148  * information must be passed to the add API.
 149  *
 150  * The SW adapter or HW PMD uses rte_crypto_op::sess_type to decide whether
 151  * request/response(private) data is located in the crypto/security session
 152  * or at an offset in the rte_crypto_op.
 153  *
 154  * For session-based operations, the set and get API provides a mechanism for
 155  * an application to store and retrieve the data information stored
 156  * along with the crypto session.
 157  * The RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA capability indicates
 158  * whether HW or SW supports this feature.
 159  *
 160  * For session-less mode, the adapter gets the private data information placed
 161  * along with the ``struct rte_crypto_op``.
 162  * The rte_crypto_op::private_data_offset provides an offset to locate the
 163  * request/response information in the rte_crypto_op. This offset is counted
 164  * from the start of the rte_crypto_op including initialization vector (IV).
 165  */
 166
 167 #ifdef __cplusplus
 168 extern "C" {
 169 #endif
 170
 171 #include <stdint.h>
 172
 173 #include "rte_eventdev.h"
 174
 175 /**
 176  * Crypto event adapter mode
 177  */
 178 enum rte_event_crypto_adapter_mode {
 179         RTE_EVENT_CRYPTO_ADAPTER_OP_NEW,
 180         /**< Start the crypto adapter in event new mode.
 181          * @see RTE_EVENT_OP_NEW.
 182          * Application submits crypto operations to the cryptodev.
 183          * Adapter only dequeues the crypto completions from cryptodev
 184          * and enqueue events to the eventdev.
 185          */
 186         RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD,
 187         /**< Start the crypto adapter in event forward mode.
 188          * @see RTE_EVENT_OP_FORWARD.
 189          * Application submits crypto requests as events to the crypto
 190          * adapter or crypto device based on
 191          * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
 192          * Crypto completions are enqueued back to the eventdev by
 193          * crypto adapter.
 194          */
 195 };
 196
 197 /**
 198  * Crypto event request structure will be filled by application to
 199  * provide event request information to the adapter.
 200  */
 201 struct rte_event_crypto_request {
 202         uint8_t resv[8];
 203         /**< Overlaps with first 8 bytes of struct rte_event
 204          * that encode the response event information. Application
 205          * is expected to fill in struct rte_event response_info.
 206          */
 207         uint16_t cdev_id;
 208         /**< cryptodev ID to be used */
 209         uint16_t queue_pair_id;
 210         /**< cryptodev queue pair ID to be used */
 211         uint32_t resv1;
 212         /**< Reserved bits */
 213 };
 214
 215 /**
 216  * Crypto event metadata structure will be filled by application
 217  * to provide crypto request and event response information.
 218  *
 219  * If crypto events are enqueued using a HW mechanism, the cryptodev
 220  * PMD will use the event response information to set up the event
 221  * that is enqueued back to eventdev after completion of the crypto
 222  * operation. If the transfer is done by SW, event response information
 223  * will be used by the adapter.
 224  */
 225 union rte_event_crypto_metadata {
 226         struct rte_event_crypto_request request_info;
 227         /**< Request information to be filled in by application
 228          * for RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
 229          */
 230         struct rte_event response_info;
 231         /**< Response information to be filled in by application
 232          * for RTE_EVENT_CRYPTO_ADAPTER_OP_NEW and
 233          * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
 234          */
 235 };
 236
 237 /**
 238  * Adapter configuration structure that the adapter configuration callback
 239  * function is expected to fill out
 240  * @see rte_event_crypto_adapter_conf_cb
 241  */
 242 struct rte_event_crypto_adapter_conf {
 243         uint8_t event_port_id;
 244         /**< Event port identifier, the adapter enqueues events to this
 245          * port and dequeues crypto request events in
 246          * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
 247          */
 248         uint32_t max_nb;
 249         /**< The adapter can return early if it has processed at least
 250          * max_nb crypto ops. This isn't treated as a requirement; batching
 251          * may cause the adapter to process more than max_nb crypto ops.
 252          */
 253 };
 254
 255 /**
 256  * Function type used for adapter configuration callback. The callback is
 257  * used to fill in members of the struct rte_event_crypto_adapter_conf, this
 258  * callback is invoked when creating a SW service for packet transfer from
 259  * cryptodev queue pair to the event device. The SW service is created within
 260  * the rte_event_crypto_adapter_queue_pair_add() function if SW based packet
 261  * transfers from cryptodev queue pair to the event device are required.
 262  *
 263  * @param id
 264  *  Adapter identifier.
 265  *
 266  * @param dev_id
 267  *  Event device identifier.
 268  *
 269  * @param conf
 270  *  Structure that needs to be populated by this callback.
 271  *
 272  * @param arg
 273  *  Argument to the callback. This is the same as the conf_arg passed to the
 274  *  rte_event_crypto_adapter_create_ext().
 275  */
 276 typedef int (*rte_event_crypto_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
 277                         struct rte_event_crypto_adapter_conf *conf,
 278                         void *arg);
 279
 280 /**
 281  * A structure used to retrieve statistics for an event crypto adapter
 282  * instance.
 283  */
 284
 285 struct rte_event_crypto_adapter_stats {
 286         uint64_t event_poll_count;
 287         /**< Event port poll count */
 288         uint64_t event_deq_count;
 289         /**< Event dequeue count */
 290         uint64_t crypto_enq_count;
 291         /**< Cryptodev enqueue count */
 292         uint64_t crypto_enq_fail;
 293         /**< Cryptodev enqueue failed count */
 294         uint64_t crypto_deq_count;
 295         /**< Cryptodev dequeue count */
 296         uint64_t event_enq_count;
 297         /**< Event enqueue count */
 298         uint64_t event_enq_retry_count;
 299         /**< Event enqueue retry count */
 300         uint64_t event_enq_fail_count;
 301         /**< Event enqueue fail count */
 302 };
 303
 304 /**
 305  * Create a new event crypto adapter with the specified identifier.
 306  *
 307  * @param id
 308  *  Adapter identifier.
 309  *
 310  * @param dev_id
 311  *  Event device identifier.
 312  *
 313  * @param conf_cb
 314  *  Callback function that fills in members of a
 315  *  struct rte_event_crypto_adapter_conf struct passed into
 316  *  it.
 317  *
 318  * @param mode
 319  *  Flag to indicate the mode of the adapter.
 320  *  @see rte_event_crypto_adapter_mode
 321  *
 322  * @param conf_arg
 323  *  Argument that is passed to the conf_cb function.
 324  *
 325  * @return
 326  *   - 0: Success
 327  *   - <0: Error code on failure
 328  */
 329 int
 330 rte_event_crypto_adapter_create_ext(uint8_t id, uint8_t dev_id,
 331                                     rte_event_crypto_adapter_conf_cb conf_cb,
 332                                     enum rte_event_crypto_adapter_mode mode,
 333                                     void *conf_arg);
 334
 335 /**
 336  * Create a new event crypto adapter with the specified identifier.
 337  * This function uses an internal configuration function that creates an event
 338  * port. This default function reconfigures the event device with an
 339  * additional event port and set up the event port using the port_config
 340  * parameter passed into this function. In case the application needs more
 341  * control in configuration of the service, it should use the
 342  * rte_event_crypto_adapter_create_ext() version.
 343  *
 344  * @param id
 345  *  Adapter identifier.
 346  *
 347  * @param dev_id
 348  *  Event device identifier.
 349  *
 350  * @param port_config
 351  *  Argument of type *rte_event_port_conf* that is passed to the conf_cb
 352  *  function.
 353  *
 354  * @param mode
 355  *  Flag to indicate the mode of the adapter.
 356  *  @see rte_event_crypto_adapter_mode
 357  *
 358  * @return
 359  *   - 0: Success
 360  *   - <0: Error code on failure
 361  */
 362 int
 363 rte_event_crypto_adapter_create(uint8_t id, uint8_t dev_id,
 364                                 struct rte_event_port_conf *port_config,
 365                                 enum rte_event_crypto_adapter_mode mode);
 366
 367 /**
 368  * Free an event crypto adapter
 369  *
 370  * @param id
 371  *  Adapter identifier.
 372  *
 373  * @return
 374  *   - 0: Success
 375  *   - <0: Error code on failure, If the adapter still has queue pairs
 376  *      added to it, the function returns -EBUSY.
 377  */
 378 int
 379 rte_event_crypto_adapter_free(uint8_t id);
 380
 381 /**
 382  * Add a queue pair to an event crypto adapter.
 383  *
 384  * @param id
 385  *  Adapter identifier.
 386  *
 387  * @param cdev_id
 388  *  Cryptodev identifier.
 389  *
 390  * @param queue_pair_id
 391  *  Cryptodev queue pair identifier. If queue_pair_id is set -1,
 392  *  adapter adds all the pre configured queue pairs to the instance.
 393  *
 394  * @param event
 395  *  if HW supports cryptodev queue pair to event queue binding, application is
 396  *  expected to fill in event information, else it will be NULL.
 397  *  @see RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND
 398  *
 399  * @return
 400  *  - 0: Success, queue pair added correctly.
 401  *  - <0: Error code on failure.
 402  */
 403 int
 404 rte_event_crypto_adapter_queue_pair_add(uint8_t id,
 405                         uint8_t cdev_id,
 406                         int32_t queue_pair_id,
 407                         const struct rte_event *event);
 408
 409 /**
 410  * Delete a queue pair from an event crypto adapter.
 411  *
 412  * @param id
 413  *  Adapter identifier.
 414  *
 415  * @param cdev_id
 416  *  Cryptodev identifier.
 417  *
 418  * @param queue_pair_id
 419  *  Cryptodev queue pair identifier.
 420  *
 421  * @return
 422  *  - 0: Success, queue pair deleted successfully.
 423  *  - <0: Error code on failure.
 424  */
 425 int
 426 rte_event_crypto_adapter_queue_pair_del(uint8_t id, uint8_t cdev_id,
 427                                         int32_t queue_pair_id);
 428
 429 /**
 430  * Start event crypto adapter
 431  *
 432  * @param id
 433  *  Adapter identifier.
 434  *
 435  *
 436  * @return
 437  *  - 0: Success, adapter started successfully.
 438  *  - <0: Error code on failure.
 439  *
 440  * @note
 441  *  The eventdev to which the event_crypto_adapter is connected needs to
 442  *  be started before calling rte_event_crypto_adapter_start().
 443  */
 444 int
 445 rte_event_crypto_adapter_start(uint8_t id);
 446
 447 /**
 448  * Stop event crypto adapter
 449  *
 450  * @param id
 451  *  Adapter identifier.
 452  *
 453  * @return
 454  *  - 0: Success, adapter stopped successfully.
 455  *  - <0: Error code on failure.
 456  */
 457 int
 458 rte_event_crypto_adapter_stop(uint8_t id);
 459
 460 /**
 461  * Retrieve statistics for an adapter
 462  *
 463  * @param id
 464  *  Adapter identifier.
 465  *
 466  * @param [out] stats
 467  *  A pointer to structure used to retrieve statistics for an adapter.
 468  *
 469  * @return
 470  *  - 0: Success, retrieved successfully.
 471  *  - <0: Error code on failure.
 472  */
 473 int
 474 rte_event_crypto_adapter_stats_get(uint8_t id,
 475                                 struct rte_event_crypto_adapter_stats *stats);
 476
 477 /**
 478  * Reset statistics for an adapter.
 479  *
 480  * @param id
 481  *  Adapter identifier.
 482  *
 483  * @return
 484  *  - 0: Success, statistics reset successfully.
 485  *  - <0: Error code on failure.
 486  */
 487 int
 488 rte_event_crypto_adapter_stats_reset(uint8_t id);
 489
 490 /**
 491  * Retrieve the service ID of an adapter. If the adapter doesn't use
 492  * a rte_service function, this function returns -ESRCH.
 493  *
 494  * @param id
 495  *  Adapter identifier.
 496  *
 497  * @param [out] service_id
 498  *  A pointer to a uint32_t, to be filled in with the service id.
 499  *
 500  * @return
 501  *  - 0: Success
 502  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
 503  * function, this function returns -ESRCH.
 504  */
 505 int
 506 rte_event_crypto_adapter_service_id_get(uint8_t id, uint32_t *service_id);
 507
 508 /**
 509  * Retrieve the event port of an adapter.
 510  *
 511  * @param id
 512  *  Adapter identifier.
 513  *
 514  * @param [out] event_port_id
 515  *  Application links its event queue to this adapter port which is used
 516  *  in RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
 517  *
 518  * @return
 519  *  - 0: Success
 520  *  - <0: Error code on failure.
 521  */
 522 int
 523 rte_event_crypto_adapter_event_port_get(uint8_t id, uint8_t *event_port_id);
 524
 525 #ifdef __cplusplus
 526 }
 527 #endif
 528 #endif  /* _RTE_EVENT_CRYPTO_ADAPTER_ */