[PATCH 0/2] cryptodev documentation patches

[PATCH 0/2] cryptodev documentation patches

[Declan Doherty]

Add an overview section to the cryptodev guide which outlines each PMD supported
algorithms.

Add new chapter to the DPDK user guide for the cryptodev library

Declan Doherty (2):
  docs: add cryptodevs guide overview section
  docs: cryptodev chapter for programmer's guide

 doc/guides/cryptodevs/index.rst                  |   3 +-
 doc/guides/cryptodevs/overview.rst               |  94 ++++
 doc/guides/prog_guide/cryptodev_lib.rst          | 584 +++++++++++++++++++++++
 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 +++
 doc/guides/prog_guide/index.rst                  |   1 +
 7 files changed, 967 insertions(+), 1 deletion(-)
 create mode 100644 doc/guides/cryptodevs/overview.rst
 create mode 100644 doc/guides/prog_guide/cryptodev_lib.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

-- 
2.5.5

[PATCH 1/2] docs: add cryptodevs guide overview section

[Declan Doherty]

Details supported device features and algorithms for each crypto PMD.

Signed-off-by: Declan Doherty <declan.doherty@intel.com>
---
 doc/guides/cryptodevs/index.rst    |  3 +-
 doc/guides/cryptodevs/overview.rst | 94 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 doc/guides/cryptodevs/overview.rst

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,,,,
-- 
2.5.5

[PATCH 2/2] docs: cryptodev chapter for programmer's guide

[Declan Doherty]

Add a programmer's guide section for cryptodev library.

Signed-off-by: Declan Doherty <declan.doherty@intel.com>
---
 doc/guides/prog_guide/cryptodev_lib.rst          | 584 +++++++++++++++++++++++
 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 +++
 doc/guides/prog_guide/index.rst                  |   1 +
 5 files changed, 871 insertions(+)
 create mode 100644 doc/guides/prog_guide/cryptodev_lib.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/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst
new file mode 100644
index 0000000..6396d02
--- /dev/null
+++ b/doc/guides/prog_guide/cryptodev_lib.rst
@@ -0,0 +1,584 @@
+..  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
+
+	/** 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.
+
+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
+
+	/**  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. */
+
+		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.
+
+.. 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 it's
+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 it's 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;	/**< 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.
+
+
+
+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
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>
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index a9404fb..b862d0c 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -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
-- 
2.5.5

Re: [PATCH 1/2] docs: add cryptodevs guide overview section

[De Lara Guarch, Pablo]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Declan Doherty
> Sent: Friday, April 08, 2016 5:17 PM
> To: dev@dpdk.org
> Cc: Doherty, Declan
> Subject: [dpdk-dev] [PATCH 1/2] docs: add cryptodevs guide overview section
> 
> Details supported device features and algorithms for each crypto PMD.
> 
> Signed-off-by: Declan Doherty <declan.doherty@intel.com>

Acked-by: Pablo de Lara <pablo.de.lara.guarch@hotmail.com>

Re: [PATCH 2/2] docs: cryptodev chapter for programmer's guide

[De Lara Guarch, Pablo]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Declan Doherty
> Sent: Friday, April 08, 2016 5:17 PM
> To: dev@dpdk.org
> Cc: Doherty, Declan
> Subject: [dpdk-dev] [PATCH 2/2] docs: cryptodev chapter for programmer's
> guide
> 
> Add a programmer's guide section for cryptodev library.
> 
> Signed-off-by: Declan Doherty <declan.doherty@intel.com>
> ---
>  doc/guides/prog_guide/cryptodev_lib.rst          | 584
> +++++++++++++++++++++++
>  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 +++
>  doc/guides/prog_guide/index.rst                  |   1 +
>  5 files changed, 871 insertions(+)
>  create mode 100644 doc/guides/prog_guide/cryptodev_lib.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/prog_guide/cryptodev_lib.rst
> b/doc/guides/prog_guide/cryptodev_lib.rst
> new file mode 100644
> index 0000000..6396d02
> --- /dev/null
> +++ b/doc/guides/prog_guide/cryptodev_lib.rst


...

> +
> +
> +Crypto Device API
> +~~~~~~~~~~~~~~~~~~~
> +
> +The cryptodev Library API is described in the *DPDK API Reference*
> document.
> +
> +

These two blank lines are not necessary.

Apart from that,
Acked-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>

Re: [PATCH 2/2] docs: cryptodev chapter for programmer's guide

[Mcnamara, John]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Declan Doherty
> Sent: Friday, April 8, 2016 5:17 PM
> To: dev@dpdk.org
> Cc: Doherty, Declan <declan.doherty@intel.com>
> Subject: [dpdk-dev] [PATCH 2/2] docs: cryptodev chapter for programmer's
> guide
> 
> Add a programmer's guide section for cryptodev library.
> 
> Signed-off-by: Declan Doherty <declan.doherty@intel.com>


Nice doc.



> +
> +
> +Cryptography Device Library
> +=============================

The underline should match the length of the title (documentation guidelines).
Shorter underlines are a warning while longer are allowed but it is best to match.


> +
> +.. 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 */
> +	};

The code blocks contain tabs instead of spaces (documentation guidelines).
This renders a little oddly for the longer examples.


Apart from these very minor comments:

Acked-by: John McNamara <john.mcnamara@intel.com>

Re: [PATCH 1/2] docs: add cryptodevs guide overview section

[Mcnamara, John]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Declan Doherty
> Sent: Friday, April 8, 2016 5:17 PM
> To: dev@dpdk.org
> Cc: Doherty, Declan <declan.doherty@intel.com>
> Subject: [dpdk-dev] [PATCH 1/2] docs: add cryptodevs guide overview
> section
> 
> Details supported device features and algorithms for each crypto PMD.
> 
> Signed-off-by: Declan Doherty <declan.doherty@intel.com>


Acked-by: John McNamara <john.mcnamara@intel.com>

Re: [PATCH 2/2] docs: cryptodev chapter for programmer's guide

[Thomas Monjalon]

> > Add a programmer's guide section for cryptodev library.
> > 
> > Signed-off-by: Declan Doherty <declan.doherty@intel.com>
[...]
> Apart from these very minor comments:
> Acked-by: John McNamara <john.mcnamara@intel.com>

Applied with some formatting fixes.
We must be careful to not put too much code in docs to keep them maintainable.