lib/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 #include "eventdev_pmd.h"
 175
 176 /**
 177  * Crypto event adapter mode
 178  */
 179 enum rte_event_crypto_adapter_mode {
 180         RTE_EVENT_CRYPTO_ADAPTER_OP_NEW,
 181         /**< Start the crypto adapter in event new mode.
 182          * @see RTE_EVENT_OP_NEW.
 183          * Application submits crypto operations to the cryptodev.
 184          * Adapter only dequeues the crypto completions from cryptodev
 185          * and enqueue events to the eventdev.
 186          */
 187         RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD,
 188         /**< Start the crypto adapter in event forward mode.
 189          * @see RTE_EVENT_OP_FORWARD.
 190          * Application submits crypto requests as events to the crypto
 191          * adapter or crypto device based on
 192          * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
 193          * Crypto completions are enqueued back to the eventdev by
 194          * crypto adapter.
 195          */
 196 };
 197
 198 /**
 199  * Crypto event request structure will be filled by application to
 200  * provide event request information to the adapter.
 201  */
 202 struct rte_event_crypto_request {
 203         uint8_t resv[8];
 204         /**< Overlaps with first 8 bytes of struct rte_event
 205          * that encode the response event information. Application
 206          * is expected to fill in struct rte_event response_info.
 207          */
 208         uint16_t cdev_id;
 209         /**< cryptodev ID to be used */
 210         uint16_t queue_pair_id;
 211         /**< cryptodev queue pair ID to be used */
 212         uint32_t resv1;
 213         /**< Reserved bits */
 214 };
 215
 216 /**
 217  * Crypto event metadata structure will be filled by application
 218  * to provide crypto request and event response information.
 219  *
 220  * If crypto events are enqueued using a HW mechanism, the cryptodev
 221  * PMD will use the event response information to set up the event
 222  * that is enqueued back to eventdev after completion of the crypto
 223  * operation. If the transfer is done by SW, event response information
 224  * will be used by the adapter.
 225  */
 226 union rte_event_crypto_metadata {
 227         struct rte_event_crypto_request request_info;
 228         /**< Request information to be filled in by application
 229          * for RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
 230          * First 8 bytes of request_info is reserved for response_info.
 231          */
 232         struct rte_event response_info;
 233         /**< Response information to be filled in by application
 234          * for RTE_EVENT_CRYPTO_ADAPTER_OP_NEW and
 235          * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
 236          */
 237 };
 238
 239 /**
 240  * Adapter configuration structure that the adapter configuration callback
 241  * function is expected to fill out
 242  * @see rte_event_crypto_adapter_conf_cb
 243  */
 244 struct rte_event_crypto_adapter_conf {
 245         uint8_t event_port_id;
 246         /**< Event port identifier, the adapter enqueues events to this
 247          * port and dequeues crypto request events in
 248          * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
 249          */
 250         uint32_t max_nb;
 251         /**< The adapter can return early if it has processed at least
 252          * max_nb crypto ops. This isn't treated as a requirement; batching
 253          * may cause the adapter to process more than max_nb crypto ops.
 254          */
 255 };
 256
 257 /**
 258  * Function type used for adapter configuration callback. The callback is
 259  * used to fill in members of the struct rte_event_crypto_adapter_conf, this
 260  * callback is invoked when creating a SW service for packet transfer from
 261  * cryptodev queue pair to the event device. The SW service is created within
 262  * the rte_event_crypto_adapter_queue_pair_add() function if SW based packet
 263  * transfers from cryptodev queue pair to the event device are required.
 264  *
 265  * @param id
 266  *  Adapter identifier.
 267  *
 268  * @param dev_id
 269  *  Event device identifier.
 270  *
 271  * @param conf
 272  *  Structure that needs to be populated by this callback.
 273  *
 274  * @param arg
 275  *  Argument to the callback. This is the same as the conf_arg passed to the
 276  *  rte_event_crypto_adapter_create_ext().
 277  */
 278 typedef int (*rte_event_crypto_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
 279                         struct rte_event_crypto_adapter_conf *conf,
 280                         void *arg);
 281
 282 /**
 283  * A structure used to retrieve statistics for an event crypto adapter
 284  * instance.
 285  */
 286
 287 struct rte_event_crypto_adapter_stats {
 288         uint64_t event_poll_count;
 289         /**< Event port poll count */
 290         uint64_t event_deq_count;
 291         /**< Event dequeue count */
 292         uint64_t crypto_enq_count;
 293         /**< Cryptodev enqueue count */
 294         uint64_t crypto_enq_fail;
 295         /**< Cryptodev enqueue failed count */
 296         uint64_t crypto_deq_count;
 297         /**< Cryptodev dequeue count */
 298         uint64_t event_enq_count;
 299         /**< Event enqueue count */
 300         uint64_t event_enq_retry_count;
 301         /**< Event enqueue retry count */
 302         uint64_t event_enq_fail_count;
 303         /**< Event enqueue fail count */
 304 };
 305
 306 /**
 307  * Create a new event crypto adapter with the specified identifier.
 308  *
 309  * @param id
 310  *  Adapter identifier.
 311  *
 312  * @param dev_id
 313  *  Event device identifier.
 314  *
 315  * @param conf_cb
 316  *  Callback function that fills in members of a
 317  *  struct rte_event_crypto_adapter_conf struct passed into
 318  *  it.
 319  *
 320  * @param mode
 321  *  Flag to indicate the mode of the adapter.
 322  *  @see rte_event_crypto_adapter_mode
 323  *
 324  * @param conf_arg
 325  *  Argument that is passed to the conf_cb function.
 326  *
 327  * @return
 328  *   - 0: Success
 329  *   - <0: Error code on failure
 330  */
 331 int
 332 rte_event_crypto_adapter_create_ext(uint8_t id, uint8_t dev_id,
 333                                     rte_event_crypto_adapter_conf_cb conf_cb,
 334                                     enum rte_event_crypto_adapter_mode mode,
 335                                     void *conf_arg);
 336
 337 /**
 338  * Create a new event crypto adapter with the specified identifier.
 339  * This function uses an internal configuration function that creates an event
 340  * port. This default function reconfigures the event device with an
 341  * additional event port and set up the event port using the port_config
 342  * parameter passed into this function. In case the application needs more
 343  * control in configuration of the service, it should use the
 344  * rte_event_crypto_adapter_create_ext() version.
 345  *
 346  * @param id
 347  *  Adapter identifier.
 348  *
 349  * @param dev_id
 350  *  Event device identifier.
 351  *
 352  * @param port_config
 353  *  Argument of type *rte_event_port_conf* that is passed to the conf_cb
 354  *  function.
 355  *
 356  * @param mode
 357  *  Flag to indicate the mode of the adapter.
 358  *  @see rte_event_crypto_adapter_mode
 359  *
 360  * @return
 361  *   - 0: Success
 362  *   - <0: Error code on failure
 363  */
 364 int
 365 rte_event_crypto_adapter_create(uint8_t id, uint8_t dev_id,
 366                                 struct rte_event_port_conf *port_config,
 367                                 enum rte_event_crypto_adapter_mode mode);
 368
 369 /**
 370  * Free an event crypto adapter
 371  *
 372  * @param id
 373  *  Adapter identifier.
 374  *
 375  * @return
 376  *   - 0: Success
 377  *   - <0: Error code on failure, If the adapter still has queue pairs
 378  *      added to it, the function returns -EBUSY.
 379  */
 380 int
 381 rte_event_crypto_adapter_free(uint8_t id);
 382
 383 /**
 384  * Add a queue pair to an event crypto adapter.
 385  *
 386  * @param id
 387  *  Adapter identifier.
 388  *
 389  * @param cdev_id
 390  *  Cryptodev identifier.
 391  *
 392  * @param queue_pair_id
 393  *  Cryptodev queue pair identifier. If queue_pair_id is set -1,
 394  *  adapter adds all the pre configured queue pairs to the instance.
 395  *
 396  * @param event
 397  *  if HW supports cryptodev queue pair to event queue binding, application is
 398  *  expected to fill in event information, else it will be NULL.
 399  *  @see RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND
 400  *
 401  * @return
 402  *  - 0: Success, queue pair added correctly.
 403  *  - <0: Error code on failure.
 404  */
 405 int
 406 rte_event_crypto_adapter_queue_pair_add(uint8_t id,
 407                         uint8_t cdev_id,
 408                         int32_t queue_pair_id,
 409                         const struct rte_event *event);
 410
 411 /**
 412  * Delete a queue pair from an event crypto adapter.
 413  *
 414  * @param id
 415  *  Adapter identifier.
 416  *
 417  * @param cdev_id
 418  *  Cryptodev identifier.
 419  *
 420  * @param queue_pair_id
 421  *  Cryptodev queue pair identifier.
 422  *
 423  * @return
 424  *  - 0: Success, queue pair deleted successfully.
 425  *  - <0: Error code on failure.
 426  */
 427 int
 428 rte_event_crypto_adapter_queue_pair_del(uint8_t id, uint8_t cdev_id,
 429                                         int32_t queue_pair_id);
 430
 431 /**
 432  * Start event crypto adapter
 433  *
 434  * @param id
 435  *  Adapter identifier.
 436  *
 437  *
 438  * @return
 439  *  - 0: Success, adapter started successfully.
 440  *  - <0: Error code on failure.
 441  *
 442  * @note
 443  *  The eventdev to which the event_crypto_adapter is connected needs to
 444  *  be started before calling rte_event_crypto_adapter_start().
 445  */
 446 int
 447 rte_event_crypto_adapter_start(uint8_t id);
 448
 449 /**
 450  * Stop event crypto adapter
 451  *
 452  * @param id
 453  *  Adapter identifier.
 454  *
 455  * @return
 456  *  - 0: Success, adapter stopped successfully.
 457  *  - <0: Error code on failure.
 458  */
 459 int
 460 rte_event_crypto_adapter_stop(uint8_t id);
 461
 462 /**
 463  * Retrieve statistics for an adapter
 464  *
 465  * @param id
 466  *  Adapter identifier.
 467  *
 468  * @param [out] stats
 469  *  A pointer to structure used to retrieve statistics for an adapter.
 470  *
 471  * @return
 472  *  - 0: Success, retrieved successfully.
 473  *  - <0: Error code on failure.
 474  */
 475 int
 476 rte_event_crypto_adapter_stats_get(uint8_t id,
 477                                 struct rte_event_crypto_adapter_stats *stats);
 478
 479 /**
 480  * Reset statistics for an adapter.
 481  *
 482  * @param id
 483  *  Adapter identifier.
 484  *
 485  * @return
 486  *  - 0: Success, statistics reset successfully.
 487  *  - <0: Error code on failure.
 488  */
 489 int
 490 rte_event_crypto_adapter_stats_reset(uint8_t id);
 491
 492 /**
 493  * Retrieve the service ID of an adapter. If the adapter doesn't use
 494  * a rte_service function, this function returns -ESRCH.
 495  *
 496  * @param id
 497  *  Adapter identifier.
 498  *
 499  * @param [out] service_id
 500  *  A pointer to a uint32_t, to be filled in with the service id.
 501  *
 502  * @return
 503  *  - 0: Success
 504  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
 505  * function, this function returns -ESRCH.
 506  */
 507 int
 508 rte_event_crypto_adapter_service_id_get(uint8_t id, uint32_t *service_id);
 509
 510 /**
 511  * Retrieve the event port of an adapter.
 512  *
 513  * @param id
 514  *  Adapter identifier.
 515  *
 516  * @param [out] event_port_id
 517  *  Application links its event queue to this adapter port which is used
 518  *  in RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
 519  *
 520  * @return
 521  *  - 0: Success
 522  *  - <0: Error code on failure.
 523  */
 524 int
 525 rte_event_crypto_adapter_event_port_get(uint8_t id, uint8_t *event_port_id);
 526
 527 /**
 528  * Enqueue a burst of crypto operations as event objects supplied in *rte_event*
 529  * structure on an event crypto adapter designated by its event *dev_id* through
 530  * the event port specified by *port_id*. This function is supported if the
 531  * eventdev PMD has the #RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD
 532  * capability flag set.
 533  *
 534  * The *nb_events* parameter is the number of event objects to enqueue which are
 535  * supplied in the *ev* array of *rte_event* structure.
 536  *
 537  * The rte_event_crypto_adapter_enqueue() function returns the number of
 538  * event objects it actually enqueued. A return value equal to *nb_events*
 539  * means that all event objects have been enqueued.
 540  *
 541  * @param dev_id
 542  *  The identifier of the device.
 543  * @param port_id
 544  *  The identifier of the event port.
 545  * @param ev
 546  *  Points to an array of *nb_events* objects of type *rte_event* structure
 547  *  which contain the event object enqueue operations to be processed.
 548  * @param nb_events
 549  *  The number of event objects to enqueue, typically number of
 550  *  rte_event_port_attr_get(...RTE_EVENT_PORT_ATTR_ENQ_DEPTH...)
 551  *  available for this port.
 552  *
 553  * @return
 554  *   The number of event objects actually enqueued on the event device. The
 555  *   return value can be less than the value of the *nb_events* parameter when
 556  *   the event devices queue is full or if invalid parameters are specified in a
 557  *   *rte_event*. If the return value is less than *nb_events*, the remaining
 558  *   events at the end of ev[] are not consumed and the caller has to take care
 559  *   of them, and rte_errno is set accordingly. Possible errno values include:
 560  *   - EINVAL   The port ID is invalid, device ID is invalid, an event's queue
 561  *              ID is invalid, or an event's sched type doesn't match the
 562  *              capabilities of the destination queue.
 563  *   - ENOSPC   The event port was backpressured and unable to enqueue
 564  *              one or more events. This error code is only applicable to
 565  *              closed systems.
 566  */
 567 static inline uint16_t
 568 rte_event_crypto_adapter_enqueue(uint8_t dev_id,
 569                                 uint8_t port_id,
 570                                 struct rte_event ev[],
 571                                 uint16_t nb_events)
 572 {
 573         const struct rte_eventdev *dev = &rte_eventdevs[dev_id];
 574
 575 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
 576         RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, -EINVAL);
 577
 578         if (port_id >= dev->data->nb_ports) {
 579                 rte_errno = EINVAL;
 580                 return 0;
 581         }
 582 #endif
 583         rte_eventdev_trace_crypto_adapter_enqueue(dev_id, port_id, ev,
 584                 nb_events);
 585
 586         return dev->ca_enqueue(dev->data->ports[port_id], ev, nb_events);
 587 }
 588
 589 #ifdef __cplusplus
 590 }
 591 #endif
 592 #endif  /* _RTE_EVENT_CRYPTO_ADAPTER_ */