d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

ethdev: deprecate direction attributes in transfer flows

Browse Source 
Attributes "ingress" and "egress" can only apply unambiguosly
to non-"transfer" flows. In "transfer" flows, the standpoint
is effectively shifted to the embedded switch. There can be
many different endpoints connected to the switch, so the
use of "ingress" / "egress" does not shed light on which
endpoints precisely can be considered as traffic sources.

Add relevant deprecation notices and suggest the use of precise
traffic source items (PORT_REPRESENTOR and REPRESENTED_PORT).

Signed-off-by: Ivan Malov <ivan.malov@oktetlabs.ru>
Acked-by: Ori Kam <orika@nvidia.com>
Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
Acked-by: Viacheslav Ovsiienko <viacheslavo@nvidia.com>
This commit is contained in:
Ivan Malov 2021-10-13 20:34:42 +03:00 committed by Ferruh Yigit
parent 5da44faa80
commit 9d2a349b38
4 changed files with 52 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/guides/prog_guide/rte_flow.rst
View File

@ -9,8 +9,8 @@ Overview
-------- --------
This API provides a generic means to configure hardware to match specific This API provides a generic means to configure hardware to match specific
ingress or egress traffic, alter its fate and query related counters traffic, alter its fate and query related counters according to any
according to any number of user-defined rules. number of user-defined rules.
It is named *rte_flow* after the prefix used for all its symbols, and is It is named *rte_flow* after the prefix used for all its symbols, and is
defined in ``rte_flow.h``. defined in ``rte_flow.h``.
@ -146,13 +146,10 @@ Note that support for more than a single priority level is not guaranteed.
Attribute: Traffic direction Attribute: Traffic direction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Flow rule patterns apply to inbound and/or outbound traffic. Unless `Attribute: Transfer`_ is specified, flow rule patterns apply
to inbound and / or outbound traffic. With this respect, ``ingress``
In the context of this API, **ingress** and **egress** respectively stand and ``egress`` respectively stand for **inbound** and **outbound**
for **inbound** and **outbound** based on the standpoint of the application based on the standpoint of the application creating a flow rule.
creating a flow rule.
There are no exceptions to this definition.
Several pattern items and actions are valid and can be used in both Several pattern items and actions are valid and can be used in both
directions. At least one direction must be specified. directions. At least one direction must be specified.
@ -171,12 +168,13 @@ When supported, this effectively enables an application to reroute traffic
not necessarily intended for it (e.g. coming from or addressed to different not necessarily intended for it (e.g. coming from or addressed to different
physical ports, VFs or applications) at the device level. physical ports, VFs or applications) at the device level.
It complements the behavior of some pattern items such as `Item: PHY_PORT`_ In "transfer" flows, the use of `Attribute: Traffic direction`_ in the sense of
and is meaningless without them. implicitly matching packets going to or going from the ethdev used to create
flow rules is **deprecated**. `Attribute: Transfer`_ shifts the viewpoint to
When transferring flow rules, **ingress** and **egress** attributes the embedded switch. In it, `Attribute: Traffic direction`_ is ambiguous as
(`Attribute: Traffic direction`_) keep their original meaning, as if the switch serves many different endpoints. The application should match
processing traffic emitted or received by the application. traffic originating from precise locations. To do so, it should
use `Item: PORT_REPRESENTOR`_ and `Item: REPRESENTED_PORT`_.
Pattern item Pattern item
~~~~~~~~~~~~ ~~~~~~~~~~~~

9
doc/guides/rel_notes/deprecation.rst
View File

@ -124,11 +124,6 @@ Deprecation Notices
to support modifying fields larger than 64 bits. to support modifying fields larger than 64 bits.
In addition, documentation will be updated to clarify byte order. In addition, documentation will be updated to clarify byte order.
* 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_*``, * ethdev: The flow API matching pattern structures, ``struct rte_flow_item_*``,
should start with relevant protocol header. should start with relevant protocol header.
Some matching pattern structures implements this by duplicating protocol header Some matching pattern structures implements this by duplicating protocol header
@ -152,6 +147,10 @@ Deprecation Notices
* ethdev: Items and actions ``PF``, ``VF``, ``PHY_PORT``, ``PORT_ID`` are * ethdev: Items and actions ``PF``, ``VF``, ``PHY_PORT``, ``PORT_ID`` are
deprecated as hard-to-use / ambiguous and will be removed in DPDK 22.11. deprecated as hard-to-use / ambiguous and will be removed in DPDK 22.11.
* ethdev: The use of attributes ``ingress`` / ``egress`` in "transfer" flows
is deprecated as ambiguous with respect to the embedded switch. The use of
these attributes will become invalid starting from DPDK 22.11.
* net: The structure ``rte_ipv4_hdr`` will have two unions. * net: The structure ``rte_ipv4_hdr`` will have two unions.
The first union is for existing ``version_ihl`` byte The first union is for existing ``version_ihl`` byte
and new bitfield for version and IHL. and new bitfield for version and IHL.

3
doc/guides/rel_notes/release_21_11.rst
View File

@ -300,6 +300,9 @@ API Changes
* ethdev: Deprecated items and actions ``PF``, ``VF``, ``PHY_PORT``, ``PORT_ID``. * ethdev: Deprecated items and actions ``PF``, ``VF``, ``PHY_PORT``, ``PORT_ID``.
Suggested items and actions ``PORT_REPRESENTOR``, ``REPRESENTED_PORT`` instead. Suggested items and actions ``PORT_REPRESENTOR``, ``REPRESENTED_PORT`` instead.
* ethdev: Deprecated the use of attributes ``ingress`` / ``egress`` combined
with ``transfer``. See items ``PORT_REPRESENTOR``, ``REPRESENTED_PORT``.
* cryptodev: The API rte_cryptodev_pmd_is_valid_dev is modified to * cryptodev: The API rte_cryptodev_pmd_is_valid_dev is modified to
rte_cryptodev_is_valid_dev as it can be used by the application as rte_cryptodev_is_valid_dev as it can be used by the application as
well as PMD to check whether the device is valid or not. well as PMD to check whether the device is valid or not.

41
lib/ethdev/rte_flow.h
View File

@ -67,7 +67,10 @@ extern "C" {
* Note that support for more than a single group and priority level is not * Note that support for more than a single group and priority level is not
* guaranteed. * guaranteed.
* *
* Flow rules can apply to inbound and/or outbound traffic (ingress/egress). * At vNIC / ethdev level, flow rules can apply to inbound and / or outbound
* traffic (ingress / egress), with respect to the vNIC / ethdev in question.
* At embedded switch level, flow rules apply to all traffic seen by it
* unless fitting meta items are used to set concrete traffic source(s).
* *
* Several pattern items and actions are valid and can be used in both * Several pattern items and actions are valid and can be used in both
* directions. Those valid for only one direction are described as such. * directions. Those valid for only one direction are described as such.
@ -80,8 +83,32 @@ extern "C" {
struct rte_flow_attr { struct rte_flow_attr {
uint32_t group; /**< Priority group. */ uint32_t group; /**< Priority group. */
uint32_t priority; /**< Rule priority level within group. */ uint32_t priority; /**< Rule priority level within group. */
uint32_t ingress:1; /**< Rule applies to ingress traffic. */ /**
uint32_t egress:1; /**< Rule applies to egress traffic. */ * The rule in question applies to ingress traffic (non-"transfer").
*
* @deprecated
* It has been possible to combine this attribute with "transfer".
* Doing so has been assumed to restrict the scope of matching
* to traffic going from within the embedded switch toward the
* ethdev the flow rule being created through. This behaviour
* is deprecated. During the transition period, one may still
* rely on it, but PMDs and applications are encouraged to
* gradually move away from this approach.
*/
uint32_t ingress:1;
/**
* The rule in question applies to egress traffic (non-"transfer").
*
* @deprecated
* It has been possible to combine this attribute with "transfer".
* Doing so has been assumed to restrict the scope of matching
* to traffic sent by the application by virtue of the ethdev
* the flow rule being created through. This behaviour is now
* deprecated. During the transition period, one may still
* rely on it, but PMDs and applications are encouraged to
* gradually move away from this approach.
*/
uint32_t egress:1;
/** /**
* Instead of simply matching the properties of traffic as it would * Instead of simply matching the properties of traffic as it would
* appear on a given DPDK port ID, enabling this attribute transfers * appear on a given DPDK port ID, enabling this attribute transfers
@ -93,12 +120,8 @@ struct rte_flow_attr {
* from or addressed to different physical ports, VFs or * from or addressed to different physical ports, VFs or
* applications) at the device level. * applications) at the device level.
* *
* It complements the behavior of some pattern items such as * The application should match traffic originating from precise
* RTE_FLOW_ITEM_TYPE_PHY_PORT and is meaningless without them. * locations. See items PORT_REPRESENTOR and REPRESENTED_PORT.
*
* When transferring flow rules, ingress and egress attributes keep
* their original meaning, as if processing traffic emitted or
* received by the application.
*/ */
uint32_t transfer:1; uint32_t transfer:1;
uint32_t reserved:29; /**< Reserved, must be zero. */ uint32_t reserved:29; /**< Reserved, must be zero. */