lib/librte_cryptodev/rte_cryptodev_pmd.h

   1 /*-
   2  *
   3  *   Copyright(c) 2015-2016 Intel Corporation. All rights reserved.
   4  *
   5  *   Redistribution and use in source and binary forms, with or without
   6  *   modification, are permitted provided that the following conditions
   7  *   are met:
   8  *
   9  *     * Redistributions of source code must retain the above copyright
  10  *       notice, this list of conditions and the following disclaimer.
  11  *     * Redistributions in binary form must reproduce the above copyright
  12  *       notice, this list of conditions and the following disclaimer in
  13  *       the documentation and/or other materials provided with the
  14  *       distribution.
  15  *     * Neither the name of Intel Corporation nor the names of its
  16  *       contributors may be used to endorse or promote products derived
  17  *       from this software without specific prior written permission.
  18  *
  19  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 #ifndef _RTE_CRYPTODEV_PMD_H_
  33 #define _RTE_CRYPTODEV_PMD_H_
  34
  35 /** @file
  36  * RTE Crypto PMD APIs
  37  *
  38  * @note
  39  * These API are from crypto PMD only and user applications should not call
  40  * them directly.
  41  */
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 #include <string.h>
  48
  49 #include <rte_config.h>
  50 #include <rte_dev.h>
  51 #include <rte_malloc.h>
  52 #include <rte_mbuf.h>
  53 #include <rte_mempool.h>
  54 #include <rte_log.h>
  55 #include <rte_common.h>
  56
  57 #include "rte_crypto.h"
  58 #include "rte_cryptodev.h"
  59
  60
  61 #define RTE_CRYPTODEV_PMD_DEFAULT_MAX_NB_QUEUE_PAIRS    8
  62 #define RTE_CRYPTODEV_PMD_DEFAULT_MAX_NB_SESSIONS       2048
  63
  64 #define RTE_CRYPTODEV_PMD_NAME_ARG                      ("name")
  65 #define RTE_CRYPTODEV_PMD_MAX_NB_QP_ARG                 ("max_nb_queue_pairs")
  66 #define RTE_CRYPTODEV_PMD_MAX_NB_SESS_ARG               ("max_nb_sessions")
  67 #define RTE_CRYPTODEV_PMD_SOCKET_ID_ARG                 ("socket_id")
  68
  69
  70 static const char * const cryptodev_pmd_valid_params[] = {
  71         RTE_CRYPTODEV_PMD_NAME_ARG,
  72         RTE_CRYPTODEV_PMD_MAX_NB_QP_ARG,
  73         RTE_CRYPTODEV_PMD_MAX_NB_SESS_ARG,
  74         RTE_CRYPTODEV_PMD_SOCKET_ID_ARG
  75 };
  76
  77 /**
  78  * @internal
  79  * Initialisation parameters for crypto devices
  80  */
  81 struct rte_cryptodev_pmd_init_params {
  82         char name[RTE_CRYPTODEV_NAME_MAX_LEN];
  83         size_t private_data_size;
  84         int socket_id;
  85         unsigned int max_nb_queue_pairs;
  86         unsigned int max_nb_sessions;
  87 };
  88
  89 /** Global structure used for maintaining state of allocated crypto devices */
  90 struct rte_cryptodev_global {
  91         struct rte_cryptodev *devs;     /**< Device information array */
  92         struct rte_cryptodev_data *data[RTE_CRYPTO_MAX_DEVS];
  93         /**< Device private data */
  94         uint8_t nb_devs;                /**< Number of devices found */
  95         uint8_t max_devs;               /**< Max number of devices */
  96 };
  97
  98 /* Cryptodev driver, containing the driver ID */
  99 struct cryptodev_driver {
 100         TAILQ_ENTRY(cryptodev_driver) next; /**< Next in list. */
 101         const struct rte_driver *driver;
 102         uint8_t id;
 103 };
 104
 105 /** pointer to global crypto devices data structure. */
 106 extern struct rte_cryptodev_global *rte_cryptodev_globals;
 107
 108 /**
 109  * Get the rte_cryptodev structure device pointer for the device. Assumes a
 110  * valid device index.
 111  *
 112  * @param       dev_id  Device ID value to select the device structure.
 113  *
 114  * @return
 115  *   - The rte_cryptodev structure pointer for the given device ID.
 116  */
 117 struct rte_cryptodev *
 118 rte_cryptodev_pmd_get_dev(uint8_t dev_id);
 119
 120 /**
 121  * Get the rte_cryptodev structure device pointer for the named device.
 122  *
 123  * @param       name    device name to select the device structure.
 124  *
 125  * @return
 126  *   - The rte_cryptodev structure pointer for the given device ID.
 127  */
 128 struct rte_cryptodev *
 129 rte_cryptodev_pmd_get_named_dev(const char *name);
 130
 131 /**
 132  * Validate if the crypto device index is valid attached crypto device.
 133  *
 134  * @param       dev_id  Crypto device index.
 135  *
 136  * @return
 137  *   - If the device index is valid (1) or not (0).
 138  */
 139 unsigned int
 140 rte_cryptodev_pmd_is_valid_dev(uint8_t dev_id);
 141
 142 /**
 143  * The pool of rte_cryptodev structures.
 144  */
 145 extern struct rte_cryptodev *rte_cryptodevs;
 146
 147
 148 /**
 149  * Definitions of all functions exported by a driver through the
 150  * the generic structure of type *crypto_dev_ops* supplied in the
 151  * *rte_cryptodev* structure associated with a device.
 152  */
 153
 154 /**
 155  *      Function used to configure device.
 156  *
 157  * @param       dev     Crypto device pointer
 158  *              config  Crypto device configurations
 159  *
 160  * @return      Returns 0 on success
 161  */
 162 typedef int (*cryptodev_configure_t)(struct rte_cryptodev *dev,
 163                 struct rte_cryptodev_config *config);
 164
 165 /**
 166  * Function used to start a configured device.
 167  *
 168  * @param       dev     Crypto device pointer
 169  *
 170  * @return      Returns 0 on success
 171  */
 172 typedef int (*cryptodev_start_t)(struct rte_cryptodev *dev);
 173
 174 /**
 175  * Function used to stop a configured device.
 176  *
 177  * @param       dev     Crypto device pointer
 178  */
 179 typedef void (*cryptodev_stop_t)(struct rte_cryptodev *dev);
 180
 181 /**
 182  * Function used to close a configured device.
 183  *
 184  * @param       dev     Crypto device pointer
 185  * @return
 186  * - 0 on success.
 187  * - EAGAIN if can't close as device is busy
 188  */
 189 typedef int (*cryptodev_close_t)(struct rte_cryptodev *dev);
 190
 191
 192 /**
 193  * Function used to get statistics of a device.
 194  *
 195  * @param       dev     Crypto device pointer
 196  * @param       stats   Pointer to crypto device stats structure to populate
 197  */
 198 typedef void (*cryptodev_stats_get_t)(struct rte_cryptodev *dev,
 199                                 struct rte_cryptodev_stats *stats);
 200
 201
 202 /**
 203  * Function used to reset statistics of a device.
 204  *
 205  * @param       dev     Crypto device pointer
 206  */
 207 typedef void (*cryptodev_stats_reset_t)(struct rte_cryptodev *dev);
 208
 209
 210 /**
 211  * Function used to get specific information of a device.
 212  *
 213  * @param       dev     Crypto device pointer
 214  */
 215 typedef void (*cryptodev_info_get_t)(struct rte_cryptodev *dev,
 216                                 struct rte_cryptodev_info *dev_info);
 217
 218 /**
 219  * Start queue pair of a device.
 220  *
 221  * @param       dev     Crypto device pointer
 222  * @param       qp_id   Queue Pair Index
 223  *
 224  * @return      Returns 0 on success.
 225  */
 226 typedef int (*cryptodev_queue_pair_start_t)(struct rte_cryptodev *dev,
 227                                 uint16_t qp_id);
 228
 229 /**
 230  * Stop queue pair of a device.
 231  *
 232  * @param       dev     Crypto device pointer
 233  * @param       qp_id   Queue Pair Index
 234  *
 235  * @return      Returns 0 on success.
 236  */
 237 typedef int (*cryptodev_queue_pair_stop_t)(struct rte_cryptodev *dev,
 238                                 uint16_t qp_id);
 239
 240 /**
 241  * Setup a queue pair for a device.
 242  *
 243  * @param       dev             Crypto device pointer
 244  * @param       qp_id           Queue Pair Index
 245  * @param       qp_conf         Queue configuration structure
 246  * @param       socket_id       Socket Index
 247  * @param       session_pool    Pointer to device session mempool
 248  *
 249  * @return      Returns 0 on success.
 250  */
 251 typedef int (*cryptodev_queue_pair_setup_t)(struct rte_cryptodev *dev,
 252                 uint16_t qp_id, const struct rte_cryptodev_qp_conf *qp_conf,
 253                 int socket_id, struct rte_mempool *session_pool);
 254
 255 /**
 256  * Release memory resources allocated by given queue pair.
 257  *
 258  * @param       dev     Crypto device pointer
 259  * @param       qp_id   Queue Pair Index
 260  *
 261  * @return
 262  * - 0 on success.
 263  * - EAGAIN if can't close as device is busy
 264  */
 265 typedef int (*cryptodev_queue_pair_release_t)(struct rte_cryptodev *dev,
 266                 uint16_t qp_id);
 267
 268 /**
 269  * Get number of available queue pairs of a device.
 270  *
 271  * @param       dev     Crypto device pointer
 272  *
 273  * @return      Returns number of queue pairs on success.
 274  */
 275 typedef uint32_t (*cryptodev_queue_pair_count_t)(struct rte_cryptodev *dev);
 276
 277 /**
 278  * Create a session mempool to allocate sessions from
 279  *
 280  * @param       dev             Crypto device pointer
 281  * @param       nb_objs         number of sessions objects in mempool
 282  * @param       obj_cache       l-core object cache size, see *rte_ring_create*
 283  * @param       socket_id       Socket Id to allocate  mempool on.
 284  *
 285  * @return
 286  * - On success returns a pointer to a rte_mempool
 287  * - On failure returns a NULL pointer
 288  */
 289 typedef int (*cryptodev_sym_create_session_pool_t)(
 290                 struct rte_cryptodev *dev, unsigned nb_objs,
 291                 unsigned obj_cache_size, int socket_id);
 292
 293
 294 /**
 295  * Get the size of a cryptodev session
 296  *
 297  * @param       dev             Crypto device pointer
 298  *
 299  * @return
 300  *  - On success returns the size of the session structure for device
 301  *  - On failure returns 0
 302  */
 303 typedef unsigned (*cryptodev_sym_get_session_private_size_t)(
 304                 struct rte_cryptodev *dev);
 305
 306 /**
 307  * Configure a Crypto session on a device.
 308  *
 309  * @param       dev             Crypto device pointer
 310  * @param       xform           Single or chain of crypto xforms
 311  * @param       priv_sess       Pointer to cryptodev's private session structure
 312  * @param       mp              Mempool where the private session is allocated
 313  *
 314  * @return
 315  *  - Returns 0 if private session structure have been created successfully.
 316  *  - Returns -EINVAL if input parameters are invalid.
 317  *  - Returns -ENOTSUP if crypto device does not support the crypto transform.
 318  *  - Returns -ENOMEM if the private session could not be allocated.
 319  */
 320 typedef int (*cryptodev_sym_configure_session_t)(struct rte_cryptodev *dev,
 321                 struct rte_crypto_sym_xform *xform,
 322                 struct rte_cryptodev_sym_session *session,
 323                 struct rte_mempool *mp);
 324
 325 /**
 326  * Free driver private session data.
 327  *
 328  * @param       dev             Crypto device pointer
 329  * @param       sess            Cryptodev session structure
 330  */
 331 typedef void (*cryptodev_sym_free_session_t)(struct rte_cryptodev *dev,
 332                 struct rte_cryptodev_sym_session *sess);
 333
 334 /**
 335  * Optional API for drivers to attach sessions with queue pair.
 336  * @param       dev             Crypto device pointer
 337  * @param       qp_id           queue pair id for attaching session
 338  * @param       priv_sess       Pointer to cryptodev's private session structure
 339  * @return
 340  *  - Return 0 on success
 341  */
 342 typedef int (*cryptodev_sym_queue_pair_attach_session_t)(
 343                   struct rte_cryptodev *dev,
 344                   uint16_t qp_id,
 345                   void *session_private);
 346
 347 /**
 348  * Optional API for drivers to detach sessions from queue pair.
 349  * @param       dev             Crypto device pointer
 350  * @param       qp_id           queue pair id for detaching session
 351  * @param       priv_sess       Pointer to cryptodev's private session structure
 352  * @return
 353  *  - Return 0 on success
 354  */
 355 typedef int (*cryptodev_sym_queue_pair_detach_session_t)(
 356                   struct rte_cryptodev *dev,
 357                   uint16_t qp_id,
 358                   void *session_private);
 359
 360 /** Crypto device operations function pointer table */
 361 struct rte_cryptodev_ops {
 362         cryptodev_configure_t dev_configure;    /**< Configure device. */
 363         cryptodev_start_t dev_start;            /**< Start device. */
 364         cryptodev_stop_t dev_stop;              /**< Stop device. */
 365         cryptodev_close_t dev_close;            /**< Close device. */
 366
 367         cryptodev_info_get_t dev_infos_get;     /**< Get device info. */
 368
 369         cryptodev_stats_get_t stats_get;
 370         /**< Get device statistics. */
 371         cryptodev_stats_reset_t stats_reset;
 372         /**< Reset device statistics. */
 373
 374         cryptodev_queue_pair_setup_t queue_pair_setup;
 375         /**< Set up a device queue pair. */
 376         cryptodev_queue_pair_release_t queue_pair_release;
 377         /**< Release a queue pair. */
 378         cryptodev_queue_pair_start_t queue_pair_start;
 379         /**< Start a queue pair. */
 380         cryptodev_queue_pair_stop_t queue_pair_stop;
 381         /**< Stop a queue pair. */
 382         cryptodev_queue_pair_count_t queue_pair_count;
 383         /**< Get count of the queue pairs. */
 384
 385         cryptodev_sym_get_session_private_size_t session_get_size;
 386         /**< Return private session. */
 387         cryptodev_sym_configure_session_t session_configure;
 388         /**< Configure a Crypto session. */
 389         cryptodev_sym_free_session_t session_clear;
 390         /**< Clear a Crypto sessions private data. */
 391         cryptodev_sym_queue_pair_attach_session_t qp_attach_session;
 392         /**< Attach session to queue pair. */
 393         cryptodev_sym_queue_pair_detach_session_t qp_detach_session;
 394         /**< Detach session from queue pair. */
 395 };
 396
 397
 398 /**
 399  * Function for internal use by dummy drivers primarily, e.g. ring-based
 400  * driver.
 401  * Allocates a new cryptodev slot for an crypto device and returns the pointer
 402  * to that slot for the driver to use.
 403  *
 404  * @param       name            Unique identifier name for each device
 405  * @param       socket_id       Socket to allocate resources on.
 406  * @return
 407  *   - Slot in the rte_dev_devices array for a new device;
 408  */
 409 struct rte_cryptodev *
 410 rte_cryptodev_pmd_allocate(const char *name, int socket_id);
 411
 412 /**
 413  * Function for internal use by dummy drivers primarily, e.g. ring-based
 414  * driver.
 415  * Release the specified cryptodev device.
 416  *
 417  * @param cryptodev
 418  * The *cryptodev* pointer is the address of the *rte_cryptodev* structure.
 419  * @return
 420  *   - 0 on success, negative on error
 421  */
 422 extern int
 423 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev);
 424
 425
 426 /**
 427  * @internal
 428  *
 429  * PMD assist function to parse initialisation arguments for crypto driver
 430  * when creating a new crypto PMD device instance.
 431  *
 432  * PMD driver should set default values for that PMD before calling function,
 433  * these default values will be over-written with successfully parsed values
 434  * from args string.
 435  *
 436  * @param       params  parsed PMD initialisation parameters
 437  * @param       args    input argument string to parse
 438  *
 439  * @return
 440  *  - 0 on success
 441  *  - errno on failure
 442  */
 443 int
 444 rte_cryptodev_pmd_parse_input_args(
 445                 struct rte_cryptodev_pmd_init_params *params,
 446                 const char *args);
 447
 448 /**
 449  * @internal
 450  *
 451  * PMD assist function to provide boiler plate code for crypto driver to create
 452  * and allocate resources for a new crypto PMD device instance.
 453  *
 454  * @param       name    crypto device name.
 455  * @param       device  base device instance
 456  * @param       params  PMD initialisation parameters
 457  *
 458  * @return
 459  *  - crypto device instance on success
 460  *  - NULL on creation failure
 461  */
 462 struct rte_cryptodev *
 463 rte_cryptodev_pmd_create(const char *name,
 464                 struct rte_device *device,
 465                 struct rte_cryptodev_pmd_init_params *params);
 466
 467 /**
 468  * @internal
 469  *
 470  * PMD assist function to provide boiler plate code for crypto driver to
 471  * destroy and free resources associated with a crypto PMD device instance.
 472  *
 473  * @param       cryptodev       crypto device handle.
 474  *
 475  * @return
 476  *  - 0 on success
 477  *  - errno on failure
 478  */
 479 int
 480 rte_cryptodev_pmd_destroy(struct rte_cryptodev *cryptodev);
 481
 482 /**
 483  * Executes all the user application registered callbacks for the specific
 484  * device.
 485  *  *
 486  * @param       dev     Pointer to cryptodev struct
 487  * @param       event   Crypto device interrupt event type.
 488  *
 489  * @return
 490  *  void
 491  */
 492 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev,
 493                                 enum rte_cryptodev_event_type event);
 494
 495 /**
 496  * @internal
 497  * Create unique device name
 498  */
 499 int
 500 rte_cryptodev_pmd_create_dev_name(char *name, const char *dev_name_prefix);
 501
 502 /**
 503  * @internal
 504  * Allocate Cryptodev driver.
 505  *
 506  * @param crypto_drv
 507  *   Pointer to cryptodev_driver.
 508  * @param drv
 509  *   Pointer to rte_driver.
 510  *
 511  * @return
 512  *  The driver type identifier
 513  */
 514 uint8_t rte_cryptodev_allocate_driver(struct cryptodev_driver *crypto_drv,
 515                 const struct rte_driver *drv);
 516
 517
 518 #define RTE_PMD_REGISTER_CRYPTO_DRIVER(crypto_drv, drv, driver_id)\
 519 RTE_INIT(init_ ##driver_id);\
 520 static void init_ ##driver_id(void)\
 521 {\
 522         driver_id = rte_cryptodev_allocate_driver(&crypto_drv, &(drv).driver);\
 523 }
 524
 525 static inline void *
 526 get_session_private_data(const struct rte_cryptodev_sym_session *sess,
 527                 uint8_t driver_id) {
 528         return sess->sess_private_data[driver_id];
 529 }
 530
 531 static inline void
 532 set_session_private_data(struct rte_cryptodev_sym_session *sess,
 533                 uint8_t driver_id, void *private_data)
 534 {
 535         sess->sess_private_data[driver_id] = private_data;
 536 }
 537
 538 #ifdef __cplusplus
 539 }
 540 #endif
 541
 542 #endif /* _RTE_CRYPTODEV_PMD_H_ */