From: Neil Horman <nhorman@tuxdriver.com>
To: Ferruh Yigit <ferruh.yigit@intel.com>
Cc: dev@dpdk.org, John McNamara <john.mcnamara@intel.com>,
Marko Kovacevic <marko.kovacevic@intel.com>,
Luca Boccassi <bluca@debian.org>,
Kevin Traynor <ktraynor@redhat.com>,
Yongseok Koh <yskoh@mellanox.com>
Subject: Re: [dpdk-dev] [PATCH v3 1/3] doc: clean ABI/API policy guide
Date: Wed, 23 Jan 2019 03:13:27 -0500 [thread overview]
Message-ID: <20190123081327.GA4864@neilslaptop.think-freely.org> (raw)
In-Reply-To: <20190122162310.53613-1-ferruh.yigit@intel.com>
On Tue, Jan 22, 2019 at 04:23:08PM +0000, Ferruh Yigit wrote:
> The original document written from the point of ABI versioning but later
> additions make document confusing, convert document into a ABI/API
> policy documentation and organize the document in subsections:
> - ABI/API Deprecation
> - Experimental APIs
> - Library versioning
> - ABI versioning
>
> Aim to clarify confusion between deprecation versioned ABI and overall
> ABI/API deprecation, also ABI versioning and Library versioning by
> organizing the sections.
>
> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> ---
> Cc: Luca Boccassi <bluca@debian.org>
> Cc: Kevin Traynor <ktraynor@redhat.com>
> Cc: Yongseok Koh <yskoh@mellanox.com>
> Cc: Neil Horman <nhorman@tuxdriver.com>
> ---
> doc/guides/contributing/versioning.rst | 132 +++++++++++++------------
> 1 file changed, 71 insertions(+), 61 deletions(-)
>
> diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
> index 01b36247e..19af56cd2 100644
> --- a/doc/guides/contributing/versioning.rst
> +++ b/doc/guides/contributing/versioning.rst
> @@ -1,33 +1,31 @@
> .. SPDX-License-Identifier: BSD-3-Clause
> Copyright 2018 The DPDK contributors
>
> -Managing ABI updates
> -====================
> +DPDK ABI/API policy
> +===================
>
> Description
> -----------
>
> This document details some methods for handling ABI management in the DPDK.
> -Note this document is not exhaustive, in that C library versioning is flexible
> -allowing multiple methods to achieve various goals, but it will provide the user
> -with some introductory methods
>
> General Guidelines
> ------------------
>
> #. Whenever possible, ABI should be preserved
> -#. Libraries or APIs marked in ``experimental`` state may change without constraint.
> +#. 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 modification of symbols can generally be managed with versioning
> #. 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.
>
> 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
> @@ -39,9 +37,13 @@ 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.
>
> -The DPDK ABI policy
> +
> +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.
> @@ -99,8 +101,36 @@ readability purposes should be avoided.
> follow the relevant deprecation policy procedures as above: 3 acks and
> announcement at least one release in advance.
>
> +Examples of Deprecation Notices
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The following are some examples of ABI deprecation notices which would be
> +added to the Release Notes:
> +
> +* The Macro ``#RTE_FOO`` is deprecated and will be removed with version 2.0,
> + to be replaced with the inline function ``rte_foo()``.
> +
> +* The function ``rte_mbuf_grok()`` has been updated to include a new parameter
> + in version 2.0. Backwards compatibility will be maintained for this function
> + until the release of version 2.1
> +
> +* The members of ``struct rte_foo`` have been reorganized in release 2.0 for
> + performance reasons. Existing binary applications will have backwards
> + compatibility in release 2.0, while newly built binaries will need to
> + reference the new structure variant ``struct rte_foo2``. Compatibility will
> + be removed in release 2.2, and all applications will require updating and
> + rebuilding to the new structure at that time, which will be renamed to the
> + original ``struct rte_foo``.
> +
> +* Significant ABI changes are planned for the ``librte_dostuff`` library. The
> + upcoming release 2.0 will not contain these changes, but release 2.1 will,
> + and no backwards compatibility is planned due to the extensive nature of
> + these changes. Binaries using this library built prior to version 2.1 will
> + require updating and recompilation.
> +
> +
> Experimental APIs
> -~~~~~~~~~~~~~~~~~
> +-----------------
>
> APIs marked as ``experimental`` are not considered part of the ABI and may
> change without warning at any time. Since changes to APIs are most likely
> @@ -130,35 +160,38 @@ is not required. Though, an API should remain in experimental state for at least
> one release. Thereafter, normal process of posting patch for review to mailing
> list can be followed.
>
> -Examples of Deprecation Notices
> --------------------------------
>
> -The following are some examples of ABI deprecation notices which would be
> -added to the Release Notes:
> +Library versioning
> +------------------
>
> -* The Macro ``#RTE_FOO`` is deprecated and will be removed with version 2.0,
> - to be replaced with the inline function ``rte_foo()``.
> +Downstreams might want to provide different DPDK releases at the same time to
> +support multiple consumers of DPDK linked against older and newer sonames.
>
> -* The function ``rte_mbuf_grok()`` has been updated to include a new parameter
> - in version 2.0. Backwards compatibility will be maintained for this function
> - until the release of version 2.1
> +Also due to the interdependencies that DPDK libraries can have applications
> +might end up with an executable space in which multiple versions of a library
> +are mapped by ld.so.
>
> -* The members of ``struct rte_foo`` have been reorganized in release 2.0 for
> - performance reasons. Existing binary applications will have backwards
> - compatibility in release 2.0, while newly built binaries will need to
> - reference the new structure variant ``struct rte_foo2``. Compatibility will
> - be removed in release 2.2, and all applications will require updating and
> - rebuilding to the new structure at that time, which will be renamed to the
> - original ``struct rte_foo``.
> +Think of LibA that got an ABI bump and LibB that did not get an ABI bump but is
> +depending on LibA.
>
> -* Significant ABI changes are planned for the ``librte_dostuff`` library. The
> - upcoming release 2.0 will not contain these changes, but release 2.1 will,
> - and no backwards compatibility is planned due to the extensive nature of
> - these changes. Binaries using this library built prior to version 2.1 will
> - require updating and recompilation.
> +.. note::
> +
> + Application
> + \-> LibA.old
> + \-> LibB.new -> LibA.new
> +
> +That is a conflict which can be avoided by setting ``CONFIG_RTE_MAJOR_ABI``.
> +If set, the value of ``CONFIG_RTE_MAJOR_ABI`` overwrites all - otherwise per
> +library - versions defined in the libraries ``LIBABIVER``.
> +An example might be ``CONFIG_RTE_MAJOR_ABI=16.11`` which will make all libraries
> +``librte<?>.so.16.11`` instead of ``librte<?>.so.<LIBABIVER>``.
> +
> +
> +ABI versioning
> +--------------
>
> Versioning Macros
> ------------------
> +~~~~~~~~~~~~~~~~~
>
> When a symbol is exported from a library to provide an API, it also provides a
> calling convention (ABI) that is embodied in its name, return type and
> @@ -186,36 +219,11 @@ The macros exported are:
> fully qualified function ``p``, so that if a symbol becomes versioned, it
> can still be mapped back to the public symbol name.
>
> -Setting a Major ABI version
> ----------------------------
> -
> -Downstreams might want to provide different DPDK releases at the same time to
> -support multiple consumers of DPDK linked against older and newer sonames.
> -
> -Also due to the interdependencies that DPDK libraries can have applications
> -might end up with an executable space in which multiple versions of a library
> -are mapped by ld.so.
> -
> -Think of LibA that got an ABI bump and LibB that did not get an ABI bump but is
> -depending on LibA.
> -
> -.. note::
> -
> - Application
> - \-> LibA.old
> - \-> LibB.new -> LibA.new
> -
> -That is a conflict which can be avoided by setting ``CONFIG_RTE_MAJOR_ABI``.
> -If set, the value of ``CONFIG_RTE_MAJOR_ABI`` overwrites all - otherwise per
> -library - versions defined in the libraries ``LIBABIVER``.
> -An example might be ``CONFIG_RTE_MAJOR_ABI=16.11`` which will make all libraries
> -``librte<?>.so.16.11`` instead of ``librte<?>.so.<LIBABIVER>``.
> -
> Examples of ABI Macro use
> --------------------------
> +^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Updating a public API
> -~~~~~~~~~~~~~~~~~~~~~
> +_____________________
>
> Assume we have a function as follows
>
> @@ -425,7 +433,7 @@ and a new DPDK_2.1 version, used by future built applications.
>
>
> Deprecating part of a public API
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +________________________________
>
> Lets assume that you've done the above update, and after a few releases have
> passed you decide you would like to retire the old version of the function.
> @@ -483,7 +491,7 @@ possibly incompatible library version:
> +LIBABIVER := 2
>
> Deprecating an entire ABI version
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +_________________________________
>
> While removing a symbol from and ABI may be useful, it is often more practical
> to remove an entire version node at once. If a version node completely
> @@ -532,6 +540,7 @@ Lastly, any VERSION_SYMBOL macros that point to the old version node should be
> removed, taking care to keep, where need old code in place to support newer
> versions of the symbol.
>
> +
> Running the ABI Validator
> -------------------------
>
> @@ -571,3 +580,4 @@ compile both tags) it will create compatibility reports in the
> follows::
>
> grep -lr Incompatible compat_reports/
> +
> --
> 2.17.2
>
>
Series
Acked-by: Neil Horman <nhorman@tuxdriver.com>
next prev parent reply other threads:[~2019-01-23 8:13 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-12-19 12:52 [dpdk-dev] [RFC 1/2] " Ferruh Yigit
2018-12-19 12:52 ` [dpdk-dev] [RFC 2/2] doc: add deprecation marker usage Ferruh Yigit
2018-12-20 8:02 ` Luca Boccassi
2018-12-21 15:52 ` Ferruh Yigit
2018-12-20 8:02 ` [dpdk-dev] [RFC 1/2] doc: clean ABI/API policy guide Luca Boccassi
2018-12-20 8:03 ` Luca Boccassi
2018-12-21 15:57 ` [dpdk-dev] [PATCH v2 " Ferruh Yigit
2018-12-21 15:57 ` [dpdk-dev] [PATCH v2 2/2] doc: add deprecation marker usage Ferruh Yigit
2019-01-22 16:23 ` [dpdk-dev] [PATCH v3 1/3] doc: clean ABI/API policy guide Ferruh Yigit
2019-01-22 16:23 ` [dpdk-dev] [PATCH v3 2/3] doc: make RTE_NEXT_ABI optional Ferruh Yigit
2019-01-22 16:23 ` [dpdk-dev] [PATCH v3 3/3] doc: add deprecation marker usage Ferruh Yigit
2019-01-23 23:07 ` Kevin Traynor
2019-01-24 14:31 ` Ferruh Yigit
2019-01-24 15:33 ` Kevin Traynor
2019-01-24 16:29 ` Ferruh Yigit
2019-01-23 8:13 ` Neil Horman [this message]
2019-01-24 18:10 ` [dpdk-dev] [PATCH v4 1/3] doc: clean ABI/API policy guide Ferruh Yigit
2019-01-24 18:10 ` [dpdk-dev] [PATCH v4 2/3] doc: make RTE_NEXT_ABI optional Ferruh Yigit
2019-01-31 17:18 ` Thomas Monjalon
2019-01-24 18:10 ` [dpdk-dev] [PATCH v4 3/3] doc: add deprecation marker usage Ferruh Yigit
2019-01-31 17:17 ` Thomas Monjalon
2019-02-01 17:06 ` Ferruh Yigit
2019-03-01 16:46 ` Thomas Monjalon
2019-01-31 17:46 ` [dpdk-dev] [PATCH v4 1/3] doc: clean ABI/API policy guide Kevin Traynor
2019-03-01 17:32 ` [dpdk-dev] [PATCH v5 " Ferruh Yigit
2019-03-01 17:32 ` [dpdk-dev] [PATCH v5 2/3] doc: make RTE_NEXT_ABI optional Ferruh Yigit
2019-03-01 17:32 ` [dpdk-dev] [PATCH v5 3/3] doc: add deprecation marker usage Ferruh Yigit
2019-03-01 17:40 ` Kevin Traynor
2019-03-27 13:29 ` Thomas Monjalon
2019-03-27 13:29 ` Thomas Monjalon
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:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190123081327.GA4864@neilslaptop.think-freely.org \
--to=nhorman@tuxdriver.com \
--cc=bluca@debian.org \
--cc=dev@dpdk.org \
--cc=ferruh.yigit@intel.com \
--cc=john.mcnamara@intel.com \
--cc=ktraynor@redhat.com \
--cc=marko.kovacevic@intel.com \
--cc=yskoh@mellanox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* 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).