diff mbox

[dpdk-dev,v5,4/7] doc: update documentation about ARMv8 crypto PMD

Message ID 1484749650-24867-5-git-send-email-zbigniew.bodek@caviumnetworks.com (mailing list archive)
State Superseded, archived
Delegated to: Pablo de Lara Guarch
Headers show

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel compilation success Compilation OK

Commit Message

zbigniew.bodek@caviumnetworks.com Jan. 18, 2017, 2:27 p.m. UTC
From: Zbigniew Bodek <zbigniew.bodek@caviumnetworks.com>

Add documentation about the driver and update
release notes.

Signed-off-by: Zbigniew Bodek <zbigniew.bodek@caviumnetworks.com>
Reviewed-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
---
 doc/guides/cryptodevs/armv8.rst        | 96 ++++++++++++++++++++++++++++++++++
 doc/guides/cryptodevs/index.rst        |  1 +
 doc/guides/rel_notes/release_17_02.rst |  5 ++
 3 files changed, 102 insertions(+)
 create mode 100644 doc/guides/cryptodevs/armv8.rst

Comments

Pablo de Lara Jan. 18, 2017, 5:05 p.m. UTC | #1
Hi Bodek,

> -----Original Message-----
> From: zbigniew.bodek@caviumnetworks.com
> [mailto:zbigniew.bodek@caviumnetworks.com]
> Sent: Wednesday, January 18, 2017 2:27 PM
> To: dev@dpdk.org
> Cc: De Lara Guarch, Pablo; Doherty, Declan;
> jerin.jacob@caviumnetworks.com; jianbo.liu@linaro.org;
> hemant.agrawal@nxp.com; Zbigniew Bodek
> Subject: [PATCH v5 4/7] doc: update documentation about ARMv8 crypto
> PMD
> 
> From: Zbigniew Bodek <zbigniew.bodek@caviumnetworks.com>
> 
> Add documentation about the driver and update
> release notes.
> 
> Signed-off-by: Zbigniew Bodek <zbigniew.bodek@caviumnetworks.com>
> Reviewed-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> ---
>  doc/guides/cryptodevs/armv8.rst        | 96
> ++++++++++++++++++++++++++++++++++
>  doc/guides/cryptodevs/index.rst        |  1 +
>  doc/guides/rel_notes/release_17_02.rst |  5 ++
>  3 files changed, 102 insertions(+)
>  create mode 100644 doc/guides/cryptodevs/armv8.rst
> 
> diff --git a/doc/guides/cryptodevs/armv8.rst
> b/doc/guides/cryptodevs/armv8.rst
> new file mode 100644
> index 0000000..ca8781e
> --- /dev/null
> +++ b/doc/guides/cryptodevs/armv8.rst

...

> +
> +ARMv8 Crypto Poll Mode Driver
> +================================

Extra "===" here.

> +
> +This code provides the initial implementation of the ARMv8 crypto PMD.
> +The driver uses ARMv8 cryptographic extensions to process chained
> crypto
> +operations in an optimized way. The core functionality is provided by
> +a low-level library, written in the assembly code.
> +
> +Features
> +--------
> +
> +ARMv8 Crypto PMD has support for the following algorithm pairs:
> +
> +Supported cipher algorithms:
> +* ``RTE_CRYPTO_CIPHER_AES_CBC``

Add a blank like before starting a list (same below).

> +
> +Supported authentication algorithms:
> +* ``RTE_CRYPTO_AUTH_SHA1_HMAC``
> +* ``RTE_CRYPTO_AUTH_SHA256_HMAC``
> +

Could you add an entry on the "Crypto Device Supported Functionality Matrices",
to show supported algorithms and feature flags? It is in doc/guides/cryptodevs/overview.rst.

There should be a column per crypto device
(I just realized that I missed one for ZUC PMD, so I will send a patch shortly,
and then you can rebase it on top of it).

The rest of the patchset looks good to me, so once you send another version, I will merge it.

Thanks,
Pablo
zbigniew.bodek@caviumnetworks.com Jan. 18, 2017, 7:52 p.m. UTC | #2
Hello Pablo,

Thanks for the remarks. Please check my answers in-line below.

Kind regards
Zbigniew

On 18.01.2017 18:05, De Lara Guarch, Pablo wrote:
> Hi Bodek,
>
>> -----Original Message-----
>> From: zbigniew.bodek@caviumnetworks.com
>> [mailto:zbigniew.bodek@caviumnetworks.com]
>> Sent: Wednesday, January 18, 2017 2:27 PM
>> To: dev@dpdk.org
>> Cc: De Lara Guarch, Pablo; Doherty, Declan;
>> jerin.jacob@caviumnetworks.com; jianbo.liu@linaro.org;
>> hemant.agrawal@nxp.com; Zbigniew Bodek
>> Subject: [PATCH v5 4/7] doc: update documentation about ARMv8 crypto
>> PMD
>>
>> From: Zbigniew Bodek <zbigniew.bodek@caviumnetworks.com>
>>
>> Add documentation about the driver and update
>> release notes.
>>
>> Signed-off-by: Zbigniew Bodek <zbigniew.bodek@caviumnetworks.com>
>> Reviewed-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>> ---
>>  doc/guides/cryptodevs/armv8.rst        | 96
>> ++++++++++++++++++++++++++++++++++
>>  doc/guides/cryptodevs/index.rst        |  1 +
>>  doc/guides/rel_notes/release_17_02.rst |  5 ++
>>  3 files changed, 102 insertions(+)
>>  create mode 100644 doc/guides/cryptodevs/armv8.rst
>>
>> diff --git a/doc/guides/cryptodevs/armv8.rst
>> b/doc/guides/cryptodevs/armv8.rst
>> new file mode 100644
>> index 0000000..ca8781e
>> --- /dev/null
>> +++ b/doc/guides/cryptodevs/armv8.rst
>
> ...
>
>> +
>> +ARMv8 Crypto Poll Mode Driver
>> +================================
>
> Extra "===" here.

Fixed in the upcoming patchset.

>
>> +
>> +This code provides the initial implementation of the ARMv8 crypto PMD.
>> +The driver uses ARMv8 cryptographic extensions to process chained
>> crypto
>> +operations in an optimized way. The core functionality is provided by
>> +a low-level library, written in the assembly code.
>> +
>> +Features
>> +--------
>> +
>> +ARMv8 Crypto PMD has support for the following algorithm pairs:
>> +
>> +Supported cipher algorithms:
>> +* ``RTE_CRYPTO_CIPHER_AES_CBC``
>
> Add a blank like before starting a list (same below).

Also fixed.

>
>> +
>> +Supported authentication algorithms:
>> +* ``RTE_CRYPTO_AUTH_SHA1_HMAC``
>> +* ``RTE_CRYPTO_AUTH_SHA256_HMAC``
>> +
>
> Could you add an entry on the "Crypto Device Supported Functionality Matrices",
> to show supported algorithms and feature flags? It is in doc/guides/cryptodevs/overview.rst.

Yes, looking at that file I realized that we also could add "crypto 
device supported feature flags" for ARM. I created another commit in the 
patchset (preceding the one with the documentation update for PMD).
The method of adding this flags is similar to what has been done earlier 
for other PMDs and their features.
I used two names:
* NEON - which is an ARM component so we can use this name as a unique name.
* ARM_CE - for ARM cryptographic extensions. AFAIK there is no other 
name for that.

>
> There should be a column per crypto device
> (I just realized that I missed one for ZUC PMD, so I will send a patch shortly,
> and then you can rebase it on top of it).

Done with the new flags mentioned above as well. I'm sending another 
patchset now and if you have some remarks to the new commits then let's 
do another round :-).

>
> The rest of the patchset looks good to me, so once you send another version, I will merge it.
>
> Thanks,
> Pablo
>
Pablo de Lara Jan. 18, 2017, 7:54 p.m. UTC | #3
Hi Zbigniew,

> -----Original Message-----
> From: Zbigniew Bodek [mailto:zbigniew.bodek@caviumnetworks.com]
> Sent: Wednesday, January 18, 2017 7:52 PM
> To: De Lara Guarch, Pablo; dev@dpdk.org
> Cc: Doherty, Declan; jerin.jacob@caviumnetworks.com;
> jianbo.liu@linaro.org; hemant.agrawal@nxp.com
> Subject: Re: [PATCH v5 4/7] doc: update documentation about ARMv8
> crypto PMD
> 
> Hello Pablo,
> 
> Thanks for the remarks. Please check my answers in-line below.
> 
> Kind regards
> Zbigniew
> 
> On 18.01.2017 18:05, De Lara Guarch, Pablo wrote:
> > Hi Bodek,
> >
> >> -----Original Message-----
> >> From: zbigniew.bodek@caviumnetworks.com
> >> [mailto:zbigniew.bodek@caviumnetworks.com]
> >> Sent: Wednesday, January 18, 2017 2:27 PM
> >> To: dev@dpdk.org
> >> Cc: De Lara Guarch, Pablo; Doherty, Declan;
> >> jerin.jacob@caviumnetworks.com; jianbo.liu@linaro.org;
> >> hemant.agrawal@nxp.com; Zbigniew Bodek
> >> Subject: [PATCH v5 4/7] doc: update documentation about ARMv8
> crypto
> >> PMD
> >>
> >> From: Zbigniew Bodek <zbigniew.bodek@caviumnetworks.com>
> >>
> >> Add documentation about the driver and update
> >> release notes.
> >>
> >> Signed-off-by: Zbigniew Bodek <zbigniew.bodek@caviumnetworks.com>
> >> Reviewed-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> >> ---
> >>  doc/guides/cryptodevs/armv8.rst        | 96
> >> ++++++++++++++++++++++++++++++++++
> >>  doc/guides/cryptodevs/index.rst        |  1 +
> >>  doc/guides/rel_notes/release_17_02.rst |  5 ++
> >>  3 files changed, 102 insertions(+)
> >>  create mode 100644 doc/guides/cryptodevs/armv8.rst
> >>
> >> diff --git a/doc/guides/cryptodevs/armv8.rst
> >> b/doc/guides/cryptodevs/armv8.rst
> >> new file mode 100644
> >> index 0000000..ca8781e
> >> --- /dev/null
> >> +++ b/doc/guides/cryptodevs/armv8.rst
> >
> > ...
> >
> >> +
> >> +ARMv8 Crypto Poll Mode Driver
> >> +================================
> >
> > Extra "===" here.
> 
> Fixed in the upcoming patchset.
> 
> >
> >> +
> >> +This code provides the initial implementation of the ARMv8 crypto
> PMD.
> >> +The driver uses ARMv8 cryptographic extensions to process chained
> >> crypto
> >> +operations in an optimized way. The core functionality is provided by
> >> +a low-level library, written in the assembly code.
> >> +
> >> +Features
> >> +--------
> >> +
> >> +ARMv8 Crypto PMD has support for the following algorithm pairs:
> >> +
> >> +Supported cipher algorithms:
> >> +* ``RTE_CRYPTO_CIPHER_AES_CBC``
> >
> > Add a blank like before starting a list (same below).
> 
> Also fixed.
> 
> >
> >> +
> >> +Supported authentication algorithms:
> >> +* ``RTE_CRYPTO_AUTH_SHA1_HMAC``
> >> +* ``RTE_CRYPTO_AUTH_SHA256_HMAC``
> >> +
> >
> > Could you add an entry on the "Crypto Device Supported Functionality
> Matrices",
> > to show supported algorithms and feature flags? It is in
> doc/guides/cryptodevs/overview.rst.
> 
> Yes, looking at that file I realized that we also could add "crypto
> device supported feature flags" for ARM. I created another commit in the
> patchset (preceding the one with the documentation update for PMD).
> The method of adding this flags is similar to what has been done earlier
> for other PMDs and their features.
> I used two names:
> * NEON - which is an ARM component so we can use this name as a unique
> name.
> * ARM_CE - for ARM cryptographic extensions. AFAIK there is no other
> name for that.

Looks good to me.
> 
> >
> > There should be a column per crypto device
> > (I just realized that I missed one for ZUC PMD, so I will send a patch
> shortly,
> > and then you can rebase it on top of it).
> 
> Done with the new flags mentioned above as well. I'm sending another
> patchset now and if you have some remarks to the new commits then let's
> do another round :-).

Thanks!

Pablo

> 
> >
> > The rest of the patchset looks good to me, so once you send another
> version, I will merge it.
> >
> > Thanks,
> > Pablo
> >
diff mbox

Patch

diff --git a/doc/guides/cryptodevs/armv8.rst b/doc/guides/cryptodevs/armv8.rst
new file mode 100644
index 0000000..ca8781e
--- /dev/null
+++ b/doc/guides/cryptodevs/armv8.rst
@@ -0,0 +1,96 @@ 
+..  BSD LICENSE
+    Copyright (C) Cavium networks Ltd. 2017.
+
+    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 Cavium networks 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.
+
+
+ARMv8 Crypto Poll Mode Driver
+================================
+
+This code provides the initial implementation of the ARMv8 crypto PMD.
+The driver uses ARMv8 cryptographic extensions to process chained crypto
+operations in an optimized way. The core functionality is provided by
+a low-level library, written in the assembly code.
+
+Features
+--------
+
+ARMv8 Crypto PMD has support for the following algorithm pairs:
+
+Supported cipher algorithms:
+* ``RTE_CRYPTO_CIPHER_AES_CBC``
+
+Supported authentication algorithms:
+* ``RTE_CRYPTO_AUTH_SHA1_HMAC``
+* ``RTE_CRYPTO_AUTH_SHA256_HMAC``
+
+Installation
+------------
+
+In order to enable this virtual crypto PMD, user must:
+
+* Download ARMv8 crypto library source code from
+  `here <https://github.com/caviumnetworks/armv8_crypto>`_
+
+* Export the environmental variable ARMV8_CRYPTO_LIB_PATH with
+  the path where the ``armv8_crypto`` library was downloaded
+  or cloned.
+
+* Build the library by invoking:
+
+.. code-block:: console
+
+	make -C $ARMV8_CRYPTO_LIB_PATH/
+
+* Set CONFIG_RTE_LIBRTE_PMD_ARMV8_CRYPTO=y in
+  config/defconfig_arm64-armv8a-linuxapp-gcc
+
+The corresponding device can be created only if the following features
+are supported by the CPU:
+
+* ``RTE_CPUFLAG_AES``
+* ``RTE_CPUFLAG_SHA1``
+* ``RTE_CPUFLAG_SHA2``
+* ``RTE_CPUFLAG_NEON``
+
+Initialization
+--------------
+
+User can use app/test application to check how to use this PMD and to verify
+crypto processing.
+
+Test name is cryptodev_sw_armv8_autotest.
+For performance test cryptodev_sw_armv8_perftest can be used.
+
+Limitations
+-----------
+
+* Maximum number of sessions is 2048.
+* Only chained operations are supported.
+* AES-128-CBC is the only supported cipher variant.
+* Cipher input data has to be a multiple of 16 bytes.
+* Digest input data has to be a multiple of 8 bytes.
diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst
index a6a9f23..06c3f6e 100644
--- a/doc/guides/cryptodevs/index.rst
+++ b/doc/guides/cryptodevs/index.rst
@@ -38,6 +38,7 @@  Crypto Device Drivers
     overview
     aesni_mb
     aesni_gcm
+    armv8
     kasumi
     openssl
     null
diff --git a/doc/guides/rel_notes/release_17_02.rst b/doc/guides/rel_notes/release_17_02.rst
index d59e386..e9c6c00 100644
--- a/doc/guides/rel_notes/release_17_02.rst
+++ b/doc/guides/rel_notes/release_17_02.rst
@@ -111,6 +111,11 @@  New Features
 
   * Support for single operations (cipher only and authentication only).
 
+* **Added armv8 crypto PMD.**
+
+  A new crypto PMD has been added, which provides combined mode cryptografic
+  operations optimized for ARMv8 processors. The driver can be used to enhance
+  performance in processing chained operations such as cipher + HMAC.
 
 Resolved Issues
 ---------------