From mboxrd@z Thu Jan 1 00:00:00 1970 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) Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga103.jf.intel.com with ESMTP; 02 Oct 2015 15:54:23 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.17,625,1437462000"; d="scan'208";a="783186105" Received: from unknown (HELO dwdohert-dpdk-fedora-20.ir.intel.com) ([163.33.213.96]) by orsmga001.jf.intel.com with ESMTP; 02 Oct 2015 15:54:22 -0700 From: Declan Doherty To: dev@dpdk.org Date: Sat, 3 Oct 2015 00:01:05 +0100 Message-Id: <1443826867-21004-5-git-send-email-declan.doherty@intel.com> X-Mailer: git-send-email 2.4.3 In-Reply-To: <1443826867-21004-1-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: 8bit Subject: [dpdk-dev] [PATCH 4/6] docs: add getting started guides for multi-buffer pmd and qat pmd X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 02 Oct 2015 22:54:24 -0000 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/aesni_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 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. + +AESN-NI Multi Buffer Crytpo Poll Mode Driver +============================================ + + +The AESNI MB PMD (**librte_pmd_aesni_mb**) provides poll mode crypto driver +support for utilising Intel multi buffer library, see the white paper +`Fast Multi-buffer IPsec Implementations on Intel® Architecture Processors +`_. + +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 are 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 compile it on +their user system before building DPDK. The environmental variable +AESNI_MULTI_BUFFER_LIB_PATH must be exported with the path where you extracted +and built the multi buffer library and finally set +CONFIG_RTE_LIBRTE_PMD_AESNI_MB=y in config/common_linuxapp. diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.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 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. + +Crypto Device Drivers +==================================== + +|today| + + +**Contents** + +.. toctree:: + :maxdepth: 2 + :numbered: + + aesni_mb + qat diff --git a/doc/guides/cryptodevs/qat.rst b/doc/guides/cryptodevs/qat.rst 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 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. + +Quick Assist Crypto Poll Mode Driver +==================================== + + +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 are 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-drivers-and-patches +Consult the Getting Started Guide at the same URL for further information. + +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 installed + 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=1" + "./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 available 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:02:0${device}.${fn} > /sys/bus/pci/devices/0000\:02\:0${device}.${fn}/driver/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 strict_stroul not being available patch the following file: + +.. code-block:: console + + /QAT/QAT1.6/quickassist/utilities/downloader/Target_CoreLibs/uclo/include/linux/uclo_platform.h + + #if LINUX_VERSION_CODE >= KERNEL_VERSION(3,18,5) + + #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (kstrtoul((str), (base), (num))) printk("Error strtoull convert %s\n", str); } + + #else + #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,38) + #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (strict_strtoull((str), (base), (num))) printk("Error strtoull convert %s\n", str); } + #else + #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,25) + #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; strict_strtoll((str), (base), (num));} + #else + #define STR_TO_64(str, base, num, endPtr) \ + do { \ + if (str[0] == '-') \ + { \ + *(num) = -(simple_strtoull((str+1), &(endPtr), (base))); \ + }else { \ + *(num) = 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 -- 2.4.3