From mboxrd@z Thu Jan 1 00:00:00 1970 From: Neil Horman Subject: Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Date: Tue, 12 Dec 2017 15:14:26 -0500 Message-ID: <20171212201426.GB1047@hmswarspite.think-freely.org> References: <20171201185628.16261-1-nhorman@tuxdriver.com> <20171211193619.21643-1-nhorman@tuxdriver.com> <6890CBC3-B3E0-4127-B780-FAC5B5267292@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Cc: DPDK , Thomas Monjalon , "Mcnamara, John" , "Richardson, Bruce" To: "Wiles, Keith" Return-path: Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 989952B99 for ; Tue, 12 Dec 2017 21:15:06 +0100 (CET) Content-Disposition: inline In-Reply-To: <6890CBC3-B3E0-4127-B780-FAC5B5267292@intel.com> List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On Tue, Dec 12, 2017 at 03:11:33PM +0000, Wiles, Keith wrote: > > > > On Dec 11, 2017, at 1:36 PM, 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: > > 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 purpose 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 Neil