From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id F09B7A0540; Mon, 13 Jul 2020 18:58:41 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id D22BD1D6FF; Mon, 13 Jul 2020 18:58:16 +0200 (CEST) Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) by dpdk.org (Postfix) with ESMTP id 0B1E81D6B7 for ; Mon, 13 Jul 2020 18:58:05 +0200 (CEST) IronPort-SDR: sT9Bi4SDQJdipjSGprFDhHuM3COjjImMY7cJFdMsaXYFA+7xMllU9myqJhAh4DLs4GE/hF6g0I w2G1zs0NHv0Q== X-IronPort-AV: E=McAfee;i="6000,8403,9681"; a="210203494" X-IronPort-AV: E=Sophos;i="5.75,348,1589266800"; d="scan'208";a="210203494" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 13 Jul 2020 09:58:05 -0700 IronPort-SDR: 6BZ+BB9mPCVkRqwwVj6goZf9mQJytGwkK3C+1gtHXYfmuU4ERE10u/IPKYIeI3ycFJpFHq/JR4 VN4YYWmKHZVg== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.75,348,1589266800"; d="scan'208";a="281465685" Received: from silpixa00398673.ir.intel.com (HELO silpixa00398673.ger.corp.intel.com) ([10.237.223.136]) by orsmga003.jf.intel.com with ESMTP; 13 Jul 2020 09:58:04 -0700 From: Fan Zhang To: dev@dpdk.org Cc: fiona.trahe@intel.com, akhil.goyal@nxp.com, Fan Zhang Date: Mon, 13 Jul 2020 17:57:55 +0100 Message-Id: <20200713165755.61814-5-roy.fan.zhang@intel.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200713165755.61814-1-roy.fan.zhang@intel.com> References: <20200703124942.29171-1-roy.fan.zhang@intel.com> <20200713165755.61814-1-roy.fan.zhang@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [dpdk-dev v5 4/4] doc: add cryptodev direct APIs guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" This patch updates programmer's guide to demonstrate the usage and limitations of cryptodev symmetric crypto data-path APIs. Signed-off-by: Fan Zhang --- doc/guides/prog_guide/cryptodev_lib.rst | 53 +++++++++++++++++++++++++ doc/guides/rel_notes/release_20_08.rst | 8 ++++ 2 files changed, 61 insertions(+) diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst index c14f750fa..6316fd1a4 100644 --- a/doc/guides/prog_guide/cryptodev_lib.rst +++ b/doc/guides/prog_guide/cryptodev_lib.rst @@ -631,6 +631,59 @@ a call argument. Status different than zero must be treated as error. For more details, e.g. how to convert an mbuf to an SGL, please refer to an example usage in the IPsec library implementation. +Cryptodev Direct Symmetric Crypto Data-plane APIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Direct symmetric crypto data-path APIs are a set of APIs that especially +provided for Symmetric HW Crypto PMD that provides fast data-path +enqueue/dequeue operations. The direct data-path APIs take advantage of +existing Cryptodev APIs for device, queue pairs, and session management. In +addition the user are required to get the queue pair pointer data and function +pointers. The APIs are provided as an advanced feature as an alternative +to ``rte_cryptodev_enqueue_burst`` and ``rte_cryptodev_dequeue_burst``. The +APIs are designed for the user to develop close-to-native performance symmetric +crypto data-path implementation for their applications that do not necessarily +depend on cryptodev operations and cryptodev operation mempools, or mbufs. + +Cryptodev PMDs who supports this feature will have +``RTE_CRYPTODEV_FF_SYM_HW_DIRECT_API`` feature flag presented. The user uses +``rte_cryptodev_sym_get_hw_ops`` function call to get all the function pointers +for different enqueue and dequeue operations, plus the device specific +queue pair data. After the ``rte_crypto_hw_ops`` structure is properly set by +the driver, the user can use the function pointers and the queue data pointers +in the structure to enqueue and dequeue crypto jobs. + +Direct Data-plane APIs share the same ``struct rte_crypto_sym_vec`` structure +as synchronous mode. However to pass IOVA addresses the user are required to +pass the ``struct rte_crypto_vec`` arrays for IV, AAD, and digests, instead +of VOID pointers as synchronous mode. + +Different than Cryptodev operation, the ``rte_crypto_sym_vec`` structure +focuses only on the data field required for crypto PMD to execute a single job, +and is not supposed stored as opaque data. The user can freely allocate the +structure buffer from stack and reuse it to fill all jobs. + +In addtion, to maximum the flexibility in the enqueue/dequeue operation, the +data-plane APIs supports some special operations specified in the flag +parameters in both enqueue and dequeue functions. For example, setting or +unsetting the flag ``RTE_CRYPTO_HW_DP_FF_ENQUEUE_EXHAUST`` shall make the +PMD behaving differently: setting the flag will make the PMD attempts enqueuing +as many jobs in the ``struct rte_crypto_sym_vec``, but unsetting it will +make the PMD only enqueue the ``num`` or zero operations depends on the +queue status. + +To use the direct symmetric crypto APIs safely, the user has to carefully +set the correct fields in rte_crypto_sym_vec structure, otherwise the +application or the system may crash. Also there are a few limitations to the +direct symmetric crypto APIs: + +* Only support in-place operations. +* APIs are NOT thread-safe. +* CANNOT mix the direct API's enqueue with rte_cryptodev_enqueue_burst, or + vice versa. + +See *DPDK API Reference* for details on each API definitions. + Sample code ----------- diff --git a/doc/guides/rel_notes/release_20_08.rst b/doc/guides/rel_notes/release_20_08.rst index f19b74872..a24797529 100644 --- a/doc/guides/rel_notes/release_20_08.rst +++ b/doc/guides/rel_notes/release_20_08.rst @@ -225,6 +225,14 @@ New Features See the :doc:`../sample_app_ug/l2_forward_real_virtual` for more details of this parameter usage. +* **Add Cryptodev data-path APIs for no mbuf-centric data-path.** + + Cryptodev is added a set of data-path APIs that are not based on + cryptodev operations. The APIs are designed for external applications + or libraries that want to use cryptodev but their data-path + implementations are not mbuf-centric. QAT Symmetric PMD is also updated + to add the support to these APIs. + Removed Items ------------- -- 2.20.1