From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id 4AF901B024 for ; Tue, 23 Jan 2018 11:35:54 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 23 Jan 2018 02:35:53 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,400,1511856000"; d="scan'208";a="21621420" Received: from irsmsx110.ger.corp.intel.com ([163.33.3.25]) by orsmga003.jf.intel.com with ESMTP; 23 Jan 2018 02:35:52 -0800 Received: from irsmsx103.ger.corp.intel.com ([169.254.3.138]) by irsmsx110.ger.corp.intel.com ([163.33.3.25]) with mapi id 14.03.0319.002; Tue, 23 Jan 2018 10:35:50 +0000 From: "Mcnamara, John" To: Neil Horman , "dev@dpdk.org" CC: Thomas Monjalon , "Richardson, Bruce" Thread-Topic: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation Thread-Index: AQHTkyMzDeG30Q+6k0a5o7woF9geQqOBRAJA Date: Tue, 23 Jan 2018 10:35:49 +0000 Message-ID: References: <20171201185628.16261-1-nhorman@tuxdriver.com> <20180122014807.24654-1-nhorman@tuxdriver.com> <20180122014807.24654-6-nhorman@tuxdriver.com> In-Reply-To: <20180122014807.24654-6-nhorman@tuxdriver.com> Accept-Language: en-GB, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ctpclassification: CTP_NT x-titus-metadata-40: eyJDYXRlZ29yeUxhYmVscyI6IiIsIk1ldGFkYXRhIjp7Im5zIjoiaHR0cDpcL1wvd3d3LnRpdHVzLmNvbVwvbnNcL0ludGVsMyIsImlkIjoiMjBhYmI2YWUtOWJkYi00ODZmLThiODItMjdmZjkwMjNmNWJkIiwicHJvcHMiOlt7Im4iOiJDVFBDbGFzc2lmaWNhdGlvbiIsInZhbHMiOlt7InZhbHVlIjoiQ1RQX05UIn1dfV19LCJTdWJqZWN0TGFiZWxzIjpbXSwiVE1DVmVyc2lvbiI6IjE2LjUuOS4zIiwiVHJ1c3RlZExhYmVsSGFzaCI6IkQwOGtiRGtObERwdE4rSlwvZWJucXRNeFBkbkdkVk9cL1lXdjhhRkgrUURvTT0ifQ== dlp-product: dlpe-windows dlp-version: 11.0.0.116 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 v5] 5/5] doc: Add ABI __experimental tag documentation 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: Tue, 23 Jan 2018 10:35:55 -0000 > -----Original Message----- > From: Neil Horman [mailto:nhorman@tuxdriver.com] > Sent: Monday, January 22, 2018 1:48 AM > To: dev@dpdk.org > Cc: Neil Horman ; Thomas Monjalon > ; Mcnamara, John ; > Richardson, Bruce > Subject: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation >=20 > Document the need to add the __experimental tag to appropriate functions >=20 > Signed-off-by: Neil Horman > CC: Thomas Monjalon > CC: "Mcnamara, John" > CC: Bruce Richardson > ... > +Note that marking an API as experimental is a multi step process. To > +mark an API as experimental, the symbols which are desired to be > +exported must be placed in an EXPERIMENTAL version block in the > +corresponding libraries' version map script. Secondly, the > +corresponding definitions of those exported functions, and their > +forward declarations (in the development header files), must be marked > +with the __rte_experimental tag (see rte_compat.h). The DPDK build > +makefiles perform a check to ensure that the map file and the C code > +reflect the same list of symbols. This check can be circumvented by > defining ALLOW_EXPERIMENTAL_API during compilation in the corresponding > library Makefile. > + > +In addition to tagging the code with __rte_experimental, the doxygen > +markup must also contain the EXPERIMENTAL string, and the MAINTAINER > +file should note that the library contains EXPERIMENTAL APIs. > + > ABI versions, once released, are available until such time as their > deprecation has been noted in the Release Notes for at least one major > release cycle. For example consider the case where the ABI for DPDK 2.0 > has been > -- > 2.14.3 Thanks for the update, and this work in general. The rendered docs would probably look a better better with __rte_experiment= al and ALLOW_EXPERIMENTAL_API is fixed width backticks ``var`` but that is onl= y a "nice to have" so no need for a respin. Acked-by: John McNamara