3 * Copyright(c) 2015-2016 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"
60 #ifdef RTE_LIBRTE_CRYPTODEV_DEBUG
61 #define RTE_PMD_DEBUG_TRACE(...) \
62 rte_pmd_debug_trace(__func__, __VA_ARGS__)
64 #define RTE_PMD_DEBUG_TRACE(fmt, args...)
67 struct rte_cryptodev_session {
70 enum rte_cryptodev_type type;
71 struct rte_mempool *mp;
77 struct rte_cryptodev_driver;
80 * Initialisation function of a crypto driver invoked for each matching
81 * crypto PCI device detected during the PCI probing phase.
83 * @param drv The pointer to the [matching] crypto driver structure
84 * supplied by the PMD when it registered itself.
85 * @param dev The dev pointer is the address of the *rte_cryptodev*
86 * structure associated with the matching device and which
87 * has been [automatically] allocated in the
88 * *rte_crypto_devices* array.
91 * - 0: Success, the device is properly initialised by the driver.
92 * In particular, the driver MUST have set up the *dev_ops* pointer
93 * of the *dev* structure.
94 * - <0: Error code of the device initialisation failure.
96 typedef int (*cryptodev_init_t)(struct rte_cryptodev_driver *drv,
97 struct rte_cryptodev *dev);
100 * Finalisation function of a driver invoked for each matching
101 * PCI device detected during the PCI closing phase.
103 * @param drv The pointer to the [matching] driver structure supplied
104 * by the PMD when it registered itself.
105 * @param dev The dev pointer is the address of the *rte_cryptodev*
106 * structure associated with the matching device and which
107 * has been [automatically] allocated in the
108 * *rte_crypto_devices* array.
111 * - 0: Success, the device is properly finalised by the driver.
112 * In particular, the driver MUST free the *dev_ops* pointer
113 * of the *dev* structure.
114 * - <0: Error code of the device initialisation failure.
116 typedef int (*cryptodev_uninit_t)(const struct rte_cryptodev_driver *drv,
117 struct rte_cryptodev *dev);
120 * The structure associated with a PMD driver.
122 * Each driver acts as a PCI driver and is represented by a generic
123 * *crypto_driver* structure that holds:
125 * - An *rte_pci_driver* structure (which must be the first field).
127 * - The *cryptodev_init* function invoked for each matching PCI device.
129 * - The size of the private data to allocate for each matching device.
131 struct rte_cryptodev_driver {
132 struct rte_pci_driver pci_drv; /**< The PMD is also a PCI driver. */
133 unsigned dev_private_size; /**< Size of device private data. */
135 cryptodev_init_t cryptodev_init; /**< Device init function. */
136 cryptodev_uninit_t cryptodev_uninit; /**< Device uninit function. */
140 /** Global structure used for maintaining state of allocated crypto devices */
141 struct rte_cryptodev_global {
142 struct rte_cryptodev *devs; /**< Device information array */
143 struct rte_cryptodev_data *data[RTE_CRYPTO_MAX_DEVS];
144 /**< Device private data */
145 uint8_t nb_devs; /**< Number of devices found */
146 uint8_t max_devs; /**< Max number of devices */
149 /** pointer to global crypto devices data structure. */
150 extern struct rte_cryptodev_global *rte_cryptodev_globals;
153 * Get the rte_cryptodev structure device pointer for the device. Assumes a
154 * valid device index.
156 * @param dev_id Device ID value to select the device structure.
159 * - The rte_cryptodev structure pointer for the given device ID.
161 static inline struct rte_cryptodev *
162 rte_cryptodev_pmd_get_dev(uint8_t dev_id)
164 return &rte_cryptodev_globals->devs[dev_id];
168 * Get the rte_cryptodev structure device pointer for the named device.
170 * @param name device name to select the device structure.
173 * - The rte_cryptodev structure pointer for the given device ID.
175 static inline struct rte_cryptodev *
176 rte_cryptodev_pmd_get_named_dev(const char *name)
178 struct rte_cryptodev *dev;
184 for (i = 0, dev = &rte_cryptodev_globals->devs[i];
185 i < rte_cryptodev_globals->max_devs; i++) {
186 if ((dev->attached == RTE_CRYPTODEV_ATTACHED) &&
187 (strcmp(dev->data->name, name) == 0))
195 * Validate if the crypto device index is valid attached crypto device.
197 * @param dev_id Crypto device index.
200 * - If the device index is valid (1) or not (0).
202 static inline unsigned
203 rte_cryptodev_pmd_is_valid_dev(uint8_t dev_id)
205 struct rte_cryptodev *dev = NULL;
207 if (dev_id >= rte_cryptodev_globals->nb_devs)
210 dev = rte_cryptodev_pmd_get_dev(dev_id);
211 if (dev->attached != RTE_CRYPTODEV_ATTACHED)
218 * The pool of rte_cryptodev structures.
220 extern struct rte_cryptodev *rte_cryptodevs;
224 * Definitions of all functions exported by a driver through the
225 * the generic structure of type *crypto_dev_ops* supplied in the
226 * *rte_cryptodev* structure associated with a device.
230 * Function used to configure device.
232 * @param dev Crypto device pointer
234 * @return Returns 0 on success
236 typedef int (*cryptodev_configure_t)(struct rte_cryptodev *dev);
239 * Function used to start a configured device.
241 * @param dev Crypto device pointer
243 * @return Returns 0 on success
245 typedef int (*cryptodev_start_t)(struct rte_cryptodev *dev);
248 * Function used to stop a configured device.
250 * @param dev Crypto device pointer
252 typedef void (*cryptodev_stop_t)(struct rte_cryptodev *dev);
255 * Function used to close a configured device.
257 * @param dev Crypto device pointer
260 * - EAGAIN if can't close as device is busy
262 typedef int (*cryptodev_close_t)(struct rte_cryptodev *dev);
266 * Function used to get statistics of a device.
268 * @param dev Crypto device pointer
269 * @param stats Pointer to crypto device stats structure to populate
271 typedef void (*cryptodev_stats_get_t)(struct rte_cryptodev *dev,
272 struct rte_cryptodev_stats *stats);
276 * Function used to reset statistics of a device.
278 * @param dev Crypto device pointer
280 typedef void (*cryptodev_stats_reset_t)(struct rte_cryptodev *dev);
284 * Function used to get specific information of a device.
286 * @param dev Crypto device pointer
288 typedef void (*cryptodev_info_get_t)(struct rte_cryptodev *dev,
289 struct rte_cryptodev_info *dev_info);
292 * Start queue pair of a device.
294 * @param dev Crypto device pointer
295 * @param qp_id Queue Pair Index
297 * @return Returns 0 on success.
299 typedef int (*cryptodev_queue_pair_start_t)(struct rte_cryptodev *dev,
303 * Stop queue pair of a device.
305 * @param dev Crypto device pointer
306 * @param qp_id Queue Pair Index
308 * @return Returns 0 on success.
310 typedef int (*cryptodev_queue_pair_stop_t)(struct rte_cryptodev *dev,
314 * Setup a queue pair for a device.
316 * @param dev Crypto device pointer
317 * @param qp_id Queue Pair Index
318 * @param qp_conf Queue configuration structure
319 * @param socket_id Socket Index
321 * @return Returns 0 on success.
323 typedef int (*cryptodev_queue_pair_setup_t)(struct rte_cryptodev *dev,
324 uint16_t qp_id, const struct rte_cryptodev_qp_conf *qp_conf,
328 * Release memory resources allocated by given queue pair.
330 * @param dev Crypto device pointer
331 * @param qp_id Queue Pair Index
335 * - EAGAIN if can't close as device is busy
337 typedef int (*cryptodev_queue_pair_release_t)(struct rte_cryptodev *dev,
341 * Get number of available queue pairs of a device.
343 * @param dev Crypto device pointer
345 * @return Returns number of queue pairs on success.
347 typedef uint32_t (*cryptodev_queue_pair_count_t)(struct rte_cryptodev *dev);
350 * Create a session mempool to allocate sessions from
352 * @param dev Crypto device pointer
353 * @param nb_objs number of sessions objects in mempool
354 * @param obj_cache l-core object cache size, see *rte_ring_create*
355 * @param socket_id Socket Id to allocate mempool on.
358 * - On success returns a pointer to a rte_mempool
359 * - On failure returns a NULL pointer
361 typedef int (*cryptodev_sym_create_session_pool_t)(
362 struct rte_cryptodev *dev, unsigned nb_objs,
363 unsigned obj_cache_size, int socket_id);
367 * Get the size of a cryptodev session
369 * @param dev Crypto device pointer
372 * - On success returns the size of the session structure for device
373 * - On failure returns 0
375 typedef unsigned (*cryptodev_sym_get_session_private_size_t)(
376 struct rte_cryptodev *dev);
379 * Initialize a Crypto session on a device.
381 * @param dev Crypto device pointer
382 * @param xform Single or chain of crypto xforms
383 * @param priv_sess Pointer to cryptodev's private session structure
386 * - Returns private session structure on success.
387 * - Returns NULL on failure.
389 typedef void (*cryptodev_sym_initialize_session_t)(struct rte_mempool *mempool,
390 void *session_private);
393 * Configure a Crypto session on a device.
395 * @param dev Crypto device pointer
396 * @param xform Single or chain of crypto xforms
397 * @param priv_sess Pointer to cryptodev's private session structure
400 * - Returns private session structure on success.
401 * - Returns NULL on failure.
403 typedef void * (*cryptodev_sym_configure_session_t)(struct rte_cryptodev *dev,
404 struct rte_crypto_sym_xform *xform, void *session_private);
407 * Free Crypto session.
408 * @param session Cryptodev session structure to free
410 typedef void (*cryptodev_sym_free_session_t)(struct rte_cryptodev *dev,
411 void *session_private);
414 /** Crypto device operations function pointer table */
415 struct rte_cryptodev_ops {
416 cryptodev_configure_t dev_configure; /**< Configure device. */
417 cryptodev_start_t dev_start; /**< Start device. */
418 cryptodev_stop_t dev_stop; /**< Stop device. */
419 cryptodev_close_t dev_close; /**< Close device. */
421 cryptodev_info_get_t dev_infos_get; /**< Get device info. */
423 cryptodev_stats_get_t stats_get;
424 /**< Get device statistics. */
425 cryptodev_stats_reset_t stats_reset;
426 /**< Reset device statistics. */
428 cryptodev_queue_pair_setup_t queue_pair_setup;
429 /**< Set up a device queue pair. */
430 cryptodev_queue_pair_release_t queue_pair_release;
431 /**< Release a queue pair. */
432 cryptodev_queue_pair_start_t queue_pair_start;
433 /**< Start a queue pair. */
434 cryptodev_queue_pair_stop_t queue_pair_stop;
435 /**< Stop a queue pair. */
436 cryptodev_queue_pair_count_t queue_pair_count;
437 /**< Get count of the queue pairs. */
439 cryptodev_sym_get_session_private_size_t session_get_size;
440 /**< Return private session. */
441 cryptodev_sym_initialize_session_t session_initialize;
442 /**< Initialization function for private session data */
443 cryptodev_sym_configure_session_t session_configure;
444 /**< Configure a Crypto session. */
445 cryptodev_sym_free_session_t session_clear;
446 /**< Clear a Crypto sessions private data. */
451 * Function for internal use by dummy drivers primarily, e.g. ring-based
453 * Allocates a new cryptodev slot for an crypto device and returns the pointer
454 * to that slot for the driver to use.
456 * @param name Unique identifier name for each device
457 * @param type Device type of this Crypto device
458 * @param socket_id Socket to allocate resources on.
460 * - Slot in the rte_dev_devices array for a new device;
462 struct rte_cryptodev *
463 rte_cryptodev_pmd_allocate(const char *name, enum pmd_type type, int socket_id);
466 * Creates a new virtual crypto device and returns the pointer
469 * @param name PMD type name
470 * @param dev_private_size Size of crypto PMDs private data
471 * @param socket_id Socket to allocate resources on.
474 * - Cryptodev pointer if device is successfully created.
475 * - NULL if device cannot be created.
477 struct rte_cryptodev *
478 rte_cryptodev_pmd_virtual_dev_init(const char *name, size_t dev_private_size,
483 * Function for internal use by dummy drivers primarily, e.g. ring-based
485 * Release the specified cryptodev device.
488 * The *cryptodev* pointer is the address of the *rte_cryptodev* structure.
490 * - 0 on success, negative on error
493 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev);
497 * Register a Crypto [Poll Mode] driver.
499 * Function invoked by the initialization function of a Crypto driver
500 * to simultaneously register itself as Crypto Poll Mode Driver and to either:
502 * a - register itself as PCI driver if the crypto device is a physical
503 * device, by invoking the rte_eal_pci_register() function to
504 * register the *pci_drv* structure embedded in the *crypto_drv*
505 * structure, after having stored the address of the
506 * rte_cryptodev_init() function in the *devinit* field of the
507 * *pci_drv* structure.
509 * During the PCI probing phase, the rte_cryptodev_init()
510 * function is invoked for each PCI [device] matching the
511 * embedded PCI identifiers provided by the driver.
513 * b, complete the initialization sequence if the device is a virtual
514 * device by calling the rte_cryptodev_init() directly passing a
515 * NULL parameter for the rte_pci_device structure.
517 * @param crypto_drv crypto_driver structure associated with the crypto
519 * @param type pmd type
522 rte_cryptodev_pmd_driver_register(struct rte_cryptodev_driver *crypto_drv,
526 * Executes all the user application registered callbacks for the specific
529 * @param dev Pointer to cryptodev struct
530 * @param event Crypto device interrupt event type.
535 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev,
536 enum rte_cryptodev_event_type event);
543 #endif /* _RTE_CRYPTODEV_PMD_H_ */