3 * Copyright(c) 2015 Intel Corporation. All rights reserved.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
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
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.
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.
32 #ifndef _RTE_CRYPTODEV_PMD_H_
33 #define _RTE_CRYPTODEV_PMD_H_
39 * These API are from crypto PMD only and user applications should not call
51 #include <rte_malloc.h>
53 #include <rte_mempool.h>
56 #include "rte_crypto.h"
57 #include "rte_cryptodev.h"
59 struct rte_cryptodev_stats;
60 struct rte_cryptodev_info;
61 struct rte_cryptodev_qp_conf;
63 enum rte_cryptodev_event_type;
65 #ifdef RTE_LIBRTE_CRYPTODEV_DEBUG
66 #define RTE_PMD_DEBUG_TRACE(...) \
67 rte_pmd_debug_trace(__func__, __VA_ARGS__)
69 #define RTE_PMD_DEBUG_TRACE(fmt, args...)
72 struct rte_cryptodev_session {
75 enum rte_cryptodev_type type;
76 struct rte_mempool *mp;
82 struct rte_cryptodev_driver;
86 * Initialisation function of a crypto driver invoked for each matching
87 * crypto PCI device detected during the PCI probing phase.
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.
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.
102 typedef int (*cryptodev_init_t)(struct rte_cryptodev_driver *drv,
103 struct rte_cryptodev *dev);
106 * Finalisation function of a driver invoked for each matching
107 * PCI device detected during the PCI closing phase.
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.
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.
122 typedef int (*cryptodev_uninit_t)(const struct rte_cryptodev_driver *drv,
123 struct rte_cryptodev *dev);
126 * The structure associated with a PMD driver.
128 * Each driver acts as a PCI driver and is represented by a generic
129 * *crypto_driver* structure that holds:
131 * - An *rte_pci_driver* structure (which must be the first field).
133 * - The *cryptodev_init* function invoked for each matching PCI device.
135 * - The size of the private data to allocate for each matching device.
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. */
141 cryptodev_init_t cryptodev_init; /**< Device init function. */
142 cryptodev_uninit_t cryptodev_uninit; /**< Device uninit function. */
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 */
155 /** pointer to global crypto devices data structure. */
156 extern struct rte_cryptodev_global *rte_cryptodev_globals;
159 * Get the rte_cryptodev structure device pointer for the device. Assumes a
160 * valid device index.
162 * @param dev_id Device ID value to select the device structure.
165 * - The rte_cryptodev structure pointer for the given device ID.
167 static inline struct rte_cryptodev *
168 rte_cryptodev_pmd_get_dev(uint8_t dev_id)
170 return &rte_cryptodev_globals->devs[dev_id];
174 * Get the rte_cryptodev structure device pointer for the named device.
176 * @param name device name to select the device structure.
179 * - The rte_cryptodev structure pointer for the given device ID.
181 static inline struct rte_cryptodev *
182 rte_cryptodev_pmd_get_named_dev(const char *name)
184 struct rte_cryptodev *dev;
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))
201 * Validate if the crypto device index is valid attached crypto device.
203 * @param dev_id Crypto device index.
206 * - If the device index is valid (1) or not (0).
208 static inline unsigned
209 rte_cryptodev_pmd_is_valid_dev(uint8_t dev_id)
211 struct rte_cryptodev *dev = NULL;
213 if (dev_id >= rte_cryptodev_globals->nb_devs)
216 dev = rte_cryptodev_pmd_get_dev(dev_id);
217 if (dev->attached != RTE_CRYPTODEV_ATTACHED)
224 * The pool of rte_cryptodev structures.
226 extern struct rte_cryptodev *rte_cryptodevs;
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.
236 * Function used to configure device.
238 * @param dev Crypto device pointer
240 * @return Returns 0 on success
242 typedef int (*cryptodev_configure_t)(struct rte_cryptodev *dev);
245 * Function used to start a configured device.
247 * @param dev Crypto device pointer
249 * @return Returns 0 on success
251 typedef int (*cryptodev_start_t)(struct rte_cryptodev *dev);
254 * Function used to stop a configured device.
256 * @param dev Crypto device pointer
258 typedef void (*cryptodev_stop_t)(struct rte_cryptodev *dev);
261 * Function used to close a configured device.
263 * @param dev Crypto device pointer
266 * - EAGAIN if can't close as device is busy
268 typedef int (*cryptodev_close_t)(struct rte_cryptodev *dev);
272 * Function used to get statistics of a device.
274 * @param dev Crypto device pointer
275 * @param stats Pointer to crypto device stats structure to populate
277 typedef void (*cryptodev_stats_get_t)(struct rte_cryptodev *dev,
278 struct rte_cryptodev_stats *stats);
282 * Function used to reset statistics of a device.
284 * @param dev Crypto device pointer
286 typedef void (*cryptodev_stats_reset_t)(struct rte_cryptodev *dev);
290 * Function used to get specific information of a device.
292 * @param dev Crypto device pointer
294 typedef void (*cryptodev_info_get_t)(struct rte_cryptodev *dev,
295 struct rte_cryptodev_info *dev_info);
298 * Start queue pair of a device.
300 * @param dev Crypto device pointer
301 * @param qp_id Queue Pair Index
303 * @return Returns 0 on success.
305 typedef int (*cryptodev_queue_pair_start_t)(struct rte_cryptodev *dev,
309 * Stop queue pair of a device.
311 * @param dev Crypto device pointer
312 * @param qp_id Queue Pair Index
314 * @return Returns 0 on success.
316 typedef int (*cryptodev_queue_pair_stop_t)(struct rte_cryptodev *dev,
320 * Setup a queue pair for a device.
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
327 * @return Returns 0 on success.
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,
334 * Release memory resources allocated by given queue pair.
336 * @param dev Crypto device pointer
337 * @param qp_id Queue Pair Index
341 * - EAGAIN if can't close as device is busy
343 typedef int (*cryptodev_queue_pair_release_t)(struct rte_cryptodev *dev,
347 * Get number of available queue pairs of a device.
349 * @param dev Crypto device pointer
351 * @return Returns number of queue pairs on success.
353 typedef uint32_t (*cryptodev_queue_pair_count_t)(struct rte_cryptodev *dev);
356 * Create a session mempool to allocate sessions from
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.
364 * - On success returns a pointer to a rte_mempool
365 * - On failure returns a NULL pointer
367 typedef int (*cryptodev_create_session_pool_t)(
368 struct rte_cryptodev *dev, unsigned nb_objs,
369 unsigned obj_cache_size, int socket_id);
373 * Get the size of a cryptodev session
375 * @param dev Crypto device pointer
378 * - On success returns the size of the session structure for device
379 * - On failure returns 0
381 typedef unsigned (*cryptodev_get_session_private_size_t)(
382 struct rte_cryptodev *dev);
385 * Initialize a Crypto session on a device.
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
392 * - Returns private session structure on success.
393 * - Returns NULL on failure.
395 typedef void (*cryptodev_initialize_session_t)(struct rte_mempool *mempool,
396 void *session_private);
399 * Configure a Crypto session on a device.
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
406 * - Returns private session structure on success.
407 * - Returns NULL on failure.
409 typedef void * (*cryptodev_configure_session_t)(struct rte_cryptodev *dev,
410 struct rte_crypto_xform *xform, void *session_private);
413 * Free Crypto session.
414 * @param session Cryptodev session structure to free
416 typedef void (*cryptodev_free_session_t)(struct rte_cryptodev *dev,
417 void *session_private);
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. */
427 cryptodev_info_get_t dev_infos_get; /**< Get device info. */
429 cryptodev_stats_get_t stats_get;
430 /**< Get generic device statistics. */
431 cryptodev_stats_reset_t stats_reset;
432 /**< Reset generic device statistics. */
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. */
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. */
457 * Function for internal use by dummy drivers primarily, e.g. ring-based
459 * Allocates a new cryptodev slot for an crypto device and returns the pointer
460 * to that slot for the driver to use.
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.
466 * - Slot in the rte_dev_devices array for a new device;
468 struct rte_cryptodev *
469 rte_cryptodev_pmd_allocate(const char *name, enum pmd_type type, int socket_id);
472 * Creates a new virtual crypto device and returns the pointer
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.
480 * - Cryptodev pointer if device is successfully created.
481 * - NULL if device cannot be created.
483 struct rte_cryptodev *
484 rte_cryptodev_pmd_virtual_dev_init(const char *name, size_t dev_private_size,
489 * Function for internal use by dummy drivers primarily, e.g. ring-based
491 * Release the specified cryptodev device.
494 * The *cryptodev* pointer is the address of the *rte_cryptodev* structure.
496 * - 0 on success, negative on error
499 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev);
503 * Register a Crypto [Poll Mode] driver.
505 * Function invoked by the initialization function of a Crypto driver
506 * to simultaneously register itself as Crypto Poll Mode Driver and to either:
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.
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.
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.
523 * @param crypto_drv crypto_driver structure associated with the crypto
525 * @param type pmd type
528 rte_cryptodev_pmd_driver_register(struct rte_cryptodev_driver *crypto_drv,
532 * Executes all the user application registered callbacks for the specific
535 * @param dev Pointer to cryptodev struct
536 * @param event Crypto device interrupt event type.
541 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev,
542 enum rte_cryptodev_event_type event);
549 #endif /* _RTE_CRYPTODEV_PMD_H_ */