From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.0 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id C9A0DC10F13 for ; Mon, 8 Apr 2019 16:14:43 +0000 (UTC) Received: from dpdk.org (dpdk.org [92.243.14.124]) by mail.kernel.org (Postfix) with ESMTP id 6070B21473 for ; Mon, 8 Apr 2019 16:14:43 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 6070B21473 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=intel.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=dev-bounces@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 227392BCE; Mon, 8 Apr 2019 18:14:42 +0200 (CEST) Received: from mga17.intel.com (mga17.intel.com [192.55.52.151]) by dpdk.org (Postfix) with ESMTP id 9EB112BC9; Mon, 8 Apr 2019 18:14:40 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga107.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 08 Apr 2019 09:14:39 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.60,325,1549958400"; d="scan'208";a="334885757" Received: from sivswdev09.ir.intel.com (HELO localhost.localdomain) ([10.237.217.48]) by fmsmga006.fm.intel.com with ESMTP; 08 Apr 2019 09:14:38 -0700 From: Fiona Trahe 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 , stable@dpdk.org Date: Mon, 8 Apr 2019 17:14:32 +0100 Message-Id: <1554740072-11898-1-git-send-email-fiona.trahe@intel.com> X-Mailer: git-send-email 1.7.0.7 Subject: [dpdk-dev] [PATCH] 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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 --- 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