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