1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2015-2020 Intel Corporation. 3 */ 4 5 #ifndef _CRYPTODEV_PMD_H_ 6 #define _CRYPTODEV_PMD_H_ 7 8 #ifdef __cplusplus 9 extern "C" { 10 #endif 11 12 /** @file 13 * RTE Crypto PMD APIs 14 * 15 * @note 16 * These API are from crypto PMD only and user applications should not call 17 * them directly. 18 */ 19 20 #include <string.h> 21 22 #include <dev_driver.h> 23 #include <rte_compat.h> 24 #include <rte_malloc.h> 25 #include <rte_log.h> 26 #include <rte_common.h> 27 28 #include "rte_crypto.h" 29 #include "rte_cryptodev.h" 30 31 32 #define RTE_CRYPTODEV_PMD_DEFAULT_MAX_NB_QUEUE_PAIRS 8 33 34 #define RTE_CRYPTODEV_PMD_NAME_ARG ("name") 35 #define RTE_CRYPTODEV_PMD_MAX_NB_QP_ARG ("max_nb_queue_pairs") 36 #define RTE_CRYPTODEV_PMD_SOCKET_ID_ARG ("socket_id") 37 38 39 static const char * const cryptodev_pmd_valid_params[] = { 40 RTE_CRYPTODEV_PMD_NAME_ARG, 41 RTE_CRYPTODEV_PMD_MAX_NB_QP_ARG, 42 RTE_CRYPTODEV_PMD_SOCKET_ID_ARG, 43 NULL 44 }; 45 46 /** 47 * @internal 48 * Initialisation parameters for crypto devices 49 */ 50 struct rte_cryptodev_pmd_init_params { 51 char name[RTE_CRYPTODEV_NAME_MAX_LEN]; 52 size_t private_data_size; 53 int socket_id; 54 unsigned int max_nb_queue_pairs; 55 }; 56 57 /** 58 * @internal 59 * The data part, with no function pointers, associated with each device. 60 * 61 * This structure is safe to place in shared memory to be common among 62 * different processes in a multi-process configuration. 63 */ 64 struct __rte_cache_aligned rte_cryptodev_data { 65 /** Device ID for this instance */ 66 uint8_t dev_id; 67 /** Socket ID where memory is allocated */ 68 int socket_id; 69 /** Unique identifier name */ 70 char name[RTE_CRYPTODEV_NAME_MAX_LEN]; 71 72 __extension__ 73 /** Device state: STARTED(1)/STOPPED(0) */ 74 uint8_t dev_started : 1; 75 76 /** Session memory pool */ 77 struct rte_mempool *session_pool; 78 /** Array of pointers to queue pairs. */ 79 void **queue_pairs; 80 /** Number of device queue pairs. */ 81 uint16_t nb_queue_pairs; 82 83 /** PMD-specific private data */ 84 void *dev_private; 85 }; 86 87 /** @internal The data structure associated with each crypto device. */ 88 struct __rte_cache_aligned rte_cryptodev { 89 /** Pointer to PMD dequeue function. */ 90 dequeue_pkt_burst_t dequeue_burst; 91 /** Pointer to PMD enqueue function. */ 92 enqueue_pkt_burst_t enqueue_burst; 93 94 /** Pointer to device data */ 95 struct rte_cryptodev_data *data; 96 /** Functions exported by PMD */ 97 struct rte_cryptodev_ops *dev_ops; 98 /** Feature flags exposes HW/SW features for the given device */ 99 uint64_t feature_flags; 100 /** Backing device */ 101 struct rte_device *device; 102 103 /** Crypto driver identifier*/ 104 uint8_t driver_id; 105 106 /** User application callback for interrupts if present */ 107 struct rte_cryptodev_cb_list link_intr_cbs; 108 109 /** Context for security ops */ 110 void *security_ctx; 111 112 __extension__ 113 /** Flag indicating the device is attached */ 114 uint8_t attached : 1; 115 116 /** User application callback for pre enqueue processing */ 117 struct rte_cryptodev_cb_rcu *enq_cbs; 118 /** User application callback for post dequeue processing */ 119 struct rte_cryptodev_cb_rcu *deq_cbs; 120 /** Pointer to PMD function to get used queue pair depth */ 121 crypto_qp_depth_used_t qp_depth_used; 122 }; 123 124 /** Global structure used for maintaining state of allocated crypto devices */ 125 struct rte_cryptodev_global { 126 struct rte_cryptodev *devs; /**< Device information array */ 127 struct rte_cryptodev_data *data[RTE_CRYPTO_MAX_DEVS]; 128 /**< Device private data */ 129 uint8_t nb_devs; /**< Number of devices found */ 130 }; 131 132 /* Cryptodev driver, containing the driver ID */ 133 struct cryptodev_driver { 134 RTE_TAILQ_ENTRY(cryptodev_driver) next; /**< Next in list. */ 135 const struct rte_driver *driver; 136 uint8_t id; 137 }; 138 139 /** Cryptodev symmetric crypto session 140 * Each session is derived from a fixed xform chain. Therefore each session 141 * has a fixed algo, key, op-type, digest_len etc. 142 */ 143 struct rte_cryptodev_sym_session { 144 RTE_MARKER cacheline0; 145 uint64_t opaque_data; 146 /**< Can be used for external metadata */ 147 uint32_t sess_data_sz; 148 /**< Pointer to the user data stored after sess data */ 149 uint16_t user_data_sz; 150 /**< Session user data will be placed after sess data */ 151 uint8_t driver_id; 152 /**< Driver id to get the session priv */ 153 rte_iova_t driver_priv_data_iova; 154 /**< Session driver data IOVA address */ 155 156 alignas(RTE_CACHE_LINE_MIN_SIZE) RTE_MARKER cacheline1; 157 /**< Second cache line - start of the driver session data */ 158 uint8_t driver_priv_data[]; 159 /**< Driver specific session data, variable size */ 160 }; 161 162 /** 163 * Helper macro to get driver private data 164 */ 165 #define CRYPTODEV_GET_SYM_SESS_PRIV(s) \ 166 ((void *)(((struct rte_cryptodev_sym_session *)s)->driver_priv_data)) 167 #define CRYPTODEV_GET_SYM_SESS_PRIV_IOVA(s) \ 168 (((struct rte_cryptodev_sym_session *)s)->driver_priv_data_iova) 169 170 171 /** 172 * Get the rte_cryptodev structure device pointer for the device. Assumes a 173 * valid device index. 174 * 175 * @param dev_id Device ID value to select the device structure. 176 * 177 * @return 178 * - The rte_cryptodev structure pointer for the given device ID. 179 */ 180 __rte_internal 181 struct rte_cryptodev * 182 rte_cryptodev_pmd_get_dev(uint8_t dev_id); 183 184 /** 185 * Get the rte_cryptodev structure device pointer for the named device. 186 * 187 * @param name device name to select the device structure. 188 * 189 * @return 190 * - The rte_cryptodev structure pointer for the given device ID. 191 */ 192 __rte_internal 193 struct rte_cryptodev * 194 rte_cryptodev_pmd_get_named_dev(const char *name); 195 196 /** 197 * Definitions of all functions exported by a driver through the 198 * generic structure of type *crypto_dev_ops* supplied in the 199 * *rte_cryptodev* structure associated with a device. 200 */ 201 202 /** 203 * Function used to configure device. 204 * 205 * @param dev Crypto device pointer 206 * @param config Crypto device configurations 207 * 208 * @return Returns 0 on success 209 */ 210 typedef int (*cryptodev_configure_t)(struct rte_cryptodev *dev, 211 struct rte_cryptodev_config *config); 212 213 /** 214 * Function used to start a configured device. 215 * 216 * @param dev Crypto device pointer 217 * 218 * @return Returns 0 on success 219 */ 220 typedef int (*cryptodev_start_t)(struct rte_cryptodev *dev); 221 222 /** 223 * Function used to stop a configured device. 224 * 225 * @param dev Crypto device pointer 226 */ 227 typedef void (*cryptodev_stop_t)(struct rte_cryptodev *dev); 228 229 /** 230 * Function used to close a configured device. 231 * 232 * @param dev Crypto device pointer 233 * @return 234 * - 0 on success. 235 * - EAGAIN if can't close as device is busy 236 */ 237 typedef int (*cryptodev_close_t)(struct rte_cryptodev *dev); 238 239 240 /** 241 * Function used to get statistics of a device. 242 * 243 * @param dev Crypto device pointer 244 * @param stats Pointer to crypto device stats structure to populate 245 */ 246 typedef void (*cryptodev_stats_get_t)(struct rte_cryptodev *dev, 247 struct rte_cryptodev_stats *stats); 248 249 250 /** 251 * Function used to reset statistics of a device. 252 * 253 * @param dev Crypto device pointer 254 */ 255 typedef void (*cryptodev_stats_reset_t)(struct rte_cryptodev *dev); 256 257 258 /** 259 * Function used to get specific information of a device. 260 * 261 * @param dev Crypto device pointer 262 * @param dev_info Pointer to infos structure to populate 263 */ 264 typedef void (*cryptodev_info_get_t)(struct rte_cryptodev *dev, 265 struct rte_cryptodev_info *dev_info); 266 267 /** 268 * Setup a queue pair for a device. 269 * 270 * @param dev Crypto device pointer 271 * @param qp_id Queue Pair Index 272 * @param qp_conf Queue configuration structure 273 * @param socket_id Socket Index 274 * 275 * @return Returns 0 on success. 276 */ 277 typedef int (*cryptodev_queue_pair_setup_t)(struct rte_cryptodev *dev, 278 uint16_t qp_id, const struct rte_cryptodev_qp_conf *qp_conf, 279 int socket_id); 280 281 /** 282 * Release memory resources allocated by given queue pair. 283 * 284 * @param dev Crypto device pointer 285 * @param qp_id Queue Pair Index 286 * 287 * @return 288 * - 0 on success. 289 * - EAGAIN if can't close as device is busy 290 */ 291 typedef int (*cryptodev_queue_pair_release_t)(struct rte_cryptodev *dev, 292 uint16_t qp_id); 293 294 /** 295 * Create a session mempool to allocate sessions from 296 * 297 * @param dev Crypto device pointer 298 * @param nb_objs number of sessions objects in mempool 299 * @param obj_cache_size l-core object cache size, see *rte_ring_create* 300 * @param socket_id Socket Id to allocate mempool on. 301 * 302 * @return 303 * - On success returns a pointer to a rte_mempool 304 * - On failure returns a NULL pointer 305 */ 306 typedef int (*cryptodev_sym_create_session_pool_t)( 307 struct rte_cryptodev *dev, unsigned nb_objs, 308 unsigned obj_cache_size, int socket_id); 309 310 311 /** 312 * Get the size of a cryptodev session 313 * 314 * @param dev Crypto device pointer 315 * 316 * @return 317 * - On success returns the size of the session structure for device 318 * - On failure returns 0 319 */ 320 typedef unsigned (*cryptodev_sym_get_session_private_size_t)( 321 struct rte_cryptodev *dev); 322 /** 323 * Get the size of a asymmetric cryptodev session 324 * 325 * @param dev Crypto device pointer 326 * 327 * @return 328 * - On success returns the size of the session structure for device 329 * - On failure returns 0 330 */ 331 typedef unsigned int (*cryptodev_asym_get_session_private_size_t)( 332 struct rte_cryptodev *dev); 333 334 /** 335 * Configure a Crypto session on a device. 336 * 337 * @param dev Crypto device pointer 338 * @param xform Single or chain of crypto xforms 339 * @param session Pointer to cryptodev's private session structure 340 * 341 * @return 342 * - Returns 0 if private session structure have been created successfully. 343 * - Returns -EINVAL if input parameters are invalid. 344 * - Returns -ENOTSUP if crypto device does not support the crypto transform. 345 * - Returns -ENOMEM if the private session could not be allocated. 346 */ 347 typedef int (*cryptodev_sym_configure_session_t)(struct rte_cryptodev *dev, 348 struct rte_crypto_sym_xform *xform, 349 struct rte_cryptodev_sym_session *session); 350 351 /** 352 * Configure a Crypto asymmetric session on a device. 353 * 354 * @param dev Crypto device pointer 355 * @param xform Single or chain of crypto xforms 356 * @param session Pointer to cryptodev's private session structure 357 * 358 * @return 359 * - Returns 0 if private session structure have been created successfully. 360 * - Returns -EINVAL if input parameters are invalid. 361 * - Returns -ENOTSUP if crypto device does not support the crypto transform. 362 * - Returns -ENOMEM if the private session could not be allocated. 363 */ 364 typedef int (*cryptodev_asym_configure_session_t)(struct rte_cryptodev *dev, 365 struct rte_crypto_asym_xform *xform, 366 struct rte_cryptodev_asym_session *session); 367 /** 368 * Free driver private session data. 369 * 370 * @param dev Crypto device pointer 371 * @param sess Cryptodev session structure 372 */ 373 typedef void (*cryptodev_sym_free_session_t)(struct rte_cryptodev *dev, 374 struct rte_cryptodev_sym_session *sess); 375 376 /** 377 * Clear asymmetric session private data. 378 * 379 * @param dev Crypto device pointer 380 * @param sess Cryptodev session structure 381 */ 382 typedef void (*cryptodev_asym_clear_session_t)(struct rte_cryptodev *dev, 383 struct rte_cryptodev_asym_session *sess); 384 /** 385 * Perform actual crypto processing (encrypt/digest or auth/decrypt) 386 * on user provided data. 387 * 388 * @param dev Crypto device pointer 389 * @param sess Cryptodev session structure 390 * @param ofs Start and stop offsets for auth and cipher operations 391 * @param vec Vectorized operation descriptor 392 * 393 * @return 394 * - Returns number of successfully processed packets. 395 */ 396 typedef uint32_t (*cryptodev_sym_cpu_crypto_process_t) 397 (struct rte_cryptodev *dev, struct rte_cryptodev_sym_session *sess, 398 union rte_crypto_sym_ofs ofs, struct rte_crypto_sym_vec *vec); 399 400 /** 401 * Typedef that the driver provided to get service context private date size. 402 * 403 * @param dev Crypto device pointer. 404 * 405 * @return 406 * - On success return the size of the device's service context private data. 407 * - On failure return negative integer. 408 */ 409 typedef int (*cryptodev_sym_get_raw_dp_ctx_size_t)(struct rte_cryptodev *dev); 410 411 /** 412 * Typedef that the driver provided to configure raw data-path context. 413 * 414 * @param dev Crypto device pointer. 415 * @param qp_id Crypto device queue pair index. 416 * @param ctx The raw data-path context data. 417 * @param sess_type session type. 418 * @param session_ctx Session context data. If NULL the driver 419 * shall only configure the drv_ctx_data in 420 * ctx buffer. Otherwise the driver shall only 421 * parse the session_ctx to set appropriate 422 * function pointers in ctx. 423 * @param is_update Set 0 if it is to initialize the ctx. 424 * Set 1 if ctx is initialized and only to update 425 * session context data. 426 * @return 427 * - On success return 0. 428 * - On failure return negative integer. 429 */ 430 typedef int (*cryptodev_sym_configure_raw_dp_ctx_t)( 431 struct rte_cryptodev *dev, uint16_t qp_id, 432 struct rte_crypto_raw_dp_ctx *ctx, 433 enum rte_crypto_op_sess_type sess_type, 434 union rte_cryptodev_session_ctx session_ctx, uint8_t is_update); 435 436 /** 437 * Typedef that the driver provided to set event crypto meta data. 438 * 439 * @param dev Crypto device pointer. 440 * @param sess Crypto or security session. 441 * @param op_type Operation type. 442 * @param sess_type Session type. 443 * @param ev_mdata Pointer to the event crypto meta data 444 * (aka *union rte_event_crypto_metadata*) 445 * @return 446 * - On success return 0. 447 * - On failure return negative integer. 448 */ 449 typedef int (*cryptodev_session_event_mdata_set_t)( 450 struct rte_cryptodev *dev, void *sess, 451 enum rte_crypto_op_type op_type, 452 enum rte_crypto_op_sess_type sess_type, 453 void *ev_mdata); 454 455 /** 456 * @internal Query queue pair error interrupt event. 457 * @see rte_cryptodev_queue_pair_event_error_query() 458 */ 459 typedef int (*cryptodev_queue_pair_event_error_query_t)(struct rte_cryptodev *dev, 460 uint16_t qp_id); 461 462 /** Crypto device operations function pointer table */ 463 struct rte_cryptodev_ops { 464 cryptodev_configure_t dev_configure; /**< Configure device. */ 465 cryptodev_start_t dev_start; /**< Start device. */ 466 cryptodev_stop_t dev_stop; /**< Stop device. */ 467 cryptodev_close_t dev_close; /**< Close device. */ 468 469 cryptodev_info_get_t dev_infos_get; /**< Get device info. */ 470 471 cryptodev_stats_get_t stats_get; 472 /**< Get device statistics. */ 473 cryptodev_stats_reset_t stats_reset; 474 /**< Reset device statistics. */ 475 476 cryptodev_queue_pair_setup_t queue_pair_setup; 477 /**< Set up a device queue pair. */ 478 cryptodev_queue_pair_release_t queue_pair_release; 479 /**< Release a queue pair. */ 480 481 cryptodev_sym_get_session_private_size_t sym_session_get_size; 482 /**< Return private session. */ 483 cryptodev_asym_get_session_private_size_t asym_session_get_size; 484 /**< Return asym session private size. */ 485 cryptodev_sym_configure_session_t sym_session_configure; 486 /**< Configure a Crypto session. */ 487 cryptodev_asym_configure_session_t asym_session_configure; 488 /**< Configure asymmetric Crypto session. */ 489 cryptodev_sym_free_session_t sym_session_clear; 490 /**< Clear a Crypto sessions private data. */ 491 cryptodev_asym_clear_session_t asym_session_clear; 492 /**< Clear a Crypto sessions private data. */ 493 union { 494 cryptodev_sym_cpu_crypto_process_t sym_cpu_process; 495 /**< process input data synchronously (cpu-crypto). */ 496 __extension__ 497 struct { 498 cryptodev_sym_get_raw_dp_ctx_size_t 499 sym_get_raw_dp_ctx_size; 500 /**< Get raw data path service context data size. */ 501 cryptodev_sym_configure_raw_dp_ctx_t 502 sym_configure_raw_dp_ctx; 503 /**< Initialize raw data path context data. */ 504 }; 505 }; 506 cryptodev_session_event_mdata_set_t session_ev_mdata_set; 507 /**< Set a Crypto or Security session even meta data. */ 508 cryptodev_queue_pair_event_error_query_t queue_pair_event_error_query; 509 /**< Query queue error interrupt event */ 510 }; 511 512 513 /** 514 * Function for internal use by dummy drivers primarily, e.g. ring-based 515 * driver. 516 * Allocates a new cryptodev slot for an crypto device and returns the pointer 517 * to that slot for the driver to use. 518 * 519 * @param name Unique identifier name for each device 520 * @param socket_id Socket to allocate resources on. 521 * @return 522 * - Slot in the rte_dev_devices array for a new device; 523 */ 524 __rte_internal 525 struct rte_cryptodev * 526 rte_cryptodev_pmd_allocate(const char *name, int socket_id); 527 528 /** 529 * Function for internal use by dummy drivers primarily, e.g. ring-based 530 * driver. 531 * Release the specified cryptodev device. 532 * 533 * @param cryptodev 534 * The *cryptodev* pointer is the address of the *rte_cryptodev* structure. 535 * @return 536 * - 0 on success, negative on error 537 */ 538 __rte_internal 539 int 540 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev); 541 542 543 /** 544 * @internal 545 * 546 * PMD assist function to parse initialisation arguments for crypto driver 547 * when creating a new crypto PMD device instance. 548 * 549 * PMD should set default values for that PMD before calling function, 550 * these default values will be over-written with successfully parsed values 551 * from args string. 552 * 553 * @param params parsed PMD initialisation parameters 554 * @param args input argument string to parse 555 * 556 * @return 557 * - 0 on success 558 * - errno on failure 559 */ 560 __rte_internal 561 int 562 rte_cryptodev_pmd_parse_input_args( 563 struct rte_cryptodev_pmd_init_params *params, 564 const char *args); 565 566 /** 567 * @internal 568 * 569 * PMD assist function to provide boiler plate code for crypto driver to create 570 * and allocate resources for a new crypto PMD device instance. 571 * 572 * @param name crypto device name. 573 * @param device base device instance 574 * @param params PMD initialisation parameters 575 * 576 * @return 577 * - crypto device instance on success 578 * - NULL on creation failure 579 */ 580 __rte_internal 581 struct rte_cryptodev * 582 rte_cryptodev_pmd_create(const char *name, 583 struct rte_device *device, 584 struct rte_cryptodev_pmd_init_params *params); 585 586 /** 587 * @internal 588 * 589 * PMD assist function to provide boiler plate code for crypto driver to 590 * destroy and free resources associated with a crypto PMD device instance. 591 * 592 * @param cryptodev crypto device handle. 593 * 594 * @return 595 * - 0 on success 596 * - errno on failure 597 */ 598 __rte_internal 599 int 600 rte_cryptodev_pmd_destroy(struct rte_cryptodev *cryptodev); 601 602 /** 603 * Executes all the user application registered callbacks for the specific 604 * device. 605 * * 606 * @param dev Pointer to cryptodev struct 607 * @param event Crypto device interrupt event type. 608 * 609 * @return 610 * void 611 */ 612 __rte_internal 613 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev, 614 enum rte_cryptodev_event_type event); 615 616 /** 617 * @internal 618 * Create unique device name 619 */ 620 __rte_internal 621 int 622 rte_cryptodev_pmd_create_dev_name(char *name, const char *dev_name_prefix); 623 624 /** 625 * @internal 626 * Allocate Cryptodev driver. 627 * 628 * @param crypto_drv 629 * Pointer to cryptodev_driver. 630 * @param drv 631 * Pointer to rte_driver. 632 * 633 * @return 634 * The driver type identifier 635 */ 636 __rte_internal 637 uint8_t rte_cryptodev_allocate_driver(struct cryptodev_driver *crypto_drv, 638 const struct rte_driver *drv); 639 640 /** 641 * @internal 642 * This is the last step of device probing. It must be called after a 643 * cryptodev is allocated and initialized successfully. 644 * 645 * @param dev Pointer to cryptodev struct 646 * 647 * @return 648 * void 649 */ 650 __rte_internal 651 void 652 rte_cryptodev_pmd_probing_finish(struct rte_cryptodev *dev); 653 654 #define RTE_PMD_REGISTER_CRYPTO_DRIVER(crypto_drv, drv, driver_id)\ 655 RTE_INIT(init_ ##driver_id)\ 656 {\ 657 driver_id = rte_cryptodev_allocate_driver(&crypto_drv, &(drv));\ 658 } 659 660 /* Reset crypto device fastpath APIs to dummy values. */ 661 __rte_internal 662 void 663 cryptodev_fp_ops_reset(struct rte_crypto_fp_ops *fp_ops); 664 665 /* Setup crypto device fastpath APIs. */ 666 __rte_internal 667 void 668 cryptodev_fp_ops_set(struct rte_crypto_fp_ops *fp_ops, 669 const struct rte_cryptodev *dev); 670 671 /** 672 * Get session event meta data (aka *union rte_event_crypto_metadata*) 673 * 674 * @param op pointer to *rte_crypto_op* structure. 675 * 676 * @return 677 * - On success, pointer to event crypto metadata 678 * - On failure, NULL. 679 */ 680 __rte_internal 681 void * 682 rte_cryptodev_session_event_mdata_get(struct rte_crypto_op *op); 683 684 /** 685 * @internal 686 * Cryptodev asymmetric crypto session. 687 */ 688 struct rte_cryptodev_asym_session { 689 uint8_t driver_id; 690 /**< Session driver ID. */ 691 uint16_t max_priv_data_sz; 692 /**< Size of private data used when creating mempool */ 693 uint16_t user_data_sz; 694 /**< Session user data will be placed after sess_data */ 695 uint8_t padding[3]; 696 void *event_mdata; 697 /**< Event metadata (aka *union rte_event_crypto_metadata*) */ 698 uint8_t sess_private_data[]; 699 }; 700 701 #ifdef __cplusplus 702 } 703 #endif 704 705 #endif /* _CRYPTODEV_PMD_H_ */ 706