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 6B78D5A76 for ; Tue, 20 Jan 2015 16:35:22 +0100 (CET) Received: from hmsreliant.think-freely.org ([2001:470:8:a08:7aac:c0ff:fec2:933b] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1YDapo-0004jW-Ur; Tue, 20 Jan 2015 10:35:20 -0500 Date: Tue, 20 Jan 2015 10:35:16 -0500 From: Neil Horman To: Thomas Monjalon Message-ID: <20150120153516.GG18449@hmsreliant.think-freely.org> References: <1419109299-9603-1-git-send-email-nhorman@tuxdriver.com> <12582729.RuWBbWddAL@xps13> <20150120143737.GB18449@hmsreliant.think-freely.org> <3451650.yEcfPMJlme@xps13> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <3451650.yEcfPMJlme@xps13> User-Agent: Mutt/1.5.23 (2014-03-12) X-Spam-Score: -2.9 (--) X-Spam-Status: No Cc: dev@dpdk.org Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 20 Jan 2015 15:35:23 -0000 On Tue, Jan 20, 2015 at 04:06:07PM +0100, Thomas Monjalon wrote: > 2015-01-20 09:37, Neil Horman: > > On Tue, Jan 20, 2015 at 03:00:01PM +0100, Thomas Monjalon wrote: > > > 2015-01-16 10:33, Neil Horman: > > > > --- /dev/null > > > > +++ b/doc/abi.txt > > > > @@ -0,0 +1,36 @@ > > > > +ABI policy: > > > > + ABI versions are set at the time of major release labeling, and ABI may > > > > +change multiple times between the last labeling and the HEAD label of the git > > > > +tree without warning > > > > + > > > > + ABI versions, once released are available until such time as their > > > > +deprecation has been noted here for at least one major release cycle, after it > > > > +has been tagged. E.g. the ABI for DPDK 1.8 is shipped, and then the decision to > > > > +remove it is made during the development of DPDK 1.9. The decision will be > > > > +recorded here, shipped with the DPDK 1.9 release, and actually removed when DPDK > > > > +1.10 ships. > > > > + > > > > + ABI versions may be deprecated in whole, or in part as needed by a given > > > > +update. > > > > + > > > > + Some ABI changes may be too significant to reasonably maintain multiple > > > > +versions of. In those events ABI's may be updated without backward > > > > +compatibility provided. The requirements for doing so are: > > > > + 1) At least 3 acknoweldgements of the need on the dpdk.org > > > > + 2) A full deprecation cycle must be made to offer downstream consumers > > > > +sufficient warning of the change. E.g. if dpdk 2.0 is under development when > > > > +the change is proposed, a deprecation notice must be added to this file, and > > > > +released with dpdk 2.0. Then the change may be incorporated for dpdk 2.1 > > > > + 3) The LIBABIVER variable in the makefilei(s) where the ABI changes are > > > > +incorporated must be incremented in parallel with the ABI changes themselves > > > > + > > > > + Note that the above process for ABI deprecation should not be undertaken > > > > +lightly. ABI stability is extreemely important for downstream consumers of the > > > > +DPDK, especially when distributed in shared object form. Every effort should be > > > > +made to preserve ABI whenever possible. For instance, reorganizing public > > > > +structure field for astetic or readability purposes should be avoided as it will > > > > > > astetic? typo? > > > > > > > +cause ABI breakage. Only significant (e.g. performance) reasons should be seen > > > > +as cause to alter ABI. > > > > + > > > > +Deprecation Notices: > > > > > > Neil, are you sure it's a good idea to put deprecations notices here instead > > > of release notes? > > > > > Funny, I just made mention of that in my last note. I do think that the release > > notes is the right place to "officially" announce deprecation warnings, but I > > think we need a way for developers to communicate that efficiently (given that > > the release notes aren't stored in the git tree). > > Yes, they are: > http://dpdk.org/browse/dpdk/tree/doc/guides/rel_notes > So I suggest to remove Deprecation Notices from abi.txt and create an entry > in release notes. > > > I think this is the place for > > developers to canonically list deprecations, and make reading this file part of > > the release notes generation process. That way, updates can be made as part of > > the commit process easily. > > Developpers can update the release notes themselves. > ok, I was unaware. If thats the case, then yes, putting these deprecations directly in the release notes makes the most sense. I'll resubmit with that changed. > > > I'm also thinking that we need to add more things in this doc: > > > - case of macros/constant deprecation (API only) > > > - case of structure update: must be renamed to provide ABI compatibility? > > > > > I'm definately in favor of adding such notices here, but I hadn't planned for > > any strict formatting of any given notice. That is to say, I considered you're > > two issues above to be able to be included here. I have no issue with listing a > > deprecation note that indicates macros are being removed or that sections of api > > are being versioned to accomodate structure changes. of any sort > > No, I was suggesting to explain in this doc that macro removal must be > announced with a deprecation notice, > and that in case structure must be reworked, the name must change if we > want to preserve ABI compatibility with old structure. > > > > Do you think we can have a tool to test the ABI compatibility by building > > > examples/apps of previous version and checking them with built DSO of > > > current version? > > > > > I do, though I'm not sure its within the scope of this update. The easiest way > > to do it currently is to checkout the last released version of the dpdk, build > > it as a DSO build, copy out one of the test/example apps, checkout the HEAD of > > the tree, rebuild, and run the saved off test app from the first build using the > > shared objects of the second build. That does some rudimentary validation, > > but it only touches on the API aspects that the application you're using makes > > use of. What would be better would be if we had a test application that made a > > call to every exported API call that we have, so that we could be confident that > > we were exhaustively testing the ABI surface. I think thats a large piece of > > work, but it would be beneficial to have. > > Yes, it should be another patchset. > Do you plan to work on it? It would be very convenient for developpers and > maintainers to test ABI compatibility. > Gladly, if we can get this in. I think its an important tool. > Thanks > -- > Thomas >