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 B2062A0547; Fri, 1 Oct 2021 15:48:01 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 8A3ED411D3; Fri, 1 Oct 2021 15:47:57 +0200 (CEST) Received: from shelob.oktetlabs.ru (shelob.oktetlabs.ru [91.220.146.113]) by mails.dpdk.org (Postfix) with ESMTP id 1B87E411BC for ; Fri, 1 Oct 2021 15:47:56 +0200 (CEST) Received: by shelob.oktetlabs.ru (Postfix, from userid 122) id D77427F6DF; Fri, 1 Oct 2021 16:47:55 +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 ACF127F6D5; Fri, 1 Oct 2021 16:47:27 +0300 (MSK) DKIM-Filter: OpenDKIM Filter v2.11.0 shelob.oktetlabs.ru ACF127F6D5 Authentication-Results: shelob.oktetlabs.ru/ACF127F6D5; 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:09 +0300 Message-Id: <20211001134716.1608857-6-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 05/12] ethdev: deprecate hard-to-use or ambiguous items and actions 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 PF, VF and PHY_PORT require that applications have extra knowledge of the underlying HW and thus are hard to use. Also, the corresponding items depend on the direction attribute (ingress / egress), which complicates their use in applications and interpretation in PMDs. The concept of PORT_ID is ambiguous as it doesn't say whether the port in question is an ethdev or the represented entity. Items and actions ETHDEV, ESWITCH_PORT should be used instead. Signed-off-by: Ivan Malov Signed-off-by: Andrew Rybchenko --- doc/guides/prog_guide/rte_flow.rst | 16 ++++++++ doc/guides/rel_notes/deprecation.rst | 9 ++--- doc/guides/rel_notes/release_21_11.rst | 3 ++ lib/ethdev/rte_flow.h | 53 ++++++++++++++++++++++++++ 4 files changed, 75 insertions(+), 6 deletions(-) diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index 22f7d327d2..a5db278e8d 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -504,6 +504,8 @@ Usage example, matching non-TCPv4 packets only: Item: ``PF`` ^^^^^^^^^^^^ +This item is DEPRECATED. Consider: `Item: ETHDEV`_, `Item: ESWITCH_PORT`_. + Matches traffic originating from (ingress) or going to (egress) the physical function of the current device. @@ -531,6 +533,8 @@ the application and thus not associated with a DPDK port ID. Item: ``VF`` ^^^^^^^^^^^^ +This item is DEPRECATED. Consider: `Item: ETHDEV`_, `Item: ESWITCH_PORT`_. + Matches traffic originating from (ingress) or going to (egress) a given virtual function of the current device. @@ -562,6 +566,8 @@ separate entities, should be addressed through their own DPDK port IDs. Item: ``PHY_PORT`` ^^^^^^^^^^^^^^^^^^ +This item is DEPRECATED. Consider: `Item: ETHDEV`_, `Item: ESWITCH_PORT`_. + Matches traffic originating from (ingress) or going to (egress) a physical port of the underlying device. @@ -596,6 +602,8 @@ associated with a port_id should be retrieved by other means. Item: ``PORT_ID`` ^^^^^^^^^^^^^^^^^ +This item is DEPRECATED. Consider: `Item: ETHDEV`_, `Item: ESWITCH_PORT`_. + Matches traffic originating from (ingress) or going to (egress) a given DPDK port ID. @@ -1913,6 +1921,8 @@ only matching traffic goes through. Action: ``PF`` ^^^^^^^^^^^^^^ +This action is DEPRECATED. Consider: `Action: ETHDEV`_. + Directs matching traffic to the physical function (PF) of the current device. @@ -1933,6 +1943,8 @@ See `Item: PF`_. Action: ``VF`` ^^^^^^^^^^^^^^ +This action is DEPRECATED. Consider: `Action: ETHDEV`_, `Action: ESWITCH_PORT`_. + Directs matching traffic to a given virtual function of the current device. Packets matched by a VF pattern item can be redirected to their original VF @@ -1957,6 +1969,8 @@ See `Item: VF`_. Action: ``PHY_PORT`` ^^^^^^^^^^^^^^^^^^^^ +This action is DEPRECATED. Consider: `Action: ESWITCH_PORT`_. + Directs matching traffic to a given physical port index of the underlying device. @@ -1976,6 +1990,8 @@ See `Item: PHY_PORT`_. Action: ``PORT_ID`` ^^^^^^^^^^^^^^^^^^^ +This action is DEPRECATED. Consider: `Action: ETHDEV`_, `Action: ESWITCH_PORT`_. + Directs matching traffic to a given DPDK port ID. See `Item: PORT_ID`_. diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index a2fe766d4b..2b6718211f 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -128,12 +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: Definition of the flow API action ``RTE_FLOW_ACTION_TYPE_PORT_ID`` - is ambiguous and needs clarification. - Structure ``rte_flow_action_port_id`` will be extended to specify - 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 @@ -262,3 +256,6 @@ Deprecation Notices * cmdline: ``cmdline`` structure will be made opaque to hide platform-specific content. On Linux and FreeBSD, supported prior to DPDK 20.11, original structure will be kept until DPDK 21.11. + +* 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. diff --git a/doc/guides/rel_notes/release_21_11.rst b/doc/guides/rel_notes/release_21_11.rst index 4f4890c7df..fa0476a290 100644 --- a/doc/guides/rel_notes/release_21_11.rst +++ b/doc/guides/rel_notes/release_21_11.rst @@ -169,6 +169,9 @@ API Changes * ethdev: Added items and actions ``ETHDEV``, ``ESWITCH_PORT`` to flow API. +* ethdev: Deprecated items and actions ``PF``, ``VF``, ``PHY_PORT``, ``PORT_ID``. + Suggested items and actions ``ETHDEV``, ``ESWITCH_PORT`` instead. + * 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 5d46b2350d..a9661dd6ae 100644 --- a/lib/ethdev/rte_flow.h +++ b/lib/ethdev/rte_flow.h @@ -160,6 +160,10 @@ enum rte_flow_item_type { RTE_FLOW_ITEM_TYPE_ANY, /** + * @deprecated + * @see RTE_FLOW_ITEM_TYPE_ETHDEV + * @see RTE_FLOW_ITEM_TYPE_ESWITCH_PORT + * * [META] * * Matches traffic originating from (ingress) or going to (egress) @@ -170,6 +174,10 @@ enum rte_flow_item_type { RTE_FLOW_ITEM_TYPE_PF, /** + * @deprecated + * @see RTE_FLOW_ITEM_TYPE_ETHDEV + * @see RTE_FLOW_ITEM_TYPE_ESWITCH_PORT + * * [META] * * Matches traffic originating from (ingress) or going to (egress) a @@ -180,6 +188,10 @@ enum rte_flow_item_type { RTE_FLOW_ITEM_TYPE_VF, /** + * @deprecated + * @see RTE_FLOW_ITEM_TYPE_ETHDEV + * @see RTE_FLOW_ITEM_TYPE_ESWITCH_PORT + * * [META] * * Matches traffic originating from (ingress) or going to (egress) a @@ -190,6 +202,10 @@ enum rte_flow_item_type { RTE_FLOW_ITEM_TYPE_PHY_PORT, /** + * @deprecated + * @see RTE_FLOW_ITEM_TYPE_ETHDEV + * @see RTE_FLOW_ITEM_TYPE_ESWITCH_PORT + * * [META] * * Matches traffic originating from (ingress) or going to (egress) a @@ -640,6 +656,10 @@ static const struct rte_flow_item_any rte_flow_item_any_mask = { #endif /** + * @deprecated + * @see RTE_FLOW_ITEM_TYPE_ETHDEV + * @see RTE_FLOW_ITEM_TYPE_ESWITCH_PORT + * * RTE_FLOW_ITEM_TYPE_VF * * Matches traffic originating from (ingress) or going to (egress) a given @@ -669,6 +689,10 @@ static const struct rte_flow_item_vf rte_flow_item_vf_mask = { #endif /** + * @deprecated + * @see RTE_FLOW_ITEM_TYPE_ETHDEV + * @see RTE_FLOW_ITEM_TYPE_ESWITCH_PORT + * * RTE_FLOW_ITEM_TYPE_PHY_PORT * * Matches traffic originating from (ingress) or going to (egress) a @@ -700,6 +724,10 @@ static const struct rte_flow_item_phy_port rte_flow_item_phy_port_mask = { #endif /** + * @deprecated + * @see RTE_FLOW_ITEM_TYPE_ETHDEV + * @see RTE_FLOW_ITEM_TYPE_ESWITCH_PORT + * * RTE_FLOW_ITEM_TYPE_PORT_ID * * Matches traffic originating from (ingress) or going to (egress) a given @@ -1989,6 +2017,9 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_RSS, /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_ETHDEV + * * Directs matching traffic to the physical function (PF) of the * current device. * @@ -1997,6 +2028,10 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_PF, /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_ETHDEV + * @see RTE_FLOW_ACTION_TYPE_ESWITCH_PORT + * * Directs matching traffic to a given virtual function of the * current device. * @@ -2005,6 +2040,9 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_VF, /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_ESWITCH_PORT + * * Directs packets to a given physical port index of the underlying * device. * @@ -2013,6 +2051,10 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_PHY_PORT, /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_ETHDEV + * @see RTE_FLOW_ACTION_TYPE_ESWITCH_PORT + * * Directs matching traffic to a given DPDK port ID. * * See struct rte_flow_action_port_id. @@ -2653,6 +2695,10 @@ struct rte_flow_action_rss { }; /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_ETHDEV + * @see RTE_FLOW_ACTION_TYPE_ESWITCH_PORT + * * RTE_FLOW_ACTION_TYPE_VF * * Directs matching traffic to a given virtual function of the current @@ -2671,6 +2717,9 @@ struct rte_flow_action_vf { }; /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_ESWITCH_PORT + * * RTE_FLOW_ACTION_TYPE_PHY_PORT * * Directs packets to a given physical port index of the underlying @@ -2685,6 +2734,10 @@ struct rte_flow_action_phy_port { }; /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_ETHDEV + * @see RTE_FLOW_ACTION_TYPE_ESWITCH_PORT + * * RTE_FLOW_ACTION_TYPE_PORT_ID * * Directs matching traffic to a given DPDK port ID. -- 2.30.2