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);
133 #ifdef RTE_CRYPTODEV_PERF
135 * Crypto Device performance counter statistics structure. This structure is
136 * used for RDTSC counters for measuring crypto operations.
138 struct rte_cryptodev_perf_stats {
139 uint64_t t_accumlated; /**< Accumulated time processing operation */
140 uint64_t t_min; /**< Max time */
141 uint64_t t_max; /**< Min time */
145 /** Crypto Device statistics */
146 struct rte_cryptodev_stats {
147 uint64_t enqueued_count;
148 /**< Count of all operations enqueued */
149 uint64_t dequeued_count;
150 /**< Count of all operations dequeued */
152 uint64_t enqueue_err_count;
153 /**< Total error count on operations enqueued */
154 uint64_t dequeue_err_count;
155 /**< Total error count on operations dequeued */
157 #ifdef RTE_CRYPTODEV_DETAILED_STATS
159 uint64_t encrypt_ops; /**< Count of encrypt operations */
160 uint64_t encrypt_bytes; /**< Number of bytes encrypted */
162 uint64_t decrypt_ops; /**< Count of decrypt operations */
163 uint64_t decrypt_bytes; /**< Number of bytes decrypted */
164 } cipher; /**< Cipher operations stats */
167 uint64_t generate_ops; /**< Count of generate operations */
168 uint64_t bytes_hashed; /**< Number of bytes hashed */
170 uint64_t verify_ops; /**< Count of verify operations */
171 uint64_t bytes_verified;/**< Number of bytes verified */
172 } hash; /**< Hash operations stats */
175 #ifdef RTE_CRYPTODEV_PERF
176 struct rte_cryptodev_perf_stats op_perf; /**< Operations stats */
178 } __rte_cache_aligned;
181 * Create a virtual crypto device
183 * @param name Cryptodev PMD name of device to be created.
184 * @param args Options arguments for device.
187 * - On successful creation of the cryptodev the device index is returned,
188 * which will be between 0 and rte_cryptodev_count().
189 * - In the case of a failure, returns -1.
192 rte_cryptodev_create_vdev(const char *name, const char *args);
195 * Get the device identifier for the named crypto device.
197 * @param name device name to select the device structure.
200 * - Returns crypto device identifier on success.
201 * - Return -1 on failure to find named crypto device.
204 rte_cryptodev_get_dev_id(const char *name);
207 * Get the total number of crypto devices that have been successfully
211 * - The total number of usable crypto devices.
214 rte_cryptodev_count(void);
217 rte_cryptodev_count_devtype(enum rte_cryptodev_type type);
219 * Return the NUMA socket to which a device is connected
222 * The identifier of the device
224 * The NUMA socket id to which the device is connected or
225 * a default of zero if the socket could not be determined.
226 * -1 if returned is the dev_id value is out of range.
229 rte_cryptodev_socket_id(uint8_t dev_id);
231 /** Crypto device configuration structure */
232 struct rte_cryptodev_config {
233 int socket_id; /**< Socket to allocate resources on */
234 uint16_t nb_queue_pairs;
235 /**< Number of queue pairs to configure on device */
238 uint32_t nb_objs; /**< Number of objects in mempool */
239 uint32_t cache_size; /**< l-core object cache size */
240 } session_mp; /**< Session mempool configuration */
244 * Configure a device.
246 * EXPERIMENTAL: this API file may change without prior notice
248 * This function must be invoked first before any other function in the
249 * API. This function can also be re-invoked when a device is in the
252 * @param dev_id The identifier of the device to configure.
253 * @param config The crypto device configuration structure.
256 * - 0: Success, device configured.
257 * - <0: Error code returned by the driver configuration function.
260 rte_cryptodev_configure(uint8_t dev_id, struct rte_cryptodev_config *config);
265 * The device start step is the last one and consists of setting the configured
266 * offload features and in starting the transmit and the receive units of the
268 * On success, all basic functions exported by the API (link status,
269 * receive/transmit, and so on) can be invoked.
272 * The identifier of the device.
274 * - 0: Success, device started.
275 * - <0: Error code of the driver device start function.
278 rte_cryptodev_start(uint8_t dev_id);
281 * Stop an device. The device can be restarted with a call to
282 * rte_cryptodev_start()
284 * @param dev_id The identifier of the device.
287 rte_cryptodev_stop(uint8_t dev_id);
290 * Close an device. The device cannot be restarted!
292 * @param dev_id The identifier of the device.
295 * - 0 on successfully closing device
296 * - <0 on failure to close device
299 rte_cryptodev_close(uint8_t dev_id);
302 * Allocate and set up a receive queue pair for a device.
305 * @param dev_id The identifier of the device.
306 * @param queue_pair_id The index of the queue pairs to set up. The
307 * value must be in the range [0, nb_queue_pair
308 * - 1] previously supplied to
309 * rte_cryptodev_configure().
310 * @param qp_conf The pointer to the configuration data to be
311 * used for the queue pair. NULL value is
312 * allowed, in which case default configuration
314 * @param socket_id The *socket_id* argument is the socket
315 * identifier in case of NUMA. The value can be
316 * *SOCKET_ID_ANY* if there is no NUMA constraint
317 * for the DMA memory allocated for the receive
321 * - 0: Success, queue pair correctly set up.
322 * - <0: Queue pair configuration failed
325 rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
326 const struct rte_cryptodev_qp_conf *qp_conf, int socket_id);
329 * Start a specified queue pair of a device. It is used
330 * when deferred_start flag of the specified queue is true.
332 * @param dev_id The identifier of the device
333 * @param queue_pair_id The index of the queue pair to start. The value
334 * must be in the range [0, nb_queue_pair - 1]
335 * previously supplied to
336 * rte_crypto_dev_configure().
338 * - 0: Success, the transmit queue is correctly set up.
339 * - -EINVAL: The dev_id or the queue_id out of range.
340 * - -ENOTSUP: The function not supported in PMD driver.
343 rte_cryptodev_queue_pair_start(uint8_t dev_id, uint16_t queue_pair_id);
346 * Stop specified queue pair of a device
348 * @param dev_id The identifier of the device
349 * @param queue_pair_id The index of the queue pair to stop. The value
350 * must be in the range [0, nb_queue_pair - 1]
351 * previously supplied to
352 * rte_cryptodev_configure().
354 * - 0: Success, the transmit queue is correctly set up.
355 * - -EINVAL: The dev_id or the queue_id out of range.
356 * - -ENOTSUP: The function not supported in PMD driver.
359 rte_cryptodev_queue_pair_stop(uint8_t dev_id, uint16_t queue_pair_id);
362 * Get the number of queue pairs on a specific crypto device
364 * @param dev_id Crypto device identifier.
366 * - The number of configured queue pairs.
369 rte_cryptodev_queue_pair_count(uint8_t dev_id);
373 * Retrieve the general I/O statistics of a device.
375 * @param dev_id The identifier of the device.
376 * @param stats A pointer to a structure of type
377 * *rte_cryptodev_stats* to be filled with the
378 * values of device counters.
380 * - Zero if successful.
381 * - Non-zero otherwise.
384 rte_cryptodev_stats_get(uint8_t dev_id, struct rte_cryptodev_stats *stats);
387 * Reset the general I/O statistics of a device.
389 * @param dev_id The identifier of the device.
392 rte_cryptodev_stats_reset(uint8_t dev_id);
395 * Retrieve the contextual information of a device.
397 * @param dev_id The identifier of the device.
398 * @param dev_info A pointer to a structure of type
399 * *rte_cryptodev_info* to be filled with the
400 * contextual information of the device.
403 rte_cryptodev_info_get(uint8_t dev_id, struct rte_cryptodev_info *dev_info);
407 * Register a callback function for specific device id.
409 * @param dev_id Device id.
410 * @param event Event interested.
411 * @param cb_fn User supplied callback function to be called.
412 * @param cb_arg Pointer to the parameters for the registered
416 * - On success, zero.
417 * - On failure, a negative value.
420 rte_cryptodev_callback_register(uint8_t dev_id,
421 enum rte_cryptodev_event_type event,
422 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
425 * Unregister a callback function for specific device id.
427 * @param dev_id The device identifier.
428 * @param event Event interested.
429 * @param cb_fn User supplied callback function to be called.
430 * @param cb_arg Pointer to the parameters for the registered
434 * - On success, zero.
435 * - On failure, a negative value.
438 rte_cryptodev_callback_unregister(uint8_t dev_id,
439 enum rte_cryptodev_event_type event,
440 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
443 typedef uint16_t (*dequeue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
445 /**< Dequeue processed packets from queue pair of a device. */
447 typedef uint16_t (*enqueue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
449 /**< Enqueue packets for processing on queue pair of a device. */
452 struct rte_cryptodev_callback;
454 /** Structure to keep track of registered callbacks */
455 TAILQ_HEAD(rte_cryptodev_cb_list, rte_cryptodev_callback);
457 /** The data structure associated with each crypto device. */
458 struct rte_cryptodev {
459 dequeue_pkt_burst_t dequeue_burst;
460 /**< Pointer to PMD receive function. */
461 enqueue_pkt_burst_t enqueue_burst;
462 /**< Pointer to PMD transmit function. */
464 const struct rte_cryptodev_driver *driver;
465 /**< Driver for this device */
466 struct rte_cryptodev_data *data;
467 /**< Pointer to device data */
468 struct rte_cryptodev_ops *dev_ops;
469 /**< Functions exported by PMD */
470 struct rte_pci_device *pci_dev;
471 /**< PCI info. supplied by probing */
473 enum rte_cryptodev_type dev_type;
474 /**< Crypto device type */
475 enum pmd_type pmd_type;
476 /**< PMD type - PDEV / VDEV */
478 struct rte_cryptodev_cb_list link_intr_cbs;
479 /**< User application callback for interrupts if present */
481 uint8_t attached : 1;
482 /**< Flag indicating the device is attached */
483 } __rte_cache_aligned;
486 #define RTE_CRYPTODEV_NAME_MAX_LEN (64)
487 /**< Max length of name of crypto PMD */
491 * The data part, with no function pointers, associated with each device.
493 * This structure is safe to place in shared memory to be common among
494 * different processes in a multi-process configuration.
496 struct rte_cryptodev_data {
498 /**< Device ID for this instance */
500 /**< Socket ID where memory is allocated */
501 char name[RTE_CRYPTODEV_NAME_MAX_LEN];
502 /**< Unique identifier name */
504 uint8_t dev_started : 1;
505 /**< Device state: STARTED(1)/STOPPED(0) */
507 struct rte_mempool *session_pool;
508 /**< Session memory pool */
510 /**< Array of pointers to queue pairs. */
511 uint16_t nb_queue_pairs;
512 /**< Number of device queue pairs. */
515 /**< PMD-specific private data */
516 } __rte_cache_aligned;
518 extern struct rte_cryptodev *rte_cryptodevs;
521 * Dequeue a burst of processed packets from a queue of the crypto device.
522 * The dequeued packets are stored in *rte_mbuf* structures whose pointers are
523 * supplied in the *pkts* array.
525 * The rte_crypto_dequeue_burst() function returns the number of packets
526 * actually dequeued, which is the number of *rte_mbuf* data structures
527 * effectively supplied into the *pkts* array.
529 * A return value equal to *nb_pkts* indicates that the queue contained
530 * at least *rx_pkts* packets, and this is likely to signify that other
531 * received packets remain in the input queue. Applications implementing
532 * a "retrieve as much received packets as possible" policy can check this
533 * specific case and keep invoking the rte_crypto_dequeue_burst() function
534 * until a value less than *nb_pkts* is returned.
536 * The rte_crypto_dequeue_burst() function does not provide any error
537 * notification to avoid the corresponding overhead.
539 * @param dev_id The identifier of the device.
540 * @param qp_id The index of the queue pair from which to
541 * retrieve processed packets. The value must be
542 * in the range [0, nb_queue_pair - 1] previously
543 * supplied to rte_cryptodev_configure().
544 * @param pkts The address of an array of pointers to
545 * *rte_mbuf* structures that must be large enough
546 * to store *nb_pkts* pointers in it.
547 * @param nb_pkts The maximum number of packets to dequeue.
550 * - The number of packets actually dequeued, which is the number
551 * of pointers to *rte_mbuf* structures effectively supplied to the
554 static inline uint16_t
555 rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
556 struct rte_mbuf **pkts, uint16_t nb_pkts)
558 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
560 nb_pkts = (*dev->dequeue_burst)
561 (dev->data->queue_pairs[qp_id], pkts, nb_pkts);
567 * Enqueue a burst of packets for processing on a crypto device.
569 * The rte_crypto_enqueue_burst() function is invoked to place packets
570 * on the queue *queue_id* of the device designated by its *dev_id*.
572 * The *nb_pkts* parameter is the number of packets to process which are
573 * supplied in the *pkts* array of *rte_mbuf* structures.
575 * The rte_crypto_enqueue_burst() function returns the number of packets it
576 * actually sent. A return value equal to *nb_pkts* means that all packets
579 * Each mbuf in the *pkts* array must have a valid *rte_mbuf_offload* structure
580 * attached which contains a valid crypto operation.
582 * @param dev_id The identifier of the device.
583 * @param qp_id The index of the queue pair which packets are
584 * to be enqueued for processing. The value
585 * must be in the range [0, nb_queue_pairs - 1]
586 * previously supplied to
587 * *rte_cryptodev_configure*.
588 * @param pkts The address of an array of *nb_pkts* pointers
589 * to *rte_mbuf* structures which contain the
591 * @param nb_pkts The number of packets to transmit.
594 * The number of packets actually enqueued on the crypto device. The return
595 * value can be less than the value of the *nb_pkts* parameter when the
596 * crypto devices queue is full or has been filled up.
597 * The number of packets is 0 if the device hasn't been started.
599 static inline uint16_t
600 rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
601 struct rte_mbuf **pkts, uint16_t nb_pkts)
603 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
605 return (*dev->enqueue_burst)(
606 dev->data->queue_pairs[qp_id], pkts, nb_pkts);
611 * Initialise a session for symmetric cryptographic operations.
613 * This function is used by the client to initialize immutable
614 * parameters of symmetric cryptographic operation.
615 * To perform the operation the rte_cryptodev_enqueue_burst function is
616 * used. Each mbuf should contain a reference to the session
617 * pointer returned from this function contained within it's crypto_op if a
618 * session-based operation is being provisioned. Memory to contain the session
619 * information is allocated from within mempool managed by the cryptodev.
621 * The rte_cryptodev_session_free must be called to free allocated
622 * memory when the session is no longer required.
624 * @param dev_id The device identifier.
625 * @param xform Crypto transform chain.
629 * Pointer to the created session or NULL
631 extern struct rte_cryptodev_session *
632 rte_cryptodev_session_create(uint8_t dev_id,
633 struct rte_crypto_xform *xform);
637 * Free the memory associated with a previously allocated session.
639 * @param dev_id The device identifier.
640 * @param session Session pointer previously allocated by
641 * *rte_cryptodev_session_create*.
644 * NULL on successful freeing of session.
645 * Session pointer on failure to free session.
647 extern struct rte_cryptodev_session *
648 rte_cryptodev_session_free(uint8_t dev_id,
649 struct rte_cryptodev_session *session);
656 #endif /* _RTE_CRYPTODEV_H_ */