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 /** Crypto device operations function pointer table */ 402 struct rte_cryptodev_ops { 403 cryptodev_configure_t dev_configure; /**< Configure device. */ 404 cryptodev_start_t dev_start; /**< Start device. */ 405 cryptodev_stop_t dev_stop; /**< Stop device. */ 406 cryptodev_close_t dev_close; /**< Close device. */ 407 408 cryptodev_info_get_t dev_infos_get; /**< Get device info. */ 409 410 cryptodev_stats_get_t stats_get; 411 /**< Get device statistics. */ 412 cryptodev_stats_reset_t stats_reset; 413 /**< Reset device statistics. */ 414 415 cryptodev_queue_pair_setup_t queue_pair_setup; 416 /**< Set up a device queue pair. */ 417 cryptodev_queue_pair_release_t queue_pair_release; 418 /**< Release a queue pair. */ 419 420 cryptodev_sym_get_session_private_size_t sym_session_get_size; 421 /**< Return private session. */ 422 cryptodev_asym_get_session_private_size_t asym_session_get_size; 423 /**< Return asym session private size. */ 424 cryptodev_sym_configure_session_t sym_session_configure; 425 /**< Configure a Crypto session. */ 426 cryptodev_asym_configure_session_t asym_session_configure; 427 /**< Configure asymmetric Crypto session. */ 428 cryptodev_sym_free_session_t sym_session_clear; 429 /**< Clear a Crypto sessions private data. */ 430 cryptodev_asym_clear_session_t asym_session_clear; 431 /**< Clear a Crypto sessions private data. */ 432 union { 433 cryptodev_sym_cpu_crypto_process_t sym_cpu_process; 434 /**< process input data synchronously (cpu-crypto). */ 435 __extension__ 436 struct { 437 cryptodev_sym_get_raw_dp_ctx_size_t 438 sym_get_raw_dp_ctx_size; 439 /**< Get raw data path service context data size. */ 440 cryptodev_sym_configure_raw_dp_ctx_t 441 sym_configure_raw_dp_ctx; 442 /**< Initialize raw data path context data. */ 443 }; 444 }; 445 }; 446 447 448 /** 449 * Function for internal use by dummy drivers primarily, e.g. ring-based 450 * driver. 451 * Allocates a new cryptodev slot for an crypto device and returns the pointer 452 * to that slot for the driver to use. 453 * 454 * @param name Unique identifier name for each device 455 * @param socket_id Socket to allocate resources on. 456 * @return 457 * - Slot in the rte_dev_devices array for a new device; 458 */ 459 __rte_internal 460 struct rte_cryptodev * 461 rte_cryptodev_pmd_allocate(const char *name, int socket_id); 462 463 /** 464 * Function for internal use by dummy drivers primarily, e.g. ring-based 465 * driver. 466 * Release the specified cryptodev device. 467 * 468 * @param cryptodev 469 * The *cryptodev* pointer is the address of the *rte_cryptodev* structure. 470 * @return 471 * - 0 on success, negative on error 472 */ 473 __rte_internal 474 extern int 475 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev); 476 477 478 /** 479 * @internal 480 * 481 * PMD assist function to parse initialisation arguments for crypto driver 482 * when creating a new crypto PMD device instance. 483 * 484 * PMD should set default values for that PMD before calling function, 485 * these default values will be over-written with successfully parsed values 486 * from args string. 487 * 488 * @param params parsed PMD initialisation parameters 489 * @param args input argument string to parse 490 * 491 * @return 492 * - 0 on success 493 * - errno on failure 494 */ 495 __rte_internal 496 int 497 rte_cryptodev_pmd_parse_input_args( 498 struct rte_cryptodev_pmd_init_params *params, 499 const char *args); 500 501 /** 502 * @internal 503 * 504 * PMD assist function to provide boiler plate code for crypto driver to create 505 * and allocate resources for a new crypto PMD device instance. 506 * 507 * @param name crypto device name. 508 * @param device base device instance 509 * @param params PMD initialisation parameters 510 * 511 * @return 512 * - crypto device instance on success 513 * - NULL on creation failure 514 */ 515 __rte_internal 516 struct rte_cryptodev * 517 rte_cryptodev_pmd_create(const char *name, 518 struct rte_device *device, 519 struct rte_cryptodev_pmd_init_params *params); 520 521 /** 522 * @internal 523 * 524 * PMD assist function to provide boiler plate code for crypto driver to 525 * destroy and free resources associated with a crypto PMD device instance. 526 * 527 * @param cryptodev crypto device handle. 528 * 529 * @return 530 * - 0 on success 531 * - errno on failure 532 */ 533 __rte_internal 534 int 535 rte_cryptodev_pmd_destroy(struct rte_cryptodev *cryptodev); 536 537 /** 538 * Executes all the user application registered callbacks for the specific 539 * device. 540 * * 541 * @param dev Pointer to cryptodev struct 542 * @param event Crypto device interrupt event type. 543 * 544 * @return 545 * void 546 */ 547 __rte_internal 548 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev, 549 enum rte_cryptodev_event_type event); 550 551 /** 552 * @internal 553 * Create unique device name 554 */ 555 __rte_internal 556 int 557 rte_cryptodev_pmd_create_dev_name(char *name, const char *dev_name_prefix); 558 559 /** 560 * @internal 561 * Allocate Cryptodev driver. 562 * 563 * @param crypto_drv 564 * Pointer to cryptodev_driver. 565 * @param drv 566 * Pointer to rte_driver. 567 * 568 * @return 569 * The driver type identifier 570 */ 571 __rte_internal 572 uint8_t rte_cryptodev_allocate_driver(struct cryptodev_driver *crypto_drv, 573 const struct rte_driver *drv); 574 575 /** 576 * @internal 577 * This is the last step of device probing. It must be called after a 578 * cryptodev is allocated and initialized successfully. 579 * 580 * @param dev Pointer to cryptodev struct 581 * 582 * @return 583 * void 584 */ 585 __rte_internal 586 void 587 rte_cryptodev_pmd_probing_finish(struct rte_cryptodev *dev); 588 589 #define RTE_PMD_REGISTER_CRYPTO_DRIVER(crypto_drv, drv, driver_id)\ 590 RTE_INIT(init_ ##driver_id)\ 591 {\ 592 driver_id = rte_cryptodev_allocate_driver(&crypto_drv, &(drv));\ 593 } 594 595 /* Reset crypto device fastpath APIs to dummy values. */ 596 __rte_internal 597 void 598 cryptodev_fp_ops_reset(struct rte_crypto_fp_ops *fp_ops); 599 600 /* Setup crypto device fastpath APIs. */ 601 __rte_internal 602 void 603 cryptodev_fp_ops_set(struct rte_crypto_fp_ops *fp_ops, 604 const struct rte_cryptodev *dev); 605 606 static inline void * 607 get_sym_session_private_data(const struct rte_cryptodev_sym_session *sess, 608 uint8_t driver_id) { 609 if (unlikely(sess->nb_drivers <= driver_id)) 610 return NULL; 611 612 return sess->sess_data[driver_id].data; 613 } 614 615 static inline void 616 set_sym_session_private_data(struct rte_cryptodev_sym_session *sess, 617 uint8_t driver_id, void *private_data) 618 { 619 if (unlikely(sess->nb_drivers <= driver_id)) { 620 CDEV_LOG_ERR("Set private data for driver %u not allowed\n", 621 driver_id); 622 return; 623 } 624 625 sess->sess_data[driver_id].data = private_data; 626 } 627 628 /** 629 * @internal 630 * Cryptodev asymmetric crypto session. 631 */ 632 RTE_STD_C11 struct rte_cryptodev_asym_session { 633 uint8_t driver_id; 634 /**< Session driver ID. */ 635 uint16_t max_priv_data_sz; 636 /**< Size of private data used when creating mempool */ 637 uint16_t user_data_sz; 638 /**< Session user data will be placed after sess_data */ 639 uint8_t padding[3]; 640 uint8_t sess_private_data[0]; 641 }; 642 643 #ifdef __cplusplus 644 } 645 #endif 646 647 #endif /* _CRYPTODEV_PMD_H_ */ 648