[dpdk-dev,v3] ethdev: fix flow validate comments

  Change comments for rte_flow_validate() function to indicate that flow
rule collision and resource validation is optional for PMD and therefore
the return codes may have different meanings.

Fixes: b1a4b4cbc0a8 ("ethdev: introduce generic flow API")

Signed-off-by: John Daley <johndale@cisco.com>
---
v2: another crack at the comments
v3: fix typos, rewording, put back a sentence omitted in v2

 lib/librte_ether/rte_flow.h | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)
  

Hi John,

On Thu, Apr 06, 2017 at 05:23:00PM -0700, John Daley wrote:
> Change comments for rte_flow_validate() function to indicate that flow
> rule collision and resource validation is optional for PMD and therefore
> the return codes may have different meanings.
> 
> Fixes: b1a4b4cbc0a8 ("ethdev: introduce generic flow API")
> 
> Signed-off-by: John Daley <johndale@cisco.com>
> ---
> v2: another crack at the comments
> v3: fix typos, rewording, put back a sentence omitted in v2

This version is fine and it clarifies the original intent, it's only missing
associated changes in doc/guides/prog_guide/rte_flow.rst (look for
rte_flow_validate).

Also the commit title could start with "doc:" as there is no API change.

I also have one minor nit, see below.

>  lib/librte_ether/rte_flow.h | 16 +++++++++++-----
>  1 file changed, 11 insertions(+), 5 deletions(-)
> 
> diff --git a/lib/librte_ether/rte_flow.h b/lib/librte_ether/rte_flow.h
> index 8013ecab2..85ce4ec90 100644
> --- a/lib/librte_ether/rte_flow.h
> +++ b/lib/librte_ether/rte_flow.h
> @@ -983,9 +983,11 @@ struct rte_flow_error {
>  /**
>   * Check whether a flow rule can be created on a given port.
>   *
> - * While this function has no effect on the target device, the flow rule is
> - * validated against its current configuration state and the returned value
> - * should be considered valid by the caller for that state only.
> + * The flow rule is validated for correctness and whether it could be accepted
> + * by the device given sufficient resources. The rule is checked against the
> + * current device mode and queue configuration. The flow rule may also
> + * optionally be validated against existing flow rules and device resources.
> + * This function has no effect on the target device.
>   *
>   * The returned value is guaranteed to remain valid only as long as no
>   * successful calls to rte_flow_create() or rte_flow_destroy() are made in
> @@ -1016,9 +1018,13 @@ struct rte_flow_error {
>   *   -ENOTSUP: valid but unsupported rule specification (e.g. partial
>   *   bit-masks are unsupported).
>   *
> - *   -EEXIST: collision with an existing rule.
> + *   -EEXIST: collision with an existing rule. Only returned if device
> + *   supports flow rule collision checking and there was a flow rule
> + *   collision. Not receiving this return code is no guarantee that creating
> + *   the rule will not fail due to a collision.
>   *
> - *   -ENOMEM: not enough resources.
> + *   -ENOMEM: Not enough memory to execute the function, or if the device

"Not" should be lowercase (why, yes, that's all).

> + *   supports resource validation, resource limitation on the device.
>   *
>   *   -EBUSY: action cannot be performed due to busy device resources, may
>   *   succeed if the affected queues or even the entire port are in a stopped
> -- 
> 2.12.0
>