DPDK patches and discussions
 help / color / mirror / Atom feed
From: David Coyle <david.coyle@intel.com>
To: dev@dpdk.org
Cc: declan.doherty@intel.com, fiona.trahe@intel.com,
	pablo.de.lara.guarch@intel.com, brendan.ryan@intel.com,
	shreyansh.jain@nxp.com, hemant.agrawal@nxp.com,
	akhil.goyal@nxp.com, ferruh.yigit@intel.com,
	David Coyle <david.coyle@intel.com>,
	Mairtin o Loingsigh <mairtin.oloingsigh@intel.com>
Subject: [dpdk-dev] [PATCH v3 4/4] doc: update docs for aesni_mb_mfn raw device PMD
Date: Fri, 10 Apr 2020 15:27:57 +0100	[thread overview]
Message-ID: <20200410142757.31508-5-david.coyle@intel.com> (raw)
In-Reply-To: <20200410142757.31508-1-david.coyle@intel.com>

Update documentation for the AESNI-MB Multi-Function raw device
PMD.

Signed-off-by: David Coyle <david.coyle@intel.com>
Signed-off-by: Mairtin o Loingsigh <mairtin.oloingsigh@intel.com>
---
 doc/api/doxy-api-index.md              |   3 +-
 doc/api/doxy-api.conf.in               |   1 +
 doc/guides/rawdevs/aesni_mb_mfn.rst    | 219 +++++++++++++++++++++++++
 doc/guides/rawdevs/index.rst           |   1 +
 doc/guides/rel_notes/release_20_05.rst |   6 +
 5 files changed, 229 insertions(+), 1 deletion(-)
 create mode 100644 doc/guides/rawdevs/aesni_mb_mfn.rst

diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index dff496be0..328d26991 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -49,7 +49,8 @@ The public API headers are grouped by topics:
   [dpaa2_mempool]      (@ref rte_dpaa2_mempool.h),
   [dpaa2_cmdif]        (@ref rte_pmd_dpaa2_cmdif.h),
   [dpaa2_qdma]         (@ref rte_pmd_dpaa2_qdma.h),
-  [crypto_scheduler]   (@ref rte_cryptodev_scheduler.h)
+  [crypto_scheduler]   (@ref rte_cryptodev_scheduler.h),
+  [multi_fn]           (@ref rte_multi_fn.h)
 
 - **memory**:
   [memseg]             (@ref rte_memory.h),
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index 65e8146be..efae9795e 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -15,6 +15,7 @@ INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
                           @TOPDIR@/drivers/net/ice \
                           @TOPDIR@/drivers/net/ixgbe \
                           @TOPDIR@/drivers/net/softnic \
+                          @TOPDIR@/drivers/raw/common/multi_fn \
                           @TOPDIR@/drivers/raw/dpaa2_cmdif \
                           @TOPDIR@/drivers/raw/dpaa2_qdma \
                           @TOPDIR@/lib/librte_eal/include \
diff --git a/doc/guides/rawdevs/aesni_mb_mfn.rst b/doc/guides/rawdevs/aesni_mb_mfn.rst
new file mode 100644
index 000000000..aaa8edd19
--- /dev/null
+++ b/doc/guides/rawdevs/aesni_mb_mfn.rst
@@ -0,0 +1,219 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2020 Intel Corporation.
+
+AES-NI Multi Buffer Multi-Function Rawdev Driver
+================================================
+
+The AES-NI MB Multi-Function Rawdev PMD is a poll mode driver which enables
+utilization of new multi-function processing capabilities in the Intel IPSec
+Multi Buffer library (see :doc:`../cryptodevs/aesni_mb` for more details on this
+library).
+
+This Rawdev PMD supports a new Multi-Function interface, which provides a way of
+combining one or more packet-processing functions into a single operation,
+thereby allowing these to be performed in parallel by the Intel IPSec Multi
+Buffer library. Through the multi-function interface, the following use-cases
+are supported by this PMD:
+
+* DOCSIS MAC: Crypto-CRC
+* GPON MAC: Crypto-CRC-BIP
+
+
+Features
+--------
+
+AES-NI MB Multi-Function Rawdev PMD currently supports the following:
+
+Cipher algorithms:
+
+* RTE_CRYPTO_CIPHER_AES_CTR (128 bit)
+* RTE_CRYPTO_CIPHER_AES_DOCSISBPI (128 bit)
+
+Error Detection algorithms:
+
+* RTE_MULTI_FN_ERR_DETECT_BIP32
+* RTE_MULTI_FN_ERR_DETECT_CRC32_ETH
+
+These algorithms may only be combined through the multi-function interface in
+the following specific orders for use by this PMD:
+
+* For DOCSIS Crypto-CRC (Encrypt direction)
+
+  1. RTE_MULTI_FN_ERR_DETECT_CRC32_ETH (Generate)
+  2. RTE_CRYPTO_CIPHER_AES_DOCSISBPI (Encrypt)
+
+
+* For DOCSIS Crypto-CRC (Decrypt direction)
+
+  1. RTE_CRYPTO_CIPHER_AES_DOCSISBPI (Decrypt)
+  2. RTE_MULTI_FN_ERR_DETECT_CRC32_ETH (Verify)
+
+
+* For GPON Crypto-CRC-BIP (Encrypt direction)
+
+  1. RTE_MULTI_FN_ERR_DETECT_CRC32_ETH (Generate)
+  2. RTE_CRYPTO_CIPHER_AES_CTR (Encrypt)
+  3. RTE_MULTI_FN_ERR_DETECT_BIP32 (Generate)
+
+
+* For GPON Crypto-CRC-BIP (Decrypt direction)
+
+  1. RTE_MULTI_FN_ERR_DETECT_BIP32 (Generate)
+  2. RTE_CRYPTO_CIPHER_AES_CTR (Decrypt)
+  3. RTE_MULTI_FN_ERR_DETECT_CRC32_ETH (Verify)
+
+
+Limitations
+-----------
+
+* Chained mbufs are not supported.
+* Out of place operation is not supported.
+* Only 128-bit keys for RTE_CRYPTO_CIPHER_AES_CTR and
+  RTE_CRYPTO_CIPHER_AES_DOCSISBPI are supported.
+
+
+Installation
+------------
+
+The AES-NI MB Multi-Function Rawdev PMD requires the Intel IPSec Multi Buffer
+library be installed on the system. For details on how to install this library,
+please see :doc:`../cryptodevs/aesni_mb`.
+
+.. note::
+
+   This PMD requires v0.54 or later of the Intel IPSec Multi Buffer library.
+
+
+Initialization
+--------------
+
+In order to enable the AES-NI MB Multi-Function Rawdev PMD, the user must:
+
+* Build the multi buffer library (as explained in Installation section).
+* Set CONFIG_RTE_LIBRTE_MULTI_FN_COMMON=y in config/common_base.
+* Set CONFIG_RTE_LIBRTE_PMD_AESNI_MB_MFN_RAWDEV=y in config/common_base.
+
+To enabled extra debug features such as extra parameter checking, the user must:
+
+* Set CONFIG_RTE_LIBRTE_PMD_AESNI_MB_RAWDEV_MFN_DEBUG=y in config/common_base.
+
+Note, however, that doing so will impact performance.
+
+To use the PMD in an application, the user must:
+
+* Call rte_vdev_init("rawdev_mfn_aesni_mb") within the application.
+* Use --vdev="rawdev_mfn_aesni_mb" in the EAL options, which will call
+  rte_vdev_init() internally.
+
+Example:
+
+.. code-block:: console
+
+    <application> -l 1 -n 4 --vdev="rawdev_mfn_aesni_mb" -- <application params>
+
+
+Device Configuration
+--------------------
+
+Configuring the AES-NI MB Multi-Function Rawdev PMD is done through a
+combination of the ``rte_rawdev_configure()`` API and the
+``struct rte_multi_fn_dev_config``  structure of the multi-function interface.
+
+The following code shows how the device is configured:
+
+.. code-block:: c
+
+    struct rte_multi_fn_dev_config mf_dev_conf = {
+                    .nb_queues = 1,
+                    .socket_id = 0
+    };
+    struct rte_rawdev_info rdev_info = {.dev_private = &mf_dev_conf};
+
+    rte_rawdev_configure(dev_id, (rte_rawdev_obj_t)&rdev_info);
+
+
+Queue Pair Configuration
+------------------------
+
+Configuring the queue pairs of the AES-NI MB Multi-Function Rawdev PMD is done
+through a combination of the ``rte_rawdev_queue_setup()`` API and the
+``struct rte_multi_fn_qp_config`` structure of the multi-function interface.
+
+The following code shows how the queue pairs are configured:
+
+.. code-block:: c
+
+    struct rte_multi_fn_qp_config qp_conf = {
+                    .nb_descriptors = 4096
+    };
+
+    rte_rawdev_queue_setup(dev_id, qp_id, (rte_rawdev_obj_t)&qp_conf);
+
+
+Multi-Function Session Creation
+-------------------------------
+
+Multi-function sessions are created on the AES-NI MB Multi-Function Rawdev PMD
+through the multi-function interface by chaining ``struct rte_multi_fn_xform``
+transforms together and calling the ``rte_multi_fn_session_create()`` API.
+
+The only transform chains supported by this PMD are listed in the Features
+section.
+
+The following code shows how a multi-function session is created, taking
+Crypto-CRC chaining as an example:
+
+.. code-block:: c
+
+    struct rte_multi_fn_xform xform[2] = {0};
+
+    xform[0].type = RTE_MULTI_FN_XFORM_TYPE_ERR_DETECT;
+    xform[0].err_detect.algo = RTE_MULTI_FN_ERR_DETECT_CRC32_ETH;
+    xform[0].err_detect.op = RTE_MULTI_FN_ERR_DETECT_OP_GENERATE;
+    xform[0].next = &xform[1];
+
+    xform[1].type = RTE_MULTI_FN_XFORM_TYPE_CRYPTO_SYM;
+    xform[1].crypto_sym.type = RTE_CRYPTO_SYM_XFORM_CIPHER;
+    xform[1].next = NULL;
+    /*
+     * setup reaminder of xform[1].crypto_sym.cipher fields here, including
+     * op, algo, key and iv
+     */
+
+    sess = rte_multi_fn_session_create(dev_id, &xform[0], rte_socket_id());
+
+
+Performing Multi-Function Operations
+------------------------------------
+
+Multi-function operations are performed on the AES-NI MB Multi-Function Rawdev
+PMD using the ``rte_rawdev_enqueue_buffers()`` and
+``rte_rawdev_dequeue_buffers()`` APIs. Chains of multi-function operations
+(``struct rte_multi_fn_op``) which are associated with an mbuf and a
+multi-function session are passed to these APIs.
+
+The following code shows how these APIs are used:
+
+
+.. code-block:: c
+
+    struct rte_multi_fn_op *ops[2];
+    rte_multi_fn_op_bulk_alloc(op_pool, ops, 2);
+
+    ops[0]->next = ops[1];
+    ops[0]->m_src = src;
+    ops[0]->sess = sess;
+    ops[1]->next = NULL;
+    /* setup remainder of ops here */
+
+    rte_rawdev_enqueue_buffers(dev_id,
+                               (struct rte_rawdev_buf **)ops,
+                               1,
+                               (rte_rawdev_obj_t)&qp_id);
+
+    do {
+        nb_deq = rte_rawdev_dequeue_buffers(dev_id,
+                                            (struct rte_rawdev_buf **)ops,
+                                            1,
+                                            (rte_rawdev_obj_t)&qp_id);
+    } while (nb_deq < 1);
diff --git a/doc/guides/rawdevs/index.rst b/doc/guides/rawdevs/index.rst
index f64ec4427..3e765adda 100644
--- a/doc/guides/rawdevs/index.rst
+++ b/doc/guides/rawdevs/index.rst
@@ -18,3 +18,4 @@ application through rawdev API.
     ntb
     octeontx2_dma
     octeontx2_ep
+    aesni_mb_mfn
diff --git a/doc/guides/rel_notes/release_20_05.rst b/doc/guides/rel_notes/release_20_05.rst
index 000bbf501..c969cd4aa 100644
--- a/doc/guides/rel_notes/release_20_05.rst
+++ b/doc/guides/rel_notes/release_20_05.rst
@@ -62,6 +62,12 @@ New Features
 
   * Added support for matching on IPv4 Time To Live and IPv6 Hop Limit.
 
+* **Added AES-NI MB Multi-Function rawdev PMD.**
+
+  Added a new AESNI-MB Multi-Function raw device PMD for utilizing
+  multi-function capabilities of the Intel IPSec Multi Buffer library. See
+  the :doc:`../rawdevs/aesni_mb_mfn` guide for more details on this new PMD.
+
 
 Removed Items
 -------------
-- 
2.17.1


  parent reply	other threads:[~2020-04-10 14:41 UTC|newest]

Thread overview: 92+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-04-10 14:27 [dpdk-dev] [PATCH v3 0/4] add AESNI-MB rawdev for multi-function processing David Coyle
2020-04-10 14:27 ` [dpdk-dev] [PATCH v3 1/4] raw/common: add multi-function interface David Coyle
2020-04-10 14:27 ` [dpdk-dev] [PATCH v3 2/4] raw/aesni_mb_mfn: add aesni_mb_mfn raw device PMD David Coyle
2020-04-10 14:27 ` [dpdk-dev] [PATCH v3 3/4] test/rawdev: add aesni_mb_mfn raw device tests David Coyle
2020-04-10 14:27 ` David Coyle [this message]
2020-04-10 22:55 ` [dpdk-dev] [PATCH v3 0/4] add AESNI-MB rawdev for multi-function processing Thomas Monjalon
2020-04-14 10:21   ` Ferruh Yigit
2020-04-14 10:32     ` Thomas Monjalon
2020-04-14 13:04       ` Trahe, Fiona
2020-04-14 13:24         ` Thomas Monjalon
2020-04-14 14:02           ` Trahe, Fiona
2020-04-14 14:44             ` Thomas Monjalon
2020-04-15 22:19               ` Doherty, Declan
2020-04-15 22:33                 ` Thomas Monjalon
2020-04-21 16:46                   ` Doherty, Declan
2020-04-21 17:23                     ` Coyle, David
2020-04-22 10:51                       ` Akhil Goyal
2020-04-22 13:17                         ` Coyle, David
2020-04-22 13:44                           ` Akhil Goyal
2020-04-22 14:21                             ` Coyle, David
2020-05-01 13:18                             ` Zhang, Roy Fan
2020-05-12 17:32                               ` Coyle, David
2020-04-22 14:01                       ` Kevin Traynor
2020-04-22 14:41                         ` Coyle, David
2020-04-21 17:25                     ` Thomas Monjalon
2020-04-21 18:37                       ` Coyle, David
2020-04-21 21:51                         ` Thomas Monjalon
2020-06-04 15:13 ` [dpdk-dev] [PATCH 0/3] add support for DOCSIS protocol to security library David Coyle
2020-06-04 15:13   ` [dpdk-dev] [PATCH 1/3] security: add support for DOCSIS protocol David Coyle
2020-06-04 15:13   ` [dpdk-dev] [PATCH 2/3] cryptodev: add security operation to crypto operation David Coyle
2020-06-09 13:23     ` Ananyev, Konstantin
2020-06-09 13:50       ` Coyle, David
2020-06-10 10:40         ` Ananyev, Konstantin
2020-06-10 12:02           ` Coyle, David
2020-06-11 12:21             ` Ananyev, Konstantin
2020-06-11 14:01               ` Coyle, David
2020-06-23 18:38               ` Akhil Goyal
2020-06-24 14:11                 ` Coyle, David
2020-06-04 15:13   ` [dpdk-dev] [PATCH 3/3] crypto/aesni_mb: add support for DOCSIS protocol David Coyle
2020-06-23 10:14   ` [dpdk-dev] [PATCH v2 0/6] " David Coyle
2020-06-23 10:14     ` [dpdk-dev] [PATCH v2 1/6] cryptodev: add security operation to crypto operation David Coyle
2020-06-23 10:14     ` [dpdk-dev] [PATCH v2 2/6] security: add support for DOCSIS protocol David Coyle
2020-06-23 17:29       ` De Lara Guarch, Pablo
2020-06-26 15:15         ` Coyle, David
2020-06-23 18:06       ` Akhil Goyal
2020-06-24 14:25         ` Coyle, David
2020-06-23 10:14     ` [dpdk-dev] [PATCH v2 3/6] crypto/aesni_mb: " David Coyle
2020-06-23 17:57       ` De Lara Guarch, Pablo
2020-06-26 15:13         ` Coyle, David
2020-06-23 10:14     ` [dpdk-dev] [PATCH v2 4/6] crypto/qat: " David Coyle
2020-06-23 10:14     ` [dpdk-dev] [PATCH v2 5/6] test/crypto: add DOCSIS security test cases David Coyle
2020-06-23 18:04       ` De Lara Guarch, Pablo
2020-06-26 15:14         ` Coyle, David
2020-06-23 10:14     ` [dpdk-dev] [PATCH v2 6/6] test/security: add DOCSIS capability check tests David Coyle
2020-06-23 14:51     ` [dpdk-dev] [PATCH v2 0/6] add support for DOCSIS protocol David Marchand
2020-06-23 15:18       ` Coyle, David
2020-06-23 15:38         ` David Marchand
2020-06-23 15:56           ` Coyle, David
2020-06-23 16:22             ` David Marchand
2020-06-23 16:27               ` Coyle, David
2020-06-30 16:30     ` [dpdk-dev] [PATCH v3 0/8] " David Coyle
2020-06-30 16:30       ` [dpdk-dev] [PATCH v3 1/8] security: " David Coyle
2020-07-01 21:41         ` Akhil Goyal
2020-06-30 16:30       ` [dpdk-dev] [PATCH v3 2/8] cryptodev: add a note regarding DOCSIS protocol support David Coyle
2020-07-01 21:42         ` Akhil Goyal
2020-06-30 16:30       ` [dpdk-dev] [PATCH v3 3/8] crypto/aesni_mb: add support for DOCSIS protocol David Coyle
2020-07-01 17:04         ` Coyle, David
2020-06-30 16:30       ` [dpdk-dev] [PATCH v3 4/8] crypto/qat: " David Coyle
2020-07-01 17:04         ` Coyle, David
2020-06-30 16:30       ` [dpdk-dev] [PATCH v3 5/8] test/crypto: add DOCSIS security test cases David Coyle
2020-07-01 21:43         ` Akhil Goyal
2020-06-30 16:30       ` [dpdk-dev] [PATCH v3 6/8] test/security: add DOCSIS capability check tests David Coyle
2020-06-30 16:30       ` [dpdk-dev] [PATCH v3 7/8] app/crypto-perf: add support for DOCSIS protocol David Coyle
2020-07-01 21:44         ` Akhil Goyal
2020-06-30 16:30       ` [dpdk-dev] [PATCH v3 8/8] doc: add doc updates for DOCSIS security protocol David Coyle
2020-06-30 18:33         ` Akhil Goyal
2020-07-01 17:03           ` Coyle, David
2020-07-03 12:39       ` [dpdk-dev] [PATCH v4 0/7] add support for DOCSIS protocol David Coyle
2020-07-03 12:39         ` [dpdk-dev] [PATCH v4 1/7] security: " David Coyle
2020-07-03 17:50           ` De Lara Guarch, Pablo
2020-07-03 12:39         ` [dpdk-dev] [PATCH v4 2/7] cryptodev: add a note regarding DOCSIS protocol support David Coyle
2020-07-03 17:56           ` De Lara Guarch, Pablo
2020-07-03 12:39         ` [dpdk-dev] [PATCH v4 3/7] crypto/aesni_mb: add support for DOCSIS protocol David Coyle
2020-07-03 17:56           ` De Lara Guarch, Pablo
2020-07-04 19:55           ` Akhil Goyal
2020-07-03 12:39         ` [dpdk-dev] [PATCH v4 4/7] crypto/qat: " David Coyle
2020-07-03 12:39         ` [dpdk-dev] [PATCH v4 5/7] test/crypto: add DOCSIS security test cases David Coyle
2020-07-03 17:56           ` De Lara Guarch, Pablo
2020-07-03 12:39         ` [dpdk-dev] [PATCH v4 6/7] test/security: add DOCSIS capability check tests David Coyle
2020-07-03 12:39         ` [dpdk-dev] [PATCH v4 7/7] app/crypto-perf: add support for DOCSIS protocol David Coyle
2020-07-03 17:57           ` De Lara Guarch, Pablo
2020-07-04 19:54         ` [dpdk-dev] [PATCH v4 0/7] " Akhil Goyal

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200410142757.31508-5-david.coyle@intel.com \
    --to=david.coyle@intel.com \
    --cc=akhil.goyal@nxp.com \
    --cc=brendan.ryan@intel.com \
    --cc=declan.doherty@intel.com \
    --cc=dev@dpdk.org \
    --cc=ferruh.yigit@intel.com \
    --cc=fiona.trahe@intel.com \
    --cc=hemant.agrawal@nxp.com \
    --cc=mairtin.oloingsigh@intel.com \
    --cc=pablo.de.lara.guarch@intel.com \
    --cc=shreyansh.jain@nxp.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).