From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id ED222A0613 for ; Wed, 28 Aug 2019 12:09:28 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 5131E1C06A; Wed, 28 Aug 2019 12:09:28 +0200 (CEST) Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id 599571BF9B for ; Wed, 28 Aug 2019 12:09:26 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga002.jf.intel.com ([10.7.209.21]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 28 Aug 2019 03:09:25 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.64,440,1559545200"; d="scan'208";a="192543176" Received: from irsmsx154.ger.corp.intel.com ([163.33.192.96]) by orsmga002.jf.intel.com with ESMTP; 28 Aug 2019 03:09:23 -0700 Received: from irsmsx101.ger.corp.intel.com ([169.254.1.61]) by IRSMSX154.ger.corp.intel.com ([169.254.12.14]) with mapi id 14.03.0439.000; Wed, 28 Aug 2019 11:09:22 +0100 From: "Trahe, Fiona" To: Shally Verma , "dev@dpdk.org" CC: "akhil.goyal@nxp.com" , Ashish Gupta , "Van Haaren, Harry" , "Trahe, Fiona" Thread-Topic: [PATCH] doc/compressdev: clarify that structs should be zeroed before use Thread-Index: AQHVXPyQ0xxEd29mEEuAHRy5Zso1f6cP6dyAgABaGpCAAA8CUA== Date: Wed, 28 Aug 2019 10:09:22 +0000 Message-ID: <348A99DA5F5B7549AA880327E580B435897FA57B@IRSMSX101.ger.corp.intel.com> References: <1566926764-31816-1-git-send-email-fiona.trahe@intel.com> <348A99DA5F5B7549AA880327E580B435897FA43E@IRSMSX101.ger.corp.intel.com> In-Reply-To: <348A99DA5F5B7549AA880327E580B435897FA43E@IRSMSX101.ger.corp.intel.com> Accept-Language: en-IE, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-titus-metadata-40: eyJDYXRlZ29yeUxhYmVscyI6IiIsIk1ldGFkYXRhIjp7Im5zIjoiaHR0cDpcL1wvd3d3LnRpdHVzLmNvbVwvbnNcL0ludGVsMyIsImlkIjoiNmRmZWFkODEtZGYxMS00YWFhLWFhNjEtNGEyNDg0YTA5Njg5IiwicHJvcHMiOlt7Im4iOiJDVFBDbGFzc2lmaWNhdGlvbiIsInZhbHMiOlt7InZhbHVlIjoiQ1RQX05UIn1dfV19LCJTdWJqZWN0TGFiZWxzIjpbXSwiVE1DVmVyc2lvbiI6IjE3LjEwLjE4MDQuNDkiLCJUcnVzdGVkTGFiZWxIYXNoIjoiXC9kYnRVM1lPZzdPRTIwaXVzSFhsS2QxRlB6Rzh1cEQ4bWJWN1wvd20wQUpKNmVYa2V5XC92a2xpaDFRYjVMT01qXC8ifQ== x-ctpclassification: CTP_NT dlp-product: dlpe-windows dlp-version: 11.2.0.6 dlp-reaction: no-action x-originating-ip: [163.33.239.180] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Subject: Re: [dpdk-dev] [PATCH] doc/compressdev: clarify that structs should be zeroed before use 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" Hi all, =20 Thanks to feedback from Harry, I've realised that I was only considering ap= plications re-compiled against the latest DPDK, but without any code rework to use the new feature= . =20 I hadn't considered pre-compiled applications running against shared libs. This solution is not sufficient to handle those cases.=20 There are many ways an API may change, this was just one small attempt to minimise the impact of possible future changes. So will nack this - we'll just deal with them through the usual deprecation notices, wrappers, etc if and when they arise. > > > -----Original Message----- > > > From: Fiona Trahe > > > Sent: Tuesday, August 27, 2019 10:56 PM > > > To: dev@dpdk.org > > > Cc: akhil.goyal@nxp.com; Ashish Gupta ; Shally > > > Verma ; Fiona Trahe > > > Subject: [PATCH] doc/compressdev: clarify that structs should be zero= ed > > > before use > > > > > > Some structs used on the API are zeroed on creation by API calls, (e.= g. > > > rte_comp_op), but a few are allocated in the application domain. > > > Clarify that the application should zero those to enable future exten= sions > > > without API breakage. > > > > > > Signed-off-by: Fiona Trahe > > > --- > > >=20 doc/guides/prog_guide/compressdev.rst | 10 ++++++++++ > > > 1 files changed, 10 insertions(+), 0 deletions(-) > > > > > > diff --git a/doc/guides/prog_guide/compressdev.rst > > > b/doc/guides/prog_guide/compressdev.rst > > > index a089db1..2a85eba 100644 > > > --- a/doc/guides/prog_guide/compressdev.rst > > > +++ b/doc/guides/prog_guide/compressdev.rst > > > @@ -76,6 +76,11 @@ The ``rte_compressdev_configure`` API is used to > > > configure a compression device. > > > The ``rte_compressdev_config`` structure is used to pass the configu= ration > > > parameters. > > > > > > +The allocation of the ``rte_compressdev_config`` struct passed on th= e > > > +API is in the application domain, so to allow future API extensions = in > > > +a backwardly compatible manner the application should zero this stru= ct, > > > +e.g. using sizeof(), before populating it. This allows the addition = of new > > > parameters to the struct with default value of zero indicating origin= al > > > behaviour. > > > + > > > See *DPDK API Reference* for details. > > > > > > Configuration of Queue Pairs > > > @@ -264,6 +269,11 @@ Compression transforms (``rte_comp_xform``) are > > > the mechanism to specify the details of the compression operation su= ch as > > > algorithm, window size and checksum. > > > > > > +The allocation of the ``rte_comp_xform`` struct passed on the API is= in > > > +the application domain, so to allow future API extensions in a > > > +backwardly compatible manner the application should zero this struct= , > > > +e.g. using sizeof(), before populating it. This allows the addition = of new > > > parameters to the struct with default value of zero indicating origin= al > > > behaviour. > > > + > > [Shally] Though summary and description looks fine. Only thing to confi= rm is that this description is > > applicable only on xform and config structure? And 0s to all field is a= llowed values. > > I have not gone back to refer to latest config and xform structure so t= ake it just a pointer to check on > > these cases. > [Fiona] I looked through all API calls and these were the only one I coul= d see. The op, private_xform and > stream are all handed under the API. But would appreciate a review in cas= e I've missed something. Nack