* Re: [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps
2020-05-13 12:11 ` [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps Ferruh Yigit
@ 2020-05-13 16:30 ` Thomas Monjalon
2020-05-13 17:37 ` Ferruh Yigit
2020-05-13 18:05 ` [dpdk-dev] [PATCH v2] " Ferruh Yigit
` (4 subsequent siblings)
5 siblings, 1 reply; 71+ messages in thread
From: Thomas Monjalon @ 2020-05-13 16:30 UTC (permalink / raw)
To: Ferruh Yigit
Cc: Ray Kinsella, Neil Horman, Cristian Dumitrescu, Eelco Chaudron,
dev, David Marchand, Luca Boccassi, Bruce Richardson, Ian Stokes,
Andrzej Ostruszka
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;
> +};
>
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps
2020-05-13 16:30 ` Thomas Monjalon
@ 2020-05-13 17:37 ` Ferruh Yigit
0 siblings, 0 replies; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-13 17:37 UTC (permalink / raw)
To: Thomas Monjalon
Cc: Ray Kinsella, Neil Horman, Cristian Dumitrescu, Eelco Chaudron,
dev, David Marchand, Luca Boccassi, Bruce Richardson, Ian Stokes,
Andrzej Ostruszka
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;
>> +};
>>
>
>
>
>
>
^ permalink raw reply [flat|nested] 71+ messages in thread
* [dpdk-dev] [PATCH v2] meter: provide experimental alias of API for old apps
2020-05-13 12:11 ` [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps Ferruh Yigit
2020-05-13 16:30 ` Thomas Monjalon
@ 2020-05-13 18:05 ` Ferruh Yigit
2020-05-14 8:44 ` Ray Kinsella
2020-05-14 11:52 ` [dpdk-dev] [PATCH v3] " Ferruh Yigit
` (3 subsequent siblings)
5 siblings, 1 reply; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-13 18:05 UTC (permalink / raw)
To: Ray Kinsella, Neil Horman, Cristian Dumitrescu, Eelco Chaudron
Cc: dev, Ferruh Yigit, Thomas Monjalon, David Marchand, stable,
Luca Boccassi, Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v2] meter: provide experimental alias of API for old apps
2020-05-13 18:05 ` [dpdk-dev] [PATCH v2] " Ferruh Yigit
@ 2020-05-14 8:44 ` Ray Kinsella
2020-05-14 11:53 ` [dpdk-dev] [dpdk-stable] " Ferruh Yigit
0 siblings, 1 reply; 71+ messages in thread
From: Ray Kinsella @ 2020-05-14 8:44 UTC (permalink / raw)
To: Ferruh Yigit, Neil Horman, Cristian Dumitrescu, Eelco Chaudron
Cc: dev, Thomas Monjalon, David Marchand, stable, Luca Boccassi,
Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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;
> +};
>
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [dpdk-stable] [PATCH v2] meter: provide experimental alias of API for old apps
2020-05-14 8:44 ` Ray Kinsella
@ 2020-05-14 11:53 ` Ferruh Yigit
0 siblings, 0 replies; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-14 11:53 UTC (permalink / raw)
To: Ray Kinsella, Neil Horman, Cristian Dumitrescu, Eelco Chaudron
Cc: dev, Thomas Monjalon, David Marchand, stable, Luca Boccassi,
Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread
* [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps
2020-05-13 12:11 ` [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps Ferruh Yigit
2020-05-13 16:30 ` Thomas Monjalon
2020-05-13 18:05 ` [dpdk-dev] [PATCH v2] " Ferruh Yigit
@ 2020-05-14 11:52 ` Ferruh Yigit
2020-05-14 15:10 ` Ray Kinsella
2020-05-14 15:32 ` David Marchand
2020-05-14 16:11 ` [dpdk-dev] [PATCH v4] " Ferruh Yigit
` (2 subsequent siblings)
5 siblings, 2 replies; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-14 11:52 UTC (permalink / raw)
To: Ray Kinsella, Neil Horman, Cristian Dumitrescu, Eelco Chaudron
Cc: dev, Ferruh Yigit, Thomas Monjalon, David Marchand, stable,
Luca Boccassi, Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps
2020-05-14 11:52 ` [dpdk-dev] [PATCH v3] " Ferruh Yigit
@ 2020-05-14 15:10 ` Ray Kinsella
2020-05-14 15:32 ` David Marchand
1 sibling, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-14 15:10 UTC (permalink / raw)
To: Ferruh Yigit, Neil Horman, Cristian Dumitrescu, Eelco Chaudron
Cc: dev, Thomas Monjalon, David Marchand, stable, Luca Boccassi,
Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps
2020-05-14 11:52 ` [dpdk-dev] [PATCH v3] " Ferruh Yigit
2020-05-14 15:10 ` Ray Kinsella
@ 2020-05-14 15:32 ` David Marchand
2020-05-14 15:56 ` Ray Kinsella
2020-05-14 16:07 ` Ferruh Yigit
1 sibling, 2 replies; 71+ messages in thread
From: David Marchand @ 2020-05-14 15:32 UTC (permalink / raw)
To: Ferruh Yigit, Ray Kinsella
Cc: Neil Horman, Cristian Dumitrescu, Eelco Chaudron, dev,
Thomas Monjalon, dpdk stable, Luca Boccassi, Bruce Richardson,
Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps
2020-05-14 15:32 ` David Marchand
@ 2020-05-14 15:56 ` Ray Kinsella
2020-05-14 16:07 ` Ferruh Yigit
1 sibling, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-14 15:56 UTC (permalink / raw)
To: David Marchand, Ferruh Yigit
Cc: Neil Horman, Cristian Dumitrescu, Eelco Chaudron, dev,
Thomas Monjalon, dpdk stable, Luca Boccassi, Bruce Richardson,
Ian Stokes, Andrzej Ostruszka
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
>
>
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps
2020-05-14 15:32 ` David Marchand
2020-05-14 15:56 ` Ray Kinsella
@ 2020-05-14 16:07 ` Ferruh Yigit
2020-05-14 16:30 ` David Marchand
1 sibling, 1 reply; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-14 16:07 UTC (permalink / raw)
To: David Marchand, Ray Kinsella
Cc: Neil Horman, Cristian Dumitrescu, Eelco Chaudron, dev,
Thomas Monjalon, dpdk stable, Luca Boccassi, Bruce Richardson,
Ian Stokes, Andrzej Ostruszka
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
>
>
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v3] meter: provide experimental alias of API for old apps
2020-05-14 16:07 ` Ferruh Yigit
@ 2020-05-14 16:30 ` David Marchand
0 siblings, 0 replies; 71+ messages in thread
From: David Marchand @ 2020-05-14 16:30 UTC (permalink / raw)
To: Ferruh Yigit
Cc: Ray Kinsella, Neil Horman, Cristian Dumitrescu, Eelco Chaudron,
dev, Thomas Monjalon, dpdk stable, Luca Boccassi,
Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread
* [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-13 12:11 ` [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps Ferruh Yigit
` (2 preceding siblings ...)
2020-05-14 11:52 ` [dpdk-dev] [PATCH v3] " Ferruh Yigit
@ 2020-05-14 16:11 ` Ferruh Yigit
2020-05-15 13:31 ` Thomas Monjalon
` (3 more replies)
2020-05-18 18:30 ` [dpdk-dev] [PATCH v5] " Ferruh Yigit
2020-05-19 12:16 ` [dpdk-dev] [PATCH v6] " Ferruh Yigit
5 siblings, 4 replies; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-14 16:11 UTC (permalink / raw)
To: Ray Kinsella, Neil Horman, Cristian Dumitrescu, Eelco Chaudron
Cc: dev, Ferruh Yigit, Thomas Monjalon, David Marchand, stable,
Luca Boccassi, Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-14 16:11 ` [dpdk-dev] [PATCH v4] " Ferruh Yigit
@ 2020-05-15 13:31 ` Thomas Monjalon
2020-05-15 14:41 ` Ray Kinsella
2020-05-15 15:03 ` Ray Kinsella
2020-05-15 14:36 ` [dpdk-dev] [PATCH v5] abi: " Ray Kinsella
` (2 subsequent siblings)
3 siblings, 2 replies; 71+ messages in thread
From: Thomas Monjalon @ 2020-05-15 13:31 UTC (permalink / raw)
To: Ray Kinsella, Ferruh Yigit
Cc: Neil Horman, Cristian Dumitrescu, Eelco Chaudron, dev,
David Marchand, stable, Luca Boccassi, Bruce Richardson,
Ian Stokes, Andrzej Ostruszka
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?
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-15 13:31 ` Thomas Monjalon
@ 2020-05-15 14:41 ` Ray Kinsella
2020-05-15 15:03 ` Ray Kinsella
1 sibling, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-15 14:41 UTC (permalink / raw)
To: Thomas Monjalon, Ferruh Yigit
Cc: Neil Horman, Cristian Dumitrescu, Eelco Chaudron, dev,
David Marchand, stable, Luca Boccassi, Bruce Richardson,
Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-15 13:31 ` Thomas Monjalon
2020-05-15 14:41 ` Ray Kinsella
@ 2020-05-15 15:03 ` Ray Kinsella
1 sibling, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-15 15:03 UTC (permalink / raw)
To: Thomas Monjalon, Ferruh Yigit
Cc: Neil Horman, Cristian Dumitrescu, Eelco Chaudron, dev,
David Marchand, stable, Luca Boccassi, Bruce Richardson,
Ian Stokes, Andrzej Ostruszka
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* [dpdk-dev] [PATCH v5] abi: provide experimental alias of API for old apps
2020-05-14 16:11 ` [dpdk-dev] [PATCH v4] " Ferruh Yigit
2020-05-15 13:31 ` Thomas Monjalon
@ 2020-05-15 14:36 ` Ray Kinsella
2020-05-15 15:01 ` [dpdk-dev] [PATCH v6] " Ray Kinsella
2020-05-17 19:52 ` [dpdk-dev] [PATCH v4] meter: " Dumitrescu, Cristian
3 siblings, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-15 14:36 UTC (permalink / raw)
To: dev
Cc: Ferruh Yigit, Ray Kinsella, Neil Horman, Thomas Monjalon,
Luca Boccassi, David Marchand, Bruce Richardson, Ian Stokes,
Eelco Chaudron, Andrzej Ostruszka, Kevin Traynor, John McNamara,
Marko Kovacevic, Cristian Dumitrescu
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
^ permalink raw reply [flat|nested] 71+ messages in thread* [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps
2020-05-14 16:11 ` [dpdk-dev] [PATCH v4] " Ferruh Yigit
2020-05-15 13:31 ` Thomas Monjalon
2020-05-15 14:36 ` [dpdk-dev] [PATCH v5] abi: " Ray Kinsella
@ 2020-05-15 15:01 ` Ray Kinsella
2020-05-16 11:53 ` Neil Horman
2020-05-17 19:52 ` [dpdk-dev] [PATCH v4] meter: " Dumitrescu, Cristian
3 siblings, 1 reply; 71+ messages in thread
From: Ray Kinsella @ 2020-05-15 15:01 UTC (permalink / raw)
To: dev
Cc: Ferruh Yigit, Ray Kinsella, Neil Horman, Thomas Monjalon,
Luca Boccassi, David Marchand, Bruce Richardson, Ian Stokes,
Eelco Chaudron, Andrzej Ostruszka, Kevin Traynor, John McNamara,
Marko Kovacevic, Cristian Dumitrescu
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps
2020-05-15 15:01 ` [dpdk-dev] [PATCH v6] " Ray Kinsella
@ 2020-05-16 11:53 ` Neil Horman
2020-05-18 17:18 ` Thomas Monjalon
0 siblings, 1 reply; 71+ messages in thread
From: Neil Horman @ 2020-05-16 11:53 UTC (permalink / raw)
To: Ray Kinsella
Cc: dev, Ferruh Yigit, Thomas Monjalon, Luca Boccassi,
David Marchand, Bruce Richardson, Ian Stokes, Eelco Chaudron,
Andrzej Ostruszka, Kevin Traynor, John McNamara, Marko Kovacevic,
Cristian Dumitrescu
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>
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps
2020-05-16 11:53 ` Neil Horman
@ 2020-05-18 17:18 ` Thomas Monjalon
2020-05-18 17:34 ` Ferruh Yigit
2020-05-19 14:14 ` Ray Kinsella
0 siblings, 2 replies; 71+ messages in thread
From: Thomas Monjalon @ 2020-05-18 17:18 UTC (permalink / raw)
To: Ray Kinsella
Cc: dev, Ferruh Yigit, Luca Boccassi, David Marchand,
Bruce Richardson, Ian Stokes, Eelco Chaudron, Andrzej Ostruszka,
Kevin Traynor, John McNamara, Marko Kovacevic,
Cristian Dumitrescu, Neil Horman
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps
2020-05-18 17:18 ` Thomas Monjalon
@ 2020-05-18 17:34 ` Ferruh Yigit
2020-05-18 17:51 ` Thomas Monjalon
2020-05-19 14:14 ` Ray Kinsella
1 sibling, 1 reply; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-18 17:34 UTC (permalink / raw)
To: Thomas Monjalon, Ray Kinsella
Cc: dev, Luca Boccassi, David Marchand, Bruce Richardson, Ian Stokes,
Eelco Chaudron, Andrzej Ostruszka, Kevin Traynor, John McNamara,
Marko Kovacevic, Cristian Dumitrescu, Neil Horman
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?
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps
2020-05-18 17:34 ` Ferruh Yigit
@ 2020-05-18 17:51 ` Thomas Monjalon
2020-05-18 18:32 ` Ferruh Yigit
0 siblings, 1 reply; 71+ messages in thread
From: Thomas Monjalon @ 2020-05-18 17:51 UTC (permalink / raw)
To: Ray Kinsella, Ferruh Yigit
Cc: dev, Luca Boccassi, David Marchand, Bruce Richardson, Ian Stokes,
Eelco Chaudron, Andrzej Ostruszka, Kevin Traynor, John McNamara,
Marko Kovacevic, Cristian Dumitrescu, Neil Horman
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps
2020-05-18 17:51 ` Thomas Monjalon
@ 2020-05-18 18:32 ` Ferruh Yigit
2020-05-19 14:13 ` Ray Kinsella
0 siblings, 1 reply; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-18 18:32 UTC (permalink / raw)
To: Thomas Monjalon, Ray Kinsella
Cc: dev, Luca Boccassi, David Marchand, Bruce Richardson, Ian Stokes,
Eelco Chaudron, Andrzej Ostruszka, Kevin Traynor, John McNamara,
Marko Kovacevic, Cristian Dumitrescu, Neil Horman
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/
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps
2020-05-18 18:32 ` Ferruh Yigit
@ 2020-05-19 14:13 ` Ray Kinsella
0 siblings, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-19 14:13 UTC (permalink / raw)
To: Ferruh Yigit, Thomas Monjalon
Cc: dev, Luca Boccassi, David Marchand, Bruce Richardson, Ian Stokes,
Eelco Chaudron, Andrzej Ostruszka, Kevin Traynor, John McNamara,
Marko Kovacevic, Cristian Dumitrescu, Neil Horman
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v6] abi: provide experimental alias of API for old apps
2020-05-18 17:18 ` Thomas Monjalon
2020-05-18 17:34 ` Ferruh Yigit
@ 2020-05-19 14:14 ` Ray Kinsella
1 sibling, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-19 14:14 UTC (permalink / raw)
To: Thomas Monjalon
Cc: dev, Ferruh Yigit, Luca Boccassi, David Marchand,
Bruce Richardson, Ian Stokes, Eelco Chaudron, Andrzej Ostruszka,
Kevin Traynor, John McNamara, Marko Kovacevic,
Cristian Dumitrescu, Neil Horman
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-14 16:11 ` [dpdk-dev] [PATCH v4] " Ferruh Yigit
` (2 preceding siblings ...)
2020-05-15 15:01 ` [dpdk-dev] [PATCH v6] " Ray Kinsella
@ 2020-05-17 19:52 ` Dumitrescu, Cristian
2020-05-18 6:29 ` Ray Kinsella
3 siblings, 1 reply; 71+ messages in thread
From: Dumitrescu, Cristian @ 2020-05-17 19:52 UTC (permalink / raw)
To: Yigit, Ferruh, Ray Kinsella, Neil Horman, Eelco Chaudron
Cc: dev, Thomas Monjalon, David Marchand, stable, Luca Boccassi,
Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-17 19:52 ` [dpdk-dev] [PATCH v4] meter: " Dumitrescu, Cristian
@ 2020-05-18 6:29 ` Ray Kinsella
2020-05-18 9:22 ` Thomas Monjalon
0 siblings, 1 reply; 71+ messages in thread
From: Ray Kinsella @ 2020-05-18 6:29 UTC (permalink / raw)
To: Dumitrescu, Cristian, Yigit, Ferruh, Neil Horman, Eelco Chaudron
Cc: dev, Thomas Monjalon, David Marchand, stable, Luca Boccassi,
Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka
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
>
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-18 6:29 ` Ray Kinsella
@ 2020-05-18 9:22 ` Thomas Monjalon
2020-05-18 9:30 ` Ray Kinsella
0 siblings, 1 reply; 71+ messages in thread
From: Thomas Monjalon @ 2020-05-18 9:22 UTC (permalink / raw)
To: Yigit, Ferruh, Ray Kinsella
Cc: Dumitrescu, Cristian, Neil Horman, Eelco Chaudron, dev,
David Marchand, stable, Luca Boccassi, Richardson, Bruce, Stokes,
Ian, Andrzej Ostruszka
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-18 9:22 ` Thomas Monjalon
@ 2020-05-18 9:30 ` Ray Kinsella
2020-05-18 10:46 ` Thomas Monjalon
0 siblings, 1 reply; 71+ messages in thread
From: Ray Kinsella @ 2020-05-18 9:30 UTC (permalink / raw)
To: Thomas Monjalon, Yigit, Ferruh
Cc: Dumitrescu, Cristian, Neil Horman, Eelco Chaudron, dev,
David Marchand, stable, Luca Boccassi, Richardson, Bruce, Stokes,
Ian, Andrzej Ostruszka
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-18 9:30 ` Ray Kinsella
@ 2020-05-18 10:46 ` Thomas Monjalon
2020-05-18 11:18 ` Dumitrescu, Cristian
2020-05-18 11:48 ` Ray Kinsella
0 siblings, 2 replies; 71+ messages in thread
From: Thomas Monjalon @ 2020-05-18 10:46 UTC (permalink / raw)
To: Yigit, Ferruh, Ray Kinsella, Dumitrescu, Cristian
Cc: Neil Horman, Eelco Chaudron, dev, David Marchand, stable,
Luca Boccassi, Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka
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?
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-18 10:46 ` Thomas Monjalon
@ 2020-05-18 11:18 ` Dumitrescu, Cristian
2020-05-18 11:49 ` Ray Kinsella
2020-05-18 11:48 ` Ray Kinsella
1 sibling, 1 reply; 71+ messages in thread
From: Dumitrescu, Cristian @ 2020-05-18 11:18 UTC (permalink / raw)
To: Thomas Monjalon, Yigit, Ferruh, Ray Kinsella
Cc: Neil Horman, Eelco Chaudron, dev, David Marchand, stable,
Luca Boccassi, Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka
> -----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
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-18 11:18 ` Dumitrescu, Cristian
@ 2020-05-18 11:49 ` Ray Kinsella
0 siblings, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-18 11:49 UTC (permalink / raw)
To: Dumitrescu, Cristian, Thomas Monjalon, Yigit, Ferruh
Cc: Neil Horman, Eelco Chaudron, dev, David Marchand, stable,
Luca Boccassi, Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-18 10:46 ` Thomas Monjalon
2020-05-18 11:18 ` Dumitrescu, Cristian
@ 2020-05-18 11:48 ` Ray Kinsella
2020-05-18 12:13 ` Thomas Monjalon
1 sibling, 1 reply; 71+ messages in thread
From: Ray Kinsella @ 2020-05-18 11:48 UTC (permalink / raw)
To: Thomas Monjalon, Yigit, Ferruh, Dumitrescu, Cristian
Cc: Neil Horman, Eelco Chaudron, dev, David Marchand, stable,
Luca Boccassi, Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-18 11:48 ` Ray Kinsella
@ 2020-05-18 12:13 ` Thomas Monjalon
2020-05-18 13:06 ` Ray Kinsella
0 siblings, 1 reply; 71+ messages in thread
From: Thomas Monjalon @ 2020-05-18 12:13 UTC (permalink / raw)
To: Yigit, Ferruh, Dumitrescu, Cristian, Ray Kinsella
Cc: Neil Horman, Eelco Chaudron, dev, David Marchand, stable,
Luca Boccassi, Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v4] meter: provide experimental alias of API for old apps
2020-05-18 12:13 ` Thomas Monjalon
@ 2020-05-18 13:06 ` Ray Kinsella
0 siblings, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-18 13:06 UTC (permalink / raw)
To: Thomas Monjalon, Yigit, Ferruh, Dumitrescu, Cristian
Cc: Neil Horman, Eelco Chaudron, dev, David Marchand, stable,
Luca Boccassi, Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread
* [dpdk-dev] [PATCH v5] meter: provide experimental alias of API for old apps
2020-05-13 12:11 ` [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps Ferruh Yigit
` (3 preceding siblings ...)
2020-05-14 16:11 ` [dpdk-dev] [PATCH v4] " Ferruh Yigit
@ 2020-05-18 18:30 ` Ferruh Yigit
2020-05-19 12:16 ` [dpdk-dev] [PATCH v6] " Ferruh Yigit
5 siblings, 0 replies; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-18 18:30 UTC (permalink / raw)
To: Cristian Dumitrescu, Ray Kinsella, Neil Horman, Eelco Chaudron
Cc: dev, Ferruh Yigit, Thomas Monjalon, David Marchand, stable,
Luca Boccassi, Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* [dpdk-dev] [PATCH v6] meter: provide experimental alias of API for old apps
2020-05-13 12:11 ` [dpdk-dev] [PATCH] meter: provide experimental alias of API for old apps Ferruh Yigit
` (4 preceding siblings ...)
2020-05-18 18:30 ` [dpdk-dev] [PATCH v5] " Ferruh Yigit
@ 2020-05-19 12:16 ` Ferruh Yigit
2020-05-19 13:26 ` Dumitrescu, Cristian
2020-05-19 14:22 ` Ray Kinsella
5 siblings, 2 replies; 71+ messages in thread
From: Ferruh Yigit @ 2020-05-19 12:16 UTC (permalink / raw)
To: Cristian Dumitrescu, Ray Kinsella, Neil Horman, Eelco Chaudron
Cc: dev, Ferruh Yigit, Thomas Monjalon, David Marchand, stable,
Luca Boccassi, Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v6] meter: provide experimental alias of API for old apps
2020-05-19 12:16 ` [dpdk-dev] [PATCH v6] " Ferruh Yigit
@ 2020-05-19 13:26 ` Dumitrescu, Cristian
2020-05-19 14:24 ` Thomas Monjalon
2020-05-19 14:22 ` Ray Kinsella
1 sibling, 1 reply; 71+ messages in thread
From: Dumitrescu, Cristian @ 2020-05-19 13:26 UTC (permalink / raw)
To: Yigit, Ferruh, Ray Kinsella, Neil Horman, Eelco Chaudron
Cc: dev, Thomas Monjalon, David Marchand, stable, Luca Boccassi,
Richardson, Bruce, Stokes, Ian, Andrzej Ostruszka, techboard
> -----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.
^ permalink raw reply [flat|nested] 71+ messages in thread* Re: [dpdk-dev] [PATCH v6] meter: provide experimental alias of API for old apps
2020-05-19 13:26 ` Dumitrescu, Cristian
@ 2020-05-19 14:24 ` Thomas Monjalon
0 siblings, 0 replies; 71+ messages in thread
From: Thomas Monjalon @ 2020-05-19 14:24 UTC (permalink / raw)
To: Yigit, Ferruh, Dumitrescu, Cristian
Cc: Ray Kinsella, Neil Horman, Eelco Chaudron, dev, David Marchand,
stable, Luca Boccassi, Richardson, Bruce, Stokes, Ian,
Andrzej Ostruszka, techboard
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.
^ permalink raw reply [flat|nested] 71+ messages in thread
* Re: [dpdk-dev] [PATCH v6] meter: provide experimental alias of API for old apps
2020-05-19 12:16 ` [dpdk-dev] [PATCH v6] " Ferruh Yigit
2020-05-19 13:26 ` Dumitrescu, Cristian
@ 2020-05-19 14:22 ` Ray Kinsella
1 sibling, 0 replies; 71+ messages in thread
From: Ray Kinsella @ 2020-05-19 14:22 UTC (permalink / raw)
To: Ferruh Yigit, Cristian Dumitrescu, Neil Horman, Eelco Chaudron
Cc: dev, Thomas Monjalon, David Marchand, stable, Luca Boccassi,
Bruce Richardson, Ian Stokes, Andrzej Ostruszka
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>
^ permalink raw reply [flat|nested] 71+ messages in thread