FM10K/dpdk-fm10k
FM10K/dpdk-fm10k
1
0
Fork 0
Code Issues Pull requests Releases Activity

compat: provide experimental alias for matured ABI

Browse source 
On v20.02 some APIs matured and symbols moved from EXPERIMENTAL to
DPDK_20.0.1 block.

This had the affect of breaking the applications that were using these
APIs on v19.11. Although there is no modification of the APIs and the
action is positive and matures the APIs, the affect can be negative to
applications.

When a maintainer is promoting an API to become part of the next major
ABI version by removing the experimental tag. The maintainer may
choose to offer an alias to the experimental tag, to prevent these
breakages in future.

The following changes are made to enabling aliasing:

Updated to the ABI policy and ABI versioning documents.

Created VERSION_SYMBOL_EXPERIMENTAL helper macro.

Updated the 'check-symbols.sh' tool, which was complaining that the
symbol is in EXPERIMENTAL tag in .map file but it is not in the
.experimental section (__rte_experimental tag is missing).
Updated tool in a way it won't complain if the symbol in the
EXPERIMENTAL tag duplicated in some other block in .map file (versioned)

Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: Neil Horman <nhorman@tuxdriver.com>
This commit is contained in:
Ferruh Yigit 2020-05-15 16:01:53 +01:00 committed by Thomas Monjalon
parent 45a4103e68
commit 05a38d7c75
4 changed files with 177 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
buildtools/check-symbols.sh
View file

@ -26,7 +26,8 @@ ret=0
for SYM in `$LIST_SYMBOL -S EXPERIMENTAL $MAPFILE |cut -d ' ' -f 3`
do
if grep -q "\.text.*[[:space:]]$SYM$" $DUMPFILE &&
! grep -q "\.text\.experimental.*[[:space:]]$SYM$" $DUMPFILE
! grep -q "\.text\.experimental.*[[:space:]]$SYM$" $DUMPFILE &&
$LIST_SYMBOL -s $SYM $MAPFILE | grep -q EXPERIMENTAL
then
cat >&2 <<- END_OF_MESSAGE
$SYM is not flagged as experimental

10
doc/guides/contributing/abi_policy.rst
View file

@ -160,6 +160,11 @@ The requirements for changing the ABI are:
``experimental``, as described in the section on :ref:`Experimental APIs
and Libraries <experimental_apis>`.
- In situations in which an ``experimental`` symbol has been stable for some
time. When promoting the symbol to become part of the next ABI version, the
maintainer may choose to provide an alias to the ``experimental`` tag, so
as not to break consuming applications.
#. If a newly proposed API functionally replaces an existing one, when the new
API becomes non-experimental, then the old one is marked with
``__rte_deprecated``.
@ -318,6 +323,11 @@ not required. Though, an API should remain in experimental state for at least
one release. Thereafter, the normal process of posting patch for review to
mailing list can be followed.
After the experimental tag has been formally removed, a tree/sub-tree maintainer
may choose to offer an alias to the experimental tag so as not to break
applications using the symbol. The alias is then dropped at the declaration of
next major ABI version.
Libraries
~~~~~~~~~

156
doc/guides/contributing/abi_versioning.rst
View file

@ -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
@ -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 <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

9
lib/librte_eal/include/rte_function_versioning.h
View file

@ -46,6 +46,14 @@
*/
#define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
/*
* VERSION_SYMBOL_EXPERIMENTAL
* Creates a symbol version table entry binding the symbol <b>@EXPERIMENTAL to the internal
* function name <b><e>. The macro is used when a symbol matures to become part of the stable ABI,
* to provide an alias to experimental for some time.
*/
#define VERSION_SYMBOL_EXPERIMENTAL(b, e) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@EXPERIMENTAL")
/*
* BIND_DEFAULT_SYMBOL
* Creates a symbol version entry instructing the linker to bind references to
@ -79,6 +87,7 @@
* No symbol versioning in use
*/
#define VERSION_SYMBOL(b, e, n)
#define VERSION_SYMBOL_EXPERIMENTAL(b, e)
#define __vsym
#define BIND_DEFAULT_SYMBOL(b, e, n)
#define MAP_STATIC_SYMBOL(f, p) f __attribute__((alias(RTE_STR(p))))