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