From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
	by inbox.dpdk.org (Postfix) with ESMTP id 0082DA054D;
	Wed, 17 Feb 2021 11:49:13 +0100 (CET)
Received: from [217.70.189.124] (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 7770A40690;
	Wed, 17 Feb 2021 11:49:13 +0100 (CET)
Received: from out3-smtp.messagingengine.com (out3-smtp.messagingengine.com
 [66.111.4.27]) by mails.dpdk.org (Postfix) with ESMTP id 5A31D4067A
 for <dev@dpdk.org>; Wed, 17 Feb 2021 11:49:12 +0100 (CET)
Received: from compute2.internal (compute2.nyi.internal [10.202.2.42])
 by mailout.nyi.internal (Postfix) with ESMTP id D4B2A5C0176;
 Wed, 17 Feb 2021 05:49:11 -0500 (EST)
Received: from mailfrontend1 ([10.202.2.162])
 by compute2.internal (MEProxy); Wed, 17 Feb 2021 05:49:11 -0500
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=
 9L/WXeuOmgB64aK/Fv9eML27AIfGX0PN3tj8UdwCxlU=; b=t3iNxWaaD1LS+4Rg
 /MDsR3D29i7WDk0o3OfShCpWjceZR58rrqRvnqkYTxunCSnII7fjKtIKY1rvJzvq
 2RA6EaUXdxw2gLqFv4IkdcGxdMKJL6k1I/6Uv0BP9dId3xPj4b3A8wtNs73Ey9Kz
 rIQ0H1QvCVdrApqgxKBeL4UooEmT1A7pO/jpbG3JYN4MA8UUlRx9/ywVSFBV2ETZ
 WuDLzGEWVQvzdxaQk/ZoyYvICNHd18OHbrocOvqmvkKmao6whKB1dJ4NjegQbwYl
 h5ud1W5eYyiCdyU3C4lDMUS6auSiqeRejiUaZEFTq47JyeVi5n2NYmbpNsu1PNiM
 qIPhXg==
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=9L/WXeuOmgB64aK/Fv9eML27AIfGX0PN3tj8UdwCx
 lU=; b=FQkV9nZEXCuU3lAtJ6hqOxKZ0nbtYh2sjmQ1zlNn6B4OYSenJmyIbgAFn
 OVxnGLFVXJP9lmrrvCFvoBFU8+ibB8nGHL3fxYUTgD6b08ufYUhKR/4Y4rHoTbE6
 S+B2hlN51j+jP8QcnOC4yNj+9op1ZV9xXwP6PLbmOte5vPZImPw8Z20K7yfoBpy/
 iPM+L3b+eMp9PpRN69FGTAgUwQilGi41UyDhhpXU97Wt64QHwf6c6Avse1Y6v6Pd
 tdt5rQPXNNd+uMViaJD2WucAyuyBR6CPFaClOKhEdR82HiyjOsI3PnyBPv6T3bHd
 +uCE3tNjAh9d6NRpChNv75oFrbb9g==
X-ME-Sender: <xms:p_QsYAr3cczEoV4tkUzSgsSH1C_VkdvCFv-bIPeDy-CPnB1CHXISLQ>
 <xme:p_QsYGpHpyFQjpTQKzqB1Md9q_yxUWJ5sTdrF-lVs1PlI7P32XH9556P6KAZYwH6Y
 L1iLwQYp-6iH4LWtw>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrjedugddugeejucetufdoteggodetrfdotf
 fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen
 uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne
 cujfgurhephffvufffkfgjfhgggfgtsehtufertddttddvnecuhfhrohhmpefvhhhomhgr
 shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg
 ftrfgrthhtvghrnhepffdvffejueetleefieeludduuefgteejleevfeekjeefieegheet
 ffdvkeefgedunecuffhomhgrihhnpeguphgukhdrohhrghenucfkphepjeejrddufeegrd
 dvtdefrddukeegnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhf
 rhhomhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvth
X-ME-Proxy: <xmx:p_QsYFP8eleB1WuNV6t_djjZELax7-MaMFQhw7QKIXirQsfk19rqbw>
 <xmx:p_QsYH5td5kAjz16oBF2JR5lTn4X0yZ1eJ7mxJKAE5Ec5gyiWu0AwA>
 <xmx:p_QsYP6WpBQKto1Dg2PfYkxEyGWJzkgSnxlwIErH9AqUPILHK8A-yQ>
 <xmx:p_QsYC0ruN0QVGgB5_WtSv0uy-wHxGDSwjVEghwkcil22Jhz2h2Ivw>
Received: from xps.localnet (184.203.134.77.rev.sfr.net [77.134.203.184])
 by mail.messagingengine.com (Postfix) with ESMTPA id 58C3224005D;
 Wed, 17 Feb 2021 05:49:10 -0500 (EST)
From: Thomas Monjalon <thomas@monjalon.net>
To: Ferruh Yigit <ferruh.yigit@intel.com>
Cc: Asaf Penso <asafp@nvidia.com>, "dev@dpdk.org" <dev@dpdk.org>,
 "Gal Cohen (ProdM)" <galco@nvidia.com>,
 Andrew Rybchenko <arybchenko@solarflare.com>, ajit.khaparde@broadcom.com,
 jerinj@marvell.com
Date: Wed, 17 Feb 2021 11:49:08 +0100
Message-ID: <24451137.kzuPNkPQvE@thomas>
In-Reply-To: <6c467b94-8a0e-91b3-4c4f-576730a7ed33@intel.com>
References: <1612694777-31505-1-git-send-email-asafp@nvidia.com>
 <DM5PR12MB24068CEC6A2307E989E6DF35CD869@DM5PR12MB2406.namprd12.prod.outlook.com>
 <6c467b94-8a0e-91b3-4c4f-576730a7ed33@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 <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <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>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

17/02/2021 11:37, Ferruh Yigit:
> On 2/17/2021 5:57 AM, Asaf Penso wrote:
> > From: Ferruh Yigit <ferruh.yigit@intel.com>
> >> On 2/7/2021 10:52 AM, Asaf Penso wrote:
> >>> In http://doc.dpdk.org/guides/nics/overview.html, table 1.1 lists all
> >>> supported features.
> >>> It has a single line for "Flow API" that refers to rte_flow support.
> >>> rte_flow is composed of many items and actions that are not expressed
> >>> in this single line.
> >>>
> >>> 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.