lib/librte_cryptodev/rte_cryptodev_pmd.h

   1 /*-
   2  *
   3  *   Copyright(c) 2015 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_dev.h>
  50 #include <rte_pci.h>
  51 #include <rte_malloc.h>
  52 #include <rte_mbuf.h>
  53 #include <rte_mempool.h>
  54 #include <rte_log.h>
  55
  56 #include "rte_crypto.h"
  57 #include "rte_cryptodev.h"
  58
  59 struct rte_cryptodev_stats;
  60 struct rte_cryptodev_info;
  61 struct rte_cryptodev_qp_conf;
  62
  63 enum rte_cryptodev_event_type;
  64
  65 #ifdef RTE_LIBRTE_CRYPTODEV_DEBUG
  66 #define RTE_PMD_DEBUG_TRACE(...) \
  67         rte_pmd_debug_trace(__func__, __VA_ARGS__)
  68 #else
  69 #define RTE_PMD_DEBUG_TRACE(fmt, args...)
  70 #endif
  71
  72 struct rte_cryptodev_session {
  73         struct {
  74                 uint8_t dev_id;
  75                 enum rte_cryptodev_type type;
  76                 struct rte_mempool *mp;
  77         } __rte_aligned(8);
  78
  79         char _private[0];
  80 };
  81
  82 struct rte_cryptodev_driver;
  83 struct rte_cryptodev;
  84
  85 /**
  86  * Initialisation function of a crypto driver invoked for each matching
  87  * crypto PCI device detected during the PCI probing phase.
  88  *
  89  * @param       drv     The pointer to the [matching] crypto driver structure
  90  *                      supplied by the PMD when it registered itself.
  91  * @param       dev     The dev pointer is the address of the *rte_cryptodev*
  92  *                      structure associated with the matching device and which
  93  *                      has been [automatically] allocated in the
  94  *                      *rte_crypto_devices* array.
  95  *
  96  * @return
  97  *   - 0: Success, the device is properly initialised by the driver.
  98  *        In particular, the driver MUST have set up the *dev_ops* pointer
  99  *        of the *dev* structure.
 100  *   - <0: Error code of the device initialisation failure.
 101  */
 102 typedef int (*cryptodev_init_t)(struct rte_cryptodev_driver *drv,
 103                 struct rte_cryptodev *dev);
 104
 105 /**
 106  * Finalisation function of a driver invoked for each matching
 107  * PCI device detected during the PCI closing phase.
 108  *
 109  * @param       drv     The pointer to the [matching] driver structure supplied
 110  *                      by the PMD when it registered itself.
 111  * @param       dev     The dev pointer is the address of the *rte_cryptodev*
 112  *                      structure associated with the matching device and which
 113  *                      has been [automatically] allocated in the
 114  *                      *rte_crypto_devices* array.
 115  *
 116  *  * @return
 117  *   - 0: Success, the device is properly finalised by the driver.
 118  *        In particular, the driver MUST free the *dev_ops* pointer
 119  *        of the *dev* structure.
 120  *   - <0: Error code of the device initialisation failure.
 121  */
 122 typedef int (*cryptodev_uninit_t)(const struct rte_cryptodev_driver  *drv,
 123                                 struct rte_cryptodev *dev);
 124
 125 /**
 126  * The structure associated with a PMD driver.
 127  *
 128  * Each driver acts as a PCI driver and is represented by a generic
 129  * *crypto_driver* structure that holds:
 130  *
 131  * - An *rte_pci_driver* structure (which must be the first field).
 132  *
 133  * - The *cryptodev_init* function invoked for each matching PCI device.
 134  *
 135  * - The size of the private data to allocate for each matching device.
 136  */
 137 struct rte_cryptodev_driver {
 138         struct rte_pci_driver pci_drv;  /**< The PMD is also a PCI driver. */
 139         unsigned dev_private_size;      /**< Size of device private data. */
 140
 141         cryptodev_init_t cryptodev_init;        /**< Device init function. */
 142         cryptodev_uninit_t cryptodev_uninit;    /**< Device uninit function. */
 143 };
 144
 145
 146 /** Global structure used for maintaining state of allocated crypto devices */
 147 struct rte_cryptodev_global {
 148         struct rte_cryptodev *devs;     /**< Device information array */
 149         struct rte_cryptodev_data *data[RTE_CRYPTO_MAX_DEVS];
 150         /**< Device private data */
 151         uint8_t nb_devs;                /**< Number of devices found */
 152         uint8_t max_devs;               /**< Max number of devices */
 153 };
 154
 155 /** pointer to global crypto devices data structure. */
 156 extern struct rte_cryptodev_global *rte_cryptodev_globals;
 157
 158 /**
 159  * Get the rte_cryptodev structure device pointer for the device. Assumes a
 160  * valid device index.
 161  *
 162  * @param       dev_id  Device ID value to select the device structure.
 163  *
 164  * @return
 165  *   - The rte_cryptodev structure pointer for the given device ID.
 166  */
 167 static inline struct rte_cryptodev *
 168 rte_cryptodev_pmd_get_dev(uint8_t dev_id)
 169 {
 170         return &rte_cryptodev_globals->devs[dev_id];
 171 }
 172
 173 /**
 174  * Get the rte_cryptodev structure device pointer for the named device.
 175  *
 176  * @param       name    device name to select the device structure.
 177  *
 178  * @return
 179  *   - The rte_cryptodev structure pointer for the given device ID.
 180  */
 181 static inline struct rte_cryptodev *
 182 rte_cryptodev_pmd_get_named_dev(const char *name)
 183 {
 184         struct rte_cryptodev *dev;
 185         unsigned i;
 186
 187         if (name == NULL)
 188                 return NULL;
 189
 190         for (i = 0, dev = &rte_cryptodev_globals->devs[i];
 191                         i < rte_cryptodev_globals->max_devs; i++) {
 192                 if ((dev->attached == RTE_CRYPTODEV_ATTACHED) &&
 193                                 (strcmp(dev->data->name, name) == 0))
 194                         return dev;
 195         }
 196
 197         return NULL;
 198 }
 199
 200 /**
 201  * Validate if the crypto device index is valid attached crypto device.
 202  *
 203  * @param       dev_id  Crypto device index.
 204  *
 205  * @return
 206  *   - If the device index is valid (1) or not (0).
 207  */
 208 static inline unsigned
 209 rte_cryptodev_pmd_is_valid_dev(uint8_t dev_id)
 210 {
 211         struct rte_cryptodev *dev = NULL;
 212
 213         if (dev_id >= rte_cryptodev_globals->nb_devs)
 214                 return 0;
 215
 216         dev = rte_cryptodev_pmd_get_dev(dev_id);
 217         if (dev->attached != RTE_CRYPTODEV_ATTACHED)
 218                 return 0;
 219         else
 220                 return 1;
 221 }
 222
 223 /**
 224  * The pool of rte_cryptodev structures.
 225  */
 226 extern struct rte_cryptodev *rte_cryptodevs;
 227
 228
 229 /**
 230  * Definitions of all functions exported by a driver through the
 231  * the generic structure of type *crypto_dev_ops* supplied in the
 232  * *rte_cryptodev* structure associated with a device.
 233  */
 234
 235 /**
 236  *      Function used to configure device.
 237  *
 238  * @param       dev     Crypto device pointer
 239  *
 240  * @return      Returns 0 on success
 241  */
 242 typedef int (*cryptodev_configure_t)(struct rte_cryptodev *dev);
 243
 244 /**
 245  * Function used to start a configured device.
 246  *
 247  * @param       dev     Crypto device pointer
 248  *
 249  * @return      Returns 0 on success
 250  */
 251 typedef int (*cryptodev_start_t)(struct rte_cryptodev *dev);
 252
 253 /**
 254  * Function used to stop a configured device.
 255  *
 256  * @param       dev     Crypto device pointer
 257  */
 258 typedef void (*cryptodev_stop_t)(struct rte_cryptodev *dev);
 259
 260 /**
 261  * Function used to close a configured device.
 262  *
 263  * @param       dev     Crypto device pointer
 264  * @return
 265  * - 0 on success.
 266  * - EAGAIN if can't close as device is busy
 267  */
 268 typedef int (*cryptodev_close_t)(struct rte_cryptodev *dev);
 269
 270
 271 /**
 272  * Function used to get statistics of a device.
 273  *
 274  * @param       dev     Crypto device pointer
 275  * @param       stats   Pointer to crypto device stats structure to populate
 276  */
 277 typedef void (*cryptodev_stats_get_t)(struct rte_cryptodev *dev,
 278                                 struct rte_cryptodev_stats *stats);
 279
 280
 281 /**
 282  * Function used to reset statistics of a device.
 283  *
 284  * @param       dev     Crypto device pointer
 285  */
 286 typedef void (*cryptodev_stats_reset_t)(struct rte_cryptodev *dev);
 287
 288
 289 /**
 290  * Function used to get specific information of a device.
 291  *
 292  * @param       dev     Crypto device pointer
 293  */
 294 typedef void (*cryptodev_info_get_t)(struct rte_cryptodev *dev,
 295                                 struct rte_cryptodev_info *dev_info);
 296
 297 /**
 298  * Start queue pair of a device.
 299  *
 300  * @param       dev     Crypto device pointer
 301  * @param       qp_id   Queue Pair Index
 302  *
 303  * @return      Returns 0 on success.
 304  */
 305 typedef int (*cryptodev_queue_pair_start_t)(struct rte_cryptodev *dev,
 306                                 uint16_t qp_id);
 307
 308 /**
 309  * Stop queue pair of a device.
 310  *
 311  * @param       dev     Crypto device pointer
 312  * @param       qp_id   Queue Pair Index
 313  *
 314  * @return      Returns 0 on success.
 315  */
 316 typedef int (*cryptodev_queue_pair_stop_t)(struct rte_cryptodev *dev,
 317                                 uint16_t qp_id);
 318
 319 /**
 320  * Setup a queue pair for a device.
 321  *
 322  * @param       dev             Crypto device pointer
 323  * @param       qp_id           Queue Pair Index
 324  * @param       qp_conf         Queue configuration structure
 325  * @param       socket_id       Socket Index
 326  *
 327  * @return      Returns 0 on success.
 328  */
 329 typedef int (*cryptodev_queue_pair_setup_t)(struct rte_cryptodev *dev,
 330                 uint16_t qp_id, const struct rte_cryptodev_qp_conf *qp_conf,
 331                 int socket_id);
 332
 333 /**
 334  * Release memory resources allocated by given queue pair.
 335  *
 336  * @param       dev     Crypto device pointer
 337  * @param       qp_id   Queue Pair Index
 338  *
 339  * @return
 340  * - 0 on success.
 341  * - EAGAIN if can't close as device is busy
 342  */
 343 typedef int (*cryptodev_queue_pair_release_t)(struct rte_cryptodev *dev,
 344                 uint16_t qp_id);
 345
 346 /**
 347  * Get number of available queue pairs of a device.
 348  *
 349  * @param       dev     Crypto device pointer
 350  *
 351  * @return      Returns number of queue pairs on success.
 352  */
 353 typedef uint32_t (*cryptodev_queue_pair_count_t)(struct rte_cryptodev *dev);
 354
 355 /**
 356  * Create a session mempool to allocate sessions from
 357  *
 358  * @param       dev             Crypto device pointer
 359  * @param       nb_objs         number of sessions objects in mempool
 360  * @param       obj_cache       l-core object cache size, see *rte_ring_create*
 361  * @param       socket_id       Socket Id to allocate  mempool on.
 362  *
 363  * @return
 364  * - On success returns a pointer to a rte_mempool
 365  * - On failure returns a NULL pointer
 366  */
 367 typedef int (*cryptodev_create_session_pool_t)(
 368                 struct rte_cryptodev *dev, unsigned nb_objs,
 369                 unsigned obj_cache_size, int socket_id);
 370
 371
 372 /**
 373  * Get the size of a cryptodev session
 374  *
 375  * @param       dev             Crypto device pointer
 376  *
 377  * @return
 378  *  - On success returns the size of the session structure for device
 379  *  - On failure returns 0
 380  */
 381 typedef unsigned (*cryptodev_get_session_private_size_t)(
 382                 struct rte_cryptodev *dev);
 383
 384 /**
 385  * Initialize a Crypto session on a device.
 386  *
 387  * @param       dev             Crypto device pointer
 388  * @param       xform           Single or chain of crypto xforms
 389  * @param       priv_sess       Pointer to cryptodev's private session structure
 390  *
 391  * @return
 392  *  - Returns private session structure on success.
 393  *  - Returns NULL on failure.
 394  */
 395 typedef void (*cryptodev_initialize_session_t)(struct rte_mempool *mempool,
 396                 void *session_private);
 397
 398 /**
 399  * Configure a Crypto session on a device.
 400  *
 401  * @param       dev             Crypto device pointer
 402  * @param       xform           Single or chain of crypto xforms
 403  * @param       priv_sess       Pointer to cryptodev's private session structure
 404  *
 405  * @return
 406  *  - Returns private session structure on success.
 407  *  - Returns NULL on failure.
 408  */
 409 typedef void * (*cryptodev_configure_session_t)(struct rte_cryptodev *dev,
 410                 struct rte_crypto_xform *xform, void *session_private);
 411
 412 /**
 413  * Free Crypto session.
 414  * @param       session         Cryptodev session structure to free
 415  */
 416 typedef void (*cryptodev_free_session_t)(struct rte_cryptodev *dev,
 417                 void *session_private);
 418
 419
 420 /** Crypto device operations function pointer table */
 421 struct rte_cryptodev_ops {
 422         cryptodev_configure_t dev_configure;    /**< Configure device. */
 423         cryptodev_start_t dev_start;            /**< Start device. */
 424         cryptodev_stop_t dev_stop;              /**< Stop device. */
 425         cryptodev_close_t dev_close;            /**< Close device. */
 426
 427         cryptodev_info_get_t dev_infos_get;     /**< Get device info. */
 428
 429         cryptodev_stats_get_t stats_get;
 430         /**< Get generic device statistics. */
 431         cryptodev_stats_reset_t stats_reset;
 432         /**< Reset generic device statistics. */
 433
 434         cryptodev_queue_pair_setup_t queue_pair_setup;
 435         /**< Set up a device queue pair. */
 436         cryptodev_queue_pair_release_t queue_pair_release;
 437         /**< Release a queue pair. */
 438         cryptodev_queue_pair_start_t queue_pair_start;
 439         /**< Start a queue pair. */
 440         cryptodev_queue_pair_stop_t queue_pair_stop;
 441         /**< Stop a queue pair. */
 442         cryptodev_queue_pair_count_t queue_pair_count;
 443         /**< Get count of the queue pairs. */
 444
 445         cryptodev_get_session_private_size_t session_get_size;
 446         /**< Return private session. */
 447         cryptodev_initialize_session_t session_initialize;
 448         /**< Initialization function for private session data */
 449         cryptodev_configure_session_t session_configure;
 450         /**< Configure a Crypto session. */
 451         cryptodev_free_session_t session_clear;
 452         /**< Clear a Crypto sessions private data. */
 453 };
 454
 455
 456 /**
 457  * Function for internal use by dummy drivers primarily, e.g. ring-based
 458  * driver.
 459  * Allocates a new cryptodev slot for an crypto device and returns the pointer
 460  * to that slot for the driver to use.
 461  *
 462  * @param       name            Unique identifier name for each device
 463  * @param       type            Device type of this Crypto device
 464  * @param       socket_id       Socket to allocate resources on.
 465  * @return
 466  *   - Slot in the rte_dev_devices array for a new device;
 467  */
 468 struct rte_cryptodev *
 469 rte_cryptodev_pmd_allocate(const char *name, enum pmd_type type, int socket_id);
 470
 471 /**
 472  * Creates a new virtual crypto device and returns the pointer
 473  * to that device.
 474  *
 475  * @param       name                    PMD type name
 476  * @param       dev_private_size        Size of crypto PMDs private data
 477  * @param       socket_id               Socket to allocate resources on.
 478  *
 479  * @return
 480  *   - Cryptodev pointer if device is successfully created.
 481  *   - NULL if device cannot be created.
 482  */
 483 struct rte_cryptodev *
 484 rte_cryptodev_pmd_virtual_dev_init(const char *name, size_t dev_private_size,
 485                 int socket_id);
 486
 487
 488 /**
 489  * Function for internal use by dummy drivers primarily, e.g. ring-based
 490  * driver.
 491  * Release the specified cryptodev device.
 492  *
 493  * @param cryptodev
 494  * The *cryptodev* pointer is the address of the *rte_cryptodev* structure.
 495  * @return
 496  *   - 0 on success, negative on error
 497  */
 498 extern int
 499 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev);
 500
 501
 502 /**
 503  * Register a Crypto [Poll Mode] driver.
 504  *
 505  * Function invoked by the initialization function of a Crypto driver
 506  * to simultaneously register itself as Crypto Poll Mode Driver and to either:
 507  *
 508  *      a - register itself as PCI driver if the crypto device is a physical
 509  *              device, by invoking the rte_eal_pci_register() function to
 510  *              register the *pci_drv* structure embedded in the *crypto_drv*
 511  *              structure, after having stored the address of the
 512  *              rte_cryptodev_init() function in the *devinit* field of the
 513  *              *pci_drv* structure.
 514  *
 515  *              During the PCI probing phase, the rte_cryptodev_init()
 516  *              function is invoked for each PCI [device] matching the
 517  *              embedded PCI identifiers provided by the driver.
 518  *
 519  *      b, complete the initialization sequence if the device is a virtual
 520  *              device by calling the rte_cryptodev_init() directly passing a
 521  *              NULL parameter for the rte_pci_device structure.
 522  *
 523  *   @param crypto_drv  crypto_driver structure associated with the crypto
 524  *                                      driver.
 525  *   @param type                pmd type
 526  */
 527 extern int
 528 rte_cryptodev_pmd_driver_register(struct rte_cryptodev_driver *crypto_drv,
 529                 enum pmd_type type);
 530
 531 /**
 532  * Executes all the user application registered callbacks for the specific
 533  * device.
 534  *  *
 535  * @param       dev     Pointer to cryptodev struct
 536  * @param       event   Crypto device interrupt event type.
 537  *
 538  * @return
 539  *  void
 540  */
 541 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev,
 542                                 enum rte_cryptodev_event_type event);
 543
 544
 545 #ifdef __cplusplus
 546 }
 547 #endif
 548
 549 #endif /* _RTE_CRYPTODEV_PMD_H_ */