[dpdk-dev] [PATCH] docs: cryptodev chapter for programmer's guide
Declan Doherty
declan.doherty at intel.com
Fri Apr 8 18:02:12 CEST 2016
Signed-off-by: Declan Doherty <declan.doherty at intel.com>
---
doc/guides/cryptodevs/index.rst | 3 +-
doc/guides/cryptodevs/overview.rst | 94 ++++
doc/guides/prog_guide/cryptodev_lib.rst | 569 +++++++++++++++++------
doc/guides/prog_guide/img/crypto_op.svg | 75 +++
doc/guides/prog_guide/img/crypto_xform_chain.svg | 145 ++++++
doc/guides/prog_guide/img/cryptodev_sym_sess.svg | 66 +++
6 files changed, 798 insertions(+), 154 deletions(-)
create mode 100644 doc/guides/cryptodevs/overview.rst
create mode 100644 doc/guides/prog_guide/img/crypto_op.svg
create mode 100644 doc/guides/prog_guide/img/crypto_xform_chain.svg
create mode 100644 doc/guides/prog_guide/img/cryptodev_sym_sess.svg
diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst
index 85193da..a3f11f3 100644
--- a/doc/guides/cryptodevs/index.rst
+++ b/doc/guides/cryptodevs/index.rst
@@ -35,8 +35,9 @@ Crypto Device Drivers
:maxdepth: 2
:numbered:
+ overview
aesni_mb
aesni_gcm
null
snow3g
- qat
+ qat
\ No newline at end of file
diff --git a/doc/guides/cryptodevs/overview.rst b/doc/guides/cryptodevs/overview.rst
new file mode 100644
index 0000000..9f9af43
--- /dev/null
+++ b/doc/guides/cryptodevs/overview.rst
@@ -0,0 +1,94 @@
+.. BSD LICENSE
+ Copyright(c) 2016 Intel Corporation. All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Intel Corporation nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Crypto Device Supported Functionality Matrices
+----------------------------------------------
+
+Supported Feature Flags
+
+.. csv-table::
+ :header: "Feature Flags", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g"
+ :stub-columns: 1
+
+ "RTE_CRYPTODEV_FF_SYMMETRIC_CRYPTO",x,x,,,
+ "RTE_CRYPTODEV_FF_ASYMMETRIC_CRYPTO",,,,,
+ "RTE_CRYPTODEV_FF_SYM_OPERATION_CHAINING",x,x,x,x,x
+ "RTE_CRYPTODEV_FF_CPU_SSE",,,x,x,x
+ "RTE_CRYPTODEV_FF_CPU_AVX",,,x,x,x
+ "RTE_CRYPTODEV_FF_CPU_AVX2",,,x,x,
+ "RTE_CRYPTODEV_FF_CPU_AESNI",,,x,x,
+ "RTE_CRYPTODEV_FF_HW_ACCELERATED",x,,,,
+
+Supported Cipher Algorithms
+
+.. csv-table::
+ :header: "Cipher Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g"
+ :stub-columns: 1
+
+ "NULL",,x,,,
+ "AES_CBC_128",x,,x,,
+ "AES_CBC_192",x,,x,,
+ "AES_CBC_256",x,,x,,
+ "AES_CTR_128",,,,,
+ "AES_CTR_192",,,,,
+ "AES_CTR_256",,,,,
+ "SNOW3G_UEA2",x,,,,x
+
+Supported Authentication Algorithms
+
+.. csv-table::
+ :header: "Cipher Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g"
+ :stub-columns: 1
+
+ "NONE",,x,,,
+ "MD5",,,,,
+ "MD5_HMAC",,,x,,
+ "SHA1",,,,,
+ "SHA1_HMAC",x,,x,,
+ "SHA224",,,,,
+ "SHA224_HMAC",,,x,,
+ "SHA256",,,,,
+ "SHA256_HMAC",x,,x,,
+ "SHA384",,,,,
+ "SHA384_HMAC",,,x,,
+ "SHA512",,,,,
+ "SHA512_HMAC",x,,x,,
+ "AES_XCBC",x,,x,,
+ "SNOW3G_UIA2",x,,,,x
+
+
+Supported AEAD Algorithms
+
+.. csv-table::
+ :header: "AEAD Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g"
+ :stub-columns: 1
+
+ "AES_GCM_128",x,,x,,
+ "AES_GCM_192",x,,,,
+ "AES_GCM_256",x,,,,
diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst
index 638a02c..6396d02 100644
--- a/doc/guides/prog_guide/cryptodev_lib.rst
+++ b/doc/guides/prog_guide/cryptodev_lib.rst
@@ -31,291 +31,554 @@
Cryptography Device Library
=============================
-The cryptodev library provides a crypto device framework for management and
-provisioning of hardware and virtual crypto poll mode drivers, defining generic
-APIs which support a number of different crypto operations.
-
-
-
-
-
-Requirements and Assumptions
-----------------------------
-
-
-
-
+The cryptodev library provides a Crypto device framework for management and
+provisioning of hardware and software Crypto poll mode drivers, defining generic
+APIs which support a number of different Crypto operations. The framework
+currently only supports cipher, authentication, chained cipher/authentication
+and AEAD symmetric Crypto operations.
Design Principles
-----------------
+The cryptodev library follows the same basic principles as those used in DPDKs
+Ethernet Device framework. The Crypto framework provides a generic Crypto device
+framework which supports both physical (hardware) and virtual (software) Crypto
+devices as well as a generic Crypto API which allows Crypto devices to be
+managed and configured and supports Crypto operations to be provisioned on
+Crypto poll mode driver.
+Device Management
+-----------------
+Device Creation
+~~~~~~~~~~~~~~~
+Physical Crypto devices are discovered during the PCI probe/enumeration of the
+EAL function which is executed at DPDK initialization, based on
+their PCI device identifier, each unique PCI BDF (bus/bridge, device,
+function). Specific physical Crypto devices, like other physical devices in DPDK
+can be white-listed or black-listed using the EAL command line options.
-Logical Cores, Memory and Queues Pair Relationships
----------------------------------------------------
-
-Crypto devices in the same vane as the :ref `Poll Mode Driver
-<Poll Mode Driver>` library supports NUMA for when a processor’s
-logical cores and interfaces utilize its local memory. Therefore, crypto
-operations, and in the case of symmetric crypto operations, session and the mbuf
-being operated on, should be allocated from memory pools created in the local
-memory. The buffers should, if possible, remain on the local processor to
-obtain the best performance results and buffer descriptors should be populated
- with mbufs allocated from a mempool allocated from local memory.
-
-The run-to-completion model also performs better, especially in the case of
-virtual crypto devices, if the crypto operation and session and data buffer is
-in local memory instead of a remote processors memory. This is also true for
-the pipe-line model provided all logical cores used are located on the same
-processor.
-
-Multiple logical cores should never share the same queue pairs for enqueuing or
-dequeuing operations on the same Crypto device since this would require global
-locks and hinder performance. It is however possible to use a different logical
-core to enqueue and dequeue operation on a queue pair.
-
-Generalities
-~~~~~~~~~~~~
-
-By default, all functions exported by a PMD are lock-free functions that are
-assumed not to be invoked in parallel on different logical cores to work on the
-same target object.
+Virtual devices can be created by two mechanisms, either using the EAL command
+line options or from within the application using an EAL API directly.
-For instance, a PMD dequeue burst function cannot be invoked in parallel on two
-logical cores to poll the same queue pair of the same port. Of course, this
-function can be invoked in parallel by different logical cores on different
-queue pairs.
+From the command line using the --vdev EAL option
-It is the responsibility of the upper-level application to enforce this rule.
+.. code-block:: console
-If needed, parallel accesses by multiple logical cores to shared queues can be
-explicitly protected by dedicated inline lock-aware functions built on top of
-their corresponding lock-free functions of the PMD API.
+ --vdev 'cryptodev_aesni_mb_pmd0,max_nb_queue_pairs=2,max_nb_sessions=1024,socket_id=0'
+Our using the rte_eal_vdev_init API within the application code.
+.. code-block:: c
-Device Identification and Configuration
----------------------------------------
+ rte_eal_vdev_init("cryptodev_aesni_mb_pmd",
+ "max_nb_queue_pairs=2,max_nb_sessions=1024,socket_id=0")
+All virtual Crypto devices support the following initialization parameters:
+* max_nb_queue_pairs - maximum number of queue pairs supported by the device.
+* max_nb_sessions - maximum number of sessions supported by the device
+* socket_id - socket on which to allocate the device resources on.
Device Identification
~~~~~~~~~~~~~~~~~~~~~
-Each crypto device, either virtual or physical is uniquely designated with a
-device identifier. Physical crypto devices are discovered during the PCI
-probe/enumeration function which is executed at DPDK initialization, based on
-their PCI device identifier, each unique PCI BDF (bus/bridge, device,
-function) for a matching identifier will be assigned a two device identifiers:
-
+Each device, whether virtual or physical is uniquely designated by two
+identifiers:
-- A device index used to designate the crypto device in all functions exported
- by the cryptodev API.
+- A unique device index used to designate the Crypto device in all functions
+ exported by the cryptodev API.
-- A device name used to designate the crypto device in console messages, for
+- A device name used to designate the Crypto device in console messages, for
administration or debugging purposes. For ease of use, the port name includes
the port index.
-Virtual devices can be created by to mechanisms, firstly by using the EAL
-command line, using the "--vdev" option or directly in an application by using
-the rte_eal_vdev_init() API. Again virtual crypto devices will be assigned two
-unique identifiers as list for physical crypto devices above.
-
-Device /Configuration
-~~~~~~~~~~~~~~~~~~~~~
-
-The configuration of each crypto device includes the following operations:
-
-- Allocate of hardware resources, if a physical device.
-- Reset the device into a well-known default state.
-- Initialize of statistics counters.
-
-
-Device Initialization
-~~~~~~~~~~~~~~~~~~~~~
-
-Crypto devices support du
-
+Device Configuration
+~~~~~~~~~~~~~~~~~~~~
+The configuration of each Crypto device includes the following operations:
+- Allocation of resources, including hardware resources if a physical device.
+- Resetting the device into a well-known default state.
+- Initialization of statistics counters.
+The rte_cryptodev_configure API is used to configure a Crypto device.
+.. code-block:: c
+ int rte_cryptodev_configure(uint8_t dev_id,
+ struct rte_cryptodev_config *config)
+The rte_cryptodev_config structure is used to pass the configuration parameters.
+In contains parameter for socket selection, number of queue pairs and the
+session mempool configuration.
+.. code-block:: c
+ /** Crypto device configuration structure */
+ struct rte_cryptodev_config {
+ int socket_id;
+ /**< Socket to allocate resources on */
+ uint16_t nb_queue_pairs;
+ /**< Number of queue pairs to configure on device */
+ struct {
+ uint32_t nb_objs;
+ uint32_t cache_size;
+ } session_mp;
+ /**< Session mempool configuration */
+ };
Configuration of Queue Pairs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Each Crypto devices queue pair is individually configured through the
+rte_cryptodev_queue_pair_setup API. Each queue pairs resources may be allocated
+on a specified socket.
+.. code-block:: c
+ 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)
+ /** Crypto device queue pair configuration structure. */
+ struct rte_cryptodev_qp_conf {
+ uint32_t nb_descriptors; /**< Number of descriptors per queue pair */
+ };
+Logical Cores, Memory and Queues Pair Relationships
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Crypto device Library as the Poll Mode Driver library support NUMA for when
+a processor’s logical cores and interfaces utilize its local memory. Therefore
+Crypto operations, and in the case of symmetric Crypto operations, the session
+and the mbuf being operated on, should be allocated from memory pools created
+in the local memory. The buffers should, if possible, remain on the local
+processor to obtain the best performance results and buffer descriptors should
+be populated with mbufs allocated from a mempool allocated from local memory.
+The run-to-completion model also performs better, especially in the case of
+virtual Crypto devices, if the Crypto operation and session and data buffer is
+in local memory instead of a remote processor's memory. This is also true for
+the pipe-line model provided all logical cores used are located on the same
+processor.
-Device Capabilities
--------------------
-
-Crypto poll drivers
-
-
-
-Registering Device Capabilities
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+Multiple logical cores should never share the same queue pair for enqueuing
+operations or dequeuing operations on the same Crypto device since this would
+require global locks and hinder performance. It is however possible to use a
+different logical core to dequeue an operation on a queue pair from the logical
+core which it was enqueued on. This means that a crypto burst enqueue/dequeue
+APIs are a logical place to transition from one logical core to another in a
+packet processing pipeline.
+
+Device Features and Capabilities
+---------------------------------
+
+Crypto devices define their functionality through two mechanisms, global device
+features and algorithm capabilities. Global devices features identify device
+wide level features which are applicable to the whole device such as
+the device having hardware acceleration or supporting symmetric Crypto
+operations,
+
+The capabilities mechanism defines the individual algorithms/functions which
+the device supports, such as a specific symmetric Crypto cipher or
+authentication operation.
+
+Device Features
+~~~~~~~~~~~~~~~
+
+Currently the following Crypto device features are defined:
+
+* Symmetric Crypto operations
+* Asymmetric Crypto operations
+* Chaining of symmetric Crypto operations
+* SSE accelerated SIMD vector operations
+* AVX accelerated SIMD vector operations
+* AVX2 accelerated SIMD vector operations
+* AESNI accelerated instructions
+* Hardware off-load processing
+
+
+Device Operation Capabilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Crypto capabilities which identify particular algorithm which the Crypto PMD
+supports are defined by the operation type, the operation transform, the
+transform identifier and then the particulars of the transform. For the full
+scope of the Crypto capability see the definition of the structure in the
+*DPDK API Reference*.
+.. code-block:: c
+
+ struct rte_cryptodev_capabilities;
+
+
+Each Crypto poll mode driver defines its own private array of capabilities
+for the operations it supports. Below is an example of the capabilities for a
+PMD which supports the authentication algorithm SHA1_HMAC and the cipher
+algorithm AES_CBC.
+
+.. code-block:: c
+
+ static const struct rte_cryptodev_capabilities pmd_capabilities[] = {
+ { /* SHA1 HMAC */
+ .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
+ .sym = {
+ .xform_type = RTE_CRYPTO_SYM_XFORM_AUTH,
+ .auth = {
+ .algo = RTE_CRYPTO_AUTH_SHA1_HMAC,
+ .block_size = 64,
+ .key_size = {
+ .min = 64,
+ .max = 64,
+ .increment = 0
+ },
+ .digest_size = {
+ .min = 12,
+ .max = 12,
+ .increment = 0
+ },
+ .aad_size = { 0 }
+ }
+ }
+ },
+ { /* AES CBC */
+ .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
+ .sym = {
+ .xform_type = RTE_CRYPTO_SYM_XFORM_CIPHER,
+ .cipher = {
+ .algo = RTE_CRYPTO_CIPHER_AES_CBC,
+ .block_size = 16,
+ .key_size = {
+ .min = 16,
+ .max = 32,
+ .increment = 8
+ },
+ .iv_size = {
+ .min = 16,
+ .max = 16,
+ .increment = 0
+ }
+ }
+ }
+ }
+ }
Capabilities Discovery
~~~~~~~~~~~~~~~~~~~~~~
+Discovering the features and capabilities of a Crypto device poll mode driver
+is achieved through the rte_cryptodev_info_get function.
+.. code-block:: c
+ void rte_cryptodev_info_get(uint8_t dev_id,
+ struct rte_cryptodev_info *dev_info);
-Operation Processing
---------------------
-
-
-
-
-Operation Representation
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-An crypto operation is represented by an rte_crypto_op structure, which is a
-generic metadata structure containing all necessary housekeeping information
-for the operation which the PMD is to process.
-
-This includes the operation type and the operation status, a pointer to the
-operation specific data, as well as the source mempool for the operation and a
-opaque pointer for user specific data.
-
-The rte_crypto_op data structure and the under lying operation specific data
-fields are represented, in a generic way, to allow provision of the requested
-operation by crypto accelerator device.
-
-Application software is responsible for specifying all the operation specific
-fields the rte_crypto_op structure which are used by the crypto PMD to process
-the requested operation. Processed operation return
-
-
-Operation Management and Allocation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This allows the user to query a specific Crypto PMD and get all the device
+features and capabilities. The rte_cryptodev_info structure contains all the
+relevant information for the device.
+.. code-block:: c
+ /** Crypto device information */
+ struct rte_cryptodev_info {
+ const char *driver_name; /**< Driver name. */
+ enum rte_cryptodev_type dev_type; /**< Device type */
+ struct rte_pci_device *pci_dev; /**< PCI information. */
+ uint64_t feature_flags; /**< Feature flags */
+ const struct rte_cryptodev_capabilities *capabilities;
+ /**< Array of devices supported capabilities */
+ unsigned max_nb_queue_pairs;
+ /**< Maximum number of queues pairs supported by device. */
-
-
-Enqueue / Dequeue Burst API
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
+ struct {
+ unsigned max_nb_sessions;
+ /**< Maximum number of sessions supported by device. */
+ } sym;
+ };
+Operation Processing
+--------------------
+Scheduling of Crypto operations on DPDK's application data path is
+performed using a burst oriented asynchronous API set. A queue pair on a Crypto
+device accepts a burst of Crypto operations using enqueue burst API. On physical
+Crypto devices the enqueue burst API will place the operations to be processed
+on the devices hardware input queue, for virtual devices the processing of the
+Crypto operations is usually completed during the enqueue call to the Crypto
+device. The dequeue burst API will retrieve any processed operations available
+from the queue pair on the Crypto device, from physical devices this is usually
+directly from the devices processed queue, and for virtual device's from a
+rte_ring where processed operations are place after being processed on the
+enqueue call.
+
+Enqueue / Dequeue Burst APIs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The burst enqueue API uses a Crypto device identifier and a queue pair
+identifier to specify the Crypto device queue pair to schedule the processing
+on. The *nb_ops* parameter is the number of operations to process which are
+supplied in the *ops* array of *rte_crypto_op* structures. The enqueue function
+returns the number of operations it actually enqueued for processing, a return
+value equal to *nb_ops* means that all packets have been enqueued.
-Symmetric Cryptography Support
-------------------------------
+.. code-block:: c
-Symmetric crypto transforms currently support are cipher transforms and authentication.
+ uint16_t rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id,
+ struct rte_crypto_op **ops, uint16_t nb_ops)
+The dequeue API uses the same format as the enqueue API of processed but
+the *nb_ops* and *ops* parameters are now used to specify the max processed
+operations the user wishes to retrieve and the location in which to store them.
+The API call returns the actual number of processed operations returned, this
+can never be larger than *nb_ops*.
+.. code-block:: c
+ uint16_t rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id,
+ struct rte_crypto_op **ops, uint16_t nb_ops)
+Operation Representation
+~~~~~~~~~~~~~~~~~~~~~~~~
+An Crypto operation is represented by an rte_crypto_op structure, which is a
+generic metadata container for all necessary information required for the
+Crypto operation to be processed on a particular Crypto device poll mode driver.
+.. figure:: img/crypto_op.*
-Transforms
-~~~~~~~~~~
+The operation structure includes the operation type and the operation status,
+a reference to the operation specific data, which can vary in size and content
+depending on the operation being provisioned. It also contains the source
+mempool for the operation, if it allocate from a mempool. Finally an
+opaque pointer for user specific data is provided.
+If Crypto operations are allocated from a Crypto operation mempool, see next
+section, there is also the ability to allocate private memory with the
+operation for applications purposes.
+Application software is responsible for specifying all the operation specific
+fields in the rte_crypto_op structure which are then used by the Crypto PMD to
+process the requested operation.
+Operation Management and Allocation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The cryptodev library provides an API set for managing Crypto operations which
+utilize the Mempool Library to allocate operation buffers. Therefore, it ensures
+that the crytpo operation is interleaved optimally across the channels and
+ranks for optimal processing. A rte_crypto_op contains a field indicating the
+pool that it originated from. When calling rte_crypto_op_free(op), the
+operation returns to its original pool.
+.. code-block:: c
+ extern struct rte_mempool *
+ rte_crypto_op_pool_create(const char *name, enum rte_crypto_op_type type,
+ unsigned nb_elts, unsigned cache_size, uint16_t priv_size,
+ int socket_id);
+During pool creation rte_crypto_op_init() is called as a constructor to
+initialize each Crypto operation which subsequently calls
+__rte_crypto_op_reset() to configure any operation type specific fields based
+on the type parameter.
+rte_crypto_op_alloc() and rte_crypto_op_bulk_alloc() are used to allocate Crypto
+operations of a specific type from a given Crypto operation mempool.
+__rte_crypto_op_reset() is called on each operation before being returned to
+allocate to a user so the operation is always in a good known state before use
+by the application.
+.. code-block:: c
+ struct rte_crypto_op *rte_crypto_op_alloc(struct rte_mempool *mempool,
+ enum rte_crypto_op_type type)
+ unsigned rte_crypto_op_bulk_alloc(struct rte_mempool *mempool,
+ enum rte_crypto_op_type type,
+ struct rte_crypto_op **ops, uint16_t nb_ops)
-Transform Chaining
-~~~~~~~~~~~~~~~~~~
+rte_crypto_op_free() is called by the application to return an operation to it's
+allocating pool.
-Transform chaining allows multiple transforms to be processed in one
-cryptographic operation. The two most common chaining combinations are
-authentication verify then cipher decryption and cipher encryption and
-authentication generate. The API does not place a limit on the number of
-transforms that can be chained together but this will be limited by the
-underlying Crypto device which is processing the operation.
+.. code-block:: c
+ void rte_crypto_op_free(struct rte_crypto_op *op)
+Symmetric Cryptography Support
+------------------------------
+The cryptodev library currently provides support for the following symmetric
+Crypto operations; cipher, authentication, including chaining of these
+operations, as well as also supporting AEAD operations.
+Session and Session Management
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Session are used in symmetric cryptographic processing to store the immutable
+data defined in a cryptographic transform which is used in the operation
+processing of a packet flow. Sessions are used to manage information such as
+expand cipher keys and HMAC IPADs and OPADs, which need to be calculated for a
+particular Crypto operation, but are immutable on a packet to packet basis for
+a flow. Crypto sessions cache this immutable data in a optimal way for the
+underlying PMD and this allows further acceleration of the offload of
+Crypto workloads.
+.. figure:: img/cryptodev_sym_sess.*
+The Crypto device framework provides a set of session pool management APIs for
+the creation and freeing of the sessions, utilizing the Mempool Library.
+The framework also provides hooks so the PMDs can pass the amount of memory
+required for that PMDs private session parameters, as well as initialization
+functions for the configuration of the session parameters and freeing function
+so the PMD can managed the memory on destruction of a session.
+**Note**: Sessions created on a particular device can only be used on Crypto
+devices of the same type, and if you try to use a session on a device different
+to that on which it was created then the Crypto operation will fail.
-Session and Session Management
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+rte_cryptodev_sym_session_create() is used to create a symmetric session on
+Crypto device. A symmetric transform chain is used to specify the particular
+operation and it's parameters. See the section below for details on transforms.
-Session are used in symmetric cryptographic processing to store the immutable
-data defined in a cryptographic transform which is used in the operation
-processing of a packet flow. In the DPDK cryptodev implementation the session
-structure fulfills two main purposes,
+.. code-block:: c
+ struct rte_cryptodev_sym_session * rte_cryptodev_sym_session_create(
+ uint8_t dev_id, struct rte_crypto_sym_xform *xform);
+**Note**: For AEAD operations the algorithm selected for authentication and
+ciphering must aligned, eg AES_GCM.
+Transforms and Transform Chaining
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Symmetric Crypto transforms (rte_crypto_sym_xform) are the mechanism used to
+specify the details of the Crypto operation. For chaining of symmetric
+operations such as cipher encrypt and authentication generate, the next pointer
+allows transform to be chained together. Crypto devices which support chaining
+must publish the chaining of symmetric Crypto operations feature flag.
+Currently there are two transforms types cipher and authentication, to specify
+an AEAD operation it is required to chain a cipher and an authentication
+transform together. Also it is important to note that the order in which the
+transforms are passed indicates the order of the chaining.
+.. code-block:: c
+ struct rte_crypto_sym_xform {
+ struct rte_crypto_sym_xform *next;
+ /**< next xform in chain */
+ enum rte_crypto_sym_xform_type type
+ ; /**< xform type */
+ union {
+ struct rte_crypto_auth_xform auth;
+ /**< Authentication / hash xform */
+ struct rte_crypto_cipher_xform cipher;
+ /**< Cipher xform */
+ };
+ };
+The API does not place a limit on the number of transforms that can be chained
+together but this will be limited by the underlying Crypto device poll mode
+driver which is processing the operation.
+.. figure:: img/crypto_xform_chain.*
Symmetric Operations
~~~~~~~~~~~~~~~~~~~~
-Symmetric cryptographic functions are provided by c
-
-
-
+The symmetric Crypto operation structure contains all the mutable data relating
+to performing symmetric cryptographic processing on a referenced mbuf data
+buffer. It is used for either cipher, authentication, AEAD and chained
+operations.
+
+As a minimum the symmetric operation must have a source data buffer (m_src),
+the session type (session-based/less), a valid session (or transform chain if in
+session-less mode) and the minimum authentication/ cipher parameters required
+depending on the type of operation specified in the session or the transform
+chain.
+
+.. code-block:: c
+
+ struct rte_crypto_sym_op {
+ struct rte_mbuf *m_src; /**< source mbuf */
+ struct rte_mbuf *m_dst; /**< destination mbuf */
+
+ enum rte_crypto_sym_op_sess_type type;
+
+ union {
+ struct rte_cryptodev_sym_session *session;
+ /**< Handle for the initialised session context */
+ struct rte_crypto_sym_xform *xform;
+ /**< Session-less API Crypto operation parameters */
+ };
+
+ struct {
+ struct {
+ uint32_t offset;
+ uint32_t length;
+ } data; /**< Data offsets and length for ciphering */
+
+ struct {
+ uint8_t *data;
+ phys_addr_t phys_addr;
+ uint16_t length;
+ } iv; /**< Initialisation vector parameters */
+ } cipher;
+
+ struct {
+ struct {
+ uint32_t offset;
+ uint32_t length;
+ } data; /**< Data offsets and length for authentication */
+
+ struct {
+ uint8_t *data;
+ phys_addr_t phys_addr;
+ uint16_t length;
+ } digest; /**< Digest parameters */
+
+ struct {
+ uint8_t *data;
+ phys_addr_t phys_addr;
+ uint16_t length;
+ } aad;
+ /**< Additional authentication parameters */
+ } auth;
+ }
Asymmetric Cryptography
-----------------------
-Asymmetric functionality is currently not supported by the cryptodev API but is
-expected to be added in the near future.
+Asymmetric functionality is currently not supported by the cryptodev API.
Crypto Device API
~~~~~~~~~~~~~~~~~~~
-The Ethernet device API exported by the Ethernet PMDs is described in the
-*DPDK API Reference*.
+The cryptodev Library API is described in the *DPDK API Reference* document.
diff --git a/doc/guides/prog_guide/img/crypto_op.svg b/doc/guides/prog_guide/img/crypto_op.svg
new file mode 100644
index 0000000..96e3aff
--- /dev/null
+++ b/doc/guides/prog_guide/img/crypto_op.svg
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by Microsoft Visio, SVG Export crypto_op.svg Page-1 -->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ev="http://www.w3.org/2001/xml-events"
+ width="2.17241in" height="2.8102in" viewBox="0 0 156.413 202.335" xml:space="preserve" color-interpolation-filters="sRGB"
+ class="st10">
+ <style type="text/css">
+ <![CDATA[
+ .st1 {fill:url(#grad0-4);stroke:#386288;stroke-width:0.75}
+ .st2 {fill:#386288;font-family:Calibri;font-size:0.833336em}
+ .st3 {fill:#ffffff;stroke:#41719c;stroke-width:0.75}
+ .st4 {fill:#41719c;font-family:Calibri;font-size:0.833336em}
+ .st5 {font-size:0.799995em}
+ .st6 {font-size:0.799995em;font-weight:bold}
+ .st7 {visibility:visible}
+ .st8 {fill:#bdd0e9;fill-opacity:0.25;filter:url(#filter_2);stroke:#bdd0e9;stroke-opacity:0.25}
+ .st9 {fill:#a6b6cd;stroke:#41719c;stroke-width:0.75}
+ .st10 {fill:none;fill-rule:evenodd;font-size:12px;overflow:visible;stroke-linecap:square;stroke-miterlimit:3}
+ ]]>
+ </style>
+
+ <defs id="Patterns_And_Gradients">
+ <linearGradient id="grad0-4" x1="0" y1="0" x2="1" y2="0" gradientTransform="rotate(60 0.5 0.5)">
+ <stop offset="0" stop-color="#e8ebef" stop-opacity="1"/>
+ <stop offset="0.24" stop-color="#f4f5f7" stop-opacity="1"/>
+ <stop offset="0.54" stop-color="#feffff" stop-opacity="1"/>
+ </linearGradient>
+ </defs>
+ <defs id="Filters">
+ <filter id="filter_2">
+ <feGaussianBlur stdDeviation="2"/>
+ </filter>
+ </defs>
+ <g>
+ <title>Page-1</title>
+ <g id="shape1-1" transform="translate(0.749889,-0.75)">
+ <title>Rounded Rectangle.24</title>
+ <desc>Crypto Operation</desc>
+ <path d="M6.78 202.33 L148.14 202.33 A6.77735 6.77735 -180 0 0 154.91 195.56 L154.91 8.28 A6.77735 6.77735 -180 0 0 148.14
+ 1.5 L6.78 1.5 A6.77735 6.77735 -180 0 0 -0 8.28 L0 195.56 A6.77735 6.77735 -180 0 0 6.78 202.33 Z"
+ class="st1"/>
+ <text x="42.07" y="14.5" class="st2">Crypto Operation</text> </g>
+ <g id="shape2-6" transform="translate(10.6711,-66.2303)">
+ <title>Rounded Rectangle.7</title>
+ <desc>Operation Specific Data (struct rte_crypto_sym_op)</desc>
+ <path d="M5.91 202.33 L129.16 202.33 A5.90925 5.90925 -180 0 0 135.07 196.43 L135.07 160.06 A5.90925 5.90925 -180 0 0
+ 129.16 154.15 L5.91 154.15 A5.90925 5.90925 -180 0 0 -0 160.06 L0 196.43 A5.90925 5.90925 -180 0 0 5.91
+ 202.33 Z" class="st3"/>
+ <text x="19.62" y="175.24" class="st4">Operation Specific Data <tspan x="22.66" dy="1.5em" class="st5">(</tspan><tspan
+ class="st6">struct </tspan><tspan class="st5">rte</tspan><tspan class="st5">_</tspan><tspan class="st5">crypto</tspan><tspan
+ class="st5">_</tspan><tspan class="st5">sym</tspan><tspan class="st5">_</tspan><tspan class="st5">op</tspan><tspan
+ class="st5">)</tspan></text> </g>
+ <g id="shape3-19" transform="translate(10.6711,-9.5374)">
+ <title>Rounded Rectangle.8</title>
+ <desc>private data</desc>
+ <g id="shadow3-20" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st7">
+ <path d="M5.91 202.33 L129.16 202.33 A5.90925 5.90925 -180 0 0 135.07 196.43 L135.07 160.06 A5.90925 5.90925 -180
+ 0 0 129.16 154.15 L5.91 154.15 A5.90925 5.90925 -180 0 0 -0 160.06 L0 196.43 A5.90925 5.90925 -180 0
+ 0 5.91 202.33 Z" class="st8"/>
+ </g>
+ <path d="M5.91 202.33 L129.16 202.33 A5.90925 5.90925 -180 0 0 135.07 196.43 L135.07 160.06 A5.90925 5.90925 -180 0 0
+ 129.16 154.15 L5.91 154.15 A5.90925 5.90925 -180 0 0 -0 160.06 L0 196.43 A5.90925 5.90925 -180 0 0 5.91
+ 202.33 Z" class="st9"/>
+ <text x="42.98" y="181.24" class="st4">private data</text> </g>
+ <g id="shape4-25" transform="translate(10.6711,-122.923)">
+ <title>Rounded Rectangle.9</title>
+ <desc>General Operation Data (struct rte_crypto_op)</desc>
+ <path d="M5.91 202.33 L129.16 202.33 A5.90925 5.90925 -180 0 0 135.07 196.43 L135.07 160.06 A5.90925 5.90925 -180 0 0
+ 129.16 154.15 L5.91 154.15 A5.90925 5.90925 -180 0 0 -0 160.06 L0 196.43 A5.90925 5.90925 -180 0 0 5.91
+ 202.33 Z" class="st3"/>
+ <text x="19.04" y="175.24" class="st4">General Operation Data <tspan x="31.23" dy="1.5em" class="st5">(</tspan><tspan
+ class="st6">struct </tspan><tspan class="st5">rte</tspan><tspan class="st5">_</tspan><tspan class="st5">crypto</tspan><tspan
+ class="st5">_</tspan><tspan class="st5">op</tspan><tspan class="st5">)</tspan></text> </g>
+ </g>
+</svg>
diff --git a/doc/guides/prog_guide/img/crypto_xform_chain.svg b/doc/guides/prog_guide/img/crypto_xform_chain.svg
new file mode 100644
index 0000000..4670a07
--- /dev/null
+++ b/doc/guides/prog_guide/img/crypto_xform_chain.svg
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by Microsoft Visio, SVG Export crypto_xform_chain.svg Page-1 -->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ev="http://www.w3.org/2001/xml-events"
+ width="4.9352in" height="4.2584in" viewBox="0 0 355.334 306.605" xml:space="preserve" color-interpolation-filters="sRGB"
+ class="st12">
+ <style type="text/css">
+ <![CDATA[
+ .st1 {fill:url(#grad0-4);stroke:#386288;stroke-width:0.75}
+ .st2 {fill:#386288;font-family:Calibri;font-size:0.833336em}
+ .st3 {font-size:0.799995em}
+ .st4 {font-size:0.799995em;font-weight:bold}
+ .st5 {visibility:visible}
+ .st6 {fill:#bdd0e9;fill-opacity:0.25;filter:url(#filter_2);stroke:#bdd0e9;stroke-opacity:0.25}
+ .st7 {fill:#a6b6cd;stroke:#41719c;stroke-width:0.75}
+ .st8 {fill:#41719c;font-family:Calibri;font-size:0.833336em}
+ .st9 {fill:#ffffff;stroke:#41719c;stroke-width:0.75}
+ .st10 {marker-end:url(#mrkr4-135);stroke:#41719c;stroke-linecap:round;stroke-linejoin:round;stroke-width:1}
+ .st11 {fill:#41719c;fill-opacity:1;stroke:#41719c;stroke-opacity:1;stroke-width:0.28409090909091}
+ .st12 {fill:none;fill-rule:evenodd;font-size:12px;overflow:visible;stroke-linecap:square;stroke-miterlimit:3}
+ ]]>
+ </style>
+
+ <defs id="Patterns_And_Gradients">
+ <linearGradient id="grad0-4" x1="0" y1="0" x2="1" y2="0" gradientTransform="rotate(60 0.5 0.5)">
+ <stop offset="0" stop-color="#e8ebef" stop-opacity="1"/>
+ <stop offset="0.24" stop-color="#f4f5f7" stop-opacity="1"/>
+ <stop offset="0.54" stop-color="#feffff" stop-opacity="1"/>
+ </linearGradient>
+ </defs>
+ <defs id="Markers">
+ <g id="lend4">
+ <path d="M 2 1 L 0 0 L 2 -1 L 2 1 " style="stroke:none"/>
+ </g>
+ <marker id="mrkr4-135" class="st11" refX="-7.04" orient="auto" markerUnits="strokeWidth" overflow="visible">
+ <use xlink:href="#lend4" transform="scale(-3.52,-3.52) "/>
+ </marker>
+ </defs>
+ <defs id="Filters">
+ <filter id="filter_2">
+ <feGaussianBlur stdDeviation="2"/>
+ </filter>
+ </defs>
+ <g>
+ <title>Page-1</title>
+ <g id="shape9-1" transform="translate(0.749889,-75.0177)">
+ <title>Rounded Rectangle.24</title>
+ <desc>Symmetric Transform (struct rte_crypto_sym_xform)</desc>
+ <path d="M6.78 306.6 L148.14 306.6 A6.77735 6.77735 -180 0 0 154.91 299.83 L154.91 82.55 A6.77735 6.77735 -180 0 0 148.14
+ 75.77 L6.78 75.77 A6.77735 6.77735 -180 0 0 -0 82.55 L0 299.83 A6.77735 6.77735 -180 0 0 6.78 306.6 Z"
+ class="st1"/>
+ <text x="33.55" y="88.77" class="st2">Symmetric Transform <tspan x="27.14" dy="1.5em" class="st3">(</tspan><tspan
+ class="st4">struct </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan
+ class="st3">_</tspan><tspan class="st3">sym</tspan><tspan class="st3">_</tspan><tspan class="st3">xform</tspan><tspan
+ class="st3">)</tspan></text> </g>
+ <g id="shape10-16" transform="translate(10.6711,-83.0965)">
+ <title>Rounded Rectangle.25</title>
+ <desc>Transform Parameters struct rte_crypto_auth_xform struct rte_...</desc>
+ <g id="shadow10-17" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st5">
+ <path d="M5.91 306.6 L129.16 306.6 A5.90925 5.90925 -180 0 0 135.07 300.7 L135.07 207.92 A5.90925 5.90925 -180 0
+ 0 129.16 202.01 L5.91 202.01 A5.90925 5.90925 -180 0 0 -0 207.92 L0 300.7 A5.90925 5.90925 -180 0 0
+ 5.91 306.6 Z" class="st6"/>
+ </g>
+ <path d="M5.91 306.6 L129.16 306.6 A5.90925 5.90925 -180 0 0 135.07 300.7 L135.07 207.92 A5.90925 5.90925 -180 0 0 129.16
+ 202.01 L5.91 202.01 A5.90925 5.90925 -180 0 0 -0 207.92 L0 300.7 A5.90925 5.90925 -180 0 0 5.91 306.6 Z"
+ class="st7"/>
+ <text x="21.89" y="241.71" class="st8">Transform Parameters <tspan x="18.76" dy="2.475em" class="st4">struct </tspan><tspan
+ class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan class="st3">_</tspan><tspan
+ class="st3">auth</tspan><tspan class="st3">_</tspan><tspan class="st3">xform </tspan><tspan x="16.02"
+ dy="1.425em" class="st4">struct </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan
+ class="st3">crypto</tspan><tspan class="st3">_</tspan><tspan class="st3">cipher</tspan><tspan class="st3">_</tspan><tspan
+ class="st3">xform</tspan></text> </g>
+ <g id="shape11-38" transform="translate(10.6711,-238.133)">
+ <title>Rounded Rectangle.26</title>
+ <desc>next transform (struct rte_crypto_sym_xform *)</desc>
+ <path d="M5.91 306.6 L129.16 306.6 A5.90925 5.90925 -180 0 0 135.07 300.7 L135.07 283.84 A5.90925 5.90925 -180 0 0 129.16
+ 277.93 L5.91 277.93 A5.90925 5.90925 -180 0 0 0 283.84 L0 300.7 A5.90925 5.90925 -180 0 0 5.91 306.6 Z"
+ class="st9"/>
+ <text x="37.15" y="289.27" class="st8">next transform <tspan x="14.33" dy="1.5em" class="st3">(</tspan><tspan
+ class="st4">struct </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan
+ class="st3">_</tspan><tspan class="st3">sym</tspan><tspan class="st3">_</tspan><tspan class="st3">xform </tspan><tspan
+ class="st3">*)</tspan></text> </g>
+ <g id="shape12-51" transform="translate(10.6711,-199.175)">
+ <title>Rounded Rectangle.29</title>
+ <desc>transform type (enum rte_crypto_sym_xform_type)</desc>
+ <path d="M5.91 306.6 L129.16 306.6 A5.90925 5.90925 -180 0 0 135.07 300.7 L135.07 283.84 A5.90925 5.90925 -180 0 0 129.16
+ 277.93 L5.91 277.93 A5.90925 5.90925 -180 0 0 0 283.84 L0 300.7 A5.90925 5.90925 -180 0 0 5.91 306.6 Z"
+ class="st9"/>
+ <text x="37.06" y="289.27" class="st8">transform type <tspan x="8.04" dy="1.5em" class="st3">(</tspan><tspan
+ class="st4">enum </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan
+ class="st3">_</tspan><tspan class="st3">sym</tspan><tspan class="st3">_</tspan><tspan class="st3">xform</tspan><tspan
+ class="st3">_</tspan><tspan class="st3">type</tspan><tspan class="st3">)</tspan></text> </g>
+ <g id="shape13-66" transform="translate(199.671,-0.75)">
+ <title>Rounded Rectangle.30</title>
+ <desc>Symmetric Transform (struct rte_crypto_sym_xform)</desc>
+ <path d="M6.78 306.6 L148.14 306.6 A6.77735 6.77735 -180 0 0 154.91 299.83 L154.91 82.55 A6.77735 6.77735 -180 0 0 148.14
+ 75.77 L6.78 75.77 A6.77735 6.77735 -180 0 0 -0 82.55 L0 299.83 A6.77735 6.77735 -180 0 0 6.78 306.6 Z"
+ class="st1"/>
+ <text x="33.55" y="88.77" class="st2">Symmetric Transform <tspan x="27.14" dy="1.5em" class="st3">(</tspan><tspan
+ class="st4">struct </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan
+ class="st3">_</tspan><tspan class="st3">sym</tspan><tspan class="st3">_</tspan><tspan class="st3">xform</tspan><tspan
+ class="st3">)</tspan></text> </g>
+ <g id="shape14-80" transform="translate(209.592,-8.82874)">
+ <title>Rounded Rectangle.31</title>
+ <desc>Transform Parameters struct rte_crypto_auth_xform struct rte_...</desc>
+ <g id="shadow14-81" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st5">
+ <path d="M5.91 306.6 L129.16 306.6 A5.90925 5.90925 -180 0 0 135.07 300.7 L135.07 207.92 A5.90925 5.90925 -180 0
+ 0 129.16 202.01 L5.91 202.01 A5.90925 5.90925 -180 0 0 -0 207.92 L0 300.7 A5.90925 5.90925 -180 0 0
+ 5.91 306.6 Z" class="st6"/>
+ </g>
+ <path d="M5.91 306.6 L129.16 306.6 A5.90925 5.90925 -180 0 0 135.07 300.7 L135.07 207.92 A5.90925 5.90925 -180 0 0 129.16
+ 202.01 L5.91 202.01 A5.90925 5.90925 -180 0 0 -0 207.92 L0 300.7 A5.90925 5.90925 -180 0 0 5.91 306.6 Z"
+ class="st7"/>
+ <text x="21.89" y="241.71" class="st8">Transform Parameters <tspan x="18.76" dy="2.475em" class="st4">struct </tspan><tspan
+ class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan class="st3">_</tspan><tspan
+ class="st3">auth</tspan><tspan class="st3">_</tspan><tspan class="st3">xform </tspan><tspan x="16.02"
+ dy="1.425em" class="st4">struct </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan
+ class="st3">crypto</tspan><tspan class="st3">_</tspan><tspan class="st3">cipher</tspan><tspan class="st3">_</tspan><tspan
+ class="st3">xform</tspan></text> </g>
+ <g id="shape15-102" transform="translate(209.592,-163.865)">
+ <title>Rounded Rectangle.32</title>
+ <desc>next transform (struct rte_crypto_sym_xform *)</desc>
+ <path d="M5.91 306.6 L129.16 306.6 A5.90925 5.90925 -180 0 0 135.07 300.7 L135.07 283.84 A5.90925 5.90925 -180 0 0 129.16
+ 277.93 L5.91 277.93 A5.90925 5.90925 -180 0 0 0 283.84 L0 300.7 A5.90925 5.90925 -180 0 0 5.91 306.6 Z"
+ class="st9"/>
+ <text x="37.15" y="289.27" class="st8">next transform <tspan x="14.33" dy="1.5em" class="st3">(</tspan><tspan
+ class="st4">struct </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan
+ class="st3">_</tspan><tspan class="st3">sym</tspan><tspan class="st3">_</tspan><tspan class="st3">xform </tspan><tspan
+ class="st3">*)</tspan></text> </g>
+ <g id="shape16-115" transform="translate(209.592,-124.907)">
+ <title>Rounded Rectangle.33</title>
+ <desc>transform type (enum rte_crypto_sym_xform_type)</desc>
+ <path d="M5.91 306.6 L129.16 306.6 A5.90925 5.90925 -180 0 0 135.07 300.7 L135.07 283.84 A5.90925 5.90925 -180 0 0 129.16
+ 277.93 L5.91 277.93 A5.90925 5.90925 -180 0 0 0 283.84 L0 300.7 A5.90925 5.90925 -180 0 0 5.91 306.6 Z"
+ class="st9"/>
+ <text x="37.06" y="289.27" class="st8">transform type <tspan x="8.04" dy="1.5em" class="st3">(</tspan><tspan
+ class="st4">enum </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan
+ class="st3">_</tspan><tspan class="st3">sym</tspan><tspan class="st3">_</tspan><tspan class="st3">xform</tspan><tspan
+ class="st3">_</tspan><tspan class="st3">type</tspan><tspan class="st3">)</tspan></text> </g>
+ <g id="shape17-130" transform="translate(145.742,-252.47)">
+ <title>Dynamic connector</title>
+ <path d="M0 306.6 L131.39 306.6 L131.39 320.45" class="st10"/>
+ </g>
+ </g>
+</svg>
diff --git a/doc/guides/prog_guide/img/cryptodev_sym_sess.svg b/doc/guides/prog_guide/img/cryptodev_sym_sess.svg
new file mode 100644
index 0000000..e5f41ec
--- /dev/null
+++ b/doc/guides/prog_guide/img/cryptodev_sym_sess.svg
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by Microsoft Visio, SVG Export cryptodev_sym_sess.svg Page-1 -->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ev="http://www.w3.org/2001/xml-events"
+ width="2.17241in" height="2.8102in" viewBox="0 0 156.413 202.335" xml:space="preserve" color-interpolation-filters="sRGB"
+ class="st10">
+ <style type="text/css">
+ <![CDATA[
+ .st1 {fill:url(#grad0-4);stroke:#386288;stroke-width:0.75}
+ .st2 {fill:#386288;font-family:Calibri;font-size:0.833336em}
+ .st3 {visibility:visible}
+ .st4 {fill:#bdd0e9;fill-opacity:0.25;filter:url(#filter_2);stroke:#bdd0e9;stroke-opacity:0.25}
+ .st5 {fill:#a6b6cd;stroke:#41719c;stroke-width:0.75}
+ .st6 {fill:#41719c;font-family:Calibri;font-size:0.833336em}
+ .st7 {fill:#ffffff;stroke:#41719c;stroke-width:0.75}
+ .st8 {font-size:0.799995em}
+ .st9 {font-size:0.799995em;font-weight:bold}
+ .st10 {fill:none;fill-rule:evenodd;font-size:12px;overflow:visible;stroke-linecap:square;stroke-miterlimit:3}
+ ]]>
+ </style>
+
+ <defs id="Patterns_And_Gradients">
+ <linearGradient id="grad0-4" x1="0" y1="0" x2="1" y2="0" gradientTransform="rotate(60 0.5 0.5)">
+ <stop offset="0" stop-color="#e8ebef" stop-opacity="1"/>
+ <stop offset="0.24" stop-color="#f4f5f7" stop-opacity="1"/>
+ <stop offset="0.54" stop-color="#feffff" stop-opacity="1"/>
+ </linearGradient>
+ </defs>
+ <defs id="Filters">
+ <filter id="filter_2">
+ <feGaussianBlur stdDeviation="2"/>
+ </filter>
+ </defs>
+ <g>
+ <title>Page-1</title>
+ <g id="shape18-1" transform="translate(0.749889,-0.75)">
+ <title>Rounded Rectangle.12</title>
+ <desc>Crypto Symmetric Session</desc>
+ <path d="M6.78 202.33 L148.14 202.33 A6.77735 6.77735 -180 0 0 154.91 195.56 L154.91 8.28 A6.77735 6.77735 -180 0 0 148.14
+ 1.5 L6.78 1.5 A6.77735 6.77735 -180 0 0 -0 8.28 L0 195.56 A6.77735 6.77735 -180 0 0 6.78 202.33 Z"
+ class="st1"/>
+ <text x="24.76" y="14.5" class="st2">Crypto Symmetric Session</text> </g>
+ <g id="shape19-6" transform="translate(10.6711,-9.82087)">
+ <title>Rounded Rectangle.13</title>
+ <desc>Private Session Data</desc>
+ <g id="shadow19-7" transform="matrix(1,0,0,1,0.345598,1.97279)" class="st3">
+ <path d="M5.91 202.33 L129.16 202.33 A5.90925 5.90925 -180 0 0 135.07 196.43 L135.07 103.65 A5.90925 5.90925 -180
+ 0 0 129.16 97.74 L5.91 97.74 A5.90925 5.90925 -180 0 0 -0 103.65 L0 196.43 A5.90925 5.90925 -180 0 0
+ 5.91 202.33 Z" class="st4"/>
+ </g>
+ <path d="M5.91 202.33 L129.16 202.33 A5.90925 5.90925 -180 0 0 135.07 196.43 L135.07 103.65 A5.90925 5.90925 -180 0 0
+ 129.16 97.74 L5.91 97.74 A5.90925 5.90925 -180 0 0 -0 103.65 L0 196.43 A5.90925 5.90925 -180 0 0 5.91 202.33
+ Z" class="st5"/>
+ <text x="26.34" y="153.04" class="st6">Private Session Data</text> </g>
+ <g id="shape20-12" transform="translate(10.6711,-122.923)">
+ <title>Rounded Rectangle.15</title>
+ <desc>General Session Data (struct rte_cryptodev_sym_session)</desc>
+ <path d="M5.91 202.33 L129.16 202.33 A5.90925 5.90925 -180 0 0 135.07 196.43 L135.07 160.06 A5.90925 5.90925 -180 0 0
+ 129.16 154.15 L5.91 154.15 A5.90925 5.90925 -180 0 0 -0 160.06 L0 196.43 A5.90925 5.90925 -180 0 0 5.91
+ 202.33 Z" class="st7"/>
+ <text x="24.58" y="175.24" class="st6">General Session Data <tspan x="9.16" dy="1.5em" class="st8">(</tspan><tspan
+ class="st9">struct </tspan><tspan class="st8">rte</tspan><tspan class="st8">_</tspan><tspan class="st8">cryptodev</tspan><tspan
+ class="st8">_</tspan><tspan class="st8">sym</tspan><tspan class="st8">_</tspan><tspan class="st8">session</tspan><tspan
+ class="st8">)</tspan></text> </g>
+ </g>
+</svg>
--
2.5.5
More information about the dev
mailing list