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 * @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_ */ 576