From mboxrd@z Thu Jan 1 00:00:00 1970 From: Declan Doherty Subject: [PATCH 4/6] docs: add getting started guides for multi-buffer pmd and qat pmd Date: Sat, 3 Oct 2015 00:01:05 +0100 Message-ID: <1443826867-21004-5-git-send-email-declan.doherty@intel.com> References: <1443826867-21004-1-git-send-email-declan.doherty@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable To: dev@dpdk.org Return-path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 8F4E58E85 for ; Sat, 3 Oct 2015 00:54:23 +0200 (CEST) In-Reply-To: <1443826867-21004-1-git-send-email-declan.doherty@intel.com> List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Signed-off-by: Declan Doherty --- doc/guides/cryptodevs/aesni_mb.rst | 76 ++++++++++++++++++ doc/guides/cryptodevs/index.rst | 43 ++++++++++ doc/guides/cryptodevs/qat.rst | 155 +++++++++++++++++++++++++++++++= ++++++ doc/guides/index.rst | 1 + 4 files changed, 275 insertions(+) create mode 100644 doc/guides/cryptodevs/aesni_mb.rst create mode 100644 doc/guides/cryptodevs/index.rst create mode 100644 doc/guides/cryptodevs/qat.rst diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/a= esni_mb.rst new file mode 100644 index 0000000..826b632 --- /dev/null +++ b/doc/guides/cryptodevs/aesni_mb.rst @@ -0,0 +1,76 @@ +.. BSD LICENSE + Copyright(c) 2015 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 FO= R + 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 AN= Y + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +AESN-NI Multi Buffer Crytpo Poll Mode Driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + +The AESNI MB PMD (**librte_pmd_aesni_mb**) provides poll mode crypto dri= ver +support for utilising Intel multi buffer library, see the white paper +`Fast Multi-buffer IPsec Implementations on Intel=C2=AE Architecture Pro= cessors +`_. + +The AES-NI MB PMD has current only been tested on Fedora 21 64-bit with = gcc. + +Features +-------- + +AESNI MB PMD has support for: + +Cipher algorithms: + +* RTE_CRYPTO_SYM_CIPHER_AES128_CBC +* RTE_CRYPTO_SYM_CIPHER_AES256_CBC +* RTE_CRYPTO_SYM_CIPHER_AES512_CBC + +Hash algorithms: + +* RTE_CRYPTO_SYM_HASH_SHA1_HMAC +* RTE_CRYPTO_SYM_HASH_SHA256_HMAC +* RTE_CRYPTO_SYM_HASH_SHA512_HMAC + +Limitations +----------- + +* Chained mbufs are not supported. +* Hash only is not supported. +* Cipher only is not supported. +* Only in-place is currently supported (destination address is the same = as source address). +* Only supports session-oriented API implementation (session-less APIs a= re not supported). +* Not performance tuned. + +Installation +------------ + +To build DPKD with the AESNI_MB_PMD the user is required to download the= library +from `here `_ and compi= le it on +their user system before building DPDK. The environmental variable +AESNI_MULTI_BUFFER_LIB_PATH must be exported with the path where you ext= racted +and built the multi buffer library and finally set +CONFIG_RTE_LIBRTE_PMD_AESNI_MB=3Dy in config/common_linuxapp. diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/inde= x.rst new file mode 100644 index 0000000..8949fd0 --- /dev/null +++ b/doc/guides/cryptodevs/index.rst @@ -0,0 +1,43 @@ +.. BSD LICENSE + Copyright(c) 2015 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 FO= R + 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 AN= Y + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Crypto Device Drivers +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +|today| + + +**Contents** + +.. toctree:: + :maxdepth: 2 + :numbered: + + aesni_mb + qat diff --git a/doc/guides/cryptodevs/qat.rst b/doc/guides/cryptodevs/qat.rs= t new file mode 100644 index 0000000..c5c7b2b --- /dev/null +++ b/doc/guides/cryptodevs/qat.rst @@ -0,0 +1,155 @@ +.. BSD LICENSE + Copyright(c) 2015 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 FO= R + 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 AN= Y + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Quick Assist Crypto Poll Mode Driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + +The QAT PMD provides poll mode crypto driver support for **Intel +QuickAssist Technology DH895xxC hardware accelerator. QAT PMD has +current only been tested on Fedora 21 64-bit with gcc. + +Features +-------- + +QAT PMD has support for: + +Cipher algorithms: + +* RTE_CRYPTO_SYM_CIPHER_AES128_CBC +* RTE_CRYPTO_SYM_CIPHER_AES256_CBC +* RTE_CRYPTO_SYM_CIPHER_AES512_CBC + +Hash algorithms: + +* RTE_CRYPTO_SYM_HASH_SHA1_HMAC +* RTE_CRYPTO_SYM_HASH_SHA256_HMAC +* RTE_CRYPTO_SYM_HASH_SHA512_HMAC + +Limitations +----------- + +* Chained mbufs are not supported. +* Hash only is not supported. +* Cipher only is not supported. +* Only in-place is currently supported (destination address is the same = as source address). +* Only supports session-oriented API implementation (session-less APIs a= re not supported). +* Not performance tuned. + +Installation +------------ + +To use the DPDK QAT PMD an SRIOV-enabled QAT kernel driver is required. +The VF devices exposed by this driver will be used by QAT PMD +Future kernel versions will provide this as standard, in the interim the +following steps are necessary to load this driver. + + +Download the latest QuickAssist Technology Driver from 01.org +https://01.org/packet-processing/intel%C2%AE-quickassist-technology-driv= ers-and-patches +Consult the Getting Started Guide at the same URL for further informatio= n. + +Steps below assume + * building on a platform with one DH895xCC device + * using package qatmux.l.2.3.0-34.tgz + * on Fedora21 kernel 3.17.4-301.fc21.x86_64 + +In BIOS ensure that SRIOV is enabled and VT-d is disabled. + +Uninstall any existing QAT driver, e.g. by running + * "./installer.sh uninstall" in the directory where originally instal= led + or + * "rmmod qat_dh895xcc; rmmod intel_qat" + +Build and install the SRIOV-enabled QAT driver + +.. code-block:: console + + "mkdir /QAT; cd /QAT" + copy qatmux.l.2.3.0-34.tgz to this location + "tar zxof qatmux.l.2.3.0-34.tgz" + "export ICP_WITHOUT_IOMMU=3D1" + "./installer.sh install QAT1.6 host" + +You can use "cat /proc/icp_dh895xcc_dev0/version" to confirm the driver = is correctly installed. +You can use "lspci -d:443" to confirm the bdf of the 32 VF devices avail= able per DH895xCC device. + +The unbind command below assumes bdfs of 02:01.00-02:04.07, if yours are= different adjust the unbind command below. + +Make available to DPDK + +.. code-block:: console + + cd $(RTE_SDK) (See http://dpdk.org/doc/quick-start to install DPDK) + "modprobe uio" + "insmod ./build/kmod/igb_uio.ko" + "for device in $(seq 1 4); do for fn in $(seq 0 7); do echo -n 0000:0= 2:0${device}.${fn} > /sys/bus/pci/devices/0000\:02\:0${device}.${fn}/driv= er/unbind;done ;done" + "echo "8086 0443" > /sys/bus/pci/drivers/igb_uio/new_id" + +You can use "lspci -vvd:443" to confirm that all devices are now in use = by igb_uio kernel driver + + +Notes: +If using a later kernel and the build fails with an error relating to st= rict_stroul not being available patch the following file: + +.. code-block:: console + + /QAT/QAT1.6/quickassist/utilities/downloader/Target_CoreLibs/uclo/incl= ude/linux/uclo_platform.h + + #if LINUX_VERSION_CODE >=3D KERNEL_VERSION(3,18,5) + + #define STR_TO_64(str, base, num, endPtr) {endPtr=3DNULL; if (kstrto= ul((str), (base), (num))) printk("Error strtoull convert %s\n", str); } + + #else + #if LINUX_VERSION_CODE >=3D KERNEL_VERSION(2,6,38) + #define STR_TO_64(str, base, num, endPtr) {endPtr=3DNULL; if (strict_s= trtoull((str), (base), (num))) printk("Error strtoull convert %s\n", str)= ; } + #else + #if LINUX_VERSION_CODE >=3D KERNEL_VERSION(2,6,25) + #define STR_TO_64(str, base, num, endPtr) {endPtr=3DNULL; strict_strto= ll((str), (base), (num));} + #else + #define STR_TO_64(str, base, num, endPtr) = \ + do { = \ + if (str[0] =3D=3D '-') = \ + { = \ + *(num) =3D -(simple_strtoull((str+1), &(endPtr), (base= ))); \ + }else { = \ + *(num) =3D simple_strtoull((str), &(endPtr), (base)); = \ + } = \ + } while(0) + + #endif + #endif + #endif + + +If build fails due to missing header files you may need to do following: + * sudo yum install zlib-devel + * sudo yum install openssl-devel + +If build or install fails due to mismatching kernel sources you may need= to do the following: + * sudo yum install kernel-headers-`uname -r` + * sudo yum install kernel-src-`uname -r` + * sudo yum install kernel-devel-`uname -r` + diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 439c7e3..c5d7a9f 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -42,6 +42,7 @@ Contents: xen/index prog_guide/index nics/index + cryptodevs/index sample_app_ug/index testpmd_app_ug/index faq/index --=20 2.4.3