d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: add ABI experimental tag in versioning guide

Browse Source 
Document the need to add the __experimental tag to appropriate functions

Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
This commit is contained in:
Neil Horman 2018-01-21 20:48:07 -05:00 committed by Thomas Monjalon
parent a6ec31597a
commit 2843cdd93a
1 changed files with 16 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/guides/contributing/versioning.rst
View File

@ -50,6 +50,22 @@ those new APIs and start finding issues with them, new DPDK APIs will be
automatically marked as ``experimental`` to allow for a period of stabilization
before they become part of a tracked ABI.
Note that marking an API as experimental is a multi step process.
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``).
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``
during compilation in the corresponding library Makefile.
In addition to tagging the code with ``__rte_experimental``,
the doxygen markup must also contain the EXPERIMENTAL string,
and the MAINTAINERS file should note the EXPERIMENTAL libraries.
ABI versions, once released, are available until such time as their
deprecation has been noted in the Release Notes for at least one major release
cycle. For example consider the case where the ABI for DPDK 2.0 has been