[dpdk-dev] [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation

Mcnamara, John john.mcnamara at intel.com
Tue Jan 23 11:35:49 CET 2018



> -----Original Message-----
> From: Neil Horman [mailto:nhorman at tuxdriver.com]
> Sent: Monday, January 22, 2018 1:48 AM
> To: dev at dpdk.org
> Cc: Neil Horman <nhorman at tuxdriver.com>; Thomas Monjalon
> <thomas at monjalon.net>; Mcnamara, John <john.mcnamara at intel.com>;
> Richardson, Bruce <bruce.richardson at intel.com>
> Subject: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation
> 
> Document the need to add the __experimental tag to appropriate functions
> 
> Signed-off-by: Neil Horman <nhorman at tuxdriver.com>
> CC: Thomas Monjalon <thomas at monjalon.net>
> CC: "Mcnamara, John" <john.mcnamara at intel.com>
> CC: Bruce Richardson <bruce.richardson at intel.com>
> ...
> +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 MAINTAINER
> +file should note that the library contains EXPERIMENTAL APIs.
> +
>  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
> --
> 2.14.3

Thanks for the update, and this work in general.

The rendered docs would probably look a better better with __rte_experimental
and ALLOW_EXPERIMENTAL_API is fixed width backticks ``var`` but that is only
a "nice to have" so no need for a respin.

Acked-by: John McNamara <john.mcnamara at intel.com>





More information about the dev mailing list