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 86121A0546; Tue, 6 Apr 2021 17:07:15 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 1590014118F; Tue, 6 Apr 2021 17:07:15 +0200 (CEST) Received: from out5-smtp.messagingengine.com (out5-smtp.messagingengine.com [66.111.4.29]) by mails.dpdk.org (Postfix) with ESMTP id 08FCE141121 for ; Tue, 6 Apr 2021 17:07:14 +0200 (CEST) Received: from compute2.internal (compute2.nyi.internal [10.202.2.42]) by mailout.nyi.internal (Postfix) with ESMTP id 9102C5C0138; Tue, 6 Apr 2021 11:07:13 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute2.internal (MEProxy); Tue, 06 Apr 2021 11:07:13 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:content-type; s=fm3; bh= Hh79sjBFyx2pPiEV7O3MUvrHy8YgEeFdVMFObJ4rriA=; b=VUSeK3eiZhcqG4tn 9b+yYUdfWGJJ7VodaGwJRODUCn7Fcv5/NOmVzv70C154JMoaGzBS1r5EkvQGMVMW MbP1NGs3Cf7J5HgPnSqEIVmxnCBBYJ7PBQK1dMY1abpisRfzTa7xuGYqUqVFJSoM vZ0b4OzPtF5vhh5SCAvL0NkbUpy+79EWJh+OFJhTlka/G0cazYrZGVE6CB+hxC5+ gLqCj8fwMWExRO5WMO/+WGz4sjgAgj/zvdDtZYDfzJt7u0s7S5SA2z4xBx/aJI3U kl4gnkmiXimjHiNwVJwfK9jIg14XwuHtgjrViRZ0EBd8bWODk3QrG6LcG13PptMK 5JeTdQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm2; bh=Hh79sjBFyx2pPiEV7O3MUvrHy8YgEeFdVMFObJ4rr iA=; b=N7pLFHCbMMqkOt0HBhhkvtdMJJ/kBrhZKZ3+lYX7rCVf157UPq7nTNttc U6gP6TWvTgj3a7BA7TvYzu4XGgr2BEQBH1f2pdCqQbawoQBpWNPcj4DgEdl/ZtmX kOAr6O2tu+vqU6ug83lAHR9PRol//FilUTWebnOspqiUbmHwftqbijPk+MJIF+jn /txuizUiutBKWKMhkH/OxdCG4slHHqk+Byf7AD4NKNEMfEV5WY8EshNWDY0WPAqR ACCoJ1eGjSNcc3FjE4Mmmkq7WKyNlBwST0NK6m+non4vrPztBIJLctzAgivfC/fC 7WKduFxJ9t3U8Zu38xjC+PxBGI+Ag== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrudejhedgfeduucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufffkfgjfhgggfgtsehtufertddttddvnecuhfhrohhmpefvhhhomhgr shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg ftrfgrthhtvghrnhepffdvffejueetleefieeludduuefgteejleevfeekjeefieegheet ffdvkeefgedunecuffhomhgrihhnpeguphgukhdrohhrghenucfkphepjeejrddufeegrd dvtdefrddukeegnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhf rhhomhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvth X-ME-Proxy: Received: from xps.localnet (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id CFBF11080064; Tue, 6 Apr 2021 11:07:11 -0400 (EDT) From: Thomas Monjalon To: Asaf Penso , Ferruh Yigit Cc: Ajit Khaparde , dev@dpdk.org, "Gal Cohen (ProdM)" , Andrew Rybchenko , Jerin Jacob Kollanukkaran , rasland@nvidia.com, qi.z.zhang@intel.com Date: Tue, 06 Apr 2021 17:07:10 +0200 Message-ID: <1765424.M8NlyeqTKT@thomas> In-Reply-To: <89ed919a-f45d-3c74-ad62-5402056a612b@intel.com> References: <1612694777-31505-1-git-send-email-asafp@nvidia.com> <89ed919a-f45d-3c74-ad62-5402056a612b@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Subject: Re: [dpdk-dev] [PATCH v4] doc: add new tables for rte flow items and actions support 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" 18/02/2021 19:45, Ferruh Yigit: > On 2/18/2021 5:58 PM, Ajit Khaparde wrote: > > On Wed, Feb 17, 2021 at 2:49 AM Thomas Monjalon wrote: > >> 17/02/2021 11:37, Ferruh Yigit: > >>> On 2/17/2021 5:57 AM, Asaf Penso wrote: > >>>> From: Ferruh Yigit > >>>>> On 2/7/2021 10:52 AM, Asaf Penso wrote: > >>>>>> The following new tables are suggested: > >>>>>> 1. rte_flow items > >>>>>> 2. rte_flow actions > >>>>> > >>>>> Hi Asaf, > >>>>> > >>>>> I understand the intention, but I am not sure about this. > >>>>> > >>>>> The Flow API does not provide a capability or feature list in the API > >>>>> level, by > >>>>> design, because it is very hard to do it correct, but this patch > >>>>> tries to do it in the > >>>>> documentation level. > >>>>> > >>>>> This will be missing lots of details, the flow items and actions > >>>>> documented as > >>>>> supported may and may not be supported based on the details. > >>>>> > >>>> > >>>> Which missing details are you referring to? All flow items and all > >>>> actions are listed. > >>> > >>> Patterns are complex, any rule can be valid or invalid based on provided > >>> pattern > >>> values (details), also any rule can be valid or invalid based on > >>> previous rules > >>> or configuration. > >>> > >>> In practice this information is much more useful if it is provided by > >>> API, but > >>> we are not able to do it because of its complex nature, it should be > >>> same level > >>> of complexity to provide this information by documentation. > >>> > >>>>> It will be very hard to read this table (when it becomes full), also > >>>>> will be very hard to maintain. > >>>> > >>>> As part of any documentation change in rte_flow the developer would > >>>> also need to update this table. > >>>> Why would it be very hard to maintain? > >>> > >>> Ahh, that sound so simple when you say like this :) In practice even > >>> keeping > >>> feature list requiring lots of effort, developers are > >>> missing/neglecting/ignoring updating documentation when updating the > >>> code. > >>> > >>> And for this case is partially correct table a useful information? If > >>> this is > >>> not completely correct people won't rely on it and it will become just > >>> useless. > >>> So this feature should come with an automated way to detect if a rule > >>> supported > >>> but not documented, or even better this table should be generated from > >>> code automatically. > >>> > >>>>> Let me start with a question, who do you think will be your consumer? > >>>>> Who will benefit from this table and how? > >>>> > >>>> We get a lot of questions from users regarding rte_flow support and we > >>>> do not have a single place with proper documentation. > >>>> I can ask the same about the overall feature table, right? There is a > >>>> value to document the support. > >>>> > >>> > >>> Let's discuss the feature table separately, I think that is a valid > >>> question. > >>> > >>> For the rte_flow, who is asking questions? End user, or application > >>> developer? > >>> So is this intended to be a marketing documentation or technical > >>> documentation? > >>> > >>> And what is the nature of the questions, if it is related to the > >>> rte_flow, there > >>> is already a proper documentation for it: > >>> https://doc.dpdk.org/guides/prog_guide/rte_flow.html > >>> > >>> If this question is if any specific rule supported by a specific PMD, > >>> right now > >>> only valid way to say this that I am aware of is, run > >>> 'rte_flow_validate()' and see. > >>> Not sure if we can document this properly. > >> > >> I think in general we are missing a big disclaimer > >> on top of this overview page: > >> Each feature may have some hardware limitations. > >> > >> Then there is a need, both for application developers and end-users, > >> to know which feature can be supported by a PMD, > >> or which PMD can support a feature. > >> Yes there are complex limitations with hardware offloads in general. > >> Yes it would be nice to report some tested capabilities with a CI. > >> But it does not mean we should not try to document it in my opinion. > >> > > +1 to all of these. > > A document like this will help give an idea on what is possible with the > > PMD without looking at the code. Beyond that, the user can check with > > the vendor/developer for specific details if needed. > > I am still feeling we are trying to workaround flow API design constrain with > documentation, although we know it won't be complete. I disagree, it is not a workaround. API is for application to work with any hardware. Doc is for users to imagine which feature they could use in which config (HW, DPDK version, etc). > And not really clear who will benefit from this in what way. End users will be the main users of this doc, but it will help a lot more people to track what is implemented. > Anyway, as mentioned above I am concerned the maintenance cost, can this series > investigate: > 1) A way to automatically fill the table from source code I am looking at it. > 2) A way to check if a patch is adding a new flow support but not documenting it Looking into it as well. > Also can you please propose a maintainer for it (can be documented in MAINTAINER > file) who will be responsible of the correctness of the table, which means: > - Will verify a claimed support by a PMD is really supported > - All flow API features are documented for a PMD > - Changes in the code are reflected to the documentation > - Trace PMD maintainers for missing data I'm not sure we should have a maintainer for this single file. With the help of checkpatch script, the responsibility can be shared in the next-net trees, isn't it?