From 5da44faa809a1a1c6293c3f3d654c0c933d1cf33 Mon Sep 17 00:00:00 2001 From: Ivan Malov Date: Wed, 13 Oct 2021 20:34:41 +0300 Subject: [PATCH] ethdev: deprecate hard-to-use or ambiguous items and actions 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 c28bc3680e..c46e0e936a 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -124,12 +124,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 @@ -155,6 +149,9 @@ Deprecation Notices will be limited to maximum 256 queues. Also compile time flag ``RTE_ETHDEV_QUEUE_STAT_CNTRS`` will be removed. +* 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 81e5d9c72f..8333b5ebfd 100644 --- a/doc/guides/rel_notes/release_21_11.rst +++ b/doc/guides/rel_notes/release_21_11.rst @@ -297,6 +297,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. + * 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 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.