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 /** Crypto device operations function pointer table */ 455 struct rte_cryptodev_ops { 456 cryptodev_configure_t dev_configure; /**< Configure device. */ 457 cryptodev_start_t dev_start; /**< Start device. */ 458 cryptodev_stop_t dev_stop; /**< Stop device. */ 459 cryptodev_close_t dev_close; /**< Close device. */ 460 461 cryptodev_info_get_t dev_infos_get; /**< Get device info. */ 462 463 cryptodev_stats_get_t stats_get; 464 /**< Get device statistics. */ 465 cryptodev_stats_reset_t stats_reset; 466 /**< Reset device statistics. */ 467 468 cryptodev_queue_pair_setup_t queue_pair_setup; 469 /**< Set up a device queue pair. */ 470 cryptodev_queue_pair_release_t queue_pair_release; 471 /**< Release a queue pair. */ 472 473 cryptodev_sym_get_session_private_size_t sym_session_get_size; 474 /**< Return private session. */ 475 cryptodev_asym_get_session_private_size_t asym_session_get_size; 476 /**< Return asym session private size. */ 477 cryptodev_sym_configure_session_t sym_session_configure; 478 /**< Configure a Crypto session. */ 479 cryptodev_asym_configure_session_t asym_session_configure; 480 /**< Configure asymmetric Crypto session. */ 481 cryptodev_sym_free_session_t sym_session_clear; 482 /**< Clear a Crypto sessions private data. */ 483 cryptodev_asym_clear_session_t asym_session_clear; 484 /**< Clear a Crypto sessions private data. */ 485 union { 486 cryptodev_sym_cpu_crypto_process_t sym_cpu_process; 487 /**< process input data synchronously (cpu-crypto). */ 488 __extension__ 489 struct { 490 cryptodev_sym_get_raw_dp_ctx_size_t 491 sym_get_raw_dp_ctx_size; 492 /**< Get raw data path service context data size. */ 493 cryptodev_sym_configure_raw_dp_ctx_t 494 sym_configure_raw_dp_ctx; 495 /**< Initialize raw data path context data. */ 496 }; 497 }; 498 cryptodev_session_event_mdata_set_t session_ev_mdata_set; 499 /**< Set a Crypto or Security session even meta data. */ 500 }; 501 502 503 /** 504 * Function for internal use by dummy drivers primarily, e.g. ring-based 505 * driver. 506 * Allocates a new cryptodev slot for an crypto device and returns the pointer 507 * to that slot for the driver to use. 508 * 509 * @param name Unique identifier name for each device 510 * @param socket_id Socket to allocate resources on. 511 * @return 512 * - Slot in the rte_dev_devices array for a new device; 513 */ 514 __rte_internal 515 struct rte_cryptodev * 516 rte_cryptodev_pmd_allocate(const char *name, int socket_id); 517 518 /** 519 * Function for internal use by dummy drivers primarily, e.g. ring-based 520 * driver. 521 * Release the specified cryptodev device. 522 * 523 * @param cryptodev 524 * The *cryptodev* pointer is the address of the *rte_cryptodev* structure. 525 * @return 526 * - 0 on success, negative on error 527 */ 528 __rte_internal 529 extern int 530 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev); 531 532 533 /** 534 * @internal 535 * 536 * PMD assist function to parse initialisation arguments for crypto driver 537 * when creating a new crypto PMD device instance. 538 * 539 * PMD should set default values for that PMD before calling function, 540 * these default values will be over-written with successfully parsed values 541 * from args string. 542 * 543 * @param params parsed PMD initialisation parameters 544 * @param args input argument string to parse 545 * 546 * @return 547 * - 0 on success 548 * - errno on failure 549 */ 550 __rte_internal 551 int 552 rte_cryptodev_pmd_parse_input_args( 553 struct rte_cryptodev_pmd_init_params *params, 554 const char *args); 555 556 /** 557 * @internal 558 * 559 * PMD assist function to provide boiler plate code for crypto driver to create 560 * and allocate resources for a new crypto PMD device instance. 561 * 562 * @param name crypto device name. 563 * @param device base device instance 564 * @param params PMD initialisation parameters 565 * 566 * @return 567 * - crypto device instance on success 568 * - NULL on creation failure 569 */ 570 __rte_internal 571 struct rte_cryptodev * 572 rte_cryptodev_pmd_create(const char *name, 573 struct rte_device *device, 574 struct rte_cryptodev_pmd_init_params *params); 575 576 /** 577 * @internal 578 * 579 * PMD assist function to provide boiler plate code for crypto driver to 580 * destroy and free resources associated with a crypto PMD device instance. 581 * 582 * @param cryptodev crypto device handle. 583 * 584 * @return 585 * - 0 on success 586 * - errno on failure 587 */ 588 __rte_internal 589 int 590 rte_cryptodev_pmd_destroy(struct rte_cryptodev *cryptodev); 591 592 /** 593 * Executes all the user application registered callbacks for the specific 594 * device. 595 * * 596 * @param dev Pointer to cryptodev struct 597 * @param event Crypto device interrupt event type. 598 * 599 * @return 600 * void 601 */ 602 __rte_internal 603 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev, 604 enum rte_cryptodev_event_type event); 605 606 /** 607 * @internal 608 * Create unique device name 609 */ 610 __rte_internal 611 int 612 rte_cryptodev_pmd_create_dev_name(char *name, const char *dev_name_prefix); 613 614 /** 615 * @internal 616 * Allocate Cryptodev driver. 617 * 618 * @param crypto_drv 619 * Pointer to cryptodev_driver. 620 * @param drv 621 * Pointer to rte_driver. 622 * 623 * @return 624 * The driver type identifier 625 */ 626 __rte_internal 627 uint8_t rte_cryptodev_allocate_driver(struct cryptodev_driver *crypto_drv, 628 const struct rte_driver *drv); 629 630 /** 631 * @internal 632 * This is the last step of device probing. It must be called after a 633 * cryptodev is allocated and initialized successfully. 634 * 635 * @param dev Pointer to cryptodev struct 636 * 637 * @return 638 * void 639 */ 640 __rte_internal 641 void 642 rte_cryptodev_pmd_probing_finish(struct rte_cryptodev *dev); 643 644 #define RTE_PMD_REGISTER_CRYPTO_DRIVER(crypto_drv, drv, driver_id)\ 645 RTE_INIT(init_ ##driver_id)\ 646 {\ 647 driver_id = rte_cryptodev_allocate_driver(&crypto_drv, &(drv));\ 648 } 649 650 /* Reset crypto device fastpath APIs to dummy values. */ 651 __rte_internal 652 void 653 cryptodev_fp_ops_reset(struct rte_crypto_fp_ops *fp_ops); 654 655 /* Setup crypto device fastpath APIs. */ 656 __rte_internal 657 void 658 cryptodev_fp_ops_set(struct rte_crypto_fp_ops *fp_ops, 659 const struct rte_cryptodev *dev); 660 661 /** 662 * Get session event meta data (aka *union rte_event_crypto_metadata*) 663 * 664 * @param op pointer to *rte_crypto_op* structure. 665 * 666 * @return 667 * - On success, pointer to event crypto metadata 668 * - On failure, NULL. 669 */ 670 __rte_internal 671 void * 672 rte_cryptodev_session_event_mdata_get(struct rte_crypto_op *op); 673 674 /** 675 * @internal 676 * Cryptodev asymmetric crypto session. 677 */ 678 RTE_STD_C11 struct rte_cryptodev_asym_session { 679 uint8_t driver_id; 680 /**< Session driver ID. */ 681 uint16_t max_priv_data_sz; 682 /**< Size of private data used when creating mempool */ 683 uint16_t user_data_sz; 684 /**< Session user data will be placed after sess_data */ 685 uint8_t padding[3]; 686 void *event_mdata; 687 /**< Event metadata (aka *union rte_event_crypto_metadata*) */ 688 uint8_t sess_private_data[]; 689 }; 690 691 #ifdef __cplusplus 692 } 693 #endif 694 695 #endif /* _CRYPTODEV_PMD_H_ */ 696