From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from dpdk.org (dpdk.org [92.243.14.124])
by dpdk.space (Postfix) with ESMTP id A933AA0096
for <public@inbox.dpdk.org>; Tue, 9 Apr 2019 16:55:57 +0200 (CEST)
Received: from [92.243.14.124] (localhost [127.0.0.1])
by dpdk.org (Postfix) with ESMTP id A52A754AE;
Tue, 9 Apr 2019 16:55:57 +0200 (CEST)
Received: from mga02.intel.com (mga02.intel.com [134.134.136.20])
by dpdk.org (Postfix) with ESMTP id 2663C548B;
Tue, 9 Apr 2019 16:55:56 +0200 (CEST)
X-Amp-Result: SKIPPED(no attachment in message)
X-Amp-File-Uploaded: False
Received: from orsmga006.jf.intel.com ([10.7.209.51])
by orsmga101.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;
09 Apr 2019 07:55:54 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.60,329,1549958400"; d="scan'208";a="134273227"
Received: from sivswdev09.ir.intel.com (HELO localhost.localdomain)
([10.237.217.48])
by orsmga006.jf.intel.com with ESMTP; 09 Apr 2019 07:55:52 -0700
From: Fiona Trahe <fiona.trahe@intel.com>
To: dev@dpdk.org
Cc: akhil.goyal@nxp.com, ashish.gupta@marvell.com, lee.daly@intel.com,
ssahu@marvell.com, shallyv@marvell.com,
Fiona Trahe <fiona.trahe@intel.com>, stable@dpdk.org
Date: Tue, 9 Apr 2019 15:55:47 +0100
Message-Id: <1554821747-27868-1-git-send-email-fiona.trahe@intel.com>
X-Mailer: git-send-email 1.7.0.7
In-Reply-To: <1554740072-11898-1-git-send-email-fiona.trahe@intel.com>
References: <1554740072-11898-1-git-send-email-fiona.trahe@intel.com>
Subject: [dpdk-dev] [PATCH v2] doc/compress: clarify error handling on
data-plane
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>
Content-Type: text/plain; charset="UTF-8"
Message-ID: <20190409145547.Ypc06f267TwzNPDYQuRvIiGWdoXEomSJX61xu1uBiB4@z>
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