-Managing ABI updates
-====================
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2018 The DPDK contributors
+
+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
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.
-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
-immediately after their introduction, as users begin to take advantage of
-those new APIs and start finding issues with them, new DPDK APIs will be
-automatically marked as ``experimental`` to allow for a period of stabilization
-before they become part of a tracked ABI.
-
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
interest" be sought for each deprecation, for example: from NIC vendors,
CPU vendors, end-users, etc.
-#. The changes (including an alternative map file) must be gated with
- the ``RTE_NEXT_ABI`` option, and provided with a deprecation notice at the
- same time.
- It will become the default ABI in the next release.
+#. 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.
+ More preferred way to provide this information is sending the feature
+ as a separate patch and reference it in deprecation notice.
#. A full deprecation cycle, as explained above, must be made to offer
downstream consumers sufficient warning of the change.
-#. At the beginning of the next release cycle, every ``RTE_NEXT_ABI``
- conditions will be removed, the ``LIBABIVER`` variable in the makefile(s)
- where the ABI is changed will be incremented, and the map files will
- be updated.
-
Note that the above process for ABI deprecation should not be undertaken
lightly. ABI stability is extremely important for downstream consumers of the
DPDK, especially when distributed in shared object form. Every effort should
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:
these changes. Binaries using this library built prior to version 2.1 will
require updating and recompilation.
-Versioning Macros
------------------
+New API replacing previous one
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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
-arguments. Occasionally that function may need to change to accommodate new
-functionality or behavior. When that occurs, it is desirable to allow for
-backward compatibility for a time with older binaries that are dynamically
-linked to the DPDK.
+If a new API proposed functionally replaces an existing one, when the new API
+becomes non-experimental then the old one is marked with ``__rte_deprecated``.
+Deprecated APIs are removed completely just after the next LTS.
-To support backward compatibility the ``lib/librte_compat/rte_compat.h``
-header file provides macros to use when updating exported functions. These
-macros are used in conjunction with the ``rte_<library>_version.map`` file for
-a given library to allow multiple versions of a symbol to exist in a shared
-library so that older binaries need not be immediately recompiled.
+Reminder that old API should follow deprecation process to be removed.
-The macros exported are:
-* ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry binding
- versioned symbol ``b@DPDK_n`` to the internal function ``b_e``.
-
-* ``BIND_DEFAULT_SYMBOL(b, e, n)``: Creates a symbol version entry instructing
- the linker to bind references to symbol ``b`` to the internal symbol
- ``b_e``.
+Experimental APIs
+-----------------
-* ``MAP_STATIC_SYMBOL(f, p)``: Declare the prototype ``f``, and map it to the
- fully qualified function ``p``, so that if a symbol becomes versioned, it
- can still be mapped back to the public symbol name.
+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
+immediately after their introduction, as users begin to take advantage of
+those new APIs and start finding issues with them, new DPDK APIs will be
+automatically marked as ``experimental`` to allow for a period of stabilization
+before they become part of a tracked ABI.
-Setting a Major ABI version
----------------------------
+Note that marking an API as experimental is a multi step process.
+To mark an API as experimental, the symbols which are desired to be exported
+must be placed in an EXPERIMENTAL version block in the corresponding libraries'
+version map script.
+Secondly, the corresponding prototypes of those exported functions (in the
+development header files), must be marked with the ``__rte_experimental`` tag
+(see ``rte_compat.h``).
+The DPDK build makefiles perform a check to ensure that the map file and the
+C code reflect the same list of symbols.
+This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``
+during compilation in the corresponding library Makefile.
+
+In addition to tagging the code with ``__rte_experimental``,
+the doxygen markup must also contain the EXPERIMENTAL string,
+and the MAINTAINERS file should note the EXPERIMENTAL libraries.
+
+For removing the experimental tag associated with an API, deprecation notice
+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.
+
+
+Library versioning
+------------------
Downstreams might want to provide different DPDK releases at the same time to
support multiple consumers of DPDK linked against older and newer sonames.
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
+arguments. Occasionally that function may need to change to accommodate new
+functionality or behavior. When that occurs, it is desirable to allow for
+backward compatibility for a time with older binaries that are dynamically
+linked to the DPDK.
+
+To support backward compatibility the ``rte_function_versioning.h``
+header file provides macros to use when updating exported functions. These
+macros are used in conjunction with the ``rte_<library>_version.map`` file for
+a given library to allow multiple versions of a symbol to exist in a shared
+library so that older binaries need not be immediately recompiled.
+
+The macros exported are:
+
+* ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry binding
+ versioned symbol ``b@DPDK_n`` to the internal function ``be``.
+
+* ``BIND_DEFAULT_SYMBOL(b, e, n)``: Creates a symbol version entry instructing
+ the linker to bind references to symbol ``b`` to the internal symbol
+ ``be``.
+
+* ``MAP_STATIC_SYMBOL(f, p)``: Declare the prototype ``f``, and map it to the
+ fully qualified function ``p``, so that if a symbol becomes versioned, it
+ can still be mapped back to the public symbol name.
+
+* ``__vsym``: Annotation to be used in a declaration of the internal symbol
+ ``be`` to signal that it is being used as an implementation of a particular
+ version of symbol ``b``.
+
Examples of ABI Macro use
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
Updating a public API
-~~~~~~~~~~~~~~~~~~~~~
+_____________________
Assume we have a function as follows
.. code-block:: c
- struct rte_acl_ctx *
+ -struct rte_acl_ctx *
-rte_acl_create(const struct rte_acl_param *param)
+ +struct rte_acl_ctx * __vsym
+rte_acl_create_v20(const struct rte_acl_param *param)
{
size_t sz;
...
Note that the base name of the symbol was kept intact, as this is conducive to
-the macros used for versioning symbols. That is our next step, mapping this new
+the macros used for versioning symbols and we have annotated the function as an
+implementation of versioned symbol. That is our next step, mapping this new
symbol name to the initial symbol name at version node 2.0. Immediately after
the function, we add this line of code
VERSION_SYMBOL(rte_acl_create, _v20, 2.0);
-Remembering to also add the rte_compat.h header to the requisite c file where
+Remembering to also add the rte_function_versioning.h header to the requisite c file where
these changes are being made. The above macro instructs the linker to create a
new symbol ``rte_acl_create@DPDK_2.0``, which matches the symbol created in older
builds, but now points to the above newly named function. We have now mapped
.. code-block:: c
- struct rte_acl_ctx *
+ struct rte_acl_ctx * __vsym
rte_acl_create_v21(const struct rte_acl_param *param, int debug);
{
struct rte_acl_ctx *ctx = rte_acl_create_v20(param);
.. code-block:: c
- struct rte_acl_ctx *
+ struct rte_acl_ctx * __vsym
rte_acl_create_v21(const struct rte_acl_param *param, int debug)
{
...
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.
+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
removed, taking care to keep, where need old code in place to support newer
versions of the symbol.
+
Running the ABI Validator
-------------------------
The syntax of the ``validate-abi.sh`` utility is::
- ./devtools/validate-abi.sh <REV1> <REV2> <TARGET>
+ ./devtools/validate-abi.sh <REV1> <REV2>
Where ``REV1`` and ``REV2`` are valid gitrevisions(7)
https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html
-on the local repo and target is the usual DPDK compilation target.
+on the local repo.
For example::
# Check between the previous and latest commit:
- ./devtools/validate-abi.sh HEAD~1 HEAD x86_64-native-linuxapp-gcc
+ ./devtools/validate-abi.sh HEAD~1 HEAD
+
+ # Check on a specific compilation target:
+ ./devtools/validate-abi.sh -t x86_64-native-linux-gcc HEAD~1 HEAD
# Check between two tags:
- ./devtools/validate-abi.sh v2.0.0 v2.1.0 x86_64-native-linuxapp-gcc
+ ./devtools/validate-abi.sh v2.0.0 v2.1.0
# Check between git master and local topic-branch "vhost-hacking":
- ./devtools/validate-abi.sh master vhost-hacking x86_64-native-linuxapp-gcc
+ ./devtools/validate-abi.sh master vhost-hacking
After the validation script completes (it can take a while since it need to
compile both tags) it will create compatibility reports in the
-``./compat_report`` directory. Listed incompatibilities can be found as
-follows::
+``./abi-check/compat_report`` directory. Listed incompatibilities can be found
+as follows::
- grep -lr Incompatible compat_reports/
+ grep -lr Incompatible abi-check/compat_reports/
git.droids-corp.org / dpdk.git / blobdiff