1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright 2019 The DPDK contributors 3 4ABI Policy 5========== 6 7Description 8----------- 9 10This document details the management policy that ensures the long-term stability 11of the DPDK ABI and API. 12 13General Guidelines 14------------------ 15 16#. Major ABI versions are declared no more frequently than yearly. Compatibility 17 with the major ABI version is mandatory in subsequent releases until a 18 :ref:`new major ABI version <new_abi_version>` is declared. 19#. Major ABI versions are usually but not always declared aligned with a 20 :ref:`LTS release <stable_lts_releases>`. 21#. The ABI version is managed at a project level in DPDK, and is reflected in 22 all non-experimental :ref:`library's soname <what_is_soname>`. 23#. The ABI should be preserved and not changed lightly. ABI changes must follow 24 the outlined :ref:`deprecation process <abi_changes>`. 25#. The addition of symbols is generally not problematic. The modification of 26 symbols is managed with :ref:`ABI Versioning <abi_versioning>`. 27#. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`, 28 once approved these will form part of the next ABI version. 29#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may 30 be changed or removed without prior notice, as they are not considered part 31 of an ABI version. 32#. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop 33 support for hardware which was previously supported, should be treated as an 34 ABI change. 35 36.. note:: 37 38 Please note that this policy does not currently apply to the 39 :doc:`Windows build <../windows_gsg/intro>`. 40 41What is an ABI? 42~~~~~~~~~~~~~~~ 43 44An ABI (Application Binary Interface) is the set of runtime interfaces exposed 45by a library. It is similar to an API (Application Programming Interface) but 46is the result of compilation. It is also effectively cloned when applications 47link to dynamic libraries. That is to say when an application is compiled to 48link against dynamic libraries, it is assumed that the ABI remains constant 49between the time the application is compiled/linked, and the time that it runs. 50Therefore, in the case of dynamic linking, it is critical that an ABI is 51preserved, or (when modified), done in such a way that the application is unable 52to behave improperly or in an unexpected fashion. 53 54.. _figure_what_is_an_abi: 55 56.. figure:: img/what_is_an_abi.* 57 58 Illustration of DPDK API and ABI. 59 60 61What is an ABI version? 62~~~~~~~~~~~~~~~~~~~~~~~ 63 64An ABI version is an instance of a library's ABI at a specific release. Certain 65releases are considered to be milestone releases, the yearly LTS release for 66example. The ABI of a milestone release may be declared as a 'major ABI 67version', where this ABI version is then supported for some number of subsequent 68releases and is annotated in the library's :ref:`soname<what_is_soname>`. 69 70ABI version support in subsequent releases facilitates application upgrades, by 71enabling applications built against the milestone release to upgrade to 72subsequent releases of a library without a rebuild. 73 74More details on major ABI version can be found in the :ref:`ABI versioning 75<major_abi_versions>` guide. 76 77The DPDK ABI policy 78------------------- 79 80A new major ABI version is declared no more frequently than yearly, with 81declarations usually aligning with a LTS release, e.g. ABI 21 for DPDK 20.11. 82Compatibility with the major ABI version is then mandatory in subsequent 83releases until the next major ABI version is declared, e.g. ABI 22 for DPDK 8421.11. 85 86At the declaration of a major ABI version, major version numbers encoded in 87libraries' sonames are bumped to indicate the new version, with the minor 88version reset to ``0``. An example would be ``librte_eal.so.21.3`` would become 89``librte_eal.so.22.0``. 90 91The ABI may then change multiple times, without warning, between the last major 92ABI version increment and the HEAD label of the git tree, with the condition 93that ABI compatibility with the major ABI version is preserved and therefore 94sonames do not change. 95 96Minor versions are incremented to indicate the release of a new ABI compatible 97DPDK release, typically the DPDK quarterly releases. An example of this, might 98be that ``librte_eal.so.21.1`` would indicate the first ABI compatible DPDK 99release, following the declaration of the new major ABI version ``21``. 100 101An ABI version is supported in all new releases until the next major ABI version 102is declared. When changing the major ABI version, the release notes will detail 103all ABI changes. 104 105.. _figure_abi_stability_policy: 106 107.. figure:: img/abi_stability_policy.* 108 109 Mapping of new ABI versions and ABI version compatibility to DPDK 110 releases. 111 112.. _abi_changes: 113 114ABI Changes 115~~~~~~~~~~~ 116 117The ABI may still change after the declaration of a major ABI version, that is 118new APIs may be still added or existing APIs may be modified. 119 120.. Warning:: 121 122 Note that, this policy details the method by which the ABI may be changed, 123 with due regard to preserving compatibility and observing deprecation 124 notices. This process however should not be undertaken lightly, as a general 125 rule ABI stability is extremely important for downstream consumers of DPDK. 126 The API should only be changed for significant reasons, such as performance 127 enhancements. API breakages due to changes such as reorganizing public 128 structure fields for aesthetic or readability purposes should be avoided. 129 130The requirements for changing the ABI are: 131 132#. At least 3 acknowledgments of the need to do so must be made on the 133 dpdk.org mailing list. 134 135 - The acknowledgment of the maintainer of the component is mandatory, or if 136 no maintainer is available for the component, the tree/sub-tree maintainer 137 for that component must acknowledge the ABI change instead. 138 139 - The acknowledgment of three members of the technical board, as delegates 140 of the `technical board <https://core.dpdk.org/techboard/>`_ acknowledging 141 the need for the ABI change, is also mandatory. 142 143 - It is also recommended that acknowledgments from different "areas of 144 interest" be sought for each deprecation, for example: from NIC vendors, 145 CPU vendors, end-users, etc. 146 147#. Backward compatibility with the major ABI version must be maintained through 148 :ref:`abi_versioning`, with :ref:`forward-only <forward-only>` compatibility 149 offered for any ABI changes that are indicated to be part of the next ABI 150 version. 151 152 - In situations where backward compatibility is not possible, read the 153 section on :ref:`abi_breakages`. 154 155 - No backward or forward compatibility is offered for API changes marked as 156 ``experimental``, as described in the section on :ref:`Experimental APIs 157 and Libraries <experimental_apis>`. 158 159 - In situations in which an ``experimental`` symbol has been stable for some 160 time. When promoting the symbol to become part of the next ABI version, the 161 maintainer may choose to provide an alias to the ``experimental`` tag, so 162 as not to break consuming applications. 163 164#. If a newly proposed API functionally replaces an existing one, when the new 165 API becomes non-experimental, then the old one is marked with 166 ``__rte_deprecated``. 167 168 - The depreciated API should follow the notification process to be removed, 169 see :ref:`deprecation_notices`. 170 171 - At the declaration of the next major ABI version, those ABI changes then 172 become a formal part of the new ABI and the requirement to preserve ABI 173 compatibility with the last major ABI version is then dropped. 174 175 - The responsibility for removing redundant ABI compatibility code rests 176 with the original contributor of the ABI changes, failing that, then with 177 the contributor's company and then finally with the maintainer. 178 179.. _forward-only: 180 181.. Note:: 182 183 Note that forward-only compatibility is offered for those changes made 184 between major ABI versions. As a library's soname can only describe 185 compatibility with the last major ABI version, until the next major ABI 186 version is declared, these changes therefore cannot be resolved as a runtime 187 dependency through the soname. Therefore any application wishing to make use 188 of these ABI changes can only ensure that its runtime dependencies are met 189 through Operating System package versioning. 190 191.. _hw_rqmts: 192 193.. Note:: 194 195 Updates to the minimum hardware requirements, which drop support for hardware 196 which was previously supported, should be treated as an ABI change, and 197 follow the relevant deprecation policy procedures as above: 3 acks, technical 198 board approval and announcement at least one release in advance. 199 200.. _abi_breakages: 201 202ABI Breakages 203~~~~~~~~~~~~~ 204 205For those ABI changes that are too significant to reasonably maintain multiple 206symbol versions, there is an amended process. In these cases, ABIs may be 207updated without the requirement of backward compatibility being provided. These 208changes must follow the same process :ref:`described above <abi_changes>` as non-breaking 209changes, however with the following additional requirements: 210 211#. ABI breaking changes (including an alternative map file) can be included with 212 deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option, to provide 213 more details about oncoming changes. ``RTE_NEXT_ABI`` wrapper will be removed 214 at the declaration of the next major ABI version. 215 216#. Once approved, and after the deprecation notice has been observed these 217 changes will form part of the next declared major ABI version. 218 219Examples of ABI Changes 220~~~~~~~~~~~~~~~~~~~~~~~ 221 222The following are examples of allowable ABI changes occurring between 223declarations of major ABI versions. 224 225* DPDK 20.11 release defines the function ``rte_foo()`` ; ``rte_foo()`` 226 is part of the major ABI version ``21``. 227 228* DPDK 21.02 release defines a new function ``rte_foo(uint8_t bar)``. 229 This is not a problem as long as the symbol ``rte_foo@DPDK_21`` is 230 preserved through :ref:`abi_versioning`. 231 232 - The new function may be marked with the ``__rte_experimental`` tag for a 233 number of releases, as described in the section :ref:`experimental_apis`. 234 235 - Once ``rte_foo(uint8_t bar)`` becomes non-experimental, ``rte_foo()`` is 236 declared as ``__rte_deprecated`` and an deprecation notice is provided. 237 238* DPDK 20.11 is not re-released to include ``rte_foo(uint8_t bar)``, the new 239 version of ``rte_foo`` only exists from DPDK 21.02 onwards as described in the 240 :ref:`note on forward-only compatibility<forward-only>`. 241 242* DPDK 21.02 release defines the experimental function ``__rte_experimental 243 rte_baz()``. This function may or may not exist in the DPDK 21.05 release. 244 245* An application ``dPacket`` wishes to use ``rte_foo(uint8_t bar)``, before the 246 declaration of the DPDK ``22`` major ABI version. The application can only 247 ensure its runtime dependencies are met by specifying ``DPDK (>= 21.2)`` as 248 an explicit package dependency, as the soname can only indicate the 249 supported major ABI version. 250 251* At the release of DPDK 21.11, the function ``rte_foo(uint8_t bar)`` becomes 252 formally part of then new major ABI version DPDK ``22`` and ``rte_foo()`` may be 253 removed. 254 255.. _deprecation_notices: 256 257Examples of Deprecation Notices 258~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 259 260The following are some examples of ABI deprecation notices which would be 261added to the Release Notes: 262 263* The Macro ``#RTE_FOO`` is deprecated and will be removed with ABI version 264 22, to be replaced with the inline function ``rte_foo()``. 265 266* The function ``rte_mbuf_grok()`` has been updated to include a new parameter 267 in version 21.2. Backwards compatibility will be maintained for this function 268 until the release of the new DPDK major ABI version 22, in DPDK version 269 21.11. 270 271* The members of ``struct rte_foo`` have been reorganized in DPDK 21.02 for 272 performance reasons. Existing binary applications will have backwards 273 compatibility in release 21.02, while newly built binaries will need to 274 reference the new structure variant ``struct rte_foo2``. Compatibility will be 275 removed in release 21.11, and all applications will require updating and 276 rebuilding to the new structure at that time, which will be renamed to the 277 original ``struct rte_foo``. 278 279* Significant ABI changes are planned for the ``librte_dostuff`` library. The 280 upcoming release 21.02 will not contain these changes, but release 21.11 will, 281 and no backwards compatibility is planned due to the extensive nature of 282 these changes. Binaries using this library built prior to ABI version 22 will 283 require updating and recompilation. 284 285 286.. _new_abi_version: 287 288New ABI versions 289------------------ 290 291A new ABI version may be declared aligned with a given release. 292The requirement to preserve compatibility with the previous major ABI version 293is then dropped for the duration of this release cycle. 294This is commonly known as the *ABI breakage window*, 295and some amended rules apply during this cycle: 296 297 * The requirement to preserve compatibility with the previous major ABI 298 version, as described in the section :ref:`abi_changes` does not apply. 299 * Contributors of compatibility preserving code in previous releases, 300 are now required to remove this compatibility code, 301 as described in the section :ref:`abi_changes`. 302 * Symbol versioning references to the old ABI version are updated 303 to reference the new ABI version, 304 as described in the section :ref:`deprecating_entire_abi`. 305 * Contributors of aliases to experimental in previous releases, 306 as described in section :ref:`aliasing_experimental_symbols`, 307 are now required to remove these aliases. 308 * Finally, the *ABI breakage window* is *not* permission to circumvent 309 the other aspects of the procedures to make ABI changes 310 described in :ref:`abi_changes`, that is, 3 ACKs of the requirement 311 to break the ABI and the observance of a deprecation notice 312 are still considered mandatory. 313 314.. _experimental_apis: 315 316Experimental 317------------ 318 319APIs 320~~~~ 321 322APIs marked as ``experimental`` are not considered part of an ABI version and 323may be changed or removed without prior notice. Since changes to APIs are most likely 324immediately after their introduction, as users begin to take advantage of those 325new APIs and start finding issues with them, new DPDK APIs will be automatically 326marked as ``experimental`` to allow for a period of stabilization before they 327become part of a tracked ABI version. 328 329Note that marking an API as experimental is a multi step process. 330To mark an API as experimental, the symbols which are desired to be exported 331must be placed in an EXPERIMENTAL version block in the corresponding libraries' 332version map script. 333Secondly, the corresponding prototypes of those exported functions (in the 334development header files), must be marked with the ``__rte_experimental`` tag 335(see ``rte_compat.h``). 336The DPDK build makefiles perform a check to ensure that the map file and the 337C code reflect the same list of symbols. 338This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API`` 339during compilation in the corresponding library Makefile. 340 341In addition to tagging the code with ``__rte_experimental``, 342the doxygen markup must also contain the EXPERIMENTAL string, 343and the MAINTAINERS file should note the EXPERIMENTAL libraries. 344 345For removing the experimental tag associated with an API, deprecation notice is 346not required. Though, an API should remain in experimental state for at least 347one release. Thereafter, the normal process of posting patch for review to 348mailing list can be followed. 349 350After the experimental tag has been formally removed, a tree/sub-tree maintainer 351may choose to offer an alias to the experimental tag so as not to break 352applications using the symbol. The alias is then dropped at the declaration of 353next major ABI version. 354 355Libraries 356~~~~~~~~~ 357 358Libraries marked as ``experimental`` are entirely not considered part of an ABI 359version. 360All functions in such libraries may be changed or removed without prior notice. 361