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 * First 8 bytes of request_info is reserved for response_info. 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 and cryptodev to which the event_crypto_adapter is connected 443 * needs to 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_event_fp_ops *fp_ops; 573 void *port; 574 575 fp_ops = &rte_event_fp_ops[dev_id]; 576 port = fp_ops->data[port_id]; 577 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG 578 if (dev_id >= RTE_EVENT_MAX_DEVS || 579 port_id >= RTE_EVENT_MAX_PORTS_PER_DEV) { 580 rte_errno = EINVAL; 581 return 0; 582 } 583 584 if (port == NULL) { 585 rte_errno = EINVAL; 586 return 0; 587 } 588 #endif 589 rte_eventdev_trace_crypto_adapter_enqueue(dev_id, port_id, ev, 590 nb_events); 591 592 return fp_ops->ca_enqueue(port, ev, nb_events); 593 } 594 595 #ifdef __cplusplus 596 } 597 #endif 598 #endif /* _RTE_EVENT_CRYPTO_ADAPTER_ */ 599