[dpdk-dev,v4] doc: fix flow validate comments
Checks
Commit Message
Change comments for rte_flow_validate() function to indicate that flow
rule collision and resource validation is optional for PMDs 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
v4: fixes per Adrien Mazarguil- update guide, typo, commit title
doc/guides/prog_guide/rte_flow.rst | 17 ++++++++++++-----
lib/librte_ether/rte_flow.h | 16 +++++++++++-----
2 files changed, 23 insertions(+), 10 deletions(-)
Comments
On Thu, Apr 20, 2017 at 11:49:33AM -0700, John Daley wrote:
> Change comments for rte_flow_validate() function to indicate that flow
> rule collision and resource validation is optional for PMDs and
> therefore the return codes may have different meanings.
>
> Fixes: b1a4b4cbc0a8 ("ethdev: introduce generic flow API")
>
> Signed-off-by: John Daley <johndale@cisco.com>
One last nit below (not sure if you need to send a new version). In any
case:
Acked-by: Adrien Mazarguil <adrien.mazarguil@6wind.com>
[...]
> @@ -1360,8 +1362,13 @@ Return values:
> - ``-EINVAL``: unknown or invalid rule specification.
> - ``-ENOTSUP``: valid but unsupported rule specification (e.g. partial
> bit-masks are unsupported).
> -- ``-EEXIST``: collision with an existing rule.
> -- ``-ENOMEM``: not enough resources.
> +- ``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 memory to execute the function, or if the device
> + supports resource validation, resource limitation on the device.
> +
This new empty line should be removed.
> - ``-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
> state (see ``rte_eth_dev_rx_queue_stop()`` and ``rte_eth_dev_stop()``).
[...]
Thanks.
21/04/2017 10:11, Adrien Mazarguil:
> On Thu, Apr 20, 2017 at 11:49:33AM -0700, John Daley wrote:
> > Change comments for rte_flow_validate() function to indicate that flow
> > rule collision and resource validation is optional for PMDs and
> > therefore the return codes may have different meanings.
> >
> > Fixes: b1a4b4cbc0a8 ("ethdev: introduce generic flow API")
> >
> > Signed-off-by: John Daley <johndale@cisco.com>
>
> One last nit below (not sure if you need to send a new version). In any
> case:
>
> Acked-by: Adrien Mazarguil <adrien.mazarguil@6wind.com>
Applied (with empty line removed), thanks
@@ -1332,9 +1332,11 @@ supported and can be created.
const struct rte_flow_action actions[],
struct rte_flow_error *error);
-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
@@ -1360,8 +1362,13 @@ Return values:
- ``-EINVAL``: unknown or invalid rule specification.
- ``-ENOTSUP``: valid but unsupported rule specification (e.g. partial
bit-masks are unsupported).
-- ``-EEXIST``: collision with an existing rule.
-- ``-ENOMEM``: not enough resources.
+- ``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 memory to execute the function, or if the device
+ 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
state (see ``rte_eth_dev_rx_queue_stop()`` and ``rte_eth_dev_stop()``).
@@ -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
+ * 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