From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by dpdk.space (Postfix) with ESMTP id 398B7A00E6 for ; Thu, 18 Apr 2019 14:12:29 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 18BB01B9DD; Thu, 18 Apr 2019 14:12:29 +0200 (CEST) Received: from mx0b-0016f401.pphosted.com (mx0a-0016f401.pphosted.com [67.231.148.174]) by dpdk.org (Postfix) with ESMTP id 80B461B9D4; Thu, 18 Apr 2019 14:12:25 +0200 (CEST) Received: from pps.filterd (m0045849.ppops.net [127.0.0.1]) by mx0a-0016f401.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x3IC08F0013370; Thu, 18 Apr 2019 05:12:24 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.com; h=from : to : cc : subject : date : message-id : references : in-reply-to : content-type : content-transfer-encoding : mime-version; s=pfpt0818; bh=ceS4YiwuG2Ys/xRWSapWLbhfIyIjp5Ss/GMJqkf5LFc=; b=qoxndgGQHa8D3s3J3g8fHNaR5BsuMQX/junAx81xL7cJ5aVOnj+SlsuySONG0xR5YVKs 7MtGm3hVLECdhM32SNcdKDnGSOAMci88u2h1u1sFtanun4m2z5sfOB7YlOaZI1uT3q2j tjLwK4L3FFDuJ/ACC4PJbK+uzmkNzqy4xJKXTgXI5823qPXbX6DbHgTkiAFhSAnr+L1X dRPnD2Q773lVVnrbTO61yBJRX6naDTKmVMQVxRyQDP3IU6uK5nFi0n/3qigHoY6dt7gQ 5Wk+ggCGqgAhVZhCpX/LhalbMKO9mUUY1HqicemAjI0mXbtTTn1cUtMWDgBc3GibsGhF WA== Received: from sc-exch01.marvell.com ([199.233.58.181]) by mx0a-0016f401.pphosted.com with ESMTP id 2rxmp1h15n-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT); Thu, 18 Apr 2019 05:12:24 -0700 Received: from SC-EXCH03.marvell.com (10.93.176.83) by SC-EXCH01.marvell.com (10.93.176.81) with Microsoft SMTP Server (TLS) id 15.0.1367.3; Thu, 18 Apr 2019 05:12:23 -0700 Received: from NAM01-SN1-obe.outbound.protection.outlook.com (104.47.32.57) by SC-EXCH03.marvell.com (10.93.176.83) with Microsoft SMTP Server (TLS) id 15.0.1367.3 via Frontend Transport; Thu, 18 Apr 2019 05:12:23 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=marvell.onmicrosoft.com; s=selector1-marvell-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=ceS4YiwuG2Ys/xRWSapWLbhfIyIjp5Ss/GMJqkf5LFc=; b=lnH5Mzuq+zlR7fIuFPA6AXbiJmuKB+WQou0IgdeSm6uKw0ls2QlWfaOE7R/1EuRiDyEMiwLLr6pIgJhuVqnh2EhlE7FucoXXR7DxmM+opzsBTE4wJjqSdSHWlyoo2NS/lrqlQd/vO53Z63I3E4qs1Tlf39yIC33vlJS23vQyRSM= Received: from BN6PR1801MB2052.namprd18.prod.outlook.com (10.161.157.11) by BN6PR1801MB1953.namprd18.prod.outlook.com (10.161.155.18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1813.12; Thu, 18 Apr 2019 12:12:21 +0000 Received: from BN6PR1801MB2052.namprd18.prod.outlook.com ([fe80::20c9:bb0e:2024:6af]) by BN6PR1801MB2052.namprd18.prod.outlook.com ([fe80::20c9:bb0e:2024:6af%5]) with mapi id 15.20.1813.011; Thu, 18 Apr 2019 12:12:21 +0000 From: Shally Verma To: Fiona Trahe , "dev@dpdk.org" CC: "akhil.goyal@nxp.com" , Ashish Gupta , "lee.daly@intel.com" , Sunila Sahu , "stable@dpdk.org" Thread-Topic: [PATCH v2] doc/compress: clarify error handling on data-plane Thread-Index: AQHU7uRcY1b0dFOFhkSSkiDYaczK7aZB3cyw Date: Thu, 18 Apr 2019 12:12:21 +0000 Message-ID: References: <1554740072-11898-1-git-send-email-fiona.trahe@intel.com> <1554821747-27868-1-git-send-email-fiona.trahe@intel.com> In-Reply-To: <1554821747-27868-1-git-send-email-fiona.trahe@intel.com> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [115.113.156.2] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 4771e058-9ffe-4433-e1db-08d6c3f71c11 x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(4652040)(8989299)(5600141)(711020)(4605104)(4534185)(7168020)(4627221)(201703031133081)(201702281549075)(8990200)(2017052603328)(7193020); SRVR:BN6PR1801MB1953; x-ms-traffictypediagnostic: BN6PR1801MB1953: x-microsoft-antispam-prvs: x-forefront-prvs: 0011612A55 x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(39860400002)(346002)(376002)(396003)(136003)(366004)(199004)(189003)(13464003)(51234002)(71200400001)(71190400001)(2501003)(55016002)(102836004)(256004)(76176011)(6246003)(68736007)(53936002)(446003)(14444005)(52536014)(305945005)(97736004)(8676002)(11346002)(476003)(86362001)(5660300002)(3846002)(26005)(53546011)(186003)(99286004)(6116002)(4326008)(25786009)(7696005)(55236004)(6506007)(316002)(66066001)(81166006)(9686003)(486006)(229853002)(110136005)(54906003)(74316002)(14454004)(8936002)(478600001)(2906002)(81156014)(33656002)(6436002)(7736002); DIR:OUT; SFP:1101; SCL:1; SRVR:BN6PR1801MB1953; H:BN6PR1801MB2052.namprd18.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1; received-spf: None (protection.outlook.com: marvell.com does not designate permitted sender hosts) x-ms-exchange-senderadcheck: 1 x-microsoft-antispam-message-info: EFnwoA2N3ui7Yx+XkDN230fmlYP7cdAdBsOozpzWjhvwbwaS9d75GkfJcBZeXkVqGes8vyA5XGV1YdF6wF613phowJP6bH7pan+klqwQ3u59/58Lb8mrTRhK+zOJwtxwEnq06bp3GfFkTRd3XczRRmGxl8az0U6gjbVm89ZOUmk/DpIzqFaw4URHGY1g9Qff5fRAmISiv6iMQes7Oqs96ENkls4X0hHyAjbidWptB/aKk0itwI6yLOoY87ZgUn714fd1nzjbZqVHK+lCMhf3sFu68jVoFwtZg5PCW7NMdMqtjHP0ZcLahdds/R2kT4jtmJQo5wDSHZvdIkIkaJG1WEITxmwcNP0AEzkb/2xXdCjIBi8h4WPGcqksjfUeV99iJ3wc1ktXHp6lYI4rQRynqgy79/+O6VDZA8E7zGdKHb4= Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-MS-Exchange-CrossTenant-Network-Message-Id: 4771e058-9ffe-4433-e1db-08d6c3f71c11 X-MS-Exchange-CrossTenant-originalarrivaltime: 18 Apr 2019 12:12:21.3945 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 70e1fb47-1155-421d-87fc-2e58f638b6e0 X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-Transport-CrossTenantHeadersStamped: BN6PR1801MB1953 X-OriginatorOrg: marvell.com X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2019-04-18_06:, , signatures=0 Subject: Re: [dpdk-stable] [PATCH v2] doc/compress: clarify error handling on data-plane X-BeenThere: stable@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches for DPDK stable branches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: stable-bounces@dpdk.org Sender: "stable" Hi Fiona, > -----Original Message----- > From: Fiona Trahe > Sent: Tuesday, April 9, 2019 8:26 PM > To: dev@dpdk.org > Cc: akhil.goyal@nxp.com; Ashish Gupta ; > lee.daly@intel.com; Sunila Sahu ; Shally Verma > ; Fiona Trahe ; > stable@dpdk.org > Subject: [PATCH v2] doc/compress: clarify error handling on data-plane >=20 > Fixed some typos and clarified which errors should be returned when and > why on the enqueue and dequeue APIs. >=20 > Fixes: a584d3bea902 ("doc: add compressdev library guide") > cc: stable@dpdk.org >=20 > Signed-off-by: Fiona Trahe > --- > v2 changes: > - changed "0 or undefined" to just "undefined" as 0 is superfluous. >=20 >=20 > doc/guides/prog_guide/compressdev.rst | 46 > ++++++++++++++++++++++++++++++++--- > 1 file changed, 43 insertions(+), 3 deletions(-) >=20 > 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: >=20 > - 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. >=20 > +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.=20 This statement looks bit confusing.=20 Seems like we are trying to add a description regarding op status check eve= n after the enqueue call unlike current scenario, where app only check for = it after dequeue? 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 applicati= on > 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 validat= ing > 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) How does app identify error is transient or permanent? =20 > +- 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 co= uld > result in an infinite loop. > + May be , you are trying to insist whenever the number_enqueued ops < number= actually enqueued , then caller should check for status of num_enqueued + = 1th op to know exact reason, and=20 take corrective measure before re-enqueuing it for following status conditi= on: 1. INVALID_ARGS=20 2. INVALID_STATE 3 ERROR=20 Is that correct? > Produced, Consumed And Operation Status > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >=20 > - If status is RTE_COMP_OP_STATUS_SUCCESS, > consumed =3D amount of data read from input buffer, and > produced =3D amount of data written in destination buffer > -- If status is RTE_COMP_OP_STATUS_FAILURE, > - consumed =3D produced =3D 0 or undefined > +- If status is RTE_COMP_OP_STATUS_ERROR, > + consumed =3D produced =3D undefined > - If status is RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED, > consumed =3D 0 and > produced =3D usually 0, but in decompression cases a PMD may return = > 0 > -- Acked. > 2.13.6