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 02B36160 for ; Sun, 31 Dec 2017 02:57:54 +0100 (CET) Received: from cpe-2606-a000-111b-423c-215-ff-fecc-4872.dyn6.twc.com ([2606:a000:111b:423c:215:ff:fecc:4872] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1eVSso-00038N-EI; Sat, 30 Dec 2017 20:57:52 -0500 Date: Sat, 30 Dec 2017 20:57:17 -0500 From: Neil Horman To: Luca Boccassi Cc: dev@dpdk.org Message-ID: <20171231015717.GA19485@neilslaptop.think-freely.org> References: <20171201185628.16261-1-nhorman@tuxdriver.com> <20171213151728.16747-1-nhorman@tuxdriver.com> <1514661658.6638.59.camel@debian.org> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <1514661658.6638.59.camel@debian.org> 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: Sun, 31 Dec 2017 01:57:56 -0000 On Sat, Dec 30, 2017 at 08:20:58PM +0100, Luca Boccassi wrote: > On Wed, 2017-12-13 at 10:17 -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 > > Acked-by: Luca Boccassi > > I really like the idea of showing warnings at build time for users of > the libraries, in fact I like it so much I'm going to shamelessly steal > it for another few projects I work on where we have an experimental > (DRAFT) api system :-) > You're welcome to it :) Neil