[dpdk-dev] [PATCH] doc: clarify implicit filtering in transfer rules

[Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>]

As per existing documentation, attribute "transfer", quote, "complements
the behavior of some pattern items such as RTE_FLOW_ITEM_TYPE_PHY_PORT
and is meaningless without them". That effectively confronts the idea of
implicit filtering imposed by port_id argument passed by flow create API.

This bit of documentation is vague, and having no implicit filtering is
unfriendly to applications which insert flow rules on specific ports
based on the source port IDs of the (not offloaded) incoming packets.

In order to address the problem, document the existence of the implicit
filtering. Use the term "weak" for this filtering as it implies the
possibility to override it by including explicit traffic source criteria
in the flow pattern (PORT_ID, PHY_PORT and the likes).

Signed-off-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
---
The topic was briefly discussed in mail thread [1].

I'm not sure if the patch should have "Fixes:" tag. If it is really
behaviour intended from the very beginning, it should be backported
and corresponding fixes in drivers should be backported as well.

[1] https://patches.dpdk.org/project/dpdk/patch/20210601111420.5549-1-ivan.malov@oktetlabs.ru/

 doc/guides/prog_guide/rte_flow.rst   | 17 ++++++++++++++---
 doc/guides/rel_notes/deprecation.rst |  5 -----
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 2b42d5ec8c..af54939418 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -171,13 +171,24 @@ When supported, this effectively enables an application to reroute traffic
 not necessarily intended for it (e.g. coming from or addressed to different
 physical ports, VFs or applications) at the device level.
 
-It complements the behavior of some pattern items such as `Item: PHY_PORT`_
-and is meaningless without them.
-
 When transferring flow rules, **ingress** and **egress** attributes
 (`Attribute: Traffic direction`_) keep their original meaning, as if
 processing traffic emitted or received by the application.
 
+DPDK port used to create transfer rule is important since it implicitly adds
+filtering by it (similar to `Item: PORT_ID` with ``spec.id`` equal to
+the port ID and exact match mask) if no other items which specify source
+are present in the rule pattern (e.g. `Item: PHY_PORT`, `Item: VF` or
+explicit `Item: PORT_ID`). It means that by default ingress rules apply to
+traffic which comes from associated upstream switch port, i.e. physical
+network port for PF DPDK port, VF for VF representor. Egress rules
+transfer traffic transmitted via corresponding DPDK port, i.e. PF DPDK
+port or VF representor itself.
+
+It is still possible to apply transfer rule on a traffic originating from
+any switch port using wildcard mask in corresponding pattern item if
+underlying PMD supports it.
+
 Pattern item
 ~~~~~~~~~~~~
 
diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index 76a4abfd6b..f1d290a911 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -134,11 +134,6 @@ Deprecation Notices
   traffic direction to the represented entity or ethdev port itself
   in DPDK 21.11.
 
-* ethdev: Flow API documentation is unclear if ethdev port used to create
-  a flow rule adds any implicit match criteria in the case of transfer rules.
-  The semantics will be clarified in DPDK 21.11 and it will require fixes in
-  drivers and applications which interpret it in a different way.
-
 * ethdev: The flow API matching pattern structures, ``struct rte_flow_item_*``,
   should start with relevant protocol header.
   Some matching pattern structures implements this by duplicating protocol header
-- 
2.30.2