doc/guides/contributing/abi_policy.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2018 The DPDK contributors
   3
   4 DPDK ABI/API policy
   5 ===================
   6
   7 Description
   8 -----------
   9
  10 This document details some methods for handling ABI management in the DPDK.
  11
  12 General Guidelines
  13 ------------------
  14
  15 #. Whenever possible, ABI should be preserved
  16 #. ABI/API may be changed with a deprecation process
  17 #. The modification of symbols can generally be managed with versioning
  18 #. Libraries or APIs marked in ``experimental`` state may change without constraint
  19 #. New APIs will be marked as ``experimental`` for at least one release to allow
  20    any issues found by users of the new API to be fixed quickly
  21 #. The addition of symbols is generally not problematic
  22 #. The removal of symbols generally is an ABI break and requires bumping of the
  23    LIBABIVER macro
  24 #. Updates to the minimum hardware requirements, which drop support for hardware which
  25    was previously supported, should be treated as an ABI change.
  26
  27 What is an ABI
  28 ~~~~~~~~~~~~~~
  29
  30 An ABI (Application Binary Interface) is the set of runtime interfaces exposed
  31 by a library. It is similar to an API (Application Programming Interface) but
  32 is the result of compilation.  It is also effectively cloned when applications
  33 link to dynamic libraries.  That is to say when an application is compiled to
  34 link against dynamic libraries, it is assumed that the ABI remains constant
  35 between the time the application is compiled/linked, and the time that it runs.
  36 Therefore, in the case of dynamic linking, it is critical that an ABI is
  37 preserved, or (when modified), done in such a way that the application is unable
  38 to behave improperly or in an unexpected fashion.
  39
  40
  41 ABI/API Deprecation
  42 -------------------
  43
  44 The DPDK ABI policy
  45 ~~~~~~~~~~~~~~~~~~~
  46
  47 ABI versions are set at the time of major release labeling, and the ABI may
  48 change multiple times, without warning, between the last release label and the
  49 HEAD label of the git tree.
  50
  51 ABI versions, once released, are available until such time as their
  52 deprecation has been noted in the Release Notes for at least one major release
  53 cycle. For example consider the case where the ABI for DPDK 2.0 has been
  54 shipped and then a decision is made to modify it during the development of
  55 DPDK 2.1. The decision will be recorded in the Release Notes for the DPDK 2.1
  56 release and the modification will be made available in the DPDK 2.2 release.
  57
  58 ABI versions may be deprecated in whole or in part as needed by a given
  59 update.
  60
  61 Some ABI changes may be too significant to reasonably maintain multiple
  62 versions. In those cases ABI's may be updated without backward compatibility
  63 being provided. The requirements for doing so are:
  64
  65 #. At least 3 acknowledgments of the need to do so must be made on the
  66    dpdk.org mailing list.
  67
  68    - The acknowledgment of the maintainer of the component is mandatory, or if
  69      no maintainer is available for the component, the tree/sub-tree maintainer
  70      for that component must acknowledge the ABI change instead.
  71
  72    - It is also recommended that acknowledgments from different "areas of
  73      interest" be sought for each deprecation, for example: from NIC vendors,
  74      CPU vendors, end-users, etc.
  75
  76 #. The changes (including an alternative map file) can be included with
  77    deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option,
  78    to provide more details about oncoming changes.
  79    ``RTE_NEXT_ABI`` wrapper will be removed when it become the default ABI.
  80    More preferred way to provide this information is sending the feature
  81    as a separate patch and reference it in deprecation notice.
  82
  83 #. A full deprecation cycle, as explained above, must be made to offer
  84    downstream consumers sufficient warning of the change.
  85
  86 Note that the above process for ABI deprecation should not be undertaken
  87 lightly. ABI stability is extremely important for downstream consumers of the
  88 DPDK, especially when distributed in shared object form. Every effort should
  89 be made to preserve the ABI whenever possible. The ABI should only be changed
  90 for significant reasons, such as performance enhancements. ABI breakage due to
  91 changes such as reorganizing public structure fields for aesthetic or
  92 readability purposes should be avoided.
  93
  94 .. note::
  95
  96    Updates to the minimum hardware requirements, which drop support for hardware
  97    which was previously supported, should be treated as an ABI change, and
  98    follow the relevant deprecation policy procedures as above: 3 acks and
  99    announcement at least one release in advance.
 100
 101 Examples of Deprecation Notices
 102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 103
 104 The following are some examples of ABI deprecation notices which would be
 105 added to the Release Notes:
 106
 107 * The Macro ``#RTE_FOO`` is deprecated and will be removed with version 2.0,
 108   to be replaced with the inline function ``rte_foo()``.
 109
 110 * The function ``rte_mbuf_grok()`` has been updated to include a new parameter
 111   in version 2.0. Backwards compatibility will be maintained for this function
 112   until the release of version 2.1
 113
 114 * The members of ``struct rte_foo`` have been reorganized in release 2.0 for
 115   performance reasons. Existing binary applications will have backwards
 116   compatibility in release 2.0, while newly built binaries will need to
 117   reference the new structure variant ``struct rte_foo2``. Compatibility will
 118   be removed in release 2.2, and all applications will require updating and
 119   rebuilding to the new structure at that time, which will be renamed to the
 120   original ``struct rte_foo``.
 121
 122 * Significant ABI changes are planned for the ``librte_dostuff`` library. The
 123   upcoming release 2.0 will not contain these changes, but release 2.1 will,
 124   and no backwards compatibility is planned due to the extensive nature of
 125   these changes. Binaries using this library built prior to version 2.1 will
 126   require updating and recompilation.
 127
 128 New API replacing previous one
 129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 130
 131 If a new API proposed functionally replaces an existing one, when the new API
 132 becomes non-experimental then the old one is marked with ``__rte_deprecated``.
 133 Deprecated APIs are removed completely just after the next LTS.
 134
 135 Reminder that old API should follow deprecation process to be removed.
 136
 137
 138 Experimental APIs
 139 -----------------
 140
 141 APIs marked as ``experimental`` are not considered part of the ABI and may
 142 change without warning at any time.  Since changes to APIs are most likely
 143 immediately after their introduction, as users begin to take advantage of
 144 those new APIs and start finding issues with them, new DPDK APIs will be
 145 automatically marked as ``experimental`` to allow for a period of stabilization
 146 before they become part of a tracked ABI.
 147
 148 Note that marking an API as experimental is a multi step process.
 149 To mark an API as experimental, the symbols which are desired to be exported
 150 must be placed in an EXPERIMENTAL version block in the corresponding libraries'
 151 version map script.
 152 Secondly, the corresponding prototypes of those exported functions (in the
 153 development header files), must be marked with the ``__rte_experimental`` tag
 154 (see ``rte_compat.h``).
 155 The DPDK build makefiles perform a check to ensure that the map file and the
 156 C code reflect the same list of symbols.
 157 This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``
 158 during compilation in the corresponding library Makefile.
 159
 160 In addition to tagging the code with ``__rte_experimental``,
 161 the doxygen markup must also contain the EXPERIMENTAL string,
 162 and the MAINTAINERS file should note the EXPERIMENTAL libraries.
 163
 164 For removing the experimental tag associated with an API, deprecation notice
 165 is not required. Though, an API should remain in experimental state for at least
 166 one release. Thereafter, normal process of posting patch for review to mailing
 167 list can be followed.