diff mbox series

pipeline: remove experimental tag from API

Message ID 20210901122007.3885050-1-jasvinder.singh@intel.com (mailing list archive)
State Rejected
Delegated to: Thomas Monjalon
Headers show
Series pipeline: remove experimental tag from API | expand

Checks

Context Check Description
ci/iol-x86_64-compile-testing success Testing PASS
ci/iol-mellanox-Performance success Performance Testing PASS
ci/iol-x86_64-unit-testing success Testing PASS
ci/intel-Testing success Testing PASS
ci/Intel-compilation success Compilation OK
ci/iol-aarch64-compile-testing success Testing PASS
ci/iol-intel-Performance success Performance Testing PASS
ci/iol-intel-Functional success Functional Testing PASS
ci/iol-broadcom-Functional success Functional Testing PASS
ci/iol-broadcom-Performance success Performance Testing PASS
ci/github-robot: build success github build: passed
ci/checkpatch success coding style OK

Commit Message

Singh, Jasvinder Sept. 1, 2021, 12:20 p.m. UTC
These APIs were introduced in 18.05, therefore removing
experimental tag to promote them to stable state.

Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
---
 lib/pipeline/rte_port_in_action.h | 10 ----------
 lib/pipeline/rte_table_action.h   | 18 ------------------
 lib/pipeline/version.map          | 16 ++++++----------
 3 files changed, 6 insertions(+), 38 deletions(-)

Comments

Kinsella, Ray Sept. 1, 2021, 1:48 p.m. UTC | #1
On 01/09/2021 13:20, Jasvinder Singh wrote:
> These APIs were introduced in 18.05, therefore removing
> experimental tag to promote them to stable state.
> 
> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> ---
>  lib/pipeline/rte_port_in_action.h | 10 ----------
>  lib/pipeline/rte_table_action.h   | 18 ------------------
>  lib/pipeline/version.map          | 16 ++++++----------
>  3 files changed, 6 insertions(+), 38 deletions(-)

Acked-by: Ray Kinsella <mdr@ashroe.eu>
Zhang, Roy Fan Sept. 3, 2021, 12:56 p.m. UTC | #2
> -----Original Message-----
> From: Singh, Jasvinder <jasvinder.singh@intel.com>
> Sent: Wednesday, September 1, 2021 1:20 PM
> To: dev@dpdk.org
> Cc: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>; mdr@ashroe.eu;
> Zhang, Roy Fan <roy.fan.zhang@intel.com>
> Subject: [PATCH] pipeline: remove experimental tag from API
> 
> These APIs were introduced in 18.05, therefore removing
> experimental tag to promote them to stable state.
> 
> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> ---
Acked-by: Fan Zhang <roy.fan.zhang@intel.com>
Thanks Jasvinder.
Kinsella, Ray Sept. 3, 2021, 1 p.m. UTC | #3
On 01/09/2021 13:20, Jasvinder Singh wrote:
> These APIs were introduced in 18.05, therefore removing
> experimental tag to promote them to stable state.
> 
> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> ---
>  lib/pipeline/rte_port_in_action.h | 10 ----------
>  lib/pipeline/rte_table_action.h   | 18 ------------------
>  lib/pipeline/version.map          | 16 ++++++----------
>  3 files changed, 6 insertions(+), 38 deletions(-)
> 
Acked-by: Ray Kinsella <mdr@ashroe.eu>
Thomas Monjalon Sept. 27, 2021, 10:17 a.m. UTC | #4
01/09/2021 14:20, Jasvinder Singh:
> These APIs were introduced in 18.05, therefore removing
> experimental tag to promote them to stable state.
> 
> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> ---
>  lib/pipeline/rte_port_in_action.h | 10 ----------
>  lib/pipeline/rte_table_action.h   | 18 ------------------
>  lib/pipeline/version.map          | 16 ++++++----------
>  3 files changed, 6 insertions(+), 38 deletions(-)

Cristian, please can you check whether you intend to keep these functions in future?
If they are candidate to be removed, there is no point to promote them.
Dumitrescu, Cristian Oct. 12, 2021, 8:34 p.m. UTC | #5
> -----Original Message-----
> From: Thomas Monjalon <thomas@monjalon.net>
> Sent: Monday, September 27, 2021 11:18 AM
> To: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>
> Cc: dev@dpdk.org; mdr@ashroe.eu; Zhang, Roy Fan
> <roy.fan.zhang@intel.com>; Singh, Jasvinder <jasvinder.singh@intel.com>
> Subject: Re: [dpdk-dev] [PATCH] pipeline: remove experimental tag from API
> 
> 01/09/2021 14:20, Jasvinder Singh:
> > These APIs were introduced in 18.05, therefore removing
> > experimental tag to promote them to stable state.
> >
> > Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> > ---
> >  lib/pipeline/rte_port_in_action.h | 10 ----------
> >  lib/pipeline/rte_table_action.h   | 18 ------------------
> >  lib/pipeline/version.map          | 16 ++++++----------
> >  3 files changed, 6 insertions(+), 38 deletions(-)
> 
> Cristian, please can you check whether you intend to keep these functions in
> future?
> If they are candidate to be removed, there is no point to promote them.
> 
> 

Hi Thomas,

Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.

But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.

So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.

So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.

Regards,
Cristian
Dumitrescu, Cristian Oct. 12, 2021, 8:34 p.m. UTC | #6
> -----Original Message-----
> From: Singh, Jasvinder <jasvinder.singh@intel.com>
> Sent: Wednesday, September 1, 2021 1:20 PM
> To: dev@dpdk.org
> Cc: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>; mdr@ashroe.eu;
> Zhang, Roy Fan <roy.fan.zhang@intel.com>
> Subject: [PATCH] pipeline: remove experimental tag from API
> 
> These APIs were introduced in 18.05, therefore removing
> experimental tag to promote them to stable state.
> 
> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> ---
>  lib/pipeline/rte_port_in_action.h | 10 ----------
>  lib/pipeline/rte_table_action.h   | 18 ------------------
>  lib/pipeline/version.map          | 16 ++++++----------
>  3 files changed, 6 insertions(+), 38 deletions(-)
> 
> diff --git a/lib/pipeline/rte_port_in_action.h
> b/lib/pipeline/rte_port_in_action.h
> index d6b063cf58..de611cbfab 100644
> --- a/lib/pipeline/rte_port_in_action.h
> +++ b/lib/pipeline/rte_port_in_action.h
> @@ -42,8 +42,6 @@
>   *    used by the input port action handler based on given action parameters.
>   *    API functions: rte_port_in_action_apply().
>   *
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
>   */
> 
>  #ifdef __cplusplus
> @@ -172,7 +170,6 @@ struct rte_port_in_action_profile;
>   * @return
>   *   Input port action profile handle on success, NULL otherwise.
>   */
> -__rte_experimental
>  struct rte_port_in_action_profile *
>  rte_port_in_action_profile_create(uint32_t socket_id);
> 
> @@ -184,7 +181,6 @@ rte_port_in_action_profile_create(uint32_t
> socket_id);
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_port_in_action_profile_free(struct rte_port_in_action_profile *profile);
> 
> @@ -203,7 +199,6 @@ rte_port_in_action_profile_free(struct
> rte_port_in_action_profile *profile);
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_port_in_action_profile_action_register(
>  	struct rte_port_in_action_profile *profile,
> @@ -226,7 +221,6 @@ rte_port_in_action_profile_action_register(
>   *
>   * @see rte_port_in_action_create()
>   */
> -__rte_experimental
>  int
>  rte_port_in_action_profile_freeze(struct rte_port_in_action_profile
> *profile);
> 
> @@ -249,7 +243,6 @@ struct rte_port_in_action;
>   * @return
>   *   Handle to input port action object on success, NULL on error.
>   */
> -__rte_experimental
>  struct rte_port_in_action *
>  rte_port_in_action_create(struct rte_port_in_action_profile *profile,
>  	uint32_t socket_id);
> @@ -262,7 +255,6 @@ rte_port_in_action_create(struct
> rte_port_in_action_profile *profile,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_port_in_action_free(struct rte_port_in_action *action);
> 
> @@ -276,7 +268,6 @@ rte_port_in_action_free(struct rte_port_in_action
> *action);
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_port_in_action_params_get(struct rte_port_in_action *action,
>  	struct rte_pipeline_port_in_params *params);
> @@ -296,7 +287,6 @@ rte_port_in_action_params_get(struct
> rte_port_in_action *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_port_in_action_apply(struct rte_port_in_action *action,
>  	enum rte_port_in_action_type type,
> diff --git a/lib/pipeline/rte_table_action.h b/lib/pipeline/rte_table_action.h
> index 82bc9d9ac9..aac6b8ce8d 100644
> --- a/lib/pipeline/rte_table_action.h
> +++ b/lib/pipeline/rte_table_action.h
> @@ -48,8 +48,6 @@
>   *  - Use the table action object to read action data (e.g. stats counters) for
>   *    any given rule. API functions: rte_table_action_XYZ_read().
>   *
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
>   */
> 
>  #ifdef __cplusplus
> @@ -823,7 +821,6 @@ struct rte_table_action_profile;
>   * @return
>   *   Table action profile handle on success, NULL otherwise.
>   */
> -__rte_experimental
>  struct rte_table_action_profile *
>  rte_table_action_profile_create(struct rte_table_action_common_config
> *common);
> 
> @@ -835,7 +832,6 @@ rte_table_action_profile_create(struct
> rte_table_action_common_config *common);
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_profile_free(struct rte_table_action_profile *profile);
> 
> @@ -854,7 +850,6 @@ rte_table_action_profile_free(struct
> rte_table_action_profile *profile);
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_profile_action_register(struct rte_table_action_profile
> *profile,
>  	enum rte_table_action_type type,
> @@ -875,7 +870,6 @@ rte_table_action_profile_action_register(struct
> rte_table_action_profile *profil
>   *
>   * @see rte_table_action_create()
>   */
> -__rte_experimental
>  int
>  rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
> 
> @@ -899,7 +893,6 @@ struct rte_table_action;
>   *
>   * @see rte_table_action_create()
>   */
> -__rte_experimental
>  struct rte_table_action *
>  rte_table_action_create(struct rte_table_action_profile *profile,
>  	uint32_t socket_id);
> @@ -912,7 +905,6 @@ rte_table_action_create(struct
> rte_table_action_profile *profile,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_free(struct rte_table_action *action);
> 
> @@ -926,7 +918,6 @@ rte_table_action_free(struct rte_table_action
> *action);
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_table_params_get(struct rte_table_action *action,
>  	struct rte_pipeline_table_params *params);
> @@ -949,7 +940,6 @@ rte_table_action_table_params_get(struct
> rte_table_action *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_apply(struct rte_table_action *action,
>  	void *data,
> @@ -969,7 +959,6 @@ rte_table_action_apply(struct rte_table_action
> *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_dscp_table_update(struct rte_table_action *action,
>  	uint64_t dscp_mask,
> @@ -989,7 +978,6 @@ rte_table_action_dscp_table_update(struct
> rte_table_action *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_meter_profile_add(struct rte_table_action *action,
>  	uint32_t meter_profile_id,
> @@ -1006,7 +994,6 @@ rte_table_action_meter_profile_add(struct
> rte_table_action *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_meter_profile_delete(struct rte_table_action *action,
>  	uint32_t meter_profile_id);
> @@ -1038,7 +1025,6 @@ rte_table_action_meter_profile_delete(struct
> rte_table_action *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_meter_read(struct rte_table_action *action,
>  	void *data,
> @@ -1065,7 +1051,6 @@ rte_table_action_meter_read(struct
> rte_table_action *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_ttl_read(struct rte_table_action *action,
>  	void *data,
> @@ -1091,7 +1076,6 @@ rte_table_action_ttl_read(struct rte_table_action
> *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_stats_read(struct rte_table_action *action,
>  	void *data,
> @@ -1112,7 +1096,6 @@ rte_table_action_stats_read(struct
> rte_table_action *action,
>   * @return
>   *   Zero on success, non-zero error code otherwise.
>   */
> -__rte_experimental
>  int
>  rte_table_action_time_read(struct rte_table_action *action,
>  	void *data,
> @@ -1128,7 +1111,6 @@ rte_table_action_time_read(struct
> rte_table_action *action,
>   * @return
>   *   The pointer to the session on success, NULL otherwise.
>   */
> -__rte_experimental
>  struct rte_cryptodev_sym_session *
>  rte_table_action_crypto_sym_session_get(struct rte_table_action *action,
>  	void *data);
> diff --git a/lib/pipeline/version.map b/lib/pipeline/version.map
> index 2b68f584a4..5732fac16b 100644
> --- a/lib/pipeline/version.map
> +++ b/lib/pipeline/version.map
> @@ -24,14 +24,6 @@ DPDK_22 {
>  	rte_pipeline_table_entry_delete;
>  	rte_pipeline_table_entry_delete_bulk;
>  	rte_pipeline_table_stats_read;
> -
> -	local: *;
> -};
> -
> -EXPERIMENTAL {
> -	global:
> -
> -	# added in 18.05
>  	rte_port_in_action_apply;
>  	rte_port_in_action_create;
>  	rte_port_in_action_free;
> @@ -55,10 +47,14 @@ EXPERIMENTAL {
>  	rte_table_action_table_params_get;
>  	rte_table_action_time_read;
>  	rte_table_action_ttl_read;
> -
> -	# added in 18.11
>  	rte_table_action_crypto_sym_session_get;
> 
> +	local: *;
> +};
> +
> +EXPERIMENTAL {
> +	global:
> +
>  	# added in 20.11
>  	rte_swx_ctl_action_arg_info_get;
>  	rte_swx_ctl_action_info_get;
> --
> 2.26.3

Acked-by: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
Thomas Monjalon Oct. 12, 2021, 9:52 p.m. UTC | #7
12/10/2021 22:34, Dumitrescu, Cristian:
> From: Thomas Monjalon <thomas@monjalon.net>
> > 01/09/2021 14:20, Jasvinder Singh:
> > > These APIs were introduced in 18.05, therefore removing
> > > experimental tag to promote them to stable state.
> > >
> > > Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> > > ---
> > >  lib/pipeline/rte_port_in_action.h | 10 ----------
> > >  lib/pipeline/rte_table_action.h   | 18 ------------------
> > >  lib/pipeline/version.map          | 16 ++++++----------
> > >  3 files changed, 6 insertions(+), 38 deletions(-)
> > 
> > Cristian, please can you check whether you intend to keep these functions in
> > future?
> > If they are candidate to be removed, there is no point to promote them.
> 
> Hi Thomas,
> 
> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
> 
> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
> 
> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
> 
> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.

I think we should not promote API that we know will disappear soon.
The stable status means something for the users.
Ray, what is your opinion?
Kinsella, Ray Oct. 13, 2021, 8:51 a.m. UTC | #8
On 12/10/2021 22:52, Thomas Monjalon wrote:
> 12/10/2021 22:34, Dumitrescu, Cristian:
>> From: Thomas Monjalon <thomas@monjalon.net>
>>> 01/09/2021 14:20, Jasvinder Singh:
>>>> These APIs were introduced in 18.05, therefore removing
>>>> experimental tag to promote them to stable state.
>>>>
>>>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
>>>> ---
>>>>  lib/pipeline/rte_port_in_action.h | 10 ----------
>>>>  lib/pipeline/rte_table_action.h   | 18 ------------------
>>>>  lib/pipeline/version.map          | 16 ++++++----------
>>>>  3 files changed, 6 insertions(+), 38 deletions(-)
>>>
>>> Cristian, please can you check whether you intend to keep these functions in
>>> future?
>>> If they are candidate to be removed, there is no point to promote them.
>>
>> Hi Thomas,
>>
>> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
>>
>> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
>>
>> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
>>
>> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.
> 
> I think we should not promote API that we know will disappear soon.
> The stable status means something for the users.
> Ray, what is your opinion?
> 

Well - I agree with Cristian (he and I discuss this a few weeks ago).
My position is if you are going to maintain an API, that means giving a few guarantees.
The API's have been experimental for 3 years ... at what point do they mature?

However, I agree there is two ways to look at this thing, I try to be pragmatic. 
Maturing of any ABI/API is a conversation between a maintainer and the contributor.
If they strongly feel, it is a pointless exercise - I won't argue. 
 
Ray K
Kinsella, Ray Oct. 13, 2021, 8:51 a.m. UTC | #9
On 12/10/2021 21:34, Dumitrescu, Cristian wrote:
> 
> 
>> -----Original Message-----
>> From: Singh, Jasvinder <jasvinder.singh@intel.com>
>> Sent: Wednesday, September 1, 2021 1:20 PM
>> To: dev@dpdk.org
>> Cc: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>; mdr@ashroe.eu;
>> Zhang, Roy Fan <roy.fan.zhang@intel.com>
>> Subject: [PATCH] pipeline: remove experimental tag from API
>>
>> These APIs were introduced in 18.05, therefore removing
>> experimental tag to promote them to stable state.
>>
>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
>> ---
>>  lib/pipeline/rte_port_in_action.h | 10 ----------
>>  lib/pipeline/rte_table_action.h   | 18 ------------------
>>  lib/pipeline/version.map          | 16 ++++++----------
>>  3 files changed, 6 insertions(+), 38 deletions(-)
>>
>> diff --git a/lib/pipeline/rte_port_in_action.h
>> b/lib/pipeline/rte_port_in_action.h
>> index d6b063cf58..de611cbfab 100644
>> --- a/lib/pipeline/rte_port_in_action.h
>> +++ b/lib/pipeline/rte_port_in_action.h
>> @@ -42,8 +42,6 @@
>>   *    used by the input port action handler based on given action parameters.
>>   *    API functions: rte_port_in_action_apply().
>>   *
>> - * @warning
>> - * @b EXPERIMENTAL: this API may change without prior notice
>>   */
>>
>>  #ifdef __cplusplus
>> @@ -172,7 +170,6 @@ struct rte_port_in_action_profile;
>>   * @return
>>   *   Input port action profile handle on success, NULL otherwise.
>>   */
>> -__rte_experimental
>>  struct rte_port_in_action_profile *
>>  rte_port_in_action_profile_create(uint32_t socket_id);
>>
>> @@ -184,7 +181,6 @@ rte_port_in_action_profile_create(uint32_t
>> socket_id);
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_port_in_action_profile_free(struct rte_port_in_action_profile *profile);
>>
>> @@ -203,7 +199,6 @@ rte_port_in_action_profile_free(struct
>> rte_port_in_action_profile *profile);
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_port_in_action_profile_action_register(
>>  	struct rte_port_in_action_profile *profile,
>> @@ -226,7 +221,6 @@ rte_port_in_action_profile_action_register(
>>   *
>>   * @see rte_port_in_action_create()
>>   */
>> -__rte_experimental
>>  int
>>  rte_port_in_action_profile_freeze(struct rte_port_in_action_profile
>> *profile);
>>
>> @@ -249,7 +243,6 @@ struct rte_port_in_action;
>>   * @return
>>   *   Handle to input port action object on success, NULL on error.
>>   */
>> -__rte_experimental
>>  struct rte_port_in_action *
>>  rte_port_in_action_create(struct rte_port_in_action_profile *profile,
>>  	uint32_t socket_id);
>> @@ -262,7 +255,6 @@ rte_port_in_action_create(struct
>> rte_port_in_action_profile *profile,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_port_in_action_free(struct rte_port_in_action *action);
>>
>> @@ -276,7 +268,6 @@ rte_port_in_action_free(struct rte_port_in_action
>> *action);
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_port_in_action_params_get(struct rte_port_in_action *action,
>>  	struct rte_pipeline_port_in_params *params);
>> @@ -296,7 +287,6 @@ rte_port_in_action_params_get(struct
>> rte_port_in_action *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_port_in_action_apply(struct rte_port_in_action *action,
>>  	enum rte_port_in_action_type type,
>> diff --git a/lib/pipeline/rte_table_action.h b/lib/pipeline/rte_table_action.h
>> index 82bc9d9ac9..aac6b8ce8d 100644
>> --- a/lib/pipeline/rte_table_action.h
>> +++ b/lib/pipeline/rte_table_action.h
>> @@ -48,8 +48,6 @@
>>   *  - Use the table action object to read action data (e.g. stats counters) for
>>   *    any given rule. API functions: rte_table_action_XYZ_read().
>>   *
>> - * @warning
>> - * @b EXPERIMENTAL: this API may change without prior notice
>>   */
>>
>>  #ifdef __cplusplus
>> @@ -823,7 +821,6 @@ struct rte_table_action_profile;
>>   * @return
>>   *   Table action profile handle on success, NULL otherwise.
>>   */
>> -__rte_experimental
>>  struct rte_table_action_profile *
>>  rte_table_action_profile_create(struct rte_table_action_common_config
>> *common);
>>
>> @@ -835,7 +832,6 @@ rte_table_action_profile_create(struct
>> rte_table_action_common_config *common);
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_profile_free(struct rte_table_action_profile *profile);
>>
>> @@ -854,7 +850,6 @@ rte_table_action_profile_free(struct
>> rte_table_action_profile *profile);
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_profile_action_register(struct rte_table_action_profile
>> *profile,
>>  	enum rte_table_action_type type,
>> @@ -875,7 +870,6 @@ rte_table_action_profile_action_register(struct
>> rte_table_action_profile *profil
>>   *
>>   * @see rte_table_action_create()
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
>>
>> @@ -899,7 +893,6 @@ struct rte_table_action;
>>   *
>>   * @see rte_table_action_create()
>>   */
>> -__rte_experimental
>>  struct rte_table_action *
>>  rte_table_action_create(struct rte_table_action_profile *profile,
>>  	uint32_t socket_id);
>> @@ -912,7 +905,6 @@ rte_table_action_create(struct
>> rte_table_action_profile *profile,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_free(struct rte_table_action *action);
>>
>> @@ -926,7 +918,6 @@ rte_table_action_free(struct rte_table_action
>> *action);
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_table_params_get(struct rte_table_action *action,
>>  	struct rte_pipeline_table_params *params);
>> @@ -949,7 +940,6 @@ rte_table_action_table_params_get(struct
>> rte_table_action *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_apply(struct rte_table_action *action,
>>  	void *data,
>> @@ -969,7 +959,6 @@ rte_table_action_apply(struct rte_table_action
>> *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_dscp_table_update(struct rte_table_action *action,
>>  	uint64_t dscp_mask,
>> @@ -989,7 +978,6 @@ rte_table_action_dscp_table_update(struct
>> rte_table_action *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_meter_profile_add(struct rte_table_action *action,
>>  	uint32_t meter_profile_id,
>> @@ -1006,7 +994,6 @@ rte_table_action_meter_profile_add(struct
>> rte_table_action *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_meter_profile_delete(struct rte_table_action *action,
>>  	uint32_t meter_profile_id);
>> @@ -1038,7 +1025,6 @@ rte_table_action_meter_profile_delete(struct
>> rte_table_action *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_meter_read(struct rte_table_action *action,
>>  	void *data,
>> @@ -1065,7 +1051,6 @@ rte_table_action_meter_read(struct
>> rte_table_action *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_ttl_read(struct rte_table_action *action,
>>  	void *data,
>> @@ -1091,7 +1076,6 @@ rte_table_action_ttl_read(struct rte_table_action
>> *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_stats_read(struct rte_table_action *action,
>>  	void *data,
>> @@ -1112,7 +1096,6 @@ rte_table_action_stats_read(struct
>> rte_table_action *action,
>>   * @return
>>   *   Zero on success, non-zero error code otherwise.
>>   */
>> -__rte_experimental
>>  int
>>  rte_table_action_time_read(struct rte_table_action *action,
>>  	void *data,
>> @@ -1128,7 +1111,6 @@ rte_table_action_time_read(struct
>> rte_table_action *action,
>>   * @return
>>   *   The pointer to the session on success, NULL otherwise.
>>   */
>> -__rte_experimental
>>  struct rte_cryptodev_sym_session *
>>  rte_table_action_crypto_sym_session_get(struct rte_table_action *action,
>>  	void *data);
>> diff --git a/lib/pipeline/version.map b/lib/pipeline/version.map
>> index 2b68f584a4..5732fac16b 100644
>> --- a/lib/pipeline/version.map
>> +++ b/lib/pipeline/version.map
>> @@ -24,14 +24,6 @@ DPDK_22 {
>>  	rte_pipeline_table_entry_delete;
>>  	rte_pipeline_table_entry_delete_bulk;
>>  	rte_pipeline_table_stats_read;
>> -
>> -	local: *;
>> -};
>> -
>> -EXPERIMENTAL {
>> -	global:
>> -
>> -	# added in 18.05
>>  	rte_port_in_action_apply;
>>  	rte_port_in_action_create;
>>  	rte_port_in_action_free;
>> @@ -55,10 +47,14 @@ EXPERIMENTAL {
>>  	rte_table_action_table_params_get;
>>  	rte_table_action_time_read;
>>  	rte_table_action_ttl_read;
>> -
>> -	# added in 18.11
>>  	rte_table_action_crypto_sym_session_get;
>>
>> +	local: *;
>> +};
>> +
>> +EXPERIMENTAL {
>> +	global:
>> +
>>  	# added in 20.11
>>  	rte_swx_ctl_action_arg_info_get;
>>  	rte_swx_ctl_action_info_get;
>> --
>> 2.26.3
> 
> Acked-by: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
> 
Acked-by: Ray Kinsella <mdr@ashroe.eu>
Thomas Monjalon Oct. 13, 2021, 9:40 a.m. UTC | #10
13/10/2021 10:51, Kinsella, Ray:
> 
> On 12/10/2021 22:52, Thomas Monjalon wrote:
> > 12/10/2021 22:34, Dumitrescu, Cristian:
> >> From: Thomas Monjalon <thomas@monjalon.net>
> >>> 01/09/2021 14:20, Jasvinder Singh:
> >>>> These APIs were introduced in 18.05, therefore removing
> >>>> experimental tag to promote them to stable state.
> >>>>
> >>>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> >>>> ---
> >>>>  lib/pipeline/rte_port_in_action.h | 10 ----------
> >>>>  lib/pipeline/rte_table_action.h   | 18 ------------------
> >>>>  lib/pipeline/version.map          | 16 ++++++----------
> >>>>  3 files changed, 6 insertions(+), 38 deletions(-)
> >>>
> >>> Cristian, please can you check whether you intend to keep these functions in
> >>> future?
> >>> If they are candidate to be removed, there is no point to promote them.
> >>
> >> Hi Thomas,
> >>
> >> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
> >>
> >> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
> >>
> >> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
> >>
> >> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.
> > 
> > I think we should not promote API that we know will disappear soon.
> > The stable status means something for the users.
> > Ray, what is your opinion?
> > 
> 
> Well - I agree with Cristian (he and I discuss this a few weeks ago).
> My position is if you are going to maintain an API, that means giving a few guarantees.
> The API's have been experimental for 3 years ... at what point do they mature?
> 
> However, I agree there is two ways to look at this thing, I try to be pragmatic. 
> Maturing of any ABI/API is a conversation between a maintainer and the contributor.
> If they strongly feel, it is a pointless exercise - I won't argue. 

I think you did't get it.
This API will be removed soon.
That's why I think it doesn't make sense to make them stable, just before removing.
Kinsella, Ray Oct. 13, 2021, 9:43 a.m. UTC | #11
On 13/10/2021 10:40, Thomas Monjalon wrote:
> 13/10/2021 10:51, Kinsella, Ray:
>>
>> On 12/10/2021 22:52, Thomas Monjalon wrote:
>>> 12/10/2021 22:34, Dumitrescu, Cristian:
>>>> From: Thomas Monjalon <thomas@monjalon.net>
>>>>> 01/09/2021 14:20, Jasvinder Singh:
>>>>>> These APIs were introduced in 18.05, therefore removing
>>>>>> experimental tag to promote them to stable state.
>>>>>>
>>>>>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
>>>>>> ---
>>>>>>  lib/pipeline/rte_port_in_action.h | 10 ----------
>>>>>>  lib/pipeline/rte_table_action.h   | 18 ------------------
>>>>>>  lib/pipeline/version.map          | 16 ++++++----------
>>>>>>  3 files changed, 6 insertions(+), 38 deletions(-)
>>>>>
>>>>> Cristian, please can you check whether you intend to keep these functions in
>>>>> future?
>>>>> If they are candidate to be removed, there is no point to promote them.
>>>>
>>>> Hi Thomas,
>>>>
>>>> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
>>>>
>>>> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
>>>>
>>>> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
>>>>
>>>> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.
>>>
>>> I think we should not promote API that we know will disappear soon.
>>> The stable status means something for the users.
>>> Ray, what is your opinion?
>>>
>>
>> Well - I agree with Cristian (he and I discuss this a few weeks ago).
>> My position is if you are going to maintain an API, that means giving a few guarantees.
>> The API's have been experimental for 3 years ... at what point do they mature?
>>
>> However, I agree there is two ways to look at this thing, I try to be pragmatic. 
>> Maturing of any ABI/API is a conversation between a maintainer and the contributor.
>> If they strongly feel, it is a pointless exercise - I won't argue. 
> 
> I think you did't get it.
> This API will be removed soon.
> That's why I think it doesn't make sense to make them stable, just before removing.
> 

Nope, I got it 110%
I reflected both my opinion as ABI Maintainer, and tried to be pragmatic about the situation.

As I said "Maturing of any ABI/API is a conversation between a maintainer and the contributor.
If they strongly feel, it is a pointless exercise - I won't argue."

Ray K
Thomas Monjalon Oct. 13, 2021, 9:49 a.m. UTC | #12
13/10/2021 11:43, Kinsella, Ray:
> On 13/10/2021 10:40, Thomas Monjalon wrote:
> > 13/10/2021 10:51, Kinsella, Ray:
> >> On 12/10/2021 22:52, Thomas Monjalon wrote:
> >>> 12/10/2021 22:34, Dumitrescu, Cristian:
> >>>> From: Thomas Monjalon <thomas@monjalon.net>
> >>>>> 01/09/2021 14:20, Jasvinder Singh:
> >>>>>> These APIs were introduced in 18.05, therefore removing
> >>>>>> experimental tag to promote them to stable state.
> >>>>>>
> >>>>>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> >>>>>> ---
> >>>>>>  lib/pipeline/rte_port_in_action.h | 10 ----------
> >>>>>>  lib/pipeline/rte_table_action.h   | 18 ------------------
> >>>>>>  lib/pipeline/version.map          | 16 ++++++----------
> >>>>>>  3 files changed, 6 insertions(+), 38 deletions(-)
> >>>>>
> >>>>> Cristian, please can you check whether you intend to keep these functions in
> >>>>> future?
> >>>>> If they are candidate to be removed, there is no point to promote them.
> >>>>
> >>>> Hi Thomas,
> >>>>
> >>>> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
> >>>>
> >>>> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
> >>>>
> >>>> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
> >>>>
> >>>> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.
> >>>
> >>> I think we should not promote API that we know will disappear soon.
> >>> The stable status means something for the users.
> >>> Ray, what is your opinion?
> >>>
> >>
> >> Well - I agree with Cristian (he and I discuss this a few weeks ago).
> >> My position is if you are going to maintain an API, that means giving a few guarantees.
> >> The API's have been experimental for 3 years ... at what point do they mature?
> >>
> >> However, I agree there is two ways to look at this thing, I try to be pragmatic. 
> >> Maturing of any ABI/API is a conversation between a maintainer and the contributor.
> >> If they strongly feel, it is a pointless exercise - I won't argue. 
> > 
> > I think you did't get it.
> > This API will be removed soon.
> > That's why I think it doesn't make sense to make them stable, just before removing.
> > 
> 
> Nope, I got it 110%
> I reflected both my opinion as ABI Maintainer, and tried to be pragmatic about the situation.
> 
> As I said "Maturing of any ABI/API is a conversation between a maintainer and the contributor.
> If they strongly feel, it is a pointless exercise - I won't argue."

Sorry, I don't understand your position.
Do you think we should promote functions to stable which are candidate to be removed soon?
Kinsella, Ray Oct. 13, 2021, 10:02 a.m. UTC | #13
On 13/10/2021 10:49, Thomas Monjalon wrote:
> 13/10/2021 11:43, Kinsella, Ray:
>> On 13/10/2021 10:40, Thomas Monjalon wrote:
>>> 13/10/2021 10:51, Kinsella, Ray:
>>>> On 12/10/2021 22:52, Thomas Monjalon wrote:
>>>>> 12/10/2021 22:34, Dumitrescu, Cristian:
>>>>>> From: Thomas Monjalon <thomas@monjalon.net>
>>>>>>> 01/09/2021 14:20, Jasvinder Singh:
>>>>>>>> These APIs were introduced in 18.05, therefore removing
>>>>>>>> experimental tag to promote them to stable state.
>>>>>>>>
>>>>>>>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
>>>>>>>> ---
>>>>>>>>  lib/pipeline/rte_port_in_action.h | 10 ----------
>>>>>>>>  lib/pipeline/rte_table_action.h   | 18 ------------------
>>>>>>>>  lib/pipeline/version.map          | 16 ++++++----------
>>>>>>>>  3 files changed, 6 insertions(+), 38 deletions(-)
>>>>>>>
>>>>>>> Cristian, please can you check whether you intend to keep these functions in
>>>>>>> future?
>>>>>>> If they are candidate to be removed, there is no point to promote them.
>>>>>>
>>>>>> Hi Thomas,
>>>>>>
>>>>>> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
>>>>>>
>>>>>> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
>>>>>>
>>>>>> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
>>>>>>
>>>>>> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.
>>>>>
>>>>> I think we should not promote API that we know will disappear soon.
>>>>> The stable status means something for the users.
>>>>> Ray, what is your opinion?
>>>>>
>>>>
>>>> Well - I agree with Cristian (he and I discuss this a few weeks ago).
>>>> My position is if you are going to maintain an API, that means giving a few guarantees.
>>>> The API's have been experimental for 3 years ... at what point do they mature?
>>>>
>>>> However, I agree there is two ways to look at this thing, I try to be pragmatic. 
>>>> Maturing of any ABI/API is a conversation between a maintainer and the contributor.
>>>> If they strongly feel, it is a pointless exercise - I won't argue. 
>>>
>>> I think you did't get it.
>>> This API will be removed soon.
>>> That's why I think it doesn't make sense to make them stable, just before removing.
>>>
>>
>> Nope, I got it 110%
>> I reflected both my opinion as ABI Maintainer, and tried to be pragmatic about the situation.
>>
>> As I said "Maturing of any ABI/API is a conversation between a maintainer and the contributor.
>> If they strongly feel, it is a pointless exercise - I won't argue."
> 
> Sorry, I don't understand your position.
> Do you think we should promote functions to stable which are candidate to be removed soon?
> 

I am just reflecting the policy here.

"An API’s experimental status should be reviewed annually, by both the maintainer and/or the original contributor. Ordinarily APIs marked as experimental will be promoted to the stable ABI once a maintainer has become satisfied that the API is mature and is unlikely to change."

then,

"The promotion or removal of symbols will typically form part of a conversation between the maintainer and the original contributor.".

As I said, in my email above ...

"Maturing of any ABI/API is a conversation between a maintainer and the contributor.
If they strongly feel, it is a pointless exercise [to make the symbols stable] - I won't argue.

Or to be _abundantly clear_ ... 

I don't think we should promote functions needlessly, as I said, if others decide it is pointless, I won't argue. 
I do think if we have a policy, that experimental symbols will mature or be removed, we should be careful about the exceptions we make, lest the policy becomes irrelevant and ignored. 

Ray K
Bruce Richardson Oct. 13, 2021, 11:11 a.m. UTC | #14
On Wed, Oct 13, 2021 at 11:02:02AM +0100, Kinsella, Ray wrote:
> 
> 
> On 13/10/2021 10:49, Thomas Monjalon wrote:
> > 13/10/2021 11:43, Kinsella, Ray:
> >> On 13/10/2021 10:40, Thomas Monjalon wrote:
> >>> 13/10/2021 10:51, Kinsella, Ray:
> >>>> On 12/10/2021 22:52, Thomas Monjalon wrote:
> >>>>> 12/10/2021 22:34, Dumitrescu, Cristian:
> >>>>>> From: Thomas Monjalon <thomas@monjalon.net>
> >>>>>>> 01/09/2021 14:20, Jasvinder Singh:
> >>>>>>>> These APIs were introduced in 18.05, therefore removing
> >>>>>>>> experimental tag to promote them to stable state.
> >>>>>>>>
> >>>>>>>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> >>>>>>>> ---
> >>>>>>>>  lib/pipeline/rte_port_in_action.h | 10 ----------
> >>>>>>>>  lib/pipeline/rte_table_action.h   | 18 ------------------
> >>>>>>>>  lib/pipeline/version.map          | 16 ++++++----------
> >>>>>>>>  3 files changed, 6 insertions(+), 38 deletions(-)
> >>>>>>>
> >>>>>>> Cristian, please can you check whether you intend to keep these functions in
> >>>>>>> future?
> >>>>>>> If they are candidate to be removed, there is no point to promote them.
> >>>>>>
> >>>>>> Hi Thomas,
> >>>>>>
> >>>>>> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
> >>>>>>
> >>>>>> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
> >>>>>>
> >>>>>> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
> >>>>>>
> >>>>>> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.
> >>>>>
> >>>>> I think we should not promote API that we know will disappear soon.
> >>>>> The stable status means something for the users.
> >>>>> Ray, what is your opinion?
> >>>>>
> >>>>
> >>>> Well - I agree with Cristian (he and I discuss this a few weeks ago).
> >>>> My position is if you are going to maintain an API, that means giving a few guarantees.
> >>>> The API's have been experimental for 3 years ... at what point do they mature?
> >>>>
> >>>> However, I agree there is two ways to look at this thing, I try to be pragmatic. 
> >>>> Maturing of any ABI/API is a conversation between a maintainer and the contributor.
> >>>> If they strongly feel, it is a pointless exercise - I won't argue. 
> >>>
> >>> I think you did't get it.
> >>> This API will be removed soon.
> >>> That's why I think it doesn't make sense to make them stable, just before removing.
> >>>
> >>
> >> Nope, I got it 110%
> >> I reflected both my opinion as ABI Maintainer, and tried to be pragmatic about the situation.
> >>
> >> As I said "Maturing of any ABI/API is a conversation between a maintainer and the contributor.
> >> If they strongly feel, it is a pointless exercise - I won't argue."
> > 
> > Sorry, I don't understand your position.
> > Do you think we should promote functions to stable which are candidate to be removed soon?
> > 
> 
> I am just reflecting the policy here.
> 
> "An API’s experimental status should be reviewed annually, by both the maintainer and/or the original contributor. Ordinarily APIs marked as experimental will be promoted to the stable ABI once a maintainer has become satisfied that the API is mature and is unlikely to change."
>
If an API is planned for removal, then I think it falls under the bucket of
"likely to change", so should not be made non-experimental. Therefore I'd
agree with Thomas view on this - not so much that promoting them is
pointless, but I'd actually view it as harmful in encouraging use that will
be broken in future.

/Bruce
Kinsella, Ray Oct. 13, 2021, 11:42 a.m. UTC | #15
On 13/10/2021 12:11, Bruce Richardson wrote:
> On Wed, Oct 13, 2021 at 11:02:02AM +0100, Kinsella, Ray wrote:
>>
>>
>> On 13/10/2021 10:49, Thomas Monjalon wrote:
>>> 13/10/2021 11:43, Kinsella, Ray:
>>>> On 13/10/2021 10:40, Thomas Monjalon wrote:
>>>>> 13/10/2021 10:51, Kinsella, Ray:
>>>>>> On 12/10/2021 22:52, Thomas Monjalon wrote:
>>>>>>> 12/10/2021 22:34, Dumitrescu, Cristian:
>>>>>>>> From: Thomas Monjalon <thomas@monjalon.net>
>>>>>>>>> 01/09/2021 14:20, Jasvinder Singh:
>>>>>>>>>> These APIs were introduced in 18.05, therefore removing
>>>>>>>>>> experimental tag to promote them to stable state.
>>>>>>>>>>
>>>>>>>>>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
>>>>>>>>>> ---
>>>>>>>>>>  lib/pipeline/rte_port_in_action.h | 10 ----------
>>>>>>>>>>  lib/pipeline/rte_table_action.h   | 18 ------------------
>>>>>>>>>>  lib/pipeline/version.map          | 16 ++++++----------
>>>>>>>>>>  3 files changed, 6 insertions(+), 38 deletions(-)
>>>>>>>>>
>>>>>>>>> Cristian, please can you check whether you intend to keep these functions in
>>>>>>>>> future?
>>>>>>>>> If they are candidate to be removed, there is no point to promote them.
>>>>>>>>
>>>>>>>> Hi Thomas,
>>>>>>>>
>>>>>>>> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
>>>>>>>>
>>>>>>>> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
>>>>>>>>
>>>>>>>> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
>>>>>>>>
>>>>>>>> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.
>>>>>>>
>>>>>>> I think we should not promote API that we know will disappear soon.
>>>>>>> The stable status means something for the users.
>>>>>>> Ray, what is your opinion?
>>>>>>>
>>>>>>
>>>>>> Well - I agree with Cristian (he and I discuss this a few weeks ago).
>>>>>> My position is if you are going to maintain an API, that means giving a few guarantees.
>>>>>> The API's have been experimental for 3 years ... at what point do they mature?
>>>>>>
>>>>>> However, I agree there is two ways to look at this thing, I try to be pragmatic. 
>>>>>> Maturing of any ABI/API is a conversation between a maintainer and the contributor.
>>>>>> If they strongly feel, it is a pointless exercise - I won't argue. 
>>>>>
>>>>> I think you did't get it.
>>>>> This API will be removed soon.
>>>>> That's why I think it doesn't make sense to make them stable, just before removing.
>>>>>
>>>>
>>>> Nope, I got it 110%
>>>> I reflected both my opinion as ABI Maintainer, and tried to be pragmatic about the situation.
>>>>
>>>> As I said "Maturing of any ABI/API is a conversation between a maintainer and the contributor.
>>>> If they strongly feel, it is a pointless exercise - I won't argue."
>>>
>>> Sorry, I don't understand your position.
>>> Do you think we should promote functions to stable which are candidate to be removed soon?
>>>
>>
>> I am just reflecting the policy here.
>>
>> "An API’s experimental status should be reviewed annually, by both the maintainer and/or the original contributor. Ordinarily APIs marked as experimental will be promoted to the stable ABI once a maintainer has become satisfied that the API is mature and is unlikely to change."
>>
> If an API is planned for removal, then I think it falls under the bucket of
> "likely to change", so should not be made non-experimental. Therefore I'd
> agree with Thomas view on this - not so much that promoting them is
> pointless, but I'd actually view it as harmful in encouraging use that will
> be broken in future.
> 

To be clear (again).

I don't think we should promote functions needlessly, as I said, if others decide it is pointless, I won't argue.  
I do think if we have a policy, that experimental symbols will mature or be removed, we should be careful about the exceptions we make, lest the policy becomes irrelevant and ignored. 

Since we have argued this out, endlessly ... we can agree, we have been careful about this exception and move on?

Ray K
Thomas Monjalon Oct. 13, 2021, 11:58 a.m. UTC | #16
13/10/2021 13:42, Kinsella, Ray:
> On 13/10/2021 12:11, Bruce Richardson wrote:
> > On Wed, Oct 13, 2021 at 11:02:02AM +0100, Kinsella, Ray wrote:
> >> On 13/10/2021 10:49, Thomas Monjalon wrote:
> >>> 13/10/2021 11:43, Kinsella, Ray:
> >>>> On 13/10/2021 10:40, Thomas Monjalon wrote:
> >>>>> 13/10/2021 10:51, Kinsella, Ray:
> >>>>>> On 12/10/2021 22:52, Thomas Monjalon wrote:
> >>>>>>> 12/10/2021 22:34, Dumitrescu, Cristian:
> >>>>>>>> From: Thomas Monjalon <thomas@monjalon.net>
> >>>>>>>>> 01/09/2021 14:20, Jasvinder Singh:
> >>>>>>>>>> These APIs were introduced in 18.05, therefore removing
> >>>>>>>>>> experimental tag to promote them to stable state.
> >>>>>>>>>>
> >>>>>>>>>> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> >>>>>>>>>> ---
> >>>>>>>>>>  lib/pipeline/rte_port_in_action.h | 10 ----------
> >>>>>>>>>>  lib/pipeline/rte_table_action.h   | 18 ------------------
> >>>>>>>>>>  lib/pipeline/version.map          | 16 ++++++----------
> >>>>>>>>>>  3 files changed, 6 insertions(+), 38 deletions(-)
> >>>>>>>>>
> >>>>>>>>> Cristian, please can you check whether you intend to keep these functions in
> >>>>>>>>> future?
> >>>>>>>>> If they are candidate to be removed, there is no point to promote them.
> >>>>>>>>
> >>>>>>>> Hi Thomas,
> >>>>>>>>
> >>>>>>>> Yes, they are candidate for removal, as the new rte_swx_pipeline API evolves.
> >>>>>>>>
> >>>>>>>> But removing them requires updating the drivers/net/softnic code to use the new API, which is not going to be completed in time for release 21.11.
> >>>>>>>>
> >>>>>>>> So given this lag, it might be better to simply promote these functions to stable API now, as Ray suggests, instead of continuing to keep them experimental; then, once these functions are no longer used, then we can remove them, most likely in 22.11.
> >>>>>>>>
> >>>>>>>> So I will ack these patches, but I am willing to reconsider if you feel strongly against this approach.
> >>>>>>>
> >>>>>>> I think we should not promote API that we know will disappear soon.
> >>>>>>> The stable status means something for the users.
> >>>>>>> Ray, what is your opinion?
> >>>>>>>
> >>>>>>
> >>>>>> Well - I agree with Cristian (he and I discuss this a few weeks ago).
> >>>>>> My position is if you are going to maintain an API, that means giving a few guarantees.
> >>>>>> The API's have been experimental for 3 years ... at what point do they mature?
> >>>>>>
> >>>>>> However, I agree there is two ways to look at this thing, I try to be pragmatic. 
> >>>>>> Maturing of any ABI/API is a conversation between a maintainer and the contributor.
> >>>>>> If they strongly feel, it is a pointless exercise - I won't argue. 
> >>>>>
> >>>>> I think you did't get it.
> >>>>> This API will be removed soon.
> >>>>> That's why I think it doesn't make sense to make them stable, just before removing.
> >>>>>
> >>>>
> >>>> Nope, I got it 110%
> >>>> I reflected both my opinion as ABI Maintainer, and tried to be pragmatic about the situation.
> >>>>
> >>>> As I said "Maturing of any ABI/API is a conversation between a maintainer and the contributor.
> >>>> If they strongly feel, it is a pointless exercise - I won't argue."
> >>>
> >>> Sorry, I don't understand your position.
> >>> Do you think we should promote functions to stable which are candidate to be removed soon?
> >>>
> >>
> >> I am just reflecting the policy here.
> >>
> >> "An API’s experimental status should be reviewed annually, by both the maintainer and/or the original contributor. Ordinarily APIs marked as experimental will be promoted to the stable ABI once a maintainer has become satisfied that the API is mature and is unlikely to change."
> >>
> > If an API is planned for removal, then I think it falls under the bucket of
> > "likely to change", so should not be made non-experimental. Therefore I'd
> > agree with Thomas view on this - not so much that promoting them is
> > pointless, but I'd actually view it as harmful in encouraging use that will
> > be broken in future.
> > 
> 
> To be clear (again).
> 
> I don't think we should promote functions needlessly, as I said, if others decide it is pointless, I won't argue.  
> I do think if we have a policy, that experimental symbols will mature or be removed, we should be careful about the exceptions we make, lest the policy becomes irrelevant and ignored. 
> 
> Since we have argued this out, endlessly ... we can agree, we have been careful about this exception and move on?

The patch is set as rejected.
diff mbox series

Patch

diff --git a/lib/pipeline/rte_port_in_action.h b/lib/pipeline/rte_port_in_action.h
index d6b063cf58..de611cbfab 100644
--- a/lib/pipeline/rte_port_in_action.h
+++ b/lib/pipeline/rte_port_in_action.h
@@ -42,8 +42,6 @@ 
  *    used by the input port action handler based on given action parameters.
  *    API functions: rte_port_in_action_apply().
  *
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
  */
 
 #ifdef __cplusplus
@@ -172,7 +170,6 @@  struct rte_port_in_action_profile;
  * @return
  *   Input port action profile handle on success, NULL otherwise.
  */
-__rte_experimental
 struct rte_port_in_action_profile *
 rte_port_in_action_profile_create(uint32_t socket_id);
 
@@ -184,7 +181,6 @@  rte_port_in_action_profile_create(uint32_t socket_id);
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_port_in_action_profile_free(struct rte_port_in_action_profile *profile);
 
@@ -203,7 +199,6 @@  rte_port_in_action_profile_free(struct rte_port_in_action_profile *profile);
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_port_in_action_profile_action_register(
 	struct rte_port_in_action_profile *profile,
@@ -226,7 +221,6 @@  rte_port_in_action_profile_action_register(
  *
  * @see rte_port_in_action_create()
  */
-__rte_experimental
 int
 rte_port_in_action_profile_freeze(struct rte_port_in_action_profile *profile);
 
@@ -249,7 +243,6 @@  struct rte_port_in_action;
  * @return
  *   Handle to input port action object on success, NULL on error.
  */
-__rte_experimental
 struct rte_port_in_action *
 rte_port_in_action_create(struct rte_port_in_action_profile *profile,
 	uint32_t socket_id);
@@ -262,7 +255,6 @@  rte_port_in_action_create(struct rte_port_in_action_profile *profile,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_port_in_action_free(struct rte_port_in_action *action);
 
@@ -276,7 +268,6 @@  rte_port_in_action_free(struct rte_port_in_action *action);
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_port_in_action_params_get(struct rte_port_in_action *action,
 	struct rte_pipeline_port_in_params *params);
@@ -296,7 +287,6 @@  rte_port_in_action_params_get(struct rte_port_in_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_port_in_action_apply(struct rte_port_in_action *action,
 	enum rte_port_in_action_type type,
diff --git a/lib/pipeline/rte_table_action.h b/lib/pipeline/rte_table_action.h
index 82bc9d9ac9..aac6b8ce8d 100644
--- a/lib/pipeline/rte_table_action.h
+++ b/lib/pipeline/rte_table_action.h
@@ -48,8 +48,6 @@ 
  *  - Use the table action object to read action data (e.g. stats counters) for
  *    any given rule. API functions: rte_table_action_XYZ_read().
  *
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
  */
 
 #ifdef __cplusplus
@@ -823,7 +821,6 @@  struct rte_table_action_profile;
  * @return
  *   Table action profile handle on success, NULL otherwise.
  */
-__rte_experimental
 struct rte_table_action_profile *
 rte_table_action_profile_create(struct rte_table_action_common_config *common);
 
@@ -835,7 +832,6 @@  rte_table_action_profile_create(struct rte_table_action_common_config *common);
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_profile_free(struct rte_table_action_profile *profile);
 
@@ -854,7 +850,6 @@  rte_table_action_profile_free(struct rte_table_action_profile *profile);
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_profile_action_register(struct rte_table_action_profile *profile,
 	enum rte_table_action_type type,
@@ -875,7 +870,6 @@  rte_table_action_profile_action_register(struct rte_table_action_profile *profil
  *
  * @see rte_table_action_create()
  */
-__rte_experimental
 int
 rte_table_action_profile_freeze(struct rte_table_action_profile *profile);
 
@@ -899,7 +893,6 @@  struct rte_table_action;
  *
  * @see rte_table_action_create()
  */
-__rte_experimental
 struct rte_table_action *
 rte_table_action_create(struct rte_table_action_profile *profile,
 	uint32_t socket_id);
@@ -912,7 +905,6 @@  rte_table_action_create(struct rte_table_action_profile *profile,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_free(struct rte_table_action *action);
 
@@ -926,7 +918,6 @@  rte_table_action_free(struct rte_table_action *action);
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_table_params_get(struct rte_table_action *action,
 	struct rte_pipeline_table_params *params);
@@ -949,7 +940,6 @@  rte_table_action_table_params_get(struct rte_table_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_apply(struct rte_table_action *action,
 	void *data,
@@ -969,7 +959,6 @@  rte_table_action_apply(struct rte_table_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_dscp_table_update(struct rte_table_action *action,
 	uint64_t dscp_mask,
@@ -989,7 +978,6 @@  rte_table_action_dscp_table_update(struct rte_table_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_meter_profile_add(struct rte_table_action *action,
 	uint32_t meter_profile_id,
@@ -1006,7 +994,6 @@  rte_table_action_meter_profile_add(struct rte_table_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_meter_profile_delete(struct rte_table_action *action,
 	uint32_t meter_profile_id);
@@ -1038,7 +1025,6 @@  rte_table_action_meter_profile_delete(struct rte_table_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_meter_read(struct rte_table_action *action,
 	void *data,
@@ -1065,7 +1051,6 @@  rte_table_action_meter_read(struct rte_table_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_ttl_read(struct rte_table_action *action,
 	void *data,
@@ -1091,7 +1076,6 @@  rte_table_action_ttl_read(struct rte_table_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_stats_read(struct rte_table_action *action,
 	void *data,
@@ -1112,7 +1096,6 @@  rte_table_action_stats_read(struct rte_table_action *action,
  * @return
  *   Zero on success, non-zero error code otherwise.
  */
-__rte_experimental
 int
 rte_table_action_time_read(struct rte_table_action *action,
 	void *data,
@@ -1128,7 +1111,6 @@  rte_table_action_time_read(struct rte_table_action *action,
  * @return
  *   The pointer to the session on success, NULL otherwise.
  */
-__rte_experimental
 struct rte_cryptodev_sym_session *
 rte_table_action_crypto_sym_session_get(struct rte_table_action *action,
 	void *data);
diff --git a/lib/pipeline/version.map b/lib/pipeline/version.map
index 2b68f584a4..5732fac16b 100644
--- a/lib/pipeline/version.map
+++ b/lib/pipeline/version.map
@@ -24,14 +24,6 @@  DPDK_22 {
 	rte_pipeline_table_entry_delete;
 	rte_pipeline_table_entry_delete_bulk;
 	rte_pipeline_table_stats_read;
-
-	local: *;
-};
-
-EXPERIMENTAL {
-	global:
-
-	# added in 18.05
 	rte_port_in_action_apply;
 	rte_port_in_action_create;
 	rte_port_in_action_free;
@@ -55,10 +47,14 @@  EXPERIMENTAL {
 	rte_table_action_table_params_get;
 	rte_table_action_time_read;
 	rte_table_action_ttl_read;
-
-	# added in 18.11
 	rte_table_action_crypto_sym_session_get;
 
+	local: *;
+};
+
+EXPERIMENTAL {
+	global:
+
 	# added in 20.11
 	rte_swx_ctl_action_arg_info_get;
 	rte_swx_ctl_action_info_get;