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 B6D93A0C55; Wed, 13 Oct 2021 18:43:34 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 46B1C41162; Wed, 13 Oct 2021 18:43:09 +0200 (CEST) Received: from shelob.oktetlabs.ru (shelob.oktetlabs.ru [91.220.146.113]) by mails.dpdk.org (Postfix) with ESMTP id 5D2F340151 for ; Wed, 13 Oct 2021 18:42:58 +0200 (CEST) Received: from localhost.localdomain (unknown [5.144.123.99]) (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 0A60E7F6F9; Wed, 13 Oct 2021 19:42:58 +0300 (MSK) DKIM-Filter: OpenDKIM Filter v2.11.0 shelob.oktetlabs.ru 0A60E7F6F9 DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=oktetlabs.ru; s=default; t=1634143378; bh=Z+owkV+j37LAnsZFaoRPn3mqsl/hpAiEYVEI3YCyfS0=; h=From:To:Cc:Subject:Date:In-Reply-To:References; b=loXPtKZRY/acYla9MjcbgPxLPainoFZ85HzTSiIogk1uu22mqBqKtlH8jyrU3KuxI kmCouT323i9zw6wyKlD9HKeMb32Cn33hkjVqIRoSnm/g9z9V/9Wd9zSTcL50QzxM52 BOqtEOSoyhhgAPJyhaicXwYmysA3VwelhZ0QbBoA= From: Ivan Malov To: dev@dpdk.org Cc: Ferruh Yigit , Thomas Monjalon , Ori Kam , Andrew Rybchenko , Ray Kinsella Date: Wed, 13 Oct 2021 19:42:36 +0300 Message-Id: <20211013164243.21264-6-ivan.malov@oktetlabs.ru> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20211013164243.21264-1-ivan.malov@oktetlabs.ru> References: <20211001134716.1608857-1-andrew.rybchenko@oktetlabs.ru> <20211013164243.21264-1-ivan.malov@oktetlabs.ru> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v4 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 Acked-by: Ori Kam Acked-by: Andrew Rybchenko --- 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 27a17fac58..d7185c49df 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. @@ -1950,6 +1966,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. @@ -1970,6 +1990,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 @@ -1994,6 +2018,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. @@ -2013,6 +2041,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 5853b5988d..25aec56bec 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -113,12 +113,6 @@ Deprecation Notices to support modifying fields larger than 64 bits. In addition, documentation will be updated to clarify byte order. -* 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 @@ -149,6 +143,9 @@ Deprecation Notices consistent with existing outer header checksum status flag naming, which should help in reducing confusion about its usage. +* 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. + * net: The structure ``rte_ipv4_hdr`` will have two unions. The first union is for existing ``version_ihl`` byte and new bitfield for version and IHL. diff --git a/doc/guides/rel_notes/release_21_11.rst b/doc/guides/rel_notes/release_21_11.rst index 6c15afc1e9..75c4f6d018 100644 --- a/doc/guides/rel_notes/release_21_11.rst +++ b/doc/guides/rel_notes/release_21_11.rst @@ -254,6 +254,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. + ABI Changes ----------- diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h index ff32c0a5ee..76653105a0 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 @@ -1998,6 +2026,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. * @@ -2006,6 +2038,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. * @@ -2014,6 +2050,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. * @@ -2022,6 +2062,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. @@ -2648,6 +2692,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 @@ -2666,6 +2714,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 @@ -2680,6 +2732,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