Re: [dpdk-dev] [PATCH] stack: remove experimental tag from API

["Kinsella, Ray" <mdr@ashroe.eu>]

A nit and some questions below, thanks Ray K.

On 30/09/2020 22:39, 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.11 major version.
> 
> Signed-off-by: Gage Eads <gage.eads@intel.com>
> Acked-by: David Marchand <david.marchand@redhat.com>
> ---
>  doc/guides/rel_notes/release_20_11.rst |  3 +++
>  lib/librte_stack/rte_stack.h           | 32 --------------------------------
>  lib/librte_stack/rte_stack_lf.h        |  2 --
>  lib/librte_stack/rte_stack_std.h       |  3 ---
>  lib/librte_stack/rte_stack_version.map |  2 +-
>  5 files changed, 4 insertions(+), 38 deletions(-)
NIT: You are missing the v3 in the subject line, doesn't require a fix. 

> 
> v3:
> - Rebase on top of main.
> - Move release notes comment to the API changes section.
> 
> v2:
> - Added 20.11 tag, will set patch status to 'Deferred' so it is skipped
>   for the 20.08 development period.
> - Added release notes announcement. release_20_11.rst doesn't exist yet,
>   so I made the change to release_20_08.rst then edited the filename
>   directly in the patch. This will not apply cleanly.
> - Changed rte_stack_version.map version to DPDK_21.
> 
> diff --git a/doc/guides/rel_notes/release_20_11.rst b/doc/guides/rel_notes/release_20_11.rst
> index 4eb3224a7..0b8cdd920 100644
> --- a/doc/guides/rel_notes/release_20_11.rst
> +++ b/doc/guides/rel_notes/release_20_11.rst
> @@ -170,6 +170,9 @@ API Changes
>    and the function ``rte_rawdev_queue_conf_get()``
>    from ``void`` to ``int`` allowing the return of error codes from drivers.
>  
> +* stack: the experimental tag has been dropped from the stack library, and its
> +  interfaces are considered stable as of DPDK 20.11.
> +
>  * bpf: ``RTE_BPF_XTYPE_NUM`` has been dropped from ``rte_bpf_xtype``.
>  
>  
> diff --git a/lib/librte_stack/rte_stack.h b/lib/librte_stack/rte_stack.h
> index abf642076..395b9ef83 100644
> --- a/lib/librte_stack/rte_stack.h
> +++ b/lib/librte_stack/rte_stack.h
> @@ -7,10 +7,6 @@
>   *
>   * RTE Stack.
>   *
> - * @warning
> - * @b EXPERIMENTAL:
> - * All functions in this file may be changed or removed without prior notice.
> - *
>   * librte_stack provides an API for configuration and use of a bounded stack of
>   * pointers. Push and pop operations are MT-safe, allowing concurrent access,
>   * and the interface supports pushing and popping multiple pointers at a time.
> @@ -101,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
> @@ -115,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)
>  {
> @@ -129,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
> @@ -143,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)
>  {
> @@ -157,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
> @@ -167,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)
>  {
> @@ -180,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
> @@ -190,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)
>  {
> @@ -200,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
> @@ -229,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
> @@ -261,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

This looks like an internal function, should it be __rte_internal?

>  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

This looks like an internal function, should it be __rte_internal?

>  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

This looks like an internal function, should it be __rte_internal?

>  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

This looks like an internal function, should it be __rte_internal?

>  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..8c4ca0245 100644
> --- a/lib/librte_stack/rte_stack_version.map
> +++ b/lib/librte_stack/rte_stack_version.map
> @@ -1,4 +1,4 @@
> -EXPERIMENTAL {
> +DPDK_21 {
>  	global:
>  
>  	rte_stack_create;
>