From: Akhil Goyal <akhil.goyal@nxp.com>
To: "shallyv@marvell.com" <shallyv@marvell.com>,
"ashish.gupta@marvell.com" <ashish.gupta@marvell.com>
Cc: "lee.daly@intel.com" <lee.daly@intel.com>,
"ssahu@marvell.com" <ssahu@marvell.com>,
"stable@dpdk.org" <stable@dpdk.org>,
"dev@dpdk.org" <dev@dpdk.org>,
Fiona Trahe <fiona.trahe@intel.com>
Subject: Re: [dpdk-stable] [PATCH v2] doc/compress: clarify error handling on data-plane
Date: Tue, 16 Apr 2019 15:02:57 +0000 [thread overview]
Message-ID: <VI1PR04MB48934BDA409452B4DC25FBCEE6240@VI1PR04MB4893.eurprd04.prod.outlook.com> (raw)
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
next reply other threads:[~2019-04-16 15:03 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-16 15:02 Akhil Goyal [this message]
-- strict thread matches above, loose matches on Subject: below --
2019-04-08 16:14 [dpdk-stable] [PATCH] " 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=VI1PR04MB48934BDA409452B4DC25FBCEE6240@VI1PR04MB4893.eurprd04.prod.outlook.com \
--to=akhil.goyal@nxp.com \
--cc=ashish.gupta@marvell.com \
--cc=dev@dpdk.org \
--cc=fiona.trahe@intel.com \
--cc=lee.daly@intel.com \
--cc=shallyv@marvell.com \
--cc=ssahu@marvell.com \
--cc=stable@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).