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