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 DB4942030 for ; Wed, 13 Dec 2017 16:18:21 +0100 (CET) Received: from cpe-2606-a000-111b-423c-e874-da8e-c543-d863.dyn6.twc.com ([2606:a000:111b:423c:e874:da8e:c543:d863] helo=hmswarspite.think-freely.org) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1eP8nS-0003Qm-NI; Wed, 13 Dec 2017 10:18:15 -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 vBDFHZqq016797; Wed, 13 Dec 2017 10:17:36 -0500 Received: (from nhorman@localhost) by hmswarspite.think-freely.org (8.15.2/8.15.2/Submit) id vBDFHZKW016796; Wed, 13 Dec 2017 10:17:35 -0500 From: Neil Horman To: dev@dpdk.org Cc: thomas@monjalon.net, john.mcnamara@intel.com, bruce.richardson@intel.com Date: Wed, 13 Dec 2017 10:17:23 -0500 Message-Id: <20171213151728.16747-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] [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: Wed, 13 Dec 2017 15:18:22 -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_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