[dpdk-stable] [PATCH v6] meter: provide experimental alias of API for old apps

[Dumitrescu, Cristian]

> -----Original Message-----
> From: Yigit, Ferruh <ferruh.yigit at intel.com>
> Sent: Tuesday, May 19, 2020 1:16 PM
> To: Dumitrescu, Cristian <cristian.dumitrescu at intel.com>; Ray Kinsella
> <mdr at ashroe.eu>; Neil Horman <nhorman at tuxdriver.com>; Eelco
> Chaudron <echaudro at redhat.com>
> Cc: dev at dpdk.org; Yigit, Ferruh <ferruh.yigit at intel.com>; Thomas Monjalon
> <thomas at monjalon.net>; David Marchand <david.marchand at redhat.com>;
> stable at dpdk.org; Luca Boccassi <bluca at debian.org>; Richardson, Bruce
> <bruce.richardson at intel.com>; Stokes, Ian <ian.stokes at intel.com>; Andrzej
> Ostruszka <amo at semihalf.com>
> Subject: [PATCH v6] meter: provide experimental alias of API for old apps
> 
> On v20.02 some meter APIs have been matured and symbols moved from
> EXPERIMENTAL to DPDK_20.0.1 block.
> 
> This can break the applications that were using these mentioned APIs on
> v19.11. Although there is no modification on the APIs and the action is
> positive and matures the APIs, the affect can be negative to
> applications.
> 
> This patch provides aliasing by duplicating the existing and versioned
> symbols as experimental.
> 
> Since symbols moved from DPDK_20.0.1 to DPDK_21 block in the v20.05, the
> aliasing done between EXPERIMENTAL and DPDK_21.
> 
> With DPDK_21 ABI (DPDK v20.11) all aliasing will be removed and only
> stable version of the APIs will remain.
> 
> Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM
> API")
> Cc: stable at dpdk.org
> 
> Signed-off-by: Ferruh Yigit <ferruh.yigit at intel.com>
> ---
> Cc: Neil Horman <nhorman at tuxdriver.com>
> Cc: Thomas Monjalon <thomas at monjalon.net>
> Cc: Luca Boccassi <bluca at debian.org>
> Cc: David Marchand <david.marchand at redhat.com>
> Cc: Bruce Richardson <bruce.richardson at intel.com>
> Cc: Ian Stokes <ian.stokes at intel.com>
> Cc: Eelco Chaudron <echaudro at redhat.com>
> Cc: Andrzej Ostruszka <amo at semihalf.com>
> Cc: Ray Kinsella <mdr at ashroe.eu>
> Cc: cristian.dumitrescu at intel.com
> 
> v2:
> * Commit log updated
> 
> v3:
> * added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro
> 
> v4:
> * update script name in commit log, remove empty line
> 
> v5:
> * Patch has only meter library changes
> * Aliasing moved into rte_meter_compat.c
> 
> v6:
> * Move aliasing back to rte_meter.c
> * Rename static function to have '__' prefix
> * Add comment to alias code
> ---
>  lib/librte_meter/meson.build           |  1 +
>  lib/librte_meter/rte_meter.c           | 73 ++++++++++++++++++++++++--
>  lib/librte_meter/rte_meter_version.map |  8 +++
>  3 files changed, 79 insertions(+), 3 deletions(-)
> 
> diff --git a/lib/librte_meter/meson.build b/lib/librte_meter/meson.build
> index 646fd4d43f..fce0368437 100644
> --- a/lib/librte_meter/meson.build
> +++ b/lib/librte_meter/meson.build
> @@ -3,3 +3,4 @@
> 
>  sources = files('rte_meter.c')
>  headers = files('rte_meter.h')
> +use_function_versioning = true
> diff --git a/lib/librte_meter/rte_meter.c b/lib/librte_meter/rte_meter.c
> index da01429a8b..149cf58bdd 100644
> --- a/lib/librte_meter/rte_meter.c
> +++ b/lib/librte_meter/rte_meter.c
> @@ -9,6 +9,7 @@
>  #include <rte_common.h>
>  #include <rte_log.h>
>  #include <rte_cycles.h>
> +#include <rte_function_versioning.h>
> 
>  #include "rte_meter.h"
> 
> @@ -119,8 +120,15 @@ rte_meter_trtcm_config(struct rte_meter_trtcm
> *m,
>  	return 0;
>  }
> 
> -int
> -rte_meter_trtcm_rfc4115_profile_config(
> +/*
> + *  ABI aliasing done for 'rte_meter_trtcm_rfc4115_profile_config'
> + *  to support both EXPERIMENTAL and DPDK_21 versions
> + *  This versioning will be removed on next ABI version (v20.11)
> + *  and '__rte_meter_trtcm_rfc4115_profile_config' will be restrored back
> to
> + *  'rte_meter_trtcm_rfc4115_profile_config' without versioning.
> + */
> +static int
> +__rte_meter_trtcm_rfc4115_profile_config(
>  	struct rte_meter_trtcm_rfc4115_profile *p,
>  	struct rte_meter_trtcm_rfc4115_params *params)
>  {
> @@ -145,7 +153,42 @@ rte_meter_trtcm_rfc4115_profile_config(
>  }
> 
>  int
> -rte_meter_trtcm_rfc4115_config(
> +rte_meter_trtcm_rfc4115_profile_config_s(
> +	struct rte_meter_trtcm_rfc4115_profile *p,
> +	struct rte_meter_trtcm_rfc4115_params *params);
> +int
> +rte_meter_trtcm_rfc4115_profile_config_s(
> +	struct rte_meter_trtcm_rfc4115_profile *p,
> +	struct rte_meter_trtcm_rfc4115_params *params)
> +{
> +	return __rte_meter_trtcm_rfc4115_profile_config(p, params);
> +}
> +BIND_DEFAULT_SYMBOL(rte_meter_trtcm_rfc4115_profile_config, _s, 21);
> +MAP_STATIC_SYMBOL(int rte_meter_trtcm_rfc4115_profile_config(struct
> rte_meter_trtcm_rfc4115_profile *p,
> +		struct rte_meter_trtcm_rfc4115_params *params),
> rte_meter_trtcm_rfc4115_profile_config_s);
> +
> +int
> +rte_meter_trtcm_rfc4115_profile_config_e(
> +	struct rte_meter_trtcm_rfc4115_profile *p,
> +	struct rte_meter_trtcm_rfc4115_params *params);
> +int
> +rte_meter_trtcm_rfc4115_profile_config_e(
> +	struct rte_meter_trtcm_rfc4115_profile *p,
> +	struct rte_meter_trtcm_rfc4115_params *params)
> +{
> +	return __rte_meter_trtcm_rfc4115_profile_config(p, params);
> +}
> +VERSION_SYMBOL_EXPERIMENTAL(rte_meter_trtcm_rfc4115_profile_conf
> ig, _e);
> +
> +/*
> + *  ABI aliasing done for 'rte_meter_trtcm_rfc4115_config'
> + *  to support both EXPERIMENTAL and DPDK_21 versions
> + *  This versioning will be removed on next ABI version (v20.11)
> + *  and '__rte_meter_trtcm_rfc4115_config' will be restrored back to
> + *  'rte_meter_trtcm_rfc4115_config' without versioning.
> + */
> +static int
> +__rte_meter_trtcm_rfc4115_config(
>  	struct rte_meter_trtcm_rfc4115 *m,
>  	struct rte_meter_trtcm_rfc4115_profile *p)
>  {
> @@ -160,3 +203,27 @@ rte_meter_trtcm_rfc4115_config(
> 
>  	return 0;
>  }
> +
> +int
> +rte_meter_trtcm_rfc4115_config_s(struct rte_meter_trtcm_rfc4115 *m,
> +	struct rte_meter_trtcm_rfc4115_profile *p);
> +int
> +rte_meter_trtcm_rfc4115_config_s(struct rte_meter_trtcm_rfc4115 *m,
> +	struct rte_meter_trtcm_rfc4115_profile *p)
> +{
> +	return __rte_meter_trtcm_rfc4115_config(m, p);
> +}
> +BIND_DEFAULT_SYMBOL(rte_meter_trtcm_rfc4115_config, _s, 21);
> +MAP_STATIC_SYMBOL(int rte_meter_trtcm_rfc4115_config(struct
> rte_meter_trtcm_rfc4115 *m,
> +		 struct rte_meter_trtcm_rfc4115_profile *p),
> rte_meter_trtcm_rfc4115_config_s);
> +
> +int
> +rte_meter_trtcm_rfc4115_config_e(struct rte_meter_trtcm_rfc4115 *m,
> +	struct rte_meter_trtcm_rfc4115_profile *p);
> +int
> +rte_meter_trtcm_rfc4115_config_e(struct rte_meter_trtcm_rfc4115 *m,
> +	struct rte_meter_trtcm_rfc4115_profile *p)
> +{
> +	return __rte_meter_trtcm_rfc4115_config(m, p);
> +}
> +VERSION_SYMBOL_EXPERIMENTAL(rte_meter_trtcm_rfc4115_config, _e);
> diff --git a/lib/librte_meter/rte_meter_version.map
> b/lib/librte_meter/rte_meter_version.map
> index 2c7dadbcac..b493bcebe9 100644
> --- a/lib/librte_meter/rte_meter_version.map
> +++ b/lib/librte_meter/rte_meter_version.map
> @@ -20,4 +20,12 @@ DPDK_21 {
>  	rte_meter_trtcm_rfc4115_color_blind_check;
>  	rte_meter_trtcm_rfc4115_config;
>  	rte_meter_trtcm_rfc4115_profile_config;
> +
>  } DPDK_20.0;
> +
> +EXPERIMENTAL {
> +       global:
> +
> +	rte_meter_trtcm_rfc4115_config;
> +	rte_meter_trtcm_rfc4115_profile_config;
> +};
> --
> 2.25.4

Acked-by: Cristian Dumitrescu <cristian.dumitrescu at intel.com>

Thanks, Ferruh and Ray!

I am OK to let this is temporarily until release 20.11.

Regarding the API breakage larger problem,  this method only fixes the case of experimental APIs transitioning to non-experimental status with no modifications, but it does not handle the following possible cases:

	1. Experimental APIs transitioning to non-experimental status with some modifications.
	2. Experimental APIs being removed.
	3. Non-experimental APIs transitioning to deprecated status.

We need a clear procedure & timing for all these cases to avoid similar situations in the future. Likely a good topic for techboard discussion.