From: Neil Horman <nhorman@tuxdriver.com>
To: Luca Boccassi <bluca@debian.org>
Cc: dev@dpdk.org
Subject: Re: [dpdk-dev] [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging
Date: Sat, 30 Dec 2017 20:57:17 -0500 [thread overview]
Message-ID: <20171231015717.GA19485@neilslaptop.think-freely.org> (raw)
In-Reply-To: <1514661658.6638.59.camel@debian.org>
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 <bluca@debian.org>
>
> 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
next prev parent reply other threads:[~2017-12-31 1:57 UTC|newest]
Thread overview: 83+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-01 18:56 [dpdk-dev] [PATCH " Neil Horman
2017-12-01 18:56 ` [dpdk-dev] [PATCH 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-01 18:56 ` [dpdk-dev] [PATCH 2/4] compat: Add __experimental macro Neil Horman
2017-12-01 18:56 ` [dpdk-dev] [PATCH 3/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-01 18:56 ` [dpdk-dev] [PATCH 4/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 2/4] compat: Add __experimental macro Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-11 11:35 ` Bruce Richardson
2017-12-11 12:40 ` Neil Horman
2017-12-11 12:45 ` Bruce Richardson
2017-12-11 18:44 ` Neil Horman
2017-12-08 17:14 ` [dpdk-dev] [PATCHv2 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 2/4] compat: Add __experimental macro Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-11 19:36 ` [dpdk-dev] [PATCHv3 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-12 14:07 ` [dpdk-dev] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
2017-12-30 17:15 ` Neil Horman
2018-01-04 12:56 ` Neil Horman
2018-01-05 14:08 ` Thomas Monjalon
2018-01-05 16:00 ` Neil Horman
2018-01-09 1:32 ` [dpdk-dev] [dpdk-ci] " Neil Horman
2018-01-09 9:20 ` Thomas Monjalon
2018-01-09 12:36 ` Neil Horman
2018-01-19 15:44 ` Neil Horman
2017-12-12 14:33 ` [dpdk-dev] " Mcnamara, John
2017-12-12 20:18 ` Neil Horman
2017-12-12 15:11 ` Wiles, Keith
2017-12-12 20:14 ` Neil Horman
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 " Neil Horman
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2018-01-21 18:31 ` Thomas Monjalon
2018-01-21 22:07 ` Neil Horman
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 2/5] compat: Add __experimental macro Neil Horman
2018-01-21 18:37 ` Thomas Monjalon
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 20:50 ` Neil Horman
2018-01-12 11:49 ` Ferruh Yigit
2018-01-12 12:44 ` Neil Horman
2018-01-21 18:54 ` Thomas Monjalon
2018-01-22 1:34 ` Neil Horman
2018-01-22 1:37 ` Thomas Monjalon
2018-01-21 18:50 ` Thomas Monjalon
2018-01-22 1:19 ` Neil Horman
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 21:24 ` Neil Horman
2018-01-12 11:50 ` Ferruh Yigit
2018-01-12 14:25 ` Neil Horman
2018-01-12 15:53 ` Ferruh Yigit
2017-12-13 15:17 ` [dpdk-dev] [PATCHv4 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2017-12-13 15:32 ` Bruce Richardson
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 21:29 ` Neil Horman
2018-01-12 11:50 ` Ferruh Yigit
2018-01-12 14:37 ` Neil Horman
2018-01-12 15:55 ` Ferruh Yigit
2018-01-13 0:28 ` Neil Horman
2018-01-13 15:56 ` Thomas Monjalon
2018-01-14 14:36 ` Neil Horman
2018-01-14 16:27 ` Thomas Monjalon
2018-01-21 20:14 ` Thomas Monjalon
2017-12-13 15:32 ` [dpdk-dev] [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
2017-12-21 14:21 ` Neil Horman
2017-12-30 19:20 ` Luca Boccassi
2017-12-31 1:57 ` Neil Horman [this message]
2018-01-22 1:48 ` [dpdk-dev] [PATCH 0/5] " Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 2/5] compat: Add __rte_experimental macro Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 4/5] dpdk: add __rte_experimental tag to appropriate api calls Neil Horman
2018-01-22 1:48 ` [dpdk-dev] [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2018-01-23 10:35 ` Mcnamara, John
2018-01-29 21:42 ` Thomas Monjalon
2018-01-29 21:46 ` [dpdk-dev] [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging Thomas Monjalon
2018-01-30 15:54 ` Neil Horman
2018-01-30 16:15 ` Thomas Monjalon
2018-01-31 12:18 ` Neil Horman
2018-01-31 12:36 ` Thomas Monjalon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20171231015717.GA19485@neilslaptop.think-freely.org \
--to=nhorman@tuxdriver.com \
--cc=bluca@debian.org \
--cc=dev@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).