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_H_
33 #define _RTE_CRYPTODEV_H_
36 * @file rte_cryptodev.h
38 * RTE Cryptographic Device APIs
40 * Defines RTE Crypto Device APIs for the provisioning of cipher and
41 * authentication operations.
44 * @b EXPERIMENTAL: this API may change without prior notice
53 #include "rte_crypto.h"
56 #define CRYPTODEV_NAME_NULL_PMD ("cryptodev_null_pmd")
57 /**< Null crypto PMD device name */
58 #define CRYPTODEV_NAME_AESNI_MB_PMD ("cryptodev_aesni_mb_pmd")
59 /**< AES-NI Multi buffer PMD device name */
60 #define CRYPTODEV_NAME_QAT_SYM_PMD ("cryptodev_qat_sym_pmd")
61 /**< Intel QAT Symmetric Crypto PMD device name */
63 /** Crypto device type */
64 enum rte_cryptodev_type {
65 RTE_CRYPTODEV_NULL_PMD = 1, /**< Null crypto PMD */
66 RTE_CRYPTODEV_AESNI_MB_PMD, /**< AES-NI multi buffer PMD */
67 RTE_CRYPTODEV_QAT_SYM_PMD, /**< QAT PMD Symmetric Crypto */
72 #define CDEV_LOG_ERR(fmt, args...) \
73 RTE_LOG(ERR, CRYPTODEV, "%s() line %u: " fmt "\n", \
74 __func__, __LINE__, ## args)
76 #define CDEV_PMD_LOG_ERR(dev, fmt, args...) \
77 RTE_LOG(ERR, CRYPTODEV, "[%s] %s() line %u: " fmt "\n", \
78 dev, __func__, __LINE__, ## args)
80 #ifdef RTE_LIBRTE_CRYPTODEV_DEBUG
81 #define CDEV_LOG_DEBUG(fmt, args...) \
82 RTE_LOG(DEBUG, CRYPTODEV, "%s() line %u: " fmt "\n", \
83 __func__, __LINE__, ## args) \
85 #define CDEV_PMD_TRACE(fmt, args...) \
86 RTE_LOG(DEBUG, CRYPTODEV, "[%s] %s: " fmt "\n", \
87 dev, __func__, ## args)
90 #define CDEV_LOG_DEBUG(fmt, args...)
91 #define CDEV_PMD_TRACE(fmt, args...)
94 /** Crypto device information */
95 struct rte_cryptodev_info {
96 const char *driver_name; /**< Driver name. */
97 enum rte_cryptodev_type dev_type; /**< Device type */
98 struct rte_pci_device *pci_dev; /**< PCI information. */
100 unsigned max_nb_queue_pairs;
101 /**< Maximum number of queues pairs supported by device. */
104 unsigned max_nb_sessions;
105 /**< Maximum number of sessions supported by device. */
109 #define RTE_CRYPTODEV_DETACHED (0)
110 #define RTE_CRYPTODEV_ATTACHED (1)
112 /** Definitions of Crypto device event types */
113 enum rte_cryptodev_event_type {
114 RTE_CRYPTODEV_EVENT_UNKNOWN, /**< unknown event type */
115 RTE_CRYPTODEV_EVENT_ERROR, /**< error interrupt event */
116 RTE_CRYPTODEV_EVENT_MAX /**< max value of this enum */
119 /** Crypto device queue pair configuration structure. */
120 struct rte_cryptodev_qp_conf {
121 uint32_t nb_descriptors; /**< Number of descriptors per queue pair */
125 * Typedef for application callback function to be registered by application
126 * software for notification of device events
128 * @param dev_id Crypto device identifier
129 * @param event Crypto device event to register for notification of.
130 * @param cb_arg User specified parameter to be passed as to passed to
131 * users callback function.
133 typedef void (*rte_cryptodev_cb_fn)(uint8_t dev_id,
134 enum rte_cryptodev_event_type event, void *cb_arg);
137 /** Crypto Device statistics */
138 struct rte_cryptodev_stats {
139 uint64_t enqueued_count;
140 /**< Count of all operations enqueued */
141 uint64_t dequeued_count;
142 /**< Count of all operations dequeued */
144 uint64_t enqueue_err_count;
145 /**< Total error count on operations enqueued */
146 uint64_t dequeue_err_count;
147 /**< Total error count on operations dequeued */
152 * Create a virtual crypto device
154 * @param name Cryptodev PMD name of device to be created.
155 * @param args Options arguments for device.
158 * - On successful creation of the cryptodev the device index is returned,
159 * which will be between 0 and rte_cryptodev_count().
160 * - In the case of a failure, returns -1.
163 rte_cryptodev_create_vdev(const char *name, const char *args);
166 * Get the device identifier for the named crypto device.
168 * @param name device name to select the device structure.
171 * - Returns crypto device identifier on success.
172 * - Return -1 on failure to find named crypto device.
175 rte_cryptodev_get_dev_id(const char *name);
178 * Get the total number of crypto devices that have been successfully
182 * - The total number of usable crypto devices.
185 rte_cryptodev_count(void);
188 rte_cryptodev_count_devtype(enum rte_cryptodev_type type);
190 * Return the NUMA socket to which a device is connected
193 * The identifier of the device
195 * The NUMA socket id to which the device is connected or
196 * a default of zero if the socket could not be determined.
197 * -1 if returned is the dev_id value is out of range.
200 rte_cryptodev_socket_id(uint8_t dev_id);
202 /** Crypto device configuration structure */
203 struct rte_cryptodev_config {
204 int socket_id; /**< Socket to allocate resources on */
205 uint16_t nb_queue_pairs;
206 /**< Number of queue pairs to configure on device */
209 uint32_t nb_objs; /**< Number of objects in mempool */
210 uint32_t cache_size; /**< l-core object cache size */
211 } session_mp; /**< Session mempool configuration */
215 * Configure a device.
217 * EXPERIMENTAL: this API file may change without prior notice
219 * This function must be invoked first before any other function in the
220 * API. This function can also be re-invoked when a device is in the
223 * @param dev_id The identifier of the device to configure.
224 * @param config The crypto device configuration structure.
227 * - 0: Success, device configured.
228 * - <0: Error code returned by the driver configuration function.
231 rte_cryptodev_configure(uint8_t dev_id, struct rte_cryptodev_config *config);
236 * The device start step is the last one and consists of setting the configured
237 * offload features and in starting the transmit and the receive units of the
239 * On success, all basic functions exported by the API (link status,
240 * receive/transmit, and so on) can be invoked.
243 * The identifier of the device.
245 * - 0: Success, device started.
246 * - <0: Error code of the driver device start function.
249 rte_cryptodev_start(uint8_t dev_id);
252 * Stop an device. The device can be restarted with a call to
253 * rte_cryptodev_start()
255 * @param dev_id The identifier of the device.
258 rte_cryptodev_stop(uint8_t dev_id);
261 * Close an device. The device cannot be restarted!
263 * @param dev_id The identifier of the device.
266 * - 0 on successfully closing device
267 * - <0 on failure to close device
270 rte_cryptodev_close(uint8_t dev_id);
273 * Allocate and set up a receive queue pair for a device.
276 * @param dev_id The identifier of the device.
277 * @param queue_pair_id The index of the queue pairs to set up. The
278 * value must be in the range [0, nb_queue_pair
279 * - 1] previously supplied to
280 * rte_cryptodev_configure().
281 * @param qp_conf The pointer to the configuration data to be
282 * used for the queue pair. NULL value is
283 * allowed, in which case default configuration
285 * @param socket_id The *socket_id* argument is the socket
286 * identifier in case of NUMA. The value can be
287 * *SOCKET_ID_ANY* if there is no NUMA constraint
288 * for the DMA memory allocated for the receive
292 * - 0: Success, queue pair correctly set up.
293 * - <0: Queue pair configuration failed
296 rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
297 const struct rte_cryptodev_qp_conf *qp_conf, int socket_id);
300 * Start a specified queue pair of a device. It is used
301 * when deferred_start flag of the specified queue is true.
303 * @param dev_id The identifier of the device
304 * @param queue_pair_id The index of the queue pair to start. The value
305 * must be in the range [0, nb_queue_pair - 1]
306 * previously supplied to
307 * rte_crypto_dev_configure().
309 * - 0: Success, the transmit queue is correctly set up.
310 * - -EINVAL: The dev_id or the queue_id out of range.
311 * - -ENOTSUP: The function not supported in PMD driver.
314 rte_cryptodev_queue_pair_start(uint8_t dev_id, uint16_t queue_pair_id);
317 * Stop specified queue pair of a device
319 * @param dev_id The identifier of the device
320 * @param queue_pair_id The index of the queue pair to stop. The value
321 * must be in the range [0, nb_queue_pair - 1]
322 * previously supplied to
323 * rte_cryptodev_configure().
325 * - 0: Success, the transmit queue is correctly set up.
326 * - -EINVAL: The dev_id or the queue_id out of range.
327 * - -ENOTSUP: The function not supported in PMD driver.
330 rte_cryptodev_queue_pair_stop(uint8_t dev_id, uint16_t queue_pair_id);
333 * Get the number of queue pairs on a specific crypto device
335 * @param dev_id Crypto device identifier.
337 * - The number of configured queue pairs.
340 rte_cryptodev_queue_pair_count(uint8_t dev_id);
344 * Retrieve the general I/O statistics of a device.
346 * @param dev_id The identifier of the device.
347 * @param stats A pointer to a structure of type
348 * *rte_cryptodev_stats* to be filled with the
349 * values of device counters.
351 * - Zero if successful.
352 * - Non-zero otherwise.
355 rte_cryptodev_stats_get(uint8_t dev_id, struct rte_cryptodev_stats *stats);
358 * Reset the general I/O statistics of a device.
360 * @param dev_id The identifier of the device.
363 rte_cryptodev_stats_reset(uint8_t dev_id);
366 * Retrieve the contextual information of a device.
368 * @param dev_id The identifier of the device.
369 * @param dev_info A pointer to a structure of type
370 * *rte_cryptodev_info* to be filled with the
371 * contextual information of the device.
374 rte_cryptodev_info_get(uint8_t dev_id, struct rte_cryptodev_info *dev_info);
378 * Register a callback function for specific device id.
380 * @param dev_id Device id.
381 * @param event Event interested.
382 * @param cb_fn User supplied callback function to be called.
383 * @param cb_arg Pointer to the parameters for the registered
387 * - On success, zero.
388 * - On failure, a negative value.
391 rte_cryptodev_callback_register(uint8_t dev_id,
392 enum rte_cryptodev_event_type event,
393 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
396 * Unregister a callback function for specific device id.
398 * @param dev_id The device identifier.
399 * @param event Event interested.
400 * @param cb_fn User supplied callback function to be called.
401 * @param cb_arg Pointer to the parameters for the registered
405 * - On success, zero.
406 * - On failure, a negative value.
409 rte_cryptodev_callback_unregister(uint8_t dev_id,
410 enum rte_cryptodev_event_type event,
411 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
414 typedef uint16_t (*dequeue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
416 /**< Dequeue processed packets from queue pair of a device. */
418 typedef uint16_t (*enqueue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
420 /**< Enqueue packets for processing on queue pair of a device. */
423 struct rte_cryptodev_callback;
425 /** Structure to keep track of registered callbacks */
426 TAILQ_HEAD(rte_cryptodev_cb_list, rte_cryptodev_callback);
428 /** The data structure associated with each crypto device. */
429 struct rte_cryptodev {
430 dequeue_pkt_burst_t dequeue_burst;
431 /**< Pointer to PMD receive function. */
432 enqueue_pkt_burst_t enqueue_burst;
433 /**< Pointer to PMD transmit function. */
435 const struct rte_cryptodev_driver *driver;
436 /**< Driver for this device */
437 struct rte_cryptodev_data *data;
438 /**< Pointer to device data */
439 struct rte_cryptodev_ops *dev_ops;
440 /**< Functions exported by PMD */
441 struct rte_pci_device *pci_dev;
442 /**< PCI info. supplied by probing */
444 enum rte_cryptodev_type dev_type;
445 /**< Crypto device type */
446 enum pmd_type pmd_type;
447 /**< PMD type - PDEV / VDEV */
449 struct rte_cryptodev_cb_list link_intr_cbs;
450 /**< User application callback for interrupts if present */
452 uint8_t attached : 1;
453 /**< Flag indicating the device is attached */
454 } __rte_cache_aligned;
457 #define RTE_CRYPTODEV_NAME_MAX_LEN (64)
458 /**< Max length of name of crypto PMD */
462 * The data part, with no function pointers, associated with each device.
464 * This structure is safe to place in shared memory to be common among
465 * different processes in a multi-process configuration.
467 struct rte_cryptodev_data {
469 /**< Device ID for this instance */
471 /**< Socket ID where memory is allocated */
472 char name[RTE_CRYPTODEV_NAME_MAX_LEN];
473 /**< Unique identifier name */
475 uint8_t dev_started : 1;
476 /**< Device state: STARTED(1)/STOPPED(0) */
478 struct rte_mempool *session_pool;
479 /**< Session memory pool */
481 /**< Array of pointers to queue pairs. */
482 uint16_t nb_queue_pairs;
483 /**< Number of device queue pairs. */
486 /**< PMD-specific private data */
487 } __rte_cache_aligned;
489 extern struct rte_cryptodev *rte_cryptodevs;
492 * Dequeue a burst of processed packets from a queue of the crypto device.
493 * The dequeued packets are stored in *rte_mbuf* structures whose pointers are
494 * supplied in the *pkts* array.
496 * The rte_crypto_dequeue_burst() function returns the number of packets
497 * actually dequeued, which is the number of *rte_mbuf* data structures
498 * effectively supplied into the *pkts* array.
500 * A return value equal to *nb_pkts* indicates that the queue contained
501 * at least *rx_pkts* packets, and this is likely to signify that other
502 * received packets remain in the input queue. Applications implementing
503 * a "retrieve as much received packets as possible" policy can check this
504 * specific case and keep invoking the rte_crypto_dequeue_burst() function
505 * until a value less than *nb_pkts* is returned.
507 * The rte_crypto_dequeue_burst() function does not provide any error
508 * notification to avoid the corresponding overhead.
510 * @param dev_id The identifier of the device.
511 * @param qp_id The index of the queue pair from which to
512 * retrieve processed packets. The value must be
513 * in the range [0, nb_queue_pair - 1] previously
514 * supplied to rte_cryptodev_configure().
515 * @param pkts The address of an array of pointers to
516 * *rte_mbuf* structures that must be large enough
517 * to store *nb_pkts* pointers in it.
518 * @param nb_pkts The maximum number of packets to dequeue.
521 * - The number of packets actually dequeued, which is the number
522 * of pointers to *rte_mbuf* structures effectively supplied to the
525 static inline uint16_t
526 rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
527 struct rte_mbuf **pkts, uint16_t nb_pkts)
529 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
531 nb_pkts = (*dev->dequeue_burst)
532 (dev->data->queue_pairs[qp_id], pkts, nb_pkts);
538 * Enqueue a burst of packets for processing on a crypto device.
540 * The rte_crypto_enqueue_burst() function is invoked to place packets
541 * on the queue *queue_id* of the device designated by its *dev_id*.
543 * The *nb_pkts* parameter is the number of packets to process which are
544 * supplied in the *pkts* array of *rte_mbuf* structures.
546 * The rte_crypto_enqueue_burst() function returns the number of packets it
547 * actually sent. A return value equal to *nb_pkts* means that all packets
550 * Each mbuf in the *pkts* array must have a valid *rte_mbuf_offload* structure
551 * attached which contains a valid crypto operation.
553 * @param dev_id The identifier of the device.
554 * @param qp_id The index of the queue pair which packets are
555 * to be enqueued for processing. The value
556 * must be in the range [0, nb_queue_pairs - 1]
557 * previously supplied to
558 * *rte_cryptodev_configure*.
559 * @param pkts The address of an array of *nb_pkts* pointers
560 * to *rte_mbuf* structures which contain the
562 * @param nb_pkts The number of packets to transmit.
565 * The number of packets actually enqueued on the crypto device. The return
566 * value can be less than the value of the *nb_pkts* parameter when the
567 * crypto devices queue is full or has been filled up.
568 * The number of packets is 0 if the device hasn't been started.
570 static inline uint16_t
571 rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
572 struct rte_mbuf **pkts, uint16_t nb_pkts)
574 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
576 return (*dev->enqueue_burst)(
577 dev->data->queue_pairs[qp_id], pkts, nb_pkts);
581 /** Cryptodev symmetric crypto session */
582 struct rte_cryptodev_sym_session {
586 enum rte_cryptodev_type type;
587 /** Crypto Device type session created on */
588 struct rte_mempool *mp;
589 /**< Mempool session allocated from */
591 /**< Public symmetric session details */
594 /**< Private session material */
599 * Initialise a session for symmetric cryptographic operations.
601 * This function is used by the client to initialize immutable
602 * parameters of symmetric cryptographic operation.
603 * To perform the operation the rte_cryptodev_enqueue_burst function is
604 * used. Each mbuf should contain a reference to the session
605 * pointer returned from this function contained within it's crypto_op if a
606 * session-based operation is being provisioned. Memory to contain the session
607 * information is allocated from within mempool managed by the cryptodev.
609 * The rte_cryptodev_session_free must be called to free allocated
610 * memory when the session is no longer required.
612 * @param dev_id The device identifier.
613 * @param xform Crypto transform chain.
617 * Pointer to the created session or NULL
619 extern struct rte_cryptodev_sym_session *
620 rte_cryptodev_sym_session_create(uint8_t dev_id,
621 struct rte_crypto_sym_xform *xform);
624 * Free the memory associated with a previously allocated session.
626 * @param dev_id The device identifier.
627 * @param session Session pointer previously allocated by
628 * *rte_cryptodev_sym_session_create*.
631 * NULL on successful freeing of session.
632 * Session pointer on failure to free session.
634 extern struct rte_cryptodev_sym_session *
635 rte_cryptodev_sym_session_free(uint8_t dev_id,
636 struct rte_cryptodev_sym_session *session);
643 #endif /* _RTE_CRYPTODEV_H_ */