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
~~~~~~~~~~~~~~~~~~
``be`` to signal that it is being used as an implementation of a particular
version of symbol ``b``.
+* ``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.
+
.. _example_abi_macro_usage:
Examples of ABI Macro use
library or driver. In the libraries or driver where we have added symbol
versioning, in the ``meson.build`` file we add the following
-.. code-block::
+.. code-block:: none
use_function_versioning = true
enable the function version macros when building. There is no corresponding
directive required for the ``make`` build system.
+
+.. _aliasing_experimental_symbols:
+
+Aliasing experimental symbols
+_____________________________
+
+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
+``experimental`` symbol version, so as not to break consuming applications.
+
+The process to provide an alias to ``experimental`` is similar to that, of
+:ref:`symbol versioning <example_abi_macro_usage>` described above.
+Assume we have an experimental function ``rte_acl_create`` as follows:
+
+.. code-block:: c
+
+ #include <rte_compat.h>
+
+ /*
+ * Create an acl context object for apps to
+ * manipulate
+ */
+ __rte_experimental
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+ ...
+ }
+
+In the map file, experimental symbols are listed as part of the ``EXPERIMENTAL``
+version node.
+
+.. code-block:: none
+
+ DPDK_20 {
+ global:
+ ...
+
+ local: *;
+ };
+
+ EXPERIMENTAL {
+ global:
+
+ rte_acl_create;
+ };
+
+When we promote the symbol to the stable ABI, we simply strip the
+``__rte_experimental`` annotation from the function and move the symbol from the
+``EXPERIMENTAL`` node, to the node of the next major ABI version as follow.
+
+.. code-block:: c
+
+ /*
+ * Create an acl context object for apps to
+ * manipulate
+ */
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+ ...
+ }
+
+We then update the map file, adding the symbol ``rte_acl_create``
+to the ``DPDK_21`` version node.
+
+.. code-block:: none
+
+ DPDK_20 {
+ global:
+ ...
+
+ local: *;
+ };
+
+ DPDK_21 {
+ global:
+
+ rte_acl_create;
+ } DPDK_20;
+
+
+Although there are strictly no guarantees or commitments associated with
+:ref:`experimental symbols <experimental_apis>`, a maintainer may wish to offer
+an alias to experimental. The process to add an alias to experimental,
+is similar to the symbol versioning process. Assuming we have an experimental
+symbol as before, we now add the symbol to both the ``EXPERIMENTAL``
+and ``DPDK_21`` version nodes.
+
+.. code-block:: c
+
+ #include <rte_compat.h>;
+ #include <rte_function_versioning.h>
+
+ /*
+ * Create an acl context object for apps to
+ * manipulate
+ */
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+ ...
+ }
+
+ __rte_experimental
+ struct rte_acl_ctx *
+ rte_acl_create_e(const struct rte_acl_param *param)
+ {
+ return rte_acl_create(param);
+ }
+ VERSION_SYMBOL_EXPERIMENTAL(rte_acl_create, _e);
+
+ struct rte_acl_ctx *
+ rte_acl_create_v21(const struct rte_acl_param *param)
+ {
+ return rte_acl_create(param);
+ }
+ BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 21);
+
+In the map file, we map the symbol to both the ``EXPERIMENTAL``
+and ``DPDK_21`` version nodes.
+
+.. code-block:: none
+
+ DPDK_20 {
+ global:
+ ...
+
+ local: *;
+ };
+
+ DPDK_21 {
+ global:
+
+ rte_acl_create;
+ } DPDK_20;
+
+ EXPERIMENTAL {
+ global:
+
+ rte_acl_create;
+ };
+
+.. note::
+
+ Please note, similar to :ref:`symbol versioning <example_abi_macro_usage>`,
+ when aliasing to experimental you will also need to take care of
+ :ref:`mapping static symbols <mapping_static_symbols>`.
+
+
.. _abi_deprecation:
Deprecating part of a public API
-------------------------
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>`_.
-
-This has a dependency on the ``abi-compliance-checker`` and ``and abi-dumper``
-utilities which can be installed via a package manager. For example::
-
- sudo yum install abi-compliance-checker
- sudo yum install abi-dumper
-
-The syntax of the ``validate-abi.sh`` utility is::
-
- ./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-abi.sh``, for validating the DPDK ABI based on the libabigail
+`abidiff utility <https://sourceware.org/libabigail/manual/abidiff.html>`_.
- # Check between two tags:
- ./devtools/validate-abi.sh v2.0.0 v2.1.0
+The syntax of the ``check-abi.sh`` utility is::
- # Check between git master and local topic-branch "vhost-hacking":
- ./devtools/validate-abi.sh master vhost-hacking
+ devtools/check-abi.sh <refdir> <newdir>
-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::
+Where <refdir> specifies the directory housing the reference build of DPDK,
+and <newdir> specifies the DPDK build directory to check the ABI of.
- 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