X-Git-Url: https://gerrit.fd.io/r/gitweb?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fversioning.rst;h=01b36247e79c043eccef277487e514e13a29e9ec;hb=b63264c8342e6a1b6971c79550d2af2024b6a4de;hp=08e2e217d9354f0a8230e8589b817cf6aea24ba1;hpb=6b3e017e5d25f15da73f7700f7f2ac553ef1a2e9;p=deb_dpdk.git diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst index 08e2e217..01b36247 100644 --- a/doc/guides/contributing/versioning.rst +++ b/doc/guides/contributing/versioning.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 The DPDK contributors + Managing ABI updates ==================== @@ -13,11 +16,15 @@ General Guidelines ------------------ #. Whenever possible, ABI should be preserved -#. The libraries marked in experimental state may change without constraint. +#. 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 -------------- @@ -56,6 +63,14 @@ 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) must be gated with the ``RTE_NEXT_ABI`` option, and provided with a deprecation notice at the same time. @@ -77,6 +92,44 @@ for significant reasons, such as performance enhancements. ABI breakage due to changes such as reorganizing public structure fields for aesthetic or readability purposes should be avoided. +.. note:: + + Updates to the minimum hardware requirements, which drop support for hardware + which was previously supported, should be treated as an ABI change, and + follow the relevant deprecation policy procedures as above: 3 acks and + announcement at least one release in advance. + +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 +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. + +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 definitions of those exported functions, and +their forward declarations (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. + Examples of Deprecation Notices ------------------------------- @@ -133,6 +186,31 @@ 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.``. + Examples of ABI Macro use ------------------------- @@ -457,7 +535,7 @@ versions of the symbol. Running the ABI Validator ------------------------- -The ``scripts`` directory in the DPDK source tree contains a utility program, +The ``devtools`` directory in the DPDK source tree contains a utility program, ``validate-abi.sh``, for validating the DPDK ABI based on the Linux `ABI Compliance Checker `_. @@ -470,7 +548,7 @@ utilities which can be installed via a package manager. For example:: The syntax of the ``validate-abi.sh`` utility is:: - ./scripts/validate-abi.sh + ./devtools/validate-abi.sh Where ``REV1`` and ``REV2`` are valid gitrevisions(7) https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html @@ -479,13 +557,13 @@ on the local repo and target is the usual DPDK compilation target. For example:: # Check between the previous and latest commit: - ./scripts/validate-abi.sh HEAD~1 HEAD x86_64-native-linuxapp-gcc + ./devtools/validate-abi.sh HEAD~1 HEAD x86_64-native-linuxapp-gcc # Check between two tags: - ./scripts/validate-abi.sh v2.0.0 v2.1.0 x86_64-native-linuxapp-gcc + ./devtools/validate-abi.sh v2.0.0 v2.1.0 x86_64-native-linuxapp-gcc # Check between git master and local topic-branch "vhost-hacking": - ./scripts/validate-abi.sh master vhost-hacking x86_64-native-linuxapp-gcc + ./devtools/validate-abi.sh master vhost-hacking x86_64-native-linuxapp-gcc After the validation script completes (it can take a while since it need to compile both tags) it will create compatibility reports in the