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