Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/58872/?format=api
{ "id": 58872, "url": "http://patchwork.dpdk.org/api/patches/58872/?format=api", "web_url": "http://patchwork.dpdk.org/project/dpdk/patch/20190906131330.40185-11-roy.fan.zhang@intel.com/", "project": { "id": 1, "url": "http://patchwork.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": "<20190906131330.40185-11-roy.fan.zhang@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20190906131330.40185-11-roy.fan.zhang@intel.com", "date": "2019-09-06T13:13:30", "name": "[10/10] doc: update security cpu process description", "commit_ref": null, "pull_url": null, "state": "changes-requested", "archived": true, "hash": "e15f0c06e511b74f1df71e11d33c887bcc463261", "submitter": { "id": 304, "url": "http://patchwork.dpdk.org/api/people/304/?format=api", "name": "Fan Zhang", "email": "roy.fan.zhang@intel.com" }, "delegate": { "id": 6690, "url": "http://patchwork.dpdk.org/api/users/6690/?format=api", "username": "akhil", "first_name": "akhil", "last_name": "goyal", "email": "gakhil@marvell.com" }, "mbox": "http://patchwork.dpdk.org/project/dpdk/patch/20190906131330.40185-11-roy.fan.zhang@intel.com/mbox/", "series": [ { "id": 6303, "url": "http://patchwork.dpdk.org/api/series/6303/?format=api", "web_url": "http://patchwork.dpdk.org/project/dpdk/list/?series=6303", "date": "2019-09-06T13:13:20", "name": "security: add software synchronous crypto process", "version": 1, "mbox": "http://patchwork.dpdk.org/series/6303/mbox/" } ], "comments": "http://patchwork.dpdk.org/api/patches/58872/comments/", "check": "success", "checks": "http://patchwork.dpdk.org/api/patches/58872/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 1F6BE1F3D9;\n\tFri, 6 Sep 2019 15:14:11 +0200 (CEST)", "from mga11.intel.com (mga11.intel.com [192.55.52.93])\n\tby dpdk.org (Postfix) with ESMTP id 2048D1F3A3\n\tfor <dev@dpdk.org>; Fri, 6 Sep 2019 15:13:51 +0200 (CEST)", "from fmsmga002.fm.intel.com ([10.253.24.26])\n\tby fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;\n\t06 Sep 2019 06:13:51 -0700", "from silpixa00398673.ir.intel.com (HELO\n\tsilpixa00398673.ger.corp.intel.com) ([10.237.223.136])\n\tby fmsmga002.fm.intel.com with ESMTP; 06 Sep 2019 06:13:49 -0700" ], "X-Amp-Result": "SKIPPED(no attachment in message)", "X-Amp-File-Uploaded": "False", "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.64,473,1559545200\"; d=\"scan'208\";a=\"213140808\"", "From": "Fan Zhang <roy.fan.zhang@intel.com>", "To": "dev@dpdk.org", "Cc": "konstantin.ananyev@intel.com, declan.doherty@intel.com,\n\takhil.goyal@nxp.com, Fan Zhang <roy.fan.zhang@intel.com>", "Date": "Fri, 6 Sep 2019 14:13:30 +0100", "Message-Id": "<20190906131330.40185-11-roy.fan.zhang@intel.com>", "X-Mailer": "git-send-email 2.14.5", "In-Reply-To": "<20190906131330.40185-1-roy.fan.zhang@intel.com>", "References": "<20190903154046.55992-1-roy.fan.zhang@intel.com>\n\t<20190906131330.40185-1-roy.fan.zhang@intel.com>", "Subject": "[dpdk-dev] [PATCH 10/10] doc: update security cpu process\n\tdescription", "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": "This patch updates programmer's guide and release note for\nnewly added security cpu process description.\n\nSigned-off-by: Fan Zhang <roy.fan.zhang@intel.com>\n---\n doc/guides/cryptodevs/aesni_gcm.rst | 6 ++\n doc/guides/cryptodevs/aesni_mb.rst | 7 +++\n doc/guides/prog_guide/rte_security.rst | 112 ++++++++++++++++++++++++++++++++-\n doc/guides/rel_notes/release_19_11.rst | 7 +++\n 4 files changed, 131 insertions(+), 1 deletion(-)", "diff": "diff --git a/doc/guides/cryptodevs/aesni_gcm.rst b/doc/guides/cryptodevs/aesni_gcm.rst\nindex 9a8bc9323..31297fabd 100644\n--- a/doc/guides/cryptodevs/aesni_gcm.rst\n+++ b/doc/guides/cryptodevs/aesni_gcm.rst\n@@ -9,6 +9,12 @@ The AES-NI GCM PMD (**librte_pmd_aesni_gcm**) provides poll mode crypto driver\n support for utilizing Intel multi buffer library (see AES-NI Multi-buffer PMD documentation\n to learn more about it, including installation).\n \n+The AES-NI GCM PMD also supports rte_security with security session create\n+and ``rte_security_process_cpu_crypto_bulk`` function call to process\n+symmetric crypto synchronously with all algorithms specified below. With this\n+way it supports scather-gather buffers (``rte_security_vec`` can be greater than\n+``1``. Please refer to ``rte_security`` programmer's guide for more detail.\n+\n Features\n --------\n \ndiff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst\nindex 1eff2b073..1a3ddd850 100644\n--- a/doc/guides/cryptodevs/aesni_mb.rst\n+++ b/doc/guides/cryptodevs/aesni_mb.rst\n@@ -12,6 +12,13 @@ support for utilizing Intel multi buffer library, see the white paper\n \n The AES-NI MB PMD has current only been tested on Fedora 21 64-bit with gcc.\n \n+The AES-NI MB PMD also supports rte_security with security session create\n+and ``rte_security_process_cpu_crypto_bulk`` function call to process\n+symmetric crypto synchronously with all algorithms specified below. However\n+it does not support scather-gather buffer so the ``num`` value in\n+``rte_security_vec`` can only be ``1``. Please refer to ``rte_security``\n+programmer's guide for more detail.\n+\n Features\n --------\n \ndiff --git a/doc/guides/prog_guide/rte_security.rst b/doc/guides/prog_guide/rte_security.rst\nindex 7d0734a37..861619202 100644\n--- a/doc/guides/prog_guide/rte_security.rst\n+++ b/doc/guides/prog_guide/rte_security.rst\n@@ -296,6 +296,56 @@ Just like IPsec, in case of PDCP also header addition/deletion, cipher/\n de-cipher, integrity protection/verification is done based on the action\n type chosen.\n \n+\n+Synchronous CPU Crypto\n+~~~~~~~~~~~~~~~~~~~~~~\n+\n+RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO:\n+This action type allows the burst of symmetric crypto workload using the same\n+algorithm, key, and direction being processed by CPU cycles synchronously.\n+\n+The packet is sent to the crypto device for symmetric crypto\n+processing. The device will encrypt or decrypt the buffer based on the key(s)\n+and algorithm(s) specified and preprocessed in the security session. Different\n+than the inline or lookaside modes, when the function exits, the user will\n+expect the buffers are either processed successfully, or having the error number\n+assigned to the appropriate index of the status array.\n+\n+E.g. in case of IPsec, the application will use CPU cycles to process both\n+stack and crypto workload synchronously.\n+\n+.. code-block:: console\n+\n+ Egress Data Path\n+ |\n+ +--------|--------+\n+ | egress IPsec |\n+ | | |\n+ | +------V------+ |\n+ | | SADB lookup | |\n+ | +------|------+ |\n+ | +------V------+ |\n+ | | Desc | |\n+ | +------|------+ |\n+ +--------V--------+\n+ |\n+ +--------V--------+\n+ | L2 Stack |\n+ +-----------------+\n+ | |\n+ | Synchronous | <------ Using CPU instructions\n+ | Crypto Process |\n+ | |\n+ +--------V--------+\n+ | L2 Stack Post | <------ Add tunnel, ESP header etc header etc.\n+ +--------|--------+\n+ |\n+ +--------|--------+\n+ | NIC |\n+ +--------|--------+\n+ V\n+\n+\n Device Features and Capabilities\n ---------------------------------\n \n@@ -491,6 +541,7 @@ Security Session configuration structure is defined as ``rte_security_session_co\n struct rte_security_ipsec_xform ipsec;\n struct rte_security_macsec_xform macsec;\n struct rte_security_pdcp_xform pdcp;\n+ struct rte_security_cpu_crypto_xform cpu_crypto;\n };\n /**< Configuration parameters for security session */\n struct rte_crypto_sym_xform *crypto_xform;\n@@ -515,9 +566,12 @@ Offload.\n RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL,\n /**< All security protocol processing is performed inline during\n * transmission */\n- RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL\n+ RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,\n /**< All security protocol processing including crypto is performed\n * on a lookaside accelerator */\n+ RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO\n+ /**< Crypto processing for security protocol is processed by CPU\n+ * synchronously\n };\n \n The ``rte_security_session_protocol`` is defined as\n@@ -587,6 +641,10 @@ PDCP related configuration parameters are defined in ``rte_security_pdcp_xform``\n uint32_t hfn_threshold;\n };\n \n+For CPU Crypto processing action, the application should attach the initialized\n+`xform` to the security session configuration to specify the algorithm, key,\n+direction, and other necessary fields required to perform crypto operation.\n+\n \n Security API\n ~~~~~~~~~~~~\n@@ -650,3 +708,55 @@ it is only valid to have a single flow to map to that security session.\n +-------+ +--------+ +-----+\n | Eth | -> ... -> | ESP | -> | END |\n +-------+ +--------+ +-----+\n+\n+\n+Process bulk crypto workload using CPU instructions\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+The inline and lookaside mode depends on the external HW to complete the\n+workload, where the user has another option to use rte_security to process\n+symmetric crypto synchronously with CPU instructions.\n+\n+When creating the security session the user need to fill the\n+``rte_security_session_conf`` parameter with the ``action_type`` field as\n+``RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO``, and points ``crypto_xform`` to an\n+properly initialized cryptodev xform. The user then passes the\n+``rte_security_session_conf`` instance to ``rte_security_session_create()``\n+along with the security context pointer belongs to a certain SW crypto device.\n+The crypto device may or may not support this action type or the algorithm /\n+key sizes specified in the ``crypto_xform``, but when everything is ok\n+the function will return the created security session.\n+\n+The user then can use this session to process the crypto workload synchronously.\n+Instead of using mbuf ``next`` pointers, synchronous CPU crypto processing uses\n+a special structure ``rte_security_vec`` to describe scatter-gather buffers.\n+\n+.. code-block:: c\n+\n+ struct rte_security_vec {\n+ struct iovec *vec;\n+ uint32_t num;\n+ };\n+\n+Where the structure ``rte_security_vec`` is used to store scatter-gather buffer\n+pointers, where ``vec`` is the pointer to one buffer and ``num`` indicates the\n+number of buffers.\n+\n+Please note not all crypto devices support scatter-gather buffer processing,\n+please check ``cryptodev`` guide for more details.\n+\n+The API of the synchronous CPU crypto process is\n+\n+.. code-block:: c\n+\n+ void\n+ rte_security_process_cpu_crypto_bulk(struct rte_security_ctx *instance,\n+ struct rte_security_session *sess,\n+ struct rte_security_vec buf[], void *iv[], void *aad[],\n+ void *digest[], int status[], uint32_t num);\n+\n+This function will process ``num`` number of ``rte_security_vec`` buffers using\n+the content stored in ``iv`` and ``aad`` arrays. The API only support in-place\n+operation so ``buf`` will be overwritten the encrypted or decrypted values\n+when successfully processed. Otherwise the error number of the status array's\n+according index.\ndiff --git a/doc/guides/rel_notes/release_19_11.rst b/doc/guides/rel_notes/release_19_11.rst\nindex 8490d897c..6cd21704f 100644\n--- a/doc/guides/rel_notes/release_19_11.rst\n+++ b/doc/guides/rel_notes/release_19_11.rst\n@@ -56,6 +56,13 @@ New Features\n Also, make sure to start the actual text at the margin.\n =========================================================\n \n+* **RTE_SECURITY is added new synchronous Crypto burst API with CPU**\n+\n+ A new API rte_security_process_cpu_crypto_bulk is introduced in security\n+ library to process crypto workload in bulk using CPU instructions. AESNI_MB\n+ and AESNI_GCM PMD, as well as unit-test and ipsec-secgw sample applications\n+ are updated to support this feature.\n+\n \n Removed Items\n -------------\n", "prefixes": [ "10/10" ] }