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