these changes. Binaries using this library built prior to version 2.1 will
require updating and recompilation.
+New API replacing previous one
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+Reminder that old API should follow deprecation process to be removed.
+
Experimental APIs
-----------------
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``).
+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``
backward compatibility for a time with older binaries that are dynamically
linked to the DPDK.
-To support backward compatibility the ``rte_compat.h``
+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
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``.
+ 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
- ``b_e``.
+ ``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
^^^^^^^^^^^^^^^^^^^^^^^^^
.. 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)
{
...
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-linux-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-linux-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-linux-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