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 <ivan.malov@oktetlabs.ru> Acked-by: Ori Kam <orika@nvidia.com> Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
2021-10-13 20:34:41 +03:00 · 2021-10-13 20:34:41 +03:00 · 5da44faa80
commit 5da44faa80
parent 88caad251c
4 changed files with 94 additions and 6 deletions
--- 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`_.
--- 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.
--- 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.
--- 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.