Re: [dpdk-dev] DPDK ABI/API Stability

[Luca Boccassi <bluca@debian.org>]

On Wed, 2019-04-03 at 16:42 +0100, Ray Kinsella wrote:
> Hi folks,
> 
> Recently I started a discussion with the DPDK Technical Board on DPDK
> ABI/API stability. This was born out informal feedback I had received
> from a number of users of DPDK about ABI churn. In turn this feedback
> then prompted an ABI analysis of DPDK using tools from abi-
> laboratory.
> 
> https://abi-laboratory.pro/index.php?view=timeline&l=dpdk
> 
> 
> I guess the short story is that DPDK ABI hasn't really settled down
> as
> the project has matured. If you take a look at the “Backward Compat.”
> column which measures ABI compatibility compared to the previous
> releases, you will see significant churn in the ABI over successive
> releases since v16.04.
> 
> Now compare DPDK to GStreamer as an example of a very mature project
> with a similar intent, a framework for building applications, and
> which
> enjoys a very stable API.
> 
> https://abi-laboratory.pro/index.php?view=timeline&l=gstreamer
> 
> 
> The DPDK ABI churn has the following affects for users:-
> 
> 1. The churn obliges users of DPDK to commit to a constant
> re-integration and re-validation effort for new versions of DPDK.
> This
> effort from their perspective may not add value to their consuming
> project, particular if they are only updating to "stay current".
> 2. The churn encourages users of DPDK to slip versions, putting off
> reintegration to later, building up technical debt and causing their
> projects to miss support for new hardware or features.
> 3. It makes DPDK different to almost every other system library and
> framework that an operating systems might ship. This makes DPDK
> trickier
> to dynamically link against, package and maintain for OS maintainers.
> 
> In order to address this issue, I have put together the minimal set
> of
> concrete proposals below for discussion at the Technical Board next
> Wednesday.
> 
> I wanted to share this, as these might not yet be the right
> proposals,
> however I am putting them out there for feedback to start the
> discussion.
> 
> Thanks,
> 
> Ray K

Hello Ray,

It will not come as a surprise to anybody when I say I fully agree with
your analysis :-)

One of the consequences is that this has a tendency to lead to
vendorization - given distros have to move on, and moving on with
application is a lot of work as you pointed out, the easiest solution
is to fork and embed.

If we can't change this, I think at the very least we should be more
explicit in the documentation about how the API is in flux. At least
project managers would be able to know up front that there is a higher-
than-normal long-term opex attached to a DPDK application, even when
all other development stops.

A couple of comments inline below.

> Experimental API
> 1.	APIs designated as experimental are not considered part of the
> ABI
> and may change without warning at any time.
> 2.	APIs designated as experimental must be marked depreciated for
> a
> least one quarterly release before removal.
> 3.	APIs designated as experimental will no longer automatically
> graduate
> to core after one release, they may stay experimental until their
> author
> and the maintainer agree that graduation is appropriate.

From my experience in other projects, if a symbol is available in a
shared library, it will be used. So one thing that's missing from the
current system, which is already good and very helpful, is being able
to completely disable the experimental APIs.
In the past I looked into stopping to export those symbols but the
issue is intra-project dependencies - this can only be done if, for
example, PMDs are not allowed to use an experimental RTE api, unless
it's wrapped in an experimental ifdef (or similar mechanism). This of
course would be a major pain for everybody involved.

> Core API (non-experimental API)
> 4.	APIs designated as core must be depreciated for a least two
> years
> before removal, to facilitate the continued compatibility with LTS
> releases. A final removal notice will be published to the DPDK
> Mailing
> List, and if there are no strong objections only then an API may be
> removed.
> 5.	APIs designated as core may be changed as follows:-
> 5.a	The change proposer must demonstrated that the change has a
> supporting use case and could not be achieved in any other way.
> 5.b	ABI version compatibility must be retained, as described below.
> 
> Shared Libraries
> 6.	DPDK will move to shared libraries & dynamic linking by
> default, to
> accommodate greater use of ABI versioning by DPDK consumers.

The switch to Meson will help here, as it's the default.

> ABI Versioning
> 7.	New quarterly releases of DPDK will remain ABI compatible with
> the
> most recent DPDK LTS release.
> (e.g. DPDK 19.08 will remain ABI compatible with DPDK LTS 18.11).
> 8.	New DPDK LTS releases will remain ABI compatible with the
> previous
> two DPDK LTS releases.
> (e.g. DPDK 20.11 will be ABI compatible with DPDK 19.11 and DPDK
> 18.11,
> DPDK 21.11 will be ABI compatible with DPDK 20.11 and DPDK 19.11 etc)
> 8. & 9. will be achieved with ABI symbol versioning.

There is also an additional problem with the way we do ABI versioning,
we talked about it many times - ABI bumps need to be "sticky" and
propagate. Eg: if libfoo goes from 1 to 2, all libraries linking to foo
also need a bump. We don't do this, which made necessary the
introduction of the "major abi revision" option, which essentially
makes all the ABI versions match the release version, and which we use
in Debian/Ubuntu.

IMHO we should do a mix of the two - move to always use major version,
but of the LTS as you suggest. So all ABI revisions will be 19.11 until
20.11 is out, and so on.

-- 
Kind regards,
Luca Boccassi