doc: announce flow API matching structs changes

Proposing to replace protocol header fields in the ``rte_flow_item_*``
structures with the protocol structs.

This is both for documenting the intention and to be sure
``rte_flow_item_*`` always starts with complete protocol header.

Change will be done in two steps, at first step in v21.02 release,
protocol header struct will be added as union, for example:

Current ``struct rte_flow_item_eth``,

struct rte_flow_item_eth {
	struct rte_ether_addr dst;
	struct rte_ether_addr src;
	rte_be16_t type;
	uint32_t has_vlan:1;
	uint32_t reserved:31;
}

will become in v21.02:

__extension__
struct rte_flow_item_eth {
	union {
		struct {
			struct rte_ether_addr dst;
			struct rte_ether_addr src;
			rte_be16_t type;
		};
		struct rte_ether_hdr hdr;
	};
	uint32_t has_vlan:1;
	uint32_t reserved:31;
}

After this point usage should switch to 'hdr' struct.

And in the second step, in the v21.11 LTS release the protocol fields
will be removed, and the struct will become:

struct rte_flow_item_eth {
	struct rte_ether_hdr hdr;
	uint32_t has_vlan:1;
	uint32_t reserved:31;
}

Already many ``rte_flow_item_*`` structures implemented to have protocol
struct, target is convert all to this usage.

Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
Acked-by: Ajit Khaparde <ajit.khaparde@broadcom.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index ad91102..da47718 100644 (file)
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -79,6 +79,16 @@ 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: The flow API matching pattern structures, ``struct rte_flow_item_*``,
+  should start with relevant protocol header.
+  Some matching pattern structures implements this by duplicating protocol header
+  fields in the struct. To clarify the intention and to be sure protocol header
+  is intact, will replace those fields with relevant protocol header struct.
+  In v21.02 both individual protocol header fields and the protocol header struct
+  will be added as union, target is switch usage to the protocol header by time.
+  In v21.11 LTS, protocol header fields will be cleaned and only protocol header
+  struct will remain.
+
 * ethdev: Queue specific stats fields will be removed from ``struct rte_eth_stats``.
   Mentioned fields are: ``q_ipackets``, ``q_opackets``, ``q_ibytes``, ``q_obytes``,
   ``q_errors``.