From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 8F976A0032; Fri, 1 Oct 2021 15:48:09 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E5020411DC; Fri, 1 Oct 2021 15:47:59 +0200 (CEST) Received: from shelob.oktetlabs.ru (shelob.oktetlabs.ru [91.220.146.113]) by mails.dpdk.org (Postfix) with ESMTP id A4998411E6 for ; Fri, 1 Oct 2021 15:47:58 +0200 (CEST) Received: by shelob.oktetlabs.ru (Postfix, from userid 122) id 68FCD7F6DF; Fri, 1 Oct 2021 16:47:58 +0300 (MSK) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on shelob.oktetlabs.ru X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=ALL_TRUSTED, DKIM_ADSP_DISCARD, URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.2 Received: from aros.oktetlabs.ru (aros.oktetlabs.ru [192.168.38.17]) by shelob.oktetlabs.ru (Postfix) with ESMTP id E1C6E7F6D6; Fri, 1 Oct 2021 16:47:27 +0300 (MSK) DKIM-Filter: OpenDKIM Filter v2.11.0 shelob.oktetlabs.ru E1C6E7F6D6 Authentication-Results: shelob.oktetlabs.ru/E1C6E7F6D6; dkim=none; dkim-atps=neutral From: Andrew Rybchenko To: Ori Kam , Ray Kinsella , Thomas Monjalon , Ferruh Yigit Cc: dev@dpdk.org, Ivan Malov Date: Fri, 1 Oct 2021 16:47:10 +0300 Message-Id: <20211001134716.1608857-7-andrew.rybchenko@oktetlabs.ru> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20211001134716.1608857-1-andrew.rybchenko@oktetlabs.ru> References: <20210907125157.3843-1-ivan.malov@oktetlabs.ru> <20211001134716.1608857-1-andrew.rybchenko@oktetlabs.ru> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v1 06/12] ethdev: deprecate direction attributes in transfer flows X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" From: Ivan Malov Attributes "ingress" and "egress" can only apply unambiguosly to non-"transfer" flows. In "transfer" flows, the standpoint is effectively shifted to the underlying e-switch. There can be many different endpoints connected to the e-switch, so the use of "ingress" / "egress" doesn't 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 (ETHDEV and ESWITCH_PORT) instead. Signed-off-by: Ivan Malov Signed-off-by: Andrew Rybchenko --- doc/guides/prog_guide/rte_flow.rst | 29 +++++++++--------- doc/guides/rel_notes/deprecation.rst | 9 +++--- doc/guides/rel_notes/release_21_11.rst | 4 +++ lib/ethdev/rte_flow.h | 41 ++++++++++++++++++++------ 4 files changed, 54 insertions(+), 29 deletions(-) diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index a5db278e8d..c8b2102b52 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -9,8 +9,8 @@ Overview -------- This API provides a generic means to configure hardware to match specific -ingress or egress traffic, alter its fate and query related counters -according to any number of user-defined rules. +traffic, alter its fate and query related counters according to any +number of user-defined rules. It is named *rte_flow* after the prefix used for all its symbols, and is 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Flow rule patterns apply to inbound and/or outbound traffic. - -In the context of this API, **ingress** and **egress** respectively stand -for **inbound** and **outbound** based on the standpoint of the application -creating a flow rule. - -There are no exceptions to this definition. +Unless `Attribute: Transfer`_ is specified, flow rule patterns apply +to inbound and / or outbound traffic. With this respect, **ingress** +and **egress** respectively stand for **inbound** and **outbound** +based on the standpoint of the application creating a flow rule. Several pattern items and actions are valid and can be used in both directions. At least one direction must be specified. @@ -171,12 +168,14 @@ 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. +In **transfer** flows, the use of **ingress** and **egress** attributes +(`Attribute: Traffic direction`_) in the sense of implicitly matching +packets going to or going from the ethdev used to create flow rules +is DEPRECATED as these attributes are ambiguous. The standpoint is +shifted to the e-switch, and, over there, terms **ingress** / **egress** +are not relevant since there're many different ports served by the +e-switch. If the application needs to match traffic origination from some +precise locations, it should use `Item: ETHDEV`_ and `Item: ESWITCH_PORT`_. Pattern item ~~~~~~~~~~~~ diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index 2b6718211f..0c9e739bf2 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -128,11 +128,6 @@ Deprecation Notices is deprecated and will be removed in DPDK 21.11. Shared counters should be managed using shared actions API (``rte_flow_shared_action_create`` etc). -* 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 @@ -259,3 +254,7 @@ Deprecation Notices * 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. + +* ethdev: The use of attributes ``ingress`` / ``egress`` in "transfer" flows + is deprecated as ambiguous with respect to the e-switch standpoint. Such + use of these attributes will become invalid starting from DPDK 22.11. diff --git a/doc/guides/rel_notes/release_21_11.rst b/doc/guides/rel_notes/release_21_11.rst index fa0476a290..37776c135e 100644 --- a/doc/guides/rel_notes/release_21_11.rst +++ b/doc/guides/rel_notes/release_21_11.rst @@ -172,6 +172,10 @@ API Changes * ethdev: Deprecated items and actions ``PF``, ``VF``, ``PHY_PORT``, ``PORT_ID``. Suggested items and actions ``ETHDEV``, ``ESWITCH_PORT`` instead. +* ethdev: Deprecated the use of attributes ``ingress`` / ``egress`` combined + with attribute ``transfer``. Items ``ETHDEV``, ``ESWITCH_PORT`` + should be used instead to specify traffic source(s). + * 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 well as PMD to check whether the device is valid or not. diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h index a9661dd6ae..f195aa7224 100644 --- a/lib/ethdev/rte_flow.h +++ b/lib/ethdev/rte_flow.h @@ -67,7 +67,10 @@ extern "C" { * Note that support for more than a single group and priority level is not * 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 e-switch level, flow rules apply to all traffic seen by the e-switch + * unless suitable meta items are used to set concrete traffic source(s). * * Several pattern items and actions are valid and can be used in both * directions. Those valid for only one direction are described as such. @@ -80,8 +83,32 @@ extern "C" { struct rte_flow_attr { uint32_t group; /**< Priority 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 e-switch toward 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 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 * 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 * applications) at the device level. * - * It complements the behavior of some pattern items such as - * RTE_FLOW_ITEM_TYPE_PHY_PORT and is meaningless without them. - * - * When transferring flow rules, ingress and egress attributes keep - * their original meaning, as if processing traffic emitted or - * received by the application. + * In order to match traffic originating from specific source(s), the + * application should use pattern items ETHDEV and ESWITCH_PORT. */ uint32_t transfer:1; uint32_t reserved:29; /**< Reserved, must be zero. */ -- 2.30.2