[dpdk-dev] [PATCH] doc: refine ethernet and VLAN flow rule items

[Dekel Peled]

Thanks, PSB.

> -----Original Message-----
> From: Andrew Rybchenko <arybchenko at solarflare.com>
> Sent: Saturday, April 25, 2020 5:00 PM
> To: Dekel Peled <dekelp at mellanox.com>; Ori Kam <orika at mellanox.com>;
> john.mcnamara at intel.com; marko.kovacevic at intel.com; Thomas Monjalon
> <thomas at monjalon.net>; ferruh.yigit at intel.com
> Cc: dev at dpdk.org; Asaf Penso <asafp at mellanox.com>
> Subject: Re: [PATCH] doc: refine ethernet and VLAN flow rule items
> 
> On 4/23/20 9:30 PM, Dekel Peled wrote:
> > Specified pattern may be translated in different manner.
> > For example the pattern "eth / ipv4" can be translated to match
> > untagged packets only, since the pattern doesn't specify a vlan item.
> 
> vlan -> VLAN

I will change to uppercase.

> 
> > It can also be translated to match both tagged and untagged packets,
> > for the same reason.
> > This patch updates the rte_flow documentation to clearly specify the
> > required pattern to use.
> > For example:
> > To match tagged ipv4 packets, the pattern "eth type is 0x8100 / vlan /
> > ipv4 / end" should be used.
> 
> Isn't eth / vlan / ipv4 /end sufficient? What's the difference?
> I guess later should allow any VLAN TPID, but it is greyish since it is HW
> dependent.

In the example I wanted to show explicit rule, to emphasize the importance of detailed pattern structure.

> 
> > To match untagged ipv4 packets, the pattern "eth type is 0x0800 /
> > ipv4 / end" should be used.
> 
> What about eth / ipv4 / end?
> Does usage of ipv4 assume that EtherType is 0x0800?

Same as above.

> 
> > To match both tagged and untagged packets, the pattern "eth / end"
> > should be used.
> 
> The interesting question is what should be used if I want either tagged or
> untagged IPv4 packets. I think it worse to mention to make the picture
> complete.

To match any IPV4 packet, either tagged or untagged, need to apply two rules.
One for tagged packets and the other for untagged packets.
I will add this example as well.

> 
> > Signed-off-by: Dekel Peled <dekelp at mellanox.com>
> > ---
> >  doc/guides/prog_guide/rte_flow.rst | 8 ++++++++
> >  lib/librte_ethdev/rte_flow.h       | 9 +++++++++
> >  2 files changed, 17 insertions(+)
> >
> > diff --git a/doc/guides/prog_guide/rte_flow.rst
> > b/doc/guides/prog_guide/rte_flow.rst
> > index cf4368e..0d1c305 100644
> > --- a/doc/guides/prog_guide/rte_flow.rst
> > +++ b/doc/guides/prog_guide/rte_flow.rst
> > @@ -905,6 +905,12 @@ so-called layer 2.5 pattern items such as
> > ``RTE_FLOW_ITEM_TYPE_VLAN``. In  the latter case, ``type`` refers to
> > that of the outer header, with the inner  EtherType/TPID provided by
> > the subsequent pattern item. This is the same  order as on the wire.
> > +If the ``type`` field contains a TPID value, then only tagged packets
> > +will match the pattern.
> 
> Shouldn't we emphasis that "tagged packets with specified TPID will match
> the pattern." since tagged packets could have various TPIDs.

Agree, I will update.

> 
> > +If the ``type`` field contains another EtherType value, then only
> > +untagged packets will match the pattern.
> 
> I'm afraid "another EtherType" is too ambiguous.
> "non-TPID EtherType" is ambiguous as well and HW dependent. May be it is
> better to remove the sentence completely.

I think this sentence is important in order to emphasize the untagged packets case.
How about "Otherwise, only untagged packets will match the pattern."?

> 
> > +If the ``ETH`` item is the only item in the pattern, and the ``type``
> > +field is not specified, then both tagged and untagged packets will match
> the pattern.
> >
> >  - ``dst``: destination MAC.
> >  - ``src``: source MAC.
> > @@ -919,6 +925,8 @@ Matches an 802.1Q/ad VLAN tag.
> >  The corresponding standard outer EtherType (TPID) values are
> > ``RTE_ETHER_TYPE_VLAN`` or ``RTE_ETHER_TYPE_QINQ``. It can be
> > overridden by the  preceding pattern item.
> > +If a ``VLAN`` item is present in the pattern, then only tagged
> > +packets will match the pattern.
> >
> >  - ``tci``: tag control information.
> >  - ``inner_type``: inner EtherType or TPID.
> > diff --git a/lib/librte_ethdev/rte_flow.h
> > b/lib/librte_ethdev/rte_flow.h index 132b44e..178e87e 100644
> > --- a/lib/librte_ethdev/rte_flow.h
> > +++ b/lib/librte_ethdev/rte_flow.h
> > @@ -710,6 +710,13 @@ struct rte_flow_item_raw {
> >   * the latter case, @p type refers to that of the outer header, with the
> >   * inner EtherType/TPID provided by the subsequent pattern item. This is
> the
> >   * same order as on the wire.
> > + * If the @p type field contains a TPID value, then only tagged
> > + packets will
> > + * match the pattern.
> > + * If the @p type field contains another EtherType value, then only
> > + untagged
> > + * packets will match the pattern.
> > + * If the @p ETH item is the only item in the pattern, and the @p
> > + type field
> > + * is not specified, then both tagged and untagged packets will match
> > + the
> > + * pattern.
> >   */
> >  struct rte_flow_item_eth {
> >  	struct rte_ether_addr dst; /**< Destination MAC. */ @@ -734,6
> +741,8
> > @@ struct rte_flow_item_eth {
> >   * The corresponding standard outer EtherType (TPID) values are
> >   * RTE_ETHER_TYPE_VLAN or RTE_ETHER_TYPE_QINQ. It can be
> overridden by
> >   * the preceding pattern item.
> > + * If a @p VLAN item is present in the pattern, then only tagged
> > + packets will
> > + * match the pattern.
> >   */
> >  struct rte_flow_item_vlan {
> >  	rte_be16_t tci; /**< Tag control information. */
> >