Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/52430/?format=api
{ "id": 52430, "url": "https://patches.dpdk.org/api/patches/52430/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/1554740072-11898-1-git-send-email-fiona.trahe@intel.com/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<1554740072-11898-1-git-send-email-fiona.trahe@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/1554740072-11898-1-git-send-email-fiona.trahe@intel.com", "date": "2019-04-08T16:14:32", "name": "doc/compress: clarify error handling on data-plane", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "d46ca1883fe33df5fea04952fcd75f3ea481b46d", "submitter": { "id": 423, "url": "https://patches.dpdk.org/api/people/423/?format=api", "name": "Fiona Trahe", "email": "fiona.trahe@intel.com" }, "delegate": { "id": 6690, "url": "https://patches.dpdk.org/api/users/6690/?format=api", "username": "akhil", "first_name": "akhil", "last_name": "goyal", "email": "gakhil@marvell.com" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/1554740072-11898-1-git-send-email-fiona.trahe@intel.com/mbox/", "series": [ { "id": 4183, "url": "https://patches.dpdk.org/api/series/4183/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=4183", "date": "2019-04-08T16:14:32", "name": "doc/compress: clarify error handling on data-plane", "version": 1, "mbox": "https://patches.dpdk.org/series/4183/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/52430/comments/", "check": "success", "checks": "https://patches.dpdk.org/api/patches/52430/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@dpdk.org", "Delivered-To": "patchwork@dpdk.org", "Received": [ "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id 227392BCE;\n\tMon, 8 Apr 2019 18:14:42 +0200 (CEST)", "from mga17.intel.com (mga17.intel.com [192.55.52.151])\n\tby dpdk.org (Postfix) with ESMTP id 9EB112BC9;\n\tMon, 8 Apr 2019 18:14:40 +0200 (CEST)", "from fmsmga006.fm.intel.com ([10.253.24.20])\n\tby fmsmga107.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;\n\t08 Apr 2019 09:14:39 -0700", "from sivswdev09.ir.intel.com (HELO localhost.localdomain)\n\t([10.237.217.48])\n\tby fmsmga006.fm.intel.com with ESMTP; 08 Apr 2019 09:14:38 -0700" ], "X-Amp-Result": "SKIPPED(no attachment in message)", "X-Amp-File-Uploaded": "False", "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.60,325,1549958400\"; d=\"scan'208\";a=\"334885757\"", "From": "Fiona Trahe <fiona.trahe@intel.com>", "To": "dev@dpdk.org", "Cc": "akhil.goyal@nxp.com, ashish.gupta@marvell.com, lee.daly@intel.com,\n\tssahu@marvell.com, shallyv@marvell.com,\n\tFiona Trahe <fiona.trahe@intel.com>, 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\n\tdata-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>,\n\t<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>,\n\t<mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Fixed some typos and clarified which errors should be returned\nwhen and why on the enqueue and dequeue APIs.\n\nFixes: a584d3bea902 (\"doc: add compressdev library guide\")\ncc: stable@dpdk.org\n\nSigned-off-by: Fiona Trahe <fiona.trahe@intel.com>\n---\n doc/guides/prog_guide/compressdev.rst | 44 +++++++++++++++++++++++++++++++++--\n 1 file changed, 42 insertions(+), 2 deletions(-)", "diff": "diff --git a/doc/guides/prog_guide/compressdev.rst b/doc/guides/prog_guide/compressdev.rst\nindex ad9703753..09893fa4a 100644\n--- a/doc/guides/prog_guide/compressdev.rst\n+++ b/doc/guides/prog_guide/compressdev.rst\n@@ -201,7 +201,7 @@ for stateful processing of ops.\n Operation Status\n ~~~~~~~~~~~~~~~~\n Each operation carries a status information updated by PMD after it is processed.\n-following are currently supported status:\n+Following are currently supported:\n \n - RTE_COMP_OP_STATUS_SUCCESS,\n Operation is successfully completed\n@@ -227,13 +227,53 @@ following are currently supported status:\n is not an error case. Output data up to op.produced can be used and\n next op in the stream should continue on from op.consumed+1.\n \n+Operation status after enqueue / dequeue\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Some of the above values will only arise in the op after an\n+``rte_compressdev_enqueue_burst()``, some only after an\n+``rte_compressdev_dequeue_burst()``. For optimal performance on the data-plane an\n+application is not expected to check the ``op.status`` of all ops after both enqueue and dequeue,\n+it should be sufficient to only check after dequeue. To facilitate this optimisation, most errors\n+which may reasonably be expected to occur in a production environment will be returned by\n+the PMD on the ``dequeue``.\n+op.status may hold the following values after dequeue:\n+\n+- RTE_COMP_OP_STATUS_SUCCESS\n+- RTE_COMP_OP_STATUS_ERROR\n+- RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED\n+- RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE\n+\n+There are some exceptions whereby errors can occur on the ``enqueue``. For any error which\n+can occur in a production environment and can be successful after a retry with the same op the\n+PMD may return the error on the enqueue. So if less than the full burst is enqueued there's no\n+need for the application to check op.status - the application can simply retry in a later enqueue\n+and expect success. Though the application is not expected to check for these, the\n+values are as follows:\n+\n+- 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.\n+\n+- RTE_COMP_OP_STATUS_ERROR - could occur due to out-of-memory or other transient condition which could clear after a time.\n+\n+Other errors may also occur on an ``enqueue``, but they are only expected to arise during\n+development. As a retry with the same op won't be successful, if a performant application\n+wants to avoid checking op.status on the enqueue it should ensure these never arise in a\n+production environment, e.g. by checking device capabilities and validating input parameters\n+before sending operations. Examples are:\n+\n+- RTE_COMP_OP_STATUS_INVALID_ARGS\n+- RTE_COMP_OP_STATUS_ERROR (if due to a condition which is not transient)\n+- RTE_COMP_OP_STATUS_INVALID_STATE\n+\n+If an application doesn't safeguard against these AND doesn't check the op.status of the next\n+op which was not enqueued, but just retries, it could result in an infinite loop.\n+\n Produced, Consumed And Operation Status\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n - If status is RTE_COMP_OP_STATUS_SUCCESS,\n consumed = amount of data read from input buffer, and\n produced = amount of data written in destination buffer\n-- If status is RTE_COMP_OP_STATUS_FAILURE,\n+- If status is RTE_COMP_OP_STATUS_ERROR,\n consumed = produced = 0 or undefined\n - If status is RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED,\n consumed = 0 and\n", "prefixes": [] }