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 */ 230 struct rte_event response_info; 231 /**< Response information to be filled in by application 232 * for RTE_EVENT_CRYPTO_ADAPTER_OP_NEW and 233 * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode. 234 */ 235 }; 236 237 /** 238 * Adapter configuration structure that the adapter configuration callback 239 * function is expected to fill out 240 * @see rte_event_crypto_adapter_conf_cb 241 */ 242 struct rte_event_crypto_adapter_conf { 243 uint8_t event_port_id; 244 /**< Event port identifier, the adapter enqueues events to this 245 * port and dequeues crypto request events in 246 * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode. 247 */ 248 uint32_t max_nb; 249 /**< The adapter can return early if it has processed at least 250 * max_nb crypto ops. This isn't treated as a requirement; batching 251 * may cause the adapter to process more than max_nb crypto ops. 252 */ 253 }; 254 255 /** 256 * Function type used for adapter configuration callback. The callback is 257 * used to fill in members of the struct rte_event_crypto_adapter_conf, this 258 * callback is invoked when creating a SW service for packet transfer from 259 * cryptodev queue pair to the event device. The SW service is created within 260 * the rte_event_crypto_adapter_queue_pair_add() function if SW based packet 261 * transfers from cryptodev queue pair to the event device are required. 262 * 263 * @param id 264 * Adapter identifier. 265 * 266 * @param dev_id 267 * Event device identifier. 268 * 269 * @param conf 270 * Structure that needs to be populated by this callback. 271 * 272 * @param arg 273 * Argument to the callback. This is the same as the conf_arg passed to the 274 * rte_event_crypto_adapter_create_ext(). 275 */ 276 typedef int (*rte_event_crypto_adapter_conf_cb) (uint8_t id, uint8_t dev_id, 277 struct rte_event_crypto_adapter_conf *conf, 278 void *arg); 279 280 /** 281 * A structure used to retrieve statistics for an event crypto adapter 282 * instance. 283 */ 284 285 struct rte_event_crypto_adapter_stats { 286 uint64_t event_poll_count; 287 /**< Event port poll count */ 288 uint64_t event_deq_count; 289 /**< Event dequeue count */ 290 uint64_t crypto_enq_count; 291 /**< Cryptodev enqueue count */ 292 uint64_t crypto_enq_fail; 293 /**< Cryptodev enqueue failed count */ 294 uint64_t crypto_deq_count; 295 /**< Cryptodev dequeue count */ 296 uint64_t event_enq_count; 297 /**< Event enqueue count */ 298 uint64_t event_enq_retry_count; 299 /**< Event enqueue retry count */ 300 uint64_t event_enq_fail_count; 301 /**< Event enqueue fail count */ 302 }; 303 304 /** 305 * Create a new event crypto adapter with the specified identifier. 306 * 307 * @param id 308 * Adapter identifier. 309 * 310 * @param dev_id 311 * Event device identifier. 312 * 313 * @param conf_cb 314 * Callback function that fills in members of a 315 * struct rte_event_crypto_adapter_conf struct passed into 316 * it. 317 * 318 * @param mode 319 * Flag to indicate the mode of the adapter. 320 * @see rte_event_crypto_adapter_mode 321 * 322 * @param conf_arg 323 * Argument that is passed to the conf_cb function. 324 * 325 * @return 326 * - 0: Success 327 * - <0: Error code on failure 328 */ 329 int 330 rte_event_crypto_adapter_create_ext(uint8_t id, uint8_t dev_id, 331 rte_event_crypto_adapter_conf_cb conf_cb, 332 enum rte_event_crypto_adapter_mode mode, 333 void *conf_arg); 334 335 /** 336 * Create a new event crypto adapter with the specified identifier. 337 * This function uses an internal configuration function that creates an event 338 * port. This default function reconfigures the event device with an 339 * additional event port and set up the event port using the port_config 340 * parameter passed into this function. In case the application needs more 341 * control in configuration of the service, it should use the 342 * rte_event_crypto_adapter_create_ext() version. 343 * 344 * @param id 345 * Adapter identifier. 346 * 347 * @param dev_id 348 * Event device identifier. 349 * 350 * @param port_config 351 * Argument of type *rte_event_port_conf* that is passed to the conf_cb 352 * function. 353 * 354 * @param mode 355 * Flag to indicate the mode of the adapter. 356 * @see rte_event_crypto_adapter_mode 357 * 358 * @return 359 * - 0: Success 360 * - <0: Error code on failure 361 */ 362 int 363 rte_event_crypto_adapter_create(uint8_t id, uint8_t dev_id, 364 struct rte_event_port_conf *port_config, 365 enum rte_event_crypto_adapter_mode mode); 366 367 /** 368 * Free an event crypto adapter 369 * 370 * @param id 371 * Adapter identifier. 372 * 373 * @return 374 * - 0: Success 375 * - <0: Error code on failure, If the adapter still has queue pairs 376 * added to it, the function returns -EBUSY. 377 */ 378 int 379 rte_event_crypto_adapter_free(uint8_t id); 380 381 /** 382 * Add a queue pair to an event crypto adapter. 383 * 384 * @param id 385 * Adapter identifier. 386 * 387 * @param cdev_id 388 * Cryptodev identifier. 389 * 390 * @param queue_pair_id 391 * Cryptodev queue pair identifier. If queue_pair_id is set -1, 392 * adapter adds all the pre configured queue pairs to the instance. 393 * 394 * @param event 395 * if HW supports cryptodev queue pair to event queue binding, application is 396 * expected to fill in event information, else it will be NULL. 397 * @see RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND 398 * 399 * @return 400 * - 0: Success, queue pair added correctly. 401 * - <0: Error code on failure. 402 */ 403 int 404 rte_event_crypto_adapter_queue_pair_add(uint8_t id, 405 uint8_t cdev_id, 406 int32_t queue_pair_id, 407 const struct rte_event *event); 408 409 /** 410 * Delete a queue pair from an event crypto adapter. 411 * 412 * @param id 413 * Adapter identifier. 414 * 415 * @param cdev_id 416 * Cryptodev identifier. 417 * 418 * @param queue_pair_id 419 * Cryptodev queue pair identifier. 420 * 421 * @return 422 * - 0: Success, queue pair deleted successfully. 423 * - <0: Error code on failure. 424 */ 425 int 426 rte_event_crypto_adapter_queue_pair_del(uint8_t id, uint8_t cdev_id, 427 int32_t queue_pair_id); 428 429 /** 430 * Start event crypto adapter 431 * 432 * @param id 433 * Adapter identifier. 434 * 435 * 436 * @return 437 * - 0: Success, adapter started successfully. 438 * - <0: Error code on failure. 439 * 440 * @note 441 * The eventdev to which the event_crypto_adapter is connected needs to 442 * be started before calling rte_event_crypto_adapter_start(). 443 */ 444 int 445 rte_event_crypto_adapter_start(uint8_t id); 446 447 /** 448 * Stop event crypto adapter 449 * 450 * @param id 451 * Adapter identifier. 452 * 453 * @return 454 * - 0: Success, adapter stopped successfully. 455 * - <0: Error code on failure. 456 */ 457 int 458 rte_event_crypto_adapter_stop(uint8_t id); 459 460 /** 461 * Retrieve statistics for an adapter 462 * 463 * @param id 464 * Adapter identifier. 465 * 466 * @param [out] stats 467 * A pointer to structure used to retrieve statistics for an adapter. 468 * 469 * @return 470 * - 0: Success, retrieved successfully. 471 * - <0: Error code on failure. 472 */ 473 int 474 rte_event_crypto_adapter_stats_get(uint8_t id, 475 struct rte_event_crypto_adapter_stats *stats); 476 477 /** 478 * Reset statistics for an adapter. 479 * 480 * @param id 481 * Adapter identifier. 482 * 483 * @return 484 * - 0: Success, statistics reset successfully. 485 * - <0: Error code on failure. 486 */ 487 int 488 rte_event_crypto_adapter_stats_reset(uint8_t id); 489 490 /** 491 * Retrieve the service ID of an adapter. If the adapter doesn't use 492 * a rte_service function, this function returns -ESRCH. 493 * 494 * @param id 495 * Adapter identifier. 496 * 497 * @param [out] service_id 498 * A pointer to a uint32_t, to be filled in with the service id. 499 * 500 * @return 501 * - 0: Success 502 * - <0: Error code on failure, if the adapter doesn't use a rte_service 503 * function, this function returns -ESRCH. 504 */ 505 int 506 rte_event_crypto_adapter_service_id_get(uint8_t id, uint32_t *service_id); 507 508 /** 509 * Retrieve the event port of an adapter. 510 * 511 * @param id 512 * Adapter identifier. 513 * 514 * @param [out] event_port_id 515 * Application links its event queue to this adapter port which is used 516 * in RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode. 517 * 518 * @return 519 * - 0: Success 520 * - <0: Error code on failure. 521 */ 522 int 523 rte_event_crypto_adapter_event_port_get(uint8_t id, uint8_t *event_port_id); 524 525 #ifdef __cplusplus 526 } 527 #endif 528 #endif /* _RTE_EVENT_CRYPTO_ADAPTER_ */ 529