stack: remove experimental tag from API
PATCH 1/1 stack: remove experimental tag from API
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.
--- 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(-)
lib/librte_stack/rte_stack.h +0 -29
@@ -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 intrte_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 intrte_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 intrte_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 intrte_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);
lib/librte_stack/rte_stack_lf.h +0 -2
@@ -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) {
lib/librte_stack/rte_stack_std.h +0 -3
@@ -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) {
lib/librte_stack/rte_stack_version.map +1 -1
@@ -1,4 +1,4 @@ -EXPERIMENTAL { +DPDK_20.0.3 { global: rte_stack_create;
Signature · 1 line
2.13.6
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.
Quoted 197 lines · Gage Eads
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 <[email protected]>--- 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(-)lib/librte_stack/rte_stack.h +0
-29@@ -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 intrte_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 intrte_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 intrte_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 intrte_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);lib/librte_stack/rte_stack_lf.h +0
-2@@ -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) {lib/librte_stack/rte_stack_std.h +0
-3@@ -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) {lib/librte_stack/rte_stack_version.map +0
-0
lib/librte_stack/rte_stack_version.map line 4
Quoted 5 lines
lib/librte_stack/rte_stack_version.map +1
-1@@ -1,4 +1,4 @@ -EXPERIMENTAL { +DPDK_20.0.3 { global: rte_stack_create;
Should be DPDK_21, the next major ABI version is v21.
28/05/2020 07:46, Ray Kinsella:
Quoted 9 lines
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).
Quoted 1 line · Thomas Monjalon
Anyway I think it deserves a comment in the release notes (API section).
agreed
Quoted 11 lines
-----Original Message-----
From: Thomas Monjalon <[email protected]>
Sent: Thursday, May 28, 2020 3:11 AM
To: Eads, Gage <[email protected]>; Ray Kinsella <[email protected]>
Cc: [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]
Subject: Re: [PATCH] stack: remove experimental tag from API
Quoted 7 lines
28/05/2020 07:46, Ray Kinsella:
Quoted 4 lines
Hi Gage,
Do you have any idea.
If the change from experimental to stable symbol is likely to break anyone'sapplication?
Quoted 1 line
(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.
Quoted 8 lines
Quoted 2 lines
If so, you _may_ consider offering a temporary alias to experimental until the
v21 is declared at 20.11.
Quoted 2 lines
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.
Quoted 2 lines
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
Quoted 30 lines · Gage
Quoted 11 lines
-----Original Message-----
From: Thomas Monjalon <[email protected]>
Sent: Thursday, May 28, 2020 3:11 AM
To: Eads, Gage <[email protected]>; Ray Kinsella <[email protected]>
Cc: [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]
Subject: Re: [PATCH] stack: remove experimental tag from APIQuoted 7 lines
28/05/2020 07:46, Ray Kinsella:
Quoted 4 lines
Hi Gage,
Do you have any idea.
If the change from experimental to stable symbol is likely to break anyone'sapplication?
Quoted 1 line
(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.
Quoted 8 lines
Quoted 2 lines
If so, you _may_ consider offering a temporary alias to experimental until the
v21 is declared at 20.11.
Quoted 2 lines
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.
Quoted 7 lines
That works. I have no urgency to get this into 20.08 in particular.
Quoted 2 lines
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
[dpdk-dev] [20.11] [PATCH v2] stack: remove experimental tag from API
In reply to Gage EadsThe 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.
--- doc/guides/rel_notes/release_20_11.rst | 3 +++ 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 +- 5 files changed, 4 insertions(+), 35 deletions(-)
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.
doc/guides/rel_notes/release_20_11.rst +3 -0
@@ -101,6 +101,9 @@ ABI Changes Also, make sure to start the actual text at the margin. ========================================================= +* stack: the experimental tag has been dropped from the stack library, and its + interfaces are considered stable as of DPDK 20.11. + * No ABI change that would break compatibility with 19.11.
lib/librte_stack/rte_stack.h +0 -29
@@ -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 intrte_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 intrte_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 intrte_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 intrte_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);
lib/librte_stack/rte_stack_lf.h +0 -2
@@ -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) {
lib/librte_stack/rte_stack_std.h +0 -3
@@ -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) {
lib/librte_stack/rte_stack_version.map +1 -1
@@ -1,4 +1,4 @@ -EXPERIMENTAL { +DPDK_21 { global: rte_stack_create;
Signature · 1 line
2.13.6
Re: [dpdk-dev] [20.11] [PATCH v2] stack: remove experimental tag from API
28/05/2020 17:04, Gage Eads:
Quoted 13 lines
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 <[email protected]>--- doc/guides/rel_notes/release_20_11.rst | 3 +++ 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 +- 5 files changed, 4 insertions(+), 35 deletions(-)
Quoted 7 lines
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.rstdoesn't exist yet, so I made the change torelease_20_08.rstthen edited the filename directly in the patch. This will not apply cleanly.
- Changed rte_stack_version.map version toDPDK_21.
I think you did it right.
David Marchand
Acked-byRe: [dpdk-dev] [20.11] [PATCH v2] stack: remove experimental tag from API
In reply to Gage EadsQuoted 27 lines · Gage Eads
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 <[email protected]>--- doc/guides/rel_notes/release_20_11.rst | 3 +++ 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 +- 5 files changed, 4 insertions(+), 35 deletions(-)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.rstdoesn't exist yet, so I made the change torelease_20_08.rstthen edited the filename directly in the patch. This will not apply cleanly.
- Changed rte_stack_version.map version toDPDK_21.doc/guides/rel_notes/release_20_11.rst +0
-0
doc/guides/rel_notes/release_20_11.rst ABI Changes · line 106
Quoted 6 lines
doc/guides/rel_notes/release_20_11.rst +3
-0@@ -101,6 +101,9 @@ ABI Changes Also, make sure to start the actual text at the margin. ========================================================= +* stack: the experimental tag has been dropped from the stack library, and its + interfaces are considered stable as of DPDK 20.11. +
I would move this to the API changes section, as proposed by Thomas before.
lib/librte_stack/rte_stack.h line 7
Quoted 12 lines
doc/guides/rel_notes/release_20_11.rst +0
-0* No ABI change that would break compatibility with 19.11.lib/librte_stack/rte_stack.h +0
-1@@ -4,7 +4,6 @@/** * @file rte_stack.h -* @b EXPERIMENTAL: this API may change without prior notice
There is a little conflict here that git-pw/git-am seems to silently skip...
Quoted 181 lines
lib/librte_stack/rte_stack.h +0
-28* * 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 intrte_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 intrte_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 intrte_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 intrte_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);lib/librte_stack/rte_stack_lf.h +0
-2@@ -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) {lib/librte_stack/rte_stack_std.h +0
-3@@ -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) {lib/librte_stack/rte_stack_version.map +1
-2@@ -1,4 +1,4 @@ -EXPERIMENTAL { +DPDK_21 { global: rte_stack_create; --
Quoted 2 lines
2.13.6
Otherwise, lgtm.
Signature · 1 line
David Marchand
PATCH 1/1 stack: remove experimental tag from API
In reply to Gage EadsThe 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.
--- 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(-)
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.
doc/guides/rel_notes/release_20_11.rst +3 -0
@@ -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``.
lib/librte_stack/rte_stack.h +0 -32
@@ -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 intrte_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 intrte_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 intrte_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 intrte_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);
lib/librte_stack/rte_stack_lf.h +0 -2
@@ -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) {
lib/librte_stack/rte_stack_std.h +0 -3
@@ -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) {
lib/librte_stack/rte_stack_version.map +1 -1
@@ -1,4 +1,4 @@ -EXPERIMENTAL { +DPDK_21 { global: rte_stack_create;
Signature · 1 line
2.13.6
A nit and some questions below, thanks Ray K.
Quoted 6 lines · Gage Eads
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 <[email protected]>Acked-by David Marchand <[email protected]>
Quoted 7 lines
--- 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.
Quoted 166 lines
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.rstdoesn't exist yet, so I made the change torelease_20_08.rstthen edited the filename directly in the patch. This will not apply cleanly.
- Changed rte_stack_version.map version toDPDK_21.doc/guides/rel_notes/release_20_11.rst +3
-0@@ -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``.lib/librte_stack/rte_stack.h +0
-32@@ -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 intrte_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 intrte_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 intrte_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 intrte_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);lib/librte_stack/rte_stack_lf.h +0
-0
lib/librte_stack/rte_stack_lf.h line 30
Quoted 4 lines
lib/librte_stack/rte_stack_lf.h +0
-1@@ -27,7 +27,6 @@* @return * Actual number of objects enqueued. */ -__rte_experimental
This looks like an internal function, should it be __rte_internal?
lib/librte_stack/rte_stack_lf.h __rte_stack_lf_push(struct rte_stack *s, · line 69
Quoted 8 lines
lib/librte_stack/rte_stack_lf.h +0
-1static __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?
lib/librte_stack/rte_stack_std.h line 22
Quoted 12 lines
lib/librte_stack/rte_stack_lf.h +0
-0static __rte_always_inline unsigned int__rte_stack_lf_pop (struct rte_stack *s,void **obj_table,unsigned int n) {lib/librte_stack/rte_stack_std.h +0
-1@@ -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?
lib/librte_stack/rte_stack_std.h __rte_stack_std_push(struct rte_stack *s, void * const *obj_table, · line 62
Quoted 8 lines
lib/librte_stack/rte_stack_std.h +0
-1static __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?
Quoted 22 lines
lib/librte_stack/rte_stack_std.h +0
-1static __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) {lib/librte_stack/rte_stack_version.map +1
-1@@ -1,4 +1,4 @@ -EXPERIMENTAL { +DPDK_21 { global: rte_stack_create;
Kinsella, Ray
Acked-byQuoted 16 lines · Ray
A nit and some questions below, thanks Ray K.
Quoted 6 lines · Gage Eads
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 <[email protected]>Acked-by David Marchand <[email protected]>Quoted 7 lines
--- 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(-)
Quoted 2 lines
NIT: You are missing the v3 in the subject line, doesn't require a fix.
[SNIP]
So after chatting with David, it looks like there is no _nice_ way to indicate that some inlines are "internal" while others are "public".
Something to look at in future maybe.
Quoted 70 lines
lib/librte_stack/rte_stack_lf.h line 30
Quoted 10 lines
lib/librte_stack/rte_stack_lf.h +0
-1@@ -27,7 +27,6 @@* @return * Actual number of objects enqueued. */ -__rte_experimentalThis looks like an internal function, should it be
__rte_internal?lib/librte_stack/rte_stack_lf.h __rte_stack_lf_push(struct rte_stack *s, · line 69
Quoted 8 lines
lib/librte_stack/rte_stack_lf.h +0
-1static __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_experimentalThis looks like an internal function, should it be
__rte_internal?lib/librte_stack/rte_stack_std.h line 22
Quoted 12 lines
lib/librte_stack/rte_stack_lf.h +0
-0static __rte_always_inline unsigned int__rte_stack_lf_pop (struct rte_stack *s,void **obj_table,unsigned int n) {lib/librte_stack/rte_stack_std.h +0
-1@@ -19,7 +19,6 @@* @return * Actual number of objects pushed (either 0 or *n*). */ -__rte_experimentalThis looks like an internal function, should it be
__rte_internal?lib/librte_stack/rte_stack_std.h __rte_stack_std_push(struct rte_stack *s, void * const *obj_table, · line 62
Quoted 8 lines
lib/librte_stack/rte_stack_std.h +0
-1static __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_experimentalThis looks like an internal function, should it be
__rte_internal?Quoted 20 lines
lib/librte_stack/rte_stack_std.h +0
-1static __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) {lib/librte_stack/rte_stack_version.map +1
-1@@ -1,4 +1,4 @@ -EXPERIMENTAL { +DPDK_21 { global:
Quoted 2 lines
lib/librte_stack/rte_stack_version.map line 4
Quoted 2 lines
lib/librte_stack/rte_stack_version.map +0
-0rte_stack_create;
Quoted 7 lines · Gage Eads
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 <[email protected]>Acked-by David Marchand <[email protected]>
Removed remaining comment in MAINTAINERS.
Applied, thanks.
Signature · 1 line
David Marchand