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 A51D0A04C8; Fri, 18 Sep 2020 22:39:07 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 6640A1DB39; Fri, 18 Sep 2020 22:39:06 +0200 (CEST) Received: from EUR03-DB5-obe.outbound.protection.outlook.com (mail-eopbgr40071.outbound.protection.outlook.com [40.107.4.71]) by dpdk.org (Postfix) with ESMTP id BC25F1DB35 for ; Fri, 18 Sep 2020 22:39:04 +0200 (CEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=SJ5DAtd2Bvzubi4fR9+p0Er97+5Dz9iVxIfVNhZD02nvqPkg3NAxrGyqyc1Uu4E3kWiSa96rAtKodzuXQNrYLC3+SzaBsZq6/T575fOl++Iao9vI9IjCMgWn8i4wIXB4m+buMdhGcX7R8Z9S1QjbDCQVjjpFtAAryEHQsQ+urattSClb4UE2vw60DOORIyW5FWQa5zrjAAxZrDFvqgGgbmABOm/afK9c5txutw6f1NHd/74OmvA1y0NKI9hFDo6IoR0HJts5qYeAcMK+1+TpaJCLfsj3q3VqhEg7SojN4ZZICtStJX9dlFOK3oTGcdUthlV25VcF84ztV8jkF75Mhw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=9USTlljxyhzYtAWAiYR3Pel04u1SM78KPElRbG9bcus=; b=WuZ7GaKX6lYBSRhZejQDTxzW+Dq4Alo9BGHdof0wGjAKqNjbnuA6gGlZE26WB24b6gnFSyGI38t0JTAk5Kb+ruFRBxf3pMa4koR75Irp0y6T7dTAYE9UZ8J0wyblHbVgrBP3ulFR9ZOv3HD2sT470no6T6lK1GshQcFBn7L027hzx2NPDAQUyOYcOS6xfl0UvkpizvI2QxA+6x31LEsnSm74+bls9H2yO87dOyfucsLaHwhpJFVEudN9FgVNhvbO9QStCSK6B6J97UgimZE0GOP6siX1xsxSACfELBfDV39EMLFylYuTQAESlBM9Sqc1gHhizuWjt32F1KbY5TW4rg== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=nxp.com; dmarc=pass action=none header.from=nxp.com; dkim=pass header.d=nxp.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=9USTlljxyhzYtAWAiYR3Pel04u1SM78KPElRbG9bcus=; b=R2kuixHtOsXRWir3oLUdaz2UKVFi0q9nfPa0G9rZwgKmDTMv005BVBldbsNVstjmxx2crXWFcf1k776dibWEN58XzciTkbc4hFTjUcgeFnsv55A6hEknj1zuPJTTaW2hXW7f3Jbf+BR1cF3yKgNVtXVWuTpI+GrqDA5CgbFrGCQ= Received: from VI1PR04MB3168.eurprd04.prod.outlook.com (2603:10a6:802:6::10) by VI1PR04MB4414.eurprd04.prod.outlook.com (2603:10a6:803:69::13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3391.11; Fri, 18 Sep 2020 20:39:02 +0000 Received: from VI1PR04MB3168.eurprd04.prod.outlook.com ([fe80::9513:3b55:931f:216e]) by VI1PR04MB3168.eurprd04.prod.outlook.com ([fe80::9513:3b55:931f:216e%4]) with mapi id 15.20.3391.013; Fri, 18 Sep 2020 20:39:02 +0000 From: Akhil Goyal To: Fan Zhang , "dev@dpdk.org" CC: "fiona.trahe@intel.com" , "arkadiuszx.kusztal@intel.com" , "adamx.dybkowski@intel.com" , Anoob Joseph Thread-Topic: [dpdk-dev v9 4/4] doc: add cryptodev service APIs guide Thread-Index: AQHWhbwVyI8GjwXVOUCcIZFg4B7FV6lu4oow Date: Fri, 18 Sep 2020 20:39:02 +0000 Message-ID: References: <20200904152539.20608-1-roy.fan.zhang@intel.com> <20200908084253.81022-1-roy.fan.zhang@intel.com> <20200908084253.81022-5-roy.fan.zhang@intel.com> In-Reply-To: <20200908084253.81022-5-roy.fan.zhang@intel.com> Accept-Language: en-IN, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: intel.com; dkim=none (message not signed) header.d=none;intel.com; dmarc=none action=none header.from=nxp.com; x-originating-ip: [122.162.67.38] x-ms-publictraffictype: Email x-ms-office365-filtering-ht: Tenant x-ms-office365-filtering-correlation-id: 99cf5c48-dd70-47e0-d1ee-08d85c12e104 x-ms-traffictypediagnostic: VI1PR04MB4414: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-ms-exchange-senderadcheck: 1 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: d5XnVQVLOWrK0y/mvpoB0b7CstV8imwoDM/BlQAunl0S+dpGTd8GD3sCnOBVIS2tYxd7xVdLbTjHxCTX2x8Bqjikj+0neAOxYXvMt/f5aiGgfz2U3bW6i06tQuhjyZgOBBMFm79qxl2WRzX1r7dtSdrlsJ8SbSpHt51Jp14pcdCavniBHnTFz5oUfTE2Ssfeu1xf2OHeW6lU1ijnqrsht/UDsFJE5+iNaNR97eEIGqRQ/eof074gQF3w0dnoRJeT+tEYdSV4WpSNvNu8Y3iblzkFO8DPLPU+i08bofYMpnvvyEHD4cFyZ14ZhuVrK+OU3+KzpA++ngNHxU1EIsPDjxNkrKKD6zkNxGXeHCP85zmBFEhUpzuXNaJUtrkUEZ6d x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:VI1PR04MB3168.eurprd04.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(396003)(39860400002)(366004)(136003)(346002)(376002)(71200400001)(2906002)(66446008)(66946007)(55016002)(76116006)(66476007)(66556008)(4326008)(83380400001)(86362001)(6506007)(8936002)(8676002)(54906003)(44832011)(52536014)(33656002)(64756008)(9686003)(5660300002)(316002)(7696005)(26005)(186003)(478600001)(110136005); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata: 77/cV3L0VfV0ROZnnwbr68k8coXSPRivRC/KIL9+N3gJQ7dRnLx9a970SPzBS7LwXAuQ43WPv/ltK8Z1pdrg0EuueCzvoqxNlJ9WCnntllmqMUphc/CSB7eyXknPvWw9659zGucwi278jUMeN3u4qOLA9i7k5cIk4yfErQNHBUU9nFIIVLE2UfBtoU8ZbzwknDWZ+sb60f6822uoiDSsp7gfGqDYMjcaWzlX2LCxzwToJaCumyYhk4Ea6qsldgM7O93hAM/QqT3MHXRLp0/ajiB150FX39X+2qqITlMGwSlJR33aA98nOeH6KC8O0HkOYLj0c1bFO+8A74xomQadHskWGoFmb2OrMac6Tb8bGJscz7dTNrFoflhucLhEzTqHsowjrr3AZmxvWJbtX4u0QQ6yeuWowkfaAVdAi5608l7Y8AAybwXr7y0C2DvIU+FoNQtAP0P4rZnTNXY8GCXoKCWd+o3VELkKGGYLS3IUTK8CtGTXojOxUUCMFpmz3Wg10UR8sN7UQJvIz/Qmu/K9Jj2Wrx59tWsGbfBECeg5gWE8yGQJT6wukn8R1u25BcFw/Ssr67u1rWGOgZMZi1H6tTk+k1bJuo3USd7BTZdHy4u6fEkBjh+SAERwyjNPaXCklXSSfx2Pt8H09yiuYQ0H9A== x-ms-exchange-transport-forked: True Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: VI1PR04MB3168.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 99cf5c48-dd70-47e0-d1ee-08d85c12e104 X-MS-Exchange-CrossTenant-originalarrivaltime: 18 Sep 2020 20:39:02.6052 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: siV52etQQrpfBCm3VTqsEQ0gFXtKZuO4bRrQoYaF53BU6iwDlgh4CE4pTcCqg01N7aFKn2+Za29JYHP+SLTpKg== X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR04MB4414 Subject: Re: [dpdk-dev] [dpdk-dev v9 4/4] doc: add cryptodev service 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" Hi Fan, > Subject: [dpdk-dev v9 4/4] doc: add cryptodev service APIs guide >=20 > This patch updates programmer's guide to demonstrate the usage > and limitations of cryptodev symmetric crypto data-path service > APIs. >=20 > Signed-off-by: Fan Zhang > --- > doc/guides/prog_guide/cryptodev_lib.rst | 90 +++++++++++++++++++++++++ > doc/guides/rel_notes/release_20_11.rst | 7 ++ > 2 files changed, 97 insertions(+) We generally do not take separate patches for documentation. Squash it the = patches which Implement the feature. >=20 > diff --git a/doc/guides/prog_guide/cryptodev_lib.rst > b/doc/guides/prog_guide/cryptodev_lib.rst > index c14f750fa..1321e4c5d 100644 > --- a/doc/guides/prog_guide/cryptodev_lib.rst > +++ b/doc/guides/prog_guide/cryptodev_lib.rst > @@ -631,6 +631,96 @@ 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. >=20 > +Cryptodev Direct Data-path Service API > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ What do you mean by Direct here. It should be referenced as raw APIs? Moreover, service keyword can also be dropped. We normally use it for Software implementation of a feature which is normally done in hardware. > + > +Direct crypto data-path service are a set of APIs that especially provid= ed for > +the external libraries/applications who want to take advantage of the ri= ch > +features provided by cryptodev, but not necessarily depend on cryptodev > +operations, mempools, or mbufs in the their data-path implementations. Raw crypto data path is a set of APIs which can be used by external libraries/applications to take advantage of the rich features provided by c= ryptodev, but not necessarily depend on cryptodev operations, mempools, or mbufs in t= he data-path implementations. > + > +The direct crypto data-path service has the following advantages: > +- Supports raw data pointer and physical addresses as input. > +- Do not require specific data structure allocated from heap, such as > + cryptodev operation. > +- Enqueue in a burst or single operation. The service allow enqueuing in > + a burst similar to ``rte_cryptodev_enqueue_burst`` operation, or only > + enqueue one job at a time but maintaining necessary context data local= ly for > + next single job enqueue operation. The latter method is especially hel= pful > + when the user application's crypto operations are clustered into a bur= st. > + Allowing enqueue one operation at a time helps reducing one additional= loop > + and also reduced the cache misses during the double "looping" situatio= n. > +- Customerizable dequeue count. Instead of dequeue maximum possible > operations > + as same as ``rte_cryptodev_dequeue_burst`` operation, the service allo= ws the > + user to provide a callback function to decide how many operations to b= e > + dequeued. This is especially helpful when the expected dequeue count i= s > + hidden inside the opaque data stored during enqueue. The user can prov= ide > + the callback function to parse the opaque data structure. > +- Abandon enqueue and dequeue anytime. One of the drawbacks of > + ``rte_cryptodev_enqueue_burst`` and ``rte_cryptodev_dequeue_burst`` > + operations are: once an operation is enqueued/dequeued there is no way= to > + undo the operation. The service make the operation abandon possible by > + creating a local copy of the queue operation data in the service conte= xt > + data. The data will be written back to driver maintained operation dat= a > + when enqueue or dequeue done function is called. > + The language in the above test need to be re-written. Some sentences does n= ot Make complete sense and has grammatical errors. I suggest to have an internal review within Intel first before sending the = next version. > +The cryptodev data-path service uses > + > +Cryptodev PMDs who supports this feature will have > +``RTE_CRYPTODEV_FF_SYM_HW_DIRECT_API`` feature flag presented. To use RTE_CRYPTODEV_FF_SYM_HW_RAW_DP looks better. > this > +feature the function ``rte_cryptodev_get_dp_service_ctx_data_size`` shou= ld Can be renamed as rte_cryptodev_get_raw_dp_ctx_size > +be called to get the data path service context data size. The user shoul= d > +creates a local buffer at least this size long and initialize it using The user should create a local buffer of at least this size and initialize = it using > +``rte_cryptodev_dp_configure_service`` function call. rte_cryptodev_raw_dp_configure or rte_cryptodev_configure _raw_dp can be us= ed here. > + > +The ``rte_cryptodev_dp_configure_service`` function call initialize or > +updates the ``struct rte_crypto_dp_service_ctx`` buffer, in which contai= ns the > +driver specific queue pair data pointer and service context buffer, and = a > +set of function pointers to enqueue and dequeue different algorithms' > +operations. The ``rte_cryptodev_dp_configure_service`` should be called = when: > + > +- Before enqueuing or dequeuing starts (set ``is_update`` parameter to 0= ). > +- When different cryptodev session, security session, or session-less xf= orm > + is used (set ``is_update`` parameter to 1). The use of is_update is not clear with above text. IMO, we do not need this= flag. Whenever an update is required, we change the session information and call = the Same API again and driver can copy all information blindly without checking= . > + > +Two different enqueue functions are provided. > + > +- ``rte_cryptodev_dp_sym_submit_vec``: submit a burst of operations stor= ed in > + the ``rte_crypto_sym_vec`` structure. > +- ``rte_cryptodev_dp_submit_single_job``: submit single operation. What is the meaning of single job here? Can we use multiple buffers/vectors= of same session In a single job? Or we can submit only a single buffer/vector in a job? > + > +Either enqueue functions will not command the crypto device to start > processing > +until ``rte_cryptodev_dp_submit_done`` function is called. Before then t= he user > +shall expect the driver only stores the necessory context data in the > +``rte_crypto_dp_service_ctx`` buffer for the next enqueue operation. If = the > user > +wants to abandon the submitted operations, simply call > +``rte_cryptodev_dp_configure_service`` function instead with the paramet= er > +``is_update`` set to 0. The driver will recover the service context data= to > +the previous state. Can you explain a use case where this is actually being used? This looks fa= ncy but Do we have this type of requirement in any protocol stacks/specifications? I believe it to be an extra burden on the application writer if it is not a= protocol requirement. > + > +To dequeue the operations the user also have two operations: > + > +- ``rte_cryptodev_dp_sym_dequeue``: fully customizable deuqueue operatio= n. > The > + user needs to provide the callback function for the driver to get the > + dequeue count and perform post processing such as write the status fie= ld. > +- ``rte_cryptodev_dp_sym_dequeue_single_job``: dequeue single job. > + > +Same as enqueue, the function ``rte_cryptodev_dp_dequeue_done`` is used = to > +merge user's local service context data with the driver's queue operatio= n > +data. Also to abandon the dequeue operation (still keep the operations i= n the > +queue), the user shall avoid ``rte_cryptodev_dp_dequeue_done`` function = call > +but calling ``rte_cryptodev_dp_configure_service`` function with the par= ameter > +``is_update`` set to 0. > + > +There are a few limitations to the data path service: > + > +* 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 > ----------- >=20 > diff --git a/doc/guides/rel_notes/release_20_11.rst > b/doc/guides/rel_notes/release_20_11.rst > index df227a177..159823345 100644 > --- a/doc/guides/rel_notes/release_20_11.rst > +++ b/doc/guides/rel_notes/release_20_11.rst > @@ -55,6 +55,13 @@ New Features > Also, make sure to start the actual text at the margin. > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D >=20 > + * **Added data-path APIs for cryptodev library.** > + > + Cryptodev is added data-path APIs to accelerate external libraries = or > + applications those want to avail fast cryptodev enqueue/dequeue > + operations but does not necessarily depends on mbufs and cryptodev > + operation mempool. > + >=20 > Removed Items > ------------- Regards, Akhil