[dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Ferruh Yigit]

Duplicated the existing symbol and versioned one as experimental and
other as stable.

Created VERSION_SYMBOL_EXPERIMENTAL helper macro.

Updated the 'check-experimental-syms.sh' buildtool, 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)

Updated meson build system to allow the versioning,
'use_function_versioning = true', not sure why it was disabled by
default.

Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")

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>

I didn't like the idea of duplicating the symbol but not able to find to
alias it without duplicating, if there is a way please share.

Also not tested with old binaries, only verified the symbols in new
binaries.
---
 buildtools/check-experimental-syms.sh         |  3 +-
 .../common/include/rte_function_versioning.h  |  4 ++
 lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
 lib/librte_meter/rte_meter_version.map        |  8 +++
 lib/meson.build                               |  2 +-
 5 files changed, 71 insertions(+), 5 deletions(-)

diff --git a/buildtools/check-experimental-syms.sh b/buildtools/check-experimental-syms.sh
index f3603e5ba..35c4bf006 100755
--- a/buildtools/check-experimental-syms.sh
+++ b/buildtools/check-experimental-syms.sh
@@ -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
diff --git a/lib/librte_eal/common/include/rte_function_versioning.h b/lib/librte_eal/common/include/rte_function_versioning.h
index c924351d5..ab102b06e 100644
--- a/lib/librte_eal/common/include/rte_function_versioning.h
+++ b/lib/librte_eal/common/include/rte_function_versioning.h
@@ -46,6 +46,9 @@
  */
 #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
 
+
+#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 +82,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))))
diff --git a/lib/librte_meter/rte_meter.c b/lib/librte_meter/rte_meter.c
index da01429a8..5244537fa 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
 	return 0;
 }
 
-int
-rte_meter_trtcm_rfc4115_profile_config(
+static int
+rte_meter_trtcm_rfc4115_profile_config_(
 	struct rte_meter_trtcm_rfc4115_profile *p,
 	struct rte_meter_trtcm_rfc4115_params *params)
 {
@@ -145,7 +146,35 @@ 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, 20.0.1);
+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);
+
+static int
+rte_meter_trtcm_rfc4115_config_(
 	struct rte_meter_trtcm_rfc4115 *m,
 	struct rte_meter_trtcm_rfc4115_profile *p)
 {
@@ -160,3 +189,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, 20.0.1);
+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 fc12cc0bf..b4b043174 100644
--- a/lib/librte_meter/rte_meter_version.map
+++ b/lib/librte_meter/rte_meter_version.map
@@ -20,4 +20,12 @@ DPDK_20.0.1 {
 	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;
+};
diff --git a/lib/meson.build b/lib/meson.build
index 0af3efab2..553964831 100644
--- a/lib/meson.build
+++ b/lib/meson.build
@@ -48,7 +48,7 @@ foreach l:libraries
 	reason = '<unknown reason>' # set if build == false to explain why
 	name = l
 	allow_experimental_apis = false
-	use_function_versioning = false
+	use_function_versioning = true
 	sources = []
 	headers = []
 	includes = []
-- 
2.24.1

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Bruce Richardson]

On Wed, Jan 29, 2020 at 12:29:53PM +0000, Ferruh Yigit wrote:
> Duplicated the existing symbol and versioned one as experimental and
> other as stable.
> 
> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> Updated the 'check-experimental-syms.sh' buildtool, 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)
> 
> Updated meson build system to allow the versioning,
> 'use_function_versioning = true', not sure why it was disabled by
> default.
> 

Because when enabled everything in the library must be built twice - once
for static lib and differently for a dynamic lib. Therefore unless a
library actually needs versioned symbols, we only build everything once to
save on build time.

/Bruce

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Andrzej Ostruszka]

On 1/29/20 1:29 PM, Ferruh Yigit wrote:
[...]
> Updated meson build system to allow the versioning,
> 'use_function_versioning = true', not sure why it was disabled by
> default.

AFAIR this is to save build time with meson.  By default static build is
made and from the objects from the static build shared library is
constructed.  This works unless function versioning is used - because
for the static build "attribute alias" is used and for shared build
.symver is used.  So 'use_function_versioning' by default is false and
only libraries that actually use them have it set to true (and perform
separate shared build - see lib/meson.build).

I've now noticed that LPM, Distributor and Timer libraries no longer use
function versioning but have it still set in their meson.build.

With regards
Andrzej Ostruszka

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Ferruh Yigit]

On 1/29/2020 2:57 PM, Andrzej Ostruszka wrote:
> On 1/29/20 1:29 PM, Ferruh Yigit wrote:
> [...]
>> Updated meson build system to allow the versioning,
>> 'use_function_versioning = true', not sure why it was disabled by
>> default.
> 
> AFAIR this is to save build time with meson.  By default static build is
> made and from the objects from the static build shared library is
> constructed.  This works unless function versioning is used - because
> for the static build "attribute alias" is used and for shared build
> .symver is used.  So 'use_function_versioning' by default is false and
> only libraries that actually use them have it set to true (and perform
> separate shared build - see lib/meson.build).

Hi Andrzej,

Thanks for clarification, I will reduce it to the library.

> 
> I've now noticed that LPM, Distributor and Timer libraries no longer use
> function versioning but have it still set in their meson.build.

Right, I can remove them.

> 
> With regards
> Andrzej Ostruszka
> 

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Andrzej Ostruszka]

On 1/29/20 5:25 PM, Ferruh Yigit wrote:
> On 1/29/2020 2:57 PM, Andrzej Ostruszka wrote:
[...]
>> I've now noticed that LPM, Distributor and Timer libraries no longer use
>> function versioning but have it still set in their meson.build.
> 
> Right, I can remove them.

Bruce was kind enough to give me a nudge for that :).
If you decide to do it in one patch let me know so that I can drop my
patch in patchwork.

With regards
Andrzej Ostruszka

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Ferruh Yigit]

On 1/29/2020 4:30 PM, Andrzej Ostruszka wrote:
> On 1/29/20 5:25 PM, Ferruh Yigit wrote:
>> On 1/29/2020 2:57 PM, Andrzej Ostruszka wrote:
> [...]
>>> I've now noticed that LPM, Distributor and Timer libraries no longer use
>>> function versioning but have it still set in their meson.build.
>>
>> Right, I can remove them.
> 
> Bruce was kind enough to give me a nudge for that :).
> If you decide to do it in one patch let me know so that I can drop my
> patch in patchwork.

Separate patch makes more sense, thanks for the patch.

[dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Ferruh Yigit]

Duplicated the existing symbol and versioned one as experimental and
other as stable.

Created VERSION_SYMBOL_EXPERIMENTAL helper macro.

Updated the 'check-experimental-syms.sh' buildtool, 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)

Enabled function versioning for meson build for the library.

Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")

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>

v2:
* allow versioning only for meter library, instead of enabling it
  globally

I didn't like the idea of duplicating the symbol but not able to find to
alias it without duplicating, if there is a way please share.

Also not tested with old binaries, only verified the symbols in new
binaries.
---
 buildtools/check-experimental-syms.sh         |  3 +-
 .../common/include/rte_function_versioning.h  |  4 ++
 lib/librte_meter/meson.build                  |  1 +
 lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
 lib/librte_meter/rte_meter_version.map        |  8 +++
 5 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/buildtools/check-experimental-syms.sh b/buildtools/check-experimental-syms.sh
index f3603e5ba..35c4bf006 100755
--- a/buildtools/check-experimental-syms.sh
+++ b/buildtools/check-experimental-syms.sh
@@ -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
diff --git a/lib/librte_eal/common/include/rte_function_versioning.h b/lib/librte_eal/common/include/rte_function_versioning.h
index c924351d5..ab102b06e 100644
--- a/lib/librte_eal/common/include/rte_function_versioning.h
+++ b/lib/librte_eal/common/include/rte_function_versioning.h
@@ -46,6 +46,9 @@
  */
 #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
 
+
+#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 +82,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))))
diff --git a/lib/librte_meter/meson.build b/lib/librte_meter/meson.build
index 646fd4d43..fce036843 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 da01429a8..5244537fa 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
 	return 0;
 }
 
-int
-rte_meter_trtcm_rfc4115_profile_config(
+static int
+rte_meter_trtcm_rfc4115_profile_config_(
 	struct rte_meter_trtcm_rfc4115_profile *p,
 	struct rte_meter_trtcm_rfc4115_params *params)
 {
@@ -145,7 +146,35 @@ 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, 20.0.1);
+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);
+
+static int
+rte_meter_trtcm_rfc4115_config_(
 	struct rte_meter_trtcm_rfc4115 *m,
 	struct rte_meter_trtcm_rfc4115_profile *p)
 {
@@ -160,3 +189,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, 20.0.1);
+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 fc12cc0bf..b4b043174 100644
--- a/lib/librte_meter/rte_meter_version.map
+++ b/lib/librte_meter/rte_meter_version.map
@@ -20,4 +20,12 @@ DPDK_20.0.1 {
 	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.24.1

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Andrzej Ostruszka]

On 1/29/20 5:43 PM, Ferruh Yigit wrote:
[...]
> diff --git a/lib/librte_meter/rte_meter.c b/lib/librte_meter/rte_meter.c
> index da01429a8..5244537fa 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
>  	return 0;
>  }
>  
> -int
> -rte_meter_trtcm_rfc4115_profile_config(
> +static int
> +rte_meter_trtcm_rfc4115_profile_config_(
>  	struct rte_meter_trtcm_rfc4115_profile *p,
>  	struct rte_meter_trtcm_rfc4115_params *params)
>  {
> @@ -145,7 +146,35 @@ 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, 20.0.1);

You might want to mark these version symbols with __vsym macro.  Without
this shared lib build with LTO might remove them (due to long standing
gcc bug - it does not have proper way to mark .symver in internal
representation and so does not recognize that function is used).

This comment is global - for all symbols mentioned in BIND_/VERSION_ macros.

Out of curiosity - why do you need separate declaration just before
definition?

With regards
Andrzej Ostruszka

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Thomas Monjalon]

Hi,

I disagree with the need of this patch.
The symbol was experimental, meaning we can change it.
Removing experimental tag is not an ABI break.


29/01/2020 17:43, Ferruh Yigit:
> Duplicated the existing symbol and versioned one as experimental and
> other as stable.
[..]
> --- a/lib/librte_meter/rte_meter_version.map
> +++ b/lib/librte_meter/rte_meter_version.map
> @@ -20,4 +20,12 @@ DPDK_20.0.1 {
>  	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;
> +};

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Luca Boccassi]

On Thu, 2020-01-30 at 13:33 +0100, Thomas Monjalon wrote:
> Hi,
> 
> I disagree with the need of this patch.
> The symbol was experimental, meaning we can change it.
> Removing experimental tag is not an ABI break.

Hi,

This symbol change was requested for backport in 19.11.x, and
experimental or not I'm not too keen on backward incompatible changes
to the public interface in an _LTS point release_. The compromise was
to see if we could support both symbols version, which makes the change
backward compatible.

If you prefer not to have this patch in mainline I'm also fine in
taking it just for the LTS. I agree with you that it is not required
for mainline releases (although nicer for me if it's a backport rather
than a new change).

> 29/01/2020 17:43, Ferruh Yigit:
> > Duplicated the existing symbol and versioned one as experimental
> > and
> > other as stable.
> 
> [..]
> > --- a/lib/librte_meter/rte_meter_version.map
> > +++ b/lib/librte_meter/rte_meter_version.map
> > @@ -20,4 +20,12 @@ DPDK_20.0.1 {
> >  	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;
> > +};
> 
> 
> 
> 
> 
-- 
Kind regards,
Luca Boccassi

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Thomas Monjalon]

30/01/2020 13:57, Luca Boccassi:
> On Thu, 2020-01-30 at 13:33 +0100, Thomas Monjalon wrote:
> > Hi,
> > 
> > I disagree with the need of this patch.
> > The symbol was experimental, meaning we can change it.
> > Removing experimental tag is not an ABI break.
> 
> Hi,
> 
> This symbol change was requested for backport in 19.11.x, and
> experimental or not I'm not too keen on backward incompatible changes
> to the public interface in an _LTS point release_. The compromise was
> to see if we could support both symbols version, which makes the change
> backward compatible.
> 
> If you prefer not to have this patch in mainline I'm also fine in
> taking it just for the LTS. I agree with you that it is not required
> for mainline releases (although nicer for me if it's a backport rather
> than a new change).

I would like to avoid opening the door for maintaining the experimental ABI
in the mainline. Please take it directly in the LTS.

The next question is to know whether we really want to have such patch in LTS.
Anyway, 19.11.0 has this symbol as experimental.
How adding a non-experimental version of the function in 19.11.1 will change
the ABI status of the whole 19.11 branch?



> > 29/01/2020 17:43, Ferruh Yigit:
> > > Duplicated the existing symbol and versioned one as experimental
> > > and
> > > other as stable.
> > 
> > [..]
> > > --- a/lib/librte_meter/rte_meter_version.map
> > > +++ b/lib/librte_meter/rte_meter_version.map
> > > @@ -20,4 +20,12 @@ DPDK_20.0.1 {
> > >  	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;
> > > +};

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Luca Boccassi]

On Thu, 2020-01-30 at 15:17 +0100, Thomas Monjalon wrote:
> 30/01/2020 13:57, Luca Boccassi:
> > On Thu, 2020-01-30 at 13:33 +0100, Thomas Monjalon wrote:
> > > Hi,
> > > 
> > > I disagree with the need of this patch.
> > > The symbol was experimental, meaning we can change it.
> > > Removing experimental tag is not an ABI break.
> > 
> > Hi,
> > 
> > This symbol change was requested for backport in 19.11.x, and
> > experimental or not I'm not too keen on backward incompatible
> > changes
> > to the public interface in an _LTS point release_. The compromise
> > was
> > to see if we could support both symbols version, which makes the
> > change
> > backward compatible.
> > 
> > If you prefer not to have this patch in mainline I'm also fine in
> > taking it just for the LTS. I agree with you that it is not
> > required
> > for mainline releases (although nicer for me if it's a backport
> > rather
> > than a new change).
> 
> I would like to avoid opening the door for maintaining the
> experimental ABI
> in the mainline. Please take it directly in the LTS.
> 
> The next question is to know whether we really want to have such
> patch in LTS.
> Anyway, 19.11.0 has this symbol as experimental.
> How adding a non-experimental version of the function in 19.11.1 will
> change
> the ABI status of the whole 19.11 branch?

The problem is not adding the new symbol, but removing the experimental
one. Changing the version of the symbol was requested by OVS for
inclusion in 19.11.

-- 
Kind regards,
Luca Boccassi

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Thomas Monjalon]

30/01/2020 15:21, Luca Boccassi:
> On Thu, 2020-01-30 at 15:17 +0100, Thomas Monjalon wrote:
> > 30/01/2020 13:57, Luca Boccassi:
> > > On Thu, 2020-01-30 at 13:33 +0100, Thomas Monjalon wrote:
> > > > Hi,
> > > > 
> > > > I disagree with the need of this patch.
> > > > The symbol was experimental, meaning we can change it.
> > > > Removing experimental tag is not an ABI break.
> > > 
> > > Hi,
> > > 
> > > This symbol change was requested for backport in 19.11.x, and
> > > experimental or not I'm not too keen on backward incompatible
> > > changes
> > > to the public interface in an _LTS point release_. The compromise
> > > was
> > > to see if we could support both symbols version, which makes the
> > > change
> > > backward compatible.
> > > 
> > > If you prefer not to have this patch in mainline I'm also fine in
> > > taking it just for the LTS. I agree with you that it is not
> > > required
> > > for mainline releases (although nicer for me if it's a backport
> > > rather
> > > than a new change).
> > 
> > I would like to avoid opening the door for maintaining the
> > experimental ABI
> > in the mainline. Please take it directly in the LTS.
> > 
> > The next question is to know whether we really want to have such
> > patch in LTS.
> > Anyway, 19.11.0 has this symbol as experimental.
> > How adding a non-experimental version of the function in 19.11.1 will
> > change
> > the ABI status of the whole 19.11 branch?
> 
> The problem is not adding the new symbol, but removing the experimental
> one. Changing the version of the symbol was requested by OVS for
> inclusion in 19.11.

Yes, sorry, this is what I meant.
Given 19.11.0 already has the symbol as experimental,
and that applications like OVS had to accept it as experimental,
why removing experimental tag in 19.11.1?

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Luca Boccassi]

On Thu, 2020-01-30 at 16:55 +0100, Thomas Monjalon wrote:
> 30/01/2020 15:21, Luca Boccassi:
> > On Thu, 2020-01-30 at 15:17 +0100, Thomas Monjalon wrote:
> > > 30/01/2020 13:57, Luca Boccassi:
> > > > On Thu, 2020-01-30 at 13:33 +0100, Thomas Monjalon wrote:
> > > > > Hi,
> > > > > 
> > > > > I disagree with the need of this patch.
> > > > > The symbol was experimental, meaning we can change it.
> > > > > Removing experimental tag is not an ABI break.
> > > > 
> > > > Hi,
> > > > 
> > > > This symbol change was requested for backport in 19.11.x, and
> > > > experimental or not I'm not too keen on backward incompatible
> > > > changes
> > > > to the public interface in an _LTS point release_. The
> > > > compromise
> > > > was
> > > > to see if we could support both symbols version, which makes
> > > > the
> > > > change
> > > > backward compatible.
> > > > 
> > > > If you prefer not to have this patch in mainline I'm also fine
> > > > in
> > > > taking it just for the LTS. I agree with you that it is not
> > > > required
> > > > for mainline releases (although nicer for me if it's a backport
> > > > rather
> > > > than a new change).
> > > 
> > > I would like to avoid opening the door for maintaining the
> > > experimental ABI
> > > in the mainline. Please take it directly in the LTS.
> > > 
> > > The next question is to know whether we really want to have such
> > > patch in LTS.
> > > Anyway, 19.11.0 has this symbol as experimental.
> > > How adding a non-experimental version of the function in 19.11.1
> > > will
> > > change
> > > the ABI status of the whole 19.11 branch?
> > 
> > The problem is not adding the new symbol, but removing the
> > experimental
> > one. Changing the version of the symbol was requested by OVS for
> > inclusion in 19.11.
> 
> Yes, sorry, this is what I meant.
> Given 19.11.0 already has the symbol as experimental,
> and that applications like OVS had to accept it as experimental,
> why removing experimental tag in 19.11.1?

I think it was mentioned that it was preferred not to suppress the
compiler warning to avoid any accidental use in the future, but the OVS
maintainer(s) should answer as I might remember wrongly.

-- 
Kind regards,
Luca Boccassi

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Eelco Chaudron]

On 30 Jan 2020, at 17:04, Luca Boccassi wrote:

> On Thu, 2020-01-30 at 16:55 +0100, Thomas Monjalon wrote:
>> 30/01/2020 15:21, Luca Boccassi:
>>> On Thu, 2020-01-30 at 15:17 +0100, Thomas Monjalon wrote:
>>>> 30/01/2020 13:57, Luca Boccassi:
>>>>> On Thu, 2020-01-30 at 13:33 +0100, Thomas Monjalon wrote:
>>>>>> Hi,
>>>>>>
>>>>>> I disagree with the need of this patch.
>>>>>> The symbol was experimental, meaning we can change it.
>>>>>> Removing experimental tag is not an ABI break.
>>>>>
>>>>> Hi,
>>>>>
>>>>> This symbol change was requested for backport in 19.11.x, and
>>>>> experimental or not I'm not too keen on backward incompatible
>>>>> changes
>>>>> to the public interface in an _LTS point release_. The
>>>>> compromise
>>>>> was
>>>>> to see if we could support both symbols version, which makes
>>>>> the
>>>>> change
>>>>> backward compatible.
>>>>>
>>>>> If you prefer not to have this patch in mainline I'm also fine
>>>>> in
>>>>> taking it just for the LTS. I agree with you that it is not
>>>>> required
>>>>> for mainline releases (although nicer for me if it's a backport
>>>>> rather
>>>>> than a new change).
>>>>
>>>> I would like to avoid opening the door for maintaining the
>>>> experimental ABI
>>>> in the mainline. Please take it directly in the LTS.
>>>>
>>>> The next question is to know whether we really want to have such
>>>> patch in LTS.
>>>> Anyway, 19.11.0 has this symbol as experimental.
>>>> How adding a non-experimental version of the function in 19.11.1
>>>> will
>>>> change
>>>> the ABI status of the whole 19.11 branch?
>>>
>>> The problem is not adding the new symbol, but removing the
>>> experimental
>>> one. Changing the version of the symbol was requested by OVS for
>>> inclusion in 19.11.
>>
>> Yes, sorry, this is what I meant.
>> Given 19.11.0 already has the symbol as experimental,
>> and that applications like OVS had to accept it as experimental,
>> why removing experimental tag in 19.11.1?
>
> I think it was mentioned that it was preferred not to suppress the
> compiler warning to avoid any accidental use in the future, but the 
> OVS
> maintainer(s) should answer as I might remember wrongly.

Yes this is the reason, OVS compiles with -Werror so we would like to 
avoid the warnings. You can not disable them per include, it’s global 
for all of DPDK.

//Eelco

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Thomas Monjalon]

30/01/2020 17:15, Eelco Chaudron:
> On 30 Jan 2020, at 17:04, Luca Boccassi wrote:
> > On Thu, 2020-01-30 at 16:55 +0100, Thomas Monjalon wrote:
> >> 30/01/2020 15:21, Luca Boccassi:
> >>> On Thu, 2020-01-30 at 15:17 +0100, Thomas Monjalon wrote:
> >>>> 30/01/2020 13:57, Luca Boccassi:
> >>>>> On Thu, 2020-01-30 at 13:33 +0100, Thomas Monjalon wrote:
> >>>>>> Hi,
> >>>>>>
> >>>>>> I disagree with the need of this patch.
> >>>>>> The symbol was experimental, meaning we can change it.
> >>>>>> Removing experimental tag is not an ABI break.
> >>>>>
> >>>>> Hi,
> >>>>>
> >>>>> This symbol change was requested for backport in 19.11.x, and
> >>>>> experimental or not I'm not too keen on backward incompatible
> >>>>> changes
> >>>>> to the public interface in an _LTS point release_. The
> >>>>> compromise
> >>>>> was
> >>>>> to see if we could support both symbols version, which makes
> >>>>> the
> >>>>> change
> >>>>> backward compatible.
> >>>>>
> >>>>> If you prefer not to have this patch in mainline I'm also fine
> >>>>> in
> >>>>> taking it just for the LTS. I agree with you that it is not
> >>>>> required
> >>>>> for mainline releases (although nicer for me if it's a backport
> >>>>> rather
> >>>>> than a new change).
> >>>>
> >>>> I would like to avoid opening the door for maintaining the
> >>>> experimental ABI
> >>>> in the mainline. Please take it directly in the LTS.
> >>>>
> >>>> The next question is to know whether we really want to have such
> >>>> patch in LTS.
> >>>> Anyway, 19.11.0 has this symbol as experimental.
> >>>> How adding a non-experimental version of the function in 19.11.1
> >>>> will
> >>>> change
> >>>> the ABI status of the whole 19.11 branch?
> >>>
> >>> The problem is not adding the new symbol, but removing the
> >>> experimental
> >>> one. Changing the version of the symbol was requested by OVS for
> >>> inclusion in 19.11.
> >>
> >> Yes, sorry, this is what I meant.
> >> Given 19.11.0 already has the symbol as experimental,
> >> and that applications like OVS had to accept it as experimental,
> >> why removing experimental tag in 19.11.1?
> >
> > I think it was mentioned that it was preferred not to suppress the
> > compiler warning to avoid any accidental use in the future, but the 
> > OVS
> > maintainer(s) should answer as I might remember wrongly.
> 
> Yes this is the reason, OVS compiles with -Werror so we would like to 
> avoid the warnings. You can not disable them per include, it’s global 
> for all of DPDK.

Yes but anyway OVS must accept the experimental function as the next release
will use it with DPDK 19.11.0.

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Ferruh Yigit]

On 1/30/2020 12:33 PM, Thomas Monjalon wrote:
> Hi,
> 
> I disagree with the need of this patch.
> The symbol was experimental, meaning we can change it.
> Removing experimental tag is not an ABI break.

In theory what you said is correct, this is experimental API and anything can
happen to it, this is the contract.

And when we need to change an experimental API, the users will be affected,
there is no escape from it.

But for this case limitation is more mechanical I believe,
because API is not changing at all, and it is becoming mature.
So we are breaking the user application because the experimental API they are
using becoming mature without any change.
This looks annoying from the user perspective, and if we can prevent this break,
I am for preventing it.

> 
> 
> 29/01/2020 17:43, Ferruh Yigit:
>> Duplicated the existing symbol and versioned one as experimental and
>> other as stable.
> [..]
>> --- a/lib/librte_meter/rte_meter_version.map
>> +++ b/lib/librte_meter/rte_meter_version.map
>> @@ -20,4 +20,12 @@ DPDK_20.0.1 {
>>  	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;
>> +};
> 
> 
> 
> 

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Neil Horman]

On Wed, Jan 29, 2020 at 12:29:53PM +0000, Ferruh Yigit wrote:
> Duplicated the existing symbol and versioned one as experimental and
> other as stable.
> 
> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> Updated the 'check-experimental-syms.sh' buildtool, 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)
> 
> Updated meson build system to allow the versioning,
> 'use_function_versioning = true', not sure why it was disabled by
> default.
> 
> Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")
> 
I'm not sure I understand the purpose here.

I think I understand what you are trying to do. I believe that you are
trying to move the experimental symbols in librte_meter to be part of
the official ABI, while still maintaining backward compatibility with
applications built against the experimental symbol versions, correct?

I can understand the desire, and I'm not exactly opposed to providing a
mechanism for that, but it seems somewhat complex, and to be honest,
part of the drawback to using experimental symbols as an application
developer is understanding that you may need to rebuild when those
symbols change (even if the change is the symbol removal and replacement
with an identical one that has a versioned tag).

I think the right answer for people encountering this condition is to
just rebuild.  Otherwise, we are creating an environment in which we are
implicitly communicating to users that we are maintaining a modicum of
stability in experimental symobls.

A few more nits in line

> 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>
> 
> I didn't like the idea of duplicating the symbol but not able to find to
> alias it without duplicating, if there is a way please share.
> 
> Also not tested with old binaries, only verified the symbols in new
> binaries.
> ---
>  buildtools/check-experimental-syms.sh         |  3 +-
>  .../common/include/rte_function_versioning.h  |  4 ++
>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
>  lib/librte_meter/rte_meter_version.map        |  8 +++
>  lib/meson.build                               |  2 +-
>  5 files changed, 71 insertions(+), 5 deletions(-)
> 
> diff --git a/buildtools/check-experimental-syms.sh b/buildtools/check-experimental-syms.sh
> index f3603e5ba..35c4bf006 100755
> --- a/buildtools/check-experimental-syms.sh
> +++ b/buildtools/check-experimental-syms.sh
> @@ -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
> diff --git a/lib/librte_eal/common/include/rte_function_versioning.h b/lib/librte_eal/common/include/rte_function_versioning.h
> index c924351d5..ab102b06e 100644
> --- a/lib/librte_eal/common/include/rte_function_versioning.h
> +++ b/lib/librte_eal/common/include/rte_function_versioning.h
> @@ -46,6 +46,9 @@
>   */
>  #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
>  
> +
> +#define VERSION_SYMBOL_EXPERIMENTAL(b, e) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@EXPERIMENTAL")
> +
I don't know that you want to make a explicit clone of this macro.
instead what you might want to do is something like:

#define __VERSION_SYMBOL(b, e, n, t) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@" RTE_STR(t) "_" RTE_STR(n))

#define VERSION_SYMBOL(b, e, n) __VERSION_SYMBOL(b, e, n, DPDK)

Thats not exactly right, but you get the idea, then you can emulate
VERSION_SYMBOL_EXPERIMENTAL with __VERSION_SYMBOL(b, e, n, EXPERIMENTAL)


>  /*
>   * BIND_DEFAULT_SYMBOL
>   * Creates a symbol version entry instructing the linker to bind references to
> @@ -79,6 +82,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))))
> diff --git a/lib/librte_meter/rte_meter.c b/lib/librte_meter/rte_meter.c
> index da01429a8..5244537fa 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
>  	return 0;
>  }
>  
> -int
> -rte_meter_trtcm_rfc4115_profile_config(
> +static int
> +rte_meter_trtcm_rfc4115_profile_config_(
>  	struct rte_meter_trtcm_rfc4115_profile *p,
>  	struct rte_meter_trtcm_rfc4115_params *params)
>  {
> @@ -145,7 +146,35 @@ 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, 20.0.1);
> +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);
> +
> +static int
> +rte_meter_trtcm_rfc4115_config_(
>  	struct rte_meter_trtcm_rfc4115 *m,
>  	struct rte_meter_trtcm_rfc4115_profile *p)
>  {
> @@ -160,3 +189,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, 20.0.1);
> +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 fc12cc0bf..b4b043174 100644
> --- a/lib/librte_meter/rte_meter_version.map
> +++ b/lib/librte_meter/rte_meter_version.map
> @@ -20,4 +20,12 @@ DPDK_20.0.1 {
>  	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;
> +};
> diff --git a/lib/meson.build b/lib/meson.build
> index 0af3efab2..553964831 100644
> --- a/lib/meson.build
> +++ b/lib/meson.build
> @@ -48,7 +48,7 @@ foreach l:libraries
>  	reason = '<unknown reason>' # set if build == false to explain why
>  	name = l
>  	allow_experimental_apis = false
> -	use_function_versioning = false
> +	use_function_versioning = true
>  	sources = []
>  	headers = []
>  	includes = []
> -- 
> 2.24.1
> 
> 

Re: [dpdk-dev] [RFC v2] meter: fix ABI break due to experimental tag removal

[Eelco Chaudron]

On 30 Jan 2020, at 21:20, Thomas Monjalon wrote:

<SNIP>

>>>>
>>>> Yes, sorry, this is what I meant.
>>>> Given 19.11.0 already has the symbol as experimental,
>>>> and that applications like OVS had to accept it as experimental,
>>>> why removing experimental tag in 19.11.1?
>>>
>>> I think it was mentioned that it was preferred not to suppress the
>>> compiler warning to avoid any accidental use in the future, but the
>>> OVS
>>> maintainer(s) should answer as I might remember wrongly.
>>
>> Yes this is the reason, OVS compiles with -Werror so we would like to
>> avoid the warnings. You can not disable them per include, it’s 
>> global
>> for all of DPDK.
>
> Yes but anyway OVS must accept the experimental function as the next 
> release
> will use it with DPDK 19.11.0.

Yes, we do for now, but we would like to remove it ASAP as it opens up 
the code base for the experimental APIs to slip in…

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Ferruh Yigit]

On 2/2/2020 6:53 PM, Neil Horman wrote:
> On Wed, Jan 29, 2020 at 12:29:53PM +0000, Ferruh Yigit wrote:
>> Duplicated the existing symbol and versioned one as experimental and
>> other as stable.
>>
>> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
>>
>> Updated the 'check-experimental-syms.sh' buildtool, 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)
>>
>> Updated meson build system to allow the versioning,
>> 'use_function_versioning = true', not sure why it was disabled by
>> default.
>>
>> Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")
>>
> I'm not sure I understand the purpose here.
> 
> I think I understand what you are trying to do. I believe that you are
> trying to move the experimental symbols in librte_meter to be part of
> the official ABI, while still maintaining backward compatibility with
> applications built against the experimental symbol versions, correct?

Yes, exactly.

> 
> I can understand the desire, and I'm not exactly opposed to providing a
> mechanism for that, but it seems somewhat complex, and to be honest,
> part of the drawback to using experimental symbols as an application
> developer is understanding that you may need to rebuild when those
> symbols change (even if the change is the symbol removal and replacement
> with an identical one that has a versioned tag).
> 
> I think the right answer for people encountering this condition is to
> just rebuild.  Otherwise, we are creating an environment in which we are
> implicitly communicating to users that we are maintaining a modicum of
> stability in experimental symobls.

This will mean, even the the API was perfect it will force its users to
recompile (and re-package, re-deploy etc..) at least once, this is feeling like
we are still breaking user applications easily.
And this may create a stronger motivation by applications not to use
experimental APIs, I can't decide if this is a good thing or bad thing.


The issue is amplified in the LTS,
If we remove experimental tag in LTS, will be breaking the apps using that
experimental API, just to mature the API.
If we keep it as experimental, the API will be mature in main repo, but the LTS
has to keep exact same API as experimental up to two years.

But if we can do the versioning in the master, LTS can backport it and can have
mature version of that API in LTS without breaking the existing users.

> 
> A few more nits in line
> 
>> 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>
>>
>> I didn't like the idea of duplicating the symbol but not able to find to
>> alias it without duplicating, if there is a way please share.
>>
>> Also not tested with old binaries, only verified the symbols in new
>> binaries.
>> ---
>>  buildtools/check-experimental-syms.sh         |  3 +-
>>  .../common/include/rte_function_versioning.h  |  4 ++
>>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
>>  lib/librte_meter/rte_meter_version.map        |  8 +++
>>  lib/meson.build                               |  2 +-
>>  5 files changed, 71 insertions(+), 5 deletions(-)
>>
>> diff --git a/buildtools/check-experimental-syms.sh b/buildtools/check-experimental-syms.sh
>> index f3603e5ba..35c4bf006 100755
>> --- a/buildtools/check-experimental-syms.sh
>> +++ b/buildtools/check-experimental-syms.sh
>> @@ -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
>> diff --git a/lib/librte_eal/common/include/rte_function_versioning.h b/lib/librte_eal/common/include/rte_function_versioning.h
>> index c924351d5..ab102b06e 100644
>> --- a/lib/librte_eal/common/include/rte_function_versioning.h
>> +++ b/lib/librte_eal/common/include/rte_function_versioning.h
>> @@ -46,6 +46,9 @@
>>   */
>>  #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
>>  
>> +
>> +#define VERSION_SYMBOL_EXPERIMENTAL(b, e) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@EXPERIMENTAL")
>> +
> I don't know that you want to make a explicit clone of this macro.
> instead what you might want to do is something like:
> 
> #define __VERSION_SYMBOL(b, e, n, t) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@" RTE_STR(t) "_" RTE_STR(n))
> 
> #define VERSION_SYMBOL(b, e, n) __VERSION_SYMBOL(b, e, n, DPDK)
> 
> Thats not exactly right, but you get the idea, then you can emulate
> VERSION_SYMBOL_EXPERIMENTAL with __VERSION_SYMBOL(b, e, n, EXPERIMENTAL)

+1

> 
> 
>>  /*
>>   * BIND_DEFAULT_SYMBOL
>>   * Creates a symbol version entry instructing the linker to bind references to
>> @@ -79,6 +82,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))))
>> diff --git a/lib/librte_meter/rte_meter.c b/lib/librte_meter/rte_meter.c
>> index da01429a8..5244537fa 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
>>  	return 0;
>>  }
>>  
>> -int
>> -rte_meter_trtcm_rfc4115_profile_config(
>> +static int
>> +rte_meter_trtcm_rfc4115_profile_config_(
>>  	struct rte_meter_trtcm_rfc4115_profile *p,
>>  	struct rte_meter_trtcm_rfc4115_params *params)
>>  {
>> @@ -145,7 +146,35 @@ 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, 20.0.1);
>> +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);
>> +
>> +static int
>> +rte_meter_trtcm_rfc4115_config_(
>>  	struct rte_meter_trtcm_rfc4115 *m,
>>  	struct rte_meter_trtcm_rfc4115_profile *p)
>>  {
>> @@ -160,3 +189,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, 20.0.1);
>> +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 fc12cc0bf..b4b043174 100644
>> --- a/lib/librte_meter/rte_meter_version.map
>> +++ b/lib/librte_meter/rte_meter_version.map
>> @@ -20,4 +20,12 @@ DPDK_20.0.1 {
>>  	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;
>> +};
>> diff --git a/lib/meson.build b/lib/meson.build
>> index 0af3efab2..553964831 100644
>> --- a/lib/meson.build
>> +++ b/lib/meson.build
>> @@ -48,7 +48,7 @@ foreach l:libraries
>>  	reason = '<unknown reason>' # set if build == false to explain why
>>  	name = l
>>  	allow_experimental_apis = false
>> -	use_function_versioning = false
>> +	use_function_versioning = true
>>  	sources = []
>>  	headers = []
>>  	includes = []
>> -- 
>> 2.24.1
>>
>>

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Neil Horman]

On Mon, Feb 03, 2020 at 12:53:28PM +0000, Ferruh Yigit wrote:
> On 2/2/2020 6:53 PM, Neil Horman wrote:
> > On Wed, Jan 29, 2020 at 12:29:53PM +0000, Ferruh Yigit wrote:
> >> Duplicated the existing symbol and versioned one as experimental and
> >> other as stable.
> >>
> >> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> >>
> >> Updated the 'check-experimental-syms.sh' buildtool, 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)
> >>
> >> Updated meson build system to allow the versioning,
> >> 'use_function_versioning = true', not sure why it was disabled by
> >> default.
> >>
> >> Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")
> >>
> > I'm not sure I understand the purpose here.
> > 
> > I think I understand what you are trying to do. I believe that you are
> > trying to move the experimental symbols in librte_meter to be part of
> > the official ABI, while still maintaining backward compatibility with
> > applications built against the experimental symbol versions, correct?
> 
> Yes, exactly.
> 
Ok, so we're on the same page, good.

> > 
> > I can understand the desire, and I'm not exactly opposed to providing a
> > mechanism for that, but it seems somewhat complex, and to be honest,
> > part of the drawback to using experimental symbols as an application
> > developer is understanding that you may need to rebuild when those
> > symbols change (even if the change is the symbol removal and replacement
> > with an identical one that has a versioned tag).
> > 
> > I think the right answer for people encountering this condition is to
> > just rebuild.  Otherwise, we are creating an environment in which we are
> > implicitly communicating to users that we are maintaining a modicum of
> > stability in experimental symobls.
> 
> This will mean, even the the API was perfect it will force its users to
> recompile (and re-package, re-deploy etc..) at least once, this is feeling like
Yes, thats correct.

> we are still breaking user applications easily.
we reserve that right, based on the fact that we marked these symbols as
experimental.  Thats the deal we provide.  Stable (non experimental) API calls
are guaranteed not to change for the ABI lifetime, and its our responsibility to
maintain that.  However, experimental API's are marked as such because we can
change them (even if that change is to remove it and replace it with an
identical stable version), and application developers assume that risk by using
them.  I understand the removal of an experimental symbol, replacing it with a
stable identical version is a trivial case of that change, and if we can ease
the burden, thats fine, but I don't think we need to go out of our way, or incur
any additional burden to ease that transition.  We created the experimental
symbol marking to ease the burden of this sort of development on us, we should
be willing to use it.

> And this may create a stronger motivation by applications not to use
> experimental APIs, I can't decide if this is a good thing or bad thing.
> 
Yeah, for stable, long term support applications, that makes sense, they
shouldn't be using experimental API's when they need the guarantee of support,
or they should be understanding of their responsibility to rebuild, when we
change the API's in both complex and trivial cases like this.

> 
> The issue is amplified in the LTS,
> If we remove experimental tag in LTS, will be breaking the apps using that
> experimental API, just to mature the API.
You shouldn't be making this sort of transition in LTS.  Just leave the
experimental symbol as is there, and commit the transition for the next LTS
release.

> If we keep it as experimental, the API will be mature in main repo, but the LTS
> has to keep exact same API as experimental up to two years.
Yes, thats the meaning of LTS.  Things stay stable for its lifetime.  And if the
only thing you are doing is replacing the experimental ABI version with a stable
version (leaving the details of the ABI unchanged), then its a moot point.  The
only difference will be that the LTS release will have symbols marked as
experimental.

> 
> But if we can do the versioning in the master, LTS can backport it and can have
> mature version of that API in LTS without breaking the existing users.
> 
But why bother?  The only thing you've changed is the version tagging.  Its ok
to leave that alone in LTS, you just cant change it.

Thats part of the burden of an LTS release, it will have some drift from the
upstream head, because you have to keep things stable.  So you stabilize the
upstream ABI version for this API and just never backport it to the current LTS
release.

> > 
> > A few more nits in line
> > 
> >> 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>
> >>
> >> I didn't like the idea of duplicating the symbol but not able to find to
> >> alias it without duplicating, if there is a way please share.
> >>
> >> Also not tested with old binaries, only verified the symbols in new
> >> binaries.
> >> ---
> >>  buildtools/check-experimental-syms.sh         |  3 +-
> >>  .../common/include/rte_function_versioning.h  |  4 ++
> >>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
> >>  lib/librte_meter/rte_meter_version.map        |  8 +++
> >>  lib/meson.build                               |  2 +-
> >>  5 files changed, 71 insertions(+), 5 deletions(-)
> >>
> >> diff --git a/buildtools/check-experimental-syms.sh b/buildtools/check-experimental-syms.sh
> >> index f3603e5ba..35c4bf006 100755
> >> --- a/buildtools/check-experimental-syms.sh
> >> +++ b/buildtools/check-experimental-syms.sh
> >> @@ -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
> >> diff --git a/lib/librte_eal/common/include/rte_function_versioning.h b/lib/librte_eal/common/include/rte_function_versioning.h
> >> index c924351d5..ab102b06e 100644
> >> --- a/lib/librte_eal/common/include/rte_function_versioning.h
> >> +++ b/lib/librte_eal/common/include/rte_function_versioning.h
> >> @@ -46,6 +46,9 @@
> >>   */
> >>  #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
> >>  
> >> +
> >> +#define VERSION_SYMBOL_EXPERIMENTAL(b, e) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@EXPERIMENTAL")
> >> +
> > I don't know that you want to make a explicit clone of this macro.
> > instead what you might want to do is something like:
> > 
> > #define __VERSION_SYMBOL(b, e, n, t) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@" RTE_STR(t) "_" RTE_STR(n))
> > 
> > #define VERSION_SYMBOL(b, e, n) __VERSION_SYMBOL(b, e, n, DPDK)
> > 
> > Thats not exactly right, but you get the idea, then you can emulate
> > VERSION_SYMBOL_EXPERIMENTAL with __VERSION_SYMBOL(b, e, n, EXPERIMENTAL)
> 
> +1
> 
> > 
> > 
> >>  /*
> >>   * BIND_DEFAULT_SYMBOL
> >>   * Creates a symbol version entry instructing the linker to bind references to
> >> @@ -79,6 +82,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))))
> >> diff --git a/lib/librte_meter/rte_meter.c b/lib/librte_meter/rte_meter.c
> >> index da01429a8..5244537fa 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
> >>  	return 0;
> >>  }
> >>  
> >> -int
> >> -rte_meter_trtcm_rfc4115_profile_config(
> >> +static int
> >> +rte_meter_trtcm_rfc4115_profile_config_(
> >>  	struct rte_meter_trtcm_rfc4115_profile *p,
> >>  	struct rte_meter_trtcm_rfc4115_params *params)
> >>  {
> >> @@ -145,7 +146,35 @@ 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, 20.0.1);
> >> +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);
> >> +
> >> +static int
> >> +rte_meter_trtcm_rfc4115_config_(
> >>  	struct rte_meter_trtcm_rfc4115 *m,
> >>  	struct rte_meter_trtcm_rfc4115_profile *p)
> >>  {
> >> @@ -160,3 +189,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, 20.0.1);
> >> +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 fc12cc0bf..b4b043174 100644
> >> --- a/lib/librte_meter/rte_meter_version.map
> >> +++ b/lib/librte_meter/rte_meter_version.map
> >> @@ -20,4 +20,12 @@ DPDK_20.0.1 {
> >>  	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;
> >> +};
> >> diff --git a/lib/meson.build b/lib/meson.build
> >> index 0af3efab2..553964831 100644
> >> --- a/lib/meson.build
> >> +++ b/lib/meson.build
> >> @@ -48,7 +48,7 @@ foreach l:libraries
> >>  	reason = '<unknown reason>' # set if build == false to explain why
> >>  	name = l
> >>  	allow_experimental_apis = false
> >> -	use_function_versioning = false
> >> +	use_function_versioning = true
> >>  	sources = []
> >>  	headers = []
> >>  	includes = []
> >> -- 
> >> 2.24.1
> >>
> >>
> 
> 

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Luca Boccassi]

On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
> > But if we can do the versioning in the master, LTS can backport it
> > and can have
> > mature version of that API in LTS without breaking the existing
> > users.
> > 
> 
> But why bother?  The only thing you've changed is the version
> tagging.  Its ok
> to leave that alone in LTS, you just cant change it.
> 
> Thats part of the burden of an LTS release, it will have some drift
> from the
> upstream head, because you have to keep things stable.  So you
> stabilize the
> upstream ABI version for this API and just never backport it to the
> current LTS
> release.

Hi,

A customer (OVS) explicitly and specifically requested backporting the
symbol change to 19.11, as they don't want to enable experimental APIs
in their releases. I replied that it would only be acceptable with
aliasing to keep compatibility, and Ferruh very kindly did the work to
implement that.

-- 
Kind regards,
Luca Boccassi

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Neil Horman]

On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
> > > But if we can do the versioning in the master, LTS can backport it
> > > and can have
> > > mature version of that API in LTS without breaking the existing
> > > users.
> > > 
> > 
> > But why bother?  The only thing you've changed is the version
> > tagging.  Its ok
> > to leave that alone in LTS, you just cant change it.
> > 
> > Thats part of the burden of an LTS release, it will have some drift
> > from the
> > upstream head, because you have to keep things stable.  So you
> > stabilize the
> > upstream ABI version for this API and just never backport it to the
> > current LTS
> > release.
> 
> Hi,
> 
> A customer (OVS) explicitly and specifically requested backporting the
> symbol change to 19.11, as they don't want to enable experimental APIs
> in their releases. I replied that it would only be acceptable with
> aliasing to keep compatibility, and Ferruh very kindly did the work to
> implement that.
> 
but, thats part of the agreement, no?  You can't always have new features and
stability at the same time.

I get that this is an odd corner case, because strictly speaking you could waive
the ABI change that libabigail is reporting, and most application users (like
OVS) could get away with it, because their application does all the right things
to make it ok, but I don't think you can make a decsion like this for all users
based on the request of a single user.

It seems like the right thing is for OVS to augment their build time
configuration to allow developers to select the ability to use experimental apis
at compile time, and then the decision is placed in the hands of end users.

Neil
> -- 
> Kind regards,
> Luca Boccassi
> 

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Ray Kinsella]

On 05/02/2020 11:32, Neil Horman wrote:
> On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
>> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
>>>> But if we can do the versioning in the master, LTS can backport it
>>>> and can have
>>>> mature version of that API in LTS without breaking the existing
>>>> users.
>>>>
>>>
>>> But why bother?  The only thing you've changed is the version
>>> tagging.  Its ok
>>> to leave that alone in LTS, you just cant change it.
>>>
>>> Thats part of the burden of an LTS release, it will have some drift
>>> from the
>>> upstream head, because you have to keep things stable.  So you
>>> stabilize the
>>> upstream ABI version for this API and just never backport it to the
>>> current LTS
>>> release.
>>
>> Hi,
>>
>> A customer (OVS) explicitly and specifically requested backporting the
>> symbol change to 19.11, as they don't want to enable experimental APIs
>> in their releases. I replied that it would only be acceptable with
>> aliasing to keep compatibility, and Ferruh very kindly did the work to
>> implement that.
>>
> but, thats part of the agreement, no?  You can't always have new features and
> stability at the same time.
> 
> I get that this is an odd corner case, because strictly speaking you could waive
> the ABI change that libabigail is reporting, and most application users (like
> OVS) could get away with it, because their application does all the right things
> to make it ok, but I don't think you can make a decsion like this for all users
> based on the request of a single user.
> 
> It seems like the right thing is for OVS to augment their build time
> configuration to allow developers to select the ability to use experimental apis
> at compile time, and then the decision is placed in the hands of end users.

So this is not isolated case right ... it is common from API's to graduate 
from experimental to mature, we _want_ that to happen, we _want_ APIs to mature. 

I am worried what you are proposing will encourage a behavior whereby maintainers 
to wait until the declaration of the next major ABI version to make these symbol changes,
causing these kinds of changes to queue up for that release. 

And you would have to ask why?
In the case of a reasonably mature API, there will be no functional or signature change - its mature!
So what is the harm of providing an alias back to Experimental until the next ABI version is declared?

So while yes, you are 100% right - experimental mean no guarantees. 
But if the API is baked, it is not going to change, so I don't see the harm.

We don't want the unnecessary triumph of policy over pragmatism. 

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Neil Horman]

On Thu, Feb 13, 2020 at 05:40:43PM +0000, Ray Kinsella wrote:
> 
> 
> On 05/02/2020 11:32, Neil Horman wrote:
> > On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
> >> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
> >>>> But if we can do the versioning in the master, LTS can backport it
> >>>> and can have
> >>>> mature version of that API in LTS without breaking the existing
> >>>> users.
> >>>>
> >>>
> >>> But why bother?  The only thing you've changed is the version
> >>> tagging.  Its ok
> >>> to leave that alone in LTS, you just cant change it.
> >>>
> >>> Thats part of the burden of an LTS release, it will have some drift
> >>> from the
> >>> upstream head, because you have to keep things stable.  So you
> >>> stabilize the
> >>> upstream ABI version for this API and just never backport it to the
> >>> current LTS
> >>> release.
> >>
> >> Hi,
> >>
> >> A customer (OVS) explicitly and specifically requested backporting the
> >> symbol change to 19.11, as they don't want to enable experimental APIs
> >> in their releases. I replied that it would only be acceptable with
> >> aliasing to keep compatibility, and Ferruh very kindly did the work to
> >> implement that.
> >>
> > but, thats part of the agreement, no?  You can't always have new features and
> > stability at the same time.
> > 
> > I get that this is an odd corner case, because strictly speaking you could waive
> > the ABI change that libabigail is reporting, and most application users (like
> > OVS) could get away with it, because their application does all the right things
> > to make it ok, but I don't think you can make a decsion like this for all users
> > based on the request of a single user.
> > 
> > It seems like the right thing is for OVS to augment their build time
> > configuration to allow developers to select the ability to use experimental apis
> > at compile time, and then the decision is placed in the hands of end users.
> 
> So this is not isolated case right ... it is common from API's to graduate 
> from experimental to mature, we _want_ that to happen, we _want_ APIs to mature. 
> 
Sure, I can absolutely agree with that, though I would suggest that
the maturity of the ABI is orthogonal to its labeling as such (more on
that below)

> I am worried what you are proposing will encourage a behavior whereby maintainers 
> to wait until the declaration of the next major ABI version to make these symbol changes,
> causing these kinds of changes to queue up for that release. 
> 
I think you're probably right about that, and would make the agrument
that thats perfectly fine (again I'll clarify below)

> And you would have to ask why?
> In the case of a reasonably mature API, there will be no functional or signature change - its mature!
> So what is the harm of providing an alias back to Experimental until the next ABI version is declared?
> 
From a philosophical standpoint, there is absoluely no harm, and I don't
think anyone would disagree, the harm comes from the details of the
implementation, as you've noted.

> So while yes, you are 100% right - experimental mean no guarantees. 
> But if the API is baked, it is not going to change, so I don't see the harm.
> 
> We don't want the unnecessary triumph of policy over pragmatism. 
> 
I would make the converse argument here.  While I agree that when an API
is mature, theres no point in calling it experimental anymore, I would
also suggest that, if an API is mature, and not expected to change,
theres no harm in leaving its version tag as experimental for an LTS
release.  This is what I was referring to above.  Once an application
developer has done the work to integrate an API from DPDK into its
application, that work is done.  If the API remains stable, then I
honestly don't know that they care that the version label is
EXPERIMENTAL versus 20.11 or 20.05 or whatever.  They care about the API
being stable more so than its version label.  As such, it
seems....reasonable to me to have developers queue their migration of
experimental APIs to official versioned APIs at the next major release
deliniation point.

I'd welcome counter arguments, but it seems pretty natural to me to make
these sorts of changes at the major release mark.  People using
experimantal apis have already implicity agreed to manage changes to
them, so if we just hold it stable in an LTS release (and don't update
the version label), its just gravy for them.

Regards
Neil

> 
> 
> 
> 
> 
> 

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Bruce Richardson]

On Thu, Feb 13, 2020 at 09:40:40PM -0500, Neil Horman wrote:
> On Thu, Feb 13, 2020 at 05:40:43PM +0000, Ray Kinsella wrote:
> > 
> > 
> > On 05/02/2020 11:32, Neil Horman wrote:
> > > On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
> > >> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
> > >>>> But if we can do the versioning in the master, LTS can backport it
> > >>>> and can have mature version of that API in LTS without breaking
> > >>>> the existing users.
> > >>>>
> > >>>
> > >>> But why bother?  The only thing you've changed is the version
> > >>> tagging.  Its ok to leave that alone in LTS, you just cant change
> > >>> it.
> > >>>
> > >>> Thats part of the burden of an LTS release, it will have some drift
> > >>> from the upstream head, because you have to keep things stable.  So
> > >>> you stabilize the upstream ABI version for this API and just never
> > >>> backport it to the current LTS release.
> > >>
> > >> Hi,
> > >>
> > >> A customer (OVS) explicitly and specifically requested backporting
> > >> the symbol change to 19.11, as they don't want to enable
> > >> experimental APIs in their releases. I replied that it would only be
> > >> acceptable with aliasing to keep compatibility, and Ferruh very
> > >> kindly did the work to implement that.
> > >>
> > > but, thats part of the agreement, no?  You can't always have new
> > > features and stability at the same time.
> > > 
> > > I get that this is an odd corner case, because strictly speaking you
> > > could waive the ABI change that libabigail is reporting, and most
> > > application users (like OVS) could get away with it, because their
> > > application does all the right things to make it ok, but I don't
> > > think you can make a decsion like this for all users based on the
> > > request of a single user.
> > > 
> > > It seems like the right thing is for OVS to augment their build time
> > > configuration to allow developers to select the ability to use
> > > experimental apis at compile time, and then the decision is placed in
> > > the hands of end users.
> > 
> > So this is not isolated case right ... it is common from API's to
> > graduate from experimental to mature, we _want_ that to happen, we
> > _want_ APIs to mature. 
> > 
> Sure, I can absolutely agree with that, though I would suggest that the
> maturity of the ABI is orthogonal to its labeling as such (more on that
> below)
> 
> > I am worried what you are proposing will encourage a behavior whereby
> > maintainers to wait until the declaration of the next major ABI version
> > to make these symbol changes, causing these kinds of changes to queue
> > up for that release. 
> > 
> I think you're probably right about that, and would make the agrument
> that thats perfectly fine (again I'll clarify below)
> 
> > And you would have to ask why?  In the case of a reasonably mature API,
> > there will be no functional or signature change - its mature!  So what
> > is the harm of providing an alias back to Experimental until the next
> > ABI version is declared?
> > 
> From a philosophical standpoint, there is absoluely no harm, and I don't
> think anyone would disagree, the harm comes from the details of the
> implementation, as you've noted.
> 
> > So while yes, you are 100% right - experimental mean no guarantees.
> > But if the API is baked, it is not going to change, so I don't see the
> > harm.
> > 
> > We don't want the unnecessary triumph of policy over pragmatism. 
> > 
> I would make the converse argument here.  While I agree that when an API
> is mature, theres no point in calling it experimental anymore, I would
> also suggest that, if an API is mature, and not expected to change,
> theres no harm in leaving its version tag as experimental for an LTS
> release.  This is what I was referring to above.  Once an application
> developer has done the work to integrate an API from DPDK into its
> application, that work is done.  If the API remains stable, then I
> honestly don't know that they care that the version label is EXPERIMENTAL
> versus 20.11 or 20.05 or whatever.  They care about the API being stable
> more so than its version label.  As such, it seems....reasonable to me to
> have developers queue their migration of experimental APIs to official
> versioned APIs at the next major release deliniation point.
> 
> I'd welcome counter arguments, but it seems pretty natural to me to make
> these sorts of changes at the major release mark.  People using
> experimantal apis have already implicity agreed to manage changes to
> them, so if we just hold it stable in an LTS release (and don't update
> the version label), its just gravy for them.
> 
The counter argument that I see is that while the experimental tag remains
in place the user has no way to know that an API is stable or not, and so
in many projects cannot use the API. If for example an API that is
experimental in 19.11 is unchanged through 20.05 at which point we decide
to promote it to stable. Once the change to the exp tag it is made, any
users of 19.11 can then see that it is an unchanged and now-stable ABI and
can start using it in their software, if they wish, without having to wait
for the 20.11 release. Changing the tag early allows ABIs to be potentially
used immediately.

Regards,
/Bruce

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Neil Horman]

On Fri, Feb 14, 2020 at 11:36:34AM +0000, Bruce Richardson wrote:
> On Thu, Feb 13, 2020 at 09:40:40PM -0500, Neil Horman wrote:
> > On Thu, Feb 13, 2020 at 05:40:43PM +0000, Ray Kinsella wrote:
> > > 
> > > 
> > > On 05/02/2020 11:32, Neil Horman wrote:
> > > > On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
> > > >> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
> > > >>>> But if we can do the versioning in the master, LTS can backport it
> > > >>>> and can have mature version of that API in LTS without breaking
> > > >>>> the existing users.
> > > >>>>
> > > >>>
> > > >>> But why bother?  The only thing you've changed is the version
> > > >>> tagging.  Its ok to leave that alone in LTS, you just cant change
> > > >>> it.
> > > >>>
> > > >>> Thats part of the burden of an LTS release, it will have some drift
> > > >>> from the upstream head, because you have to keep things stable.  So
> > > >>> you stabilize the upstream ABI version for this API and just never
> > > >>> backport it to the current LTS release.
> > > >>
> > > >> Hi,
> > > >>
> > > >> A customer (OVS) explicitly and specifically requested backporting
> > > >> the symbol change to 19.11, as they don't want to enable
> > > >> experimental APIs in their releases. I replied that it would only be
> > > >> acceptable with aliasing to keep compatibility, and Ferruh very
> > > >> kindly did the work to implement that.
> > > >>
> > > > but, thats part of the agreement, no?  You can't always have new
> > > > features and stability at the same time.
> > > > 
> > > > I get that this is an odd corner case, because strictly speaking you
> > > > could waive the ABI change that libabigail is reporting, and most
> > > > application users (like OVS) could get away with it, because their
> > > > application does all the right things to make it ok, but I don't
> > > > think you can make a decsion like this for all users based on the
> > > > request of a single user.
> > > > 
> > > > It seems like the right thing is for OVS to augment their build time
> > > > configuration to allow developers to select the ability to use
> > > > experimental apis at compile time, and then the decision is placed in
> > > > the hands of end users.
> > > 
> > > So this is not isolated case right ... it is common from API's to
> > > graduate from experimental to mature, we _want_ that to happen, we
> > > _want_ APIs to mature. 
> > > 
> > Sure, I can absolutely agree with that, though I would suggest that the
> > maturity of the ABI is orthogonal to its labeling as such (more on that
> > below)
> > 
> > > I am worried what you are proposing will encourage a behavior whereby
> > > maintainers to wait until the declaration of the next major ABI version
> > > to make these symbol changes, causing these kinds of changes to queue
> > > up for that release. 
> > > 
> > I think you're probably right about that, and would make the agrument
> > that thats perfectly fine (again I'll clarify below)
> > 
> > > And you would have to ask why?  In the case of a reasonably mature API,
> > > there will be no functional or signature change - its mature!  So what
> > > is the harm of providing an alias back to Experimental until the next
> > > ABI version is declared?
> > > 
> > From a philosophical standpoint, there is absoluely no harm, and I don't
> > think anyone would disagree, the harm comes from the details of the
> > implementation, as you've noted.
> > 
> > > So while yes, you are 100% right - experimental mean no guarantees.
> > > But if the API is baked, it is not going to change, so I don't see the
> > > harm.
> > > 
> > > We don't want the unnecessary triumph of policy over pragmatism. 
> > > 
> > I would make the converse argument here.  While I agree that when an API
> > is mature, theres no point in calling it experimental anymore, I would
> > also suggest that, if an API is mature, and not expected to change,
> > theres no harm in leaving its version tag as experimental for an LTS
> > release.  This is what I was referring to above.  Once an application
> > developer has done the work to integrate an API from DPDK into its
> > application, that work is done.  If the API remains stable, then I
> > honestly don't know that they care that the version label is EXPERIMENTAL
> > versus 20.11 or 20.05 or whatever.  They care about the API being stable
> > more so than its version label.  As such, it seems....reasonable to me to
> > have developers queue their migration of experimental APIs to official
> > versioned APIs at the next major release deliniation point.
> > 
> > I'd welcome counter arguments, but it seems pretty natural to me to make
> > these sorts of changes at the major release mark.  People using
> > experimantal apis have already implicity agreed to manage changes to
> > them, so if we just hold it stable in an LTS release (and don't update
> > the version label), its just gravy for them.
> > 
> The counter argument that I see is that while the experimental tag remains
> in place the user has no way to know that an API is stable or not, and so
> in many projects cannot use the API. If for example an API that is
> experimental in 19.11 is unchanged through 20.05 at which point we decide
> to promote it to stable. Once the change to the exp tag it is made, any
> users of 19.11 can then see that it is an unchanged and now-stable ABI and
> can start using it in their software, if they wish, without having to wait
> for the 20.11 release. Changing the tag early allows ABIs to be potentially
> used immediately.
> 

I would agree with this, however, when using an LTS release, in my mind at
least, part of the agreement there is you get stability in the fuctions that
were declared stable at the time of release.  I'm not sure there should be an
expectation of additional stabilization within the lifetime of the release
(thats really what the 12 month LTS release cycle is for, no)?  You never have
to wait more than a year for a new set of stable features.  If you want faster
feature integration than that, you can choose to enable the experimental API's
and accept the benefits and drawbacks thereof.

That said, if (as I understand it) the goal is to provide a mechanism to allow
experimental features to be promoted to stable status, perhaps we can find a
happy middle ground.  What if we were to create a construct such as this:

#pragma push_macro("ALLOW_EXPERIMENTAL_APIS")
#undef ALLOW_EXPERIMENTAL_APIS
void __rte_experimental func(...);
#pragma pop_macro("ALLOW_EXPERIMENTAL_APIS")

Such a consruct would allow the maintainer of an API to pseudo-promote an API
from a experimental to stable status, at least so far as compilation would be
concerned.  Its messy and clunky, and it wouldn't change the function version at
all, but the end result would be that:
a) such a wraped experimental function would no longer issue a warning when used
during compilation/linking
and
b) provide a semi-easy grepable pattern for application writers to look for when
considering the use of an API that was previously experimental

such a construct would have to be used very judiciously, in that once its
implemented, the API has to be treated as stable, even though its 'excused' from
the normal checking, but it could provide something of the more rapid promotion
path being sought.

Thoughts?
Neil
> Regards,
> /Bruce
> 

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Bruce Richardson]

On Fri, Feb 14, 2020 at 03:48:48PM -0500, Neil Horman wrote:
> On Fri, Feb 14, 2020 at 11:36:34AM +0000, Bruce Richardson wrote:
> > On Thu, Feb 13, 2020 at 09:40:40PM -0500, Neil Horman wrote:
> > > On Thu, Feb 13, 2020 at 05:40:43PM +0000, Ray Kinsella wrote:
> > > > 
> > > > 
> > > > On 05/02/2020 11:32, Neil Horman wrote:
> > > > > On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
> > > > >> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
> > > > >>>> But if we can do the versioning in the master, LTS can backport it
> > > > >>>> and can have mature version of that API in LTS without breaking
> > > > >>>> the existing users.
> > > > >>>>
> > > > >>>
> > > > >>> But why bother?  The only thing you've changed is the version
> > > > >>> tagging.  Its ok to leave that alone in LTS, you just cant change
> > > > >>> it.
> > > > >>>
> > > > >>> Thats part of the burden of an LTS release, it will have some drift
> > > > >>> from the upstream head, because you have to keep things stable.  So
> > > > >>> you stabilize the upstream ABI version for this API and just never
> > > > >>> backport it to the current LTS release.
> > > > >>
> > > > >> Hi,
> > > > >>
> > > > >> A customer (OVS) explicitly and specifically requested backporting
> > > > >> the symbol change to 19.11, as they don't want to enable
> > > > >> experimental APIs in their releases. I replied that it would only be
> > > > >> acceptable with aliasing to keep compatibility, and Ferruh very
> > > > >> kindly did the work to implement that.
> > > > >>
> > > > > but, thats part of the agreement, no?  You can't always have new
> > > > > features and stability at the same time.
> > > > > 
> > > > > I get that this is an odd corner case, because strictly speaking you
> > > > > could waive the ABI change that libabigail is reporting, and most
> > > > > application users (like OVS) could get away with it, because their
> > > > > application does all the right things to make it ok, but I don't
> > > > > think you can make a decsion like this for all users based on the
> > > > > request of a single user.
> > > > > 
> > > > > It seems like the right thing is for OVS to augment their build time
> > > > > configuration to allow developers to select the ability to use
> > > > > experimental apis at compile time, and then the decision is placed in
> > > > > the hands of end users.
> > > > 
> > > > So this is not isolated case right ... it is common from API's to
> > > > graduate from experimental to mature, we _want_ that to happen, we
> > > > _want_ APIs to mature. 
> > > > 
> > > Sure, I can absolutely agree with that, though I would suggest that the
> > > maturity of the ABI is orthogonal to its labeling as such (more on that
> > > below)
> > > 
> > > > I am worried what you are proposing will encourage a behavior whereby
> > > > maintainers to wait until the declaration of the next major ABI version
> > > > to make these symbol changes, causing these kinds of changes to queue
> > > > up for that release. 
> > > > 
> > > I think you're probably right about that, and would make the agrument
> > > that thats perfectly fine (again I'll clarify below)
> > > 
> > > > And you would have to ask why?  In the case of a reasonably mature API,
> > > > there will be no functional or signature change - its mature!  So what
> > > > is the harm of providing an alias back to Experimental until the next
> > > > ABI version is declared?
> > > > 
> > > From a philosophical standpoint, there is absoluely no harm, and I don't
> > > think anyone would disagree, the harm comes from the details of the
> > > implementation, as you've noted.
> > > 
> > > > So while yes, you are 100% right - experimental mean no guarantees.
> > > > But if the API is baked, it is not going to change, so I don't see the
> > > > harm.
> > > > 
> > > > We don't want the unnecessary triumph of policy over pragmatism. 
> > > > 
> > > I would make the converse argument here.  While I agree that when an API
> > > is mature, theres no point in calling it experimental anymore, I would
> > > also suggest that, if an API is mature, and not expected to change,
> > > theres no harm in leaving its version tag as experimental for an LTS
> > > release.  This is what I was referring to above.  Once an application
> > > developer has done the work to integrate an API from DPDK into its
> > > application, that work is done.  If the API remains stable, then I
> > > honestly don't know that they care that the version label is EXPERIMENTAL
> > > versus 20.11 or 20.05 or whatever.  They care about the API being stable
> > > more so than its version label.  As such, it seems....reasonable to me to
> > > have developers queue their migration of experimental APIs to official
> > > versioned APIs at the next major release deliniation point.
> > > 
> > > I'd welcome counter arguments, but it seems pretty natural to me to make
> > > these sorts of changes at the major release mark.  People using
> > > experimantal apis have already implicity agreed to manage changes to
> > > them, so if we just hold it stable in an LTS release (and don't update
> > > the version label), its just gravy for them.
> > > 
> > The counter argument that I see is that while the experimental tag remains
> > in place the user has no way to know that an API is stable or not, and so
> > in many projects cannot use the API. If for example an API that is
> > experimental in 19.11 is unchanged through 20.05 at which point we decide
> > to promote it to stable. Once the change to the exp tag it is made, any
> > users of 19.11 can then see that it is an unchanged and now-stable ABI and
> > can start using it in their software, if they wish, without having to wait
> > for the 20.11 release. Changing the tag early allows ABIs to be potentially
> > used immediately.
> > 
> 
> I would agree with this, however, when using an LTS release, in my mind at
> least, part of the agreement there is you get stability in the fuctions that
> were declared stable at the time of release.  I'm not sure there should be an
> expectation of additional stabilization within the lifetime of the release
> (thats really what the 12 month LTS release cycle is for, no)?  You never have
> to wait more than a year for a new set of stable features.  If you want faster
> feature integration than that, you can choose to enable the experimental API's
> and accept the benefits and drawbacks thereof.
> 
> That said, if (as I understand it) the goal is to provide a mechanism to allow
> experimental features to be promoted to stable status, perhaps we can find a
> happy middle ground.  What if we were to create a construct such as this:
> 
> #pragma push_macro("ALLOW_EXPERIMENTAL_APIS")
> #undef ALLOW_EXPERIMENTAL_APIS
> void __rte_experimental func(...);
> #pragma pop_macro("ALLOW_EXPERIMENTAL_APIS")
> 
> Such a consruct would allow the maintainer of an API to pseudo-promote an API
> from a experimental to stable status, at least so far as compilation would be
> concerned.  Its messy and clunky, and it wouldn't change the function version at
> all, but the end result would be that:
> a) such a wraped experimental function would no longer issue a warning when used
> during compilation/linking
> and
> b) provide a semi-easy grepable pattern for application writers to look for when
> considering the use of an API that was previously experimental
> 
> such a construct would have to be used very judiciously, in that once its
> implemented, the API has to be treated as stable, even though its 'excused' from
> the normal checking, but it could provide something of the more rapid promotion
> path being sought.
> 
Sure it could work and does meet the end goal. I'm not really sure it's a
better solution than just promoting the function and putting in an alias
for it back to experimental, though.

/Bruce

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Neil Horman]

On Fri, Feb 14, 2020 at 09:52:53PM +0000, Bruce Richardson wrote:
> On Fri, Feb 14, 2020 at 03:48:48PM -0500, Neil Horman wrote:
> > On Fri, Feb 14, 2020 at 11:36:34AM +0000, Bruce Richardson wrote:
> > > On Thu, Feb 13, 2020 at 09:40:40PM -0500, Neil Horman wrote:
> > > > On Thu, Feb 13, 2020 at 05:40:43PM +0000, Ray Kinsella wrote:
> > > > > 
> > > > > 
> > > > > On 05/02/2020 11:32, Neil Horman wrote:
> > > > > > On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
> > > > > >> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
> > > > > >>>> But if we can do the versioning in the master, LTS can backport it
> > > > > >>>> and can have mature version of that API in LTS without breaking
> > > > > >>>> the existing users.
> > > > > >>>>
> > > > > >>>
> > > > > >>> But why bother?  The only thing you've changed is the version
> > > > > >>> tagging.  Its ok to leave that alone in LTS, you just cant change
> > > > > >>> it.
> > > > > >>>
> > > > > >>> Thats part of the burden of an LTS release, it will have some drift
> > > > > >>> from the upstream head, because you have to keep things stable.  So
> > > > > >>> you stabilize the upstream ABI version for this API and just never
> > > > > >>> backport it to the current LTS release.
> > > > > >>
> > > > > >> Hi,
> > > > > >>
> > > > > >> A customer (OVS) explicitly and specifically requested backporting
> > > > > >> the symbol change to 19.11, as they don't want to enable
> > > > > >> experimental APIs in their releases. I replied that it would only be
> > > > > >> acceptable with aliasing to keep compatibility, and Ferruh very
> > > > > >> kindly did the work to implement that.
> > > > > >>
> > > > > > but, thats part of the agreement, no?  You can't always have new
> > > > > > features and stability at the same time.
> > > > > > 
> > > > > > I get that this is an odd corner case, because strictly speaking you
> > > > > > could waive the ABI change that libabigail is reporting, and most
> > > > > > application users (like OVS) could get away with it, because their
> > > > > > application does all the right things to make it ok, but I don't
> > > > > > think you can make a decsion like this for all users based on the
> > > > > > request of a single user.
> > > > > > 
> > > > > > It seems like the right thing is for OVS to augment their build time
> > > > > > configuration to allow developers to select the ability to use
> > > > > > experimental apis at compile time, and then the decision is placed in
> > > > > > the hands of end users.
> > > > > 
> > > > > So this is not isolated case right ... it is common from API's to
> > > > > graduate from experimental to mature, we _want_ that to happen, we
> > > > > _want_ APIs to mature. 
> > > > > 
> > > > Sure, I can absolutely agree with that, though I would suggest that the
> > > > maturity of the ABI is orthogonal to its labeling as such (more on that
> > > > below)
> > > > 
> > > > > I am worried what you are proposing will encourage a behavior whereby
> > > > > maintainers to wait until the declaration of the next major ABI version
> > > > > to make these symbol changes, causing these kinds of changes to queue
> > > > > up for that release. 
> > > > > 
> > > > I think you're probably right about that, and would make the agrument
> > > > that thats perfectly fine (again I'll clarify below)
> > > > 
> > > > > And you would have to ask why?  In the case of a reasonably mature API,
> > > > > there will be no functional or signature change - its mature!  So what
> > > > > is the harm of providing an alias back to Experimental until the next
> > > > > ABI version is declared?
> > > > > 
> > > > From a philosophical standpoint, there is absoluely no harm, and I don't
> > > > think anyone would disagree, the harm comes from the details of the
> > > > implementation, as you've noted.
> > > > 
> > > > > So while yes, you are 100% right - experimental mean no guarantees.
> > > > > But if the API is baked, it is not going to change, so I don't see the
> > > > > harm.
> > > > > 
> > > > > We don't want the unnecessary triumph of policy over pragmatism. 
> > > > > 
> > > > I would make the converse argument here.  While I agree that when an API
> > > > is mature, theres no point in calling it experimental anymore, I would
> > > > also suggest that, if an API is mature, and not expected to change,
> > > > theres no harm in leaving its version tag as experimental for an LTS
> > > > release.  This is what I was referring to above.  Once an application
> > > > developer has done the work to integrate an API from DPDK into its
> > > > application, that work is done.  If the API remains stable, then I
> > > > honestly don't know that they care that the version label is EXPERIMENTAL
> > > > versus 20.11 or 20.05 or whatever.  They care about the API being stable
> > > > more so than its version label.  As such, it seems....reasonable to me to
> > > > have developers queue their migration of experimental APIs to official
> > > > versioned APIs at the next major release deliniation point.
> > > > 
> > > > I'd welcome counter arguments, but it seems pretty natural to me to make
> > > > these sorts of changes at the major release mark.  People using
> > > > experimantal apis have already implicity agreed to manage changes to
> > > > them, so if we just hold it stable in an LTS release (and don't update
> > > > the version label), its just gravy for them.
> > > > 
> > > The counter argument that I see is that while the experimental tag remains
> > > in place the user has no way to know that an API is stable or not, and so
> > > in many projects cannot use the API. If for example an API that is
> > > experimental in 19.11 is unchanged through 20.05 at which point we decide
> > > to promote it to stable. Once the change to the exp tag it is made, any
> > > users of 19.11 can then see that it is an unchanged and now-stable ABI and
> > > can start using it in their software, if they wish, without having to wait
> > > for the 20.11 release. Changing the tag early allows ABIs to be potentially
> > > used immediately.
> > > 
> > 
> > I would agree with this, however, when using an LTS release, in my mind at
> > least, part of the agreement there is you get stability in the fuctions that
> > were declared stable at the time of release.  I'm not sure there should be an
> > expectation of additional stabilization within the lifetime of the release
> > (thats really what the 12 month LTS release cycle is for, no)?  You never have
> > to wait more than a year for a new set of stable features.  If you want faster
> > feature integration than that, you can choose to enable the experimental API's
> > and accept the benefits and drawbacks thereof.
> > 
> > That said, if (as I understand it) the goal is to provide a mechanism to allow
> > experimental features to be promoted to stable status, perhaps we can find a
> > happy middle ground.  What if we were to create a construct such as this:
> > 
> > #pragma push_macro("ALLOW_EXPERIMENTAL_APIS")
> > #undef ALLOW_EXPERIMENTAL_APIS
> > void __rte_experimental func(...);
> > #pragma pop_macro("ALLOW_EXPERIMENTAL_APIS")
> > 
> > Such a consruct would allow the maintainer of an API to pseudo-promote an API
> > from a experimental to stable status, at least so far as compilation would be
> > concerned.  Its messy and clunky, and it wouldn't change the function version at
> > all, but the end result would be that:
> > a) such a wraped experimental function would no longer issue a warning when used
> > during compilation/linking
> > and
> > b) provide a semi-easy grepable pattern for application writers to look for when
> > considering the use of an API that was previously experimental
> > 
> > such a construct would have to be used very judiciously, in that once its
> > implemented, the API has to be treated as stable, even though its 'excused' from
> > the normal checking, but it could provide something of the more rapid promotion
> > path being sought.
> > 
> Sure it could work and does meet the end goal. I'm not really sure it's a
> better solution than just promoting the function and putting in an alias
> for it back to experimental, though.
> 
It probably isn't, I was just trying to think of alternative
implementations, that dont make life harder in keeping up with LTS
maintenence.

Neil

		
> /Bruce
> 

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Ray Kinsella]

On 14/02/2020 20:48, Neil Horman wrote:
> On Fri, Feb 14, 2020 at 11:36:34AM +0000, Bruce Richardson wrote:
>> On Thu, Feb 13, 2020 at 09:40:40PM -0500, Neil Horman wrote:
>>> On Thu, Feb 13, 2020 at 05:40:43PM +0000, Ray Kinsella wrote:
>>>>
>>>>
>>>> On 05/02/2020 11:32, Neil Horman wrote:
>>>>> On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
>>>>>> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
>>>>>>>> But if we can do the versioning in the master, LTS can backport it
>>>>>>>> and can have mature version of that API in LTS without breaking
>>>>>>>> the existing users.
>>>>>>>>
>>>>>>>
>>>>>>> But why bother?  The only thing you've changed is the version
>>>>>>> tagging.  Its ok to leave that alone in LTS, you just cant change
>>>>>>> it.
>>>>>>>
>>>>>>> Thats part of the burden of an LTS release, it will have some drift
>>>>>>> from the upstream head, because you have to keep things stable.  So
>>>>>>> you stabilize the upstream ABI version for this API and just never
>>>>>>> backport it to the current LTS release.
>>>>>>
>>>>>> Hi,
>>>>>>
>>>>>> A customer (OVS) explicitly and specifically requested backporting
>>>>>> the symbol change to 19.11, as they don't want to enable
>>>>>> experimental APIs in their releases. I replied that it would only be
>>>>>> acceptable with aliasing to keep compatibility, and Ferruh very
>>>>>> kindly did the work to implement that.
>>>>>>
>>>>> but, thats part of the agreement, no?  You can't always have new
>>>>> features and stability at the same time.
>>>>>
>>>>> I get that this is an odd corner case, because strictly speaking you
>>>>> could waive the ABI change that libabigail is reporting, and most
>>>>> application users (like OVS) could get away with it, because their
>>>>> application does all the right things to make it ok, but I don't
>>>>> think you can make a decsion like this for all users based on the
>>>>> request of a single user.
>>>>>
>>>>> It seems like the right thing is for OVS to augment their build time
>>>>> configuration to allow developers to select the ability to use
>>>>> experimental apis at compile time, and then the decision is placed in
>>>>> the hands of end users.
>>>>
>>>> So this is not isolated case right ... it is common from API's to
>>>> graduate from experimental to mature, we _want_ that to happen, we
>>>> _want_ APIs to mature. 
>>>>
>>> Sure, I can absolutely agree with that, though I would suggest that the
>>> maturity of the ABI is orthogonal to its labeling as such (more on that
>>> below)
>>>
>>>> I am worried what you are proposing will encourage a behavior whereby
>>>> maintainers to wait until the declaration of the next major ABI version
>>>> to make these symbol changes, causing these kinds of changes to queue
>>>> up for that release. 
>>>>
>>> I think you're probably right about that, and would make the agrument
>>> that thats perfectly fine (again I'll clarify below)
>>>
>>>> And you would have to ask why?  In the case of a reasonably mature API,
>>>> there will be no functional or signature change - its mature!  So what
>>>> is the harm of providing an alias back to Experimental until the next
>>>> ABI version is declared?
>>>>
>>> From a philosophical standpoint, there is absoluely no harm, and I don't
>>> think anyone would disagree, the harm comes from the details of the
>>> implementation, as you've noted.
>>>
>>>> So while yes, you are 100% right - experimental mean no guarantees.
>>>> But if the API is baked, it is not going to change, so I don't see the
>>>> harm.
>>>>
>>>> We don't want the unnecessary triumph of policy over pragmatism. 
>>>>
>>> I would make the converse argument here.  While I agree that when an API
>>> is mature, theres no point in calling it experimental anymore, I would
>>> also suggest that, if an API is mature, and not expected to change,
>>> theres no harm in leaving its version tag as experimental for an LTS
>>> release.  This is what I was referring to above.  Once an application
>>> developer has done the work to integrate an API from DPDK into its
>>> application, that work is done.  If the API remains stable, then I
>>> honestly don't know that they care that the version label is EXPERIMENTAL
>>> versus 20.11 or 20.05 or whatever.  They care about the API being stable
>>> more so than its version label.  As such, it seems....reasonable to me to
>>> have developers queue their migration of experimental APIs to official
>>> versioned APIs at the next major release deliniation point.
>>>
>>> I'd welcome counter arguments, but it seems pretty natural to me to make
>>> these sorts of changes at the major release mark.  People using
>>> experimantal apis have already implicity agreed to manage changes to
>>> them, so if we just hold it stable in an LTS release (and don't update
>>> the version label), its just gravy for them.
>>>
>> The counter argument that I see is that while the experimental tag remains
>> in place the user has no way to know that an API is stable or not, and so
>> in many projects cannot use the API. If for example an API that is
>> experimental in 19.11 is unchanged through 20.05 at which point we decide
>> to promote it to stable. Once the change to the exp tag it is made, any
>> users of 19.11 can then see that it is an unchanged and now-stable ABI and
>> can start using it in their software, if they wish, without having to wait
>> for the 20.11 release. Changing the tag early allows ABIs to be potentially
>> used immediately.
>>
> 
> I would agree with this, however, when using an LTS release, in my mind at
> least, part of the agreement there is you get stability in the fuctions that
> were declared stable at the time of release.  I'm not sure there should be an
> expectation of additional stabilization within the lifetime of the release
> (thats really what the 12 month LTS release cycle is for, no)?  You never have
> to wait more than a year for a new set of stable features.  If you want faster
> feature integration than that, you can choose to enable the experimental API's
> and accept the benefits and drawbacks thereof.
> 
> That said, if (as I understand it) the goal is to provide a mechanism to allow
> experimental features to be promoted to stable status, perhaps we can find a
> happy middle ground.  What if we were to create a construct such as this:
> 
> #pragma push_macro("ALLOW_EXPERIMENTAL_APIS")
> #undef ALLOW_EXPERIMENTAL_APIS
> void __rte_experimental func(...);
> #pragma pop_macro("ALLOW_EXPERIMENTAL_APIS")
> 
> Such a consruct would allow the maintainer of an API to pseudo-promote an API
> from a experimental to stable status, at least so far as compilation would be
> concerned.  Its messy and clunky, and it wouldn't change the function version at
> all, but the end result would be that:
> a) such a wraped experimental function would no longer issue a warning when used
> during compilation/linking
> and
> b) provide a semi-easy grepable pattern for application writers to look for when
> considering the use of an API that was previously experimental
> 
> such a construct would have to be used very judiciously, in that once its
> implemented, the API has to be treated as stable, even though its 'excused' from
> the normal checking, but it could provide something of the more rapid promotion
> path being sought.
> 
> Thoughts?
> Neil
>> Regards,
>> /Bruce
>>


Then method above seems clunky, and it is unclear to me if it solves the original problem. 
It seems simpler to me to promote a symbol the next ABI version,  and then provide an alias.

At the declaration of the next major ABI version (v21), we would then only need to check 
for those symbols that are both EXPERIMENTAL and v21, to know which aliases need to be removed. 

Thanks,

Ray K

Re: [dpdk-dev] [RFC] meter: fix ABI break due to experimental tag removal

[Neil Horman]

On Mon, Feb 17, 2020 at 02:23:15PM +0000, Ray Kinsella wrote:
> 
> 
> On 14/02/2020 20:48, Neil Horman wrote:
> > On Fri, Feb 14, 2020 at 11:36:34AM +0000, Bruce Richardson wrote:
> >> On Thu, Feb 13, 2020 at 09:40:40PM -0500, Neil Horman wrote:
> >>> On Thu, Feb 13, 2020 at 05:40:43PM +0000, Ray Kinsella wrote:
> >>>>
> >>>>
> >>>> On 05/02/2020 11:32, Neil Horman wrote:
> >>>>> On Wed, Feb 05, 2020 at 11:04:29AM +0100, Luca Boccassi wrote:
> >>>>>> On Tue, 2020-02-04 at 07:02 -0500, Neil Horman wrote:
> >>>>>>>> But if we can do the versioning in the master, LTS can backport it
> >>>>>>>> and can have mature version of that API in LTS without breaking
> >>>>>>>> the existing users.
> >>>>>>>>
> >>>>>>>
> >>>>>>> But why bother?  The only thing you've changed is the version
> >>>>>>> tagging.  Its ok to leave that alone in LTS, you just cant change
> >>>>>>> it.
> >>>>>>>
> >>>>>>> Thats part of the burden of an LTS release, it will have some drift
> >>>>>>> from the upstream head, because you have to keep things stable.  So
> >>>>>>> you stabilize the upstream ABI version for this API and just never
> >>>>>>> backport it to the current LTS release.
> >>>>>>
> >>>>>> Hi,
> >>>>>>
> >>>>>> A customer (OVS) explicitly and specifically requested backporting
> >>>>>> the symbol change to 19.11, as they don't want to enable
> >>>>>> experimental APIs in their releases. I replied that it would only be
> >>>>>> acceptable with aliasing to keep compatibility, and Ferruh very
> >>>>>> kindly did the work to implement that.
> >>>>>>
> >>>>> but, thats part of the agreement, no?  You can't always have new
> >>>>> features and stability at the same time.
> >>>>>
> >>>>> I get that this is an odd corner case, because strictly speaking you
> >>>>> could waive the ABI change that libabigail is reporting, and most
> >>>>> application users (like OVS) could get away with it, because their
> >>>>> application does all the right things to make it ok, but I don't
> >>>>> think you can make a decsion like this for all users based on the
> >>>>> request of a single user.
> >>>>>
> >>>>> It seems like the right thing is for OVS to augment their build time
> >>>>> configuration to allow developers to select the ability to use
> >>>>> experimental apis at compile time, and then the decision is placed in
> >>>>> the hands of end users.
> >>>>
> >>>> So this is not isolated case right ... it is common from API's to
> >>>> graduate from experimental to mature, we _want_ that to happen, we
> >>>> _want_ APIs to mature. 
> >>>>
> >>> Sure, I can absolutely agree with that, though I would suggest that the
> >>> maturity of the ABI is orthogonal to its labeling as such (more on that
> >>> below)
> >>>
> >>>> I am worried what you are proposing will encourage a behavior whereby
> >>>> maintainers to wait until the declaration of the next major ABI version
> >>>> to make these symbol changes, causing these kinds of changes to queue
> >>>> up for that release. 
> >>>>
> >>> I think you're probably right about that, and would make the agrument
> >>> that thats perfectly fine (again I'll clarify below)
> >>>
> >>>> And you would have to ask why?  In the case of a reasonably mature API,
> >>>> there will be no functional or signature change - its mature!  So what
> >>>> is the harm of providing an alias back to Experimental until the next
> >>>> ABI version is declared?
> >>>>
> >>> From a philosophical standpoint, there is absoluely no harm, and I don't
> >>> think anyone would disagree, the harm comes from the details of the
> >>> implementation, as you've noted.
> >>>
> >>>> So while yes, you are 100% right - experimental mean no guarantees.
> >>>> But if the API is baked, it is not going to change, so I don't see the
> >>>> harm.
> >>>>
> >>>> We don't want the unnecessary triumph of policy over pragmatism. 
> >>>>
> >>> I would make the converse argument here.  While I agree that when an API
> >>> is mature, theres no point in calling it experimental anymore, I would
> >>> also suggest that, if an API is mature, and not expected to change,
> >>> theres no harm in leaving its version tag as experimental for an LTS
> >>> release.  This is what I was referring to above.  Once an application
> >>> developer has done the work to integrate an API from DPDK into its
> >>> application, that work is done.  If the API remains stable, then I
> >>> honestly don't know that they care that the version label is EXPERIMENTAL
> >>> versus 20.11 or 20.05 or whatever.  They care about the API being stable
> >>> more so than its version label.  As such, it seems....reasonable to me to
> >>> have developers queue their migration of experimental APIs to official
> >>> versioned APIs at the next major release deliniation point.
> >>>
> >>> I'd welcome counter arguments, but it seems pretty natural to me to make
> >>> these sorts of changes at the major release mark.  People using
> >>> experimantal apis have already implicity agreed to manage changes to
> >>> them, so if we just hold it stable in an LTS release (and don't update
> >>> the version label), its just gravy for them.
> >>>
> >> The counter argument that I see is that while the experimental tag remains
> >> in place the user has no way to know that an API is stable or not, and so
> >> in many projects cannot use the API. If for example an API that is
> >> experimental in 19.11 is unchanged through 20.05 at which point we decide
> >> to promote it to stable. Once the change to the exp tag it is made, any
> >> users of 19.11 can then see that it is an unchanged and now-stable ABI and
> >> can start using it in their software, if they wish, without having to wait
> >> for the 20.11 release. Changing the tag early allows ABIs to be potentially
> >> used immediately.
> >>
> > 
> > I would agree with this, however, when using an LTS release, in my mind at
> > least, part of the agreement there is you get stability in the fuctions that
> > were declared stable at the time of release.  I'm not sure there should be an
> > expectation of additional stabilization within the lifetime of the release
> > (thats really what the 12 month LTS release cycle is for, no)?  You never have
> > to wait more than a year for a new set of stable features.  If you want faster
> > feature integration than that, you can choose to enable the experimental API's
> > and accept the benefits and drawbacks thereof.
> > 
> > That said, if (as I understand it) the goal is to provide a mechanism to allow
> > experimental features to be promoted to stable status, perhaps we can find a
> > happy middle ground.  What if we were to create a construct such as this:
> > 
> > #pragma push_macro("ALLOW_EXPERIMENTAL_APIS")
> > #undef ALLOW_EXPERIMENTAL_APIS
> > void __rte_experimental func(...);
> > #pragma pop_macro("ALLOW_EXPERIMENTAL_APIS")
> > 
> > Such a consruct would allow the maintainer of an API to pseudo-promote an API
> > from a experimental to stable status, at least so far as compilation would be
> > concerned.  Its messy and clunky, and it wouldn't change the function version at
> > all, but the end result would be that:
> > a) such a wraped experimental function would no longer issue a warning when used
> > during compilation/linking
> > and
> > b) provide a semi-easy grepable pattern for application writers to look for when
> > considering the use of an API that was previously experimental
> > 
> > such a construct would have to be used very judiciously, in that once its
> > implemented, the API has to be treated as stable, even though its 'excused' from
> > the normal checking, but it could provide something of the more rapid promotion
> > path being sought.
> > 
> > Thoughts?
> > Neil
> >> Regards,
> >> /Bruce
> >>
> 
> 
> Then method above seems clunky, and it is unclear to me if it solves the original problem. 
> It seems simpler to me to promote a symbol the next ABI version,  and then provide an alias.
> 
> At the declaration of the next major ABI version (v21), we would then only need to check 
> for those symbols that are both EXPERIMENTAL and v21, to know which aliases need to be removed. 
> 
> Thanks,
> 
> Ray K
> 
i don't disagree, just looking for other potential options.

Neil

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

[Ferruh Yigit]

Duplicate the existing and versioned symbol as experimental.

This is to prevent DPDK maturing experimental API breaking old
applications using that experimental API.
The relevant process update is captured in:
https://patches.dpdk.org/patch/65863/

Created VERSION_SYMBOL_EXPERIMENTAL helper macro.

Updated the 'check-experimental-syms.sh' buildtool, 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)

Enabled function versioning for meson build for the library.

Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")

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>
---
 buildtools/check-symbols.sh                   |  3 +-
 .../include/rte_function_versioning.h         |  4 ++
 lib/librte_meter/meson.build                  |  1 +
 lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
 lib/librte_meter/rte_meter_version.map        |  8 +++
 5 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
index 3df57c322c..e407553a34 100755
--- a/buildtools/check-symbols.sh
+++ b/buildtools/check-symbols.sh
@@ -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
diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
index b9f862d295..22ec5f9424 100644
--- a/lib/librte_eal/include/rte_function_versioning.h
+++ b/lib/librte_eal/include/rte_function_versioning.h
@@ -46,6 +46,9 @@
  */
 #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
 
+
+#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 +82,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))))
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..c600b05064 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
 	return 0;
 }
 
-int
-rte_meter_trtcm_rfc4115_profile_config(
+static int
+rte_meter_trtcm_rfc4115_profile_config_(
 	struct rte_meter_trtcm_rfc4115_profile *p,
 	struct rte_meter_trtcm_rfc4115_params *params)
 {
@@ -145,7 +146,35 @@ 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);
+
+static int
+rte_meter_trtcm_rfc4115_config_(
 	struct rte_meter_trtcm_rfc4115 *m,
 	struct rte_meter_trtcm_rfc4115_profile *p)
 {
@@ -160,3 +189,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

Re: [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps

[Thomas Monjalon]

I think the title should be about ABI, not API.

13/05/2020 14:11, Ferruh Yigit:
> Duplicate the existing and versioned symbol as experimental.

Would be good to explain the case of the meter lib you are addressing.
If I understand well, you consider we "broke" the experimental ABI
during 20.02 when moving symbols from EXPERIMENTAL to DPDK_20.0.1
(and to DPDK_21 during 20.05).
That's why you want to add back the EXPERIMENTAL symbol as an alias
of the symbol in the next ABI (21).


> This is to prevent DPDK maturing experimental API breaking old
> applications using that experimental API.
> The relevant process update is captured in:
> https://patches.dpdk.org/patch/65863/
> 
> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> Updated the 'check-experimental-syms.sh' buildtool, 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)
> 
> Enabled function versioning for meson build for the library.
> 
> Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")

Even if it's never backported, it would be more correct to add Cc: stable
to indicate it is fixing previous release (20.02 here).


> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
[...]
> --- 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;
> +};
> 

Re: [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps

[Ferruh Yigit]

On 5/13/2020 5:30 PM, Thomas Monjalon wrote:
> I think the title should be about ABI, not API.
> 
> 13/05/2020 14:11, Ferruh Yigit:
>> Duplicate the existing and versioned symbol as experimental.
> 
> Would be good to explain the case of the meter lib you are addressing.
> If I understand well, you consider we "broke" the experimental ABI
> during 20.02 when moving symbols from EXPERIMENTAL to DPDK_20.0.1
> (and to DPDK_21 during 20.05).
> That's why you want to add back the EXPERIMENTAL symbol as an alias
> of the symbol in the next ABI (21).

Yes, this is the case, I can try again to clarify.

Btw, I wasn't following that bit, how we are mitigating the affect of the
DPDK_20.0.1 -> DPDK_21 change to applications?


> 
> 
>> This is to prevent DPDK maturing experimental API breaking old
>> applications using that experimental API.
>> The relevant process update is captured in:
>> https://patches.dpdk.org/patch/65863/
>>
>> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
>>
>> Updated the 'check-experimental-syms.sh' buildtool, 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)
>>
>> Enabled function versioning for meson build for the library.
>>
>> Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")
> 
> Even if it's never backported, it would be more correct to add Cc: stable
> to indicate it is fixing previous release (20.02 here).

As you said original patch is after LTS, but yes I can add the tag.
(Although not having stable tag implies the fix is not in this release, it also
may mean backport is not requested as been in this case.)

> 
> 
>> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> [...]
>> --- 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;
>> +};
>>
> 
> 
> 
> 
> 

[dpdk-dev] [PATCH v2] meter: provide experimental alias of API for old apps

[Ferruh Yigit]

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.

Since experimental APIs can change or go away without notice as part of
contract, to prevent this negative affect that may occur by maturing
experimental API, a process update already suggested, which enables
aliasing without forcing it:
https://patches.dpdk.org/patch/65863/

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.

Also following changes done to enabling aliasing:

Created VERSION_SYMBOL_EXPERIMENTAL helper macro.

Updated the 'check-experimental-syms.sh' buildtool, 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)

Enabled function versioning for meson build for the library.

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>

v2:
* Commit log updated
---
 buildtools/check-symbols.sh                   |  3 +-
 .../include/rte_function_versioning.h         |  4 ++
 lib/librte_meter/meson.build                  |  1 +
 lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
 lib/librte_meter/rte_meter_version.map        |  8 +++
 5 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
index 3df57c322c..e407553a34 100755
--- a/buildtools/check-symbols.sh
+++ b/buildtools/check-symbols.sh
@@ -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
diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
index b9f862d295..22ec5f9424 100644
--- a/lib/librte_eal/include/rte_function_versioning.h
+++ b/lib/librte_eal/include/rte_function_versioning.h
@@ -46,6 +46,9 @@
  */
 #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
 
+
+#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 +82,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))))
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..c600b05064 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
 	return 0;
 }
 
-int
-rte_meter_trtcm_rfc4115_profile_config(
+static int
+rte_meter_trtcm_rfc4115_profile_config_(
 	struct rte_meter_trtcm_rfc4115_profile *p,
 	struct rte_meter_trtcm_rfc4115_params *params)
 {
@@ -145,7 +146,35 @@ 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);
+
+static int
+rte_meter_trtcm_rfc4115_config_(
 	struct rte_meter_trtcm_rfc4115 *m,
 	struct rte_meter_trtcm_rfc4115_profile *p)
 {
@@ -160,3 +189,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

Re: [dpdk-dev] [PATCH v2] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 13/05/2020 19:05, 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.
> 
> Since experimental APIs can change or go away without notice as part of
> contract, to prevent this negative affect that may occur by maturing
> experimental API, a process update already suggested, which enables
> aliasing without forcing it:
> https://patches.dpdk.org/patch/65863/
> 
> 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.
> 
> Also following changes done to enabling aliasing:
> 
> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> Updated the 'check-experimental-syms.sh' buildtool, 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)
> 
> Enabled function versioning for meson build for the library.
> 
> 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>
> 
> v2:
> * Commit log updated
> ---
>  buildtools/check-symbols.sh                   |  3 +-
>  .../include/rte_function_versioning.h         |  4 ++
>  lib/librte_meter/meson.build                  |  1 +
>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
>  lib/librte_meter/rte_meter_version.map        |  8 +++
>  5 files changed, 71 insertions(+), 4 deletions(-)
> 
> diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
> index 3df57c322c..e407553a34 100755
> --- a/buildtools/check-symbols.sh
> +++ b/buildtools/check-symbols.sh
> @@ -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
> diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
> index b9f862d295..22ec5f9424 100644
> --- a/lib/librte_eal/include/rte_function_versioning.h
> +++ b/lib/librte_eal/include/rte_function_versioning.h
> @@ -46,6 +46,9 @@
>   */
>  #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))

Please add

/*
 * 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.
 */

I will take care of the updates to doc/guides/contributing/abi*.rst

> +
> +#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 +82,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))))
> 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..c600b05064 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
>  	return 0;
>  }
>  
> -int
> -rte_meter_trtcm_rfc4115_profile_config(
> +static int
> +rte_meter_trtcm_rfc4115_profile_config_(
>  	struct rte_meter_trtcm_rfc4115_profile *p,
>  	struct rte_meter_trtcm_rfc4115_params *params)
>  {
> @@ -145,7 +146,35 @@ 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);
> +
> +static int
> +rte_meter_trtcm_rfc4115_config_(
>  	struct rte_meter_trtcm_rfc4115 *m,
>  	struct rte_meter_trtcm_rfc4115_profile *p)
>  {
> @@ -160,3 +189,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;
> +};
> 

[dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps

[Ferruh Yigit]

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.

Since experimental APIs can change or go away without notice as part of
contract, to prevent this negative affect that may occur by maturing
experimental API, a process update already suggested, which enables
aliasing without forcing it:
https://patches.dpdk.org/patch/65863/

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.

Also following changes done to enabling aliasing:

Created VERSION_SYMBOL_EXPERIMENTAL helper macro.

Updated the 'check-experimental-syms.sh' buildtool, 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)

Enabled function versioning for meson build for the library.

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>

v2:
* Commit log updated

v3:
* added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro
---
 buildtools/check-symbols.sh                   |  3 +-
 .../include/rte_function_versioning.h         | 10 ++++
 lib/librte_meter/meson.build                  |  1 +
 lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
 lib/librte_meter/rte_meter_version.map        |  8 +++
 5 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
index 3df57c322c..e407553a34 100755
--- a/buildtools/check-symbols.sh
+++ b/buildtools/check-symbols.sh
@@ -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
diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
index b9f862d295..534a8bff95 100644
--- a/lib/librte_eal/include/rte_function_versioning.h
+++ b/lib/librte_eal/include/rte_function_versioning.h
@@ -46,6 +46,15 @@
  */
 #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 +88,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))))
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..c600b05064 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
 	return 0;
 }
 
-int
-rte_meter_trtcm_rfc4115_profile_config(
+static int
+rte_meter_trtcm_rfc4115_profile_config_(
 	struct rte_meter_trtcm_rfc4115_profile *p,
 	struct rte_meter_trtcm_rfc4115_params *params)
 {
@@ -145,7 +146,35 @@ 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);
+
+static int
+rte_meter_trtcm_rfc4115_config_(
 	struct rte_meter_trtcm_rfc4115 *m,
 	struct rte_meter_trtcm_rfc4115_profile *p)
 {
@@ -160,3 +189,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

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

[Ferruh Yigit]

On 5/14/2020 9:44 AM, Ray Kinsella wrote:
> 
> 
> On 13/05/2020 19:05, 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.
>>
>> Since experimental APIs can change or go away without notice as part of
>> contract, to prevent this negative affect that may occur by maturing
>> experimental API, a process update already suggested, which enables
>> aliasing without forcing it:
>> https://patches.dpdk.org/patch/65863/
>>
>> 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.
>>
>> Also following changes done to enabling aliasing:
>>
>> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
>>
>> Updated the 'check-experimental-syms.sh' buildtool, 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)
>>
>> Enabled function versioning for meson build for the library.
>>
>> Fixes: 30512af820fe ("meter: remove experimental flag from RFC4115 trTCM API")
>> Cc: stable@dpdk.org
>>
>> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>

<...>

>> @@ -46,6 +46,9 @@
>>   */
>>  #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
> 
> Please add
> 
> /*
>  * 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.
>  */

done

Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 14/05/2020 12:52, 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.
> 
> Since experimental APIs can change or go away without notice as part of
> contract, to prevent this negative affect that may occur by maturing
> experimental API, a process update already suggested, which enables
> aliasing without forcing it:
> https://patches.dpdk.org/patch/65863/
> 
> 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.
> 
> Also following changes done to enabling aliasing:
> 
> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> Updated the 'check-experimental-syms.sh' buildtool, 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)
> 
> Enabled function versioning for meson build for the library.
> 
> 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>
> 
> v2:
> * Commit log updated
> 
> v3:
> * added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro
> ---
[SNIP]
> 

Acked-by: Ray Kinsella 

Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps

[David Marchand]

On Thu, May 14, 2020 at 1:52 PM Ferruh Yigit <ferruh.yigit@intel.com> 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.
>
> Since experimental APIs can change or go away without notice as part of
> contract, to prevent this negative affect that may occur by maturing
> experimental API, a process update already suggested, which enables
> aliasing without forcing it:
> https://patches.dpdk.org/patch/65863/
>
> 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.
>
> Also following changes done to enabling aliasing:
>
> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.

This helper (+ script update) must come with the process update: the
macro is referenced in its v5 revision.


>
> Updated the 'check-experimental-syms.sh' buildtool, which was

Nit: the script name changed.


> diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
> index b9f862d295..534a8bff95 100644
> --- a/lib/librte_eal/include/rte_function_versioning.h
> +++ b/lib/librte_eal/include/rte_function_versioning.h
> @@ -46,6 +46,15 @@
>   */
>  #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
>
> +

No need for this newline.

> +/*
> + * 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


-- 
David Marchand

Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 14/05/2020 16:32, David Marchand wrote:
> On Thu, May 14, 2020 at 1:52 PM Ferruh Yigit <ferruh.yigit@intel.com> 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.
>>
>> Since experimental APIs can change or go away without notice as part of
>> contract, to prevent this negative affect that may occur by maturing
>> experimental API, a process update already suggested, which enables
>> aliasing without forcing it:
>> https://patches.dpdk.org/patch/65863/
>>
>> 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.
>>
>> Also following changes done to enabling aliasing:
>>
>> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> This helper (+ script update) must come with the process update: the
> macro is referenced in its v5 revision.

You mean you want to consolidate both into a single commit?

> 
> 
>>
>> Updated the 'check-experimental-syms.sh' buildtool, which was
> 
> Nit: the script name changed.
> 
> 
>> diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
>> index b9f862d295..534a8bff95 100644
>> --- a/lib/librte_eal/include/rte_function_versioning.h
>> +++ b/lib/librte_eal/include/rte_function_versioning.h
>> @@ -46,6 +46,15 @@
>>   */
>>  #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
>>
>> +
> 
> No need for this newline.
> 
>> +/*
>> + * 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
> 
> 

Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps

[Ferruh Yigit]

On 5/14/2020 4:32 PM, David Marchand wrote:
> On Thu, May 14, 2020 at 1:52 PM Ferruh Yigit <ferruh.yigit@intel.com> 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.
>>
>> Since experimental APIs can change or go away without notice as part of
>> contract, to prevent this negative affect that may occur by maturing
>> experimental API, a process update already suggested, which enables
>> aliasing without forcing it:
>> https://patches.dpdk.org/patch/65863/
>>
>> 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.
>>
>> Also following changes done to enabling aliasing:
>>
>> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> This helper (+ script update) must come with the process update: the
> macro is referenced in its v5 revision.

The macro is implementation detail, and this patch does the implementation.
There is a dependency to process update patch, but that doesn't need to define
how the macro should be.

Let me send a new version with below updates, we can discuss this more if required.

> 
> 
>>
>> Updated the 'check-experimental-syms.sh' buildtool, which was
> 
> Nit: the script name changed.
> 
> 
>> diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
>> index b9f862d295..534a8bff95 100644
>> --- a/lib/librte_eal/include/rte_function_versioning.h
>> +++ b/lib/librte_eal/include/rte_function_versioning.h
>> @@ -46,6 +46,15 @@
>>   */
>>  #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
>>
>> +
> 
> No need for this newline.
> 
>> +/*
>> + * 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
> 
> 

[dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Ferruh Yigit]

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.

Since experimental APIs can change or go away without notice as part of
contract, to prevent this negative affect that may occur by maturing
experimental API, a process update already suggested, which enables
aliasing without forcing it:
https://patches.dpdk.org/patch/65863/

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.

Also following changes done to enabling aliasing:

Created VERSION_SYMBOL_EXPERIMENTAL helper macro.

Updated the 'check-symbols.sh' buildtool, 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)

Enabled function versioning for meson build for the library.

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>

v2:
* Commit log updated

v3:
* added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro

v4:
* update script name in commit log, remove empty line
---
 buildtools/check-symbols.sh                   |  3 +-
 .../include/rte_function_versioning.h         |  9 +++
 lib/librte_meter/meson.build                  |  1 +
 lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
 lib/librte_meter/rte_meter_version.map        |  8 +++
 5 files changed, 76 insertions(+), 4 deletions(-)

diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
index 3df57c322c..e407553a34 100755
--- a/buildtools/check-symbols.sh
+++ b/buildtools/check-symbols.sh
@@ -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
diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
index b9f862d295..f588f2643b 100644
--- a/lib/librte_eal/include/rte_function_versioning.h
+++ b/lib/librte_eal/include/rte_function_versioning.h
@@ -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))))
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..c600b05064 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
 	return 0;
 }
 
-int
-rte_meter_trtcm_rfc4115_profile_config(
+static int
+rte_meter_trtcm_rfc4115_profile_config_(
 	struct rte_meter_trtcm_rfc4115_profile *p,
 	struct rte_meter_trtcm_rfc4115_params *params)
 {
@@ -145,7 +146,35 @@ 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);
+
+static int
+rte_meter_trtcm_rfc4115_config_(
 	struct rte_meter_trtcm_rfc4115 *m,
 	struct rte_meter_trtcm_rfc4115_profile *p)
 {
@@ -160,3 +189,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

Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps

[David Marchand]

On Thu, May 14, 2020 at 6:08 PM Ferruh Yigit <ferruh.yigit@intel.com> wrote:
>
> On 5/14/2020 4:32 PM, David Marchand wrote:
> > On Thu, May 14, 2020 at 1:52 PM Ferruh Yigit <ferruh.yigit@intel.com> 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.
> >>
> >> Since experimental APIs can change or go away without notice as part of
> >> contract, to prevent this negative affect that may occur by maturing
> >> experimental API, a process update already suggested, which enables
> >> aliasing without forcing it:
> >> https://patches.dpdk.org/patch/65863/
> >>
> >> 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.
> >>
> >> Also following changes done to enabling aliasing:
> >>
> >> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> >
> > This helper (+ script update) must come with the process update: the
> > macro is referenced in its v5 revision.
>
> The macro is implementation detail, and this patch does the implementation.
> There is a dependency to process update patch, but that doesn't need to define
> how the macro should be.

This is inconsistent.
The process update patch gives a clear example of how the macro must be used.


-- 
David Marchand

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Thomas Monjalon]

14/05/2020 18:11, Ferruh Yigit:
> 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.
> 
> Since experimental APIs can change or go away without notice as part of
> contract, to prevent this negative affect that may occur by maturing
> experimental API, a process update already suggested, which enables
> aliasing without forcing it:
> https://patches.dpdk.org/patch/65863/
> 
> 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.
> 
> Also following changes done to enabling aliasing:
> 
> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> Updated the 'check-symbols.sh' buildtool, 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)
> 
> Enabled function versioning for meson build for the library.
> 
> 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>
> 
> v2:
> * Commit log updated
> 
> v3:
> * added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro
> 
> v4:
> * update script name in commit log, remove empty line
> ---
>  buildtools/check-symbols.sh                   |  3 +-
>  .../include/rte_function_versioning.h         |  9 +++
>  lib/librte_meter/meson.build                  |  1 +
>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
>  lib/librte_meter/rte_meter_version.map        |  8 +++
>  5 files changed, 76 insertions(+), 4 deletions(-)

This patch is introducing the tooling and use it for the lib meter.
It is based on approval of the process documentation.

Ray sent a patch for the process documentation which refers to this tooling.

As raised by David, there is a circular dependency :)

I think it would be clearer to merge tooling and doc together,
and have meter changes separate.
Would it work for you?

[dpdk-dev] [PATCH v5] abi: provide experimental alias of API for old apps

[Ray Kinsella]

From: Ferruh Yigit <ferruh.yigit@intel.com>

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' buildtool, 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>
---

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: Kevin Traynor <ktraynor@redhat.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:
* incorporate policy and version doc changes
* remove changes to librte_meter

 buildtools/check-symbols.sh                      |   3 +-
 doc/guides/contributing/abi_policy.rst           |  10 ++
 doc/guides/contributing/abi_versioning.rst       | 158 ++++++++++++++++++++++-
 lib/librte_eal/include/rte_function_versioning.h |   9 ++
 4 files changed, 178 insertions(+), 2 deletions(-)

diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
index 3df57c3..e407553 100755
--- a/buildtools/check-symbols.sh
+++ b/buildtools/check-symbols.sh
@@ -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
diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 86e7dd9..c33bff1 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -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
 ~~~~~~~~~

diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
index 7065979..27b5231 100644
--- a/doc/guides/contributing/abi_versioning.rst
+++ b/doc/guides/contributing/abi_versioning.rst
@@ -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
@@ -361,7 +366,7 @@ and a new DPDK_21 version, used by future built applications.
 .. note::

    **Before you leave**, please take care to the review the sections on
-   :ref:`Mapping static symbols <mapping_static_symbols>`, :ref:`Enabling
+   :ref:`mapping static symbols <mapping_static_symbols>`, :ref:`enabling
    versioning macros <enabling_versioning_macros>` and :ref:`ABI deprecation
    <abi_decprecation>`.

@@ -415,6 +420,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 visioning <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 ``v21``
+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 ``v21``
+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 ``v21`` 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 visioning <example_abi_macro_usage>`
+   when aliasing to experimental you will also need to take care of
+   :ref:`mapping static symbols <mapping_static_symbols>`.
+
+
 .. _abi_decprecation:

 Deprecating part of a public API
diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
index b9f862d..f588f26 100644
--- a/lib/librte_eal/include/rte_function_versioning.h
+++ b/lib/librte_eal/include/rte_function_versioning.h
@@ -47,6 +47,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
  * symbol <b> to the internal symbol <b><e>
@@ -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))))
--
2.7.4

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 15/05/2020 14:31, Thomas Monjalon wrote:
> 14/05/2020 18:11, Ferruh Yigit:
>> 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.
>>
>> Since experimental APIs can change or go away without notice as part of
>> contract, to prevent this negative affect that may occur by maturing
>> experimental API, a process update already suggested, which enables
>> aliasing without forcing it:
>> https://patches.dpdk.org/patch/65863/
>>
>> 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.
>>
>> Also following changes done to enabling aliasing:
>>
>> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
>>
>> Updated the 'check-symbols.sh' buildtool, 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)
>>
>> Enabled function versioning for meson build for the library.
>>
>> 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>
>>
>> v2:
>> * Commit log updated
>>
>> v3:
>> * added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro
>>
>> v4:
>> * update script name in commit log, remove empty line
>> ---
>>  buildtools/check-symbols.sh                   |  3 +-
>>  .../include/rte_function_versioning.h         |  9 +++
>>  lib/librte_meter/meson.build                  |  1 +
>>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
>>  lib/librte_meter/rte_meter_version.map        |  8 +++
>>  5 files changed, 76 insertions(+), 4 deletions(-)
> 
> This patch is introducing the tooling and use it for the lib meter.
> It is based on approval of the process documentation.
> 
> Ray sent a patch for the process documentation which refers to this tooling.
> 
> As raised by David, there is a circular dependency :)
> 
> I think it would be clearer to merge tooling and doc together,
> and have meter changes separate.
> Would it work for you?
>

So I sent a v5 just of the policy and tooling changes.

Ray K

[dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps

[Ray Kinsella]

From: Ferruh Yigit <ferruh.yigit@intel.com>

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' buildtool, 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>
---

This patch depends on "doc: fix references to bind_default_symbol".
https://patches.dpdk.org/patch/69850/

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: Kevin Traynor <ktraynor@redhat.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:
* incorporate policy and version doc changes
* remove changes to librte_meter

v6:
* clarified dependency chain includes "doc: fix references to bind_default_symbol".

 buildtools/check-symbols.sh                      |   3 +-
 doc/guides/contributing/abi_policy.rst           |  10 ++
 doc/guides/contributing/abi_versioning.rst       | 158 ++++++++++++++++++++++-
 lib/librte_eal/include/rte_function_versioning.h |   9 ++
 4 files changed, 178 insertions(+), 2 deletions(-)

diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
index 3df57c3..e407553 100755
--- a/buildtools/check-symbols.sh
+++ b/buildtools/check-symbols.sh
@@ -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
diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 86e7dd9..c33bff1 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -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
 ~~~~~~~~~

diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
index 7065979..27b5231 100644
--- a/doc/guides/contributing/abi_versioning.rst
+++ b/doc/guides/contributing/abi_versioning.rst
@@ -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
@@ -361,7 +366,7 @@ and a new DPDK_21 version, used by future built applications.
 .. note::

    **Before you leave**, please take care to the review the sections on
-   :ref:`Mapping static symbols <mapping_static_symbols>`, :ref:`Enabling
+   :ref:`mapping static symbols <mapping_static_symbols>`, :ref:`enabling
    versioning macros <enabling_versioning_macros>` and :ref:`ABI deprecation
    <abi_decprecation>`.

@@ -415,6 +420,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 visioning <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 ``v21``
+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 ``v21``
+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 ``v21`` 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 visioning <example_abi_macro_usage>`
+   when aliasing to experimental you will also need to take care of
+   :ref:`mapping static symbols <mapping_static_symbols>`.
+
+
 .. _abi_decprecation:

 Deprecating part of a public API
diff --git a/lib/librte_eal/include/rte_function_versioning.h b/lib/librte_eal/include/rte_function_versioning.h
index b9f862d..f588f26 100644
--- a/lib/librte_eal/include/rte_function_versioning.h
+++ b/lib/librte_eal/include/rte_function_versioning.h
@@ -47,6 +47,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
  * symbol <b> to the internal symbol <b><e>
@@ -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))))
--
2.7.4

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 15/05/2020 14:31, Thomas Monjalon wrote:
> 14/05/2020 18:11, Ferruh Yigit:
>> 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.
>>
>> Since experimental APIs can change or go away without notice as part of
>> contract, to prevent this negative affect that may occur by maturing
>> experimental API, a process update already suggested, which enables
>> aliasing without forcing it:
>> https://patches.dpdk.org/patch/65863/
>>
>> 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.
>>
>> Also following changes done to enabling aliasing:
>>
>> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
>>
>> Updated the 'check-symbols.sh' buildtool, 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)
>>
>> Enabled function versioning for meson build for the library.
>>
>> 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>
>>
>> v2:
>> * Commit log updated
>>
>> v3:
>> * added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro
>>
>> v4:
>> * update script name in commit log, remove empty line
>> ---
>>  buildtools/check-symbols.sh                   |  3 +-
>>  .../include/rte_function_versioning.h         |  9 +++
>>  lib/librte_meter/meson.build                  |  1 +
>>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
>>  lib/librte_meter/rte_meter_version.map        |  8 +++
>>  5 files changed, 76 insertions(+), 4 deletions(-)
> 
> This patch is introducing the tooling and use it for the lib meter.
> It is based on approval of the process documentation.
> 
> Ray sent a patch for the process documentation which refers to this tooling.
> 
> As raised by David, there is a circular dependency :)
> 
> I think it would be clearer to merge tooling and doc together,
> and have meter changes separate.
> Would it work for you?
> 

BTW - send a v6 to make a abundantly clear that 

"doc: fix references to bind_default_symbol".
https://patches.dpdk.org/patch/69850/

is a dependency. 

Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps

[Neil Horman]

On Fri, May 15, 2020 at 04:01:53PM +0100, Ray Kinsella wrote:
> From: Ferruh Yigit <ferruh.yigit@intel.com>
> 
> 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' buildtool, 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>
> ---
> 
> This patch depends on "doc: fix references to bind_default_symbol".
> https://patches.dpdk.org/patch/69850/
> 
> 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: Kevin Traynor <ktraynor@redhat.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:
> * incorporate policy and version doc changes
> * remove changes to librte_meter
> 
> v6:
> * clarified dependency chain includes "doc: fix references to bind_default_symbol".
> 
>  buildtools/check-symbols.sh                      |   3 +-
>  doc/guides/contributing/abi_policy.rst           |  10 ++
>  doc/guides/contributing/abi_versioning.rst       | 158 ++++++++++++++++++++++-
>  lib/librte_eal/include/rte_function_versioning.h |   9 ++
>  4 files changed, 178 insertions(+), 2 deletions(-)
> 
Acked-by: Neil Horman <nhorman@tuxdriver.com>

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Dumitrescu, Cristian]

Hi Ferruh,

> -----Original Message-----
> From: Yigit, Ferruh <ferruh.yigit@intel.com>
> Sent: Thursday, May 14, 2020 5:11 PM
> To: Ray Kinsella <mdr@ashroe.eu>; Neil Horman
> <nhorman@tuxdriver.com>; Dumitrescu, Cristian
> <cristian.dumitrescu@intel.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 v4] 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.
> 
> Since experimental APIs can change or go away without notice as part of
> contract, to prevent this negative affect that may occur by maturing
> experimental API, a process update already suggested, which enables
> aliasing without forcing it:
> https://patches.dpdk.org/patch/65863/
> 

Personally, I am not convinced this is really needed.

Are there any users asking for this?

Is there any other library where this is also applied, or is librte_meter the only library?

> 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.
> 
> Also following changes done to enabling aliasing:
> 
> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
> 
> Updated the 'check-symbols.sh' buildtool, 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)
> 
> Enabled function versioning for meson build for the library.
> 
> 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>
> 
> v2:
> * Commit log updated
> 
> v3:
> * added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro
> 
> v4:
> * update script name in commit log, remove empty line
> ---
>  buildtools/check-symbols.sh                   |  3 +-
>  .../include/rte_function_versioning.h         |  9 +++
>  lib/librte_meter/meson.build                  |  1 +
>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
>  lib/librte_meter/rte_meter_version.map        |  8 +++
>  5 files changed, 76 insertions(+), 4 deletions(-)
> 
> diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
> index 3df57c322c..e407553a34 100755
> --- a/buildtools/check-symbols.sh
> +++ b/buildtools/check-symbols.sh
> @@ -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
> diff --git a/lib/librte_eal/include/rte_function_versioning.h
> b/lib/librte_eal/include/rte_function_versioning.h
> index b9f862d295..f588f2643b 100644
> --- a/lib/librte_eal/include/rte_function_versioning.h
> +++ b/lib/librte_eal/include/rte_function_versioning.h
> @@ -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))))
> 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..c600b05064 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
>  	return 0;
>  }
> 
> -int
> -rte_meter_trtcm_rfc4115_profile_config(
> +static int
> +rte_meter_trtcm_rfc4115_profile_config_(
>  	struct rte_meter_trtcm_rfc4115_profile *p,
>  	struct rte_meter_trtcm_rfc4115_params *params)
>  {
> @@ -145,7 +146,35 @@ 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);
> +
> +static int
> +rte_meter_trtcm_rfc4115_config_(
>  	struct rte_meter_trtcm_rfc4115 *m,
>  	struct rte_meter_trtcm_rfc4115_profile *p)
>  {
> @@ -160,3 +189,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);

To me, this is a significant amount of dead code that does not add any functionality and does not bring any added value to the library for any user. I am not a build system expert, but I would definitely prefer avoiding adding any C code to the library for this purpose, and just modify the map file, would this approach be possible?

Also, very important, is this C code to be added permanently or is it added just on a temporary basis? If temporary, when is it going to be removed?

> 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

Regards,
Cristian

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 17/05/2020 20:52, Dumitrescu, Cristian wrote:
> Hi Ferruh,
> 
>> -----Original Message-----
>> From: Yigit, Ferruh <ferruh.yigit@intel.com>
>> Sent: Thursday, May 14, 2020 5:11 PM
>> To: Ray Kinsella <mdr@ashroe.eu>; Neil Horman
>> <nhorman@tuxdriver.com>; Dumitrescu, Cristian
>> <cristian.dumitrescu@intel.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 v4] 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.
>>
>> Since experimental APIs can change or go away without notice as part of
>> contract, to prevent this negative affect that may occur by maturing
>> experimental API, a process update already suggested, which enables
>> aliasing without forcing it:
>> https://patches.dpdk.org/patch/65863/
>>
> 
> Personally, I am not convinced this is really needed.
> 
> Are there any users asking for this?

As it happens it is all breaking our abi regression test suite.
One of the things we do is to run the unit tests binary from v19.11 against the latest release. 
 
> Is there any other library where this is also applied, or is librte_meter the only library?

librte_meter is the only example AFAIK. 
But then we only have one example of needing symbol versioning also at the moment (Cryptodev).

This is going to happen with experimental symbols that have been around a while, 
that have become used in applications. It is a non-mandatory tool a maintainer can use
to preserve abi compatibility. 

> 
>> 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.
>>
>> Also following changes done to enabling aliasing:
>>
>> Created VERSION_SYMBOL_EXPERIMENTAL helper macro.
>>
>> Updated the 'check-symbols.sh' buildtool, 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)
>>
>> Enabled function versioning for meson build for the library.
>>
>> 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>
>>
>> v2:
>> * Commit log updated
>>
>> v3:
>> * added suggested comment to VERSION_SYMBOL_EXPERIMENTAL macro
>>
>> v4:
>> * update script name in commit log, remove empty line
>> ---
>>  buildtools/check-symbols.sh                   |  3 +-
>>  .../include/rte_function_versioning.h         |  9 +++
>>  lib/librte_meter/meson.build                  |  1 +
>>  lib/librte_meter/rte_meter.c                  | 59 ++++++++++++++++++-
>>  lib/librte_meter/rte_meter_version.map        |  8 +++
>>  5 files changed, 76 insertions(+), 4 deletions(-)
>>
>> diff --git a/buildtools/check-symbols.sh b/buildtools/check-symbols.sh
>> index 3df57c322c..e407553a34 100755
>> --- a/buildtools/check-symbols.sh
>> +++ b/buildtools/check-symbols.sh
>> @@ -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
>> diff --git a/lib/librte_eal/include/rte_function_versioning.h
>> b/lib/librte_eal/include/rte_function_versioning.h
>> index b9f862d295..f588f2643b 100644
>> --- a/lib/librte_eal/include/rte_function_versioning.h
>> +++ b/lib/librte_eal/include/rte_function_versioning.h
>> @@ -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))))
>> 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..c600b05064 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,8 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
>>  	return 0;
>>  }
>>
>> -int
>> -rte_meter_trtcm_rfc4115_profile_config(
>> +static int
>> +rte_meter_trtcm_rfc4115_profile_config_(
>>  	struct rte_meter_trtcm_rfc4115_profile *p,
>>  	struct rte_meter_trtcm_rfc4115_params *params)
>>  {
>> @@ -145,7 +146,35 @@ 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);
>> +
>> +static int
>> +rte_meter_trtcm_rfc4115_config_(
>>  	struct rte_meter_trtcm_rfc4115 *m,
>>  	struct rte_meter_trtcm_rfc4115_profile *p)
>>  {
>> @@ -160,3 +189,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);
> 
> To me, this is a significant amount of dead code that does not add any functionality and does not bring any added value to the library for any user. I am not a build system expert, but I would definitely prefer avoiding adding any C code to the library for this purpose, and just modify the map file, would this approach be possible?

Approach is exactly the same as the rest of symbol versioning. 
 
> Also, very important, is this C code to be added permanently or is it added just on a temporary basis? If temporary, when is it going to be removed?

It will be removed in the v21 (20.11 lts) release. 
When we officially rev the abi and start afresh. 

> 
>> 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
> 
> Regards,
> Cristian
> 

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Thomas Monjalon]

18/05/2020 08:29, Ray Kinsella:
> On 17/05/2020 20:52, Dumitrescu, Cristian wrote:
> > 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.
> >>
> >> Since experimental APIs can change or go away without notice as part of
> >> contract, to prevent this negative affect that may occur by maturing
> >> experimental API, a process update already suggested, which enables
> >> aliasing without forcing it:
> >> https://patches.dpdk.org/patch/65863/
> >>
> > 
> > Personally, I am not convinced this is really needed.
> > 
> > Are there any users asking for this?
> 
> As it happens it is all breaking our abi regression test suite.
> One of the things we do is to run the unit tests binary from v19.11 against the latest release. 
>  
> > Is there any other library where this is also applied, or is librte_meter the only library?
> 
> librte_meter is the only example AFAIK. 
> But then we only have one example of needing symbol versioning also at the moment (Cryptodev).
> 
> This is going to happen with experimental symbols that have been around a while, 
> that have become used in applications. It is a non-mandatory tool a maintainer can use
> to preserve abi compatibility.

If you want to maintain ABI compatibility of experimental symbols,
it IS a mandatory tool.
You cannot enforce your "ABI regression test suite" and at the same time
say it is "non-mandatory".

The real question here is to know whether we want to maintain compatibility
of experimental symbols. We said no. Then we said we can.
The main concern is the message clarity in my opinion.

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 18/05/2020 10:22, Thomas Monjalon wrote:
> 18/05/2020 08:29, Ray Kinsella:
>> On 17/05/2020 20:52, Dumitrescu, Cristian wrote:
>>> 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.
>>>>
>>>> Since experimental APIs can change or go away without notice as part of
>>>> contract, to prevent this negative affect that may occur by maturing
>>>> experimental API, a process update already suggested, which enables
>>>> aliasing without forcing it:
>>>> https://patches.dpdk.org/patch/65863/
>>>>
>>>
>>> Personally, I am not convinced this is really needed.
>>>
>>> Are there any users asking for this?
>>
>> As it happens it is all breaking our abi regression test suite.
>> One of the things we do is to run the unit tests binary from v19.11 against the latest release. 
>>  
>>> Is there any other library where this is also applied, or is librte_meter the only library?
>>
>> librte_meter is the only example AFAIK. 
>> But then we only have one example of needing symbol versioning also at the moment (Cryptodev).
>>
>> This is going to happen with experimental symbols that have been around a while, 
>> that have become used in applications. It is a non-mandatory tool a maintainer can use
>> to preserve abi compatibility.
> 
> If you want to maintain ABI compatibility of experimental symbols,
> it IS a mandatory tool.
> You cannot enforce your "ABI regression test suite" and at the same time
> say it is "non-mandatory".> 
> The real question here is to know whether we want to maintain compatibility
> of experimental symbols. We said no. Then we said we can.
> The main concern is the message clarity in my opinion.
> 

There is complete clarity, there is no obligation. 
Our lack of obligation around experimental, is upfront in the policy is upfront in the policy.

"Libraries or APIs marked as experimental may change without constraint, as they are not considered part of an ABI version. Experimental libraries have the major ABI version 0."

Later we give the _option_ without obligation to add an alias to experimental.pls see the v6.

+   - 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.

So it is something a Maintainer, _may_ choose to do.
I use the word, "may" not "will" as there is no obligation's associated with experimental.

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Thomas Monjalon]

18/05/2020 11:30, Ray Kinsella:
> On 18/05/2020 10:22, Thomas Monjalon wrote:
> > 18/05/2020 08:29, Ray Kinsella:
> >> On 17/05/2020 20:52, Dumitrescu, Cristian wrote:
> >>> 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.
> >>>>
> >>>> Since experimental APIs can change or go away without notice as part of
> >>>> contract, to prevent this negative affect that may occur by maturing
> >>>> experimental API, a process update already suggested, which enables
> >>>> aliasing without forcing it:
> >>>> https://patches.dpdk.org/patch/65863/
> >>>>
> >>>
> >>> Personally, I am not convinced this is really needed.
> >>>
> >>> Are there any users asking for this?
> >>
> >> As it happens it is all breaking our abi regression test suite.
> >> One of the things we do is to run the unit tests binary from v19.11 against the latest release. 
> >>  
> >>> Is there any other library where this is also applied, or is librte_meter the only library?
> >>
> >> librte_meter is the only example AFAIK. 
> >> But then we only have one example of needing symbol versioning also at the moment (Cryptodev).
> >>
> >> This is going to happen with experimental symbols that have been around a while, 
> >> that have become used in applications. It is a non-mandatory tool a maintainer can use
> >> to preserve abi compatibility.
> > 
> > If you want to maintain ABI compatibility of experimental symbols,
> > it IS a mandatory tool.
> > You cannot enforce your "ABI regression test suite" and at the same time
> > say it is "non-mandatory".
> > 
> > The real question here is to know whether we want to maintain compatibility
> > of experimental symbols. We said no. Then we said we can.
> > The main concern is the message clarity in my opinion.
> > 
> 
> There is complete clarity, there is no obligation. 
> Our lack of obligation around experimental, is upfront in the policy is upfront in the policy.
> 
> "Libraries or APIs marked as experimental may change without constraint, as they are not considered part of an ABI version. Experimental libraries have the major ABI version 0."
> 
> Later we give the _option_ without obligation to add an alias to experimental.pls see the v6.
> 
> +   - 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.
> 
> So it is something a Maintainer, _may_ choose to do.
> I use the word, "may" not "will" as there is no obligation's associated with experimental.


OK Ray, this is my understanding as well.

The only difficult part to understand is when claiming
"it is all breaking our abi regression test suite"
to justify the choice.
As the maintainer (Cristian) says he does not like this change,
it means the regression test suite should skip this case, right?

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Dumitrescu, Cristian]

> -----Original Message-----
> From: Thomas Monjalon <thomas@monjalon.net>
> Sent: Monday, May 18, 2020 11:46 AM
> To: Yigit, Ferruh <ferruh.yigit@intel.com>; Ray Kinsella <mdr@ashroe.eu>;
> Dumitrescu, Cristian <cristian.dumitrescu@intel.com>
> Cc: Neil Horman <nhorman@tuxdriver.com>; Eelco Chaudron
> <echaudro@redhat.com>; dev@dpdk.org; 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: Re: [PATCH v4] meter: provide experimental alias of API for old apps
> 
> 18/05/2020 11:30, Ray Kinsella:
> > On 18/05/2020 10:22, Thomas Monjalon wrote:
> > > 18/05/2020 08:29, Ray Kinsella:
> > >> On 17/05/2020 20:52, Dumitrescu, Cristian wrote:
> > >>> 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.
> > >>>>
> > >>>> Since experimental APIs can change or go away without notice as part
> of
> > >>>> contract, to prevent this negative affect that may occur by maturing
> > >>>> experimental API, a process update already suggested, which
> enables
> > >>>> aliasing without forcing it:
> > >>>> https://patches.dpdk.org/patch/65863/
> > >>>>
> > >>>
> > >>> Personally, I am not convinced this is really needed.
> > >>>
> > >>> Are there any users asking for this?
> > >>
> > >> As it happens it is all breaking our abi regression test suite.
> > >> One of the things we do is to run the unit tests binary from v19.11
> against the latest release.
> > >>
> > >>> Is there any other library where this is also applied, or is librte_meter
> the only library?
> > >>
> > >> librte_meter is the only example AFAIK.
> > >> But then we only have one example of needing symbol versioning also
> at the moment (Cryptodev).
> > >>
> > >> This is going to happen with experimental symbols that have been
> around a while,
> > >> that have become used in applications. It is a non-mandatory tool a
> maintainer can use
> > >> to preserve abi compatibility.
> > >
> > > If you want to maintain ABI compatibility of experimental symbols,
> > > it IS a mandatory tool.
> > > You cannot enforce your "ABI regression test suite" and at the same time
> > > say it is "non-mandatory".
> > >
> > > The real question here is to know whether we want to maintain
> compatibility
> > > of experimental symbols. We said no. Then we said we can.
> > > The main concern is the message clarity in my opinion.
> > >
> >
> > There is complete clarity, there is no obligation.
> > Our lack of obligation around experimental, is upfront in the policy is
> upfront in the policy.
> >
> > "Libraries or APIs marked as experimental may change without constraint,
> as they are not considered part of an ABI version. Experimental libraries have
> the major ABI version 0."
> >
> > Later we give the _option_ without obligation to add an alias to
> experimental.pls see the v6.
> >
> > +   - 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.
> >
> > So it is something a Maintainer, _may_ choose to do.
> > I use the word, "may" not "will" as there is no obligation's associated with
> experimental.
> 
> 
> OK Ray, this is my understanding as well.
> 
> The only difficult part to understand is when claiming
> "it is all breaking our abi regression test suite"
> to justify the choice.
> As the maintainer (Cristian) says he does not like this change,
> it means the regression test suite should skip this case, right?
> 

I am yet to be convinced of the value of this, but if some people think it is useful, I am willing to compromise. This is subject to this code being temporary code to be removed for 20.11 release, which Ray already confirmed.

Ray, a few more suggestions, are you OK with them?
1. Move this code to a separate file in the library (suggest rte_meter_abi_compat.c as the file name)
2. Clearly state in the patch description this is temporary code to be removed for 20.11 release.
3. Agree that you or Ferruh take the AR to send a patch prior to the 20.11 release to remove this code.

Thanks,
Cristian

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 18/05/2020 11:46, Thomas Monjalon wrote:
> 18/05/2020 11:30, Ray Kinsella:
>> On 18/05/2020 10:22, Thomas Monjalon wrote:
>>> 18/05/2020 08:29, Ray Kinsella:
>>>> On 17/05/2020 20:52, Dumitrescu, Cristian wrote:
>>>>> 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.
>>>>>>
>>>>>> Since experimental APIs can change or go away without notice as part of
>>>>>> contract, to prevent this negative affect that may occur by maturing
>>>>>> experimental API, a process update already suggested, which enables
>>>>>> aliasing without forcing it:
>>>>>> https://patches.dpdk.org/patch/65863/
>>>>>>
>>>>>
>>>>> Personally, I am not convinced this is really needed.
>>>>>
>>>>> Are there any users asking for this?
>>>>
>>>> As it happens it is all breaking our abi regression test suite.
>>>> One of the things we do is to run the unit tests binary from v19.11 against the latest release. 
>>>>  
>>>>> Is there any other library where this is also applied, or is librte_meter the only library?
>>>>
>>>> librte_meter is the only example AFAIK. 
>>>> But then we only have one example of needing symbol versioning also at the moment (Cryptodev).
>>>>
>>>> This is going to happen with experimental symbols that have been around a while, 
>>>> that have become used in applications. It is a non-mandatory tool a maintainer can use
>>>> to preserve abi compatibility.
>>>
>>> If you want to maintain ABI compatibility of experimental symbols,
>>> it IS a mandatory tool.
>>> You cannot enforce your "ABI regression test suite" and at the same time
>>> say it is "non-mandatory".
>>>
>>> The real question here is to know whether we want to maintain compatibility
>>> of experimental symbols. We said no. Then we said we can.
>>> The main concern is the message clarity in my opinion.
>>>
>>
>> There is complete clarity, there is no obligation. 
>> Our lack of obligation around experimental, is upfront in the policy is upfront in the policy.
>>
>> "Libraries or APIs marked as experimental may change without constraint, as they are not considered part of an ABI version. Experimental libraries have the major ABI version 0."
>>
>> Later we give the _option_ without obligation to add an alias to experimental.pls see the v6.
>>
>> +   - 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.
>>
>> So it is something a Maintainer, _may_ choose to do.
>> I use the word, "may" not "will" as there is no obligation's associated with experimental.
> 
> 
> OK Ray, this is my understanding as well.
> 
> The only difficult part to understand is when claiming
> "it is all breaking our abi regression test suite"
> to justify the choice.

Justification, is the same as any other consumer of DPDK saying you broke my APP.

> As the maintainer (Cristian) says he does not like this change,
> it means the regression test suite should skip this case, right?

So the regression test run the v19.11 Unit Test's against the v20.05 rc.
My thought was that would provide reasonably good coverage of the ABI to catch more subtly regression.
Those regressions that affect the behavior of the ABI (the contract), instead of ABI itself. 

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 18/05/2020 12:18, Dumitrescu, Cristian wrote:
> 
> 
>> -----Original Message-----
>> From: Thomas Monjalon <thomas@monjalon.net>
>> Sent: Monday, May 18, 2020 11:46 AM
>> To: Yigit, Ferruh <ferruh.yigit@intel.com>; Ray Kinsella <mdr@ashroe.eu>;
>> Dumitrescu, Cristian <cristian.dumitrescu@intel.com>
>> Cc: Neil Horman <nhorman@tuxdriver.com>; Eelco Chaudron
>> <echaudro@redhat.com>; dev@dpdk.org; 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: Re: [PATCH v4] meter: provide experimental alias of API for old apps
>>
>> 18/05/2020 11:30, Ray Kinsella:
>>> On 18/05/2020 10:22, Thomas Monjalon wrote:
>>>> 18/05/2020 08:29, Ray Kinsella:
>>>>> On 17/05/2020 20:52, Dumitrescu, Cristian wrote:
>>>>>> 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.
>>>>>>>
>>>>>>> Since experimental APIs can change or go away without notice as part
>> of
>>>>>>> contract, to prevent this negative affect that may occur by maturing
>>>>>>> experimental API, a process update already suggested, which
>> enables
>>>>>>> aliasing without forcing it:
>>>>>>> https://patches.dpdk.org/patch/65863/
>>>>>>>
>>>>>>
>>>>>> Personally, I am not convinced this is really needed.
>>>>>>
>>>>>> Are there any users asking for this?
>>>>>
>>>>> As it happens it is all breaking our abi regression test suite.
>>>>> One of the things we do is to run the unit tests binary from v19.11
>> against the latest release.
>>>>>
>>>>>> Is there any other library where this is also applied, or is librte_meter
>> the only library?
>>>>>
>>>>> librte_meter is the only example AFAIK.
>>>>> But then we only have one example of needing symbol versioning also
>> at the moment (Cryptodev).
>>>>>
>>>>> This is going to happen with experimental symbols that have been
>> around a while,
>>>>> that have become used in applications. It is a non-mandatory tool a
>> maintainer can use
>>>>> to preserve abi compatibility.
>>>>
>>>> If you want to maintain ABI compatibility of experimental symbols,
>>>> it IS a mandatory tool.
>>>> You cannot enforce your "ABI regression test suite" and at the same time
>>>> say it is "non-mandatory".
>>>>
>>>> The real question here is to know whether we want to maintain
>> compatibility
>>>> of experimental symbols. We said no. Then we said we can.
>>>> The main concern is the message clarity in my opinion.
>>>>
>>>
>>> There is complete clarity, there is no obligation.
>>> Our lack of obligation around experimental, is upfront in the policy is
>> upfront in the policy.
>>>
>>> "Libraries or APIs marked as experimental may change without constraint,
>> as they are not considered part of an ABI version. Experimental libraries have
>> the major ABI version 0."
>>>
>>> Later we give the _option_ without obligation to add an alias to
>> experimental.pls see the v6.
>>>
>>> +   - 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.
>>>
>>> So it is something a Maintainer, _may_ choose to do.
>>> I use the word, "may" not "will" as there is no obligation's associated with
>> experimental.
>>
>>
>> OK Ray, this is my understanding as well.
>>
>> The only difficult part to understand is when claiming
>> "it is all breaking our abi regression test suite"
>> to justify the choice.
>> As the maintainer (Cristian) says he does not like this change,
>> it means the regression test suite should skip this case, right?
>>
> 
> I am yet to be convinced of the value of this, but if some people think it is useful, I am willing to compromise. This is subject to this code being temporary code to be removed for 20.11 release, which Ray already confirmed.
> 
> Ray, a few more suggestions, are you OK with them?
> 1. Move this code to a separate file in the library (suggest rte_meter_abi_compat.c as the file name)
> 2. Clearly state in the patch description this is temporary code to be removed for 20.11 release.
> 3. Agree that you or Ferruh take the AR to send a patch prior to the 20.11 release to remove this code.
> 
> Thanks,
> Cristian

Hi Cristain - I am good with all of the above.

Ray K

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Thomas Monjalon]

18/05/2020 13:48, Ray Kinsella:
> On 18/05/2020 11:46, Thomas Monjalon wrote:
> > 18/05/2020 11:30, Ray Kinsella:
> >> On 18/05/2020 10:22, Thomas Monjalon wrote:
> >>> 18/05/2020 08:29, Ray Kinsella:
> >>>> On 17/05/2020 20:52, Dumitrescu, Cristian wrote:
> >>>>> 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.
> >>>>>>
> >>>>>> Since experimental APIs can change or go away without notice as part of
> >>>>>> contract, to prevent this negative affect that may occur by maturing
> >>>>>> experimental API, a process update already suggested, which enables
> >>>>>> aliasing without forcing it:
> >>>>>> https://patches.dpdk.org/patch/65863/
> >>>>>>
> >>>>>
> >>>>> Personally, I am not convinced this is really needed.
> >>>>>
> >>>>> Are there any users asking for this?
> >>>>
> >>>> As it happens it is all breaking our abi regression test suite.
> >>>> One of the things we do is to run the unit tests binary from v19.11 against the latest release. 
> >>>>  
> >>>>> Is there any other library where this is also applied, or is librte_meter the only library?
> >>>>
> >>>> librte_meter is the only example AFAIK. 
> >>>> But then we only have one example of needing symbol versioning also at the moment (Cryptodev).
> >>>>
> >>>> This is going to happen with experimental symbols that have been around a while, 
> >>>> that have become used in applications. It is a non-mandatory tool a maintainer can use
> >>>> to preserve abi compatibility.
> >>>
> >>> If you want to maintain ABI compatibility of experimental symbols,
> >>> it IS a mandatory tool.
> >>> You cannot enforce your "ABI regression test suite" and at the same time
> >>> say it is "non-mandatory".
> >>>
> >>> The real question here is to know whether we want to maintain compatibility
> >>> of experimental symbols. We said no. Then we said we can.
> >>> The main concern is the message clarity in my opinion.
> >>>
> >>
> >> There is complete clarity, there is no obligation. 
> >> Our lack of obligation around experimental, is upfront in the policy is upfront in the policy.
> >>
> >> "Libraries or APIs marked as experimental may change without constraint, as they are not considered part of an ABI version. Experimental libraries have the major ABI version 0."
> >>
> >> Later we give the _option_ without obligation to add an alias to experimental.pls see the v6.
> >>
> >> +   - 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.
> >>
> >> So it is something a Maintainer, _may_ choose to do.
> >> I use the word, "may" not "will" as there is no obligation's associated with experimental.
> > 
> > 
> > OK Ray, this is my understanding as well.
> > 
> > The only difficult part to understand is when claiming
> > "it is all breaking our abi regression test suite"
> > to justify the choice.
> 
> Justification, is the same as any other consumer of DPDK saying you broke my APP.
> 
> > As the maintainer (Cristian) says he does not like this change,
> > it means the regression test suite should skip this case, right?
> 
> So the regression test run the v19.11 Unit Test's against the v20.05 rc.
> My thought was that would provide reasonably good coverage of the ABI to catch more subtly regression.
> Those regressions that affect the behavior of the ABI (the contract), instead of ABI itself. 

I understand the goal.
And I think, because of this goal, you will try to maintain ABI compat
of *ALL* experimental symbols maturing as stable symbol.

Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps

[Ray Kinsella]

On 18/05/2020 13:13, Thomas Monjalon wrote:
> And I think, because of this goal, you will try to maintain ABI compat
> of *ALL* experimental symbols maturing as stable symbol.

I think that is a fair point, what we will ultimately need is a way to filter 
TCs that touch experimental from the Unit Test framework. 

That doesn't exist for v19.11, nor can we respectively invent it.
We should look at that for v20.11 to avoid supporting all "experimental symbols". 

As a better useful solution.
That said - I think having an alias-to-experimental tool in our box, 
stands on its own merit.

Ray K

Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps

[Thomas Monjalon]

16/05/2020 13:53, Neil Horman:
> On Fri, May 15, 2020 at 04:01:53PM +0100, Ray Kinsella wrote:
> > From: Ferruh Yigit <ferruh.yigit@intel.com>
> > 
> > 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' buildtool, 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>

Applied with few typos fixed, thanks.

Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps

[Ferruh Yigit]

On 5/18/2020 6:18 PM, Thomas Monjalon wrote:
> 16/05/2020 13:53, Neil Horman:
>> On Fri, May 15, 2020 at 04:01:53PM +0100, Ray Kinsella wrote:
>>> From: Ferruh Yigit <ferruh.yigit@intel.com>
>>>
>>> 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' buildtool, 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>
> 
> Applied with few typos fixed, thanks.
> 

Is a new version of the meter library required?

Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps

[Thomas Monjalon]

18/05/2020 19:34, Ferruh Yigit:
> On 5/18/2020 6:18 PM, Thomas Monjalon wrote:
> > 16/05/2020 13:53, Neil Horman:
> >> On Fri, May 15, 2020 at 04:01:53PM +0100, Ray Kinsella wrote:
> >>> From: Ferruh Yigit <ferruh.yigit@intel.com>
> >>>
> >>> 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' buildtool, 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>
> > 
> > Applied with few typos fixed, thanks.
> > 
> 
> Is a new version of the meter library required?

I think yes, Cristian is asking for some changes.

[dpdk-dev] [PATCH v5] meter: provide experimental alias of API for old apps

[Ferruh Yigit]

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
---
 lib/librte_meter/Makefile              |  2 +-
 lib/librte_meter/meson.build           |  3 +-
 lib/librte_meter/rte_meter.c           |  5 +--
 lib/librte_meter/rte_meter_compat.c    | 47 ++++++++++++++++++++++++++
 lib/librte_meter/rte_meter_compat.h    | 26 ++++++++++++++
 lib/librte_meter/rte_meter_version.map |  7 ++++
 6 files changed, 86 insertions(+), 4 deletions(-)
 create mode 100644 lib/librte_meter/rte_meter_compat.c
 create mode 100644 lib/librte_meter/rte_meter_compat.h

diff --git a/lib/librte_meter/Makefile b/lib/librte_meter/Makefile
index 48366e82b0..e2f59fee7c 100644
--- a/lib/librte_meter/Makefile
+++ b/lib/librte_meter/Makefile
@@ -19,7 +19,7 @@ EXPORT_MAP := rte_meter_version.map
 #
 # all source are stored in SRCS-y
 #
-SRCS-$(CONFIG_RTE_LIBRTE_METER) := rte_meter.c
+SRCS-$(CONFIG_RTE_LIBRTE_METER) := rte_meter.c rte_meter_compat.c
 
 # install includes
 SYMLINK-$(CONFIG_RTE_LIBRTE_METER)-include := rte_meter.h
diff --git a/lib/librte_meter/meson.build b/lib/librte_meter/meson.build
index 646fd4d43f..fdc97dc4c9 100644
--- a/lib/librte_meter/meson.build
+++ b/lib/librte_meter/meson.build
@@ -1,5 +1,6 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright(c) 2017 Intel Corporation
 
-sources = files('rte_meter.c')
+sources = files('rte_meter.c', 'rte_meter_compat.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..b5378f615e 100644
--- a/lib/librte_meter/rte_meter.c
+++ b/lib/librte_meter/rte_meter.c
@@ -11,6 +11,7 @@
 #include <rte_cycles.h>
 
 #include "rte_meter.h"
+#include "rte_meter_compat.h"
 
 #ifndef RTE_METER_TB_PERIOD_MIN
 #define RTE_METER_TB_PERIOD_MIN      100
@@ -120,7 +121,7 @@ rte_meter_trtcm_config(struct rte_meter_trtcm *m,
 }
 
 int
-rte_meter_trtcm_rfc4115_profile_config(
+rte_meter_trtcm_rfc4115_profile_config_(
 	struct rte_meter_trtcm_rfc4115_profile *p,
 	struct rte_meter_trtcm_rfc4115_params *params)
 {
@@ -145,7 +146,7 @@ rte_meter_trtcm_rfc4115_profile_config(
 }
 
 int
-rte_meter_trtcm_rfc4115_config(
+rte_meter_trtcm_rfc4115_config_(
 	struct rte_meter_trtcm_rfc4115 *m,
 	struct rte_meter_trtcm_rfc4115_profile *p)
 {
diff --git a/lib/librte_meter/rte_meter_compat.c b/lib/librte_meter/rte_meter_compat.c
new file mode 100644
index 0000000000..ab04b9c244
--- /dev/null
+++ b/lib/librte_meter/rte_meter_compat.c
@@ -0,0 +1,47 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2020 Intel Corporation
+ */
+
+#include <rte_function_versioning.h>
+
+#include "rte_meter.h"
+#include "rte_meter_compat.h"
+
+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)
+{
+	return rte_meter_trtcm_rfc4115_profile_config_(p, params);
+}
+VERSION_SYMBOL_EXPERIMENTAL(rte_meter_trtcm_rfc4115_profile_config, _e);
+
+
+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)
+{
+	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_compat.h b/lib/librte_meter/rte_meter_compat.h
new file mode 100644
index 0000000000..63c282b015
--- /dev/null
+++ b/lib/librte_meter/rte_meter_compat.h
@@ -0,0 +1,26 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2020 Intel Corporation
+ */
+
+int
+rte_meter_trtcm_rfc4115_profile_config_(
+	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);
+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_config_s(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);
+int
+rte_meter_trtcm_rfc4115_config_(
+	struct rte_meter_trtcm_rfc4115 *m,
+	struct rte_meter_trtcm_rfc4115_profile *p);
diff --git a/lib/librte_meter/rte_meter_version.map b/lib/librte_meter/rte_meter_version.map
index 2c7dadbcac..3fef20366a 100644
--- a/lib/librte_meter/rte_meter_version.map
+++ b/lib/librte_meter/rte_meter_version.map
@@ -21,3 +21,10 @@ DPDK_21 {
 	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

Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps

[Ferruh Yigit]

On 5/18/2020 6:51 PM, Thomas Monjalon wrote:
> 18/05/2020 19:34, Ferruh Yigit:
>> On 5/18/2020 6:18 PM, Thomas Monjalon wrote:
>>> 16/05/2020 13:53, Neil Horman:
>>>> On Fri, May 15, 2020 at 04:01:53PM +0100, Ray Kinsella wrote:
>>>>> From: Ferruh Yigit <ferruh.yigit@intel.com>
>>>>>
>>>>> 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' buildtool, 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>
>>>
>>> Applied with few typos fixed, thanks.
>>>
>>
>> Is a new version of the meter library required?
> 
> I think yes, Cristian is asking for some changes.
> 

done: https://patches.dpdk.org/patch/70399/

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

[Ferruh Yigit]

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;
+};
-- 
2.25.4

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

[Dumitrescu, Cristian]

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

Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps

[Ray Kinsella]

On 18/05/2020 19:32, Ferruh Yigit wrote:
> On 5/18/2020 6:51 PM, Thomas Monjalon wrote:
>> 18/05/2020 19:34, Ferruh Yigit:
>>> On 5/18/2020 6:18 PM, Thomas Monjalon wrote:
>>>> 16/05/2020 13:53, Neil Horman:
>>>>> On Fri, May 15, 2020 at 04:01:53PM +0100, Ray Kinsella wrote:
>>>>>> From: Ferruh Yigit <ferruh.yigit@intel.com>
>>>>>>
>>>>>> 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' buildtool, 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>
>>>>
>>>> Applied with few typos fixed, thanks.
>>>>
>>>
>>> Is a new version of the meter library required?
>>
>> I think yes, Cristian is asking for some changes.
>>
> 
> done: https://patches.dpdk.org/patch/70399/
> 

Thanks Ferruh.

Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps

[Ray Kinsella]

On 18/05/2020 18:18, Thomas Monjalon wrote:
> 16/05/2020 13:53, Neil Horman:
>> On Fri, May 15, 2020 at 04:01:53PM +0100, Ray Kinsella wrote:
>>> From: Ferruh Yigit <ferruh.yigit@intel.com>
>>>
>>> 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' buildtool, 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>
> 
> Applied with few typos fixed, thanks.
> 
> 
> 

Thanks Thomas. 

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

[Ray Kinsella]

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>

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

[Thomas Monjalon]

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.