patches for DPDK stable branches
 help / color / mirror / Atom feed
* [dpdk-stable] [PATCH] doc/compress: clarify error handling on data-plane
@ 2019-04-08 16:14 Fiona Trahe
  2019-04-09 14:55 ` [dpdk-stable] [PATCH v2] " Fiona Trahe
  0 siblings, 1 reply; 17+ messages in thread
From: Fiona Trahe @ 2019-04-08 16:14 UTC (permalink / raw)
  To: dev
  Cc: akhil.goyal, ashish.gupta, lee.daly, ssahu, shallyv, Fiona Trahe, stable

Fixed some typos and clarified which errors should be returned
when and why on the enqueue and dequeue APIs.

Fixes: a584d3bea902 ("doc: add compressdev library guide")
cc: stable@dpdk.org

Signed-off-by: Fiona Trahe <fiona.trahe@intel.com>
---
 doc/guides/prog_guide/compressdev.rst | 44 +++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/doc/guides/prog_guide/compressdev.rst b/doc/guides/prog_guide/compressdev.rst
index ad9703753..09893fa4a 100644
--- a/doc/guides/prog_guide/compressdev.rst
+++ b/doc/guides/prog_guide/compressdev.rst
@@ -201,7 +201,7 @@ for stateful processing of ops.
 Operation Status
 ~~~~~~~~~~~~~~~~
 Each operation carries a status information updated by PMD after it is processed.
-following are currently supported status:
+Following are currently supported:
 
 - RTE_COMP_OP_STATUS_SUCCESS,
     Operation is successfully completed
@@ -227,13 +227,53 @@ following are currently supported status:
     is not an error case. Output data up to op.produced can be used and
     next op in the stream should continue on from op.consumed+1.
 
+Operation status after enqueue / dequeue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Some of the above values will only arise in the op after an
+``rte_compressdev_enqueue_burst()``, some only after an
+``rte_compressdev_dequeue_burst()``. For optimal performance on the data-plane an
+application is not expected to check the ``op.status`` of all ops after both enqueue and dequeue,
+it should be sufficient to only check after dequeue. To facilitate this optimisation, most errors
+which may reasonably be expected to occur in a production environment will be returned by
+the PMD on the ``dequeue``.
+op.status may hold the following values after dequeue:
+
+- RTE_COMP_OP_STATUS_SUCCESS
+- RTE_COMP_OP_STATUS_ERROR
+- RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED
+- RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE
+
+There are some exceptions whereby errors can occur on the ``enqueue``. For any error which
+can occur in a production environment and can be successful after a retry with the same op the
+PMD may return the error on the enqueue. So if less than the full burst is enqueued there's no
+need for the application to check op.status - the application can simply retry in a later enqueue
+and expect success. Though the application is not expected to check for these, the
+values are as follows:
+
+- RTE_COMP_OP_STATUS_NOT_PROCESSED  - could occur if a hardware device's queue is full, after a dequeue a retry of the enqueue can be successful.
+
+- RTE_COMP_OP_STATUS_ERROR - could occur due to out-of-memory or other transient condition which could clear after a time.
+
+Other errors may also occur on an ``enqueue``, but they are only expected to arise during
+development. As a retry with the same op won't be successful, if a performant application
+wants to avoid checking op.status on the enqueue it should ensure these never arise in a
+production environment, e.g. by checking device capabilities and validating input parameters
+before sending operations. Examples are:
+
+- RTE_COMP_OP_STATUS_INVALID_ARGS
+- RTE_COMP_OP_STATUS_ERROR (if due to a condition which is not transient)
+- RTE_COMP_OP_STATUS_INVALID_STATE
+
+If an application doesn't safeguard against these AND doesn't check the op.status of the next
+op which was not enqueued, but just retries, it could result in an infinite loop.
+
 Produced, Consumed And Operation Status
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - If status is RTE_COMP_OP_STATUS_SUCCESS,
     consumed = amount of data read from input buffer, and
     produced = amount of data written in destination buffer
-- If status is RTE_COMP_OP_STATUS_FAILURE,
+- If status is RTE_COMP_OP_STATUS_ERROR,
     consumed = produced = 0 or undefined
 - If status is RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED,
     consumed = 0 and
-- 
2.13.6


^ permalink raw reply	[flat|nested] 17+ messages in thread
* Re: [dpdk-stable] [PATCH v2] doc/compress: clarify error handling on data-plane
@ 2019-04-16 15:02 Akhil Goyal
  0 siblings, 0 replies; 17+ messages in thread
From: Akhil Goyal @ 2019-04-16 15:02 UTC (permalink / raw)
  To: shallyv, ashish.gupta; +Cc: lee.daly, ssahu, stable, dev, Fiona Trahe

Hi Shally/Ashish,
Could you please review this patch.

Thanks,
Akhil
> 
> Fixed some typos and clarified which errors should be returned
> when and why on the enqueue and dequeue APIs.
> 
> Fixes: a584d3bea902 ("doc: add compressdev library guide")
> cc: stable@dpdk.org
> 
> Signed-off-by: Fiona Trahe <fiona.trahe@intel.com>
> ---
> v2 changes:
>  - changed "0 or undefined" to just "undefined" as 0 is superfluous.
> 
> 
>  doc/guides/prog_guide/compressdev.rst | 46
> ++++++++++++++++++++++++++++++++---
>  1 file changed, 43 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/compressdev.rst
> b/doc/guides/prog_guide/compressdev.rst
> index ad9703753..c700dd103 100644
> --- a/doc/guides/prog_guide/compressdev.rst
> +++ b/doc/guides/prog_guide/compressdev.rst
> @@ -201,7 +201,7 @@ for stateful processing of ops.
>  Operation Status
>  ~~~~~~~~~~~~~~~~
>  Each operation carries a status information updated by PMD after it is
> processed.
> -following are currently supported status:
> +Following are currently supported:
> 
>  - RTE_COMP_OP_STATUS_SUCCESS,
>      Operation is successfully completed
> @@ -227,14 +227,54 @@ following are currently supported status:
>      is not an error case. Output data up to op.produced can be used and
>      next op in the stream should continue on from op.consumed+1.
> 
> +Operation status after enqueue / dequeue
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Some of the above values will only arise in the op after an
> +``rte_compressdev_enqueue_burst()``, some only after an
> +``rte_compressdev_dequeue_burst()``. For optimal performance on the data-
> plane an
> +application is not expected to check the ``op.status`` of all ops after both
> enqueue and dequeue,
> +it should be sufficient to only check after dequeue. To facilitate this
> optimisation, most errors
> +which may reasonably be expected to occur in a production environment will
> be returned by
> +the PMD on the ``dequeue``.
> +op.status may hold the following values after dequeue:
> +
> +- RTE_COMP_OP_STATUS_SUCCESS
> +- RTE_COMP_OP_STATUS_ERROR
> +- RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED
> +- RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE
> +
> +There are some exceptions whereby errors can occur on the ``enqueue``. For
> any error which
> +can occur in a production environment and can be successful after a retry with
> the same op the
> +PMD may return the error on the enqueue. So if less than the full burst is
> enqueued there's no
> +need for the application to check op.status - the application can simply retry in
> a later enqueue
> +and expect success. Though the application is not expected to check for these,
> the
> +values are as follows:
> +
> +- RTE_COMP_OP_STATUS_NOT_PROCESSED  - could occur if a hardware
> device's queue is full, after a dequeue a retry of the enqueue can be successful.
> +
> +- RTE_COMP_OP_STATUS_ERROR - could occur due to out-of-memory or
> other transient condition which could clear after a time.
> +
> +Other errors may also occur on an ``enqueue``, but they are only expected to
> arise during
> +development. As a retry with the same op won't be successful, if a performant
> application
> +wants to avoid checking op.status on the enqueue it should ensure these never
> arise in a
> +production environment, e.g. by checking device capabilities and validating
> input parameters
> +before sending operations. Examples are:
> +
> +- RTE_COMP_OP_STATUS_INVALID_ARGS
> +- RTE_COMP_OP_STATUS_ERROR (if due to a condition which is not transient)
> +- RTE_COMP_OP_STATUS_INVALID_STATE
> +
> +If an application doesn't safeguard against these AND doesn't check the
> op.status of the next
> +op which was not enqueued, but just retries, it could result in an infinite loop.
> +
>  Produced, Consumed And Operation Status
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 
>  - If status is RTE_COMP_OP_STATUS_SUCCESS,
>      consumed = amount of data read from input buffer, and
>      produced = amount of data written in destination buffer
> -- If status is RTE_COMP_OP_STATUS_FAILURE,
> -    consumed = produced = 0 or undefined
> +- If status is RTE_COMP_OP_STATUS_ERROR,
> +    consumed = produced = undefined
>  - If status is RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED,
>      consumed = 0 and
>      produced = usually 0, but in decompression cases a PMD may return > 0
> --
> 2.13.6


^ permalink raw reply	[flat|nested] 17+ messages in thread

end of thread, other threads:[~2019-06-19 14:57 UTC | newest]

Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-04-08 16:14 [dpdk-stable] [PATCH] doc/compress: clarify error handling on data-plane Fiona Trahe
2019-04-09 14:55 ` [dpdk-stable] [PATCH v2] " Fiona Trahe
2019-04-18 12:12   ` Shally Verma
2019-04-30 16:33     ` Trahe, Fiona
2019-05-07 17:14       ` Shally Verma
2019-05-07 18:24         ` Trahe, Fiona
2019-05-08 12:41           ` Shally Verma
2019-05-08 14:00             ` Trahe, Fiona
2019-05-09  8:58               ` Akhil Goyal
2019-05-09 10:44   ` Shally Verma
2019-05-14 15:29     ` Trahe, Fiona
2019-05-14 15:37       ` Shally Verma
2019-05-15 11:16   ` [dpdk-stable] [PATCH v3] " Fiona Trahe
2019-05-15 11:43     ` Jozwiak, TomaszX
2019-05-15 12:03     ` Shally Verma
2019-06-19 14:57       ` Akhil Goyal
2019-04-16 15:02 [dpdk-stable] [PATCH v2] " Akhil Goyal

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).