Re: [dpdk-dev] [PATCH v1] doc: update mlx4 flow limitations

[Adrien Mazarguil <adrien.mazarguil@6wind.com>]

On Fri, Feb 09, 2018 at 05:39:50PM +0100, Thomas Monjalon wrote:
> 09/02/2018 17:21, Adrien Mazarguil:
> > This section is titled "Limitations" but contains a mix of features,
> > limitations and quirks, more like "Random thoughts regarding rte_flow
> > support". I think this is not what users might expect from such a
> > documentation which must be exhaustive and consistent. Getting there may
> > involve tables.
> 
> +Cc Ferruh
> 
> > My suggestion is to first get everyone agree on a common rte_flow
> > capabilities documentation format all PMDs could reuse and then fill in the
> > blanks. What's your opinion?
> 
> I think it's better to have some random thoughts than nothing.
> All the comments you gave in this thread deserve to be written in
> the documentation as soon as possible.

Right, but as a side note in the meantime, more complete documentation is
already available in Doxygen format in mlx4_flow.c. *All* limitations are
also returned in plain text through error messages (rte_flow_error.message)
in the same file (git grep 'msg =' drivers/net/mlx4/mlx4_flow.c).

While not proper documentation, it shouldn't be too difficult to write an
exhaustive list based on that information.

> Working on a better standardized documentation (longer term) should
> not prevent us to write some messy notes in the meantime.

I'm not sure, misleading documentation can do more harm than good for all
parties in my opinion, with users assuming features or limitations that do
not exist, then making purchase decisions and bug reports based on that.

> Is there already some similar rte_flow notes in other PMD docs?

I'm not aware of any, but I do think it's a good idea to start with mlx4.

> About the common documentation, do you think about a generated table
> like it is done for other features?

I'm not sure about this specific format, which can be used to deal with
a bunch of concrete use cases (e.g. "matching TCPv4 traffic and sending it
to some queue = Y") but more than a dozen like that will make it too
confusing to be useful.

I think the current "Flow API = Y" is enough, the rest should be described
in a more verbose format common to all PMDs which remains to be defined.

By "tables" I mean coming up with a visual representation for flow
attributes, patterns and action lists on a single line such as:

 +---------+   +-----+------+-----+    +-------+-----+
 | ingress | : | ETH | IPV4 | UDP | => | COUNT | RSS |
 +---------+   +-----+------+-----+    +-------+-----+

And/or some kind of grammar summarizing all the possibilities, e.g. for
mlx4:

 ingress : ETH [ VLAN ] [ IPV4 [ (UDP | TCP) ] ] => [ VOID ] (DROP | QUEUE | RSS)

With features/limitation for each item described separately.

> Do you plan to provide a template or an example?

I certainly would like to submit something with the plan I suggested,
unfortunately I don't have time to work on that at the moment.

-- 
Adrien Mazarguil
6WIND