[dpdk-dev] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging

Neil Horman nhorman at tuxdriver.com
Tue Dec 12 21:14:26 CET 2017

On Tue, Dec 12, 2017 at 03:11:33PM +0000, Wiles, Keith wrote:
> > On Dec 11, 2017, at 1:36 PM, Neil Horman <nhorman at tuxdriver.com> 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:
> One question is how does this effect the ABI map files or does it? If an API is exposed in the map file does it need any type of special indicator on that API line? It may not make much difference, but I was thinking it could be an indicator the API is experimental and may not exist. If the new experimental API is included in the map file then it could become a problem for systems expecting all of the APIs in the map file to be solid.
> Regards,
> Keith

So, thats a few questions that are all interconnected, I'll try to answer them
as completely as I can:

1) Despite being experimental API's, they still need to be part of the version
map files.  This is an always condition, and there are no ecpetions to that.
Failure to put an api call in the map file means it won't get exported when we
build as a shared library and so is unusable.  This has been the case since we
introduced the map files.  You'll note that each map file which exports
experimental APIS has an EXPERIMENTAL clause in the map for expressly this

2) One of the problems that I identified in my cover letter was that, when
reviewing patches (and when using API's), there was no clear indicator that the
patch we were reviewing was part of an experimental API (without
simeoultaneously consulting the map file).  That was part of what this patch set
was meant to address (visual clues in the patch that told reviewers this was
part of an experimental API).

3) The __experimental tag is expressly meant to go on function definitions and
forward declarations to address the concern in (2) expressly

4) The __experimental tag is also meant to trigger a warning to users that build
code using experimental apis.  At compile time a warning is generated for any
call made to said tagged api (unless -DALLOW_EXPERIMENTAL_APIS is set)

5) The one issue I had with this patch set was that there was a need to manually
keep in sync items tagged with __experimental and the symbols listed in the
EXPERIMENTAL section of a map file.  The first patch in this series addresses
that by adding a build check to make sure that symbols in the map file are
tagged with __experimental in the source.

Hope that answers all your questions

More information about the dev mailing list