.. code-block:: none
- $ head ./lib/librte_acl/rte_acl_version.map
+ $ head ./lib/librte_acl/version.map
DPDK_20 {
global:
...
- $ head ./lib/librte_eal/rte_eal_version.map
+ $ head ./lib/librte_eal/version.map
DPDK_20 {
global:
...
.. code-block:: none
- $ head ./lib/librte_acl/rte_acl_version.map
+ $ head ./lib/librte_acl/version.map
DPDK_20 {
global:
...
} DPDK_20;
...
- $ head ./lib/librte_eal/rte_eal_version.map
+ $ head ./lib/librte_eal/version.map
DPDK_20 {
global:
...
.. code-block:: none
- $ head ./lib/librte_acl/rte_acl_version.map
+ $ head ./lib/librte_acl/version.map
DPDK_21 {
global:
...
- $ head ./lib/librte_eal/rte_eal_version.map
+ $ head ./lib/librte_eal/version.map
DPDK_21 {
global:
...
At the same time, the major ABI version is changed atomically across all
libraries by incrementing the major version in the ABI_VERSION file. This is
-done globally for all libraries that declare a stable ABI. For libraries marked
-as EXPERIMENTAL, their major ABI version is always set to 0.
+done globally for all libraries.
Minor ABI versions
~~~~~~~~~~~~~~~~~~
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
+macros are used in conjunction with the ``version.map`` file for
a given library to allow multiple versions of a symbol to exist in a shared
library so that older binaries need not be immediately recompiled.
* ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
The macro is used when a symbol matures to become part of the stable ABI, to
- provide an alias to experimental for some time.
+ provide an alias to experimental until the next major ABI version.
.. _example_abi_macro_usage:
In situations in which an ``experimental`` symbol has been stable for some time,
and it becomes a candidate for promotion to the stable ABI. At this time, when
-promoting the symbol, maintainer may choose to provide an alias to the
+promoting the symbol, the maintainer may choose to provide an alias to the
``experimental`` symbol version, so as not to break consuming applications.
+This alias is then dropped in the next major ABI version.
The process to provide an alias to ``experimental`` is similar to that, of
:ref:`symbol versioning <example_abi_macro_usage>` described above.
-BIND_DEFAULT_SYMBOL(rte_acl_create, _v20, 20);
+BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 21);
-Lastly, any VERSION_SYMBOL macros that point to the old version node should be
-removed, taking care to keep, where need old code in place to support newer
-versions of the symbol.
+Lastly, any VERSION_SYMBOL macros that point to the old version nodes
+should be removed, taking care to preserve any code that is shared
+with the new version node.
Running the ABI Validator
-------------------------
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
-<http://ispras.linuxbase.org/index.php/ABI_compliance_checker>`_.
+``check-abi.sh``, for validating the DPDK ABI based on the libabigail
+`abidiff utility <https://sourceware.org/libabigail/manual/abidiff.html>`_.
-This has a dependency on the ``abi-compliance-checker`` and ``and abi-dumper``
-utilities which can be installed via a package manager. For example::
+The syntax of the ``check-abi.sh`` utility is::
- sudo yum install abi-compliance-checker
- sudo yum install abi-dumper
+ devtools/check-abi.sh <refdir> <newdir>
-The syntax of the ``validate-abi.sh`` utility is::
+Where <refdir> specifies the directory housing the reference build of DPDK,
+and <newdir> specifies the DPDK build directory to check the ABI of.
- ./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.
-
-For example::
-
- # Check between the previous and latest commit:
- ./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
-
- # Check between git master and local topic-branch "vhost-hacking":
- ./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
-``./abi-check/compat_report`` directory. Listed incompatibilities can be found
-as follows::
-
- grep -lr Incompatible abi-check/compat_reports/
+The ABI compatibility is automatically verified when using a build script
+from ``devtools``, if the variable ``DPDK_ABI_REF_VERSION`` is set with a tag,
+as described in :ref:`ABI check recommendations<integrated_abi_check>`.
git.droids-corp.org / dpdk.git / blobdiff