X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fabi_versioning.rst;h=e96fde340f397747e5f68afdbc8a78cf17243b6b;hb=6735434917ab4af24063078b72d9ebd3b214b5de;hp=e526fb179a045a5b926037580b2abf06321042aa;hpb=45a4103e680d6b9bfb2b4ee4f4ef528d8de51ec0;p=dpdk.git diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst index e526fb179a..e96fde340f 100644 --- a/doc/guides/contributing/abi_versioning.rst +++ b/doc/guides/contributing/abi_versioning.rst @@ -156,6 +156,11 @@ The macros exported are: ``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 @@ -408,7 +413,7 @@ Finally, we need to indicate to the :doc:`meson/ninja build system 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 @@ -416,6 +421,157 @@ at the start of the head of the file. This will indicate to the tool-chain to 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 ` described above. +Assume we have an experimental function ``rte_acl_create`` as follows: + +.. code-block:: c + + #include + + /* + * 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 `, 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 ; + #include + + /* + * 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 `, + when aliasing to experimental you will also need to take care of + :ref:`mapping static symbols `. + + .. _abi_deprecation: Deprecating part of a public API @@ -526,41 +682,16 @@ 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 -`_. - -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 - -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 `_. - # 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 -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 specifies the directory housing the reference build of DPDK, +and 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`.