[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@dpdk.org

Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
---
Cc: Neil Horman <nhorman@tuxdriver.com>
Cc: Thomas Monjalon <thomas@monjalon.net>
Cc: Luca Boccassi <bluca@debian.org>
Cc: David Marchand <david.marchand@redhat.com>
Cc: Bruce Richardson <bruce.richardson@intel.com>
Cc: Ian Stokes <ian.stokes@intel.com>
Cc: Eelco Chaudron <echaudro@redhat.com>
Cc: Andrzej Ostruszka <amo@semihalf.com>
Cc: Ray Kinsella <mdr@ashroe.eu>
Cc: cristian.dumitrescu@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(-)
  

> -----Original Message-----
> From: Yigit, Ferruh <ferruh.yigit@intel.com>
> Sent: Tuesday, May 19, 2020 1:16 PM
> To: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>; Ray Kinsella
> <mdr@ashroe.eu>; Neil Horman <nhorman@tuxdriver.com>; Eelco
> Chaudron <echaudro@redhat.com>
> Cc: dev@dpdk.org; Yigit, Ferruh <ferruh.yigit@intel.com>; Thomas Monjalon
> <thomas@monjalon.net>; David Marchand <david.marchand@redhat.com>;
> stable@dpdk.org; Luca Boccassi <bluca@debian.org>; Richardson, Bruce
> <bruce.richardson@intel.com>; Stokes, Ian <ian.stokes@intel.com>; Andrzej
> Ostruszka <amo@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@dpdk.org
> 
> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> ---
> Cc: Neil Horman <nhorman@tuxdriver.com>
> Cc: Thomas Monjalon <thomas@monjalon.net>
> Cc: Luca Boccassi <bluca@debian.org>
> Cc: David Marchand <david.marchand@redhat.com>
> Cc: Bruce Richardson <bruce.richardson@intel.com>
> Cc: Ian Stokes <ian.stokes@intel.com>
> Cc: Eelco Chaudron <echaudro@redhat.com>
> Cc: Andrzej Ostruszka <amo@semihalf.com>
> Cc: Ray Kinsella <mdr@ashroe.eu>
> Cc: cristian.dumitrescu@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@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.
  

On 19/05/2020 13:16, Ferruh Yigit wrote:
> 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@dpdk.org
> 
> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> ---
> Cc: Neil Horman <nhorman@tuxdriver.com>
> Cc: Thomas Monjalon <thomas@monjalon.net>
> Cc: Luca Boccassi <bluca@debian.org>
> Cc: David Marchand <david.marchand@redhat.com>
> Cc: Bruce Richardson <bruce.richardson@intel.com>
> Cc: Ian Stokes <ian.stokes@intel.com>
> Cc: Eelco Chaudron <echaudro@redhat.com>
> Cc: Andrzej Ostruszka <amo@semihalf.com>
> Cc: Ray Kinsella <mdr@ashroe.eu>
> Cc: cristian.dumitrescu@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_config, _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;
> +};
> 
Acked-by: Ray Kinsella <mdr@ashroe.eu>
  

19/05/2020 15:26, Dumitrescu, Cristian:
> From: Yigit, Ferruh <ferruh.yigit@intel.com>
> > 
> > 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@dpdk.org
> > 
> > Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> 
> Acked-by: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
> 
> Thanks, Ferruh and Ray!
> 
> I am OK to let this is temporarily until release 20.11.

Applied, thanks



> Regarding the API breakage larger problem,
> this method only fixes the case of experimental APIs transitioning
> to non-experimental status with no modifications,

Yes

> but it does not handle the following possible cases:
> 
> 	1. Experimental APIs transitioning to non-experimental status with some modifications.

If there is a modification, it should mature as experimental first.

> 	2. Experimental APIs being removed.

No guarantee that an experimental API remains forever.

> 	3. Non-experimental APIs transitioning to deprecated status.

I don't think we need to deprecate experimental API.
We can change or remove them freely at any time.

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

We can ask if there are different opinions.
I think the experimental status is quite clear: no guarantee.