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.
43 * @b EXPERIMENTAL: this API may change without prior notice
51 #include "rte_kvargs.h"
52 #include "rte_crypto.h"
55 #define CRYPTODEV_NAME_NULL_PMD ("cryptodev_null_pmd")
56 /**< Null crypto PMD device name */
57 #define CRYPTODEV_NAME_AESNI_MB_PMD ("cryptodev_aesni_mb_pmd")
58 /**< AES-NI Multi buffer PMD device name */
59 #define CRYPTODEV_NAME_AESNI_GCM_PMD ("cryptodev_aesni_gcm_pmd")
60 /**< AES-NI GCM PMD device name */
61 #define CRYPTODEV_NAME_QAT_SYM_PMD ("cryptodev_qat_sym_pmd")
62 /**< Intel QAT Symmetric Crypto PMD device name */
63 #define CRYPTODEV_NAME_SNOW3G_PMD ("cryptodev_snow3g_pmd")
64 /**< SNOW 3G PMD device name */
66 /** Crypto device type */
67 enum rte_cryptodev_type {
68 RTE_CRYPTODEV_NULL_PMD = 1, /**< Null crypto PMD */
69 RTE_CRYPTODEV_AESNI_GCM_PMD, /**< AES-NI GCM PMD */
70 RTE_CRYPTODEV_AESNI_MB_PMD, /**< AES-NI multi buffer PMD */
71 RTE_CRYPTODEV_QAT_SYM_PMD, /**< QAT PMD Symmetric Crypto */
72 RTE_CRYPTODEV_SNOW3G_PMD, /**< SNOW 3G PMD */
75 extern const char **rte_cyptodev_names;
79 #define CDEV_LOG_ERR(fmt, args...) \
80 RTE_LOG(ERR, CRYPTODEV, "%s() line %u: " fmt "\n", \
81 __func__, __LINE__, ## args)
83 #define CDEV_PMD_LOG_ERR(dev, fmt, args...) \
84 RTE_LOG(ERR, CRYPTODEV, "[%s] %s() line %u: " fmt "\n", \
85 dev, __func__, __LINE__, ## args)
87 #ifdef RTE_LIBRTE_CRYPTODEV_DEBUG
88 #define CDEV_LOG_DEBUG(fmt, args...) \
89 RTE_LOG(DEBUG, CRYPTODEV, "%s() line %u: " fmt "\n", \
90 __func__, __LINE__, ## args) \
92 #define CDEV_PMD_TRACE(fmt, args...) \
93 RTE_LOG(DEBUG, CRYPTODEV, "[%s] %s: " fmt "\n", \
94 dev, __func__, ## args)
97 #define CDEV_LOG_DEBUG(fmt, args...)
98 #define CDEV_PMD_TRACE(fmt, args...)
101 /** Crypto device information */
102 struct rte_cryptodev_info {
103 const char *driver_name; /**< Driver name. */
104 enum rte_cryptodev_type dev_type; /**< Device type */
105 struct rte_pci_device *pci_dev; /**< PCI information. */
107 unsigned max_nb_queue_pairs;
108 /**< Maximum number of queues pairs supported by device. */
111 unsigned max_nb_sessions;
112 /**< Maximum number of sessions supported by device. */
116 #define RTE_CRYPTODEV_DETACHED (0)
117 #define RTE_CRYPTODEV_ATTACHED (1)
119 /** Definitions of Crypto device event types */
120 enum rte_cryptodev_event_type {
121 RTE_CRYPTODEV_EVENT_UNKNOWN, /**< unknown event type */
122 RTE_CRYPTODEV_EVENT_ERROR, /**< error interrupt event */
123 RTE_CRYPTODEV_EVENT_MAX /**< max value of this enum */
126 /** Crypto device queue pair configuration structure. */
127 struct rte_cryptodev_qp_conf {
128 uint32_t nb_descriptors; /**< Number of descriptors per queue pair */
132 * Typedef for application callback function to be registered by application
133 * software for notification of device events
135 * @param dev_id Crypto device identifier
136 * @param event Crypto device event to register for notification of.
137 * @param cb_arg User specified parameter to be passed as to passed to
138 * users callback function.
140 typedef void (*rte_cryptodev_cb_fn)(uint8_t dev_id,
141 enum rte_cryptodev_event_type event, void *cb_arg);
144 /** Crypto Device statistics */
145 struct rte_cryptodev_stats {
146 uint64_t enqueued_count;
147 /**< Count of all operations enqueued */
148 uint64_t dequeued_count;
149 /**< Count of all operations dequeued */
151 uint64_t enqueue_err_count;
152 /**< Total error count on operations enqueued */
153 uint64_t dequeue_err_count;
154 /**< Total error count on operations dequeued */
157 #define RTE_CRYPTODEV_VDEV_DEFAULT_MAX_NB_QUEUE_PAIRS 8
158 #define RTE_CRYPTODEV_VDEV_DEFAULT_MAX_NB_SESSIONS 2048
162 * Initialisation parameters for virtual crypto devices
164 struct rte_crypto_vdev_init_params {
165 unsigned max_nb_queue_pairs;
166 unsigned max_nb_sessions;
170 #define RTE_CRYPTODEV_VDEV_MAX_NB_QP_ARG ("max_nb_queue_pairs")
171 #define RTE_CRYPTODEV_VDEV_MAX_NB_SESS_ARG ("max_nb_sessions")
172 #define RTE_CRYPTODEV_VDEV_SOCKET_ID ("socket_id")
174 static const char *cryptodev_vdev_valid_params[] = {
175 RTE_CRYPTODEV_VDEV_MAX_NB_QP_ARG,
176 RTE_CRYPTODEV_VDEV_MAX_NB_SESS_ARG,
177 RTE_CRYPTODEV_VDEV_SOCKET_ID
180 static inline uint8_t
181 number_of_sockets(void)
185 const struct rte_memseg *ms = rte_eal_get_physmem_layout();
187 for (i = 0; ((i < RTE_MAX_MEMSEG) && (ms[i].addr != NULL)); i++) {
188 if (sockets < ms[i].socket_id)
189 sockets = ms[i].socket_id;
192 /* Number of sockets = maximum socket_id + 1 */
196 /** Parse integer from integer argument */
198 __rte_cryptodev_parse_integer_arg(const char *key __rte_unused,
199 const char *value, void *extra_args)
201 int *i = (int *) extra_args;
205 CDEV_LOG_ERR("Argument has to be positive.");
213 * Parse virtual device initialisation parameters input arguments
216 * @params params Initialisation parameters with defaults set.
217 * @params input_args Command line arguments
220 * 0 on successful parse
221 * <0 on failure to parse
224 rte_cryptodev_parse_vdev_init_params(struct rte_crypto_vdev_init_params *params,
225 const char *input_args)
227 struct rte_kvargs *kvlist;
234 kvlist = rte_kvargs_parse(input_args,
235 cryptodev_vdev_valid_params);
239 ret = rte_kvargs_process(kvlist,
240 RTE_CRYPTODEV_VDEV_MAX_NB_QP_ARG,
241 &__rte_cryptodev_parse_integer_arg,
242 ¶ms->max_nb_queue_pairs);
246 ret = rte_kvargs_process(kvlist,
247 RTE_CRYPTODEV_VDEV_MAX_NB_SESS_ARG,
248 &__rte_cryptodev_parse_integer_arg,
249 ¶ms->max_nb_sessions);
253 ret = rte_kvargs_process(kvlist, RTE_CRYPTODEV_VDEV_SOCKET_ID,
254 &__rte_cryptodev_parse_integer_arg,
259 if (params->socket_id >= number_of_sockets()) {
260 CDEV_LOG_ERR("Invalid socket id specified to create "
261 "the virtual crypto device on");
269 rte_kvargs_free(kvlist);
274 * Create a virtual crypto device
276 * @param name Cryptodev PMD name of device to be created.
277 * @param args Options arguments for device.
280 * - On successful creation of the cryptodev the device index is returned,
281 * which will be between 0 and rte_cryptodev_count().
282 * - In the case of a failure, returns -1.
285 rte_cryptodev_create_vdev(const char *name, const char *args);
288 * Get the device identifier for the named crypto device.
290 * @param name device name to select the device structure.
293 * - Returns crypto device identifier on success.
294 * - Return -1 on failure to find named crypto device.
297 rte_cryptodev_get_dev_id(const char *name);
300 * Get the total number of crypto devices that have been successfully
304 * - The total number of usable crypto devices.
307 rte_cryptodev_count(void);
310 rte_cryptodev_count_devtype(enum rte_cryptodev_type type);
312 * Return the NUMA socket to which a device is connected
315 * The identifier of the device
317 * The NUMA socket id to which the device is connected or
318 * a default of zero if the socket could not be determined.
319 * -1 if returned is the dev_id value is out of range.
322 rte_cryptodev_socket_id(uint8_t dev_id);
324 /** Crypto device configuration structure */
325 struct rte_cryptodev_config {
326 int socket_id; /**< Socket to allocate resources on */
327 uint16_t nb_queue_pairs;
328 /**< Number of queue pairs to configure on device */
331 uint32_t nb_objs; /**< Number of objects in mempool */
332 uint32_t cache_size; /**< l-core object cache size */
333 } session_mp; /**< Session mempool configuration */
337 * Configure a device.
339 * This function must be invoked first before any other function in the
340 * API. This function can also be re-invoked when a device is in the
343 * @param dev_id The identifier of the device to configure.
344 * @param config The crypto device configuration structure.
347 * - 0: Success, device configured.
348 * - <0: Error code returned by the driver configuration function.
351 rte_cryptodev_configure(uint8_t dev_id, struct rte_cryptodev_config *config);
356 * The device start step is the last one and consists of setting the configured
357 * offload features and in starting the transmit and the receive units of the
359 * On success, all basic functions exported by the API (link status,
360 * receive/transmit, and so on) can be invoked.
363 * The identifier of the device.
365 * - 0: Success, device started.
366 * - <0: Error code of the driver device start function.
369 rte_cryptodev_start(uint8_t dev_id);
372 * Stop an device. The device can be restarted with a call to
373 * rte_cryptodev_start()
375 * @param dev_id The identifier of the device.
378 rte_cryptodev_stop(uint8_t dev_id);
381 * Close an device. The device cannot be restarted!
383 * @param dev_id The identifier of the device.
386 * - 0 on successfully closing device
387 * - <0 on failure to close device
390 rte_cryptodev_close(uint8_t dev_id);
393 * Allocate and set up a receive queue pair for a device.
396 * @param dev_id The identifier of the device.
397 * @param queue_pair_id The index of the queue pairs to set up. The
398 * value must be in the range [0, nb_queue_pair
399 * - 1] previously supplied to
400 * rte_cryptodev_configure().
401 * @param qp_conf The pointer to the configuration data to be
402 * used for the queue pair. NULL value is
403 * allowed, in which case default configuration
405 * @param socket_id The *socket_id* argument is the socket
406 * identifier in case of NUMA. The value can be
407 * *SOCKET_ID_ANY* if there is no NUMA constraint
408 * for the DMA memory allocated for the receive
412 * - 0: Success, queue pair correctly set up.
413 * - <0: Queue pair configuration failed
416 rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id,
417 const struct rte_cryptodev_qp_conf *qp_conf, int socket_id);
420 * Start a specified queue pair of a device. It is used
421 * when deferred_start flag of the specified queue is true.
423 * @param dev_id The identifier of the device
424 * @param queue_pair_id The index of the queue pair to start. The value
425 * must be in the range [0, nb_queue_pair - 1]
426 * previously supplied to
427 * rte_crypto_dev_configure().
429 * - 0: Success, the transmit queue is correctly set up.
430 * - -EINVAL: The dev_id or the queue_id out of range.
431 * - -ENOTSUP: The function not supported in PMD driver.
434 rte_cryptodev_queue_pair_start(uint8_t dev_id, uint16_t queue_pair_id);
437 * Stop specified queue pair of a device
439 * @param dev_id The identifier of the device
440 * @param queue_pair_id The index of the queue pair to stop. The value
441 * must be in the range [0, nb_queue_pair - 1]
442 * previously supplied to
443 * rte_cryptodev_configure().
445 * - 0: Success, the transmit queue is correctly set up.
446 * - -EINVAL: The dev_id or the queue_id out of range.
447 * - -ENOTSUP: The function not supported in PMD driver.
450 rte_cryptodev_queue_pair_stop(uint8_t dev_id, uint16_t queue_pair_id);
453 * Get the number of queue pairs on a specific crypto device
455 * @param dev_id Crypto device identifier.
457 * - The number of configured queue pairs.
460 rte_cryptodev_queue_pair_count(uint8_t dev_id);
464 * Retrieve the general I/O statistics of a device.
466 * @param dev_id The identifier of the device.
467 * @param stats A pointer to a structure of type
468 * *rte_cryptodev_stats* to be filled with the
469 * values of device counters.
471 * - Zero if successful.
472 * - Non-zero otherwise.
475 rte_cryptodev_stats_get(uint8_t dev_id, struct rte_cryptodev_stats *stats);
478 * Reset the general I/O statistics of a device.
480 * @param dev_id The identifier of the device.
483 rte_cryptodev_stats_reset(uint8_t dev_id);
486 * Retrieve the contextual information of a device.
488 * @param dev_id The identifier of the device.
489 * @param dev_info A pointer to a structure of type
490 * *rte_cryptodev_info* to be filled with the
491 * contextual information of the device.
494 rte_cryptodev_info_get(uint8_t dev_id, struct rte_cryptodev_info *dev_info);
498 * Register a callback function for specific device id.
500 * @param dev_id Device id.
501 * @param event Event interested.
502 * @param cb_fn User supplied callback function to be called.
503 * @param cb_arg Pointer to the parameters for the registered
507 * - On success, zero.
508 * - On failure, a negative value.
511 rte_cryptodev_callback_register(uint8_t dev_id,
512 enum rte_cryptodev_event_type event,
513 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
516 * Unregister a callback function for specific device id.
518 * @param dev_id The device identifier.
519 * @param event Event interested.
520 * @param cb_fn User supplied callback function to be called.
521 * @param cb_arg Pointer to the parameters for the registered
525 * - On success, zero.
526 * - On failure, a negative value.
529 rte_cryptodev_callback_unregister(uint8_t dev_id,
530 enum rte_cryptodev_event_type event,
531 rte_cryptodev_cb_fn cb_fn, void *cb_arg);
534 typedef uint16_t (*dequeue_pkt_burst_t)(void *qp,
535 struct rte_crypto_op **ops, uint16_t nb_ops);
536 /**< Dequeue processed packets from queue pair of a device. */
538 typedef uint16_t (*enqueue_pkt_burst_t)(void *qp,
539 struct rte_crypto_op **ops, uint16_t nb_ops);
540 /**< Enqueue packets for processing on queue pair of a device. */
543 struct rte_cryptodev_callback;
545 /** Structure to keep track of registered callbacks */
546 TAILQ_HEAD(rte_cryptodev_cb_list, rte_cryptodev_callback);
548 /** The data structure associated with each crypto device. */
549 struct rte_cryptodev {
550 dequeue_pkt_burst_t dequeue_burst;
551 /**< Pointer to PMD receive function. */
552 enqueue_pkt_burst_t enqueue_burst;
553 /**< Pointer to PMD transmit function. */
555 const struct rte_cryptodev_driver *driver;
556 /**< Driver for this device */
557 struct rte_cryptodev_data *data;
558 /**< Pointer to device data */
559 struct rte_cryptodev_ops *dev_ops;
560 /**< Functions exported by PMD */
561 struct rte_pci_device *pci_dev;
562 /**< PCI info. supplied by probing */
564 enum rte_cryptodev_type dev_type;
565 /**< Crypto device type */
566 enum pmd_type pmd_type;
567 /**< PMD type - PDEV / VDEV */
569 struct rte_cryptodev_cb_list link_intr_cbs;
570 /**< User application callback for interrupts if present */
572 uint8_t attached : 1;
573 /**< Flag indicating the device is attached */
574 } __rte_cache_aligned;
577 #define RTE_CRYPTODEV_NAME_MAX_LEN (64)
578 /**< Max length of name of crypto PMD */
582 * The data part, with no function pointers, associated with each device.
584 * This structure is safe to place in shared memory to be common among
585 * different processes in a multi-process configuration.
587 struct rte_cryptodev_data {
589 /**< Device ID for this instance */
591 /**< Socket ID where memory is allocated */
592 char name[RTE_CRYPTODEV_NAME_MAX_LEN];
593 /**< Unique identifier name */
595 uint8_t dev_started : 1;
596 /**< Device state: STARTED(1)/STOPPED(0) */
598 struct rte_mempool *session_pool;
599 /**< Session memory pool */
601 /**< Array of pointers to queue pairs. */
602 uint16_t nb_queue_pairs;
603 /**< Number of device queue pairs. */
606 /**< PMD-specific private data */
607 } __rte_cache_aligned;
609 extern struct rte_cryptodev *rte_cryptodevs;
612 * Dequeue a burst of processed crypto operations from a queue on the crypto
613 * device. The dequeued operation are stored in *rte_crypto_op* structures
614 * whose pointers are supplied in the *ops* array.
616 * The rte_cryptodev_dequeue_burst() function returns the number of ops
617 * actually dequeued, which is the number of *rte_crypto_op* data structures
618 * effectively supplied into the *ops* array.
620 * A return value equal to *nb_ops* indicates that the queue contained
621 * at least *nb_ops* operations, and this is likely to signify that other
622 * processed operations remain in the devices output queue. Applications
623 * implementing a "retrieve as many processed operations as possible" policy
624 * can check this specific case and keep invoking the
625 * rte_cryptodev_dequeue_burst() function until a value less than
626 * *nb_ops* is returned.
628 * The rte_cryptodev_dequeue_burst() function does not provide any error
629 * notification to avoid the corresponding overhead.
631 * @param dev_id The symmetric crypto device identifier
632 * @param qp_id The index of the queue pair from which to
633 * retrieve processed packets. The value must be
634 * in the range [0, nb_queue_pair - 1] previously
635 * supplied to rte_cryptodev_configure().
636 * @param ops The address of an array of pointers to
637 * *rte_crypto_op* structures that must be
638 * large enough to store *nb_ops* pointers in it.
639 * @param nb_ops The maximum number of operations to dequeue.
642 * - The number of operations actually dequeued, which is the number
643 * of pointers to *rte_crypto_op* structures effectively supplied to the
646 static inline uint16_t
647 rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
648 struct rte_crypto_op **ops, uint16_t nb_ops)
650 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
652 nb_ops = (*dev->dequeue_burst)
653 (dev->data->queue_pairs[qp_id], ops, nb_ops);
659 * Enqueue a burst of operations for processing on a crypto device.
661 * The rte_cryptodev_enqueue_burst() function is invoked to place
662 * crypto operations on the queue *qp_id* of the device designated by
665 * The *nb_ops* parameter is the number of operations to process which are
666 * supplied in the *ops* array of *rte_crypto_op* structures.
668 * The rte_cryptodev_enqueue_burst() function returns the number of
669 * operations it actually enqueued for processing. A return value equal to
670 * *nb_ops* means that all packets have been enqueued.
672 * @param dev_id The identifier of the device.
673 * @param qp_id The index of the queue pair which packets are
674 * to be enqueued for processing. The value
675 * must be in the range [0, nb_queue_pairs - 1]
676 * previously supplied to
677 * *rte_cryptodev_configure*.
678 * @param ops The address of an array of *nb_ops* pointers
679 * to *rte_crypto_op* structures which contain
680 * the crypto operations to be processed.
681 * @param nb_ops The number of operations to process.
684 * The number of operations actually enqueued on the crypto device. The return
685 * value can be less than the value of the *nb_ops* parameter when the
686 * crypto devices queue is full or if invalid parameters are specified in
689 static inline uint16_t
690 rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
691 struct rte_crypto_op **ops, uint16_t nb_ops)
693 struct rte_cryptodev *dev = &rte_cryptodevs[dev_id];
695 return (*dev->enqueue_burst)(
696 dev->data->queue_pairs[qp_id], ops, nb_ops);
700 /** Cryptodev symmetric crypto session */
701 struct rte_cryptodev_sym_session {
705 enum rte_cryptodev_type type;
706 /** Crypto Device type session created on */
707 struct rte_mempool *mp;
708 /**< Mempool session allocated from */
710 /**< Public symmetric session details */
713 /**< Private session material */
718 * Initialise a session for symmetric cryptographic operations.
720 * This function is used by the client to initialize immutable
721 * parameters of symmetric cryptographic operation.
722 * To perform the operation the rte_cryptodev_enqueue_burst function is
723 * used. Each mbuf should contain a reference to the session
724 * pointer returned from this function contained within it's crypto_op if a
725 * session-based operation is being provisioned. Memory to contain the session
726 * information is allocated from within mempool managed by the cryptodev.
728 * The rte_cryptodev_session_free must be called to free allocated
729 * memory when the session is no longer required.
731 * @param dev_id The device identifier.
732 * @param xform Crypto transform chain.
736 * Pointer to the created session or NULL
738 extern struct rte_cryptodev_sym_session *
739 rte_cryptodev_sym_session_create(uint8_t dev_id,
740 struct rte_crypto_sym_xform *xform);
743 * Free the memory associated with a previously allocated session.
745 * @param dev_id The device identifier.
746 * @param session Session pointer previously allocated by
747 * *rte_cryptodev_sym_session_create*.
750 * NULL on successful freeing of session.
751 * Session pointer on failure to free session.
753 extern struct rte_cryptodev_sym_session *
754 rte_cryptodev_sym_session_free(uint8_t dev_id,
755 struct rte_cryptodev_sym_session *session);
762 #endif /* _RTE_CRYPTODEV_H_ */