[dpdk-dev] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
Bruce Richardson
bruce.richardson at intel.com
Tue Dec 12 15:07:52 CET 2017
On Mon, Dec 11, 2017 at 02:36:15PM -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
>
Despite the fact that this is making yet more work for porting to a new
build system, I think this is a good idea to have. As such,
Acked-by: Bruce Richardson <bruce.richardson at intel.com>
More information about the dev
mailing list