[v2] doc: announce flow API matching pattern struct changes
diff mbox series

Message ID 20201124131535.276072-1-ferruh.yigit@intel.com
State Accepted, archived
Delegated to: Thomas Monjalon
Headers show
Series
  • [v2] doc: announce flow API matching pattern struct changes
Related show

Checks

Context Check Description
ci/travis-robot success Travis build: passed
ci/Intel-compilation success Compilation OK
ci/checkpatch success coding style OK

Commit Message

Ferruh Yigit Nov. 24, 2020, 1:15 p.m. UTC
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>
---
Cc: Thomas Monjalon <thomas@monjalon.net>
Cc: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
Cc: Ori Kam <orika@nvidia.com>

v2:
* Defer actual cleanup to the v21.11 LTS release
---
 doc/guides/rel_notes/deprecation.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

Comments

Ajit Khaparde Nov. 24, 2020, 2:29 p.m. UTC | #1
On Tue, Nov 24, 2020 at 5:15 AM Ferruh Yigit <ferruh.yigit@intel.com> wrote:
>
> 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>

> ---
> Cc: Thomas Monjalon <thomas@monjalon.net>
> Cc: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
> Cc: Ori Kam <orika@nvidia.com>
>
> v2:
> * Defer actual cleanup to the v21.11 LTS release
> ---
>  doc/guides/rel_notes/deprecation.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index 96986fabd598..90b6fbc9548c 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -88,6 +88,16 @@ Deprecation Notices
>    will be limited to maximum 256 queues.
>    Also compile time flag ``RTE_ETHDEV_QUEUE_STAT_CNTRS`` will be removed.
>
> +* 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.
> +
>  * sched: To allow more traffic classes, flexible mapping of pipe queues to
>    traffic classes, and subport level configuration of pipes and queues
>    changes will be made to macros, data structures and API functions defined
> --
> 2.26.2
>
Bruce Richardson Nov. 27, 2020, 4:16 p.m. UTC | #2
On Tue, Nov 24, 2020 at 01:15:35PM +0000, Ferruh Yigit wrote:
> 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>
> ---
> Cc: Thomas Monjalon <thomas@monjalon.net>
> Cc: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
> Cc: Ori Kam <orika@nvidia.com>
> 
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Thomas Monjalon Nov. 27, 2020, 5:56 p.m. UTC | #3
24/11/2020 15:29, Ajit Khaparde:
> On Tue, Nov 24, 2020 at 5:15 AM Ferruh Yigit <ferruh.yigit@intel.com> wrote:
> >
> > 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: Thomas Monjalon <thomas@monjalon.net>

Applied, thanks

Patch
diff mbox series

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index 96986fabd598..90b6fbc9548c 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -88,6 +88,16 @@  Deprecation Notices
   will be limited to maximum 256 queues.
   Also compile time flag ``RTE_ETHDEV_QUEUE_STAT_CNTRS`` will be removed.
 
+* 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.
+
 * sched: To allow more traffic classes, flexible mapping of pipe queues to
   traffic classes, and subport level configuration of pipes and queues
   changes will be made to macros, data structures and API functions defined