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