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 239CFA0C43; Sun, 10 Oct 2021 16:40:35 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4C10841123; Sun, 10 Oct 2021 16:40:07 +0200 (CEST) Received: from shelob.oktetlabs.ru (shelob.oktetlabs.ru [91.220.146.113]) by mails.dpdk.org (Postfix) with ESMTP id 7F3D84003C for ; Sun, 10 Oct 2021 16:40:00 +0200 (CEST) Received: from localhost.localdomain (unknown [5.144.123.197]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by shelob.oktetlabs.ru (Postfix) with ESMTPSA id 2DC597F6D7; Sun, 10 Oct 2021 17:40:00 +0300 (MSK) DKIM-Filter: OpenDKIM Filter v2.11.0 shelob.oktetlabs.ru 2DC597F6D7 DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=oktetlabs.ru; s=default; t=1633876800; bh=6n9+fon2tp8nQD1WT6llae4RQxjJsPC4od7C41rMcS0=; h=From:To:Cc:Subject:Date:In-Reply-To:References; b=eVROE0N2Bz2G9nLvSU3XTTVdqEwzhZ78wC6PTth4oDRq0OssMRmT6f5caHsmOWX16 M+cTI+HrHV47n++NS3Z7benKHOlz2S0Q4S7hty7WDnOPDUY6smwX0TisrzO0DQ5Ww+ LD0+n9hweRrZdvUfZhyniO7wZTNplZKcBw/NsS3M= From: Ivan Malov To: dev@dpdk.org Cc: Thomas Monjalon , Ori Kam , Ray Kinsella , Ferruh Yigit , Andrew Rybchenko Date: Sun, 10 Oct 2021 17:39:23 +0300 Message-Id: <20211010143930.4985-6-ivan.malov@oktetlabs.ru> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20211010143930.4985-1-ivan.malov@oktetlabs.ru> References: <20211001134716.1608857-1-andrew.rybchenko@oktetlabs.ru> <20211010143930.4985-1-ivan.malov@oktetlabs.ru> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v3 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" PF, VF and PHY_PORT require that applications have extra knowledge of the underlying NIC 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 PORT_REPRESENTOR, REPRESENTED_PORT should be used instead. Signed-off-by: Ivan Malov --- doc/guides/prog_guide/rte_flow.rst | 32 +++++++++++++++ doc/guides/rel_notes/deprecation.rst | 9 ++--- doc/guides/rel_notes/release_21_11.rst | 3 ++ lib/ethdev/rte_flow.h | 56 ++++++++++++++++++++++++++ 4 files changed, 94 insertions(+), 6 deletions(-) diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index 2bc437e5cd..1aa24e0633 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -504,6 +504,10 @@ Usage example, matching non-TCPv4 packets only: Item: ``PF`` ^^^^^^^^^^^^ +This item is deprecated. Consider: + - `Item: PORT_REPRESENTOR`_ + - `Item: REPRESENTED_PORT`_ + Matches traffic originating from (ingress) or going to (egress) the physical function of the current device. @@ -531,6 +535,10 @@ the application and thus not associated with a DPDK port ID. Item: ``VF`` ^^^^^^^^^^^^ +This item is deprecated. Consider: + - `Item: PORT_REPRESENTOR`_ + - `Item: REPRESENTED_PORT`_ + Matches traffic originating from (ingress) or going to (egress) a given virtual function of the current device. @@ -562,6 +570,10 @@ separate entities, should be addressed through their own DPDK port IDs. Item: ``PHY_PORT`` ^^^^^^^^^^^^^^^^^^ +This item is deprecated. Consider: + - `Item: PORT_REPRESENTOR`_ + - `Item: REPRESENTED_PORT`_ + Matches traffic originating from (ingress) or going to (egress) a physical port of the underlying device. @@ -596,6 +608,10 @@ associated with a port_id should be retrieved by other means. Item: ``PORT_ID`` ^^^^^^^^^^^^^^^^^ +This item is deprecated. Consider: + - `Item: PORT_REPRESENTOR`_ + - `Item: REPRESENTED_PORT`_ + Matches traffic originating from (ingress) or going to (egress) a given DPDK port ID. @@ -1965,6 +1981,10 @@ only matching traffic goes through. Action: ``PF`` ^^^^^^^^^^^^^^ +This action is deprecated. Consider: + - `Action: PORT_REPRESENTOR`_ + - `Action: REPRESENTED_PORT`_ + Directs matching traffic to the physical function (PF) of the current device. @@ -1985,6 +2005,10 @@ See `Item: PF`_. Action: ``VF`` ^^^^^^^^^^^^^^ +This action is deprecated. Consider: + - `Action: PORT_REPRESENTOR`_ + - `Action: REPRESENTED_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 @@ -2009,6 +2033,10 @@ See `Item: VF`_. Action: ``PHY_PORT`` ^^^^^^^^^^^^^^^^^^^^ +This action is deprecated. Consider: + - `Action: PORT_REPRESENTOR`_ + - `Action: REPRESENTED_PORT`_ + Directs matching traffic to a given physical port index of the underlying device. @@ -2028,6 +2056,10 @@ See `Item: PHY_PORT`_. Action: ``PORT_ID`` ^^^^^^^^^^^^^^^^^^^ +This action is deprecated. Consider: + - `Action: PORT_REPRESENTOR`_ + - `Action: REPRESENTED_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 b86147dda1..c91d570099 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -122,12 +122,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 @@ -256,3 +250,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 f689a10e63..63f946ad88 100644 --- a/doc/guides/rel_notes/release_21_11.rst +++ b/doc/guides/rel_notes/release_21_11.rst @@ -190,6 +190,9 @@ API Changes * ethdev: Added items and actions ``PORT_REPRESENTOR``, ``REPRESENTED_PORT`` to flow API. +* ethdev: Deprecated items and actions ``PF``, ``VF``, ``PHY_PORT``, ``PORT_ID``. + Suggested items and actions ``PORT_REPRESENTOR``, ``REPRESENTED_PORT`` instead. + * kvargs: The experimental function ``rte_kvargs_strcmp()`` has been removed. Its usages have been replaced by a new function ``rte_kvargs_get_with_value()``. diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h index afd1f4c193..afd50d6d51 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_PORT_REPRESENTOR + * @see RTE_FLOW_ITEM_TYPE_REPRESENTED_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_PORT_REPRESENTOR + * @see RTE_FLOW_ITEM_TYPE_REPRESENTED_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_PORT_REPRESENTOR + * @see RTE_FLOW_ITEM_TYPE_REPRESENTED_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_PORT_REPRESENTOR + * @see RTE_FLOW_ITEM_TYPE_REPRESENTED_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_PORT_REPRESENTOR + * @see RTE_FLOW_ITEM_TYPE_REPRESENTED_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_PORT_REPRESENTOR + * @see RTE_FLOW_ITEM_TYPE_REPRESENTED_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_PORT_REPRESENTOR + * @see RTE_FLOW_ITEM_TYPE_REPRESENTED_PORT + * * RTE_FLOW_ITEM_TYPE_PORT_ID * * Matches traffic originating from (ingress) or going to (egress) a given @@ -1990,6 +2018,10 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_RSS, /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_PORT_REPRESENTOR + * @see RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT + * * Directs matching traffic to the physical function (PF) of the * current device. * @@ -1998,6 +2030,10 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_PF, /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_PORT_REPRESENTOR + * @see RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT + * * Directs matching traffic to a given virtual function of the * current device. * @@ -2006,6 +2042,10 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_VF, /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_PORT_REPRESENTOR + * @see RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT + * * Directs packets to a given physical port index of the underlying * device. * @@ -2014,6 +2054,10 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_PHY_PORT, /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_PORT_REPRESENTOR + * @see RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT + * * Directs matching traffic to a given DPDK port ID. * * See struct rte_flow_action_port_id. @@ -2654,6 +2698,10 @@ struct rte_flow_action_rss { }; /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_PORT_REPRESENTOR + * @see RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT + * * RTE_FLOW_ACTION_TYPE_VF * * Directs matching traffic to a given virtual function of the current @@ -2672,6 +2720,10 @@ struct rte_flow_action_vf { }; /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_PORT_REPRESENTOR + * @see RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT + * * RTE_FLOW_ACTION_TYPE_PHY_PORT * * Directs packets to a given physical port index of the underlying @@ -2686,6 +2738,10 @@ struct rte_flow_action_phy_port { }; /** + * @deprecated + * @see RTE_FLOW_ACTION_TYPE_PORT_REPRESENTOR + * @see RTE_FLOW_ACTION_TYPE_REPRESENTED_PORT + * * RTE_FLOW_ACTION_TYPE_PORT_ID * * Directs matching traffic to a given DPDK port ID. -- 2.20.1