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_config.h> 19 #include <rte_dev.h> 20 #include <rte_malloc.h> 21 #include <rte_mbuf.h> 22 #include <rte_mempool.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 * the 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 * @param mp Mempool where the private session is allocated 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 struct rte_mempool *mp); 334 /** 335 * Free driver private session data. 336 * 337 * @param dev Crypto device pointer 338 * @param sess Cryptodev session structure 339 */ 340 typedef void (*cryptodev_sym_free_session_t)(struct rte_cryptodev *dev, 341 struct rte_cryptodev_sym_session *sess); 342 /** 343 * Free asymmetric session private data. 344 * 345 * @param dev Crypto device pointer 346 * @param sess Cryptodev session structure 347 */ 348 typedef void (*cryptodev_asym_free_session_t)(struct rte_cryptodev *dev, 349 struct rte_cryptodev_asym_session *sess); 350 /** 351 * Perform actual crypto processing (encrypt/digest or auth/decrypt) 352 * on user provided data. 353 * 354 * @param dev Crypto device pointer 355 * @param sess Cryptodev session structure 356 * @param ofs Start and stop offsets for auth and cipher operations 357 * @param vec Vectorized operation descriptor 358 * 359 * @return 360 * - Returns number of successfully processed packets. 361 * 362 */ 363 typedef uint32_t (*cryptodev_sym_cpu_crypto_process_t) 364 (struct rte_cryptodev *dev, struct rte_cryptodev_sym_session *sess, 365 union rte_crypto_sym_ofs ofs, struct rte_crypto_sym_vec *vec); 366 367 /** 368 * Typedef that the driver provided to get service context private date size. 369 * 370 * @param dev Crypto device pointer. 371 * 372 * @return 373 * - On success return the size of the device's service context private data. 374 * - On failure return negative integer. 375 */ 376 typedef int (*cryptodev_sym_get_raw_dp_ctx_size_t)(struct rte_cryptodev *dev); 377 378 /** 379 * Typedef that the driver provided to configure raw data-path context. 380 * 381 * @param dev Crypto device pointer. 382 * @param qp_id Crypto device queue pair index. 383 * @param ctx The raw data-path context data. 384 * @param sess_type session type. 385 * @param session_ctx Session context data. If NULL the driver 386 * shall only configure the drv_ctx_data in 387 * ctx buffer. Otherwise the driver shall only 388 * parse the session_ctx to set appropriate 389 * function pointers in ctx. 390 * @param is_update Set 0 if it is to initialize the ctx. 391 * Set 1 if ctx is initialized and only to update 392 * session context data. 393 * @return 394 * - On success return 0. 395 * - On failure return negative integer. 396 */ 397 typedef int (*cryptodev_sym_configure_raw_dp_ctx_t)( 398 struct rte_cryptodev *dev, uint16_t qp_id, 399 struct rte_crypto_raw_dp_ctx *ctx, 400 enum rte_crypto_op_sess_type sess_type, 401 union rte_cryptodev_session_ctx session_ctx, uint8_t is_update); 402 403 /** Crypto device operations function pointer table */ 404 struct rte_cryptodev_ops { 405 cryptodev_configure_t dev_configure; /**< Configure device. */ 406 cryptodev_start_t dev_start; /**< Start device. */ 407 cryptodev_stop_t dev_stop; /**< Stop device. */ 408 cryptodev_close_t dev_close; /**< Close device. */ 409 410 cryptodev_info_get_t dev_infos_get; /**< Get device info. */ 411 412 cryptodev_stats_get_t stats_get; 413 /**< Get device statistics. */ 414 cryptodev_stats_reset_t stats_reset; 415 /**< Reset device statistics. */ 416 417 cryptodev_queue_pair_setup_t queue_pair_setup; 418 /**< Set up a device queue pair. */ 419 cryptodev_queue_pair_release_t queue_pair_release; 420 /**< Release a queue pair. */ 421 422 cryptodev_sym_get_session_private_size_t sym_session_get_size; 423 /**< Return private session. */ 424 cryptodev_asym_get_session_private_size_t asym_session_get_size; 425 /**< Return asym session private size. */ 426 cryptodev_sym_configure_session_t sym_session_configure; 427 /**< Configure a Crypto session. */ 428 cryptodev_asym_configure_session_t asym_session_configure; 429 /**< Configure asymmetric Crypto session. */ 430 cryptodev_sym_free_session_t sym_session_clear; 431 /**< Clear a Crypto sessions private data. */ 432 cryptodev_asym_free_session_t asym_session_clear; 433 /**< Clear a Crypto sessions private data. */ 434 union { 435 cryptodev_sym_cpu_crypto_process_t sym_cpu_process; 436 /**< process input data synchronously (cpu-crypto). */ 437 __extension__ 438 struct { 439 cryptodev_sym_get_raw_dp_ctx_size_t 440 sym_get_raw_dp_ctx_size; 441 /**< Get raw data path service context data size. */ 442 cryptodev_sym_configure_raw_dp_ctx_t 443 sym_configure_raw_dp_ctx; 444 /**< Initialize raw data path context data. */ 445 }; 446 }; 447 }; 448 449 450 /** 451 * Function for internal use by dummy drivers primarily, e.g. ring-based 452 * driver. 453 * Allocates a new cryptodev slot for an crypto device and returns the pointer 454 * to that slot for the driver to use. 455 * 456 * @param name Unique identifier name for each device 457 * @param socket_id Socket to allocate resources on. 458 * @return 459 * - Slot in the rte_dev_devices array for a new device; 460 */ 461 __rte_internal 462 struct rte_cryptodev * 463 rte_cryptodev_pmd_allocate(const char *name, int socket_id); 464 465 /** 466 * Function for internal use by dummy drivers primarily, e.g. ring-based 467 * driver. 468 * Release the specified cryptodev device. 469 * 470 * @param cryptodev 471 * The *cryptodev* pointer is the address of the *rte_cryptodev* structure. 472 * @return 473 * - 0 on success, negative on error 474 */ 475 __rte_internal 476 extern int 477 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev); 478 479 480 /** 481 * @internal 482 * 483 * PMD assist function to parse initialisation arguments for crypto driver 484 * when creating a new crypto PMD device instance. 485 * 486 * PMD driver should set default values for that PMD before calling function, 487 * these default values will be over-written with successfully parsed values 488 * from args string. 489 * 490 * @param params parsed PMD initialisation parameters 491 * @param args input argument string to parse 492 * 493 * @return 494 * - 0 on success 495 * - errno on failure 496 */ 497 __rte_internal 498 int 499 rte_cryptodev_pmd_parse_input_args( 500 struct rte_cryptodev_pmd_init_params *params, 501 const char *args); 502 503 /** 504 * @internal 505 * 506 * PMD assist function to provide boiler plate code for crypto driver to create 507 * and allocate resources for a new crypto PMD device instance. 508 * 509 * @param name crypto device name. 510 * @param device base device instance 511 * @param params PMD initialisation parameters 512 * 513 * @return 514 * - crypto device instance on success 515 * - NULL on creation failure 516 */ 517 __rte_internal 518 struct rte_cryptodev * 519 rte_cryptodev_pmd_create(const char *name, 520 struct rte_device *device, 521 struct rte_cryptodev_pmd_init_params *params); 522 523 /** 524 * @internal 525 * 526 * PMD assist function to provide boiler plate code for crypto driver to 527 * destroy and free resources associated with a crypto PMD device instance. 528 * 529 * @param cryptodev crypto device handle. 530 * 531 * @return 532 * - 0 on success 533 * - errno on failure 534 */ 535 __rte_internal 536 int 537 rte_cryptodev_pmd_destroy(struct rte_cryptodev *cryptodev); 538 539 /** 540 * Executes all the user application registered callbacks for the specific 541 * device. 542 * * 543 * @param dev Pointer to cryptodev struct 544 * @param event Crypto device interrupt event type. 545 * 546 * @return 547 * void 548 */ 549 __rte_internal 550 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev, 551 enum rte_cryptodev_event_type event); 552 553 /** 554 * @internal 555 * Create unique device name 556 */ 557 __rte_internal 558 int 559 rte_cryptodev_pmd_create_dev_name(char *name, const char *dev_name_prefix); 560 561 /** 562 * @internal 563 * Allocate Cryptodev driver. 564 * 565 * @param crypto_drv 566 * Pointer to cryptodev_driver. 567 * @param drv 568 * Pointer to rte_driver. 569 * 570 * @return 571 * The driver type identifier 572 */ 573 __rte_internal 574 uint8_t rte_cryptodev_allocate_driver(struct cryptodev_driver *crypto_drv, 575 const struct rte_driver *drv); 576 577 /** 578 * @internal 579 * This is the last step of device probing. It must be called after a 580 * cryptodev is allocated and initialized successfully. 581 * 582 * @param dev Pointer to cryptodev struct 583 * 584 * @return 585 * void 586 */ 587 __rte_internal 588 void 589 rte_cryptodev_pmd_probing_finish(struct rte_cryptodev *dev); 590 591 #define RTE_PMD_REGISTER_CRYPTO_DRIVER(crypto_drv, drv, driver_id)\ 592 RTE_INIT(init_ ##driver_id)\ 593 {\ 594 driver_id = rte_cryptodev_allocate_driver(&crypto_drv, &(drv));\ 595 } 596 597 /* Reset crypto device fastpath APIs to dummy values. */ 598 __rte_internal 599 void 600 cryptodev_fp_ops_reset(struct rte_crypto_fp_ops *fp_ops); 601 602 /* Setup crypto device fastpath APIs. */ 603 __rte_internal 604 void 605 cryptodev_fp_ops_set(struct rte_crypto_fp_ops *fp_ops, 606 const struct rte_cryptodev *dev); 607 608 static inline void * 609 get_sym_session_private_data(const struct rte_cryptodev_sym_session *sess, 610 uint8_t driver_id) { 611 if (unlikely(sess->nb_drivers <= driver_id)) 612 return NULL; 613 614 return sess->sess_data[driver_id].data; 615 } 616 617 static inline void 618 set_sym_session_private_data(struct rte_cryptodev_sym_session *sess, 619 uint8_t driver_id, void *private_data) 620 { 621 if (unlikely(sess->nb_drivers <= driver_id)) { 622 CDEV_LOG_ERR("Set private data for driver %u not allowed\n", 623 driver_id); 624 return; 625 } 626 627 sess->sess_data[driver_id].data = private_data; 628 } 629 630 static inline void * 631 get_asym_session_private_data(const struct rte_cryptodev_asym_session *sess, 632 uint8_t driver_id) { 633 return sess->sess_private_data[driver_id]; 634 } 635 636 static inline void 637 set_asym_session_private_data(struct rte_cryptodev_asym_session *sess, 638 uint8_t driver_id, void *private_data) 639 { 640 sess->sess_private_data[driver_id] = private_data; 641 } 642 643 #endif /* _CRYPTODEV_PMD_H_ */ 644