Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/43642/?format=api
{ "id": 43642, "url": "http://patches.dpdk.org/api/patches/43642/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/1533820674-9507-1-git-send-email-fiona.trahe@intel.com/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<1533820674-9507-1-git-send-email-fiona.trahe@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/1533820674-9507-1-git-send-email-fiona.trahe@intel.com", "date": "2018-08-09T13:17:54", "name": "doc/qat: clarify build config options", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "919a54620dbfa6595921a061076c0548b69a968b", "submitter": { "id": 423, "url": "http://patches.dpdk.org/api/people/423/?format=api", "name": "Fiona Trahe", "email": "fiona.trahe@intel.com" }, "delegate": null, "mbox": "http://patches.dpdk.org/project/dpdk/patch/1533820674-9507-1-git-send-email-fiona.trahe@intel.com/mbox/", "series": [ { "id": 947, "url": "http://patches.dpdk.org/api/series/947/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=947", "date": "2018-08-09T13:17:54", "name": "doc/qat: clarify build config options", "version": 1, "mbox": "http://patches.dpdk.org/series/947/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/43642/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/43642/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@dpdk.org", "Delivered-To": "patchwork@dpdk.org", "Received": [ "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id 212E02661;\n\tThu, 9 Aug 2018 15:18:09 +0200 (CEST)", "from mga09.intel.com (mga09.intel.com [134.134.136.24])\n\tby dpdk.org (Postfix) with ESMTP id 7708BFEB\n\tfor <dev@dpdk.org>; Thu, 9 Aug 2018 15:18:07 +0200 (CEST)", "from orsmga005.jf.intel.com ([10.7.209.41])\n\tby orsmga102.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;\n\t09 Aug 2018 06:18:06 -0700", "from sivswdev01.ir.intel.com (HELO localhost.localdomain)\n\t([10.237.217.45])\n\tby orsmga005.jf.intel.com with ESMTP; 09 Aug 2018 06:18:04 -0700" ], "X-Amp-Result": "SKIPPED(no attachment in message)", "X-Amp-File-Uploaded": "False", "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.53,215,1531810800\"; d=\"scan'208\";a=\"247471760\"", "From": "Fiona Trahe <fiona.trahe@intel.com>", "To": "dev@dpdk.org, pablo.de.lara.guarch@intel.com, tomaszx.jozwiak@intel.com", "Cc": "fiona.trahe@intel.com", "Date": "Thu, 9 Aug 2018 14:17:54 +0100", "Message-Id": "<1533820674-9507-1-git-send-email-fiona.trahe@intel.com>", "X-Mailer": "git-send-email 1.7.0.7", "Subject": "[dpdk-dev] [PATCH] doc/qat: clarify build config options", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n\t<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>,\n\t<mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Clarified documentation structure between\ncompressedev, cryptodev and common build parts.\nClarified build configuration options.\nAdded Testing section.\nFixed typos and made some cosmetic improvements.\n\nSigned-off-by: Fiona Trahe <fiona.trahe@intel.com>\n---\n doc/guides/compressdevs/qat_comp.rst | 6 +-\n doc/guides/cryptodevs/qat.rst | 194 ++++++++++++++++++++++++-----------\n 2 files changed, 138 insertions(+), 62 deletions(-)", "diff": "diff --git a/doc/guides/compressdevs/qat_comp.rst b/doc/guides/compressdevs/qat_comp.rst\nindex 8b1270b70..7bffbe6ff 100644\n--- a/doc/guides/compressdevs/qat_comp.rst\n+++ b/doc/guides/compressdevs/qat_comp.rst\n@@ -36,12 +36,14 @@ Limitations\n -----------\n \n * Compressdev level 0, no compression, is not supported.\n-\n * Dynamic Huffman encoding is not yet supported.\n+* Queue pairs are not thread-safe (that is, within a single queue pair, RX and TX from different lcores is not supported).\n+* No BSD support as BSD QAT kernel driver not available.\n+\n \n Installation\n ------------\n \n The QAT compression PMD is built by default with a standard DPDK build.\n \n-It depends on a QAT kernel driver, see :ref:`qat_kernel_installation`.\n+It depends on a QAT kernel driver, see :ref:`building_qat`.\ndiff --git a/doc/guides/cryptodevs/qat.rst b/doc/guides/cryptodevs/qat.rst\nindex bdc58eb2c..7b5929681 100644\n--- a/doc/guides/cryptodevs/qat.rst\n+++ b/doc/guides/cryptodevs/qat.rst\n@@ -2,9 +2,21 @@\n Copyright(c) 2015-2016 Intel Corporation.\n \n Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver\n-==================================================\n+===================================================\n \n-The QAT PMD provides poll mode crypto driver support for the following\n+QAT documentation consists of three parts:\n+\n+* Details of the symmetric crypto service below.\n+* Details of the `compression service <http://dpdk.org/doc/guides/compressdevs/qat_comp.html>`_\n+ in the compressdev drivers section.\n+* Details of building the common QAT infrastructure and the PMDs to support the\n+ above services. See :ref:`building_qat` below.\n+\n+\n+Symmetric Crypto Service on QAT\n+--------------------------------------------------\n+\n+The QAT crypto PMD provides poll mode crypto driver support for the following\n hardware accelerator devices:\n \n * ``Intel QuickAssist Technology DH895xCC``\n@@ -14,7 +26,7 @@ hardware accelerator devices:\n \n \n Features\n---------\n+~~~~~~~~\n \n The QAT PMD has support for:\n \n@@ -57,7 +69,7 @@ Supported AEAD algorithms:\n \n \n Limitations\n------------\n+~~~~~~~~~~~~~\n \n * Only supports the session-oriented API implementation (session-less APIs are not supported).\n * SNOW 3G (UEA2), KASUMI (F8) and ZUC (EEA3) supported only if cipher length and offset fields are byte-multiple.\n@@ -69,104 +81,148 @@ Limitations\n \n \n Extra notes on KASUMI F9\n-------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~\n \n When using KASUMI F9 authentication algorithm, the input buffer must be\n-constructed according to the 3GPP KASUMI specifications (section 4.4, page 13):\n-`<http://cryptome.org/3gpp/35201-900.pdf>`_.\n-Input buffer has to have COUNT (4 bytes), FRESH (4 bytes), MESSAGE and DIRECTION (1 bit)\n-concatenated. After the DIRECTION bit, a single '1' bit is appended, followed by\n-between 0 and 7 '0' bits, so that the total length of the buffer is multiple of 8 bits.\n-Note that the actual message can be any length, specified in bits.\n+constructed according to the\n+`3GPP KASUMI specification <http://cryptome.org/3gpp/35201-900.pdf>`_\n+(section 4.4, page 13). The input buffer has to have COUNT (4 bytes),\n+FRESH (4 bytes), MESSAGE and DIRECTION (1 bit) concatenated. After the DIRECTION\n+bit, a single '1' bit is appended, followed by between 0 and 7 '0' bits, so that\n+the total length of the buffer is multiple of 8 bits. Note that the actual\n+message can be any length, specified in bits.\n \n Once this buffer is passed this way, when creating the crypto operation,\n-length of data to authenticate (op.sym.auth.data.length) must be the length\n+length of data to authenticate \"op.sym.auth.data.length\" must be the length\n of all the items described above, including the padding at the end.\n-Also, offset of data to authenticate (op.sym.auth.data.offset)\n+Also, offset of data to authenticate \"op.sym.auth.data.offset\"\n must be such that points at the start of the COUNT bytes.\n \n \n-Building the DPDK QAT cryptodev PMD\n------------------------------------\n \n+.. _building_qat:\n+\n+Building PMDs on QAT\n+----------------------------------\n+\n+A QAT device can host multiple acceleration services:\n+\n+* symmetric cryptography\n+* data compression\n \n-To enable QAT crypto in DPDK, follow the instructions for modifying the compile-time\n-configuration file as described `here <http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html>`_.\n+These services are provided to DPDK applications via PMDs which register to\n+implement the corresponding cryptodev and compressdev APIs. The PMDs use\n+common QAT driver code which manages the QAT PCI device. They also depend on a\n+QAT kernel driver being installed on the platform, see :ref:`qat_kernel` below.\n \n \n-Quick instructions are as follows:\n+Configuring and Building the DPDK QAT PMDs\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+\n+Further information on configuring, building and installing DPDK is described\n+`here <http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html>`_.\n+\n+\n+Quick instructions for QAT cryptodev PMD are as follows:\n \n .. code-block:: console\n \n \tcd to the top-level DPDK directory\n \tmake config T=x86_64-native-linuxapp-gcc\n-\tsed -i 's,\\(CONFIG_RTE_LIBRTE_PMD_QAT\\)=n,\\1=y,' build/.config\n \tsed -i 's,\\(CONFIG_RTE_LIBRTE_PMD_QAT_SYM\\)=n,\\1=y,' build/.config\n \tmake\n \n+Quick instructions for QAT compressdev PMD are as follows:\n \n-.. _qat_kernel_installation:\n+.. code-block:: console\n \n-Dependency on the QAT kernel driver\n------------------------------------\n+\tcd to the top-level DPDK directory\n+\tmake config T=x86_64-native-linuxapp-gcc\n+\tmake\n \n-To use the QAT PMD an SRIOV-enabled QAT kernel driver is required. The VF\n-devices created and initialised by this driver will be used by the QAT PMD.\n+Build Configuration\n+~~~~~~~~~~~~~~~~~~~~\n \n-Instructions for installation are below, but first an explanation of the\n-relationships between the PF/VF devices and the PMDs visible to\n-DPDK applications.\n+These are the build configuration options affecting QAT, and their default values:\n \n+.. code-block:: console\n \n-Acceleration services - cryptography and compression - are provided to DPDK\n-applications via PMDs which register to implement the corresponding\n-cryptodev and compressdev APIs.\n+\tCONFIG_RTE_LIBRTE_PMD_QAT=y\n+\tCONFIG_RTE_LIBRTE_PMD_QAT_SYM=n\n+\tCONFIG_RTE_PMD_QAT_MAX_PCI_DEVICES=48\n+\tCONFIG_RTE_PMD_QAT_COMP_SGL_MAX_SEGMENTS=16\n \n-Each QuickAssist VF device can expose one cryptodev PMD and/or one compressdev PMD.\n-These QAT PMDs share the same underlying device and pci-mgmt code, but are\n-enumerated independently on their respective APIs and appear as independent\n-devices to applications.\n+CONFIG_RTE_LIBRTE_PMD_QAT must be enabled for any QAT PMD to be built.\n \n-.. Note::\n+The QAT cryptodev PMD has an external dependency on libcrypto, so is not\n+built by default. CONFIG_RTE_LIBRTE_PMD_QAT_SYM should be enabled to build it.\n \n- Each VF can only be used by one DPDK process. It is not possible to share\n- the same VF across multiple processes, even if these processes are using\n- different acceleration services.\n+The QAT compressdev PMD has no external dependencies, so needs no configuration\n+options and is built by default.\n \n- Conversely one DPDK process can use one or more QAT VFs and can expose both\n- cryptodev and compressdev instances on each of those VFs.\n+The number of VFs per PF varies - see table below. If multiple QAT packages are\n+installed on a platform then CONFIG_RTE_PMD_QAT_MAX_PCI_DEVICES should be\n+adjusted to the number of VFs which the QAT common code will need to handle.\n+Note, there is a separate config item for max cryptodevs CONFIG_RTE_CRYPTO_MAX_DEVS,\n+if necessary this should be adjusted to handle the total of QAT and other devices\n+which the process will use.\n \n+QAT allocates internal structures to handle SGLs. For the compression service\n+CONFIG_RTE_PMD_QAT_COMP_SGL_MAX_SEGMENTS can be changed if more segments are needed.\n+An extra (max_inflight_ops x 16) bytes per queue_pair will be used for every increment.\n \n \n Device and driver naming\n-------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n * The qat cryptodev driver name is \"crypto_qat\".\n- The rte_cryptodev_devices_get() returns the devices exposed by this driver.\n+ The \"rte_cryptodev_devices_get()\" returns the devices exposed by this driver.\n \n * Each qat crypto device has a unique name, in format\n- <pci bdf>_<service>, e.g. \"0000:41:01.0_qat_sym\".\n- This name can be passed to rte_cryptodev_get_dev_id() to get the device_id.\n+ \"<pci bdf>_<service>\", e.g. \"0000:41:01.0_qat_sym\".\n+ This name can be passed to \"rte_cryptodev_get_dev_id()\" to get the device_id.\n \n .. Note::\n \n-\tThe qat crypto driver name is passed to the dpdk-test-crypto-perf tool in the -devtype parameter.\n+\tThe qat crypto driver name is passed to the dpdk-test-crypto-perf tool in the \"-devtype\" parameter.\n \n \tThe qat crypto device name is in the format of the slave parameter passed to the crypto scheduler.\n \n-* The qat compressdev driver name is \"comp_qat\".\n- The rte_compressdev_devices_get() returns the devices exposed by this driver.\n \n-* Each qat compression device has a unique name, in format\n- <pci bdf>_<service>, e.g. \"0000:41:01.0_qat_comp\".\n- This name can be passed to rte_compressdev_get_dev_id() to get the device_id.\n+.. _qat_kernel:\n+\n+Dependency on the QAT kernel driver\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+To use QAT an SRIOV-enabled QAT kernel driver is required. The VF\n+devices created and initialised by this driver will be used by the QAT PMDs.\n+\n+Instructions for installation are below, but first an explanation of the\n+relationships between the PF/VF devices and the PMDs visible to\n+DPDK applications.\n+\n+Each QuickAssist PF device exposes a number of VF devices. Each VF device can\n+enable one cryptodev PMD and/or one compressdev PMD.\n+These QAT PMDs share the same underlying device and pci-mgmt code, but are\n+enumerated independently on their respective APIs and appear as independent\n+devices to applications.\n+\n+.. Note::\n+\n+ Each VF can only be used by one DPDK process. It is not possible to share\n+ the same VF across multiple processes, even if these processes are using\n+ different acceleration services.\n+\n+ Conversely one DPDK process can use one or more QAT VFs and can expose both\n+ cryptodev and compressdev instances on each of those VFs.\n \n \n Available kernel drivers\n-------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Kernel drivers for each device are listed in the following table. Scroll right\n-to check that the driver and device supports the servic you require.\n+to check that the driver and device supports the service you require.\n \n \n .. _table_qat_pmds_drivers:\n@@ -203,7 +259,7 @@ If you are running on a kernel which includes a driver for your device, see\n \n \n Installation using kernel.org driver\n-------------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n The examples below are based on the C62x device, if you have a different device\n use the corresponding values in the above table.\n@@ -274,7 +330,7 @@ To complete the installation follow the instructions in\n \n \n Installation using 01.org QAT driver\n-------------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Download the latest QuickAssist Technology Driver from `01.org\n <https://01.org/packet-processing/intel%C2%AE-quickassist-technology-drivers-and-patches>`_.\n@@ -368,12 +424,12 @@ To complete the installation - follow instructions in `Binding the available VFs\n \n \n Binding the available VFs to the DPDK UIO driver\n-------------------------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Unbind the VFs from the stock driver so they can be bound to the uio driver.\n \n For an Intel(R) QuickAssist Technology DH895xCC device\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n \n The unbind command below assumes ``BDFs`` of ``03:01.00-03:04.07``, if your\n VFs are different adjust the unbind command below::\n@@ -386,7 +442,7 @@ VFs are different adjust the unbind command below::\n done\n \n For an Intel(R) QuickAssist Technology C62x device\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n \n The unbind command below assumes ``BDFs`` of ``1a:01.00-1a:02.07``,\n ``3d:01.00-3d:02.07`` and ``3f:01.00-3f:02.07``, if your VFs are different\n@@ -406,7 +462,7 @@ adjust the unbind command below::\n done\n \n For Intel(R) QuickAssist Technology C3xxx or D15xx device\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n \n The unbind command below assumes ``BDFs`` of ``01:01.00-01:02.07``, if your\n VFs are different adjust the unbind command below::\n@@ -419,7 +475,7 @@ VFs are different adjust the unbind command below::\n done\n \n Bind to the DPDK uio driver\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n \n Install the DPDK igb_uio driver, bind the VF PCI Device id to it and use lspci\n to confirm the VF devices are now in use by igb_uio kernel driver,\n@@ -438,9 +494,27 @@ Another way to bind the VFs to the DPDK UIO driver is by using the\n cd to the top-level DPDK directory\n ./usertools/dpdk-devbind.py -b igb_uio 0000:03:01.1\n \n+Testing\n+~~~~~~~\n+\n+QAT crypto PMD can be tested by running the test application::\n+\n+ make test-build -j\n+ cd ./build/build/test/test\n+ ./test -l1 -n1 -w <your qat bdf>\n+ RTE>>cryptodev_qat_autotest\n+\n+QAT compression PMD can be tested by running the test application::\n+\n+ sed -i 's,\\(CONFIG_RTE_COMPRESSDEV_TEST\\)=n,\\1=y,' build/.config\n+ make test-build -j\n+ cd ./build/build/test/test\n+ ./test -l1 -n1 -w <your qat bdf>\n+ RTE>>compressdev_autotest\n+\n \n Debugging\n-----------------------------------------\n+~~~~~~~~~\n \n There are 2 sets of trace available via the dynamic logging feature:\n \n", "prefixes": [] }