[RFC] ethdev: clarify flow attribute and action port ID semantics

diff --git a/lib/ethdev/rte_flow.h b/lib/ethdev/rte_flow.h
index 70f455d47d..bf2b5e752c 100644
--- a/lib/ethdev/rte_flow.h
+++ b/lib/ethdev/rte_flow.h
@@ -82,22 +82,32 @@  struct rte_flow_attr {
 	uint32_t ingress:1; /**< Rule applies to ingress traffic. */
 	uint32_t egress:1; /**< Rule applies to egress traffic. */
 	/**
-	 * Instead of simply matching the properties of traffic as it would
-	 * appear on a given DPDK port ID, enabling this attribute transfers
-	 * a flow rule to the lowest possible level of any device endpoints
-	 * found in the pattern.
-	 *
-	 * When supported, this effectively enables an application to
-	 * re-route traffic not necessarily intended for it (e.g. coming
-	 * from or addressed to different physical ports, VFs or
-	 * applications) at the device level.
-	 *
-	 * It complements the behavior of some pattern items such as
-	 * RTE_FLOW_ITEM_TYPE_PHY_PORT and is meaningless without them.
-	 *
-	 * When transferring flow rules, ingress and egress attributes keep
-	 * their original meaning, as if processing traffic emitted or
-	 * received by the application.
+	 * This "transfers" the rule from the ethdev level to the embedded
+	 * switch (e-switch) level, where it's possible to match traffic
+	 * not necessarily going to the ethdev where the flow is created
+	 * and redirect it to endpoints otherwise not necessarily
+	 * accessible from rules having no such attribute.
+	 *
+	 * Applications willing to use attribute "transfer" should detect its
+	 * paradigm implemented inside the PMD. The paradigms are as follows:
+	 *
+	 * - The PMD supports handling "transfer" flow rules on any ethdevs
+	 *   it serves. With this paradigm, rte_flow_pick_transfer_proxy()
+	 *   call returns (-ENOTSUP) for all ethdevs backed by the PMD.
+	 *   Attributes "ingress" and "egress" are valid and preserve
+	 *   their original meaning, at application standpoint. Also,
+	 *   these attributes typically set some implicit filtering.
+	 *
+	 * - The PMD only supports handling "transfer" flow rules on some
+	 *   specific ethdev pointed out by rte_flow_pick_transfer_proxy().
+	 *   Typically, it's an admin PF ethdev backing a group of VF
+	 *   representor ethdevs. In this case, attributes "ingress"
+	 *   and "egress" cannot maintain their original meaning as
+	 *   the ethdev used to handle "transfer" flow rules is
+	 *   just a technical entry point and does not mean any
+	 *   implicit filtering. Attribute "egress" is rejected,
+	 *   and "ingress" (redundant) means traffic ingressing
+	 *   the embedded switch from any of its endpoints.
 	 */
 	uint32_t transfer:1;
 	uint32_t reserved:29; /**< Reserved, must be zero. */
@@ -191,8 +201,9 @@  enum rte_flow_item_type {
 	/**
 	 * [META]
 	 *
-	 * Matches traffic originating from (ingress) or going to (egress) a
-	 * given DPDK port ID.
+	 * Matches traffic originating from (ingress) or going to (egress) the
+	 * port which, depending on the item sub-variant, is the given ethdev
+	 * or the opposite end of the "wire" attached to this ethdev.
 	 *
 	 * See struct rte_flow_item_port_id.
 	 */
@@ -679,29 +690,61 @@  static const struct rte_flow_item_phy_port rte_flow_item_phy_port_mask = {
 };
 #endif
 
+/** Port types for use with item PORT_ID and action PORT_ID */
+enum rte_flow_item_port_id_type {
+	/**
+	 * The port in question is an embedded switch entity connected
+	 * to or represented by the given ethdev / vSwitch port.
+	 *
+	 * +--------------------------+---------------------------+
+	 * |  Ethdev / vSwitch Port   |   Embedded Switch Entity  |
+	 * +--------------------------+---------------------------+
+	 * |         PF / VF         <->       Network Port       |
+	 * +------------------------------------------------------+
+	 * |   PF / VF Representor   <->      PF / VF Itself      |
+	 * +------------------------------------------------------+
+	 */
+	RTE_FLOW_PORT_TYPE_ESWITCH = 0,
+
+	/**
+	 * The port in question is an ethdev or, synonymously,
+	 * a DPDK-backed vSwitch port.
+	 */
+	RTE_FLOW_PORT_TYPE_ETHDEV,
+};
+
 /**
  * RTE_FLOW_ITEM_TYPE_PORT_ID
  *
- * Matches traffic originating from (ingress) or going to (egress) a given
- * DPDK port ID.
+ * Matches traffic originating from (ingress) or going to (egress) the
+ * port which, depending on the item sub-variant, is the given ethdev
+ * or the opposite end of the "wire" attached to this ethdev.
  *
- * Normally only supported if the port ID in question is known by the
- * underlying PMD and related to the device the flow rule is created
- * against.
+ * Typically, the ethdev referring to the port in question must be served
+ * by the same PMD as that of the ethdev used to create the flow rule.
+ * Also, the port must normally belong to the same physical board.
  *
- * This must not be confused with @p PHY_PORT which refers to the physical
- * port of a device, whereas @p PORT_ID refers to a struct rte_eth_dev
- * object on the application side (also known as "port representor"
- * depending on the kind of underlying device).
+ * This must not be confused with item @p PHY_PORT
+ * which refers specifically to a physical port.
  */
+RTE_STD_C11
 struct rte_flow_item_port_id {
-	uint32_t id; /**< DPDK port ID. */
+	/** Synonymous defines for ethdev ID property */
+	union {
+		/** Ethdev (vSwitch port) ID */
+		uint32_t ethdev_id;
+		/** Compatibility alias to avoid breaking legacy applications */
+		uint32_t id;
+	};
+
+	/** Port type (item sub-variant) */
+	enum rte_flow_item_port_id_type type;
 };
 
 /** Default mask for RTE_FLOW_ITEM_TYPE_PORT_ID. */
 #ifndef __cplusplus
 static const struct rte_flow_item_port_id rte_flow_item_port_id_mask = {
-	.id = 0xffffffff,
+	.ethdev_id = 0xffffffff,
 };
 #endif
 
@@ -1976,7 +2019,8 @@  enum rte_flow_action_type {
 	RTE_FLOW_ACTION_TYPE_PHY_PORT,
 
 	/**
-	 * Directs matching traffic to a given DPDK port ID.
+	 * Depending on the port type, directs matching traffic either to the
+	 * given ethdev or to the opposite end of the "wire" attached to it.
 	 *
 	 * See struct rte_flow_action_port_id.
 	 */
@@ -2635,14 +2679,26 @@  struct rte_flow_action_phy_port {
 /**
  * RTE_FLOW_ACTION_TYPE_PORT_ID
  *
- * Directs matching traffic to a given DPDK port ID.
+ * Depending on the port type, directs matching traffic either to the
+ * given ethdev or to the opposite end of the "wire" attached to it.
  *
  * @see RTE_FLOW_ITEM_TYPE_PORT_ID
  */
+RTE_STD_C11
 struct rte_flow_action_port_id {
-	uint32_t original:1; /**< Use original DPDK port ID if possible. */
+	uint32_t original:1; /**< Use original ethdev ID if possible. */
 	uint32_t reserved:31; /**< Reserved, must be zero. */
-	uint32_t id; /**< DPDK port ID. */
+
+	/** Synonymous defines for ethdev ID property */
+	union {
+		/** Ethdev (vSwitch port) ID */
+		uint32_t ethdev_id;
+		/** Compatibility alias to avoid breaking legacy applications */
+		uint32_t id;
+	};
+
+	/** Port type (action sub-variant) */
+	enum rte_flow_item_port_id_type type;
 };
 
 /**
@@ -4288,6 +4344,24 @@  rte_flow_tunnel_item_release(uint16_t port_id,
 			     struct rte_flow_item *items,
 			     uint32_t num_of_items,
 			     struct rte_flow_error *error);
+
+/**
+ * Locate the "proxy" ethdev to handle "transfer" flow rules
+ * for the given ethdev. If the API returns (-ENOTSUP), the
+ * caller should assume that no "proxying" is required.
+ *
+ * @param port_id
+ *   Ethdev ID that potentially needs a "proxy"
+ * @param[out] proxy_port_id
+ *   The "proxy" port through which "transfer" rules must be communicated
+ *
+ * @return
+ *   0 on success, a negative error code otherwise
+ */
+__rte_experimental
+int
+rte_flow_pick_transfer_proxy(uint16_t port_id,
+			     uint16_t *proxy_port_id);
 #ifdef __cplusplus
 }
 #endif