Re: [dpdk-dev] [PATCH v3 1/3] doc: clean ABI/API policy guide

[Neil Horman <nhorman@tuxdriver.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>