#include "stddef.h"
#include "rte_crypto.h"
#include "rte_dev.h"

Data Structures
struct	rte_cryptodev_info
struct	rte_cryptodev_qp_conf
struct	rte_cryptodev_stats
struct	rte_cryptodev_config
struct	rte_cryptodev
struct	rte_cryptodev_data

Macros
#define	CRYPTODEV_NAME_NULL_PMD ("cryptodev_null_pmd")
#define	CRYPTODEV_NAME_AESNI_MB_PMD ("cryptodev_aesni_mb_pmd")
#define	CRYPTODEV_NAME_QAT_PMD ("cryptodev_qat_pmd")
#define	RTE_CRYPTODEV_NAME_MAX_LEN (64)

Typedefs
typedef void(*	rte_cryptodev_cb_fn )(uint8_t dev_id, enum rte_cryptodev_event_type event, void *cb_arg)
typedef uint16_t(*	dequeue_pkt_burst_t )(void qp, struct rte_mbuf *pkts, uint16_t nb_pkts)
typedef uint16_t(*	enqueue_pkt_burst_t )(void qp, struct rte_mbuf *pkts, uint16_t nb_pkts)

Enumerations
enum	rte_cryptodev_type { RTE_CRYPTODEV_NULL_PMD = 1, RTE_CRYPTODEV_AESNI_MB_PMD, RTE_CRYPTODEV_QAT_PMD }
enum	rte_cryptodev_event_type { RTE_CRYPTODEV_EVENT_UNKNOWN, RTE_CRYPTODEV_EVENT_ERROR, RTE_CRYPTODEV_EVENT_MAX }

Functions
int	rte_cryptodev_create_vdev (const char name, const char args)
int	rte_cryptodev_get_dev_id (const char *name)
uint8_t	rte_cryptodev_count (void)
int	rte_cryptodev_configure (uint8_t dev_id, struct rte_cryptodev_config *config)
int	rte_cryptodev_start (uint8_t dev_id)
void	rte_cryptodev_stop (uint8_t dev_id)
int	rte_cryptodev_close (uint8_t dev_id)
int	rte_cryptodev_queue_pair_setup (uint8_t dev_id, uint16_t queue_pair_id, const struct rte_cryptodev_qp_conf *qp_conf, int socket_id)
int	rte_cryptodev_queue_pair_start (uint8_t dev_id, uint16_t queue_pair_id)
int	rte_cryptodev_queue_pair_stop (uint8_t dev_id, uint16_t queue_pair_id)
uint16_t	rte_cryptodev_queue_pair_count (uint8_t dev_id)
int	rte_cryptodev_stats_get (uint8_t dev_id, struct rte_cryptodev_stats *stats)
void	rte_cryptodev_stats_reset (uint8_t dev_id)
void	rte_cryptodev_info_get (uint8_t dev_id, struct rte_cryptodev_info *dev_info)
int	rte_cryptodev_callback_register (uint8_t dev_id, enum rte_cryptodev_event_type event, rte_cryptodev_cb_fn cb_fn, void *cb_arg)
int	rte_cryptodev_callback_unregister (uint8_t dev_id, enum rte_cryptodev_event_type event, rte_cryptodev_cb_fn cb_fn, void *cb_arg)
	TAILQ_HEAD (rte_cryptodev_cb_list, rte_cryptodev_callback)
static uint16_t	rte_cryptodev_dequeue_burst (uint8_t dev_id, uint16_t qp_id, struct rte_mbuf **pkts, uint16_t nb_pkts)
static uint16_t	rte_cryptodev_enqueue_burst (uint8_t dev_id, uint16_t qp_id, struct rte_mbuf **pkts, uint16_t nb_pkts)
struct rte_cryptodev_session *	rte_cryptodev_session_create (uint8_t dev_id, struct rte_crypto_xform *xform)
struct rte_cryptodev_session *	rte_cryptodev_session_free (uint8_t dev_id, struct rte_cryptodev_session *session)

Detailed Description

RTE Cryptographic Device APIs

Defines RTE Crypto Device APIs for the provisioning of cipher and authentication operations.

Warning: EXPERIMENTAL: this API may change without prior notice

Definition in file rte_cryptodev.h.

Macro Definition Documentation

#define CRYPTODEV_NAME_NULL_PMD ("cryptodev_null_pmd")

Null crypto PMD device name

Definition at line 56 of file rte_cryptodev.h.

#define CRYPTODEV_NAME_AESNI_MB_PMD ("cryptodev_aesni_mb_pmd")

AES-NI Multi buffer PMD device name

Examples:: l2fwd-crypto/main.c.

Definition at line 58 of file rte_cryptodev.h.

#define CRYPTODEV_NAME_QAT_PMD ("cryptodev_qat_pmd")

Intel QAT PMD device name

Definition at line 60 of file rte_cryptodev.h.

#define RTE_CRYPTODEV_NAME_MAX_LEN (64)

Max length of name of crypto PMD

Definition at line 486 of file rte_cryptodev.h.

Typedef Documentation

typedef void(* rte_cryptodev_cb_fn)(uint8_t dev_id, enum rte_cryptodev_event_type event, void *cb_arg)

Typedef for application callback function to be registered by application software for notification of device events

Parameters

dev_id	Crypto device identifier
event	Crypto device event to register for notification of.
cb_arg	User specified parameter to be passed as to passed to users callback function.

Definition at line 130 of file rte_cryptodev.h.

typedef uint16_t(* dequeue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts, uint16_t nb_pkts)

Dequeue processed packets from queue pair of a device.

Definition at line 443 of file rte_cryptodev.h.

typedef uint16_t(* enqueue_pkt_burst_t)(void *qp, struct rte_mbuf **pkts, uint16_t nb_pkts)

Enqueue packets for processing on queue pair of a device.

Definition at line 447 of file rte_cryptodev.h.

Enumeration Type Documentation

enum rte_cryptodev_type

Crypto device type

Enumerator:

RTE_CRYPTODEV_NULL_PMD	Null crypto PMD
RTE_CRYPTODEV_AESNI_MB_PMD	AES-NI multi buffer PMD
RTE_CRYPTODEV_QAT_PMD	QAT PMD

Definition at line 64 of file rte_cryptodev.h.

enum rte_cryptodev_event_type

Definitions of Crypto device event types

Enumerator:

RTE_CRYPTODEV_EVENT_UNKNOWN	unknown event type
RTE_CRYPTODEV_EVENT_ERROR	error interrupt event
RTE_CRYPTODEV_EVENT_MAX	max value of this enum

Definition at line 110 of file rte_cryptodev.h.

Function Documentation

int rte_cryptodev_create_vdev	(	const char *	name,
		const char *	args
	)

Create a virtual crypto device

Parameters

name	Cryptodev PMD name of device to be created.
args	Options arguments for device.

Returns

On successful creation of the cryptodev the device index is returned, which will be between 0 and rte_cryptodev_count().
In the case of a failure, returns -1.

int rte_cryptodev_get_dev_id ( const char * name )

Get the device identifier for the named crypto device.

Parameters

name	device name to select the device structure.

Returns

Returns crypto device identifier on success.
Return -1 on failure to find named crypto device.

uint8_t rte_cryptodev_count ( void )

Get the total number of crypto devices that have been successfully initialised.

Returns

The total number of usable crypto devices.

Examples:: l2fwd-crypto/main.c.

int rte_cryptodev_configure	(	uint8_t	dev_id,
		struct rte_cryptodev_config *	config
	)

Configure a device.

EXPERIMENTAL: this API file may change without prior notice

This function must be invoked first before any other function in the API. This function can also be re-invoked when a device is in the stopped state.

Parameters

dev_id	The identifier of the device to configure.
config	The crypto device configuration structure.

Returns

0: Success, device configured.
<0: Error code returned by the driver configuration function.

Examples:: l2fwd-crypto/main.c.

int rte_cryptodev_start ( uint8_t dev_id )

Start an device.

The device start step is the last one and consists of setting the configured offload features and in starting the transmit and the receive units of the device. On success, all basic functions exported by the API (link status, receive/transmit, and so on) can be invoked.

Parameters

dev_id The identifier of the device.

Returns

0: Success, device started.
<0: Error code of the driver device start function.

void rte_cryptodev_stop ( uint8_t dev_id )

Stop an device. The device can be restarted with a call to rte_cryptodev_start()

Parameters

dev_id The identifier of the device.

int rte_cryptodev_close ( uint8_t dev_id )

Close an device. The device cannot be restarted!

Parameters

dev_id The identifier of the device.

Returns

0 on successfully closing device
<0 on failure to close device

int rte_cryptodev_queue_pair_setup	(	uint8_t	dev_id,
		uint16_t	queue_pair_id,
		const struct rte_cryptodev_qp_conf *	qp_conf,
		int	socket_id
	)

Allocate and set up a receive queue pair for a device.

Parameters

dev_id	The identifier of the device.
queue_pair_id	The index of the queue pairs to set up. The value must be in the range [0, nb_queue_pair 1] previously supplied to rte_cryptodev_configure().
qp_conf	The pointer to the configuration data to be used for the queue pair. NULL value is allowed, in which case default configuration will be used.
socket_id	The socket_id argument is the socket identifier in case of NUMA. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the DMA memory allocated for the receive queue pair.

Returns

0: Success, queue pair correctly set up.
<0: Queue pair configuration failed

Examples:: l2fwd-crypto/main.c.

int rte_cryptodev_queue_pair_start	(	uint8_t	dev_id,
		uint16_t	queue_pair_id
	)

Start a specified queue pair of a device. It is used when deferred_start flag of the specified queue is true.

Parameters

dev_id	The identifier of the device
queue_pair_id	The index of the queue pair to start. The value must be in the range [0, nb_queue_pair - 1] previously supplied to rte_crypto_dev_configure().

Returns

0: Success, the transmit queue is correctly set up.
-EINVAL: The dev_id or the queue_id out of range.
-ENOTSUP: The function not supported in PMD driver.

int rte_cryptodev_queue_pair_stop	(	uint8_t	dev_id,
		uint16_t	queue_pair_id
	)

Stop specified queue pair of a device

Parameters

dev_id	The identifier of the device
queue_pair_id	The index of the queue pair to stop. The value must be in the range [0, nb_queue_pair - 1] previously supplied to rte_cryptodev_configure().

Returns

0: Success, the transmit queue is correctly set up.
-EINVAL: The dev_id or the queue_id out of range.
-ENOTSUP: The function not supported in PMD driver.

uint16_t rte_cryptodev_queue_pair_count ( uint8_t dev_id )

Get the number of queue pairs on a specific crypto device

Parameters

dev_id Crypto device identifier.

Returns

The number of configured queue pairs.

int rte_cryptodev_stats_get	(	uint8_t	dev_id,
		struct rte_cryptodev_stats *	stats
	)

Retrieve the general I/O statistics of a device.

Parameters

dev_id	The identifier of the device.
stats	A pointer to a structure of type rte_cryptodev_stats to be filled with the values of device counters.

Returns

Zero if successful.
Non-zero otherwise.

void rte_cryptodev_stats_reset ( uint8_t dev_id )

Reset the general I/O statistics of a device.

Parameters

dev_id The identifier of the device.

void rte_cryptodev_info_get	(	uint8_t	dev_id,
		struct rte_cryptodev_info *	dev_info
	)

Retrieve the contextual information of a device.

Parameters

dev_id	The identifier of the device.
dev_info	A pointer to a structure of type rte_cryptodev_info to be filled with the contextual information of the device.

Examples:: l2fwd-crypto/main.c.

int rte_cryptodev_callback_register	(	uint8_t	dev_id,
		enum rte_cryptodev_event_type	event,
		rte_cryptodev_cb_fn	cb_fn,
		void *	cb_arg
	)

Register a callback function for specific device id.

Parameters

dev_id	Device id.
event	Event interested.
cb_fn	User supplied callback function to be called.
cb_arg	Pointer to the parameters for the registered callback.

Returns

On success, zero.
On failure, a negative value.

int rte_cryptodev_callback_unregister	(	uint8_t	dev_id,
		enum rte_cryptodev_event_type	event,
		rte_cryptodev_cb_fn	cb_fn,
		void *	cb_arg
	)

Unregister a callback function for specific device id.

Parameters

dev_id	The device identifier.
event	Event interested.
cb_fn	User supplied callback function to be called.
cb_arg	Pointer to the parameters for the registered callback.

Returns

On success, zero.
On failure, a negative value.

TAILQ_HEAD	(	rte_cryptodev_cb_list	,
		rte_cryptodev_callback
	)

Structure to keep track of registered callbacks

static uint16_t rte_cryptodev_dequeue_burst	(	uint8_t	dev_id,
		uint16_t	qp_id,
		struct rte_mbuf **	pkts,
		uint16_t	nb_pkts
	)

inlinestatic

Dequeue a burst of processed packets from a queue of the crypto device. The dequeued packets are stored in rte_mbuf structures whose pointers are supplied in the pkts array.

The rte_crypto_dequeue_burst() function returns the number of packets actually dequeued, which is the number of rte_mbuf data structures effectively supplied into the pkts array.

A return value equal to nb_pkts indicates that the queue contained at least rx_pkts packets, and this is likely to signify that other received packets remain in the input queue. Applications implementing a "retrieve as much received packets as possible" policy can check this specific case and keep invoking the rte_crypto_dequeue_burst() function until a value less than nb_pkts is returned.

The rte_crypto_dequeue_burst() function does not provide any error notification to avoid the corresponding overhead.

Parameters

dev_id	The identifier of the device.
qp_id	The index of the queue pair from which to retrieve processed packets. The value must be in the range [0, nb_queue_pair - 1] previously supplied to rte_cryptodev_configure().
pkts	The address of an array of pointers to rte_mbuf structures that must be large enough to store nb_pkts pointers in it.
nb_pkts	The maximum number of packets to dequeue.

Returns

The number of packets actually dequeued, which is the number of pointers to rte_mbuf structures effectively supplied to the pkts array.

Examples:: l2fwd-crypto/main.c.

Definition at line 555 of file rte_cryptodev.h.

static uint16_t rte_cryptodev_enqueue_burst	(	uint8_t	dev_id,
		uint16_t	qp_id,
		struct rte_mbuf **	pkts,
		uint16_t	nb_pkts
	)

inlinestatic

Enqueue a burst of packets for processing on a crypto device.

The rte_crypto_enqueue_burst() function is invoked to place packets on the queue queue_id of the device designated by its dev_id.

The nb_pkts parameter is the number of packets to process which are supplied in the pkts array of rte_mbuf structures.

The rte_crypto_enqueue_burst() function returns the number of packets it actually sent. A return value equal to nb_pkts means that all packets have been sent.

Each mbuf in the pkts array must have a valid rte_mbuf_offload structure attached which contains a valid crypto operation.

Parameters

dev_id	The identifier of the device.
qp_id	The index of the queue pair which packets are to be enqueued for processing. The value must be in the range [0, nb_queue_pairs - 1] previously supplied to rte_cryptodev_configure.
pkts	The address of an array of nb_pkts pointers to rte_mbuf structures which contain the output packets.
nb_pkts	The number of packets to transmit.

Returns: The number of packets actually enqueued on the crypto device. The return value can be less than the value of the nb_pkts parameter when the crypto devices queue is full or has been filled up. The number of packets is 0 if the device hasn't been started.

Examples:: l2fwd-crypto/main.c.

Definition at line 600 of file rte_cryptodev.h.

struct rte_cryptodev_session* rte_cryptodev_session_create	(	uint8_t	dev_id,
		struct rte_crypto_xform *	xform
	)

read

Initialise a session for symmetric cryptographic operations.

This function is used by the client to initialize immutable parameters of symmetric cryptographic operation. To perform the operation the rte_cryptodev_enqueue_burst function is used. Each mbuf should contain a reference to the session pointer returned from this function contained within it's crypto_op if a session-based operation is being provisioned. Memory to contain the session information is allocated from within mempool managed by the cryptodev.

The rte_cryptodev_session_free must be called to free allocated memory when the session is no longer required.

Parameters

dev_id	The device identifier.
xform	Crypto transform chain.

Returns: Pointer to the created session or NULL

Examples:: l2fwd-crypto/main.c.

struct rte_cryptodev_session* rte_cryptodev_session_free	(	uint8_t	dev_id,
		struct rte_cryptodev_session *	session
	)

read

Free the memory associated with a previously allocated session.

Parameters

dev_id	The device identifier.
session	Session pointer previously allocated by rte_cryptodev_session_create.

Returns: NULL on successful freeing of session. Session pointer on failure to free session.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation