From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mx0b-0016f401.pphosted.com (mx0b-0016f401.pphosted.com [67.231.156.173]) by dpdk.org (Postfix) with ESMTP id 0D07A34F0; Thu, 9 May 2019 12:44:53 +0200 (CEST) Received: from pps.filterd (m0045851.ppops.net [127.0.0.1]) by mx0b-0016f401.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x49AUnj9000929; Thu, 9 May 2019 03:44:53 -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=n7DXs7hH8DC3KD8Mb9FD3/BzrMNoRaspCGbTbm0Y0PM=; b=NHkWjpIf4mel/6p6OcTJdwiCwLMjMpTK4mWyCS4oKCYCJ/npT6iVmNINlTQEycBFvZKZ qGYZiR3cD1Hyj9MnkbYuojnwH0e2Jekq2R07D1ddO+Yk55ZFLFEUAoknhESDpmq3MIZX ww/3jNE3RC1nF8xNm/n8cgM4nyH1uN4Qw9b/8wun+Q18Ab82zYQ0bW1cfNVp8IVEM79X XGprsonLbMokb5pXorha0N1ZmvjxSpbYEpcnJC+14vefdfqR+8KyLmbIpqtXCtzPqR/o 1ufGtYP7Le1Ioz1HBVXgNjRg8j/zn5D6VEbxb8z1Cb4xOO9jzBcsfRaDjfVoNt/RtDrE uw== Received: from sc-exch03.marvell.com ([199.233.58.183]) by mx0b-0016f401.pphosted.com with ESMTP id 2scadra2et-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT); Thu, 09 May 2019 03:44:53 -0700 Received: from SC-EXCH03.marvell.com (10.93.176.83) by SC-EXCH03.marvell.com (10.93.176.83) with Microsoft SMTP Server (TLS) id 15.0.1367.3; Thu, 9 May 2019 03:44:51 -0700 Received: from NAM02-SN1-obe.outbound.protection.outlook.com (104.47.36.56) by SC-EXCH03.marvell.com (10.93.176.83) with Microsoft SMTP Server (TLS) id 15.0.1367.3 via Frontend Transport; Thu, 9 May 2019 03:44:51 -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=n7DXs7hH8DC3KD8Mb9FD3/BzrMNoRaspCGbTbm0Y0PM=; b=HHYxBVsvIFtbIzVz5jk2AagP5kEekgpx72P190+2/XY/lBcdH3+WrdnqPjLbFLVJJ6cK6MytuWpHWIuEZDX6eQwJn3bEtLtxQ5k7WHMQ5roqaopNAPbE9UMFI9GqL0jiP3PszYeTcqQv+Dwt0U6iHnF8NUuTIqfadw8AGvhbWDI= Received: from BN6PR1801MB2052.namprd18.prod.outlook.com (10.161.157.11) by BN6PR1801MB2033.namprd18.prod.outlook.com (10.161.154.24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1856.12; Thu, 9 May 2019 10:44:46 +0000 Received: from BN6PR1801MB2052.namprd18.prod.outlook.com ([fe80::99fe:90b9:ca17:a552]) by BN6PR1801MB2052.namprd18.prod.outlook.com ([fe80::99fe:90b9:ca17:a552%6]) with mapi id 15.20.1856.012; Thu, 9 May 2019 10:44:46 +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: AQHU7uRcY1b0dFOFhkSSkiDYaczK7aZitxdA Date: Thu, 9 May 2019 10:44:46 +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: 0b30a727-ba08-435e-29b3-08d6d46b5a81 x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(4652040)(8989299)(4534185)(7168020)(4627221)(201703031133081)(201702281549075)(8990200)(5600141)(711020)(4605104)(2017052603328)(7193020); SRVR:BN6PR1801MB2033; x-ms-traffictypediagnostic: BN6PR1801MB2033: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:9508; x-forefront-prvs: 003245E729 x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(366004)(346002)(136003)(396003)(376002)(39860400002)(51234002)(189003)(13464003)(199004)(74316002)(99286004)(6506007)(6436002)(5660300002)(68736007)(55236004)(486006)(229853002)(102836004)(2501003)(4326008)(86362001)(76176011)(6246003)(110136005)(316002)(256004)(7736002)(54906003)(14444005)(55016002)(53936002)(53546011)(305945005)(478600001)(7696005)(8936002)(81156014)(14454004)(81166006)(476003)(2906002)(9686003)(66446008)(64756008)(25786009)(66556008)(71200400001)(71190400001)(8676002)(446003)(3846002)(11346002)(66946007)(76116006)(66476007)(66066001)(73956011)(33656002)(26005)(52536014)(186003)(6116002); DIR:OUT; SFP:1101; SCL:1; SRVR:BN6PR1801MB2033; H:BN6PR1801MB2052.namprd18.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; MX:1; A: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: hZbEIP+thH+H4Xj3tyQ8lSupvPHU78xvtgI97U7kOoJ2R2mndhdSLk7Hb5sHnLjzIek3ZYbqUTQ2XRmrpJm6WD8j5rh7FkLljEuFT2+y1QkaYuJf3erijBycytCz6TX4AwsKMinDNGH9bXzA6McQpbwFYo9u8kbMA0UZpnqMLuVfPia8JMelhZWx/jD9WDvX0W3qHK0SOZT/cJa1P0F2Ht0s5yiTHcMAEg1wrRke6Bx8IJCRbCA0KeXYh/YDg+I+rq/qGoYCIF7G3hX5BA/BPVwOfJ/I77hN9xvL/IJDI6auQKX0lZHp0vQjuB31oYFX/ihtzEvq9nFWEr92decyoYPD9l29xlx+KHBWIHwqCQ4wUqXmbtu2uoOwwuUch/rAOMHwZ4NaNr2hCI4OYpfoXbDxF5qWub0C2G1mXarfVkk= Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-MS-Exchange-CrossTenant-Network-Message-Id: 0b30a727-ba08-435e-29b3-08d6d46b5a81 X-MS-Exchange-CrossTenant-originalarrivaltime: 09 May 2019 10:44:46.3637 (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: BN6PR1801MB2033 X-OriginatorOrg: marvell.com X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2019-05-09_02:, , signatures=0 Subject: Re: [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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 09 May 2019 10:44:54 -0000 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()``.=20 [Shally] I think this could be simply stated as "some of the above values m= ay arise in the op after ``rte_compressdev_enqueue_burst()``" because excep= t STATUS_NOT_PROCESSED, I don't see any other error code that cannot be ret= urned from enqueue.=20 Like STATUS_ERROR, can be returned by both enqueue() and dequeue().=20 >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. [Shally] Ack > 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``. [Shally] This statement should be moved after the next lines with bit of re= phrasing > +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``. [Shally] this can be stated as "To facilitate optimization in applications= running in production environment,=20 PMD should update and return op.status on dequeue unless in exceptional sce= narios whereby error can occur on "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 [Shally] This statement looks redundant. If an op can be successful with re= try, then no need for PMD to set an error on op. it can be left as OP_STATU= S_NOT_PROCESSED. Also, In normal scenario, if nb_enqd < actual passed, then app naturally at= tempt re-enqueue of an op. 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.=20 >Though the application > is not expected to check for these, the values are as follows: [Shally] these two statements can be combined as "if less than full burst i= s enqueued, then app shouldn't need to check for any error and simply shoul= d retry. However, if needed=20 Then app can check for following errors:" > + > +- 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,=20 [Shally] Rephrasing could be "Or, any other irrecoverable error , example I= NVALID_ARGS or STATUS_ERROR. In such case, the same op wont 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) > +- 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. > + Ack.=20 Thanks Shally > 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 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 086A2A0096 for ; Thu, 9 May 2019 12:44:57 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 36C644C93; Thu, 9 May 2019 12:44:55 +0200 (CEST) Received: from mx0b-0016f401.pphosted.com (mx0b-0016f401.pphosted.com [67.231.156.173]) by dpdk.org (Postfix) with ESMTP id 0D07A34F0; Thu, 9 May 2019 12:44:53 +0200 (CEST) Received: from pps.filterd (m0045851.ppops.net [127.0.0.1]) by mx0b-0016f401.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x49AUnj9000929; Thu, 9 May 2019 03:44:53 -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=n7DXs7hH8DC3KD8Mb9FD3/BzrMNoRaspCGbTbm0Y0PM=; b=NHkWjpIf4mel/6p6OcTJdwiCwLMjMpTK4mWyCS4oKCYCJ/npT6iVmNINlTQEycBFvZKZ qGYZiR3cD1Hyj9MnkbYuojnwH0e2Jekq2R07D1ddO+Yk55ZFLFEUAoknhESDpmq3MIZX ww/3jNE3RC1nF8xNm/n8cgM4nyH1uN4Qw9b/8wun+Q18Ab82zYQ0bW1cfNVp8IVEM79X XGprsonLbMokb5pXorha0N1ZmvjxSpbYEpcnJC+14vefdfqR+8KyLmbIpqtXCtzPqR/o 1ufGtYP7Le1Ioz1HBVXgNjRg8j/zn5D6VEbxb8z1Cb4xOO9jzBcsfRaDjfVoNt/RtDrE uw== Received: from sc-exch03.marvell.com ([199.233.58.183]) by mx0b-0016f401.pphosted.com with ESMTP id 2scadra2et-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT); Thu, 09 May 2019 03:44:53 -0700 Received: from SC-EXCH03.marvell.com (10.93.176.83) by SC-EXCH03.marvell.com (10.93.176.83) with Microsoft SMTP Server (TLS) id 15.0.1367.3; Thu, 9 May 2019 03:44:51 -0700 Received: from NAM02-SN1-obe.outbound.protection.outlook.com (104.47.36.56) by SC-EXCH03.marvell.com (10.93.176.83) with Microsoft SMTP Server (TLS) id 15.0.1367.3 via Frontend Transport; Thu, 9 May 2019 03:44:51 -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=n7DXs7hH8DC3KD8Mb9FD3/BzrMNoRaspCGbTbm0Y0PM=; b=HHYxBVsvIFtbIzVz5jk2AagP5kEekgpx72P190+2/XY/lBcdH3+WrdnqPjLbFLVJJ6cK6MytuWpHWIuEZDX6eQwJn3bEtLtxQ5k7WHMQ5roqaopNAPbE9UMFI9GqL0jiP3PszYeTcqQv+Dwt0U6iHnF8NUuTIqfadw8AGvhbWDI= Received: from BN6PR1801MB2052.namprd18.prod.outlook.com (10.161.157.11) by BN6PR1801MB2033.namprd18.prod.outlook.com (10.161.154.24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1856.12; Thu, 9 May 2019 10:44:46 +0000 Received: from BN6PR1801MB2052.namprd18.prod.outlook.com ([fe80::99fe:90b9:ca17:a552]) by BN6PR1801MB2052.namprd18.prod.outlook.com ([fe80::99fe:90b9:ca17:a552%6]) with mapi id 15.20.1856.012; Thu, 9 May 2019 10:44:46 +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: AQHU7uRcY1b0dFOFhkSSkiDYaczK7aZitxdA Date: Thu, 9 May 2019 10:44:46 +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: 0b30a727-ba08-435e-29b3-08d6d46b5a81 x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(4652040)(8989299)(4534185)(7168020)(4627221)(201703031133081)(201702281549075)(8990200)(5600141)(711020)(4605104)(2017052603328)(7193020); SRVR:BN6PR1801MB2033; x-ms-traffictypediagnostic: BN6PR1801MB2033: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:9508; x-forefront-prvs: 003245E729 x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(366004)(346002)(136003)(396003)(376002)(39860400002)(51234002)(189003)(13464003)(199004)(74316002)(99286004)(6506007)(6436002)(5660300002)(68736007)(55236004)(486006)(229853002)(102836004)(2501003)(4326008)(86362001)(76176011)(6246003)(110136005)(316002)(256004)(7736002)(54906003)(14444005)(55016002)(53936002)(53546011)(305945005)(478600001)(7696005)(8936002)(81156014)(14454004)(81166006)(476003)(2906002)(9686003)(66446008)(64756008)(25786009)(66556008)(71200400001)(71190400001)(8676002)(446003)(3846002)(11346002)(66946007)(76116006)(66476007)(66066001)(73956011)(33656002)(26005)(52536014)(186003)(6116002); DIR:OUT; SFP:1101; SCL:1; SRVR:BN6PR1801MB2033; H:BN6PR1801MB2052.namprd18.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; MX:1; A: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: hZbEIP+thH+H4Xj3tyQ8lSupvPHU78xvtgI97U7kOoJ2R2mndhdSLk7Hb5sHnLjzIek3ZYbqUTQ2XRmrpJm6WD8j5rh7FkLljEuFT2+y1QkaYuJf3erijBycytCz6TX4AwsKMinDNGH9bXzA6McQpbwFYo9u8kbMA0UZpnqMLuVfPia8JMelhZWx/jD9WDvX0W3qHK0SOZT/cJa1P0F2Ht0s5yiTHcMAEg1wrRke6Bx8IJCRbCA0KeXYh/YDg+I+rq/qGoYCIF7G3hX5BA/BPVwOfJ/I77hN9xvL/IJDI6auQKX0lZHp0vQjuB31oYFX/ihtzEvq9nFWEr92decyoYPD9l29xlx+KHBWIHwqCQ4wUqXmbtu2uoOwwuUch/rAOMHwZ4NaNr2hCI4OYpfoXbDxF5qWub0C2G1mXarfVkk= Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-MS-Exchange-CrossTenant-Network-Message-Id: 0b30a727-ba08-435e-29b3-08d6d46b5a81 X-MS-Exchange-CrossTenant-originalarrivaltime: 09 May 2019 10:44:46.3637 (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: BN6PR1801MB2033 X-OriginatorOrg: marvell.com X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2019-05-09_02:, , signatures=0 Subject: Re: [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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Message-ID: <20190509104446.pcQ6Gn8LHe_V0-GBqQd_p3z6DFWPr0CYJBHBeslzXsk@z> 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()``.=20 [Shally] I think this could be simply stated as "some of the above values m= ay arise in the op after ``rte_compressdev_enqueue_burst()``" because excep= t STATUS_NOT_PROCESSED, I don't see any other error code that cannot be ret= urned from enqueue.=20 Like STATUS_ERROR, can be returned by both enqueue() and dequeue().=20 >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. [Shally] Ack > 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``. [Shally] This statement should be moved after the next lines with bit of re= phrasing > +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``. [Shally] this can be stated as "To facilitate optimization in applications= running in production environment,=20 PMD should update and return op.status on dequeue unless in exceptional sce= narios whereby error can occur on "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 [Shally] This statement looks redundant. If an op can be successful with re= try, then no need for PMD to set an error on op. it can be left as OP_STATU= S_NOT_PROCESSED. Also, In normal scenario, if nb_enqd < actual passed, then app naturally at= tempt re-enqueue of an op. 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.=20 >Though the application > is not expected to check for these, the values are as follows: [Shally] these two statements can be combined as "if less than full burst i= s enqueued, then app shouldn't need to check for any error and simply shoul= d retry. However, if needed=20 Then app can check for following errors:" > + > +- 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,=20 [Shally] Rephrasing could be "Or, any other irrecoverable error , example I= NVALID_ARGS or STATUS_ERROR. In such case, the same op wont 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) > +- 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. > + Ack.=20 Thanks Shally > 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