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