From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
	by inbox.dpdk.org (Postfix) with ESMTP id A518BA055A;
	Wed, 16 Nov 2022 13:06:40 +0100 (CET)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 8904840E03;
	Wed, 16 Nov 2022 13:06:39 +0100 (CET)
Received: from mga07.intel.com (mga07.intel.com [134.134.136.100])
 by mails.dpdk.org (Postfix) with ESMTP id E691640DFB
 for <dev@dpdk.org>; Wed, 16 Nov 2022 13:06:36 +0100 (CET)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple;
 d=intel.com; i=@intel.com; q=dns/txt; s=Intel;
 t=1668600397; x=1700136397;
 h=from:to:cc:subject:date:message-id:in-reply-to:
 references:mime-version:content-transfer-encoding;
 bh=I9SMtKcrW8gCYz6+I/q1HNr6GGwAXgX/BzCoruZxzVg=;
 b=ZiUDwnw0stHHWEyMv1OKEDlaCpzy4Oj+BGKKRjdOmgejmyuPqYK6TBEd
 fe0WcKlB1jaYUUZBKZXkMFbk+RHGCPgatEqEfqNd6LwAKqyl0IxY9umLW
 YEShzv0Q96w5ViTubBL6YSu0NzGSNRccIT3tX7/l5OGmt4itrbZZvgSDP
 KvPQHCM3tJHGYe0J+s4yyciVFeGk/7bjsk3cTLadh//N/8H2dHQzMMnlr
 c1jJLYcVv2K57g3/TjhIChvep8z5Q14TW9sMdEfp9AQP6KkvrT/BudNDo
 qwOozHA4K1fO66wGiQ3qlIQYEPJbh8Q1HPRhOm8dX5oj+EFT8uP2t7P9t w==;
X-IronPort-AV: E=McAfee;i="6500,9779,10532"; a="376796676"
X-IronPort-AV: E=Sophos;i="5.96,167,1665471600"; d="scan'208";a="376796676"
Received: from orsmga005.jf.intel.com ([10.7.209.41])
 by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
 16 Nov 2022 04:06:33 -0800
X-ExtLoop1: 1
X-IronPort-AV: E=McAfee;i="6500,9779,10532"; a="814066595"
X-IronPort-AV: E=Sophos;i="5.96,167,1665471600"; d="scan'208";a="814066595"
Received: from silpixa00400465.ir.intel.com ([10.55.128.22])
 by orsmga005.jf.intel.com with ESMTP; 16 Nov 2022 04:06:31 -0800
From: Kai Ji <kai.ji@intel.com>
To: dev@dpdk.org
Cc: gakhil@marvell.com, Pablo de Lara <pablo.de.lara.guarch@intel.com>,
 Kai Ji <kai.ji@intel.com>
Subject: [dpdk-dev v6] doc: support IPsec Multi-buffer lib v1.3
Date: Wed, 16 Nov 2022 20:06:29 +0800
Message-Id: <20221116120629.56634-1-kai.ji@intel.com>
X-Mailer: git-send-email 2.17.1
In-Reply-To: <20221115171109.77561-1-kai.ji@intel.com>
References: <20221115171109.77561-1-kai.ji@intel.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org

From: Pablo de Lara <pablo.de.lara.guarch@intel.com>

Updated AESNI MB and AESNI GCM, KASUMI, ZUC, SNOW3G
and CHACHA20_POLY1305 PMD documentation guides
with information about the latest Intel IPSec Multi-buffer
library supported.

Signed-off-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
Acked-by: Ciara Power <ciara.power@intel.com>
Acked-by: Brian Dooley <brian.dooley@intel.com>
Signed-off-by: Kai Ji <kai.ji@intel.com>
---
-v6: Release notes update reword
-v5: Release notes update
-v4: Added information on CHACHA20_POLY1305 PMD guide
-v3: Fixed library version from 1.2 to 1.3 in one line
-v2: Removed repeated word 'the'
---
 doc/guides/cryptodevs/aesni_gcm.rst         |  8 +++---
 doc/guides/cryptodevs/aesni_mb.rst          | 29 ++++++++++++++++-----
 doc/guides/cryptodevs/chacha20_poly1305.rst | 12 ++++++---
 doc/guides/cryptodevs/kasumi.rst            | 15 ++++++++---
 doc/guides/cryptodevs/snow3g.rst            | 15 ++++++++---
 doc/guides/cryptodevs/zuc.rst               | 14 +++++++---
 doc/guides/rel_notes/release_22_11.rst      | 11 +++++++-
 7 files changed, 77 insertions(+), 27 deletions(-)

diff --git a/doc/guides/cryptodevs/aesni_gcm.rst b/doc/guides/cryptodevs/aesni_gcm.rst
index 6229392f58..5192287ed8 100644
--- a/doc/guides/cryptodevs/aesni_gcm.rst
+++ b/doc/guides/cryptodevs/aesni_gcm.rst
@@ -40,8 +40,8 @@ Installation
 To build DPDK with the AESNI_GCM_PMD the user is required to download the multi-buffer
 library from `here <https://github.com/01org/intel-ipsec-mb>`_
 and compile it on their user system before building DPDK.
-The latest version of the library supported by this PMD is v1.2, which
-can be downloaded in `<https://github.com/01org/intel-ipsec-mb/archive/v1.2.zip>`_.
+The latest version of the library supported by this PMD is v1.3, which
+can be downloaded in `<https://github.com/01org/intel-ipsec-mb/archive/v1.3.zip>`_.

 .. code-block:: console

@@ -84,8 +84,8 @@ and the external crypto libraries supported by them:
    17.08 - 18.02  Multi-buffer library 0.46 - 0.48
    18.05 - 19.02  Multi-buffer library 0.49 - 0.52
    19.05 - 20.08  Multi-buffer library 0.52 - 0.55
-   20.11 - 21.08  Multi-buffer library 0.53 - 1.2*
-   21.11+         Multi-buffer library 1.0  - 1.2*
+   20.11 - 21.08  Multi-buffer library 0.53 - 1.3*
+   21.11+         Multi-buffer library 1.0  - 1.3*
    =============  ================================

 \* Multi-buffer library 1.0 or newer only works for Meson but not Make build system.
diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst
index 599ed5698f..b9bf03655d 100644
--- a/doc/guides/cryptodevs/aesni_mb.rst
+++ b/doc/guides/cryptodevs/aesni_mb.rst
@@ -1,7 +1,7 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2015-2018 Intel Corporation.

-AESN-NI Multi Buffer Crypto Poll Mode Driver
+AES-NI Multi Buffer Crypto Poll Mode Driver
 ============================================


@@ -10,8 +10,6 @@ support for utilizing Intel multi buffer library, see the white paper
 `Fast Multi-buffer IPsec Implementations on IntelĀ® Architecture Processors
 <https://www.intel.com/content/dam/www/public/us/en/documents/white-papers/fast-multi-buffer-ipsec-implementations-ia-processors-paper.pdf>`_.

-The AES-NI MB PMD has current only been tested on Fedora 21 64-bit with gcc.
-
 The AES-NI MB PMD supports synchronous mode of operation with
 ``rte_cryptodev_sym_cpu_crypto_process`` function call.

@@ -77,6 +75,23 @@ Limitations
 * RTE_CRYPTO_CIPHER_DES_DOCSISBPI is not supported for combined Crypto-CRC
   DOCSIS security protocol.

+AESNI MB PMD selection over SNOW3G/ZUC/KASUMI PMDs
+--------------------------------------------------
+
+This PMD supports wireless cipher suite (SNOW3G, ZUC and KASUMI).
+On Intel processors, it is recommended to use this PMD instead of SNOW3G, ZUC and KASUMI PMDs,
+as it enables algorithm mixing (e.g. cipher algorithm SNOW3G-UEA2 with
+authentication algorithm AES-CMAC-128) and performance over IMIX (packet size mix) traffic
+is significantly higher.
+
+AESNI MB PMD selection over CHACHA20-POLY1305 PMD
+-------------------------------------------------
+
+This PMD supports Chacha20-Poly1305 algorithm.
+On Intel processors, it is recommended to use this PMD instead of CHACHA20-POLY1305 PMD,
+as it delivers better performance on single segment buffers.
+For multi-segment buffers, it is still recommended to use CHACHA20-POLY1305 PMD,
+until the new SGL API is introduced in the AESNI MB PMD.

 Installation
 ------------
@@ -84,8 +99,8 @@ Installation
 To build DPDK with the AESNI_MB_PMD the user is required to download the multi-buffer
 library from `here <https://github.com/01org/intel-ipsec-mb>`_
 and compile it on their user system before building DPDK.
-The latest version of the library supported by this PMD is v1.2, which
-can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.2.zip>`_.
+The latest version of the library supported by this PMD is v1.3, which
+can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.3.zip>`_.

 .. code-block:: console

@@ -130,8 +145,8 @@ and the Multi-Buffer library version supported by them:
    18.05 - 19.02   0.49 - 0.52
    19.05 - 19.08   0.52
    19.11 - 20.08   0.52 - 0.55
-   20.11 - 21.08   0.53 - 1.2*
-   21.11+          1.0  - 1.2*
+   20.11 - 21.08   0.53 - 1.3*
+   21.11+          1.0  - 1.3*
    ==============  ============================

 \* Multi-buffer library 1.0 or newer only works for Meson but not Make build system.
diff --git a/doc/guides/cryptodevs/chacha20_poly1305.rst b/doc/guides/cryptodevs/chacha20_poly1305.rst
index 4db260818e..7d69c4b192 100644
--- a/doc/guides/cryptodevs/chacha20_poly1305.rst
+++ b/doc/guides/cryptodevs/chacha20_poly1305.rst
@@ -16,6 +16,12 @@ AEAD algorithms:

 * RTE_CRYPTO_AEAD_CHACHA20_POLY1305

+Chaha20_Poly1305 PMD vs AESNI MB PMD
+------------------------------------
+
+AESNI MB PMD also supports CHACHA20-POLY1305 algorithms.
+It is recommended to use the AESNI MB PMD, which offers better performance on Intel processors, when single-segment buffers are used.
+Take a look at the PMD documentation here :doc:`aesni_mb` for more information.

 Installation
 ------------
@@ -23,8 +29,8 @@ Installation
 To build DPDK with the Chacha20-poly1305 PMD the user is required to download
 the multi-buffer library from `here <https://github.com/01org/intel-ipsec-mb>`_
 and compile it on their user system before building DPDK.
-The latest version of the library supported by this PMD is v1.0, which
-can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.0.zip>`_.
+The latest version of the library supported by this PMD is v1.3, which
+can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.3.zip>`_.

 After downloading the library, the user needs to unpack and compile it
 on their system before building DPDK:
@@ -64,7 +70,7 @@ and the external crypto libraries supported by them:
    =============  ================================
    DPDK version   Crypto library version
    =============  ================================
-   21.11+         Multi-buffer library 1.0*
+   21.11+         Multi-buffer library 1.0-1.3*
    =============  ================================

 \* Multi-buffer library 1.0 or newer only works for Meson but not Make build system.
diff --git a/doc/guides/cryptodevs/kasumi.rst b/doc/guides/cryptodevs/kasumi.rst
index d8128928f8..c8e8f1b847 100644
--- a/doc/guides/cryptodevs/kasumi.rst
+++ b/doc/guides/cryptodevs/kasumi.rst
@@ -30,14 +30,21 @@ Limitations
   (if length and/or offset of data to be ciphered is not byte-aligned).


+KASUMI PMD vs AESNI MB PMD
+--------------------------
+
+AESNI MB PMD also supports KASUMI cipher and authentication algorithms,
+It is recommended to use the AESNI MB PMD, which offers better performance on Intel processors.
+Take a look at the PMD documentation here :doc:`aesni_mb` for more information.
+
 Installation
 ------------

 To build DPDK with the KASUMI_PMD the user is required to download the multi-buffer
 library from `here <https://github.com/01org/intel-ipsec-mb>`_
 and compile it on their user system before building DPDK.
-The latest version of the library supported by this PMD is v1.2, which
-can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.2.zip>`_.
+The latest version of the library supported by this PMD is v1.3, which
+can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.3.zip>`_.

 After downloading the library, the user needs to unpack and compile it
 on their system before building DPDK:
@@ -78,8 +85,8 @@ and the external crypto libraries supported by them:
    DPDK version   Crypto library version
    =============  ================================
    16.11 - 19.11  LibSSO KASUMI
-   20.02 - 21.08  Multi-buffer library 0.53 - 1.2*
-   21.11+         Multi-buffer library 1.0  - 1.2*
+   20.02 - 21.08  Multi-buffer library 0.53 - 1.3*
+   21.11+         Multi-buffer library 1.0  - 1.3*
    =============  ================================

 \* Multi-buffer library 1.0 or newer only works for Meson but not Make build system.
diff --git a/doc/guides/cryptodevs/snow3g.rst b/doc/guides/cryptodevs/snow3g.rst
index 02e857c0d2..a27a6ea050 100644
--- a/doc/guides/cryptodevs/snow3g.rst
+++ b/doc/guides/cryptodevs/snow3g.rst
@@ -29,6 +29,13 @@ Limitations
 * In-place bit-level operations for SNOW 3G (UEA2) are not supported
   (if length and/or offset of data to be ciphered is not byte-aligned).

+SNOW3G PMD vs AESNI MB PMD
+--------------------------
+
+AESNI MB PMD also supports SNOW3G cipher and authentication algorithms,
+It is recommended to use the AESNI MB PMD, which offers better performance on Intel processors.
+Take a look at the PMD documentation here :doc:`aesni_mb` for more information.
+
 Installation
 ------------

@@ -37,8 +44,8 @@ library and compile it on their user system before building DPDK.

 For x86 system, the multi-buffer library is available
 `here <https://github.com/01org/intel-ipsec-mb>`_.
-The latest version of the library supported by this PMD is v1.2, which
-can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.2.zip>`_.
+The latest version of the library supported by this PMD is v1.3, which
+can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.3.zip>`_.

 For Arm system, ARM64 port of the multi-buffer library can be downloaded from
 `<https://gitlab.arm.com/arm-reference-solutions/ipsec-mb/-/tree/main/>`_. The
@@ -83,8 +90,8 @@ and the external crypto libraries supported by them:
    DPDK version   Crypto library version
    =============  ================================
    16.04 - 19.11  LibSSO SNOW3G
-   20.02 - 21.08  Multi-buffer library 0.53 - 1.2*
-   21.11+         Multi-buffer library 1.0  - 1.2*
+   20.02 - 21.08  Multi-buffer library 0.53 - 1.3*
+   21.11+         Multi-buffer library 1.0  - 1.3*
    =============  ================================

 \* Multi-buffer library 1.0 or newer only works for Meson but not Make build system.
diff --git a/doc/guides/cryptodevs/zuc.rst b/doc/guides/cryptodevs/zuc.rst
index 10d44b7393..8b646dd1e0 100644
--- a/doc/guides/cryptodevs/zuc.rst
+++ b/doc/guides/cryptodevs/zuc.rst
@@ -28,6 +28,12 @@ Limitations
 * ZUC (EIA3) supported only if hash offset field is byte-aligned.
 * ZUC (EEA3) supported only if cipher length, cipher offset fields are byte-aligned.

+ZUC PMD vs AESNI MB PMD
+-----------------------
+
+AESNI MB PMD also supports ZUC cipher and authentication algorithms,
+It is recommended to use the AESNI MB PMD, which offers better performance on Intel processors.
+Take a look at the PMD documentation here :doc:`aesni_mb` for more information.

 Installation
 ------------
@@ -37,8 +43,8 @@ library and compile it on their user system before building DPDK.

 For x86 system, the multi-buffer library is available
 `here <https://github.com/01org/intel-ipsec-mb>`_.
-The latest version of the library supported by this PMD is v1.2, which
-can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.2.zip>`_.
+The latest version of the library supported by this PMD is v1.3, which
+can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.3.zip>`_.

 For Arm system, ARM64 port of the multi-buffer library can be downloaded from
 `<https://gitlab.arm.com/arm-reference-solutions/ipsec-mb/-/tree/main/>`_. The
@@ -83,8 +89,8 @@ and the external crypto libraries supported by them:
    DPDK version   Crypto library version
    =============  ================================
    16.11 - 19.11  LibSSO ZUC
-   20.02 - 21.08  Multi-buffer library 0.53 - 1.2*
-   21.11+         Multi-buffer library 1.0  - 1.2*
+   20.02 - 21.08  Multi-buffer library 0.53 - 1.3*
+   21.11+         Multi-buffer library 1.0  - 1.3*
    =============  ================================

 \* Multi-buffer library 1.0 or newer only works for Meson but not Make build system.
diff --git a/doc/guides/rel_notes/release_22_11.rst b/doc/guides/rel_notes/release_22_11.rst
index 4e55b543ef..3a0a75617e 100644
--- a/doc/guides/rel_notes/release_22_11.rst
+++ b/doc/guides/rel_notes/release_22_11.rst
@@ -240,7 +240,16 @@ New Features

 * **Updated ipsec_mb crypto driver.**

-  Added SNOW-3G and ZUC support for ARM platform.
+  * Added ARM64 port of ipsec-mb library support and SNOW-3G and ZUC
+    support for ARM platform.
+  * Added Intel IPsec MB v1.3 library support for x86 and ARM platform,
+    see the following guides for more details:
+    :doc:`../cryptodevs/aesni_gcm`
+    :doc:`../cryptodevs/aesni_mb`
+    :doc:`../cryptodevs/chacha20_poly1305`
+    :doc:`../cryptodevs/kasumi`
+    :doc:`../cryptodevs/snow3g`
+    :doc:`../cryptodevs/zuc`

 * **Added UADK crypto driver.**

--
2.17.1