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