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_ */ 593