1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2015-2017 Intel Corporation. 3 */ 4 5 #ifndef _RTE_CRYPTODEV_H_ 6 #define _RTE_CRYPTODEV_H_ 7 8 /** 9 * @file rte_cryptodev.h 10 * 11 * RTE Cryptographic Device APIs 12 * 13 * Defines RTE Crypto Device APIs for the provisioning of cipher and 14 * authentication operations. 15 */ 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include "rte_kvargs.h" 22 #include "rte_crypto.h" 23 #include "rte_dev.h" 24 #include <rte_common.h> 25 #include <rte_config.h> 26 27 extern const char **rte_cyptodev_names; 28 29 /* Logging Macros */ 30 31 #define CDEV_LOG_ERR(...) \ 32 RTE_LOG(ERR, CRYPTODEV, \ 33 RTE_FMT("%s() line %u: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \ 34 __func__, __LINE__, RTE_FMT_TAIL(__VA_ARGS__,))) 35 36 #define CDEV_LOG_INFO(...) \ 37 RTE_LOG(INFO, CRYPTODEV, \ 38 RTE_FMT(RTE_FMT_HEAD(__VA_ARGS__,) "\n", \ 39 RTE_FMT_TAIL(__VA_ARGS__,))) 40 41 #define CDEV_LOG_DEBUG(...) \ 42 RTE_LOG(DEBUG, CRYPTODEV, \ 43 RTE_FMT("%s() line %u: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \ 44 __func__, __LINE__, RTE_FMT_TAIL(__VA_ARGS__,))) 45 46 #define CDEV_PMD_TRACE(...) \ 47 RTE_LOG(DEBUG, CRYPTODEV, \ 48 RTE_FMT("[%s] %s: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \ 49 dev, __func__, RTE_FMT_TAIL(__VA_ARGS__,))) 50 51 /** 52 * A macro that points to an offset from the start 53 * of the crypto operation structure (rte_crypto_op) 54 * 55 * The returned pointer is cast to type t. 56 * 57 * @param c 58 * The crypto operation. 59 * @param o 60 * The offset from the start of the crypto operation. 61 * @param t 62 * The type to cast the result into. 63 */ 64 #define rte_crypto_op_ctod_offset(c, t, o) \ 65 ((t)((char *)(c) + (o))) 66 67 /** 68 * A macro that returns the physical address that points 69 * to an offset from the start of the crypto operation 70 * (rte_crypto_op) 71 * 72 * @param c 73 * The crypto operation. 74 * @param o 75 * The offset from the start of the crypto operation 76 * to calculate address from. 77 */ 78 #define rte_crypto_op_ctophys_offset(c, o) \ 79 (rte_iova_t)((c)->phys_addr + (o)) 80 81 /** 82 * Crypto parameters range description 83 */ 84 struct rte_crypto_param_range { 85 uint16_t min; /**< minimum size */ 86 uint16_t max; /**< maximum size */ 87 uint16_t increment; 88 /**< if a range of sizes are supported, 89 * this parameter is used to indicate 90 * increments in byte size that are supported 91 * between the minimum and maximum 92 */ 93 }; 94 95 /** 96 * Symmetric Crypto Capability 97 */ 98 struct rte_cryptodev_symmetric_capability { 99 enum rte_crypto_sym_xform_type xform_type; 100 /**< Transform type : Authentication / Cipher / AEAD */ 101 RTE_STD_C11 102 union { 103 struct { 104 enum rte_crypto_auth_algorithm algo; 105 /**< authentication algorithm */ 106 uint16_t block_size; 107 /**< algorithm block size */ 108 struct rte_crypto_param_range key_size; 109 /**< auth key size range */ 110 struct rte_crypto_param_range digest_size; 111 /**< digest size range */ 112 struct rte_crypto_param_range aad_size; 113 /**< Additional authentication data size range */ 114 struct rte_crypto_param_range iv_size; 115 /**< Initialisation vector data size range */ 116 } auth; 117 /**< Symmetric Authentication transform capabilities */ 118 struct { 119 enum rte_crypto_cipher_algorithm algo; 120 /**< cipher algorithm */ 121 uint16_t block_size; 122 /**< algorithm block size */ 123 struct rte_crypto_param_range key_size; 124 /**< cipher key size range */ 125 struct rte_crypto_param_range iv_size; 126 /**< Initialisation vector data size range */ 127 } cipher; 128 /**< Symmetric Cipher transform capabilities */ 129 struct { 130 enum rte_crypto_aead_algorithm algo; 131 /**< AEAD algorithm */ 132 uint16_t block_size; 133 /**< algorithm block size */ 134 struct rte_crypto_param_range key_size; 135 /**< AEAD key size range */ 136 struct rte_crypto_param_range digest_size; 137 /**< digest size range */ 138 struct rte_crypto_param_range aad_size; 139 /**< Additional authentication data size range */ 140 struct rte_crypto_param_range iv_size; 141 /**< Initialisation vector data size range */ 142 } aead; 143 }; 144 }; 145 146 /** 147 * Asymmetric Xform Crypto Capability 148 * 149 */ 150 struct rte_cryptodev_asymmetric_xform_capability { 151 enum rte_crypto_asym_xform_type xform_type; 152 /**< Transform type: RSA/MODEXP/DH/DSA/MODINV */ 153 154 uint32_t op_types; 155 /**< bitmask for supported rte_crypto_asym_op_type */ 156 157 __extension__ 158 union { 159 struct rte_crypto_param_range modlen; 160 /**< Range of modulus length supported by modulus based xform. 161 * Value 0 mean implementation default 162 */ 163 }; 164 }; 165 166 /** 167 * Asymmetric Crypto Capability 168 * 169 */ 170 struct rte_cryptodev_asymmetric_capability { 171 struct rte_cryptodev_asymmetric_xform_capability xform_capa; 172 }; 173 174 175 /** Structure used to capture a capability of a crypto device */ 176 struct rte_cryptodev_capabilities { 177 enum rte_crypto_op_type op; 178 /**< Operation type */ 179 180 RTE_STD_C11 181 union { 182 struct rte_cryptodev_symmetric_capability sym; 183 /**< Symmetric operation capability parameters */ 184 struct rte_cryptodev_asymmetric_capability asym; 185 /**< Asymmetric operation capability parameters */ 186 }; 187 }; 188 189 /** Structure used to describe crypto algorithms */ 190 struct rte_cryptodev_sym_capability_idx { 191 enum rte_crypto_sym_xform_type type; 192 union { 193 enum rte_crypto_cipher_algorithm cipher; 194 enum rte_crypto_auth_algorithm auth; 195 enum rte_crypto_aead_algorithm aead; 196 } algo; 197 }; 198 199 /** 200 * Structure used to describe asymmetric crypto xforms 201 * Each xform maps to one asym algorithm. 202 * 203 */ 204 struct rte_cryptodev_asym_capability_idx { 205 enum rte_crypto_asym_xform_type type; 206 /**< Asymmetric xform (algo) type */ 207 }; 208 209 /** 210 * Provide capabilities available for defined device and algorithm 211 * 212 * @param dev_id The identifier of the device. 213 * @param idx Description of crypto algorithms. 214 * 215 * @return 216 * - Return description of the symmetric crypto capability if exist. 217 * - Return NULL if the capability not exist. 218 */ 219 const struct rte_cryptodev_symmetric_capability * 220 rte_cryptodev_sym_capability_get(uint8_t dev_id, 221 const struct rte_cryptodev_sym_capability_idx *idx); 222 223 /** 224 * Provide capabilities available for defined device and xform 225 * 226 * @param dev_id The identifier of the device. 227 * @param idx Description of asym crypto xform. 228 * 229 * @return 230 * - Return description of the asymmetric crypto capability if exist. 231 * - Return NULL if the capability not exist. 232 */ 233 const struct rte_cryptodev_asymmetric_xform_capability * __rte_experimental 234 rte_cryptodev_asym_capability_get(uint8_t dev_id, 235 const struct rte_cryptodev_asym_capability_idx *idx); 236 237 /** 238 * Check if key size and initial vector are supported 239 * in crypto cipher capability 240 * 241 * @param capability Description of the symmetric crypto capability. 242 * @param key_size Cipher key size. 243 * @param iv_size Cipher initial vector size. 244 * 245 * @return 246 * - Return 0 if the parameters are in range of the capability. 247 * - Return -1 if the parameters are out of range of the capability. 248 */ 249 int 250 rte_cryptodev_sym_capability_check_cipher( 251 const struct rte_cryptodev_symmetric_capability *capability, 252 uint16_t key_size, uint16_t iv_size); 253 254 /** 255 * Check if key size and initial vector are supported 256 * in crypto auth capability 257 * 258 * @param capability Description of the symmetric crypto capability. 259 * @param key_size Auth key size. 260 * @param digest_size Auth digest size. 261 * @param iv_size Auth initial vector size. 262 * 263 * @return 264 * - Return 0 if the parameters are in range of the capability. 265 * - Return -1 if the parameters are out of range of the capability. 266 */ 267 int 268 rte_cryptodev_sym_capability_check_auth( 269 const struct rte_cryptodev_symmetric_capability *capability, 270 uint16_t key_size, uint16_t digest_size, uint16_t iv_size); 271 272 /** 273 * Check if key, digest, AAD and initial vector sizes are supported 274 * in crypto AEAD capability 275 * 276 * @param capability Description of the symmetric crypto capability. 277 * @param key_size AEAD key size. 278 * @param digest_size AEAD digest size. 279 * @param aad_size AEAD AAD size. 280 * @param iv_size AEAD IV size. 281 * 282 * @return 283 * - Return 0 if the parameters are in range of the capability. 284 * - Return -1 if the parameters are out of range of the capability. 285 */ 286 int 287 rte_cryptodev_sym_capability_check_aead( 288 const struct rte_cryptodev_symmetric_capability *capability, 289 uint16_t key_size, uint16_t digest_size, uint16_t aad_size, 290 uint16_t iv_size); 291 292 /** 293 * Check if op type is supported 294 * 295 * @param capability Description of the asymmetric crypto capability. 296 * @param op_type op type 297 * 298 * @return 299 * - Return 1 if the op type is supported 300 * - Return 0 if unsupported 301 */ 302 int __rte_experimental 303 rte_cryptodev_asym_xform_capability_check_optype( 304 const struct rte_cryptodev_asymmetric_xform_capability *capability, 305 enum rte_crypto_asym_op_type op_type); 306 307 /** 308 * Check if modulus length is in supported range 309 * 310 * @param capability Description of the asymmetric crypto capability. 311 * @param modlen modulus length. 312 * 313 * @return 314 * - Return 0 if the parameters are in range of the capability. 315 * - Return -1 if the parameters are out of range of the capability. 316 */ 317 int __rte_experimental 318 rte_cryptodev_asym_xform_capability_check_modlen( 319 const struct rte_cryptodev_asymmetric_xform_capability *capability, 320 uint16_t modlen); 321 322 /** 323 * Provide the cipher algorithm enum, given an algorithm string 324 * 325 * @param algo_enum A pointer to the cipher algorithm 326 * enum to be filled 327 * @param algo_string Authentication algo string 328 * 329 * @return 330 * - Return -1 if string is not valid 331 * - Return 0 is the string is valid 332 */ 333 int 334 rte_cryptodev_get_cipher_algo_enum(enum rte_crypto_cipher_algorithm *algo_enum, 335 const char *algo_string); 336 337 /** 338 * Provide the authentication algorithm enum, given an algorithm string 339 * 340 * @param algo_enum A pointer to the authentication algorithm 341 * enum to be filled 342 * @param algo_string Authentication algo string 343 * 344 * @return 345 * - Return -1 if string is not valid 346 * - Return 0 is the string is valid 347 */ 348 int 349 rte_cryptodev_get_auth_algo_enum(enum rte_crypto_auth_algorithm *algo_enum, 350 const char *algo_string); 351 352 /** 353 * Provide the AEAD algorithm enum, given an algorithm string 354 * 355 * @param algo_enum A pointer to the AEAD algorithm 356 * enum to be filled 357 * @param algo_string AEAD algorithm string 358 * 359 * @return 360 * - Return -1 if string is not valid 361 * - Return 0 is the string is valid 362 */ 363 int 364 rte_cryptodev_get_aead_algo_enum(enum rte_crypto_aead_algorithm *algo_enum, 365 const char *algo_string); 366 367 /** 368 * Provide the Asymmetric xform enum, given an xform string 369 * 370 * @param xform_enum A pointer to the xform type 371 * enum to be filled 372 * @param xform_string xform string 373 * 374 * @return 375 * - Return -1 if string is not valid 376 * - Return 0 if the string is valid 377 */ 378 int __rte_experimental 379 rte_cryptodev_asym_get_xform_enum(enum rte_crypto_asym_xform_type *xform_enum, 380 const char *xform_string); 381 382 383 /** Macro used at end of crypto PMD list */ 384 #define RTE_CRYPTODEV_END_OF_CAPABILITIES_LIST() \ 385 { RTE_CRYPTO_OP_TYPE_UNDEFINED } 386 387 388 /** 389 * Crypto device supported feature flags 390 * 391 * Note: 392 * New features flags should be added to the end of the list 393 * 394 * Keep these flags synchronised with rte_cryptodev_get_feature_name() 395 */ 396 #define RTE_CRYPTODEV_FF_SYMMETRIC_CRYPTO (1ULL << 0) 397 /**< Symmetric crypto operations are supported */ 398 #define RTE_CRYPTODEV_FF_ASYMMETRIC_CRYPTO (1ULL << 1) 399 /**< Asymmetric crypto operations are supported */ 400 #define RTE_CRYPTODEV_FF_SYM_OPERATION_CHAINING (1ULL << 2) 401 /**< Chaining symmetric crypto operations are supported */ 402 #define RTE_CRYPTODEV_FF_CPU_SSE (1ULL << 3) 403 /**< Utilises CPU SIMD SSE instructions */ 404 #define RTE_CRYPTODEV_FF_CPU_AVX (1ULL << 4) 405 /**< Utilises CPU SIMD AVX instructions */ 406 #define RTE_CRYPTODEV_FF_CPU_AVX2 (1ULL << 5) 407 /**< Utilises CPU SIMD AVX2 instructions */ 408 #define RTE_CRYPTODEV_FF_CPU_AESNI (1ULL << 6) 409 /**< Utilises CPU AES-NI instructions */ 410 #define RTE_CRYPTODEV_FF_HW_ACCELERATED (1ULL << 7) 411 /**< Operations are off-loaded to an 412 * external hardware accelerator 413 */ 414 #define RTE_CRYPTODEV_FF_CPU_AVX512 (1ULL << 8) 415 /**< Utilises CPU SIMD AVX512 instructions */ 416 #define RTE_CRYPTODEV_FF_IN_PLACE_SGL (1ULL << 9) 417 /**< In-place Scatter-gather (SGL) buffers, with multiple segments, 418 * are supported 419 */ 420 #define RTE_CRYPTODEV_FF_OOP_SGL_IN_SGL_OUT (1ULL << 10) 421 /**< Out-of-place Scatter-gather (SGL) buffers are 422 * supported in input and output 423 */ 424 #define RTE_CRYPTODEV_FF_OOP_SGL_IN_LB_OUT (1ULL << 11) 425 /**< Out-of-place Scatter-gather (SGL) buffers are supported 426 * in input, combined with linear buffers (LB), with a 427 * single segment in output 428 */ 429 #define RTE_CRYPTODEV_FF_OOP_LB_IN_SGL_OUT (1ULL << 12) 430 /**< Out-of-place Scatter-gather (SGL) buffers are supported 431 * in output, combined with linear buffers (LB) in input 432 */ 433 #define RTE_CRYPTODEV_FF_OOP_LB_IN_LB_OUT (1ULL << 13) 434 /**< Out-of-place linear buffers (LB) are supported in input and output */ 435 #define RTE_CRYPTODEV_FF_CPU_NEON (1ULL << 14) 436 /**< Utilises CPU NEON instructions */ 437 #define RTE_CRYPTODEV_FF_CPU_ARM_CE (1ULL << 15) 438 /**< Utilises ARM CPU Cryptographic Extensions */ 439 #define RTE_CRYPTODEV_FF_SECURITY (1ULL << 16) 440 /**< Support Security Protocol Processing */ 441 442 443 /** 444 * Get the name of a crypto device feature flag 445 * 446 * @param flag The mask describing the flag. 447 * 448 * @return 449 * The name of this flag, or NULL if it's not a valid feature flag. 450 */ 451 452 extern const char * 453 rte_cryptodev_get_feature_name(uint64_t flag); 454 455 /** Crypto device information */ 456 struct rte_cryptodev_info { 457 const char *driver_name; /**< Driver name. */ 458 uint8_t driver_id; /**< Driver identifier */ 459 struct rte_device *device; /**< Generic device information. */ 460 461 uint64_t feature_flags; 462 /**< Feature flags exposes HW/SW features for the given device */ 463 464 const struct rte_cryptodev_capabilities *capabilities; 465 /**< Array of devices supported capabilities */ 466 467 unsigned max_nb_queue_pairs; 468 /**< Maximum number of queues pairs supported by device. */ 469 470 uint16_t min_mbuf_headroom_req; 471 /**< Minimum mbuf headroom required by device */ 472 473 uint16_t min_mbuf_tailroom_req; 474 /**< Minimum mbuf tailroom required by device */ 475 476 struct { 477 unsigned max_nb_sessions; 478 /**< Maximum number of sessions supported by device. 479 * If 0, the device does not have any limitation in 480 * number of sessions that can be used. 481 */ 482 } sym; 483 }; 484 485 #define RTE_CRYPTODEV_DETACHED (0) 486 #define RTE_CRYPTODEV_ATTACHED (1) 487 488 /** Definitions of Crypto device event types */ 489 enum rte_cryptodev_event_type { 490 RTE_CRYPTODEV_EVENT_UNKNOWN, /**< unknown event type */ 491 RTE_CRYPTODEV_EVENT_ERROR, /**< error interrupt event */ 492 RTE_CRYPTODEV_EVENT_MAX /**< max value of this enum */ 493 }; 494 495 /** Crypto device queue pair configuration structure. */ 496 struct rte_cryptodev_qp_conf { 497 uint32_t nb_descriptors; /**< Number of descriptors per queue pair */ 498 }; 499 500 /** 501 * Typedef for application callback function to be registered by application 502 * software for notification of device events 503 * 504 * @param dev_id Crypto device identifier 505 * @param event Crypto device event to register for notification of. 506 * @param cb_arg User specified parameter to be passed as to passed to 507 * users callback function. 508 */ 509 typedef void (*rte_cryptodev_cb_fn)(uint8_t dev_id, 510 enum rte_cryptodev_event_type event, void *cb_arg); 511 512 513 /** Crypto Device statistics */ 514 struct rte_cryptodev_stats { 515 uint64_t enqueued_count; 516 /**< Count of all operations enqueued */ 517 uint64_t dequeued_count; 518 /**< Count of all operations dequeued */ 519 520 uint64_t enqueue_err_count; 521 /**< Total error count on operations enqueued */ 522 uint64_t dequeue_err_count; 523 /**< Total error count on operations dequeued */ 524 }; 525 526 #define RTE_CRYPTODEV_NAME_MAX_LEN (64) 527 /**< Max length of name of crypto PMD */ 528 529 /** 530 * Get the device identifier for the named crypto device. 531 * 532 * @param name device name to select the device structure. 533 * 534 * @return 535 * - Returns crypto device identifier on success. 536 * - Return -1 on failure to find named crypto device. 537 */ 538 extern int 539 rte_cryptodev_get_dev_id(const char *name); 540 541 /** 542 * Get the crypto device name given a device identifier. 543 * 544 * @param dev_id 545 * The identifier of the device 546 * 547 * @return 548 * - Returns crypto device name. 549 * - Returns NULL if crypto device is not present. 550 */ 551 extern const char * 552 rte_cryptodev_name_get(uint8_t dev_id); 553 554 /** 555 * Get the total number of crypto devices that have been successfully 556 * initialised. 557 * 558 * @return 559 * - The total number of usable crypto devices. 560 */ 561 extern uint8_t 562 rte_cryptodev_count(void); 563 564 /** 565 * Get number of crypto device defined type. 566 * 567 * @param driver_id driver identifier. 568 * 569 * @return 570 * Returns number of crypto device. 571 */ 572 extern uint8_t 573 rte_cryptodev_device_count_by_driver(uint8_t driver_id); 574 575 /** 576 * Get number and identifiers of attached crypto devices that 577 * use the same crypto driver. 578 * 579 * @param driver_name driver name. 580 * @param devices output devices identifiers. 581 * @param nb_devices maximal number of devices. 582 * 583 * @return 584 * Returns number of attached crypto device. 585 */ 586 uint8_t 587 rte_cryptodev_devices_get(const char *driver_name, uint8_t *devices, 588 uint8_t nb_devices); 589 /* 590 * Return the NUMA socket to which a device is connected 591 * 592 * @param dev_id 593 * The identifier of the device 594 * @return 595 * The NUMA socket id to which the device is connected or 596 * a default of zero if the socket could not be determined. 597 * -1 if returned is the dev_id value is out of range. 598 */ 599 extern int 600 rte_cryptodev_socket_id(uint8_t dev_id); 601 602 /** Crypto device configuration structure */ 603 struct rte_cryptodev_config { 604 int socket_id; /**< Socket to allocate resources on */ 605 uint16_t nb_queue_pairs; 606 /**< Number of queue pairs to configure on device */ 607 }; 608 609 /** 610 * Configure a device. 611 * 612 * This function must be invoked first before any other function in the 613 * API. This function can also be re-invoked when a device is in the 614 * stopped state. 615 * 616 * @param dev_id The identifier of the device to configure. 617 * @param config The crypto device configuration structure. 618 * 619 * @return 620 * - 0: Success, device configured. 621 * - <0: Error code returned by the driver configuration function. 622 */ 623 extern int 624 rte_cryptodev_configure(uint8_t dev_id, struct rte_cryptodev_config *config); 625 626 /** 627 * Start an device. 628 * 629 * The device start step is the last one and consists of setting the configured 630 * offload features and in starting the transmit and the receive units of the 631 * device. 632 * On success, all basic functions exported by the API (link status, 633 * receive/transmit, and so on) can be invoked. 634 * 635 * @param dev_id 636 * The identifier of the device. 637 * @return 638 * - 0: Success, device started. 639 * - <0: Error code of the driver device start function. 640 */ 641 extern int 642 rte_cryptodev_start(uint8_t dev_id); 643 644 /** 645 * Stop an device. The device can be restarted with a call to 646 * rte_cryptodev_start() 647 * 648 * @param dev_id The identifier of the device. 649 */ 650 extern void 651 rte_cryptodev_stop(uint8_t dev_id); 652 653 /** 654 * Close an device. The device cannot be restarted! 655 * 656 * @param dev_id The identifier of the device. 657 * 658 * @return 659 * - 0 on successfully closing device 660 * - <0 on failure to close device 661 */ 662 extern int 663 rte_cryptodev_close(uint8_t dev_id); 664 665 /** 666 * Allocate and set up a receive queue pair for a device. 667 * 668 * 669 * @param dev_id The identifier of the device. 670 * @param queue_pair_id The index of the queue pairs to set up. The 671 * value must be in the range [0, nb_queue_pair 672 * - 1] previously supplied to 673 * rte_cryptodev_configure(). 674 * @param qp_conf The pointer to the configuration data to be 675 * used for the queue pair. NULL value is 676 * allowed, in which case default configuration 677 * will be used. 678 * @param socket_id The *socket_id* argument is the socket 679 * identifier in case of NUMA. The value can be 680 * *SOCKET_ID_ANY* if there is no NUMA constraint 681 * for the DMA memory allocated for the receive 682 * queue pair. 683 * @param session_pool Pointer to device session mempool, used 684 * for session-less operations. 685 * 686 * @return 687 * - 0: Success, queue pair correctly set up. 688 * - <0: Queue pair configuration failed 689 */ 690 extern int 691 rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id, 692 const struct rte_cryptodev_qp_conf *qp_conf, int socket_id, 693 struct rte_mempool *session_pool); 694 695 /** 696 * Get the number of queue pairs on a specific crypto device 697 * 698 * @param dev_id Crypto device identifier. 699 * @return 700 * - The number of configured queue pairs. 701 */ 702 extern uint16_t 703 rte_cryptodev_queue_pair_count(uint8_t dev_id); 704 705 706 /** 707 * Retrieve the general I/O statistics of a device. 708 * 709 * @param dev_id The identifier of the device. 710 * @param stats A pointer to a structure of type 711 * *rte_cryptodev_stats* to be filled with the 712 * values of device counters. 713 * @return 714 * - Zero if successful. 715 * - Non-zero otherwise. 716 */ 717 extern int 718 rte_cryptodev_stats_get(uint8_t dev_id, struct rte_cryptodev_stats *stats); 719 720 /** 721 * Reset the general I/O statistics of a device. 722 * 723 * @param dev_id The identifier of the device. 724 */ 725 extern void 726 rte_cryptodev_stats_reset(uint8_t dev_id); 727 728 /** 729 * Retrieve the contextual information of a device. 730 * 731 * @param dev_id The identifier of the device. 732 * @param dev_info A pointer to a structure of type 733 * *rte_cryptodev_info* to be filled with the 734 * contextual information of the device. 735 * 736 * @note The capabilities field of dev_info is set to point to the first 737 * element of an array of struct rte_cryptodev_capabilities. The element after 738 * the last valid element has it's op field set to 739 * RTE_CRYPTO_OP_TYPE_UNDEFINED. 740 */ 741 extern void 742 rte_cryptodev_info_get(uint8_t dev_id, struct rte_cryptodev_info *dev_info); 743 744 745 /** 746 * Register a callback function for specific device id. 747 * 748 * @param dev_id Device id. 749 * @param event Event interested. 750 * @param cb_fn User supplied callback function to be called. 751 * @param cb_arg Pointer to the parameters for the registered 752 * callback. 753 * 754 * @return 755 * - On success, zero. 756 * - On failure, a negative value. 757 */ 758 extern int 759 rte_cryptodev_callback_register(uint8_t dev_id, 760 enum rte_cryptodev_event_type event, 761 rte_cryptodev_cb_fn cb_fn, void *cb_arg); 762 763 /** 764 * Unregister a callback function for specific device id. 765 * 766 * @param dev_id The device identifier. 767 * @param event Event interested. 768 * @param cb_fn User supplied callback function to be called. 769 * @param cb_arg Pointer to the parameters for the registered 770 * callback. 771 * 772 * @return 773 * - On success, zero. 774 * - On failure, a negative value. 775 */ 776 extern int 777 rte_cryptodev_callback_unregister(uint8_t dev_id, 778 enum rte_cryptodev_event_type event, 779 rte_cryptodev_cb_fn cb_fn, void *cb_arg); 780 781 782 typedef uint16_t (*dequeue_pkt_burst_t)(void *qp, 783 struct rte_crypto_op **ops, uint16_t nb_ops); 784 /**< Dequeue processed packets from queue pair of a device. */ 785 786 typedef uint16_t (*enqueue_pkt_burst_t)(void *qp, 787 struct rte_crypto_op **ops, uint16_t nb_ops); 788 /**< Enqueue packets for processing on queue pair of a device. */ 789 790 791 792 793 struct rte_cryptodev_callback; 794 795 /** Structure to keep track of registered callbacks */ 796 TAILQ_HEAD(rte_cryptodev_cb_list, rte_cryptodev_callback); 797 798 /** The data structure associated with each crypto device. */ 799 struct rte_cryptodev { 800 dequeue_pkt_burst_t dequeue_burst; 801 /**< Pointer to PMD receive function. */ 802 enqueue_pkt_burst_t enqueue_burst; 803 /**< Pointer to PMD transmit function. */ 804 805 struct rte_cryptodev_data *data; 806 /**< Pointer to device data */ 807 struct rte_cryptodev_ops *dev_ops; 808 /**< Functions exported by PMD */ 809 uint64_t feature_flags; 810 /**< Feature flags exposes HW/SW features for the given device */ 811 struct rte_device *device; 812 /**< Backing device */ 813 814 uint8_t driver_id; 815 /**< Crypto driver identifier*/ 816 817 struct rte_cryptodev_cb_list link_intr_cbs; 818 /**< User application callback for interrupts if present */ 819 820 void *security_ctx; 821 /**< Context for security ops */ 822 823 __extension__ 824 uint8_t attached : 1; 825 /**< Flag indicating the device is attached */ 826 } __rte_cache_aligned; 827 828 void * 829 rte_cryptodev_get_sec_ctx(uint8_t dev_id); 830 831 /** 832 * 833 * The data part, with no function pointers, associated with each device. 834 * 835 * This structure is safe to place in shared memory to be common among 836 * different processes in a multi-process configuration. 837 */ 838 struct rte_cryptodev_data { 839 uint8_t dev_id; 840 /**< Device ID for this instance */ 841 uint8_t socket_id; 842 /**< Socket ID where memory is allocated */ 843 char name[RTE_CRYPTODEV_NAME_MAX_LEN]; 844 /**< Unique identifier name */ 845 846 __extension__ 847 uint8_t dev_started : 1; 848 /**< Device state: STARTED(1)/STOPPED(0) */ 849 850 struct rte_mempool *session_pool; 851 /**< Session memory pool */ 852 void **queue_pairs; 853 /**< Array of pointers to queue pairs. */ 854 uint16_t nb_queue_pairs; 855 /**< Number of device queue pairs. */ 856 857 void *dev_private; 858 /**< PMD-specific private data */ 859 } __rte_cache_aligned; 860 861 extern struct rte_cryptodev *rte_cryptodevs; 862 /** 863 * 864 * Dequeue a burst of processed crypto operations from a queue on the crypto 865 * device. The dequeued operation are stored in *rte_crypto_op* structures 866 * whose pointers are supplied in the *ops* array. 867 * 868 * The rte_cryptodev_dequeue_burst() function returns the number of ops 869 * actually dequeued, which is the number of *rte_crypto_op* data structures 870 * effectively supplied into the *ops* array. 871 * 872 * A return value equal to *nb_ops* indicates that the queue contained 873 * at least *nb_ops* operations, and this is likely to signify that other 874 * processed operations remain in the devices output queue. Applications 875 * implementing a "retrieve as many processed operations as possible" policy 876 * can check this specific case and keep invoking the 877 * rte_cryptodev_dequeue_burst() function until a value less than 878 * *nb_ops* is returned. 879 * 880 * The rte_cryptodev_dequeue_burst() function does not provide any error 881 * notification to avoid the corresponding overhead. 882 * 883 * @param dev_id The symmetric crypto device identifier 884 * @param qp_id The index of the queue pair from which to 885 * retrieve processed packets. The value must be 886 * in the range [0, nb_queue_pair - 1] previously 887 * supplied to rte_cryptodev_configure(). 888 * @param ops The address of an array of pointers to 889 * *rte_crypto_op* structures that must be 890 * large enough to store *nb_ops* pointers in it. 891 * @param nb_ops The maximum number of operations to dequeue. 892 * 893 * @return 894 * - The number of operations actually dequeued, which is the number 895 * of pointers to *rte_crypto_op* structures effectively supplied to the 896 * *ops* array. 897 */ 898 static inline uint16_t 899 rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id, 900 struct rte_crypto_op **ops, uint16_t nb_ops) 901 { 902 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id]; 903 904 nb_ops = (*dev->dequeue_burst) 905 (dev->data->queue_pairs[qp_id], ops, nb_ops); 906 907 return nb_ops; 908 } 909 910 /** 911 * Enqueue a burst of operations for processing on a crypto device. 912 * 913 * The rte_cryptodev_enqueue_burst() function is invoked to place 914 * crypto operations on the queue *qp_id* of the device designated by 915 * its *dev_id*. 916 * 917 * The *nb_ops* parameter is the number of operations to process which are 918 * supplied in the *ops* array of *rte_crypto_op* structures. 919 * 920 * The rte_cryptodev_enqueue_burst() function returns the number of 921 * operations it actually enqueued for processing. A return value equal to 922 * *nb_ops* means that all packets have been enqueued. 923 * 924 * @param dev_id The identifier of the device. 925 * @param qp_id The index of the queue pair which packets are 926 * to be enqueued for processing. The value 927 * must be in the range [0, nb_queue_pairs - 1] 928 * previously supplied to 929 * *rte_cryptodev_configure*. 930 * @param ops The address of an array of *nb_ops* pointers 931 * to *rte_crypto_op* structures which contain 932 * the crypto operations to be processed. 933 * @param nb_ops The number of operations to process. 934 * 935 * @return 936 * The number of operations actually enqueued on the crypto device. The return 937 * value can be less than the value of the *nb_ops* parameter when the 938 * crypto devices queue is full or if invalid parameters are specified in 939 * a *rte_crypto_op*. 940 */ 941 static inline uint16_t 942 rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id, 943 struct rte_crypto_op **ops, uint16_t nb_ops) 944 { 945 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id]; 946 947 return (*dev->enqueue_burst)( 948 dev->data->queue_pairs[qp_id], ops, nb_ops); 949 } 950 951 952 /** Cryptodev symmetric crypto session 953 * Each session is derived from a fixed xform chain. Therefore each session 954 * has a fixed algo, key, op-type, digest_len etc. 955 */ 956 struct rte_cryptodev_sym_session { 957 __extension__ void *sess_private_data[0]; 958 /**< Private symmetric session material */ 959 }; 960 961 /** Cryptodev asymmetric crypto session */ 962 struct rte_cryptodev_asym_session { 963 __extension__ void *sess_private_data[0]; 964 /**< Private asymmetric session material */ 965 }; 966 967 /** 968 * Create symmetric crypto session header (generic with no private data) 969 * 970 * @param mempool Symmetric session mempool to allocate session 971 * objects from 972 * @return 973 * - On success return pointer to sym-session 974 * - On failure returns NULL 975 */ 976 struct rte_cryptodev_sym_session * 977 rte_cryptodev_sym_session_create(struct rte_mempool *mempool); 978 979 /** 980 * Create asymmetric crypto session header (generic with no private data) 981 * 982 * @param mempool mempool to allocate asymmetric session 983 * objects from 984 * @return 985 * - On success return pointer to asym-session 986 * - On failure returns NULL 987 */ 988 struct rte_cryptodev_asym_session * __rte_experimental 989 rte_cryptodev_asym_session_create(struct rte_mempool *mempool); 990 991 /** 992 * Frees symmetric crypto session header, after checking that all 993 * the device private data has been freed, returning it 994 * to its original mempool. 995 * 996 * @param sess Session header to be freed. 997 * 998 * @return 999 * - 0 if successful. 1000 * - -EINVAL if session is NULL. 1001 * - -EBUSY if not all device private data has been freed. 1002 */ 1003 int 1004 rte_cryptodev_sym_session_free(struct rte_cryptodev_sym_session *sess); 1005 1006 /** 1007 * Frees asymmetric crypto session header, after checking that all 1008 * the device private data has been freed, returning it 1009 * to its original mempool. 1010 * 1011 * @param sess Session header to be freed. 1012 * 1013 * @return 1014 * - 0 if successful. 1015 * - -EINVAL if session is NULL. 1016 * - -EBUSY if not all device private data has been freed. 1017 */ 1018 int __rte_experimental 1019 rte_cryptodev_asym_session_free(struct rte_cryptodev_asym_session *sess); 1020 1021 /** 1022 * Fill out private data for the device id, based on its device type. 1023 * 1024 * @param dev_id ID of device that we want the session to be used on 1025 * @param sess Session where the private data will be attached to 1026 * @param xforms Symmetric crypto transform operations to apply on flow 1027 * processed with this session 1028 * @param mempool Mempool where the private data is allocated. 1029 * 1030 * @return 1031 * - On success, zero. 1032 * - -EINVAL if input parameters are invalid. 1033 * - -ENOTSUP if crypto device does not support the crypto transform or 1034 * does not support symmetric operations. 1035 * - -ENOMEM if the private session could not be allocated. 1036 */ 1037 int 1038 rte_cryptodev_sym_session_init(uint8_t dev_id, 1039 struct rte_cryptodev_sym_session *sess, 1040 struct rte_crypto_sym_xform *xforms, 1041 struct rte_mempool *mempool); 1042 1043 /** 1044 * Initialize asymmetric session on a device with specific asymmetric xform 1045 * 1046 * @param dev_id ID of device that we want the session to be used on 1047 * @param sess Session to be set up on a device 1048 * @param xforms Asymmetric crypto transform operations to apply on flow 1049 * processed with this session 1050 * @param mempool Mempool to be used for internal allocation. 1051 * 1052 * @return 1053 * - On success, zero. 1054 * - -EINVAL if input parameters are invalid. 1055 * - -ENOTSUP if crypto device does not support the crypto transform. 1056 * - -ENOMEM if the private session could not be allocated. 1057 */ 1058 int __rte_experimental 1059 rte_cryptodev_asym_session_init(uint8_t dev_id, 1060 struct rte_cryptodev_asym_session *sess, 1061 struct rte_crypto_asym_xform *xforms, 1062 struct rte_mempool *mempool); 1063 1064 /** 1065 * Frees private data for the device id, based on its device type, 1066 * returning it to its mempool. It is the application's responsibility 1067 * to ensure that private session data is not cleared while there are 1068 * still in-flight operations using it. 1069 * 1070 * @param dev_id ID of device that uses the session. 1071 * @param sess Session containing the reference to the private data 1072 * 1073 * @return 1074 * - 0 if successful. 1075 * - -EINVAL if device is invalid or session is NULL. 1076 * - -ENOTSUP if crypto device does not support symmetric operations. 1077 */ 1078 int 1079 rte_cryptodev_sym_session_clear(uint8_t dev_id, 1080 struct rte_cryptodev_sym_session *sess); 1081 1082 /** 1083 * Frees resources held by asymmetric session during rte_cryptodev_session_init 1084 * 1085 * @param dev_id ID of device that uses the asymmetric session. 1086 * @param sess Asymmetric session setup on device using 1087 * rte_cryptodev_session_init 1088 * @return 1089 * - 0 if successful. 1090 * - -EINVAL if device is invalid or session is NULL. 1091 */ 1092 int __rte_experimental 1093 rte_cryptodev_asym_session_clear(uint8_t dev_id, 1094 struct rte_cryptodev_asym_session *sess); 1095 1096 /** 1097 * Get the size of the header session, for all registered drivers. 1098 * 1099 * @return 1100 * Size of the symmetric eader session. 1101 */ 1102 unsigned int 1103 rte_cryptodev_sym_get_header_session_size(void); 1104 1105 /** 1106 * Get the size of the asymmetric session header, for all registered drivers. 1107 * 1108 * @return 1109 * Size of the asymmetric header session. 1110 */ 1111 unsigned int __rte_experimental 1112 rte_cryptodev_asym_get_header_session_size(void); 1113 1114 /** 1115 * Get the size of the private symmetric session data 1116 * for a device. 1117 * 1118 * @param dev_id The device identifier. 1119 * 1120 * @return 1121 * - Size of the private data, if successful 1122 * - 0 if device is invalid or does not have private 1123 * symmetric session 1124 */ 1125 unsigned int 1126 rte_cryptodev_sym_get_private_session_size(uint8_t dev_id); 1127 1128 /** 1129 * Get the size of the private data for asymmetric session 1130 * on device 1131 * 1132 * @param dev_id The device identifier. 1133 * 1134 * @return 1135 * - Size of the asymmetric private data, if successful 1136 * - 0 if device is invalid or does not have private session 1137 */ 1138 unsigned int __rte_experimental 1139 rte_cryptodev_asym_get_private_session_size(uint8_t dev_id); 1140 1141 /** 1142 * Provide driver identifier. 1143 * 1144 * @param name 1145 * The pointer to a driver name. 1146 * @return 1147 * The driver type identifier or -1 if no driver found 1148 */ 1149 int rte_cryptodev_driver_id_get(const char *name); 1150 1151 /** 1152 * Provide driver name. 1153 * 1154 * @param driver_id 1155 * The driver identifier. 1156 * @return 1157 * The driver name or null if no driver found 1158 */ 1159 const char *rte_cryptodev_driver_name_get(uint8_t driver_id); 1160 1161 /** 1162 * Store user data in a session. 1163 * 1164 * @param sess Session pointer allocated by 1165 * *rte_cryptodev_sym_session_create*. 1166 * @param data Pointer to the user data. 1167 * @param size Size of the user data. 1168 * 1169 * @return 1170 * - On success, zero. 1171 * - On failure, a negative value. 1172 */ 1173 int __rte_experimental 1174 rte_cryptodev_sym_session_set_user_data( 1175 struct rte_cryptodev_sym_session *sess, 1176 void *data, 1177 uint16_t size); 1178 1179 /** 1180 * Get user data stored in a session. 1181 * 1182 * @param sess Session pointer allocated by 1183 * *rte_cryptodev_sym_session_create*. 1184 * 1185 * @return 1186 * - On success return pointer to user data. 1187 * - On failure returns NULL. 1188 */ 1189 void * __rte_experimental 1190 rte_cryptodev_sym_session_get_user_data( 1191 struct rte_cryptodev_sym_session *sess); 1192 1193 #ifdef __cplusplus 1194 } 1195 #endif 1196 1197 #endif /* _RTE_CRYPTODEV_H_ */ 1198