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_cryptodev_data { 65 /** Device ID for this instance */ 66 uint8_t dev_id; 67 /** Socket ID where memory is allocated */ 68 uint8_t 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 } __rte_cache_aligned; 86 87 /** @internal The data structure associated with each crypto device. */ 88 struct 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 } __rte_cache_aligned; 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 RTE_MARKER cacheline1 __rte_cache_min_aligned; 155 /**< Second cache line - start of the driver session data */ 156 uint8_t driver_priv_data[0]; 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 */ 395 typedef uint32_t (*cryptodev_sym_cpu_crypto_process_t) 396 (struct rte_cryptodev *dev, struct rte_cryptodev_sym_session *sess, 397 union rte_crypto_sym_ofs ofs, struct rte_crypto_sym_vec *vec); 398 399 /** 400 * Typedef that the driver provided to get service context private date size. 401 * 402 * @param dev Crypto device pointer. 403 * 404 * @return 405 * - On success return the size of the device's service context private data. 406 * - On failure return negative integer. 407 */ 408 typedef int (*cryptodev_sym_get_raw_dp_ctx_size_t)(struct rte_cryptodev *dev); 409 410 /** 411 * Typedef that the driver provided to configure raw data-path context. 412 * 413 * @param dev Crypto device pointer. 414 * @param qp_id Crypto device queue pair index. 415 * @param ctx The raw data-path context data. 416 * @param sess_type session type. 417 * @param session_ctx Session context data. If NULL the driver 418 * shall only configure the drv_ctx_data in 419 * ctx buffer. Otherwise the driver shall only 420 * parse the session_ctx to set appropriate 421 * function pointers in ctx. 422 * @param is_update Set 0 if it is to initialize the ctx. 423 * Set 1 if ctx is initialized and only to update 424 * session context data. 425 * @return 426 * - On success return 0. 427 * - On failure return negative integer. 428 */ 429 typedef int (*cryptodev_sym_configure_raw_dp_ctx_t)( 430 struct rte_cryptodev *dev, uint16_t qp_id, 431 struct rte_crypto_raw_dp_ctx *ctx, 432 enum rte_crypto_op_sess_type sess_type, 433 union rte_cryptodev_session_ctx session_ctx, uint8_t is_update); 434 435 /** 436 * Typedef that the driver provided to set event crypto meta data. 437 * 438 * @param dev Crypto device pointer. 439 * @param sess Crypto or security session. 440 * @param op_type Operation type. 441 * @param sess_type Session type. 442 * @param ev_mdata Pointer to the event crypto meta data 443 * (aka *union rte_event_crypto_metadata*) 444 * @return 445 * - On success return 0. 446 * - On failure return negative integer. 447 */ 448 typedef int (*cryptodev_session_event_mdata_set_t)( 449 struct rte_cryptodev *dev, void *sess, 450 enum rte_crypto_op_type op_type, 451 enum rte_crypto_op_sess_type sess_type, 452 void *ev_mdata); 453 454 /** 455 * @internal Query queue pair error interrupt event. 456 * @see rte_cryptodev_queue_pair_event_error_query() 457 */ 458 typedef int (*cryptodev_queue_pair_event_error_query_t)(struct rte_cryptodev *dev, 459 uint16_t qp_id); 460 461 /** Crypto device operations function pointer table */ 462 struct rte_cryptodev_ops { 463 cryptodev_configure_t dev_configure; /**< Configure device. */ 464 cryptodev_start_t dev_start; /**< Start device. */ 465 cryptodev_stop_t dev_stop; /**< Stop device. */ 466 cryptodev_close_t dev_close; /**< Close device. */ 467 468 cryptodev_info_get_t dev_infos_get; /**< Get device info. */ 469 470 cryptodev_stats_get_t stats_get; 471 /**< Get device statistics. */ 472 cryptodev_stats_reset_t stats_reset; 473 /**< Reset device statistics. */ 474 475 cryptodev_queue_pair_setup_t queue_pair_setup; 476 /**< Set up a device queue pair. */ 477 cryptodev_queue_pair_release_t queue_pair_release; 478 /**< Release a queue pair. */ 479 480 cryptodev_sym_get_session_private_size_t sym_session_get_size; 481 /**< Return private session. */ 482 cryptodev_asym_get_session_private_size_t asym_session_get_size; 483 /**< Return asym session private size. */ 484 cryptodev_sym_configure_session_t sym_session_configure; 485 /**< Configure a Crypto session. */ 486 cryptodev_asym_configure_session_t asym_session_configure; 487 /**< Configure asymmetric Crypto session. */ 488 cryptodev_sym_free_session_t sym_session_clear; 489 /**< Clear a Crypto sessions private data. */ 490 cryptodev_asym_clear_session_t asym_session_clear; 491 /**< Clear a Crypto sessions private data. */ 492 union { 493 cryptodev_sym_cpu_crypto_process_t sym_cpu_process; 494 /**< process input data synchronously (cpu-crypto). */ 495 __extension__ 496 struct { 497 cryptodev_sym_get_raw_dp_ctx_size_t 498 sym_get_raw_dp_ctx_size; 499 /**< Get raw data path service context data size. */ 500 cryptodev_sym_configure_raw_dp_ctx_t 501 sym_configure_raw_dp_ctx; 502 /**< Initialize raw data path context data. */ 503 }; 504 }; 505 cryptodev_session_event_mdata_set_t session_ev_mdata_set; 506 /**< Set a Crypto or Security session even meta data. */ 507 cryptodev_queue_pair_event_error_query_t queue_pair_event_error_query; 508 /**< Query queue error interrupt event */ 509 }; 510 511 512 /** 513 * Function for internal use by dummy drivers primarily, e.g. ring-based 514 * driver. 515 * Allocates a new cryptodev slot for an crypto device and returns the pointer 516 * to that slot for the driver to use. 517 * 518 * @param name Unique identifier name for each device 519 * @param socket_id Socket to allocate resources on. 520 * @return 521 * - Slot in the rte_dev_devices array for a new device; 522 */ 523 __rte_internal 524 struct rte_cryptodev * 525 rte_cryptodev_pmd_allocate(const char *name, int socket_id); 526 527 /** 528 * Function for internal use by dummy drivers primarily, e.g. ring-based 529 * driver. 530 * Release the specified cryptodev device. 531 * 532 * @param cryptodev 533 * The *cryptodev* pointer is the address of the *rte_cryptodev* structure. 534 * @return 535 * - 0 on success, negative on error 536 */ 537 __rte_internal 538 extern int 539 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev); 540 541 542 /** 543 * @internal 544 * 545 * PMD assist function to parse initialisation arguments for crypto driver 546 * when creating a new crypto PMD device instance. 547 * 548 * PMD should set default values for that PMD before calling function, 549 * these default values will be over-written with successfully parsed values 550 * from args string. 551 * 552 * @param params parsed PMD initialisation parameters 553 * @param args input argument string to parse 554 * 555 * @return 556 * - 0 on success 557 * - errno on failure 558 */ 559 __rte_internal 560 int 561 rte_cryptodev_pmd_parse_input_args( 562 struct rte_cryptodev_pmd_init_params *params, 563 const char *args); 564 565 /** 566 * @internal 567 * 568 * PMD assist function to provide boiler plate code for crypto driver to create 569 * and allocate resources for a new crypto PMD device instance. 570 * 571 * @param name crypto device name. 572 * @param device base device instance 573 * @param params PMD initialisation parameters 574 * 575 * @return 576 * - crypto device instance on success 577 * - NULL on creation failure 578 */ 579 __rte_internal 580 struct rte_cryptodev * 581 rte_cryptodev_pmd_create(const char *name, 582 struct rte_device *device, 583 struct rte_cryptodev_pmd_init_params *params); 584 585 /** 586 * @internal 587 * 588 * PMD assist function to provide boiler plate code for crypto driver to 589 * destroy and free resources associated with a crypto PMD device instance. 590 * 591 * @param cryptodev crypto device handle. 592 * 593 * @return 594 * - 0 on success 595 * - errno on failure 596 */ 597 __rte_internal 598 int 599 rte_cryptodev_pmd_destroy(struct rte_cryptodev *cryptodev); 600 601 /** 602 * Executes all the user application registered callbacks for the specific 603 * device. 604 * * 605 * @param dev Pointer to cryptodev struct 606 * @param event Crypto device interrupt event type. 607 * 608 * @return 609 * void 610 */ 611 __rte_internal 612 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev, 613 enum rte_cryptodev_event_type event); 614 615 /** 616 * @internal 617 * Create unique device name 618 */ 619 __rte_internal 620 int 621 rte_cryptodev_pmd_create_dev_name(char *name, const char *dev_name_prefix); 622 623 /** 624 * @internal 625 * Allocate Cryptodev driver. 626 * 627 * @param crypto_drv 628 * Pointer to cryptodev_driver. 629 * @param drv 630 * Pointer to rte_driver. 631 * 632 * @return 633 * The driver type identifier 634 */ 635 __rte_internal 636 uint8_t rte_cryptodev_allocate_driver(struct cryptodev_driver *crypto_drv, 637 const struct rte_driver *drv); 638 639 /** 640 * @internal 641 * This is the last step of device probing. It must be called after a 642 * cryptodev is allocated and initialized successfully. 643 * 644 * @param dev Pointer to cryptodev struct 645 * 646 * @return 647 * void 648 */ 649 __rte_internal 650 void 651 rte_cryptodev_pmd_probing_finish(struct rte_cryptodev *dev); 652 653 #define RTE_PMD_REGISTER_CRYPTO_DRIVER(crypto_drv, drv, driver_id)\ 654 RTE_INIT(init_ ##driver_id)\ 655 {\ 656 driver_id = rte_cryptodev_allocate_driver(&crypto_drv, &(drv));\ 657 } 658 659 /* Reset crypto device fastpath APIs to dummy values. */ 660 __rte_internal 661 void 662 cryptodev_fp_ops_reset(struct rte_crypto_fp_ops *fp_ops); 663 664 /* Setup crypto device fastpath APIs. */ 665 __rte_internal 666 void 667 cryptodev_fp_ops_set(struct rte_crypto_fp_ops *fp_ops, 668 const struct rte_cryptodev *dev); 669 670 /** 671 * Get session event meta data (aka *union rte_event_crypto_metadata*) 672 * 673 * @param op pointer to *rte_crypto_op* structure. 674 * 675 * @return 676 * - On success, pointer to event crypto metadata 677 * - On failure, NULL. 678 */ 679 __rte_internal 680 void * 681 rte_cryptodev_session_event_mdata_get(struct rte_crypto_op *op); 682 683 /** 684 * @internal 685 * Cryptodev asymmetric crypto session. 686 */ 687 RTE_STD_C11 struct rte_cryptodev_asym_session { 688 uint8_t driver_id; 689 /**< Session driver ID. */ 690 uint16_t max_priv_data_sz; 691 /**< Size of private data used when creating mempool */ 692 uint16_t user_data_sz; 693 /**< Session user data will be placed after sess_data */ 694 uint8_t padding[3]; 695 void *event_mdata; 696 /**< Event metadata (aka *union rte_event_crypto_metadata*) */ 697 uint8_t sess_private_data[]; 698 }; 699 700 #ifdef __cplusplus 701 } 702 #endif 703 704 #endif /* _CRYPTODEV_PMD_H_ */ 705