diff mbox series

[v3,05/12] ethdev: deprecate hard-to-use or ambiguous items and actions

Message ID 20211010143930.4985-6-ivan.malov@oktetlabs.ru (mailing list archive)
State Superseded, archived
Delegated to: Ferruh Yigit
Headers
Series ethdev: rework transfer flow API |

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Ivan Malov Oct. 10, 2021, 2:39 p.m. UTC 
  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>
---
 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(-)

Comments

Ori Kam Oct. 11, 2021, 6:23 p.m. UTC | #1 
Hi Ivan,

> -----Original Message-----
> From: Ivan Malov <ivan.malov@oktetlabs.ru>
> Sent: Sunday, October 10, 2021 5:39 PM
> Subject: [PATCH v3 05/12] 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>
Thanks,
Ori
Andrew Rybchenko Oct. 12, 2021, 12:40 p.m. UTC | #2 
On 10/11/21 9:23 PM, Ori Kam wrote:
> Hi Ivan,
> 
>> -----Original Message-----
>> From: Ivan Malov <ivan.malov@oktetlabs.ru>
>> Sent: Sunday, October 10, 2021 5:39 PM
>> Subject: [PATCH v3 05/12] 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>
> Thanks,
> Ori
> 


Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
Ferruh Yigit Oct. 13, 2021, 11:53 a.m. UTC | #3 
On 10/10/2021 3:39 PM, Ivan Malov wrote:
> --- 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.

Since there will be a new version, can you please add new 'ethdev' deprecation notices,
to the end of the 'ethdev' related deprecation notice group above?
diff mbox series

Patch

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.