DPDK patches and discussions
 help / color / mirror / Atom feed
From: Ray Kinsella <mdr@ashroe.eu>
To: Hemant Agrawal <hemant.agrawal@nxp.com>, "dev@dpdk.org" <dev@dpdk.org>
Cc: "thomas@monjalon.net" <thomas@monjalon.net>,
	"stephen@networkplumber.org" <stephen@networkplumber.org>,
	"bruce.richardson@intel.com" <bruce.richardson@intel.com>,
	"ferruh.yigit@intel.com" <ferruh.yigit@intel.com>,
	"konstantin.ananyev@intel.com" <konstantin.ananyev@intel.com>,
	"jerinj@marvell.com" <jerinj@marvell.com>,
	"olivier.matz@6wind.com" <olivier.matz@6wind.com>,
	"nhorman@tuxdriver.com" <nhorman@tuxdriver.com>,
	"maxime.coquelin@redhat.com" <maxime.coquelin@redhat.com>,
	"john.mcnamara@intel.com" <john.mcnamara@intel.com>,
	"marko.kovacevic@intel.com" <marko.kovacevic@intel.com>,
	"ktraynor@redhat.com" <ktraynor@redhat.com>,
	"aconole@redhat.com" <aconole@redhat.com>
Subject: Re: [dpdk-dev] [PATCH v6 1/4] doc: separate versioning.rst into version and policy
Date: Tue, 1 Oct 2019 14:19:09 +0100	[thread overview]
Message-ID: <817c3f46-3216-1051-08a7-19102645e432@ashroe.eu> (raw)
In-Reply-To: <VI1PR0401MB2541B0FCE98340391B82D4F2899D0@VI1PR0401MB2541.eurprd04.prod.outlook.com>


Patch 1/4 - doc: separate versioning.rst into version and policy.

So it essentially re-organizes the existing policy into two separate
documents, one dealing with the policy and the other dealing with the
mechanics of abi versioning

Patch 2/4 -  doc: changes to abi policy introducing major abi versions

Actually details the changes to the policy.

Other comments inline below.

Ray K

On 01/10/2019 13:50, Hemant Agrawal wrote:
> Hi Ray,
>> +DPDK ABI/API policy
>> +===================
>> +
>> +Description
>> +-----------
>> +
>> +This document details some methods for handling ABI management in the
>> DPDK.
>> +
>> +General Guidelines
>> +------------------
>> +
>> +#. Whenever possible, ABI should be preserved #. ABI/API may be changed
>> +with a deprecation process #. The modification of symbols can generally
>> +be managed with versioning #. Libraries or APIs marked in
>> +``experimental`` state may change without constraint #. New APIs will
>> +be marked as ``experimental`` for at least one release to allow
>> +   any issues found by users of the new API to be fixed quickly #. The
>> +addition of symbols is generally not problematic #. The removal of
>> +symbols generally is an ABI break and requires bumping of the
>> +   LIBABIVER macro
>> +#. Updates to the minimum hardware requirements, which drop support
>> for hardware which
>> +   was previously supported, should be treated as an ABI change.
> [Hemant] You mean the specific HW pmds? 
> 1. Why dropping HW PMD is a ABI change? 

So this is part of the original policy and you are correct, it isn't
strictly abi - I think the original policy's author, wanted it treated
the same way so that a given ABI version would not drop support for

> 2. Even if they are supported across releases, there is no guarantee that they are not broken.


>> +
>> +What is an ABI
>> +~~~~~~~~~~~~~~
>> +
>> +An ABI (Application Binary Interface) is the set of runtime interfaces
>> +exposed by a library. It is similar to an API (Application Programming
>> +Interface) but is the result of compilation.  It is also effectively
>> +cloned when applications link to dynamic libraries.  That is to say
>> +when an application is compiled to link against dynamic libraries, it
>> +is assumed that the ABI remains constant between the time the application
>> is compiled/linked, and the time that it runs.
>> +Therefore, in the case of dynamic linking, it is critical that an ABI
>> +is preserved, or (when modified), done in such a way that the
>> +application is unable to behave improperly or in an unexpected fashion.
>> +
>> +
>> +ABI/API Deprecation
>> +-------------------
>> +
>> +The DPDK ABI policy
>> +~~~~~~~~~~~~~~~~~~~
>> +
>> +ABI versions are set at the time of major release labeling, and the ABI
>> +may change multiple times, without warning, between the last release
>> +label and the HEAD label of the git tree.
>> +
>> +ABI versions, once released, are available until such time as their
>> +deprecation has been noted in the Release Notes for at least one major
>> +release cycle. For example consider the case where the ABI for DPDK 2.0
>> +has been shipped and then a decision is made to modify it during the
>> +development of DPDK 2.1. The decision will be recorded in the Release
>> +Notes for the DPDK 2.1 release and the modification will be made available
>> in the DPDK 2.2 release.
>> +
> [Hemant]  Is it possible to update the DPDK numbering to current versioning, instead of using old 2.x numbering?

Already done, see Patch 2/4

>> +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. In those cases ABI's may be updated without backward
>> +compatibility being provided. The requirements for doing so are:
>> +
>> +#. At least 3 acknowledgments of the need to do so must be made on the
>> +   dpdk.org mailing list.
>> +
>> +   - The acknowledgment of the maintainer of the component is mandatory,
>> or if
>> +     no maintainer is available for the component, the tree/sub-tree
>> maintainer
>> +     for that component must acknowledge the ABI change instead.
>> +
>> +   - It is also recommended that acknowledgments from different "areas of
>> +     interest" be sought for each deprecation, for example: from NIC
>> vendors,
>> +     CPU vendors, end-users, etc.
>> +
>> +#. The changes (including an alternative map file) can be included with
>> +   deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option,
>> +   to provide more details about oncoming changes.
>> +   ``RTE_NEXT_ABI`` wrapper will be removed when it become the default
>> ABI.
> [Hemant]  The older implementation will or can be removed at this point of time? 

Detailed in Patch 2/4.

it says ... At the declaration of the next major ABI version, those ABI
changes then become a formal part of the new ABI and the requirement to
preserve ABI compatibility with the last major ABI version is then
dropped ...


Ray K

  reply	other threads:[~2019-10-01 13:19 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-27 16:54 [dpdk-dev] [PATCH v6 0/4] doc: changes to abi policy introducing major abi versions Ray Kinsella
2019-09-27 16:54 ` [dpdk-dev] [PATCH v6 1/4] doc: separate versioning.rst into version and policy Ray Kinsella
2019-10-01 12:50   ` Hemant Agrawal
2019-10-01 13:19     ` Ray Kinsella [this message]
2019-10-21  9:53   ` Thomas Monjalon
2019-10-25 11:36     ` Ray Kinsella
2019-09-27 16:54 ` [dpdk-dev] [PATCH v6 2/4] doc: changes to abi policy introducing major abi versions Ray Kinsella
2019-10-15 15:11   ` David Marchand
2019-10-25 11:43     ` Ray Kinsella
2019-10-24  0:43   ` Thomas Monjalon
2019-10-25  9:10     ` Ray Kinsella
2019-10-28 10:02       ` Thomas Monjalon
2019-10-25 12:45     ` Ray Kinsella
2019-09-27 16:54 ` [dpdk-dev] [PATCH v6 3/4] doc: updates to versioning guide for " Ray Kinsella
2019-09-27 16:54 ` [dpdk-dev] [PATCH v6 4/4] doc: add maintainer for abi policy Ray Kinsella
2019-10-21  9:50 ` [dpdk-dev] [PATCH v6 0/4] doc: changes to abi policy introducing major abi versions Thomas Monjalon
2019-10-21 10:10   ` Ray Kinsella
2019-10-21 14:38     ` Thomas Monjalon
2019-10-22  8:12       ` Ray Kinsella

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=817c3f46-3216-1051-08a7-19102645e432@ashroe.eu \
    --to=mdr@ashroe.eu \
    --cc=aconole@redhat.com \
    --cc=bruce.richardson@intel.com \
    --cc=dev@dpdk.org \
    --cc=ferruh.yigit@intel.com \
    --cc=hemant.agrawal@nxp.com \
    --cc=jerinj@marvell.com \
    --cc=john.mcnamara@intel.com \
    --cc=konstantin.ananyev@intel.com \
    --cc=ktraynor@redhat.com \
    --cc=marko.kovacevic@intel.com \
    --cc=maxime.coquelin@redhat.com \
    --cc=nhorman@tuxdriver.com \
    --cc=olivier.matz@6wind.com \
    --cc=stephen@networkplumber.org \
    --cc=thomas@monjalon.net \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).