From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 363911B28A for ; Thu, 21 Dec 2017 15:22:26 +0100 (CET) Received: from cpe-2606-a000-111b-423c-e874-da8e-c543-d863.dyn6.twc.com ([2606:a000:111b:423c:e874:da8e:c543:d863] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1eS1jd-0007KE-Id; Thu, 21 Dec 2017 09:22:24 -0500 Date: Thu, 21 Dec 2017 09:21:37 -0500 From: Neil Horman To: dev@dpdk.org Cc: thomas@monjalon.net, john.mcnamara@intel.com, bruce.richardson@intel.com Message-ID: <20171221142137.GA23958@hmswarspite.think-freely.org> References: <20171201185628.16261-1-nhorman@tuxdriver.com> <20171213151728.16747-1-nhorman@tuxdriver.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20171213151728.16747-1-nhorman@tuxdriver.com> User-Agent: Mutt/1.9.1 (2017-09-22) X-Spam-Score: -2.9 (--) X-Spam-Status: No Subject: Re: [dpdk-dev] [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging 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, 21 Dec 2017 14:22:27 -0000 On Wed, Dec 13, 2017 at 10:17:23AM -0500, Neil Horman wrote: > Hey all- > A few days ago, I was lamenting the fact that, when reviewing patches I > would frequently complain about ABI changes that were actually considered safe > because they were part of the EXPERIMENTAL api set. John M. asked me then what > I might do to improve the situation, and the following patch set is a proposal > that I've come up with. > > In thinking about the problem I identified two issues that I think we > can improve on in this area: > > 1) Make experimental api calls more visible in the source code. That is to say, > when reviewing patches, it would be nice to have some sort of visual reference > that indicates that the changes being made are part of an experimental API and > therefore ABI concerns need not be addressed > > 2) Make experimenal api usage more visible to consumers of the DPDK, so that > they can make a more informed decision about the API's they consume in their > application. We make an effort to document all the experimental API's, but > there is no guarantee that a user will check the documentation before making use > of a new library. > > This patch set attempts to achieve both of the above goals. To do this I've > added an __experimental macro tag, suitable for inserting into api forward > declarations and definitions. > > The presence of the tag in the header and c files where the api code resides > increases the likelyhood that any patch submitted against them will include the > tag in the context, making it clear to reviewers that ABI stability isn't a > concern here. > > Also, This tag marks each function it is used on with an attibute causing any > use of the fuction to emit a warning during the build > with a message indicating that the API call in question is not yet part of the > stable interface. Developers can then make an informed decision to suppress > that warning or not. > > Because there is internal use of several experimental API's, this set also > includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically > suprress these warnings. I think its fair to assume that, for internal use, we > almost always want to suppress these warnings, as by definition any change to > the apis (even their removal) must be done in parallel with an appropriate > change in the calling locations, lest the dpdk build itself break. > > Neil > > --- > Change Notes: > v2) > * Cleaned up checkpatch errors > * Added Allowance for building experimental on BSD > * Swapped Patch 3 and 4 so that we didn't have a commit level that issued > warnings/errors without need > > v3) > * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in > CFLAGS rather than a makefile variable. This is more flexible in that it > allows us to suppress this specific feature rather than all uses of the > deprecated attribute, as we might use it for other features in the furute > > v4) > * Added documentation patch to contributors guide > > Ping, can I get some more reviews/acks here please? Neil