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 >
