1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2015-2016 Intel Corporation. 3 */ 4 5 #ifndef _RTE_CRYPTODEV_PMD_H_ 6 #define _RTE_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 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 #include <string.h> 21 22 #include <rte_config.h> 23 #include <rte_dev.h> 24 #include <rte_malloc.h> 25 #include <rte_mbuf.h> 26 #include <rte_mempool.h> 27 #include <rte_log.h> 28 #include <rte_common.h> 29 30 #include "rte_crypto.h" 31 #include "rte_cryptodev.h" 32 33 34 #define RTE_CRYPTODEV_PMD_DEFAULT_MAX_NB_QUEUE_PAIRS 8 35 36 #define RTE_CRYPTODEV_PMD_NAME_ARG ("name") 37 #define RTE_CRYPTODEV_PMD_MAX_NB_QP_ARG ("max_nb_queue_pairs") 38 #define RTE_CRYPTODEV_PMD_SOCKET_ID_ARG ("socket_id") 39 40 41 static const char * const cryptodev_pmd_valid_params[] = { 42 RTE_CRYPTODEV_PMD_NAME_ARG, 43 RTE_CRYPTODEV_PMD_MAX_NB_QP_ARG, 44 RTE_CRYPTODEV_PMD_SOCKET_ID_ARG 45 }; 46 47 /** 48 * @internal 49 * Initialisation parameters for crypto devices 50 */ 51 struct rte_cryptodev_pmd_init_params { 52 char name[RTE_CRYPTODEV_NAME_MAX_LEN]; 53 size_t private_data_size; 54 int socket_id; 55 unsigned int max_nb_queue_pairs; 56 }; 57 58 /** Global structure used for maintaining state of allocated crypto devices */ 59 struct rte_cryptodev_global { 60 struct rte_cryptodev *devs; /**< Device information array */ 61 struct rte_cryptodev_data *data[RTE_CRYPTO_MAX_DEVS]; 62 /**< Device private data */ 63 uint8_t nb_devs; /**< Number of devices found */ 64 }; 65 66 /* Cryptodev driver, containing the driver ID */ 67 struct cryptodev_driver { 68 TAILQ_ENTRY(cryptodev_driver) next; /**< Next in list. */ 69 const struct rte_driver *driver; 70 uint8_t id; 71 }; 72 73 /** 74 * Get the rte_cryptodev structure device pointer for the device. Assumes a 75 * valid device index. 76 * 77 * @param dev_id Device ID value to select the device structure. 78 * 79 * @return 80 * - The rte_cryptodev structure pointer for the given device ID. 81 */ 82 struct rte_cryptodev * 83 rte_cryptodev_pmd_get_dev(uint8_t dev_id); 84 85 /** 86 * Get the rte_cryptodev structure device pointer for the named device. 87 * 88 * @param name device name to select the device structure. 89 * 90 * @return 91 * - The rte_cryptodev structure pointer for the given device ID. 92 */ 93 struct rte_cryptodev * 94 rte_cryptodev_pmd_get_named_dev(const char *name); 95 96 /** 97 * Validate if the crypto device index is valid attached crypto device. 98 * 99 * @param dev_id Crypto device index. 100 * 101 * @return 102 * - If the device index is valid (1) or not (0). 103 */ 104 unsigned int 105 rte_cryptodev_pmd_is_valid_dev(uint8_t dev_id); 106 107 /** 108 * The pool of rte_cryptodev structures. 109 */ 110 extern struct rte_cryptodev *rte_cryptodevs; 111 112 113 /** 114 * Definitions of all functions exported by a driver through the 115 * the generic structure of type *crypto_dev_ops* supplied in the 116 * *rte_cryptodev* structure associated with a device. 117 */ 118 119 /** 120 * Function used to configure device. 121 * 122 * @param dev Crypto device pointer 123 * config Crypto device configurations 124 * 125 * @return Returns 0 on success 126 */ 127 typedef int (*cryptodev_configure_t)(struct rte_cryptodev *dev, 128 struct rte_cryptodev_config *config); 129 130 /** 131 * Function used to start a configured device. 132 * 133 * @param dev Crypto device pointer 134 * 135 * @return Returns 0 on success 136 */ 137 typedef int (*cryptodev_start_t)(struct rte_cryptodev *dev); 138 139 /** 140 * Function used to stop a configured device. 141 * 142 * @param dev Crypto device pointer 143 */ 144 typedef void (*cryptodev_stop_t)(struct rte_cryptodev *dev); 145 146 /** 147 * Function used to close a configured device. 148 * 149 * @param dev Crypto device pointer 150 * @return 151 * - 0 on success. 152 * - EAGAIN if can't close as device is busy 153 */ 154 typedef int (*cryptodev_close_t)(struct rte_cryptodev *dev); 155 156 157 /** 158 * Function used to get statistics of a device. 159 * 160 * @param dev Crypto device pointer 161 * @param stats Pointer to crypto device stats structure to populate 162 */ 163 typedef void (*cryptodev_stats_get_t)(struct rte_cryptodev *dev, 164 struct rte_cryptodev_stats *stats); 165 166 167 /** 168 * Function used to reset statistics of a device. 169 * 170 * @param dev Crypto device pointer 171 */ 172 typedef void (*cryptodev_stats_reset_t)(struct rte_cryptodev *dev); 173 174 175 /** 176 * Function used to get specific information of a device. 177 * 178 * @param dev Crypto device pointer 179 */ 180 typedef void (*cryptodev_info_get_t)(struct rte_cryptodev *dev, 181 struct rte_cryptodev_info *dev_info); 182 183 /** 184 * Setup a queue pair for a device. 185 * 186 * @param dev Crypto device pointer 187 * @param qp_id Queue Pair Index 188 * @param qp_conf Queue configuration structure 189 * @param socket_id Socket Index 190 * 191 * @return Returns 0 on success. 192 */ 193 typedef int (*cryptodev_queue_pair_setup_t)(struct rte_cryptodev *dev, 194 uint16_t qp_id, const struct rte_cryptodev_qp_conf *qp_conf, 195 int socket_id); 196 197 /** 198 * Release memory resources allocated by given queue pair. 199 * 200 * @param dev Crypto device pointer 201 * @param qp_id Queue Pair Index 202 * 203 * @return 204 * - 0 on success. 205 * - EAGAIN if can't close as device is busy 206 */ 207 typedef int (*cryptodev_queue_pair_release_t)(struct rte_cryptodev *dev, 208 uint16_t qp_id); 209 210 /** 211 * Get number of available queue pairs of a device. 212 * 213 * @param dev Crypto device pointer 214 * 215 * @return Returns number of queue pairs on success. 216 */ 217 typedef uint32_t (*cryptodev_queue_pair_count_t)(struct rte_cryptodev *dev); 218 219 /** 220 * Create a session mempool to allocate sessions from 221 * 222 * @param dev Crypto device pointer 223 * @param nb_objs number of sessions objects in mempool 224 * @param obj_cache l-core object cache size, see *rte_ring_create* 225 * @param socket_id Socket Id to allocate mempool on. 226 * 227 * @return 228 * - On success returns a pointer to a rte_mempool 229 * - On failure returns a NULL pointer 230 */ 231 typedef int (*cryptodev_sym_create_session_pool_t)( 232 struct rte_cryptodev *dev, unsigned nb_objs, 233 unsigned obj_cache_size, int socket_id); 234 235 236 /** 237 * Get the size of a cryptodev session 238 * 239 * @param dev Crypto device pointer 240 * 241 * @return 242 * - On success returns the size of the session structure for device 243 * - On failure returns 0 244 */ 245 typedef unsigned (*cryptodev_sym_get_session_private_size_t)( 246 struct rte_cryptodev *dev); 247 /** 248 * Get the size of a asymmetric cryptodev session 249 * 250 * @param dev Crypto device pointer 251 * 252 * @return 253 * - On success returns the size of the session structure for device 254 * - On failure returns 0 255 */ 256 typedef unsigned int (*cryptodev_asym_get_session_private_size_t)( 257 struct rte_cryptodev *dev); 258 259 /** 260 * Configure a Crypto session on a device. 261 * 262 * @param dev Crypto device pointer 263 * @param xform Single or chain of crypto xforms 264 * @param priv_sess Pointer to cryptodev's private session structure 265 * @param mp Mempool where the private session is allocated 266 * 267 * @return 268 * - Returns 0 if private session structure have been created successfully. 269 * - Returns -EINVAL if input parameters are invalid. 270 * - Returns -ENOTSUP if crypto device does not support the crypto transform. 271 * - Returns -ENOMEM if the private session could not be allocated. 272 */ 273 typedef int (*cryptodev_sym_configure_session_t)(struct rte_cryptodev *dev, 274 struct rte_crypto_sym_xform *xform, 275 struct rte_cryptodev_sym_session *session, 276 struct rte_mempool *mp); 277 /** 278 * Configure a Crypto asymmetric session on a device. 279 * 280 * @param dev Crypto device pointer 281 * @param xform Single or chain of crypto xforms 282 * @param priv_sess Pointer to cryptodev's private session structure 283 * @param mp Mempool where the private session is allocated 284 * 285 * @return 286 * - Returns 0 if private session structure have been created successfully. 287 * - Returns -EINVAL if input parameters are invalid. 288 * - Returns -ENOTSUP if crypto device does not support the crypto transform. 289 * - Returns -ENOMEM if the private session could not be allocated. 290 */ 291 typedef int (*cryptodev_asym_configure_session_t)(struct rte_cryptodev *dev, 292 struct rte_crypto_asym_xform *xform, 293 struct rte_cryptodev_asym_session *session, 294 struct rte_mempool *mp); 295 /** 296 * Free driver private session data. 297 * 298 * @param dev Crypto device pointer 299 * @param sess Cryptodev session structure 300 */ 301 typedef void (*cryptodev_sym_free_session_t)(struct rte_cryptodev *dev, 302 struct rte_cryptodev_sym_session *sess); 303 /** 304 * Free asymmetric session private data. 305 * 306 * @param dev Crypto device pointer 307 * @param sess Cryptodev session structure 308 */ 309 typedef void (*cryptodev_asym_free_session_t)(struct rte_cryptodev *dev, 310 struct rte_cryptodev_asym_session *sess); 311 312 /** Crypto device operations function pointer table */ 313 struct rte_cryptodev_ops { 314 cryptodev_configure_t dev_configure; /**< Configure device. */ 315 cryptodev_start_t dev_start; /**< Start device. */ 316 cryptodev_stop_t dev_stop; /**< Stop device. */ 317 cryptodev_close_t dev_close; /**< Close device. */ 318 319 cryptodev_info_get_t dev_infos_get; /**< Get device info. */ 320 321 cryptodev_stats_get_t stats_get; 322 /**< Get device statistics. */ 323 cryptodev_stats_reset_t stats_reset; 324 /**< Reset device statistics. */ 325 326 cryptodev_queue_pair_setup_t queue_pair_setup; 327 /**< Set up a device queue pair. */ 328 cryptodev_queue_pair_release_t queue_pair_release; 329 /**< Release a queue pair. */ 330 cryptodev_queue_pair_count_t queue_pair_count; 331 /**< Get count of the queue pairs. */ 332 333 cryptodev_sym_get_session_private_size_t sym_session_get_size; 334 /**< Return private session. */ 335 cryptodev_asym_get_session_private_size_t asym_session_get_size; 336 /**< Return asym session private size. */ 337 cryptodev_sym_configure_session_t sym_session_configure; 338 /**< Configure a Crypto session. */ 339 cryptodev_asym_configure_session_t asym_session_configure; 340 /**< Configure asymmetric Crypto session. */ 341 cryptodev_sym_free_session_t sym_session_clear; 342 /**< Clear a Crypto sessions private data. */ 343 cryptodev_asym_free_session_t asym_session_clear; 344 /**< Clear a Crypto sessions private data. */ 345 }; 346 347 348 /** 349 * Function for internal use by dummy drivers primarily, e.g. ring-based 350 * driver. 351 * Allocates a new cryptodev slot for an crypto device and returns the pointer 352 * to that slot for the driver to use. 353 * 354 * @param name Unique identifier name for each device 355 * @param socket_id Socket to allocate resources on. 356 * @return 357 * - Slot in the rte_dev_devices array for a new device; 358 */ 359 struct rte_cryptodev * 360 rte_cryptodev_pmd_allocate(const char *name, int socket_id); 361 362 /** 363 * Function for internal use by dummy drivers primarily, e.g. ring-based 364 * driver. 365 * Release the specified cryptodev device. 366 * 367 * @param cryptodev 368 * The *cryptodev* pointer is the address of the *rte_cryptodev* structure. 369 * @return 370 * - 0 on success, negative on error 371 */ 372 extern int 373 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev); 374 375 376 /** 377 * @internal 378 * 379 * PMD assist function to parse initialisation arguments for crypto driver 380 * when creating a new crypto PMD device instance. 381 * 382 * PMD driver should set default values for that PMD before calling function, 383 * these default values will be over-written with successfully parsed values 384 * from args string. 385 * 386 * @param params parsed PMD initialisation parameters 387 * @param args input argument string to parse 388 * 389 * @return 390 * - 0 on success 391 * - errno on failure 392 */ 393 int 394 rte_cryptodev_pmd_parse_input_args( 395 struct rte_cryptodev_pmd_init_params *params, 396 const char *args); 397 398 /** 399 * @internal 400 * 401 * PMD assist function to provide boiler plate code for crypto driver to create 402 * and allocate resources for a new crypto PMD device instance. 403 * 404 * @param name crypto device name. 405 * @param device base device instance 406 * @param params PMD initialisation parameters 407 * 408 * @return 409 * - crypto device instance on success 410 * - NULL on creation failure 411 */ 412 struct rte_cryptodev * 413 rte_cryptodev_pmd_create(const char *name, 414 struct rte_device *device, 415 struct rte_cryptodev_pmd_init_params *params); 416 417 /** 418 * @internal 419 * 420 * PMD assist function to provide boiler plate code for crypto driver to 421 * destroy and free resources associated with a crypto PMD device instance. 422 * 423 * @param cryptodev crypto device handle. 424 * 425 * @return 426 * - 0 on success 427 * - errno on failure 428 */ 429 int 430 rte_cryptodev_pmd_destroy(struct rte_cryptodev *cryptodev); 431 432 /** 433 * Executes all the user application registered callbacks for the specific 434 * device. 435 * * 436 * @param dev Pointer to cryptodev struct 437 * @param event Crypto device interrupt event type. 438 * 439 * @return 440 * void 441 */ 442 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev, 443 enum rte_cryptodev_event_type event); 444 445 /** 446 * @internal 447 * Create unique device name 448 */ 449 int 450 rte_cryptodev_pmd_create_dev_name(char *name, const char *dev_name_prefix); 451 452 /** 453 * @internal 454 * Allocate Cryptodev driver. 455 * 456 * @param crypto_drv 457 * Pointer to cryptodev_driver. 458 * @param drv 459 * Pointer to rte_driver. 460 * 461 * @return 462 * The driver type identifier 463 */ 464 uint8_t rte_cryptodev_allocate_driver(struct cryptodev_driver *crypto_drv, 465 const struct rte_driver *drv); 466 467 468 #define RTE_PMD_REGISTER_CRYPTO_DRIVER(crypto_drv, drv, driver_id)\ 469 RTE_INIT(init_ ##driver_id)\ 470 {\ 471 driver_id = rte_cryptodev_allocate_driver(&crypto_drv, &(drv));\ 472 } 473 474 static inline void * 475 get_sym_session_private_data(const struct rte_cryptodev_sym_session *sess, 476 uint8_t driver_id) { 477 if (unlikely(sess->nb_drivers <= driver_id)) 478 return NULL; 479 480 return sess->sess_data[driver_id].data; 481 } 482 483 static inline void 484 set_sym_session_private_data(struct rte_cryptodev_sym_session *sess, 485 uint8_t driver_id, void *private_data) 486 { 487 if (unlikely(sess->nb_drivers <= driver_id)) { 488 CDEV_LOG_ERR("Set private data for driver %u not allowed\n", 489 driver_id); 490 return; 491 } 492 493 sess->sess_data[driver_id].data = private_data; 494 } 495 496 static inline void * 497 get_asym_session_private_data(const struct rte_cryptodev_asym_session *sess, 498 uint8_t driver_id) { 499 return sess->sess_private_data[driver_id]; 500 } 501 502 static inline void 503 set_asym_session_private_data(struct rte_cryptodev_asym_session *sess, 504 uint8_t driver_id, void *private_data) 505 { 506 sess->sess_private_data[driver_id] = private_data; 507 } 508 509 #ifdef __cplusplus 510 } 511 #endif 512 513 #endif /* _RTE_CRYPTODEV_PMD_H_ */ 514