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 * This function must be invoked first before any other function in the
247 * API. This function can also be re-invoked when a device is in the
250 * @param dev_id The identifier of the device to configure.
251 * @param config The crypto device configuration structure.
254 * - 0: Success, device configured.
255 * - <0: Error code returned by the driver configuration function.
258 rte_cryptodev_configure(uint8_t dev_id, struct rte_cryptodev_config *config);
263 * The device start step is the last one and consists of setting the configured
264 * offload features and in starting the transmit and the receive units of the
266 * On success, all basic functions exported by the API (link status,
267 * receive/transmit, and so on) can be invoked.
270 * The identifier of the device.
272 * - 0: Success, device started.
273 * - <0: Error code of the driver device start function.
276 rte_cryptodev_start(uint8_t dev_id);
279 * Stop an device. The device can be restarted with a call to
280 * rte_cryptodev_start()
282 * @param dev_id The identifier of the device.
285 rte_cryptodev_stop(uint8_t dev_id);
288 * Close an device. The device cannot be restarted!
290 * @param dev_id The identifier of the device.
293 * - 0 on successfully closing device
294 * - <0 on failure to close device
297 rte_cryptodev_close(uint8_t dev_id);
300 * Allocate and set up a receive queue pair for a device.
303 * @param dev_id The identifier of the device.
304 * @param queue_pair_id The index of the queue pairs to set up. The
305 * value must be in the range [0, nb_queue_pair
306 * - 1] previously supplied to
307 * rte_cryptodev_configure().
308 * @param qp_conf The pointer to the configuration data to be
309 * used for the queue pair. NULL value is
310 * allowed, in which case default configuration
312 * @param socket_id The *socket_id* argument is the socket
313 * identifier in case of NUMA. The value can be
314 * *SOCKET_ID_ANY* if there is no NUMA constraint
315 * for the DMA memory allocated for the receive
319 * - 0: Success, queue pair correctly set up.
320 * - <0: Queue pair configuration failed
323 rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
324 const struct rte_cryptodev_qp_conf *qp_conf, int socket_id);
327 * Start a specified queue pair of a device. It is used
328 * when deferred_start flag of the specified queue is true.
330 * @param dev_id The identifier of the device
331 * @param queue_pair_id The index of the queue pair to start. The value
332 * must be in the range [0, nb_queue_pair - 1]
333 * previously supplied to
334 * rte_crypto_dev_configure().
336 * - 0: Success, the transmit queue is correctly set up.
337 * - -EINVAL: The dev_id or the queue_id out of range.
338 * - -ENOTSUP: The function not supported in PMD driver.
341 rte_cryptodev_queue_pair_start(uint8_t dev_id, uint16_t queue_pair_id);
344 * Stop specified queue pair of a device
346 * @param dev_id The identifier of the device
347 * @param queue_pair_id The index of the queue pair to stop. The value
348 * must be in the range [0, nb_queue_pair - 1]
349 * previously supplied to
350 * rte_cryptodev_configure().
352 * - 0: Success, the transmit queue is correctly set up.
353 * - -EINVAL: The dev_id or the queue_id out of range.
354 * - -ENOTSUP: The function not supported in PMD driver.
357 rte_cryptodev_queue_pair_stop(uint8_t dev_id, uint16_t queue_pair_id);
360 * Get the number of queue pairs on a specific crypto device
362 * @param dev_id Crypto device identifier.
364 * - The number of configured queue pairs.
367 rte_cryptodev_queue_pair_count(uint8_t dev_id);
371 * Retrieve the general I/O statistics of a device.
373 * @param dev_id The identifier of the device.
374 * @param stats A pointer to a structure of type
375 * *rte_cryptodev_stats* to be filled with the
376 * values of device counters.
378 * - Zero if successful.
379 * - Non-zero otherwise.
382 rte_cryptodev_stats_get(uint8_t dev_id, struct rte_cryptodev_stats *stats);
385 * Reset the general I/O statistics of a device.
387 * @param dev_id The identifier of the device.
390 rte_cryptodev_stats_reset(uint8_t dev_id);
393 * Retrieve the contextual information of a device.
395 * @param dev_id The identifier of the device.
396 * @param dev_info A pointer to a structure of type
397 * *rte_cryptodev_info* to be filled with the
398 * contextual information of the device.
401 rte_cryptodev_info_get(uint8_t dev_id, struct rte_cryptodev_info *dev_info);
405 * Register a callback function for specific device id.
407 * @param dev_id Device id.
408 * @param event Event interested.
409 * @param cb_fn User supplied callback function to be called.
410 * @param cb_arg Pointer to the parameters for the registered
414 * - On success, zero.
415 * - On failure, a negative value.
418 rte_cryptodev_callback_register(uint8_t dev_id,
419 enum rte_cryptodev_event_type event,
420 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
423 * Unregister a callback function for specific device id.
425 * @param dev_id The device identifier.
426 * @param event Event interested.
427 * @param cb_fn User supplied callback function to be called.
428 * @param cb_arg Pointer to the parameters for the registered
432 * - On success, zero.
433 * - On failure, a negative value.
436 rte_cryptodev_callback_unregister(uint8_t dev_id,
437 enum rte_cryptodev_event_type event,
438 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
441 typedef uint16_t (*dequeue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
443 /**< Dequeue processed packets from queue pair of a device. */
445 typedef uint16_t (*enqueue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts,
447 /**< Enqueue packets for processing on queue pair of a device. */
450 struct rte_cryptodev_callback;
452 /** Structure to keep track of registered callbacks */
453 TAILQ_HEAD(rte_cryptodev_cb_list, rte_cryptodev_callback);
455 /** The data structure associated with each crypto device. */
456 struct rte_cryptodev {
457 dequeue_pkt_burst_t dequeue_burst;
458 /**< Pointer to PMD receive function. */
459 enqueue_pkt_burst_t enqueue_burst;
460 /**< Pointer to PMD transmit function. */
462 const struct rte_cryptodev_driver *driver;
463 /**< Driver for this device */
464 struct rte_cryptodev_data *data;
465 /**< Pointer to device data */
466 struct rte_cryptodev_ops *dev_ops;
467 /**< Functions exported by PMD */
468 struct rte_pci_device *pci_dev;
469 /**< PCI info. supplied by probing */
471 enum rte_cryptodev_type dev_type;
472 /**< Crypto device type */
473 enum pmd_type pmd_type;
474 /**< PMD type - PDEV / VDEV */
476 struct rte_cryptodev_cb_list link_intr_cbs;
477 /**< User application callback for interrupts if present */
479 uint8_t attached : 1;
480 /**< Flag indicating the device is attached */
481 } __rte_cache_aligned;
484 #define RTE_CRYPTODEV_NAME_MAX_LEN (64)
485 /**< Max length of name of crypto PMD */
489 * The data part, with no function pointers, associated with each device.
491 * This structure is safe to place in shared memory to be common among
492 * different processes in a multi-process configuration.
494 struct rte_cryptodev_data {
496 /**< Device ID for this instance */
498 /**< Socket ID where memory is allocated */
499 char name[RTE_CRYPTODEV_NAME_MAX_LEN];
500 /**< Unique identifier name */
502 uint8_t dev_started : 1;
503 /**< Device state: STARTED(1)/STOPPED(0) */
505 struct rte_mempool *session_pool;
506 /**< Session memory pool */
508 /**< Array of pointers to queue pairs. */
509 uint16_t nb_queue_pairs;
510 /**< Number of device queue pairs. */
513 /**< PMD-specific private data */
514 } __rte_cache_aligned;
516 extern struct rte_cryptodev *rte_cryptodevs;
519 * Dequeue a burst of processed packets from a queue of the crypto device.
520 * The dequeued packets are stored in *rte_mbuf* structures whose pointers are
521 * supplied in the *pkts* array.
523 * The rte_crypto_dequeue_burst() function returns the number of packets
524 * actually dequeued, which is the number of *rte_mbuf* data structures
525 * effectively supplied into the *pkts* array.
527 * A return value equal to *nb_pkts* indicates that the queue contained
528 * at least *rx_pkts* packets, and this is likely to signify that other
529 * received packets remain in the input queue. Applications implementing
530 * a "retrieve as much received packets as possible" policy can check this
531 * specific case and keep invoking the rte_crypto_dequeue_burst() function
532 * until a value less than *nb_pkts* is returned.
534 * The rte_crypto_dequeue_burst() function does not provide any error
535 * notification to avoid the corresponding overhead.
537 * @param dev_id The identifier of the device.
538 * @param qp_id The index of the queue pair from which to
539 * retrieve processed packets. The value must be
540 * in the range [0, nb_queue_pair - 1] previously
541 * supplied to rte_cryptodev_configure().
542 * @param pkts The address of an array of pointers to
543 * *rte_mbuf* structures that must be large enough
544 * to store *nb_pkts* pointers in it.
545 * @param nb_pkts The maximum number of packets to dequeue.
548 * - The number of packets actually dequeued, which is the number
549 * of pointers to *rte_mbuf* structures effectively supplied to the
552 static inline uint16_t
553 rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
554 struct rte_mbuf **pkts, uint16_t nb_pkts)
556 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
558 nb_pkts = (*dev->dequeue_burst)
559 (dev->data->queue_pairs[qp_id], pkts, nb_pkts);
565 * Enqueue a burst of packets for processing on a crypto device.
567 * The rte_crypto_enqueue_burst() function is invoked to place packets
568 * on the queue *queue_id* of the device designated by its *dev_id*.
570 * The *nb_pkts* parameter is the number of packets to process which are
571 * supplied in the *pkts* array of *rte_mbuf* structures.
573 * The rte_crypto_enqueue_burst() function returns the number of packets it
574 * actually sent. A return value equal to *nb_pkts* means that all packets
577 * Each mbuf in the *pkts* array must have a valid *rte_mbuf_offload* structure
578 * attached which contains a valid crypto operation.
580 * @param dev_id The identifier of the device.
581 * @param qp_id The index of the queue pair which packets are
582 * to be enqueued for processing. The value
583 * must be in the range [0, nb_queue_pairs - 1]
584 * previously supplied to
585 * *rte_cryptodev_configure*.
586 * @param pkts The address of an array of *nb_pkts* pointers
587 * to *rte_mbuf* structures which contain the
589 * @param nb_pkts The number of packets to transmit.
592 * The number of packets actually enqueued on the crypto device. The return
593 * value can be less than the value of the *nb_pkts* parameter when the
594 * crypto devices queue is full or has been filled up.
595 * The number of packets is 0 if the device hasn't been started.
597 static inline uint16_t
598 rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
599 struct rte_mbuf **pkts, uint16_t nb_pkts)
601 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
603 return (*dev->enqueue_burst)(
604 dev->data->queue_pairs[qp_id], pkts, nb_pkts);
609 * Initialise a session for symmetric cryptographic operations.
611 * This function is used by the client to initialize immutable
612 * parameters of symmetric cryptographic operation.
613 * To perform the operation the rte_cryptodev_enqueue_burst function is
614 * used. Each mbuf should contain a reference to the session
615 * pointer returned from this function contained within it's crypto_op if a
616 * session-based operation is being provisioned. Memory to contain the session
617 * information is allocated from within mempool managed by the cryptodev.
619 * The rte_cryptodev_session_free must be called to free allocated
620 * memory when the session is no longer required.
622 * @param dev_id The device identifier.
623 * @param xform Crypto transform chain.
627 * Pointer to the created session or NULL
629 extern struct rte_cryptodev_session *
630 rte_cryptodev_session_create(uint8_t dev_id,
631 struct rte_crypto_xform *xform);
635 * Free the memory associated with a previously allocated session.
637 * @param dev_id The device identifier.
638 * @param session Session pointer previously allocated by
639 * *rte_cryptodev_session_create*.
642 * NULL on successful freeing of session.
643 * Session pointer on failure to free session.
645 extern struct rte_cryptodev_session *
646 rte_cryptodev_session_free(uint8_t dev_id,
647 struct rte_cryptodev_session *session);
654 #endif /* _RTE_CRYPTODEV_H_ */