diff mbox series

[v2] doc: refine ethernet and VLAN flow rule items

Message ID c42d881f0696c3a363b9a214bb4c2439271bf323.1588489972.git.dekelp@mellanox.com (mailing list archive)
State Accepted, archived
Delegated to: Ferruh Yigit
Headers
Series [v2] doc: refine ethernet and VLAN flow rule items |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation fail Compilation issues
ci/iol-intel-Performance success Performance Testing PASS
ci/iol-nxp-Performance success Performance Testing PASS
ci/iol-mellanox-Performance success Performance Testing PASS
ci/iol-testing success Testing PASS

Commit Message

Dekel Peled May 3, 2020, 7:17 a.m. UTC 
  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 / vlan / ipv4 / end"
should be used.
To match untagged ipv4 packets, the pattern "eth / ipv4 / end"
should be used.
To match all IPV4 packets, both tagged and untagged, need to apply
two rules with the patterns above.
To match both tagged and untagged packets of any type, the pattern
"eth / end" should be used.

Signed-off-by: Dekel Peled <dekelp@mellanox.com>
---
 doc/guides/prog_guide/rte_flow.rst | 7 +++++++
 lib/librte_ethdev/rte_flow.h       | 8 ++++++++
 2 files changed, 15 insertions(+)

Comments

Andrew Rybchenko May 3, 2020, 9:56 a.m. UTC | #1 
On 5/3/20 10:17 AM, 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.
> 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 / vlan / ipv4 / end"
> should be used.
> To match untagged ipv4 packets, the pattern "eth / ipv4 / end"
> should be used.
> To match all IPV4 packets, both tagged and untagged, need to apply
> two rules with the patterns above.
> To match both tagged and untagged packets of any type, the pattern
> "eth / end" should be used.
> 
> Signed-off-by: Dekel Peled <dekelp@mellanox.com>

Acked-by: Andrew Rybchenko <arybchenko@solarflare.com>
Ori Kam May 3, 2020, 2:57 p.m. UTC | #2 
> -----Original Message-----
> From: Andrew Rybchenko <arybchenko@solarflare.com>
> 
> On 5/3/20 10:17 AM, 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.
> > 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 / vlan / ipv4 / end"
> > should be used.
> > To match untagged ipv4 packets, the pattern "eth / ipv4 / end"
> > should be used.
> > To match all IPV4 packets, both tagged and untagged, need to apply
> > two rules with the patterns above.
> > To match both tagged and untagged packets of any type, the pattern
> > "eth / end" should be used.
> >
> > Signed-off-by: Dekel Peled <dekelp@mellanox.com>
> 
> Acked-by: Andrew Rybchenko <arybchenko@solarflare.com>
Acked-by: Ori Kam <orika@mellanox.com>
Thanks,
Ori
Ferruh Yigit May 5, 2020, 4:51 p.m. UTC | #3 
On 5/3/2020 8:17 AM, 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.
> 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 / vlan / ipv4 / end"
> should be used.
> To match untagged ipv4 packets, the pattern "eth / ipv4 / end"
> should be used.
> To match all IPV4 packets, both tagged and untagged, need to apply
> two rules with the patterns above.
> To match both tagged and untagged packets of any type, the pattern
> "eth / end" should be used.
> 
> Signed-off-by: Dekel Peled <dekelp@mellanox.com>

Good to have this clarification, but also I believe we should notify the PMD
maintainers in case there are different implementations.

I have cc'ed the PMD maintainers that implemented flow_ops, to notify from the
change, planning to wait one or two more days before merging it.
Ferruh Yigit May 7, 2020, 2:18 p.m. UTC | #4 
On 5/3/2020 3:57 PM, Ori Kam wrote:
> 
> 
>> -----Original Message-----
>> From: Andrew Rybchenko <arybchenko@solarflare.com>
>>
>> On 5/3/20 10:17 AM, 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.
>>> 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 / vlan / ipv4 / end"
>>> should be used.
>>> To match untagged ipv4 packets, the pattern "eth / ipv4 / end"
>>> should be used.
>>> To match all IPV4 packets, both tagged and untagged, need to apply
>>> two rules with the patterns above.
>>> To match both tagged and untagged packets of any type, the pattern
>>> "eth / end" should be used.
>>>
>>> Signed-off-by: Dekel Peled <dekelp@mellanox.com>
>>
>> Acked-by: Andrew Rybchenko <arybchenko@solarflare.com>
> Acked-by: Ori Kam <orika@mellanox.com>

Applied to dpdk-next-net/master, thanks.
diff mbox series

Patch

diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 15c7b80..d5dd18c 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -905,6 +905,11 @@  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 with the
+specified TPID will match the pattern.
+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 +924,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 1fb94f3..b0e4199 100644
--- a/lib/librte_ethdev/rte_flow.h
+++ b/lib/librte_ethdev/rte_flow.h
@@ -710,6 +710,12 @@  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 with the
+ * specified TPID will match the pattern.
+ * Otherwise, 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 +740,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. */