Re: [dpdk-dev] [PATCH v4] doc: add new tables for rte flow items and actions support

-----Original Message-----
From: Thomas Monjalon <redacted>
Sent: Wednesday, February 17, 2021 12:49 PM
To: Ferruh Yigit <redacted>
Cc: Asaf Penso <redacted>; dev@dpdk.org; Gal Cohen (ProdM)
[off-list ref]; Andrew Rybchenko [off-list ref];
ajit.khaparde@broadcom.com; jerinj@marvell.com
Subject: Re: [dpdk-dev] [PATCH v4] doc: add new tables for rte flow items and
actions support

17/02/2021 11:37, Ferruh Yigit:

quoted

On 2/17/2021 5:57 AM, Asaf Penso wrote:

quoted

From: Ferruh Yigit <redacted>

quoted

On 2/7/2021 10:52 AM, Asaf Penso wrote:

quoted

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.

quoted

quoted

quoted

Which missing details are you referring to? All flow items and all actions are

listed.

quoted

quoted

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.

quoted

quoted

quoted

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.

quoted

quoted

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.

quoted

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.

quoted

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.

quoted

quoted

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.

quoted

quoted

I can ask the same about the overall feature table, right? There is a value

to document the support.

quoted

quoted

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?

quoted

So is this intended to be a marketing documentation or technical

documentation?

quoted

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.

quoted

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.

Also, the combination of several items and actions is not feasible to be documented. Ferruh, I believe you are referring to this case.
I wanted to have some documentation of the supported items/actions.
The questions come from all users, I didn't bisect to see if they are application engineers or developers or users.
For sure, they can take testpmd and confirm, but before even going there and if they want to evaluate DPDK, they prefer to see a place with this documentation.
We cannot document everything, I know. Also, believe me, that I know how challenging is to track the relevancy of document 😊
Still, it's better to have this, than not at all.

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.