From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id BC2E6A059F; Fri, 10 Apr 2020 16:41:14 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id AB9901D5A1; Fri, 10 Apr 2020 16:40:37 +0200 (CEST) Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id E3B441D592 for ; Fri, 10 Apr 2020 16:40:35 +0200 (CEST) IronPort-SDR: QD2LXf4rvuI8V2Q5ex2fpgfeO24M9jxZcnXgwWCncRRl9MZjYNqdk/fBzTreiGDJbKLrNNe6wf 9FI1OLPhnZqg== X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga007.fm.intel.com ([10.253.24.52]) by orsmga101.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 10 Apr 2020 07:40:35 -0700 IronPort-SDR: O+M1NDG3fApcACnt+lmAjrhZ9Iac2+DWzirZslm6D+p7chDYRhbkvNRXfkEraiwmQTZwgedDKC jZURdf0+vlOA== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.72,367,1580803200"; d="scan'208";a="242938925" Received: from silpixa00399912.ir.intel.com (HELO silpixa00399912.ger.corp.intel.com) ([10.237.223.64]) by fmsmga007.fm.intel.com with ESMTP; 10 Apr 2020 07:40:32 -0700 From: David Coyle 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 , Mairtin o Loingsigh Date: Fri, 10 Apr 2020 15:27:57 +0100 Message-Id: <20200410142757.31508-5-david.coyle@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200410142757.31508-1-david.coyle@intel.com> References: <20200410142757.31508-1-david.coyle@intel.com> Subject: [dpdk-dev] [PATCH v3 4/4] doc: update docs for aesni_mb_mfn raw device PMD X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Update documentation for the AESNI-MB Multi-Function raw device PMD. Signed-off-by: David Coyle Signed-off-by: Mairtin o Loingsigh --- 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 + + -l 1 -n 4 --vdev="rawdev_mfn_aesni_mb" -- + + +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