doc: add cryptodev chapter in prog guide
authorDeclan Doherty <declan.doherty@intel.com>
Fri, 8 Apr 2016 16:17:27 +0000 (17:17 +0100)
committerThomas Monjalon <thomas.monjalon@6wind.com>
Fri, 8 Apr 2016 22:40:33 +0000 (00:40 +0200)
Add a programmer's guide section for cryptodev library.

Signed-off-by: Declan Doherty <declan.doherty@intel.com>
Acked-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
doc/guides/prog_guide/cryptodev_lib.rst [new file with mode: 0644]
doc/guides/prog_guide/img/crypto_op.svg [new file with mode: 0644]
doc/guides/prog_guide/img/crypto_xform_chain.svg [new file with mode: 0644]
doc/guides/prog_guide/img/cryptodev_sym_sess.svg [new file with mode: 0644]
doc/guides/prog_guide/index.rst

diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst
new file mode 100644 (file)
index 0000000..ca3f551
--- /dev/null
@@ -0,0 +1,578 @@
+..  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.
+
+
+Cryptography Device Library
+===========================
+
+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.
+
+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.
+
+From the command line using the --vdev EAL option
+
+.. code-block:: console
+
+   --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
+
+   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 device, whether virtual or physical is uniquely designated by two
+identifiers:
+
+- 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
+  administration or debugging purposes. For ease of use, the port name includes
+  the port index.
+
+
+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
+
+    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)
+
+    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.
+
+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);
+
+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
+
+    struct rte_cryptodev_info {
+        const char *driver_name;
+        enum rte_cryptodev_type dev_type;
+        struct rte_pci_device *pci_dev;
+
+        uint64_t feature_flags;
+
+        const struct rte_cryptodev_capabilities *capabilities;
+
+        unsigned max_nb_queue_pairs;
+
+        struct {
+            unsigned max_nb_sessions;
+        } 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.
+
+.. code-block:: c
+
+   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.*
+
+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)
+
+``rte_crypto_op_free()`` is called by the application to return an operation to
+its allocating pool.
+
+.. 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.
+
+``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 its parameters. See the section below for details on transforms.
+
+.. 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
+~~~~~~~~~~~~~~~~~~~~
+
+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;
+        struct rte_mbuf *m_dst;
+
+        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.
+
+
+Crypto Device API
+~~~~~~~~~~~~~~~~~
+
+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 (file)
index 0000000..96e3aff
--- /dev/null
@@ -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 (file)
index 0000000..4670a07
--- /dev/null
@@ -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 (file)
index 0000000..e5f41ec
--- /dev/null
@@ -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>
index a9404fb..b862d0c 100644 (file)
@@ -42,6 +42,7 @@ Programmer's Guide
     mempool_lib
     mbuf_lib
     poll_mode_drv
+    cryptodev_lib
     ivshmem_lib
     link_bonding_poll_mode_drv_lib
     timer_lib