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_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_PMD ("cryptodev_qat_pmd")
61 /**< Intel QAT 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_PMD, /**< QAT PMD */
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. */
102 unsigned max_nb_sessions;
103 /**< Maximum number of sessions supported by device. */
106 #define RTE_CRYPTODEV_DETACHED (0)
107 #define RTE_CRYPTODEV_ATTACHED (1)
109 /** Definitions of Crypto device event types */
110 enum rte_cryptodev_event_type {
111 RTE_CRYPTODEV_EVENT_UNKNOWN, /**< unknown event type */
112 RTE_CRYPTODEV_EVENT_ERROR, /**< error interrupt event */
113 RTE_CRYPTODEV_EVENT_MAX /**< max value of this enum */
116 /** Crypto device queue pair configuration structure. */
117 struct rte_cryptodev_qp_conf {
118 uint32_t nb_descriptors; /**< Number of descriptors per queue pair */
122 * Typedef for application callback function to be registered by application
123 * software for notification of device events
125 * @param dev_id Crypto device identifier
126 * @param event Crypto device event to register for notification of.
127 * @param cb_arg User specified parameter to be passed as to passed to
128 * users callback function.
130 typedef void (*rte_cryptodev_cb_fn)(uint8_t dev_id,
131 enum rte_cryptodev_event_type event, void *cb_arg);
134 /** Crypto Device statistics */
135 struct rte_cryptodev_stats {
136 uint64_t enqueued_count;
137 /**< Count of all operations enqueued */
138 uint64_t dequeued_count;
139 /**< Count of all operations dequeued */
141 uint64_t enqueue_err_count;
142 /**< Total error count on operations enqueued */
143 uint64_t dequeue_err_count;
144 /**< Total error count on operations dequeued */
149 * Create a virtual crypto device
151 * @param name Cryptodev PMD name of device to be created.
152 * @param args Options arguments for device.
155 * - On successful creation of the cryptodev the device index is returned,
156 * which will be between 0 and rte_cryptodev_count().
157 * - In the case of a failure, returns -1.
160 rte_cryptodev_create_vdev(const char *name, const char *args);
163 * Get the device identifier for the named crypto device.
165 * @param name device name to select the device structure.
168 * - Returns crypto device identifier on success.
169 * - Return -1 on failure to find named crypto device.
172 rte_cryptodev_get_dev_id(const char *name);
175 * Get the total number of crypto devices that have been successfully
179 * - The total number of usable crypto devices.
182 rte_cryptodev_count(void);
185 rte_cryptodev_count_devtype(enum rte_cryptodev_type type);
187 * Return the NUMA socket to which a device is connected
190 * The identifier of the device
192 * The NUMA socket id to which the device is connected or
193 * a default of zero if the socket could not be determined.
194 * -1 if returned is the dev_id value is out of range.
197 rte_cryptodev_socket_id(uint8_t dev_id);
199 /** Crypto device configuration structure */
200 struct rte_cryptodev_config {
201 int socket_id; /**< Socket to allocate resources on */
202 uint16_t nb_queue_pairs;
203 /**< Number of queue pairs to configure on device */
206 uint32_t nb_objs; /**< Number of objects in mempool */
207 uint32_t cache_size; /**< l-core object cache size */
208 } session_mp; /**< Session mempool configuration */
212 * Configure a device.
214 * EXPERIMENTAL: this API file may change without prior notice
216 * This function must be invoked first before any other function in the
217 * API. This function can also be re-invoked when a device is in the
220 * @param dev_id The identifier of the device to configure.
221 * @param config The crypto device configuration structure.
224 * - 0: Success, device configured.
225 * - <0: Error code returned by the driver configuration function.
228 rte_cryptodev_configure(uint8_t dev_id, struct rte_cryptodev_config *config);
233 * The device start step is the last one and consists of setting the configured
234 * offload features and in starting the transmit and the receive units of the
236 * On success, all basic functions exported by the API (link status,
237 * receive/transmit, and so on) can be invoked.
240 * The identifier of the device.
242 * - 0: Success, device started.
243 * - <0: Error code of the driver device start function.
246 rte_cryptodev_start(uint8_t dev_id);
249 * Stop an device. The device can be restarted with a call to
250 * rte_cryptodev_start()
252 * @param dev_id The identifier of the device.
255 rte_cryptodev_stop(uint8_t dev_id);
258 * Close an device. The device cannot be restarted!
260 * @param dev_id The identifier of the device.
263 * - 0 on successfully closing device
264 * - <0 on failure to close device
267 rte_cryptodev_close(uint8_t dev_id);
270 * Allocate and set up a receive queue pair for a device.
273 * @param dev_id The identifier of the device.
274 * @param queue_pair_id The index of the queue pairs to set up. The
275 * value must be in the range [0, nb_queue_pair
276 * - 1] previously supplied to
277 * rte_cryptodev_configure().
278 * @param qp_conf The pointer to the configuration data to be
279 * used for the queue pair. NULL value is
280 * allowed, in which case default configuration
282 * @param socket_id The *socket_id* argument is the socket
283 * identifier in case of NUMA. The value can be
284 * *SOCKET_ID_ANY* if there is no NUMA constraint
285 * for the DMA memory allocated for the receive
289 * - 0: Success, queue pair correctly set up.
290 * - <0: Queue pair configuration failed
293 rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
294 const struct rte_cryptodev_qp_conf *qp_conf, int socket_id);
297 * Start a specified queue pair of a device. It is used
298 * when deferred_start flag of the specified queue is true.
300 * @param dev_id The identifier of the device
301 * @param queue_pair_id The index of the queue pair to start. The value
302 * must be in the range [0, nb_queue_pair - 1]
303 * previously supplied to
304 * rte_crypto_dev_configure().
306 * - 0: Success, the transmit queue is correctly set up.
307 * - -EINVAL: The dev_id or the queue_id out of range.
308 * - -ENOTSUP: The function not supported in PMD driver.
311 rte_cryptodev_queue_pair_start(uint8_t dev_id, uint16_t queue_pair_id);
314 * Stop specified queue pair of a device
316 * @param dev_id The identifier of the device
317 * @param queue_pair_id The index of the queue pair to stop. The value
318 * must be in the range [0, nb_queue_pair - 1]
319 * previously supplied to
320 * rte_cryptodev_configure().
322 * - 0: Success, the transmit queue is correctly set up.
323 * - -EINVAL: The dev_id or the queue_id out of range.
324 * - -ENOTSUP: The function not supported in PMD driver.
327 rte_cryptodev_queue_pair_stop(uint8_t dev_id, uint16_t queue_pair_id);
330 * Get the number of queue pairs on a specific crypto device
332 * @param dev_id Crypto device identifier.
334 * - The number of configured queue pairs.
337 rte_cryptodev_queue_pair_count(uint8_t dev_id);
341 * Retrieve the general I/O statistics of a device.
343 * @param dev_id The identifier of the device.
344 * @param stats A pointer to a structure of type
345 * *rte_cryptodev_stats* to be filled with the
346 * values of device counters.
348 * - Zero if successful.
349 * - Non-zero otherwise.
352 rte_cryptodev_stats_get(uint8_t dev_id, struct rte_cryptodev_stats *stats);
355 * Reset the general I/O statistics of a device.
357 * @param dev_id The identifier of the device.
360 rte_cryptodev_stats_reset(uint8_t dev_id);
363 * Retrieve the contextual information of a device.
365 * @param dev_id The identifier of the device.
366 * @param dev_info A pointer to a structure of type
367 * *rte_cryptodev_info* to be filled with the
368 * contextual information of the device.
371 rte_cryptodev_info_get(uint8_t dev_id, struct rte_cryptodev_info *dev_info);
375 * Register a callback function for specific device id.
377 * @param dev_id Device id.
378 * @param event Event interested.
379 * @param cb_fn User supplied callback function to be called.
380 * @param cb_arg Pointer to the parameters for the registered
384 * - On success, zero.
385 * - On failure, a negative value.
388 rte_cryptodev_callback_register(uint8_t dev_id,
389 enum rte_cryptodev_event_type event,
390 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
393 * Unregister a callback function for specific device id.
395 * @param dev_id The device identifier.
396 * @param event Event interested.
397 * @param cb_fn User supplied callback function to be called.
398 * @param cb_arg Pointer to the parameters for the registered
402 * - On success, zero.
403 * - On failure, a negative value.
406 rte_cryptodev_callback_unregister(uint8_t dev_id,
407 enum rte_cryptodev_event_type event,
408 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
411 typedef uint16_t (*dequeue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
413 /**< Dequeue processed packets from queue pair of a device. */
415 typedef uint16_t (*enqueue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
417 /**< Enqueue packets for processing on queue pair of a device. */
420 struct rte_cryptodev_callback;
422 /** Structure to keep track of registered callbacks */
423 TAILQ_HEAD(rte_cryptodev_cb_list, rte_cryptodev_callback);
425 /** The data structure associated with each crypto device. */
426 struct rte_cryptodev {
427 dequeue_pkt_burst_t dequeue_burst;
428 /**< Pointer to PMD receive function. */
429 enqueue_pkt_burst_t enqueue_burst;
430 /**< Pointer to PMD transmit function. */
432 const struct rte_cryptodev_driver *driver;
433 /**< Driver for this device */
434 struct rte_cryptodev_data *data;
435 /**< Pointer to device data */
436 struct rte_cryptodev_ops *dev_ops;
437 /**< Functions exported by PMD */
438 struct rte_pci_device *pci_dev;
439 /**< PCI info. supplied by probing */
441 enum rte_cryptodev_type dev_type;
442 /**< Crypto device type */
443 enum pmd_type pmd_type;
444 /**< PMD type - PDEV / VDEV */
446 struct rte_cryptodev_cb_list link_intr_cbs;
447 /**< User application callback for interrupts if present */
449 uint8_t attached : 1;
450 /**< Flag indicating the device is attached */
451 } __rte_cache_aligned;
454 #define RTE_CRYPTODEV_NAME_MAX_LEN (64)
455 /**< Max length of name of crypto PMD */
459 * The data part, with no function pointers, associated with each device.
461 * This structure is safe to place in shared memory to be common among
462 * different processes in a multi-process configuration.
464 struct rte_cryptodev_data {
466 /**< Device ID for this instance */
468 /**< Socket ID where memory is allocated */
469 char name[RTE_CRYPTODEV_NAME_MAX_LEN];
470 /**< Unique identifier name */
472 uint8_t dev_started : 1;
473 /**< Device state: STARTED(1)/STOPPED(0) */
475 struct rte_mempool *session_pool;
476 /**< Session memory pool */
478 /**< Array of pointers to queue pairs. */
479 uint16_t nb_queue_pairs;
480 /**< Number of device queue pairs. */
483 /**< PMD-specific private data */
484 } __rte_cache_aligned;
486 extern struct rte_cryptodev *rte_cryptodevs;
489 * Dequeue a burst of processed packets from a queue of the crypto device.
490 * The dequeued packets are stored in *rte_mbuf* structures whose pointers are
491 * supplied in the *pkts* array.
493 * The rte_crypto_dequeue_burst() function returns the number of packets
494 * actually dequeued, which is the number of *rte_mbuf* data structures
495 * effectively supplied into the *pkts* array.
497 * A return value equal to *nb_pkts* indicates that the queue contained
498 * at least *rx_pkts* packets, and this is likely to signify that other
499 * received packets remain in the input queue. Applications implementing
500 * a "retrieve as much received packets as possible" policy can check this
501 * specific case and keep invoking the rte_crypto_dequeue_burst() function
502 * until a value less than *nb_pkts* is returned.
504 * The rte_crypto_dequeue_burst() function does not provide any error
505 * notification to avoid the corresponding overhead.
507 * @param dev_id The identifier of the device.
508 * @param qp_id The index of the queue pair from which to
509 * retrieve processed packets. The value must be
510 * in the range [0, nb_queue_pair - 1] previously
511 * supplied to rte_cryptodev_configure().
512 * @param pkts The address of an array of pointers to
513 * *rte_mbuf* structures that must be large enough
514 * to store *nb_pkts* pointers in it.
515 * @param nb_pkts The maximum number of packets to dequeue.
518 * - The number of packets actually dequeued, which is the number
519 * of pointers to *rte_mbuf* structures effectively supplied to the
522 static inline uint16_t
523 rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
524 struct rte_mbuf **pkts, uint16_t nb_pkts)
526 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
528 nb_pkts = (*dev->dequeue_burst)
529 (dev->data->queue_pairs[qp_id], pkts, nb_pkts);
535 * Enqueue a burst of packets for processing on a crypto device.
537 * The rte_crypto_enqueue_burst() function is invoked to place packets
538 * on the queue *queue_id* of the device designated by its *dev_id*.
540 * The *nb_pkts* parameter is the number of packets to process which are
541 * supplied in the *pkts* array of *rte_mbuf* structures.
543 * The rte_crypto_enqueue_burst() function returns the number of packets it
544 * actually sent. A return value equal to *nb_pkts* means that all packets
547 * Each mbuf in the *pkts* array must have a valid *rte_mbuf_offload* structure
548 * attached which contains a valid crypto operation.
550 * @param dev_id The identifier of the device.
551 * @param qp_id The index of the queue pair which packets are
552 * to be enqueued for processing. The value
553 * must be in the range [0, nb_queue_pairs - 1]
554 * previously supplied to
555 * *rte_cryptodev_configure*.
556 * @param pkts The address of an array of *nb_pkts* pointers
557 * to *rte_mbuf* structures which contain the
559 * @param nb_pkts The number of packets to transmit.
562 * The number of packets actually enqueued on the crypto device. The return
563 * value can be less than the value of the *nb_pkts* parameter when the
564 * crypto devices queue is full or has been filled up.
565 * The number of packets is 0 if the device hasn't been started.
567 static inline uint16_t
568 rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
569 struct rte_mbuf **pkts, uint16_t nb_pkts)
571 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
573 return (*dev->enqueue_burst)(
574 dev->data->queue_pairs[qp_id], pkts, nb_pkts);
579 * Initialise a session for symmetric cryptographic operations.
581 * This function is used by the client to initialize immutable
582 * parameters of symmetric cryptographic operation.
583 * To perform the operation the rte_cryptodev_enqueue_burst function is
584 * used. Each mbuf should contain a reference to the session
585 * pointer returned from this function contained within it's crypto_op if a
586 * session-based operation is being provisioned. Memory to contain the session
587 * information is allocated from within mempool managed by the cryptodev.
589 * The rte_cryptodev_session_free must be called to free allocated
590 * memory when the session is no longer required.
592 * @param dev_id The device identifier.
593 * @param xform Crypto transform chain.
597 * Pointer to the created session or NULL
599 extern struct rte_cryptodev_session *
600 rte_cryptodev_session_create(uint8_t dev_id,
601 struct rte_crypto_xform *xform);
604 * Free the memory associated with a previously allocated session.
606 * @param dev_id The device identifier.
607 * @param session Session pointer previously allocated by
608 * *rte_cryptodev_session_create*.
611 * NULL on successful freeing of session.
612 * Session pointer on failure to free session.
614 extern struct rte_cryptodev_session *
615 rte_cryptodev_session_free(uint8_t dev_id,
616 struct rte_cryptodev_session *session);
623 #endif /* _RTE_CRYPTODEV_H_ */