doc: refine ethernet and VLAN flow rule items
Checks
Commit Message
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.
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.
To match untagged ipv4 packets, the pattern "eth type is 0x0800 /
ipv4 / end" should be used.
To match both tagged and untagged packets, the pattern "eth / end"
should be used.
Signed-off-by: Dekel Peled <dekelp@mellanox.com>
---
doc/guides/prog_guide/rte_flow.rst | 8 ++++++++
lib/librte_ethdev/rte_flow.h | 9 +++++++++
2 files changed, 17 insertions(+)
Comments
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
> 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.
> 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?
> 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.
> Signed-off-by: Dekel Peled <dekelp@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.
> +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.
> +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. */
>
Thanks, PSB.
> -----Original Message-----
> From: Andrew Rybchenko <arybchenko@solarflare.com>
> Sent: Saturday, April 25, 2020 5:00 PM
> To: Dekel Peled <dekelp@mellanox.com>; Ori Kam <orika@mellanox.com>;
> john.mcnamara@intel.com; marko.kovacevic@intel.com; Thomas Monjalon
> <thomas@monjalon.net>; ferruh.yigit@intel.com
> Cc: dev@dpdk.org; Asaf Penso <asafp@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@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. */
> >
On Sun, 26 Apr 2020 09:18:54 +0000
Dekel Peled <dekelp@mellanox.com> wrote:
> Thanks, PSB.
>
> > -----Original Message-----
> > From: Andrew Rybchenko <arybchenko@solarflare.com>
> > Sent: Saturday, April 25, 2020 5:00 PM
> > To: Dekel Peled <dekelp@mellanox.com>; Ori Kam <orika@mellanox.com>;
> > john.mcnamara@intel.com; marko.kovacevic@intel.com; Thomas Monjalon
> > <thomas@monjalon.net>; ferruh.yigit@intel.com
> > Cc: dev@dpdk.org; Asaf Penso <asafp@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@mellanox.com>
All this reminds me that "code is the best documentation" and there
is no working code that does a complete software implementation of the
rte_flow engine. This means the actual interpretation of what the rte_flow
means is left to documentation and hardware vendors choices in implementation.
Hi Stephen,
> -----Original Message-----
> From: Stephen Hemminger <stephen@networkplumber.org>
> Sent: Sunday, April 26, 2020 8:02 PM
> To: Dekel Peled <dekelp@mellanox.com>
> Cc: Andrew Rybchenko <arybchenko@solarflare.com>; Ori Kam
> <orika@mellanox.com>; john.mcnamara@intel.com;
> marko.kovacevic@intel.com; Thomas Monjalon <thomas@monjalon.net>;
> ferruh.yigit@intel.com; dev@dpdk.org; Asaf Penso <asafp@mellanox.com>
> Subject: Re: [dpdk-dev] [PATCH] doc: refine ethernet and VLAN flow rule items
>
> On Sun, 26 Apr 2020 09:18:54 +0000
> Dekel Peled <dekelp@mellanox.com> wrote:
>
> > Thanks, PSB.
> >
> > > -----Original Message-----
> > > From: Andrew Rybchenko <arybchenko@solarflare.com>
> > > Sent: Saturday, April 25, 2020 5:00 PM
> > > To: Dekel Peled <dekelp@mellanox.com>; Ori Kam <orika@mellanox.com>;
> > > john.mcnamara@intel.com; marko.kovacevic@intel.com; Thomas Monjalon
> > > <thomas@monjalon.net>; ferruh.yigit@intel.com
> > > Cc: dev@dpdk.org; Asaf Penso <asafp@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@mellanox.com>
>
> All this reminds me that "code is the best documentation" and there
> is no working code that does a complete software implementation of the
> rte_flow engine. This means the actual interpretation of what the rte_flow
> means is left to documentation and hardware vendors choices in
> implementation.
I agree with you, that is why I think this patch is important.
Best,
Ori
@@ -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.
+If the ``type`` field contains another EtherType value, then 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.
@@ -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. */