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

Iremonger, Bernard bernard.iremonger at intel.com
Tue Jan 20 14:37:35 CET 2015


> -----Original Message-----
> From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Thomas Monjalon
> Sent: Tuesday, January 20, 2015 7:15 AM
> To: Neil Horman
> Cc: dev at dpdk.org
> Subject: Re: [dpdk-dev] [PATCH v5 4/4] docs: Add ABI documentation
> 
> 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>
> >
> > ---
> > 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.

Hi Thomas,

Should there be a reference to this document in the programmers guide?

Regards,

Bernard.



More information about the dev mailing list