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 C5033A00E6 for ; Tue, 16 Apr 2019 17:03:04 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 814311B4FE; Tue, 16 Apr 2019 17:03:04 +0200 (CEST) Received: from EUR01-HE1-obe.outbound.protection.outlook.com (mail-eopbgr130089.outbound.protection.outlook.com [40.107.13.89]) by dpdk.org (Postfix) with ESMTP id 314671B4EE; Tue, 16 Apr 2019 17:03:00 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=DwVxz9Jg3/if0SQp9LZvOXQFNazZx4qWQTfWTN1fvnM=; b=q4xe/NmCPbsp4L5WY9J2F9FFwcxUSOu9yjtMRXM1N0i7O8kH5V8cgS34tIhgQAddYFFf5x3+57WAWAtEv0hnRqaUGf/Tt6IH5omGULuUmd0iBs8dgAcK0qQV2ba5TOM2Qe1ELfBWTDbdk+eoAYSMYkDR8thIDCWV18qvZdl6A+g= Received: from VI1PR04MB4893.eurprd04.prod.outlook.com (20.177.49.154) by VI1PR04MB4528.eurprd04.prod.outlook.com (20.177.55.86) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1792.17; Tue, 16 Apr 2019 15:02:58 +0000 Received: from VI1PR04MB4893.eurprd04.prod.outlook.com ([fe80::98b0:84a6:1c08:57c7]) by VI1PR04MB4893.eurprd04.prod.outlook.com ([fe80::98b0:84a6:1c08:57c7%3]) with mapi id 15.20.1792.018; Tue, 16 Apr 2019 15:02:58 +0000 From: Akhil Goyal To: "shallyv@marvell.com" , "ashish.gupta@marvell.com" CC: "lee.daly@intel.com" , "ssahu@marvell.com" , "stable@dpdk.org" , "dev@dpdk.org" , Fiona Trahe Thread-Topic: [PATCH v2] doc/compress: clarify error handling on data-plane Thread-Index: AdT0ZXinNfHQUMG0T3KWMpqVB7g9KQ== Date: Tue, 16 Apr 2019 15:02:57 +0000 Message-ID: Accept-Language: en-IN, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: spf=none (sender IP is ) smtp.mailfrom=akhil.goyal@nxp.com; x-originating-ip: [92.120.1.65] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 6b72e2fd-dd66-458a-e58a-08d6c27c9cbd x-ms-office365-filtering-ht: Tenant x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(4652040)(8989299)(4534185)(4627221)(201703031133081)(201702281549075)(8990200)(5600140)(711020)(4605104)(4618075)(2017052603328)(7193020); SRVR:VI1PR04MB4528; x-ms-traffictypediagnostic: VI1PR04MB4528: x-microsoft-antispam-prvs: x-forefront-prvs: 000947967F x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(136003)(396003)(366004)(376002)(346002)(39860400002)(51234002)(199004)(189003)(6436002)(97736004)(52536014)(53936002)(6246003)(8676002)(14444005)(99286004)(106356001)(229853002)(486006)(256004)(5660300002)(81156014)(110136005)(186003)(66066001)(4326008)(6506007)(105586002)(81166006)(44832011)(7696005)(476003)(55016002)(316002)(26005)(54906003)(9686003)(25786009)(3846002)(6116002)(86362001)(68736007)(2501003)(102836004)(305945005)(71190400001)(71200400001)(7736002)(14454004)(74316002)(2906002)(33656002)(8936002)(478600001); DIR:OUT; SFP:1101; SCL:1; SRVR:VI1PR04MB4528; H:VI1PR04MB4893.eurprd04.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1; received-spf: None (protection.outlook.com: nxp.com does not designate permitted sender hosts) x-ms-exchange-senderadcheck: 1 x-microsoft-antispam-message-info: PFRsAXXSym3lyu6wNOlUZormWdinWpq+9dBpMJtraLU9bhij4Gzc9yoKj+WJ8f6gSu8cQfYRw6daPY0D65Okxd+Yirn+NkHhm8jGCZWupgo8cRcJ9Vg0QJoaI/k/fYoERWt8wyfLvFoqCNESH8voPaz/+6ahd11+Oi+7sk5yeO0WnIid7W8qgl28+oPbyQ5Zqt6dcNZUCW8ESG0/lSDF9cYzOPXyxnY32OH3Sc/QvIP49PkbNDlV41t0ELSGhy0EwIaYvm/l5P+aEOCfZ2JvPJkY6FLwPNgq8O0OArxIlOXWHpvHMVs9AmE6pcxmwtyajC3mcSq3gcS3it0Q06CphmlvW+/GXwQy97ea4aVO51ifZU9+/A8AA3sWsO80m2NpalEzjffhgyjaKAlmGT38Vc/dcqRzF69z+1iUNh2pic4= Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-Network-Message-Id: 6b72e2fd-dd66-458a-e58a-08d6c27c9cbd X-MS-Exchange-CrossTenant-originalarrivaltime: 16 Apr 2019 15:02:57.9306 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR04MB4528 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 Shally/Ashish, Could you please review this patch. Thanks, Akhil >=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 wi= ll > 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``. F= or > any error which > +can occur in a production environment and can be successful after a retr= y 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 suc= cessful. > + > +- 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 expecte= d to > arise during > +development. As a retry with the same op won't be successful, if a perfo= rmant > 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= ) > +- 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 infin= ite loop. > + > 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 > -- > 2.13.6