[dpdk-dev,v3,3/4] ethdev: Add group action type to rte_flow

  Add group action type which defines a terminating action which
allows a matched flow to be redirect to a group. This allows logical
flow table hierarchies to be managed through rte_flow.

Signed-off-by: Declan Doherty <declan.doherty@intel.com>
---
 doc/guides/prog_guide/rte_flow.rst | 23 +++++++++++++++++++++++
 lib/librte_ether/rte_flow.h        | 15 +++++++++++++++
 2 files changed, 38 insertions(+)
  

On Fri, Apr 06, 2018 at 01:24:02PM +0100, Declan Doherty wrote:
> Add group action type which defines a terminating action which
> allows a matched flow to be redirect to a group. This allows logical
> flow table hierarchies to be managed through rte_flow.
> 
> Signed-off-by: Declan Doherty <declan.doherty@intel.com>

OK, I'm wondering if perhaps with the addition of this action, we should
redefine groups as unlinked by default?

Currently traffic enters through the flow rule with the lowest priority of
the group with the lowest ID and iterates through subsequent flow rules and
groups until matched by a flow rule without PASSTHRU (according to latest
definition [1]).

This would make jumps between groups always explicit, not necessarily a bad
idea given no PMD implements groups as of yet. Thoughts?

Also as a rather fundamental API addition, I suggest to add it after
RTE_FLOW_ACTION_TYPE_PASSTHRU. It's OK because ABI is already broken. You
just need to mention it in the commit log [1].

Another suggestion would be to rename it "JUMP" (reasons below).

[1] "ethdev: alter behavior of flow API actions"
    http://dpdk.org/ml/archives/dev/2018-April/095779.html

> ---
>  doc/guides/prog_guide/rte_flow.rst | 23 +++++++++++++++++++++++
>  lib/librte_ether/rte_flow.h        | 15 +++++++++++++++
>  2 files changed, 38 insertions(+)
> 
> diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
> index 106fb93..2f0a47a 100644
> --- a/doc/guides/prog_guide/rte_flow.rst
> +++ b/doc/guides/prog_guide/rte_flow.rst
> @@ -1557,6 +1557,29 @@ set of overlay header type.
>     | ``item type`` | Item type of tunnel end-point to decapsulate |
>     +---------------+----------------------------------------------+
>  
> +

Unnecessary empty line.

> +Action: ``GROUP``
> +^^^^^^^^^^^^^^^^^
> +
> +Redirects packets to a group on the current device.
> +
> +In a hierarchy of groups, which can be used to represent physical or logical
> +flow tables on the device, this action allows the terminating action to be a
> +group on that device.
> +
> +- Terminating by default.

Keep in mind there's no such thing as a terminating action anymore [1].

> +
> +.. _table_rte_flow_action_group:
> +
> +.. table:: GROUP
> +
> +   +--------------+---------------------------------+
> +   | Field        | Value                           |
> +   +==============+=================================+
> +   | ``id``       | Group ID to redirect packets to |
> +   +--------------+---------------------------------+

"Field" column can be shrunk somewhat.

> +
> +
>  Negative types
>  ~~~~~~~~~~~~~~
>  
> diff --git a/lib/librte_ether/rte_flow.h b/lib/librte_ether/rte_flow.h
> index 6d94423..968a23b 100644
> --- a/lib/librte_ether/rte_flow.h
> +++ b/lib/librte_ether/rte_flow.h
> @@ -1251,6 +1251,21 @@ struct rte_flow_action_tunnel_decap {
>  };
>  
>  /**
> + * RTE_FLOW_ACTION_TYPE_GROUP

Its addition to enum rte_flow_action_type should be part of this commit.

> + *
> + * Redirects packets to a group on the current device.
> + *
> + * In a hierarchy of groups, which can be used to represent physical or logical
> + * flow tables on the device, this action allows the terminating action to be a
> + * group on that device.
> + *
> + * Terminating by default.

See [1].

> + */
> +struct rte_flow_action_group {
> +	uint32_t id;

Assuming this structure is named rte_flow_action_jump, naming this field
"group" would match the attribute of the same name.

> +};
> +
> +/**
>   * Definition of a single action.
>   *
>   * A list of actions is terminated by a END action.
> -- 
> 2.7.4
> 

Don't forget testpmd code and documentation update.
  

On 06/04/2018 9:26 PM, Adrien Mazarguil wrote:
> On Fri, Apr 06, 2018 at 01:24:02PM +0100, Declan Doherty wrote:
>> Add group action type which defines a terminating action which
>> allows a matched flow to be redirect to a group. This allows logical
>> flow table hierarchies to be managed through rte_flow.
>>
>> Signed-off-by: Declan Doherty <declan.doherty@intel.com>
> 
> OK, I'm wondering if perhaps with the addition of this action, we should
> redefine groups as unlinked by default?

Sure that makes sense to me, as in a device with multiple groups I would 
image that you are more likely to have a tree hierarchy of groups, based 
on something like packet types, rather than a straight priority ordering.
> 
> Currently traffic enters through the flow rule with the lowest priority of
> the group with the lowest ID and iterates through subsequent flow rules and
> groups until matched by a flow rule without PASSTHRU (according to latest
> definition [1]).
> 
> This would make jumps between groups always explicit, not necessarily a bad
> idea given no PMD implements groups as of yet. Thoughts?

I think this is a good idea, as in the case with multiple groups which 
support the same packet time, there may be some flows which could 
potentially hit on many groups, but should be directed to a specific 
group. If group matching was always resolved in a strict priority it 
would result on a hit on an incorrect group. I think making it explicit 
from the start makes sense.

One issue is that groups will need to be populated with a specific rule 
to allow flow to fall through to the next priority group if no match is 
found on the default group.

This just requires changes to the API comments, correct? Do you want to 
capture those in [1] or would you like me to make them with this patch?

> 
> Also as a rather fundamental API addition, I suggest to add it after
> RTE_FLOW_ACTION_TYPE_PASSTHRU. It's OK because ABI is already broken. You
> just need to mention it in the commit log [1].

no problem, will do.

> 
> Another suggestion would be to rename it "JUMP" (reasons below).

I have no issue with changing the action name to JUMP
> 
> [1] "ethdev: alter behavior of flow API actions"
>      http://dpdk.org/ml/archives/dev/2018-April/095779.html
> 
>> ---
>>   doc/guides/prog_guide/rte_flow.rst | 23 +++++++++++++++++++++++
>>   lib/librte_ether/rte_flow.h        | 15 +++++++++++++++
>>   2 files changed, 38 insertions(+)
>>
>> diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
>> index 106fb93..2f0a47a 100644
>> --- a/doc/guides/prog_guide/rte_flow.rst
>> +++ b/doc/guides/prog_guide/rte_flow.rst
>> @@ -1557,6 +1557,29 @@ set of overlay header type.
>>      | ``item type`` | Item type of tunnel end-point to decapsulate |
>>      +---------------+----------------------------------------------+
>>   
>> +
> 
> Unnecessary empty line.
> 
>> +Action: ``GROUP``
>> +^^^^^^^^^^^^^^^^^
>> +
>> +Redirects packets to a group on the current device.
>> +
>> +In a hierarchy of groups, which can be used to represent physical or logical
>> +flow tables on the device, this action allows the terminating action to be a
>> +group on that device.
>> +
>> +- Terminating by default.
> 
> Keep in mind there's no such thing as a terminating action anymore [1].
> 
>> +
>> +.. _table_rte_flow_action_group:
>> +
>> +.. table:: GROUP
>> +
>> +   +--------------+---------------------------------+
>> +   | Field        | Value                           |
>> +   +==============+=================================+
>> +   | ``id``       | Group ID to redirect packets to |
>> +   +--------------+---------------------------------+
> 
> "Field" column can be shrunk somewhat.
> 
>> +
>> +
>>   Negative types
>>   ~~~~~~~~~~~~~~
>>   
>> diff --git a/lib/librte_ether/rte_flow.h b/lib/librte_ether/rte_flow.h
>> index 6d94423..968a23b 100644
>> --- a/lib/librte_ether/rte_flow.h
>> +++ b/lib/librte_ether/rte_flow.h
>> @@ -1251,6 +1251,21 @@ struct rte_flow_action_tunnel_decap {
>>   };
>>   
>>   /**
>> + * RTE_FLOW_ACTION_TYPE_GROUP
> 
> Its addition to enum rte_flow_action_type should be part of this commit.
> 
that was a rebasing issue, I'll fix in next revision

>> + *
>> + * Redirects packets to a group on the current device.
>> + *
>> + * In a hierarchy of groups, which can be used to represent physical or logical
>> + * flow tables on the device, this action allows the terminating action to be a
>> + * group on that device.
>> + *
>> + * Terminating by default.
> 
> See [1].
> 
>> + */
>> +struct rte_flow_action_group {
>> +	uint32_t id;
> 
> Assuming this structure is named rte_flow_action_jump, naming this field
> "group" would match the attribute of the same name.
> 
>> +};
>> +
>> +/**
>>    * Definition of a single action.
>>    *
>>    * A list of actions is terminated by a END action.
>> -- 
>> 2.7.4
>>
> 
> Don't forget testpmd code and documentation update.
>