stack: remove experimental tag from API
diff mbox series

Message ID 20200528010423.5941-1-gage.eads@intel.com
State Superseded, archived
Delegated to: David Marchand
Headers show
Series
  • stack: remove experimental tag from API
Related show

Checks

Context Check Description
ci/Intel-compilation success Compilation OK
ci/iol-testing warning Testing issues
ci/iol-mellanox-Performance success Performance Testing PASS
ci/travis-robot success Travis build: passed
ci/iol-nxp-Performance success Performance Testing PASS
ci/iol-intel-Performance success Performance Testing PASS
ci/checkpatch success coding style OK

Commit Message

Eads, Gage May 28, 2020, 1:04 a.m. UTC
The stack library was first released in 19.05, and its interfaces have been
stable since their initial introduction. This commit promotes the full
interface to stable, starting with the 20.08 ABI.

Signed-off-by: Gage Eads <gage.eads@intel.com>
---
 lib/librte_stack/rte_stack.h           | 29 -----------------------------
 lib/librte_stack/rte_stack_lf.h        |  2 --
 lib/librte_stack/rte_stack_std.h       |  3 ---
 lib/librte_stack/rte_stack_version.map |  2 +-
 4 files changed, 1 insertion(+), 35 deletions(-)

Comments

Kinsella, Ray May 28, 2020, 5:46 a.m. UTC | #1
Hi Gage,

Do you have any idea.
If the change from experimental to stable symbol is likely to break anyone's application?
(are folks actively using the api with shared libraries)

If so, you _may_ consider offering a temporary alias to experimental until the v21 is declared at 20.11.
This is entirely at your discretion, see
https://doc.dpdk.org/guides/contributing/abi_versioning.html (4.3.1.4)

Please see my additional comments on the map file below.

On 28/05/2020 02:04, Gage Eads wrote:
> The stack library was first released in 19.05, and its interfaces have been
> stable since their initial introduction. This commit promotes the full
> interface to stable, starting with the 20.08 ABI.
> 
> Signed-off-by: Gage Eads <gage.eads@intel.com>
> ---
>  lib/librte_stack/rte_stack.h           | 29 -----------------------------
>  lib/librte_stack/rte_stack_lf.h        |  2 --
>  lib/librte_stack/rte_stack_std.h       |  3 ---
>  lib/librte_stack/rte_stack_version.map |  2 +-
>  4 files changed, 1 insertion(+), 35 deletions(-)
> 
> diff --git a/lib/librte_stack/rte_stack.h b/lib/librte_stack/rte_stack.h
> index 27ddb199e..343dd019a 100644
> --- a/lib/librte_stack/rte_stack.h
> +++ b/lib/librte_stack/rte_stack.h
> @@ -4,7 +4,6 @@
>  
>  /**
>   * @file rte_stack.h
> - * @b EXPERIMENTAL: this API may change without prior notice
>   *
>   * RTE Stack
>   *
> @@ -98,9 +97,6 @@ struct rte_stack {
>  #include "rte_stack_lf.h"
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Push several objects on the stack (MT-safe).
>   *
>   * @param s
> @@ -112,7 +108,6 @@ struct rte_stack {
>   * @return
>   *   Actual number of objects pushed (either 0 or *n*).
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
>  {
> @@ -126,9 +121,6 @@ rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Pop several objects from the stack (MT-safe).
>   *
>   * @param s
> @@ -140,7 +132,6 @@ rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
>   * @return
>   *   Actual number of objects popped (either 0 or *n*).
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
>  {
> @@ -154,9 +145,6 @@ rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Return the number of used entries in a stack.
>   *
>   * @param s
> @@ -164,7 +152,6 @@ rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
>   * @return
>   *   The number of used entries in the stack.
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  rte_stack_count(struct rte_stack *s)
>  {
> @@ -177,9 +164,6 @@ rte_stack_count(struct rte_stack *s)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Return the number of free entries in a stack.
>   *
>   * @param s
> @@ -187,7 +171,6 @@ rte_stack_count(struct rte_stack *s)
>   * @return
>   *   The number of free entries in the stack.
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  rte_stack_free_count(struct rte_stack *s)
>  {
> @@ -197,9 +180,6 @@ rte_stack_free_count(struct rte_stack *s)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Create a new stack named *name* in memory.
>   *
>   * This function uses ``memzone_reserve()`` to allocate memory for a stack of
> @@ -226,28 +206,20 @@ rte_stack_free_count(struct rte_stack *s)
>   *    - ENOMEM - insufficient memory to create the stack
>   *    - ENAMETOOLONG - name size exceeds RTE_STACK_NAMESIZE
>   */
> -__rte_experimental
>  struct rte_stack *
>  rte_stack_create(const char *name, unsigned int count, int socket_id,
>  		 uint32_t flags);
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Free all memory used by the stack.
>   *
>   * @param s
>   *   Stack to free
>   */
> -__rte_experimental
>  void
>  rte_stack_free(struct rte_stack *s);
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Lookup a stack by its name.
>   *
>   * @param name
> @@ -258,7 +230,6 @@ rte_stack_free(struct rte_stack *s);
>   *    - ENOENT - Stack with name *name* not found.
>   *    - EINVAL - *name* pointer is NULL.
>   */
> -__rte_experimental
>  struct rte_stack *
>  rte_stack_lookup(const char *name);
>  
> diff --git a/lib/librte_stack/rte_stack_lf.h b/lib/librte_stack/rte_stack_lf.h
> index e67630c27..eb106e64e 100644
> --- a/lib/librte_stack/rte_stack_lf.h
> +++ b/lib/librte_stack/rte_stack_lf.h
> @@ -27,7 +27,6 @@
>   * @return
>   *   Actual number of objects enqueued.
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  __rte_stack_lf_push(struct rte_stack *s,
>  		    void * const *obj_table,
> @@ -66,7 +65,6 @@ __rte_stack_lf_push(struct rte_stack *s,
>   * @return
>   *   - Actual number of objects popped.
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  __rte_stack_lf_pop(struct rte_stack *s, void **obj_table, unsigned int n)
>  {
> diff --git a/lib/librte_stack/rte_stack_std.h b/lib/librte_stack/rte_stack_std.h
> index 7142cbf8e..ae28add5c 100644
> --- a/lib/librte_stack/rte_stack_std.h
> +++ b/lib/librte_stack/rte_stack_std.h
> @@ -19,7 +19,6 @@
>   * @return
>   *   Actual number of objects pushed (either 0 or *n*).
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  __rte_stack_std_push(struct rte_stack *s, void * const *obj_table,
>  		     unsigned int n)
> @@ -59,7 +58,6 @@ __rte_stack_std_push(struct rte_stack *s, void * const *obj_table,
>   * @return
>   *   Actual number of objects popped (either 0 or *n*).
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  __rte_stack_std_pop(struct rte_stack *s, void **obj_table, unsigned int n)
>  {
> @@ -94,7 +92,6 @@ __rte_stack_std_pop(struct rte_stack *s, void **obj_table, unsigned int n)
>   * @return
>   *   The number of used entries in the stack.
>   */
> -__rte_experimental
>  static __rte_always_inline unsigned int
>  __rte_stack_std_count(struct rte_stack *s)
>  {
> diff --git a/lib/librte_stack/rte_stack_version.map b/lib/librte_stack/rte_stack_version.map
> index 6662679c3..22c703d3b 100644
> --- a/lib/librte_stack/rte_stack_version.map
> +++ b/lib/librte_stack/rte_stack_version.map
> @@ -1,4 +1,4 @@
> -EXPERIMENTAL {
> +DPDK_20.0.3 {
>  	global:
>  
>  	rte_stack_create;
> 

Should be DPDK_21, the next major ABI version is v21.
Thomas Monjalon May 28, 2020, 8:10 a.m. UTC | #2
28/05/2020 07:46, Ray Kinsella:
> Hi Gage,
> 
> Do you have any idea.
> If the change from experimental to stable symbol is likely to break anyone's application?
> (are folks actively using the api with shared libraries)
> 
> If so, you _may_ consider offering a temporary alias to experimental until the v21 is declared at 20.11.
> This is entirely at your discretion, see
> https://doc.dpdk.org/guides/contributing/abi_versioning.html (4.3.1.4)

Or we can wait 20.11.

Anyway I think it deserves a comment in the release notes (API section).
Kinsella, Ray May 28, 2020, 8:22 a.m. UTC | #3
On 28/05/2020 09:10, Thomas Monjalon wrote:
> Anyway I think it deserves a comment in the release notes (API section).

agreed
Eads, Gage May 28, 2020, 2:18 p.m. UTC | #4
> -----Original Message-----
> From: Thomas Monjalon <thomas@monjalon.net>
> Sent: Thursday, May 28, 2020 3:11 AM
> To: Eads, Gage <gage.eads@intel.com>; Ray Kinsella <mdr@ashroe.eu>
> Cc: dev@dpdk.org; david.marchand@redhat.com; nhorman@tuxdriver.com;
> phil.yang@arm.com; honnappa.nagarahalli@arm.com;
> olivier.matz@6wind.com
> Subject: Re: [PATCH] stack: remove experimental tag from API
> 
> 28/05/2020 07:46, Ray Kinsella:
> > Hi Gage,
> >
> > Do you have any idea.
> > If the change from experimental to stable symbol is likely to break anyone's
> application?
> > (are folks actively using the api with shared libraries)

Good question. I don't have a good sense of the active users, so I'd rather play it safe.

> >
> > If so, you _may_ consider offering a temporary alias to experimental until the
> v21 is declared at 20.11.
> > This is entirely at your discretion, see
> > https://doc.dpdk.org/guides/contributing/abi_versioning.html (4.3.1.4)
> 
> Or we can wait 20.11.
> 

That works. I have no urgency to get this into 20.08 in particular.

> Anyway I think it deserves a comment in the release notes (API section).
>  

Ok, if there are no objections then I'll re-submit this patchset in a few months and include a release notes comment.

Thanks,
Gage
Bruce Richardson May 28, 2020, 2:33 p.m. UTC | #5
On Thu, May 28, 2020 at 02:18:32PM +0000, Eads, Gage wrote:
> 
> 
> > -----Original Message-----
> > From: Thomas Monjalon <thomas@monjalon.net>
> > Sent: Thursday, May 28, 2020 3:11 AM
> > To: Eads, Gage <gage.eads@intel.com>; Ray Kinsella <mdr@ashroe.eu>
> > Cc: dev@dpdk.org; david.marchand@redhat.com; nhorman@tuxdriver.com;
> > phil.yang@arm.com; honnappa.nagarahalli@arm.com;
> > olivier.matz@6wind.com
> > Subject: Re: [PATCH] stack: remove experimental tag from API
> > 
> > 28/05/2020 07:46, Ray Kinsella:
> > > Hi Gage,
> > >
> > > Do you have any idea.
> > > If the change from experimental to stable symbol is likely to break anyone's
> > application?
> > > (are folks actively using the api with shared libraries)
> 
> Good question. I don't have a good sense of the active users, so I'd rather play it safe.
> 
> > >
> > > If so, you _may_ consider offering a temporary alias to experimental until the
> > v21 is declared at 20.11.
> > > This is entirely at your discretion, see
> > > https://doc.dpdk.org/guides/contributing/abi_versioning.html (4.3.1.4)
> > 
> > Or we can wait 20.11.
> > 
> 
> That works. I have no urgency to get this into 20.08 in particular.
> 
> > Anyway I think it deserves a comment in the release notes (API section).
> >  
> 
> Ok, if there are no objections then I'll re-submit this patchset in a few months and include a release notes comment.
> 
Or just resubmit with a 20.11 tag on it, and then mark it as "deferred" in
patchwork, so it pops up automatically for disposition again at the end of
the 20.08 cycle?

/Bruce

Patch
diff mbox series

diff --git a/lib/librte_stack/rte_stack.h b/lib/librte_stack/rte_stack.h
index 27ddb199e..343dd019a 100644
--- a/lib/librte_stack/rte_stack.h
+++ b/lib/librte_stack/rte_stack.h
@@ -4,7 +4,6 @@ 
 
 /**
  * @file rte_stack.h
- * @b EXPERIMENTAL: this API may change without prior notice
  *
  * RTE Stack
  *
@@ -98,9 +97,6 @@  struct rte_stack {
 #include "rte_stack_lf.h"
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Push several objects on the stack (MT-safe).
  *
  * @param s
@@ -112,7 +108,6 @@  struct rte_stack {
  * @return
  *   Actual number of objects pushed (either 0 or *n*).
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
 {
@@ -126,9 +121,6 @@  rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Pop several objects from the stack (MT-safe).
  *
  * @param s
@@ -140,7 +132,6 @@  rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
  * @return
  *   Actual number of objects popped (either 0 or *n*).
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
 {
@@ -154,9 +145,6 @@  rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Return the number of used entries in a stack.
  *
  * @param s
@@ -164,7 +152,6 @@  rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
  * @return
  *   The number of used entries in the stack.
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 rte_stack_count(struct rte_stack *s)
 {
@@ -177,9 +164,6 @@  rte_stack_count(struct rte_stack *s)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Return the number of free entries in a stack.
  *
  * @param s
@@ -187,7 +171,6 @@  rte_stack_count(struct rte_stack *s)
  * @return
  *   The number of free entries in the stack.
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 rte_stack_free_count(struct rte_stack *s)
 {
@@ -197,9 +180,6 @@  rte_stack_free_count(struct rte_stack *s)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Create a new stack named *name* in memory.
  *
  * This function uses ``memzone_reserve()`` to allocate memory for a stack of
@@ -226,28 +206,20 @@  rte_stack_free_count(struct rte_stack *s)
  *    - ENOMEM - insufficient memory to create the stack
  *    - ENAMETOOLONG - name size exceeds RTE_STACK_NAMESIZE
  */
-__rte_experimental
 struct rte_stack *
 rte_stack_create(const char *name, unsigned int count, int socket_id,
 		 uint32_t flags);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Free all memory used by the stack.
  *
  * @param s
  *   Stack to free
  */
-__rte_experimental
 void
 rte_stack_free(struct rte_stack *s);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Lookup a stack by its name.
  *
  * @param name
@@ -258,7 +230,6 @@  rte_stack_free(struct rte_stack *s);
  *    - ENOENT - Stack with name *name* not found.
  *    - EINVAL - *name* pointer is NULL.
  */
-__rte_experimental
 struct rte_stack *
 rte_stack_lookup(const char *name);
 
diff --git a/lib/librte_stack/rte_stack_lf.h b/lib/librte_stack/rte_stack_lf.h
index e67630c27..eb106e64e 100644
--- a/lib/librte_stack/rte_stack_lf.h
+++ b/lib/librte_stack/rte_stack_lf.h
@@ -27,7 +27,6 @@ 
  * @return
  *   Actual number of objects enqueued.
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 __rte_stack_lf_push(struct rte_stack *s,
 		    void * const *obj_table,
@@ -66,7 +65,6 @@  __rte_stack_lf_push(struct rte_stack *s,
  * @return
  *   - Actual number of objects popped.
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 __rte_stack_lf_pop(struct rte_stack *s, void **obj_table, unsigned int n)
 {
diff --git a/lib/librte_stack/rte_stack_std.h b/lib/librte_stack/rte_stack_std.h
index 7142cbf8e..ae28add5c 100644
--- a/lib/librte_stack/rte_stack_std.h
+++ b/lib/librte_stack/rte_stack_std.h
@@ -19,7 +19,6 @@ 
  * @return
  *   Actual number of objects pushed (either 0 or *n*).
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 __rte_stack_std_push(struct rte_stack *s, void * const *obj_table,
 		     unsigned int n)
@@ -59,7 +58,6 @@  __rte_stack_std_push(struct rte_stack *s, void * const *obj_table,
  * @return
  *   Actual number of objects popped (either 0 or *n*).
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 __rte_stack_std_pop(struct rte_stack *s, void **obj_table, unsigned int n)
 {
@@ -94,7 +92,6 @@  __rte_stack_std_pop(struct rte_stack *s, void **obj_table, unsigned int n)
  * @return
  *   The number of used entries in the stack.
  */
-__rte_experimental
 static __rte_always_inline unsigned int
 __rte_stack_std_count(struct rte_stack *s)
 {
diff --git a/lib/librte_stack/rte_stack_version.map b/lib/librte_stack/rte_stack_version.map
index 6662679c3..22c703d3b 100644
--- a/lib/librte_stack/rte_stack_version.map
+++ b/lib/librte_stack/rte_stack_version.map
@@ -1,4 +1,4 @@ 
-EXPERIMENTAL {
+DPDK_20.0.3 {
 	global:
 
 	rte_stack_create;