From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id E4AACA0C47; Tue, 10 Aug 2021 17:27:26 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 6408940686; Tue, 10 Aug 2021 17:27:26 +0200 (CEST) Received: from mga17.intel.com (mga17.intel.com [192.55.52.151]) by mails.dpdk.org (Postfix) with ESMTP id 832EC4014F for ; Tue, 10 Aug 2021 17:27:24 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10072"; a="195193348" X-IronPort-AV: E=Sophos;i="5.84,310,1620716400"; d="scan'208";a="195193348" Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 10 Aug 2021 08:27:23 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,310,1620716400"; d="scan'208";a="671805497" Received: from orsmsx605.amr.corp.intel.com ([10.22.229.18]) by fmsmga006.fm.intel.com with ESMTP; 10 Aug 2021 08:27:23 -0700 Received: from orsmsx601.amr.corp.intel.com (10.22.229.14) by ORSMSX605.amr.corp.intel.com (10.22.229.18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.4; Tue, 10 Aug 2021 08:27:22 -0700 Received: from ORSEDG601.ED.cps.intel.com (10.7.248.6) by orsmsx601.amr.corp.intel.com (10.22.229.14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.10 via Frontend Transport; Tue, 10 Aug 2021 08:27:22 -0700 Received: from NAM12-DM6-obe.outbound.protection.outlook.com (104.47.59.176) by edgegateway.intel.com (134.134.137.102) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2242.10; Tue, 10 Aug 2021 08:27:22 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Mf1r3nCWR7mwXeeLL7qxepGw2pFDcex9CbW3bp0bwBqJ719pkdV+PWvxTilQ327QR7yqBYeKBo+lDcodtW67zil8XQNMchF8fjsjIes7OqLmZi80HpoW9ab0yXX/b9QkDHI+pHi4wQ9caT3jrjDbnjaojHitPE+iS/YadsW0HbZJVqWATwgGCN4q3BpxlSLCFNjIOFvO4OonXMzn+qo35mtkSZAFq7tU4eeWAGtv3OB8PEqQD1Mfy4tpt75x/fKodM49zNxMahjMjBS4mTHUAwQrDP2RJKJ7WVJKP36Y0HDkoNf/NDTsugkSIJJIz1NU/FURdE9YDEOyheKjqr+Ubw== 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=4ZhDEz6mc9yTGRUtyq9KvNh+Quc23s2a9oQB6B2Rt0w=; b=KbTj0W7vv1pLrc28tr3jkltR6OwJyOgdfYB7kvhBm9VRFpubuZTYpusroBLl5QOPLhEaY4sypdofVGCK5KSbf18o/FfCfYdlFhdEaodKppMb1wkJly7xJQSLN2fdMj5vHk2GsUnyPPndhMx+2s1X1MkpPwEYNBJv5mPwQgCT9kSh1wnou0jvZ/o+S9p8URYU0lPTJe8XBYOtpVMHS185O+S1xL9Sq/QXNb8TjTnmJ6DNNkslZeWz4HZPhizzhTPBhOrZe6u3/+58pUTb6h7P9EH4A0eaJsq9Rb08C5eaqtQOEPKv75XLn/NKIhaTNErSBx/saxg0VXSqVkNvwsrMcA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com; dkim=pass header.d=intel.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=intel.onmicrosoft.com; s=selector2-intel-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=4ZhDEz6mc9yTGRUtyq9KvNh+Quc23s2a9oQB6B2Rt0w=; b=oMCHrgtabItPvoAv/JVdadlaJ9NsDUoXz7G8BXenpjNnHwjkBQbt4FFJnQSnu1xhuVZJR7Zh04iU2q/WIfeoVsglvX7lpGBBztMUi/ctL4K3TXqXeG/EZETiYW64eUe9GD1fYw3Aisu2DI/RgLnuh+36mrNLeQ0O7sZZ4u48VT8= Received: from PH0PR11MB5207.namprd11.prod.outlook.com (2603:10b6:510:32::15) by PH0PR11MB5173.namprd11.prod.outlook.com (2603:10b6:510:39::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4415.13; Tue, 10 Aug 2021 15:27:20 +0000 Received: from PH0PR11MB5207.namprd11.prod.outlook.com ([fe80::c42e:f6ab:d4d6:dc8a]) by PH0PR11MB5207.namprd11.prod.outlook.com ([fe80::c42e:f6ab:d4d6:dc8a%5]) with mapi id 15.20.4394.023; Tue, 10 Aug 2021 15:27:20 +0000 From: "Walsh, Conor" To: Chengwen Feng , "thomas@monjalon.net" , "Yigit, Ferruh" , "Richardson, Bruce" , "jerinj@marvell.com" , "jerinjacobk@gmail.com" , "andrew.rybchenko@oktetlabs.ru" CC: "dev@dpdk.org" , "mb@smartsharesystems.com" , "nipun.gupta@nxp.com" , "hemant.agrawal@nxp.com" , "maxime.coquelin@redhat.com" , "honnappa.nagarahalli@arm.com" , "david.marchand@redhat.com" , "sburla@marvell.com" , "pkapoor@marvell.com" , "Ananyev, Konstantin" Thread-Topic: [dpdk-dev] [PATCH v14 5/6] doc: add DMA device library guide Thread-Index: AQHXjd8aixXTzD2AUkSEdbo3T9Unkatsxfzg Date: Tue, 10 Aug 2021 15:27:19 +0000 Message-ID: References: <1625231891-2963-1-git-send-email-fengchengwen@huawei.com> <1628596454-32918-1-git-send-email-fengchengwen@huawei.com> <1628596454-32918-6-git-send-email-fengchengwen@huawei.com> In-Reply-To: <1628596454-32918-6-git-send-email-fengchengwen@huawei.com> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: dlp-reaction: no-action dlp-version: 11.5.1.3 dlp-product: dlpe-windows authentication-results: huawei.com; dkim=none (message not signed) header.d=none;huawei.com; dmarc=none action=none header.from=intel.com; x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: df0149e6-75b0-4316-f9ce-08d95c13580b x-ms-traffictypediagnostic: PH0PR11MB5173: x-ld-processed: 46c98d88-e344-4ed4-8496-4ed7712e255d,ExtAddr x-ms-exchange-transport-forked: True x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: fYGqS1FJ89g91VD7wE5TEY+0keB+l7vPt7GFZk6dOcYo83tRNnUmyj+97shzBqNbhS5AJZnguPI8O4entyDYGyWltHRcSCmY4BlUeNx99wNIfNRLvff9Xr/yc+NSwXeK+I6dpGVTz1y8KpM0tElULPNbjA24rgAry499LqX4Q7vzzMBGJX6NHdvVF+a85IQyIY6vXvryGp70OVJjz9ZeHjkKlzGx+u3Z58TYLihkntl9X0+4+fPYzvNWOMN8I9uybXX4DffMOeEmL7j5YtIPa1pjbm8vvR4M9rEOqPg3cEZCzYwD1eGRMNv4nlINW4KxDt+/UE5LIgXZbPBCw9Lk3WKntzmmyptXpcEELekSrS5lMdXJ5dw61HYcfwzqblDWY7DsaidzybBN9pFpcrolhZ9WfJISzrZG4GJBaTl20CHZlPcaWinrxUs4nL+AwPkCllMLklGvGSeFH6Vi381A2vfacY2whkQQuZB6vudjBxMCPFbxrnMJGj5JI/tLAMB5z9C7TXWtK3SGu61sN/AHyciS3JM9GhpffxPpChXEm50z9Y81lqY10VUwInQBoj++dj0iz9ZPVMC4s2QxJVfUCgV9yqyWtQCZsEri++2ajAMbQJH48BuQfL4jo/ZNWMvnZXTCGa+WPpXGDk63mP1gSk3AK09j6kk5oFi/7r2KswAcgCY09bf03e5hGFPFE5JKShC+TX0ctTwMNia0uuNqNQ== x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:PH0PR11MB5207.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(136003)(39860400002)(396003)(376002)(346002)(366004)(8676002)(110136005)(54906003)(6506007)(7696005)(9686003)(38100700002)(26005)(4326008)(86362001)(107886003)(8936002)(38070700005)(55016002)(316002)(186003)(5660300002)(122000001)(66476007)(66556008)(7416002)(66946007)(76116006)(83380400001)(478600001)(64756008)(66446008)(33656002)(71200400001)(2906002)(52536014); DIR:OUT; SFP:1102; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?us-ascii?Q?92NlN58WzFNJyqJom9AqrAlhic5jPMvvPX1uvlcGHCgsyBdZGYEP8G8QttcE?= =?us-ascii?Q?KsTaUgLx6R0q3sbm9EEdL3PmsdJhecP2i/4Mt1l4ldqj4yjTiwkhe7vLKPsf?= =?us-ascii?Q?qX7Ybn0XEbmdpFrnwL/2O/VRua0yn1ilmEI/WtmrlWcZ3gwKTmzJeN5R6AYd?= =?us-ascii?Q?Ftq6gKjTZZDrHtqk1adR5OPYpgXjaspl/MoTN29TCMoQNtSvztG4yIBxl96+?= =?us-ascii?Q?AW5MmAzN+uh8c/jXfTtl0oKOiK35qzHNPqT9yMaYzLdIhHIYIPX3qeOQdk6c?= =?us-ascii?Q?lIpacX3VS5/BxX2CNN4I+g3oyQ11aMGGZP0mALnYcUybjmioURPuzKljsg7Z?= =?us-ascii?Q?H92rzpIV78XC4/3cnnTZZO1IPubvm8m+NiLrwW4bPfohmdF1gtHfaYdO1K/2?= =?us-ascii?Q?n6l9KT66GUyi6GdMPBMOe5+cSD9IIyMw0MXcKkPsD8B8qNeCusCcobUGu3FP?= =?us-ascii?Q?Hr15XO9gxypuGe1WkKd8mL+b2UwnBpr9oyE/SNZnKphntH0HlAx7b9x0107Y?= =?us-ascii?Q?Fg2GlCgfzZc9fUJxMgMd4YM6QAebqqBY1faGKGIXbL1OJLpk5YIuEM+VYU32?= =?us-ascii?Q?iyS5nltzLo2ih+H1gW0H0g44t196CDwWp3/7pdt9mdP4xAo+xoyvZiXyXZQB?= =?us-ascii?Q?H0MsbvT8NJFdI6vak4SlAqoQpMn43VipUuV//031Xe3YBWYcFcgXuR+C1Bfd?= =?us-ascii?Q?ntkKlnsREszUYrrqO76hEXoDYtBldDGI1Bx6y7/7UUFeL9VtWJxFzEv76a6T?= =?us-ascii?Q?HxuGQs+lbKTUnYARpBHNsG7gf2uhqQ8DyemIPvigL5MIuNDMUkDRu73Xnno6?= =?us-ascii?Q?U9zqXM2idp0epnoIY7RDq+sp/WQLCeSrtjbyOuoN89+Cv+KKviM8v74qqbqp?= =?us-ascii?Q?JZBLwM6+43L7uoEMrd3SBejTt9jDv/6uHsjZCj7fib9mFytsw7ueofxQ/VRD?= =?us-ascii?Q?MHgZBqUqo4waNX92qkQKAAOuwkxPy/+8pqAP672gM8WPECk/t/BzsiXNtmz3?= =?us-ascii?Q?pK7hAg2kOQCZjAGbEdvQdboqQGnWEC5vla8UEwzQzwdv9scxXuaMsBJP3s3c?= =?us-ascii?Q?pJOo163qDzfMYOBdlYOhyzqxaAMaZSgD+8JP7Vsg6s4mRQ72ncokXm/iyIhk?= =?us-ascii?Q?xxLpMGJcmm3BROQjon4bsQZFQNn3G0rXeauRmz/mZdsFMjaqmVR0bOaVt4wr?= =?us-ascii?Q?3WdbU1YSYfNTgZPjsHr/4kgUZXuM062sVNsphf8IDPPLhRLqpy5EiG9fpjpm?= =?us-ascii?Q?VloUhOR4stGDm3hH2J1TJiUtdUJkGfm7fqWKR5dDmDt96+tk2+2Zk99d7hzn?= =?us-ascii?Q?iV8yv47j6CNW1dSo/nUKHbl8?= Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: PH0PR11MB5207.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: df0149e6-75b0-4316-f9ce-08d95c13580b X-MS-Exchange-CrossTenant-originalarrivaltime: 10 Aug 2021 15:27:19.9914 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 46c98d88-e344-4ed4-8496-4ed7712e255d X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: 0I63q9hE0V/E7MVNKuRjp/LvCUL9vBzRIdpVsg/PxkVF63SonIPuEJ4g26+qyerKAA6iJ6Yd+zH2BTTlC+pnxA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR11MB5173 X-OriginatorOrg: intel.com Subject: Re: [dpdk-dev] [PATCH v14 5/6] doc: add DMA device library guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 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" [snip] Hi Chengwen, I have included some feedback to improve the grammar and readability of the docs inline. > +Device Management > +----------------- > + > +Device Creation > +~~~~~~~~~~~~~~~ > + > +Physical DMA controller is discovered during the PCI probe/enumeration o= f ^ "controllers are" instead of "controller is" > the > +EAL function which is executed at DPDK initialization, based on their PC= I > +device identifier, each unique PCI BDF (bus/bridge, device, function). Change after the first , to the following "this is based on their PCI BDF (bus/bridge, device, function)." > Specific > +physical DMA controller, like other physical devices in DPDK can be list= ed > using ^ "controllers" instead of "controller" > +the EAL command line options. > + > +And then dmadevs are dynamically allocated by ^ Change "And then" to "After DPDK initialization". > rte_dmadev_pmd_allocate() based on > +the number of hardware DMA channels. [snip] > +Device Features and Capabilities > +-------------------------------- > + > +DMA devices may support different feature set. In order to get the > supported PMD ^ missing "s" at the end of line: "DMA devices may support different featur= e sets." > +features ``rte_dmadev_info_get`` API which returns the info of the devic= e > and > +it's supported features. Replace "In order to get the supported PMD features rte_dmadev_info_get API= which returns the info of the device and it's supported features." with: The ``rte_dmadev_info_get`` API can be used to get a devices info and suppo= rted features. > + > +A special device capability is silent mode which application don't requi= red to > +invoke dequeue APIs. Replace the above sentence with: "Silent mode is a special device capability which does not require the appl= ication to invoke dequeue APIs." > + > + > +Enqueue / Dequeue APIs > +~~~~~~~~~~~~~~~~~~~~~~ > + > +The enqueue APIs include like ``rte_dmadev_copy`` and ``rte_dmadev_fill`= `, > if > +enqueue successful, an uint16_t ring_idx is returned. This ring_idx can = be > used > +by applications to track per-operation metadata in an application define= d > +circular ring. Replace the enqueue paragraph with the following: "Enqueue APIs such as ``rte_dmadev_copy`` and ``rte_dmadev_fill`` can be us= ed to enqueue operations to hardware. If an enqueue is successful, a ``ring_id= x`` is returned. This ``ring_idx`` can be used by applications to track per-ope= ration metadata in an application-defined circular ring." > + > +The ``rte_dmadev_submit`` API was used to issue doorbell to hardware, > and also > +there are flags (``RTE_DMA_OP_FLAG_SUBMIT``) parameter of the > enqueue APIs > +could do the same work. Replace submit line with this: "The ``rte_dmadev_submit`` API is used to issue the doorbell to hardware. Alternatively the ``RTE_DMA_OP_FLAG_SUBMIT`` flag can be passed to the enqueue APIs to also issue the doorbell to hardware." > + > +There are two dequeue APIs (``rte_dmadev_completed`` and > +``rte_dmadev_completed_status``) could used to obtain the result of > request. Replace the above sentence with: "There are two dequeue APIs ``rte_dmadev_completed`` and ``rte_dmadev_completed_status``, these are used to obtain the results of the enqueue requests." > +The first API returns the number of operation requests completed > successfully, > +the second API returns the number of operation requests completed which > may > +successfully or failed and also with meaningful status code. Replace above line with the following: "``rte_dmadev_completed`` will return the number of successfully completed = operations. ``rte_dmadev_completed_status`` will return the total number of completed o= perations along with the status of each operation (filled into the ``status`` array p= assed by user)." > Also these two > +APIs could return the last completed operation's ring_idx which will hel= p to > +track application-defined circular ring. Replace the last line with this: "These two APIs can also return the last completed operations ``ring_idx`` = which could help developers track operations within their own application-defined= rings." With the improvements suggested above, Acked-by: Conor Walsh Thanks, Conor.