From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <nhorman@tuxdriver.com>
Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58])
by dpdk.org (Postfix) with ESMTP id 40C48325F
for <dev@dpdk.org>; Mon, 22 Jan 2018 02:48:51 +0100 (CET)
Received: from cpe-2606-a000-111b-4011-eaa3-4b92-4a68-8f24.dyn6.twc.com
([2606:a000:111b:4011:eaa3:4b92:4a68:8f24] helo=hmswarspite.think-freely.org)
by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63)
(envelope-from <nhorman@tuxdriver.com>) id 1edRE5-000687-Fg
for dev@dpdk.org; Sun, 21 Jan 2018 20:48:49 -0500
Received: from hmswarspite.think-freely.org (localhost [127.0.0.1])
by hmswarspite.think-freely.org (8.15.2/8.15.2) with ESMTP id w0M1mA67024798
for <dev@dpdk.org>; Sun, 21 Jan 2018 20:48:10 -0500
Received: (from nhorman@localhost)
by hmswarspite.think-freely.org (8.15.2/8.15.2/Submit) id w0M1mA02024797
for dev@dpdk.org; Sun, 21 Jan 2018 20:48:10 -0500
From: Neil Horman <nhorman@tuxdriver.com>
To: dev@dpdk.org
Date: Sun, 21 Jan 2018 20:48:02 -0500
Message-Id: <20180122014807.24654-1-nhorman@tuxdriver.com>
X-Mailer: git-send-email 2.14.3
In-Reply-To: <20171201185628.16261-1-nhorman@tuxdriver.com>
References: <20171201185628.16261-1-nhorman@tuxdriver.com>
X-Spam-Score: -2.9 (--)
X-Spam-Status: No
Subject: [dpdk-dev] [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://dpdk.org/ml/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://dpdk.org/ml/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Mon, 22 Jan 2018 01:48:52 -0000
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_API 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
---
v5 Changes
* Clean ups suggested by Thomas