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