[dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation

Bruce Richardson bruce.richardson at intel.com
Tue Jan 20 11:47:26 CET 2015


On Tue, Jan 20, 2015 at 08:14:50AM +0100, Thomas Monjalon wrote:
> Thank you Neil for writing this document.
> This is a really important change in DPDK.
> It would be very good to have comments or acknowledgement from several
> developpers. This policy would be enforced by having several Acked-by lines.
> 
> 
> 2015-01-16 10:33, Neil Horman:
> > Adding a document describing rudimentary ABI policy and adding notice space for
> > any deprecation announcements
> > 
> > Signed-off-by: Neil Horman <nhorman at tuxdriver.com>
> > CC: Thomas Monjalon <thomas.monjalon at 6wind.com>
> > CC: "Richardson, Bruce" <bruce.richardson at intel.com>

This policy looks sensible to me.
Acked-by: Bruce Richardson <bruce.richardson at intel.com>

> > 
> > ---
> > Change notes:
> > 
> > v5) Updated documentation to add notes from Thomas M.
> > ---
> >  doc/abi.txt | 36 ++++++++++++++++++++++++++++++++++++
> >  1 file changed, 36 insertions(+)
> >  create mode 100644 doc/abi.txt
> > 
> > diff --git a/doc/abi.txt b/doc/abi.txt
> > new file mode 100644
> > index 0000000..14be464
> > --- /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
> > +cause ABI breakage.  Only significant (e.g. performance) reasons should be seen
> > +as cause to alter ABI.
>



More information about the dev mailing list