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.
50 #include "rte_crypto.h"
53 #define CRYPTODEV_NAME_NULL_PMD ("cryptodev_null_pmd")
54 /**< Null crypto PMD device name */
55 #define CRYPTODEV_NAME_AESNI_MB_PMD ("cryptodev_aesni_mb_pmd")
56 /**< AES-NI Multi buffer PMD device name */
57 #define CRYPTODEV_NAME_QAT_PMD ("cryptodev_qat_pmd")
58 /**< Intel QAT PMD device name */
60 /** Crypto device type */
61 enum rte_cryptodev_type {
62 RTE_CRYPTODEV_NULL_PMD = 1, /**< Null crypto PMD */
63 RTE_CRYPTODEV_AESNI_MB_PMD, /**< AES-NI multi buffer PMD */
64 RTE_CRYPTODEV_QAT_PMD, /**< QAT PMD */
69 #define CDEV_LOG_ERR(fmt, args...) \
70 RTE_LOG(ERR, CRYPTODEV, "%s() line %u: " fmt "\n", \
71 __func__, __LINE__, ## args)
73 #define CDEV_PMD_LOG_ERR(dev, fmt, args...) \
74 RTE_LOG(ERR, CRYPTODEV, "[%s] %s() line %u: " fmt "\n", \
75 dev, __func__, __LINE__, ## args)
77 #ifdef RTE_LIBRTE_CRYPTODEV_DEBUG
78 #define CDEV_LOG_DEBUG(fmt, args...) \
79 RTE_LOG(DEBUG, CRYPTODEV, "%s() line %u: " fmt "\n", \
80 __func__, __LINE__, ## args) \
82 #define CDEV_PMD_TRACE(fmt, args...) \
83 RTE_LOG(DEBUG, CRYPTODEV, "[%s] %s: " fmt "\n", \
84 dev, __func__, ## args)
87 #define CDEV_LOG_DEBUG(fmt, args...)
88 #define CDEV_PMD_TRACE(fmt, args...)
91 /** Crypto device information */
92 struct rte_cryptodev_info {
93 const char *driver_name; /**< Driver name. */
94 enum rte_cryptodev_type dev_type; /**< Device type */
95 struct rte_pci_device *pci_dev; /**< PCI information. */
97 unsigned max_nb_queue_pairs;
98 /**< Maximum number of queues pairs supported by device. */
99 unsigned max_nb_sessions;
100 /**< Maximum number of sessions supported by device. */
103 #define RTE_CRYPTODEV_DETACHED (0)
104 #define RTE_CRYPTODEV_ATTACHED (1)
106 /** Definitions of Crypto device event types */
107 enum rte_cryptodev_event_type {
108 RTE_CRYPTODEV_EVENT_UNKNOWN, /**< unknown event type */
109 RTE_CRYPTODEV_EVENT_ERROR, /**< error interrupt event */
110 RTE_CRYPTODEV_EVENT_MAX /**< max value of this enum */
113 /** Crypto device queue pair configuration structure. */
114 struct rte_cryptodev_qp_conf {
115 uint32_t nb_descriptors; /**< Number of descriptors per queue pair */
119 * Typedef for application callback function to be registered by application
120 * software for notification of device events
122 * @param dev_id Crypto device identifier
123 * @param event Crypto device event to register for notification of.
124 * @param cb_arg User specified parameter to be passed as to passed to
125 * users callback function.
127 typedef void (*rte_cryptodev_cb_fn)(uint8_t dev_id,
128 enum rte_cryptodev_event_type event, void *cb_arg);
130 #ifdef RTE_CRYPTODEV_PERF
132 * Crypto Device performance counter statistics structure. This structure is
133 * used for RDTSC counters for measuring crypto operations.
135 struct rte_cryptodev_perf_stats {
136 uint64_t t_accumlated; /**< Accumulated time processing operation */
137 uint64_t t_min; /**< Max time */
138 uint64_t t_max; /**< Min time */
142 /** Crypto Device statistics */
143 struct rte_cryptodev_stats {
144 uint64_t enqueued_count;
145 /**< Count of all operations enqueued */
146 uint64_t dequeued_count;
147 /**< Count of all operations dequeued */
149 uint64_t enqueue_err_count;
150 /**< Total error count on operations enqueued */
151 uint64_t dequeue_err_count;
152 /**< Total error count on operations dequeued */
154 #ifdef RTE_CRYPTODEV_DETAILED_STATS
156 uint64_t encrypt_ops; /**< Count of encrypt operations */
157 uint64_t encrypt_bytes; /**< Number of bytes encrypted */
159 uint64_t decrypt_ops; /**< Count of decrypt operations */
160 uint64_t decrypt_bytes; /**< Number of bytes decrypted */
161 } cipher; /**< Cipher operations stats */
164 uint64_t generate_ops; /**< Count of generate operations */
165 uint64_t bytes_hashed; /**< Number of bytes hashed */
167 uint64_t verify_ops; /**< Count of verify operations */
168 uint64_t bytes_verified;/**< Number of bytes verified */
169 } hash; /**< Hash operations stats */
172 #ifdef RTE_CRYPTODEV_PERF
173 struct rte_cryptodev_perf_stats op_perf; /**< Operations stats */
175 } __rte_cache_aligned;
178 * Create a virtual crypto device
180 * @param name Cryptodev PMD name of device to be created.
181 * @param args Options arguments for device.
184 * - On successful creation of the cryptodev the device index is returned,
185 * which will be between 0 and rte_cryptodev_count().
186 * - In the case of a failure, returns -1.
189 rte_cryptodev_create_vdev(const char *name, const char *args);
192 * Get the device identifier for the named crypto device.
194 * @param name device name to select the device structure.
197 * - Returns crypto device identifier on success.
198 * - Return -1 on failure to find named crypto device.
201 rte_cryptodev_get_dev_id(const char *name);
204 * Get the total number of crypto devices that have been successfully
208 * - The total number of usable crypto devices.
211 rte_cryptodev_count(void);
214 rte_cryptodev_count_devtype(enum rte_cryptodev_type type);
216 * Return the NUMA socket to which a device is connected
219 * The identifier of the device
221 * The NUMA socket id to which the device is connected or
222 * a default of zero if the socket could not be determined.
223 * -1 if returned is the dev_id value is out of range.
226 rte_cryptodev_socket_id(uint8_t dev_id);
228 /** Crypto device configuration structure */
229 struct rte_cryptodev_config {
230 int socket_id; /**< Socket to allocate resources on */
231 uint16_t nb_queue_pairs;
232 /**< Number of queue pairs to configure on device */
235 uint32_t nb_objs; /**< Number of objects in mempool */
236 uint32_t cache_size; /**< l-core object cache size */
237 } session_mp; /**< Session mempool configuration */
241 * Configure a device.
243 * This function must be invoked first before any other function in the
244 * API. This function can also be re-invoked when a device is in the
247 * @param dev_id The identifier of the device to configure.
248 * @param config The crypto device configuration structure.
251 * - 0: Success, device configured.
252 * - <0: Error code returned by the driver configuration function.
255 rte_cryptodev_configure(uint8_t dev_id, struct rte_cryptodev_config *config);
260 * The device start step is the last one and consists of setting the configured
261 * offload features and in starting the transmit and the receive units of the
263 * On success, all basic functions exported by the API (link status,
264 * receive/transmit, and so on) can be invoked.
267 * The identifier of the device.
269 * - 0: Success, device started.
270 * - <0: Error code of the driver device start function.
273 rte_cryptodev_start(uint8_t dev_id);
276 * Stop an device. The device can be restarted with a call to
277 * rte_cryptodev_start()
279 * @param dev_id The identifier of the device.
282 rte_cryptodev_stop(uint8_t dev_id);
285 * Close an device. The device cannot be restarted!
287 * @param dev_id The identifier of the device.
290 * - 0 on successfully closing device
291 * - <0 on failure to close device
294 rte_cryptodev_close(uint8_t dev_id);
297 * Allocate and set up a receive queue pair for a device.
300 * @param dev_id The identifier of the device.
301 * @param queue_pair_id The index of the queue pairs to set up. The
302 * value must be in the range [0, nb_queue_pair
303 * - 1] previously supplied to
304 * rte_cryptodev_configure().
305 * @param qp_conf The pointer to the configuration data to be
306 * used for the queue pair. NULL value is
307 * allowed, in which case default configuration
309 * @param socket_id The *socket_id* argument is the socket
310 * identifier in case of NUMA. The value can be
311 * *SOCKET_ID_ANY* if there is no NUMA constraint
312 * for the DMA memory allocated for the receive
316 * - 0: Success, queue pair correctly set up.
317 * - <0: Queue pair configuration failed
320 rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
321 const struct rte_cryptodev_qp_conf *qp_conf, int socket_id);
324 * Start a specified queue pair of a device. It is used
325 * when deferred_start flag of the specified queue is true.
327 * @param dev_id The identifier of the device
328 * @param queue_pair_id The index of the queue pair to start. The value
329 * must be in the range [0, nb_queue_pair - 1]
330 * previously supplied to
331 * rte_crypto_dev_configure().
333 * - 0: Success, the transmit queue is correctly set up.
334 * - -EINVAL: The dev_id or the queue_id out of range.
335 * - -ENOTSUP: The function not supported in PMD driver.
338 rte_cryptodev_queue_pair_start(uint8_t dev_id, uint16_t queue_pair_id);
341 * Stop specified queue pair of a device
343 * @param dev_id The identifier of the device
344 * @param queue_pair_id The index of the queue pair to stop. The value
345 * must be in the range [0, nb_queue_pair - 1]
346 * previously supplied to
347 * rte_cryptodev_configure().
349 * - 0: Success, the transmit queue is correctly set up.
350 * - -EINVAL: The dev_id or the queue_id out of range.
351 * - -ENOTSUP: The function not supported in PMD driver.
354 rte_cryptodev_queue_pair_stop(uint8_t dev_id, uint16_t queue_pair_id);
357 * Get the number of queue pairs on a specific crypto device
359 * @param dev_id Crypto device identifier.
361 * - The number of configured queue pairs.
364 rte_cryptodev_queue_pair_count(uint8_t dev_id);
368 * Retrieve the general I/O statistics of a device.
370 * @param dev_id The identifier of the device.
371 * @param stats A pointer to a structure of type
372 * *rte_cryptodev_stats* to be filled with the
373 * values of device counters.
375 * - Zero if successful.
376 * - Non-zero otherwise.
379 rte_cryptodev_stats_get(uint8_t dev_id, struct rte_cryptodev_stats *stats);
382 * Reset the general I/O statistics of a device.
384 * @param dev_id The identifier of the device.
387 rte_cryptodev_stats_reset(uint8_t dev_id);
390 * Retrieve the contextual information of a device.
392 * @param dev_id The identifier of the device.
393 * @param dev_info A pointer to a structure of type
394 * *rte_cryptodev_info* to be filled with the
395 * contextual information of the device.
398 rte_cryptodev_info_get(uint8_t dev_id, struct rte_cryptodev_info *dev_info);
402 * Register a callback function for specific device id.
404 * @param dev_id Device id.
405 * @param event Event interested.
406 * @param cb_fn User supplied callback function to be called.
407 * @param cb_arg Pointer to the parameters for the registered
411 * - On success, zero.
412 * - On failure, a negative value.
415 rte_cryptodev_callback_register(uint8_t dev_id,
416 enum rte_cryptodev_event_type event,
417 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
420 * Unregister a callback function for specific device id.
422 * @param dev_id The device identifier.
423 * @param event Event interested.
424 * @param cb_fn User supplied callback function to be called.
425 * @param cb_arg Pointer to the parameters for the registered
429 * - On success, zero.
430 * - On failure, a negative value.
433 rte_cryptodev_callback_unregister(uint8_t dev_id,
434 enum rte_cryptodev_event_type event,
435 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
438 typedef uint16_t (*dequeue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
440 /**< Dequeue processed packets from queue pair of a device. */
442 typedef uint16_t (*enqueue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
444 /**< Enqueue packets for processing on queue pair of a device. */
447 struct rte_cryptodev_callback;
449 /** Structure to keep track of registered callbacks */
450 TAILQ_HEAD(rte_cryptodev_cb_list, rte_cryptodev_callback);
452 /** The data structure associated with each crypto device. */
453 struct rte_cryptodev {
454 dequeue_pkt_burst_t dequeue_burst;
455 /**< Pointer to PMD receive function. */
456 enqueue_pkt_burst_t enqueue_burst;
457 /**< Pointer to PMD transmit function. */
459 const struct rte_cryptodev_driver *driver;
460 /**< Driver for this device */
461 struct rte_cryptodev_data *data;
462 /**< Pointer to device data */
463 struct rte_cryptodev_ops *dev_ops;
464 /**< Functions exported by PMD */
465 struct rte_pci_device *pci_dev;
466 /**< PCI info. supplied by probing */
468 enum rte_cryptodev_type dev_type;
469 /**< Crypto device type */
470 enum pmd_type pmd_type;
471 /**< PMD type - PDEV / VDEV */
473 struct rte_cryptodev_cb_list link_intr_cbs;
474 /**< User application callback for interrupts if present */
476 uint8_t attached : 1;
477 /**< Flag indicating the device is attached */
478 } __rte_cache_aligned;
481 #define RTE_CRYPTODEV_NAME_MAX_LEN (64)
482 /**< Max length of name of crypto PMD */
486 * The data part, with no function pointers, associated with each device.
488 * This structure is safe to place in shared memory to be common among
489 * different processes in a multi-process configuration.
491 struct rte_cryptodev_data {
493 /**< Device ID for this instance */
495 /**< Socket ID where memory is allocated */
496 char name[RTE_CRYPTODEV_NAME_MAX_LEN];
497 /**< Unique identifier name */
499 uint8_t dev_started : 1;
500 /**< Device state: STARTED(1)/STOPPED(0) */
502 struct rte_mempool *session_pool;
503 /**< Session memory pool */
505 /**< Array of pointers to queue pairs. */
506 uint16_t nb_queue_pairs;
507 /**< Number of device queue pairs. */
510 /**< PMD-specific private data */
511 } __rte_cache_aligned;
513 extern struct rte_cryptodev *rte_cryptodevs;
516 * Dequeue a burst of processed packets from a queue of the crypto device.
517 * The dequeued packets are stored in *rte_mbuf* structures whose pointers are
518 * supplied in the *pkts* array.
520 * The rte_crypto_dequeue_burst() function returns the number of packets
521 * actually dequeued, which is the number of *rte_mbuf* data structures
522 * effectively supplied into the *pkts* array.
524 * A return value equal to *nb_pkts* indicates that the queue contained
525 * at least *rx_pkts* packets, and this is likely to signify that other
526 * received packets remain in the input queue. Applications implementing
527 * a "retrieve as much received packets as possible" policy can check this
528 * specific case and keep invoking the rte_crypto_dequeue_burst() function
529 * until a value less than *nb_pkts* is returned.
531 * The rte_crypto_dequeue_burst() function does not provide any error
532 * notification to avoid the corresponding overhead.
534 * @param dev_id The identifier of the device.
535 * @param qp_id The index of the queue pair from which to
536 * retrieve processed packets. The value must be
537 * in the range [0, nb_queue_pair - 1] previously
538 * supplied to rte_cryptodev_configure().
539 * @param pkts The address of an array of pointers to
540 * *rte_mbuf* structures that must be large enough
541 * to store *nb_pkts* pointers in it.
542 * @param nb_pkts The maximum number of packets to dequeue.
545 * - The number of packets actually dequeued, which is the number
546 * of pointers to *rte_mbuf* structures effectively supplied to the
549 static inline uint16_t
550 rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
551 struct rte_mbuf **pkts, uint16_t nb_pkts)
553 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
555 nb_pkts = (*dev->dequeue_burst)
556 (dev->data->queue_pairs[qp_id], pkts, nb_pkts);
562 * Enqueue a burst of packets for processing on a crypto device.
564 * The rte_crypto_enqueue_burst() function is invoked to place packets
565 * on the queue *queue_id* of the device designated by its *dev_id*.
567 * The *nb_pkts* parameter is the number of packets to process which are
568 * supplied in the *pkts* array of *rte_mbuf* structures.
570 * The rte_crypto_enqueue_burst() function returns the number of packets it
571 * actually sent. A return value equal to *nb_pkts* means that all packets
574 * Each mbuf in the *pkts* array must have a valid *rte_mbuf_offload* structure
575 * attached which contains a valid crypto operation.
577 * @param dev_id The identifier of the device.
578 * @param qp_id The index of the queue pair which packets are
579 * to be enqueued for processing. The value
580 * must be in the range [0, nb_queue_pairs - 1]
581 * previously supplied to
582 * *rte_cryptodev_configure*.
583 * @param pkts The address of an array of *nb_pkts* pointers
584 * to *rte_mbuf* structures which contain the
586 * @param nb_pkts The number of packets to transmit.
589 * The number of packets actually enqueued on the crypto device. The return
590 * value can be less than the value of the *nb_pkts* parameter when the
591 * crypto devices queue is full or has been filled up.
592 * The number of packets is 0 if the device hasn't been started.
594 static inline uint16_t
595 rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
596 struct rte_mbuf **pkts, uint16_t nb_pkts)
598 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
600 return (*dev->enqueue_burst)(
601 dev->data->queue_pairs[qp_id], pkts, nb_pkts);
606 * Initialise a session for symmetric cryptographic operations.
608 * This function is used by the client to initialize immutable
609 * parameters of symmetric cryptographic operation.
610 * To perform the operation the rte_cryptodev_enqueue_burst function is
611 * used. Each mbuf should contain a reference to the session
612 * pointer returned from this function contained within it's crypto_op if a
613 * session-based operation is being provisioned. Memory to contain the session
614 * information is allocated from within mempool managed by the cryptodev.
616 * The rte_cryptodev_session_free must be called to free allocated
617 * memory when the session is no longer required.
619 * @param dev_id The device identifier.
620 * @param xform Crypto transform chain.
624 * Pointer to the created session or NULL
626 extern struct rte_cryptodev_session *
627 rte_cryptodev_session_create(uint8_t dev_id,
628 struct rte_crypto_xform *xform);
632 * Free the memory associated with a previously allocated session.
634 * @param dev_id The device identifier.
635 * @param session Session pointer previously allocated by
636 * *rte_cryptodev_session_create*.
639 * NULL on successful freeing of session.
640 * Session pointer on failure to free session.
642 extern struct rte_cryptodev_session *
643 rte_cryptodev_session_free(uint8_t dev_id,
644 struct rte_cryptodev_session *session);
651 #endif /* _RTE_CRYPTODEV_H_ */