Code Review / deb_dpdk.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
Imported Upstream version 16.11
[deb_dpdk.git] / doc / guides / cryptodevs / qat.rst
diff --git a/doc/guides/cryptodevs/qat.rst b/doc/guides/cryptodevs/qat.rst
index cae1958..52a9ae3 100644 (file)
--- a/doc/guides/cryptodevs/qat.rst
+++ b/doc/guides/cryptodevs/qat.rst
@@ -27,11 +27,12 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
     (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
-====================================
+Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver
+==================================================
 
 The QAT PMD provides poll mode crypto driver support for **Intel QuickAssist
 
 The QAT PMD provides poll mode crypto driver support for **Intel QuickAssist
-Technology DH895xxC** hardware accelerator.
+Technology DH895xxC**, **Intel QuickAssist Technology C62x** and
+**Intel QuickAssist Technology C3xxx** hardware accelerator.
 
 
 Features
 
 
 Features
@@ -41,34 +42,43 @@ The QAT PMD has support for:
 
 Cipher algorithms:
 
 
 Cipher algorithms:
 
-* ``RTE_CRYPTO_SYM_CIPHER_AES128_CBC``
-* ``RTE_CRYPTO_SYM_CIPHER_AES192_CBC``
-* ``RTE_CRYPTO_SYM_CIPHER_AES256_CBC``
-* ``RTE_CRYPTO_SYM_CIPHER_AES128_CTR``
-* ``RTE_CRYPTO_SYM_CIPHER_AES192_CTR``
-* ``RTE_CRYPTO_SYM_CIPHER_AES256_CTR``
-* ``RTE_CRYPTO_SYM_CIPHER_SNOW3G_UEA2``
+* ``RTE_CRYPTO_CIPHER_3DES_CBC``
+* ``RTE_CRYPTO_CIPHER_3DES_CTR``
+* ``RTE_CRYPTO_CIPHER_AES128_CBC``
+* ``RTE_CRYPTO_CIPHER_AES192_CBC``
+* ``RTE_CRYPTO_CIPHER_AES256_CBC``
+* ``RTE_CRYPTO_CIPHER_AES128_CTR``
+* ``RTE_CRYPTO_CIPHER_AES192_CTR``
+* ``RTE_CRYPTO_CIPHER_AES256_CTR``
+* ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2``
 * ``RTE_CRYPTO_CIPHER_AES_GCM``
 * ``RTE_CRYPTO_CIPHER_AES_GCM``
+* ``RTE_CRYPTO_CIPHER_NULL``
+* ``RTE_CRYPTO_CIPHER_KASUMI_F8``
 
 Hash algorithms:
 
 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
 
 Hash algorithms:
 
 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
+* ``RTE_CRYPTO_AUTH_SHA224_HMAC``
 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
+* ``RTE_CRYPTO_AUTH_SHA384_HMAC``
 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
 * ``RTE_CRYPTO_AUTH_AES_XCBC_MAC``
 * ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
 * ``RTE_CRYPTO_AUTH_AES_XCBC_MAC``
 * ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
+* ``RTE_CRYPTO_AUTH_MD5_HMAC``
+* ``RTE_CRYPTO_AUTH_NULL``
+* ``RTE_CRYPTO_AUTH_KASUMI_F9``
+* ``RTE_CRYPTO_AUTH_AES_GMAC``
 
 
 Limitations
 -----------
 
 * Chained mbufs are not supported.
 
 
 Limitations
 -----------
 
 * Chained mbufs are not supported.
-* Hash only is not supported except Snow3G UIA2.
-* Cipher only is not supported except Snow3G UEA2.
+* Hash only is not supported except SNOW 3G UIA2 and KASUMI F9.
+* Cipher only is not supported except SNOW 3G UEA2, KASUMI F8 and 3DES.
 * Only supports the session-oriented API implementation (session-less APIs are not supported).
 * Only supports the session-oriented API implementation (session-less APIs are not supported).
-* Not performance tuned.
-* Snow3g(UEA2) supported only if cipher length, cipher offset fields are byte-aligned.
-* Snow3g(UIA2) supported only if hash length, hash offset fields are byte-aligned.
+* SNOW 3G (UEA2) and KASUMI (F8) supported only if cipher length, cipher offset fields are byte-aligned.
+* SNOW 3G (UIA2) and KASUMI (F9) supported only if hash length, hash offset fields are byte-aligned.
 * No BSD support as BSD QAT kernel driver not available.
 
 
 * No BSD support as BSD QAT kernel driver not available.
 
 
@@ -78,14 +88,32 @@ 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.
 
 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.
 
+To enable QAT in DPDK, follow the instructions mentioned in
+http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html
+
+Quick instructions as follows:
+
+.. code-block:: console
+
+       make config T=x86_64-native-linuxapp-gcc
+       sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT\)=n,\1=y,' build/.config
+       make
+
 If you are running on kernel 4.4 or greater, see instructions for
 `Installation using kernel.org driver`_ below. If you are on a kernel earlier
 than 4.4, see `Installation using 01.org QAT driver`_.
 
 If you are running on kernel 4.4 or greater, see instructions for
 `Installation using kernel.org driver`_ below. If you are on a kernel earlier
 than 4.4, see `Installation using 01.org QAT driver`_.
 
+For **Intel QuickAssist Technology C62x** and **Intel QuickAssist Technology C3xxx**
+device, kernel 4.5 or greater is needed.
+See instructions for `Installation using kernel.org driver`_ below.
+
 
 Installation using 01.org QAT driver
 ------------------------------------
 
 
 Installation using 01.org QAT driver
 ------------------------------------
 
+NOTE: There is no driver available for **Intel QuickAssist Technology C62x** and
+**Intel QuickAssist Technology C3xxx** devices on 01.org.
+
 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.
 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.
@@ -162,6 +190,8 @@ If the build or install fails due to mismatching kernel sources you may need to
 Installation using kernel.org driver
 ------------------------------------
 
 Installation using kernel.org driver
 ------------------------------------
 
+For **Intel QuickAssist Technology DH895xxC**:
+
 Assuming you are running on at least a 4.4 kernel, you can use the stock kernel.org QAT
 driver to start the QAT hardware.
 
 Assuming you are running on at least a 4.4 kernel, you can use the stock kernel.org QAT
 driver to start the QAT hardware.
 
@@ -170,7 +200,9 @@ The steps below assume you are:
 * Running DPDK on a platform with one ``DH895xCC`` device.
 * On a kernel at least version 4.4.
 
 * Running DPDK on a platform with one ``DH895xCC`` device.
 * On a kernel at least version 4.4.
 
-In BIOS ensure that SRIOV is enabled and VT-d is disabled.
+In BIOS ensure that SRIOV is enabled and either
+a) disable VT-d or
+b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
 
 Ensure the QAT driver is loaded on your system, by executing::
 
 
 Ensure the QAT driver is loaded on your system, by executing::
 
@@ -181,9 +213,9 @@ You should see the following output::
     qat_dh895xcc            5626  0
     intel_qat              82336  1 qat_dh895xcc
 
     qat_dh895xcc            5626  0
     intel_qat              82336  1 qat_dh895xcc
 
-Next, you need to expose the VFs using the sysfs file system.
+Next, you need to expose the Virtual Functions (VFs) using the sysfs file system.
 
 
-First find the bdf of the DH895xCC device::
+First find the bdf of the physical function (PF) of the DH895xCC device::
 
     lspci -d : 435
 
 
     lspci -d : 435
 
@@ -220,11 +252,99 @@ cd to your linux source root directory and start the qat kernel modules:
 **Note**:The following warning in /var/log/messages can be ignored:
     ``IOMMU should be enabled for SR-IOV to work correctly``
 
 **Note**:The following warning in /var/log/messages can be ignored:
     ``IOMMU should be enabled for SR-IOV to work correctly``
 
+For **Intel QuickAssist Technology C62x**:
+Assuming you are running on at least a 4.5 kernel, you can use the stock kernel.org QAT
+driver to start the QAT hardware.
+
+The steps below assume you are:
+
+* Running DPDK on a platform with one ``C62x`` device.
+* On a kernel at least version 4.5.
+
+In BIOS ensure that SRIOV is enabled and either
+a) disable VT-d or
+b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
+
+Ensure the QAT driver is loaded on your system, by executing::
+
+    lsmod | grep qat
+
+You should see the following output::
+
+    qat_c62x               16384  0
+    intel_qat             122880  1 qat_c62x
+
+Next, you need to expose the VFs using the sysfs file system.
 
 
+First find the bdf of the C62x device::
+
+    lspci -d:37c8
+
+You should see output similar to::
+
+    1a:00.0 Co-processor: Intel Corporation Device 37c8
+    3d:00.0 Co-processor: Intel Corporation Device 37c8
+    3f:00.0 Co-processor: Intel Corporation Device 37c8
+
+For each c62x device there are 3 PFs.
+Using the sysfs, for each PF, enable the 16 VFs::
+
+    echo 16 > /sys/bus/pci/drivers/c6xx/0000\:1a\:00.0/sriov_numvfs
+
+If you get an error, it's likely you're using a QAT kernel driver earlier than kernel 4.5.
+
+To verify that the VFs are available for use - use ``lspci -d:37c9`` to confirm
+the bdf of the 48 VF devices are available per ``C62x`` device.
+
+To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_.
+
+For **Intel QuickAssist Technology C3xxx**:
+Assuming you are running on at least a 4.5 kernel, you can use the stock kernel.org QAT
+driver to start the QAT hardware.
+
+The steps below assume you are:
+
+* Running DPDK on a platform with one ``C3xxx`` device.
+* On a kernel at least version 4.5.
+
+In BIOS ensure that SRIOV is enabled and either
+a) disable VT-d or
+b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
+
+Ensure the QAT driver is loaded on your system, by executing::
+
+    lsmod | grep qat
+
+You should see the following output::
+
+    qat_c3xxx               16384  0
+    intel_qat             122880  1 qat_c3xxx
+
+Next, you need to expose the Virtual Functions (VFs) using the sysfs file system.
+
+First find the bdf of the physical function (PF) of the C3xxx device
+
+    lspci -d:19e2
+
+You should see output similar to::
+
+    01:00.0 Co-processor: Intel Corporation Device 19e2
+
+For c3xxx device there is 1 PFs.
+Using the sysfs, enable the 16 VFs::
+
+    echo 16 > /sys/bus/pci/drivers/c3xxx/0000\:01\:00.0/sriov_numvfs
+
+If you get an error, it's likely you're using a QAT kernel driver earlier than kernel 4.5.
+
+To verify that the VFs are available for use - use ``lspci -d:19e3`` to confirm
+the bdf of the 16 VF devices are available per ``C3xxx`` device.
+To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_.
 
 Binding the available VFs to the DPDK UIO driver
 ------------------------------------------------
 
 
 Binding the available VFs to the DPDK UIO driver
 ------------------------------------------------
 
+For **Intel(R) QuickAssist Technology DH895xcc** device:
 The unbind command below assumes ``bdfs`` of ``03:01.00-03:04.07``, if yours are different adjust the unbind command below::
 
    cd $RTE_SDK
 The unbind command below assumes ``bdfs`` of ``03:01.00-03:04.07``, if yours are different adjust the unbind command below::
 
    cd $RTE_SDK
@@ -241,3 +361,56 @@ The unbind command below assumes ``bdfs`` of ``03:01.00-03:04.07``, if yours are
    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.
    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.
+
+For **Intel(R) QuickAssist Technology C62x** device:
+The unbind command below assumes ``bdfs`` of ``1a:01.00-1a:02.07``, ``3d:01.00-3d:02.07`` and ``3f:01.00-3f:02.07``,
+if yours are different adjust the unbind command below::
+
+   cd $RTE_SDK
+   modprobe uio
+   insmod ./build/kmod/igb_uio.ko
+
+   for device in $(seq 1 2); do \
+       for fn in $(seq 0 7); do \
+           echo -n 0000:1a:0${device}.${fn} > \
+           /sys/bus/pci/devices/0000\:1a\:0${device}.${fn}/driver/unbind; \
+
+           echo -n 0000:3d:0${device}.${fn} > \
+           /sys/bus/pci/devices/0000\:3d\:0${device}.${fn}/driver/unbind; \
+
+           echo -n 0000:3f:0${device}.${fn} > \
+           /sys/bus/pci/devices/0000\:3f\:0${device}.${fn}/driver/unbind; \
+       done; \
+   done
+
+   echo "8086 37c9" > /sys/bus/pci/drivers/igb_uio/new_id
+
+You can use ``lspci -vvd:37c9`` to confirm that all devices are now in use by igb_uio kernel driver.
+
+For **Intel(R) QuickAssist Technology C3xxx** device:
+The unbind command below assumes ``bdfs`` of ``01:01.00-01:02.07``,
+if yours are different adjust the unbind command below::
+
+   cd $RTE_SDK
+   modprobe uio
+   insmod ./build/kmod/igb_uio.ko
+
+   for device in $(seq 1 2); do \
+       for fn in $(seq 0 7); do \
+           echo -n 0000:01:0${device}.${fn} > \
+           /sys/bus/pci/devices/0000\:01\:0${device}.${fn}/driver/unbind; \
+
+       done; \
+   done
+
+   echo "8086 19e3" > /sys/bus/pci/drivers/igb_uio/new_id
+
+You can use ``lspci -vvd:19e3`` to confirm that all devices are now in use by igb_uio kernel driver.
+
+
+The other way to bind the VFs to the DPDK UIO driver is by using the ``dpdk-devbind.py`` script:
+
+.. code-block:: console
+
+    cd $RTE_SDK
+    ./tools/dpdk-devbind.py -b igb_uio 0000:03:01.1
ARCHIVED- 2020-02-20 at the request of the project