[dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[Joyce Kong]

Experimental tags can be removed from APIs in module: ticket lock, 
MCS lock, pause (wait until equal APIs), and RCU (except for defer
queue APIs) as they have been aroud four releases.

Joyce Kong (4):
  eal/ticketlock: remove experimental tag
  eal/mcslock: remove experimental tag
  rcu: remove experimental tag from QSBR mechanism
  eal/pause: remove experimental tag from wait until equal

 MAINTAINERS                                   |  4 +-
 lib/librte_eal/include/generic/rte_mcslock.h  | 16 ------
 lib/librte_eal/include/generic/rte_pause.h    | 12 -----
 .../include/generic/rte_ticketlock.h          |  9 ----
 lib/librte_rcu/rte_rcu_qsbr.h                 | 52 -------------------
 lib/librte_rcu/rte_rcu_version.map            | 11 +++-
 6 files changed, 11 insertions(+), 93 deletions(-)

-- 
2.28.0

[dpdk-dev] [PATCH 1/4] eal/ticketlock: remove experimental tag

[Joyce Kong]

As rte_ticketlock was introduced in 19.05 release
and there were no changes in its public API since
19.11 release, it should be mature enough to remove
the experimental tag.

Signed-off-by: Joyce Kong <joyce.kong@arm.com>
Reviewed-by: Phil Yang <phil.yang@arm.com>
Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
---
 lib/librte_eal/include/generic/rte_ticketlock.h | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/lib/librte_eal/include/generic/rte_ticketlock.h b/lib/librte_eal/include/generic/rte_ticketlock.h
index c295ae7f7..c1b8808f5 100644
--- a/lib/librte_eal/include/generic/rte_ticketlock.h
+++ b/lib/librte_eal/include/generic/rte_ticketlock.h
@@ -48,7 +48,6 @@ typedef union {
  * @param tl
  *   A pointer to the ticketlock.
  */
-__rte_experimental
 static inline void
 rte_ticketlock_init(rte_ticketlock_t *tl)
 {
@@ -61,7 +60,6 @@ rte_ticketlock_init(rte_ticketlock_t *tl)
  * @param tl
  *   A pointer to the ticketlock.
  */
-__rte_experimental
 static inline void
 rte_ticketlock_lock(rte_ticketlock_t *tl)
 {
@@ -75,7 +73,6 @@ rte_ticketlock_lock(rte_ticketlock_t *tl)
  * @param tl
  *   A pointer to the ticketlock.
  */
-__rte_experimental
 static inline void
 rte_ticketlock_unlock(rte_ticketlock_t *tl)
 {
@@ -91,7 +88,6 @@ rte_ticketlock_unlock(rte_ticketlock_t *tl)
  * @return
  *   1 if the lock is successfully taken; 0 otherwise.
  */
-__rte_experimental
 static inline int
 rte_ticketlock_trylock(rte_ticketlock_t *tl)
 {
@@ -116,7 +112,6 @@ rte_ticketlock_trylock(rte_ticketlock_t *tl)
  * @return
  *   1 if the lock is currently taken; 0 otherwise.
  */
-__rte_experimental
 static inline int
 rte_ticketlock_is_locked(rte_ticketlock_t *tl)
 {
@@ -148,7 +143,6 @@ typedef struct {
  * @param tlr
  *   A pointer to the recursive ticketlock.
  */
-__rte_experimental
 static inline void
 rte_ticketlock_recursive_init(rte_ticketlock_recursive_t *tlr)
 {
@@ -163,7 +157,6 @@ rte_ticketlock_recursive_init(rte_ticketlock_recursive_t *tlr)
  * @param tlr
  *   A pointer to the recursive ticketlock.
  */
-__rte_experimental
 static inline void
 rte_ticketlock_recursive_lock(rte_ticketlock_recursive_t *tlr)
 {
@@ -182,7 +175,6 @@ rte_ticketlock_recursive_lock(rte_ticketlock_recursive_t *tlr)
  * @param tlr
  *   A pointer to the recursive ticketlock.
  */
-__rte_experimental
 static inline void
 rte_ticketlock_recursive_unlock(rte_ticketlock_recursive_t *tlr)
 {
@@ -201,7 +193,6 @@ rte_ticketlock_recursive_unlock(rte_ticketlock_recursive_t *tlr)
  * @return
  *   1 if the lock is successfully taken; 0 otherwise.
  */
-__rte_experimental
 static inline int
 rte_ticketlock_recursive_trylock(rte_ticketlock_recursive_t *tlr)
 {
-- 
2.28.0

[dpdk-dev] [PATCH 2/4] eal/mcslock: remove experimental tag

[Joyce Kong]

Since rte_mcslock APIs were introduced in 19.08 release,
it is now possible to remove the experimental tag from:
rte_mcslock_lock()
rte_mcslock_unlock()
rte_mcslock_trylock()
rte_mcslock_is_locked()

Signed-off-by: Joyce Kong <joyce.kong@arm.com>
Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
Acked-by: Phil Yang <phil.yang@arm.com>
---
 MAINTAINERS                                  |  2 +-
 lib/librte_eal/include/generic/rte_mcslock.h | 16 ----------------
 2 files changed, 1 insertion(+), 17 deletions(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 3003852b5..0e43a28bf 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -264,7 +264,7 @@ M: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
 F: lib/librte_eal/include/rte_bitmap.h
 F: app/test/test_bitmap.c
 
-MCSlock - EXPERIMENTAL
+MCSlock
 M: Phil Yang <phil.yang@arm.com>
 F: lib/librte_eal/include/generic/rte_mcslock.h
 F: app/test/test_mcslock.c
diff --git a/lib/librte_eal/include/generic/rte_mcslock.h b/lib/librte_eal/include/generic/rte_mcslock.h
index 2bef28351..78b0df295 100644
--- a/lib/librte_eal/include/generic/rte_mcslock.h
+++ b/lib/librte_eal/include/generic/rte_mcslock.h
@@ -32,9 +32,6 @@ typedef struct rte_mcslock {
 } rte_mcslock_t;
 
 /**
- * @warning
- * @b EXPERIMENTAL: This API may change without prior notice
- *
  * Take the MCS lock.
  *
  * @param msl
@@ -45,7 +42,6 @@ typedef struct rte_mcslock {
  *   A pointer to a new node of MCS lock. Each CPU/thread acquiring the
  *   lock should use its 'own node'.
  */
-__rte_experimental
 static inline void
 rte_mcslock_lock(rte_mcslock_t **msl, rte_mcslock_t *me)
 {
@@ -85,9 +81,6 @@ rte_mcslock_lock(rte_mcslock_t **msl, rte_mcslock_t *me)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: This API may change without prior notice
- *
  * Release the MCS lock.
  *
  * @param msl
@@ -95,7 +88,6 @@ rte_mcslock_lock(rte_mcslock_t **msl, rte_mcslock_t *me)
  * @param me
  *   A pointer to the node of MCS lock passed in rte_mcslock_lock.
  */
-__rte_experimental
 static inline void
 rte_mcslock_unlock(rte_mcslock_t **msl, rte_mcslock_t *me)
 {
@@ -126,9 +118,6 @@ rte_mcslock_unlock(rte_mcslock_t **msl, rte_mcslock_t *me)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: This API may change without prior notice
- *
  * Try to take the lock.
  *
  * @param msl
@@ -138,7 +127,6 @@ rte_mcslock_unlock(rte_mcslock_t **msl, rte_mcslock_t *me)
  * @return
  *   1 if the lock is successfully taken; 0 otherwise.
  */
-__rte_experimental
 static inline int
 rte_mcslock_trylock(rte_mcslock_t **msl, rte_mcslock_t *me)
 {
@@ -159,9 +147,6 @@ rte_mcslock_trylock(rte_mcslock_t **msl, rte_mcslock_t *me)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: This API may change without prior notice
- *
  * Test if the lock is taken.
  *
  * @param msl
@@ -169,7 +154,6 @@ rte_mcslock_trylock(rte_mcslock_t **msl, rte_mcslock_t *me)
  * @return
  *   1 if the lock is currently taken; 0 otherwise.
  */
-__rte_experimental
 static inline int
 rte_mcslock_is_locked(rte_mcslock_t *msl)
 {
-- 
2.28.0

[dpdk-dev] [PATCH 3/4] rcu: remove experimental tag from QSBR mechanism

[Joyce Kong]

RCU library supporting quiescent state was introduced
in 19.05 release and has been around 4 releases, it
should be mature enough to remove the experimental tag.

Signed-off-by: Joyce Kong <joyce.kong@arm.com>
Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
---
 MAINTAINERS                        |  2 +-
 lib/librte_rcu/rte_rcu_qsbr.h      | 52 ------------------------------
 lib/librte_rcu/rte_rcu_version.map | 11 +++++--
 3 files changed, 10 insertions(+), 55 deletions(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 0e43a28bf..12f088b62 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1449,7 +1449,7 @@ M: Olivier Matz <olivier.matz@6wind.com>
 F: lib/librte_kvargs/
 F: app/test/test_kvargs.c
 
-RCU - EXPERIMENTAL
+RCU
 M: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
 F: lib/librte_rcu/
 F: app/test/test_rcu*
diff --git a/lib/librte_rcu/rte_rcu_qsbr.h b/lib/librte_rcu/rte_rcu_qsbr.h
index a98e8f0f8..5905c53a5 100644
--- a/lib/librte_rcu/rte_rcu_qsbr.h
+++ b/lib/librte_rcu/rte_rcu_qsbr.h
@@ -202,9 +202,6 @@ struct rte_rcu_qsbr_dq_parameters {
 struct rte_rcu_qsbr_dq;
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Return the size of the memory occupied by a Quiescent State variable.
  *
  * @param max_threads
@@ -215,14 +212,10 @@ struct rte_rcu_qsbr_dq;
  *   Possible rte_errno codes are:
  *   - EINVAL - max_threads is 0
  */
-__rte_experimental
 size_t
 rte_rcu_qsbr_get_memsize(uint32_t max_threads);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Initialize a Quiescent State (QS) variable.
  *
  * @param v
@@ -237,14 +230,10 @@ rte_rcu_qsbr_get_memsize(uint32_t max_threads);
  *   - EINVAL - max_threads is 0 or 'v' is NULL.
  *
  */
-__rte_experimental
 int
 rte_rcu_qsbr_init(struct rte_rcu_qsbr *v, uint32_t max_threads);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Register a reader thread to report its quiescent state
  * on a QS variable.
  *
@@ -264,14 +253,10 @@ rte_rcu_qsbr_init(struct rte_rcu_qsbr *v, uint32_t max_threads);
  *   the QS variable. thread_id is a value between 0 and (max_threads - 1).
  *   'max_threads' is the parameter passed in 'rte_rcu_qsbr_init' API.
  */
-__rte_experimental
 int
 rte_rcu_qsbr_thread_register(struct rte_rcu_qsbr *v, unsigned int thread_id);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Remove a reader thread, from the list of threads reporting their
  * quiescent state on a QS variable.
  *
@@ -286,14 +271,10 @@ rte_rcu_qsbr_thread_register(struct rte_rcu_qsbr *v, unsigned int thread_id);
  *   Reader thread with this thread ID will stop reporting its quiescent
  *   state on the QS variable.
  */
-__rte_experimental
 int
 rte_rcu_qsbr_thread_unregister(struct rte_rcu_qsbr *v, unsigned int thread_id);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Add a registered reader thread, to the list of threads reporting their
  * quiescent state on a QS variable.
  *
@@ -318,7 +299,6 @@ rte_rcu_qsbr_thread_unregister(struct rte_rcu_qsbr *v, unsigned int thread_id);
  *   Reader thread with this thread ID will report its quiescent state on
  *   the QS variable.
  */
-__rte_experimental
 static __rte_always_inline void
 rte_rcu_qsbr_thread_online(struct rte_rcu_qsbr *v, unsigned int thread_id)
 {
@@ -358,9 +338,6 @@ rte_rcu_qsbr_thread_online(struct rte_rcu_qsbr *v, unsigned int thread_id)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Remove a registered reader thread from the list of threads reporting their
  * quiescent state on a QS variable.
  *
@@ -380,7 +357,6 @@ rte_rcu_qsbr_thread_online(struct rte_rcu_qsbr *v, unsigned int thread_id)
  *   rte_rcu_qsbr_check API will not wait for the reader thread with
  *   this thread ID to report its quiescent state on the QS variable.
  */
-__rte_experimental
 static __rte_always_inline void
 rte_rcu_qsbr_thread_offline(struct rte_rcu_qsbr *v, unsigned int thread_id)
 {
@@ -399,9 +375,6 @@ rte_rcu_qsbr_thread_offline(struct rte_rcu_qsbr *v, unsigned int thread_id)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Acquire a lock for accessing a shared data structure.
  *
  * This is implemented as a lock-free function. It is multi-thread
@@ -421,7 +394,6 @@ rte_rcu_qsbr_thread_offline(struct rte_rcu_qsbr *v, unsigned int thread_id)
  * @param thread_id
  *   Reader thread id
  */
-__rte_experimental
 static __rte_always_inline void
 rte_rcu_qsbr_lock(__rte_unused struct rte_rcu_qsbr *v,
 			__rte_unused unsigned int thread_id)
@@ -436,9 +408,6 @@ rte_rcu_qsbr_lock(__rte_unused struct rte_rcu_qsbr *v,
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Release a lock after accessing a shared data structure.
  *
  * This is implemented as a lock-free function. It is multi-thread
@@ -458,7 +427,6 @@ rte_rcu_qsbr_lock(__rte_unused struct rte_rcu_qsbr *v,
  * @param thread_id
  *   Reader thread id
  */
-__rte_experimental
 static __rte_always_inline void
 rte_rcu_qsbr_unlock(__rte_unused struct rte_rcu_qsbr *v,
 			__rte_unused unsigned int thread_id)
@@ -477,9 +445,6 @@ rte_rcu_qsbr_unlock(__rte_unused struct rte_rcu_qsbr *v,
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Ask the reader threads to report the quiescent state
  * status.
  *
@@ -492,7 +457,6 @@ rte_rcu_qsbr_unlock(__rte_unused struct rte_rcu_qsbr *v,
  *   - This is the token for this call of the API. This should be
  *     passed to rte_rcu_qsbr_check API.
  */
-__rte_experimental
 static __rte_always_inline uint64_t
 rte_rcu_qsbr_start(struct rte_rcu_qsbr *v)
 {
@@ -511,9 +475,6 @@ rte_rcu_qsbr_start(struct rte_rcu_qsbr *v)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Update quiescent state for a reader thread.
  *
  * This is implemented as a lock-free function. It is multi-thread safe.
@@ -525,7 +486,6 @@ rte_rcu_qsbr_start(struct rte_rcu_qsbr *v)
  * @param thread_id
  *   Update the quiescent state for the reader with this thread ID.
  */
-__rte_experimental
 static __rte_always_inline void
 rte_rcu_qsbr_quiescent(struct rte_rcu_qsbr *v, unsigned int thread_id)
 {
@@ -683,9 +643,6 @@ __rte_rcu_qsbr_check_all(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Checks if all the reader threads have entered the quiescent state
  * referenced by token.
  *
@@ -716,7 +673,6 @@ __rte_rcu_qsbr_check_all(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
  *   - 1 if all reader threads have passed through specified number
  *     of quiescent states.
  */
-__rte_experimental
 static __rte_always_inline int
 rte_rcu_qsbr_check(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
 {
@@ -740,9 +696,6 @@ rte_rcu_qsbr_check(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
 }
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Wait till the reader threads have entered quiescent state.
  *
  * This is implemented as a lock-free function. It is multi-thread safe.
@@ -760,14 +713,10 @@ rte_rcu_qsbr_check(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
  *   on this QS variable (i.e. the calling thread is also part of the
  *   readside critical section). If not, pass RTE_QSBR_THRID_INVALID.
  */
-__rte_experimental
 void
 rte_rcu_qsbr_synchronize(struct rte_rcu_qsbr *v, unsigned int thread_id);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Dump the details of a single QS variables to a file.
  *
  * It is NOT multi-thread safe.
@@ -782,7 +731,6 @@ rte_rcu_qsbr_synchronize(struct rte_rcu_qsbr *v, unsigned int thread_id);
  *   Possible rte_errno codes are:
  *   - EINVAL - NULL parameters are passed
  */
-__rte_experimental
 int
 rte_rcu_qsbr_dump(FILE *f, struct rte_rcu_qsbr *v);
 
diff --git a/lib/librte_rcu/rte_rcu_version.map b/lib/librte_rcu/rte_rcu_version.map
index dfac88a37..e40850350 100644
--- a/lib/librte_rcu/rte_rcu_version.map
+++ b/lib/librte_rcu/rte_rcu_version.map
@@ -1,5 +1,5 @@
-EXPERIMENTAL {
-	global:
+DPDK_21 {
+        global:
 
 	rte_rcu_log_type;
 	rte_rcu_qsbr_dump;
@@ -8,6 +8,13 @@ EXPERIMENTAL {
 	rte_rcu_qsbr_synchronize;
 	rte_rcu_qsbr_thread_register;
 	rte_rcu_qsbr_thread_unregister;
+
+        local: *;
+};
+
+EXPERIMENTAL {
+	global:
+
 	rte_rcu_qsbr_dq_create;
 	rte_rcu_qsbr_dq_enqueue;
 	rte_rcu_qsbr_dq_reclaim;
-- 
2.28.0

[dpdk-dev] [PATCH 4/4] eal/pause: remove experimental tag from wait until equal

[Joyce Kong]

rte_wait_until_equal_xx APIs were introduced in 19.11 release
and there were no changes in the public APIs since then, it
should be mature enough to remove the experimental tag.

Signed-off-by: Joyce Kong <joyce.kong@arm.com>
Reviewed-by: Phil Yang <phil.yang@arm.com>
Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
---
 lib/librte_eal/include/generic/rte_pause.h | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/lib/librte_eal/include/generic/rte_pause.h b/lib/librte_eal/include/generic/rte_pause.h
index 7422785f1..668ee4a18 100644
--- a/lib/librte_eal/include/generic/rte_pause.h
+++ b/lib/librte_eal/include/generic/rte_pause.h
@@ -28,9 +28,6 @@
 static inline void rte_pause(void);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
- *
  * Wait for *addr to be updated with a 16-bit expected value, with a relaxed
  * memory ordering model meaning the loads around this API can be reordered.
  *
@@ -44,15 +41,11 @@ static inline void rte_pause(void);
  *  C++11 memory orders with the same names, see the C++11 standard or
  *  the GCC wiki on atomic synchronization for detailed definition.
  */
-__rte_experimental
 static __rte_always_inline void
 rte_wait_until_equal_16(volatile uint16_t *addr, uint16_t expected,
 		int memorder);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
- *
  * Wait for *addr to be updated with a 32-bit expected value, with a relaxed
  * memory ordering model meaning the loads around this API can be reordered.
  *
@@ -66,15 +59,11 @@ rte_wait_until_equal_16(volatile uint16_t *addr, uint16_t expected,
  *  C++11 memory orders with the same names, see the C++11 standard or
  *  the GCC wiki on atomic synchronization for detailed definition.
  */
-__rte_experimental
 static __rte_always_inline void
 rte_wait_until_equal_32(volatile uint32_t *addr, uint32_t expected,
 		int memorder);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
- *
  * Wait for *addr to be updated with a 64-bit expected value, with a relaxed
  * memory ordering model meaning the loads around this API can be reordered.
  *
@@ -88,7 +77,6 @@ rte_wait_until_equal_32(volatile uint32_t *addr, uint32_t expected,
  *  C++11 memory orders with the same names, see the C++11 standard or
  *  the GCC wiki on atomic synchronization for detailed definition.
  */
-__rte_experimental
 static __rte_always_inline void
 rte_wait_until_equal_64(volatile uint64_t *addr, uint64_t expected,
 		int memorder);
-- 
2.28.0

Re: [dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[David Marchand]

On Fri, Sep 11, 2020 at 7:46 AM Joyce Kong <joyce.kong@arm.com> wrote:
>
> Experimental tags can be removed from APIs in module: ticket lock,
> MCS lock, pause (wait until equal APIs), and RCU (except for defer
> queue APIs) as they have been aroud four releases.
>
> Joyce Kong (4):
>   eal/ticketlock: remove experimental tag
>   eal/mcslock: remove experimental tag
>   rcu: remove experimental tag from QSBR mechanism
>   eal/pause: remove experimental tag from wait until equal

This series seems good to me but I prefer to ask other arch maintainers.
Are you fine with those API being marked as stable (especially the
wait until equal API)?


Thanks.

-- 
David Marchand

Re: [dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[David Marchand]

On Wed, Sep 16, 2020 at 7:09 PM David Marchand
<david.marchand@redhat.com> wrote:
>
> On Fri, Sep 11, 2020 at 7:46 AM Joyce Kong <joyce.kong@arm.com> wrote:
> >
> > Experimental tags can be removed from APIs in module: ticket lock,
> > MCS lock, pause (wait until equal APIs), and RCU (except for defer
> > queue APIs) as they have been aroud four releases.
> >
> > Joyce Kong (4):
> >   eal/ticketlock: remove experimental tag
> >   eal/mcslock: remove experimental tag
> >   rcu: remove experimental tag from QSBR mechanism
> >   eal/pause: remove experimental tag from wait until equal
>
> This series seems good to me but I prefer to ask other arch maintainers.
> Are you fine with those API being marked as stable (especially the
> wait until equal API)?

Going twice...


-- 
David Marchand

Re: [dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[Ananyev, Konstantin]

> On Wed, Sep 16, 2020 at 7:09 PM David Marchand
> <david.marchand@redhat.com> wrote:
> >
> > On Fri, Sep 11, 2020 at 7:46 AM Joyce Kong <joyce.kong@arm.com> wrote:
> > >
> > > Experimental tags can be removed from APIs in module: ticket lock,
> > > MCS lock, pause (wait until equal APIs), and RCU (except for defer
> > > queue APIs) as they have been aroud four releases.
> > >
> > > Joyce Kong (4):
> > >   eal/ticketlock: remove experimental tag
> > >   eal/mcslock: remove experimental tag
> > >   rcu: remove experimental tag from QSBR mechanism
> > >   eal/pause: remove experimental tag from wait until equal
> >
> > This series seems good to me but I prefer to ask other arch maintainers.
> > Are you fine with those API being marked as stable (especially the
> > wait until equal API)?
> 
> Going twice...
> 

No objections from me.
Series acked-by: Konstantin Ananyev <konstantin.ananyev@intel.com>

Re: [dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[Kinsella, Ray]

On 11/09/2020 06:45, Joyce Kong wrote:
> Experimental tags can be removed from APIs in module: ticket lock, 
> MCS lock, pause (wait until equal APIs), and RCU (except for defer
> queue APIs) as they have been aroud four releases.

NIT: aroud = around

> 
> Joyce Kong (4):
>   eal/ticketlock: remove experimental tag
>   eal/mcslock: remove experimental tag
>   rcu: remove experimental tag from QSBR mechanism
>   eal/pause: remove experimental tag from wait until equal
> 
>  MAINTAINERS                                   |  4 +-
>  lib/librte_eal/include/generic/rte_mcslock.h  | 16 ------
>  lib/librte_eal/include/generic/rte_pause.h    | 12 -----
>  .../include/generic/rte_ticketlock.h          |  9 ----
>  lib/librte_rcu/rte_rcu_qsbr.h                 | 52 -------------------
>  lib/librte_rcu/rte_rcu_version.map            | 11 +++-
>  6 files changed, 11 insertions(+), 93 deletions(-)
> 

Re: [dpdk-dev] [PATCH 3/4] rcu: remove experimental tag from QSBR mechanism

[Kinsella, Ray]

On 11/09/2020 06:45, Joyce Kong wrote:
> RCU library supporting quiescent state was introduced
> in 19.05 release and has been around 4 releases, it
> should be mature enough to remove the experimental tag.
> 
> Signed-off-by: Joyce Kong <joyce.kong@arm.com>
> Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
> ---
>  MAINTAINERS                        |  2 +-
>  lib/librte_rcu/rte_rcu_qsbr.h      | 52 ------------------------------
>  lib/librte_rcu/rte_rcu_version.map | 11 +++++--
>  3 files changed, 10 insertions(+), 55 deletions(-)
> 

Some nits on tabing versus spaces below.

> diff --git a/MAINTAINERS b/MAINTAINERS
> index 0e43a28bf..12f088b62 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1449,7 +1449,7 @@ M: Olivier Matz <olivier.matz@6wind.com>
>  F: lib/librte_kvargs/
>  F: app/test/test_kvargs.c
>  
> -RCU - EXPERIMENTAL
> +RCU
>  M: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
>  F: lib/librte_rcu/
>  F: app/test/test_rcu*
> diff --git a/lib/librte_rcu/rte_rcu_qsbr.h b/lib/librte_rcu/rte_rcu_qsbr.h
> index a98e8f0f8..5905c53a5 100644
> --- a/lib/librte_rcu/rte_rcu_qsbr.h
> +++ b/lib/librte_rcu/rte_rcu_qsbr.h
> @@ -202,9 +202,6 @@ struct rte_rcu_qsbr_dq_parameters {
>  struct rte_rcu_qsbr_dq;
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Return the size of the memory occupied by a Quiescent State variable.
>   *
>   * @param max_threads
> @@ -215,14 +212,10 @@ struct rte_rcu_qsbr_dq;
>   *   Possible rte_errno codes are:
>   *   - EINVAL - max_threads is 0
>   */
> -__rte_experimental
>  size_t
>  rte_rcu_qsbr_get_memsize(uint32_t max_threads);
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Initialize a Quiescent State (QS) variable.
>   *
>   * @param v
> @@ -237,14 +230,10 @@ rte_rcu_qsbr_get_memsize(uint32_t max_threads);
>   *   - EINVAL - max_threads is 0 or 'v' is NULL.
>   *
>   */
> -__rte_experimental
>  int
>  rte_rcu_qsbr_init(struct rte_rcu_qsbr *v, uint32_t max_threads);
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Register a reader thread to report its quiescent state
>   * on a QS variable.
>   *
> @@ -264,14 +253,10 @@ rte_rcu_qsbr_init(struct rte_rcu_qsbr *v, uint32_t max_threads);
>   *   the QS variable. thread_id is a value between 0 and (max_threads - 1).
>   *   'max_threads' is the parameter passed in 'rte_rcu_qsbr_init' API.
>   */
> -__rte_experimental
>  int
>  rte_rcu_qsbr_thread_register(struct rte_rcu_qsbr *v, unsigned int thread_id);
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Remove a reader thread, from the list of threads reporting their
>   * quiescent state on a QS variable.
>   *
> @@ -286,14 +271,10 @@ rte_rcu_qsbr_thread_register(struct rte_rcu_qsbr *v, unsigned int thread_id);
>   *   Reader thread with this thread ID will stop reporting its quiescent
>   *   state on the QS variable.
>   */
> -__rte_experimental
>  int
>  rte_rcu_qsbr_thread_unregister(struct rte_rcu_qsbr *v, unsigned int thread_id);
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Add a registered reader thread, to the list of threads reporting their
>   * quiescent state on a QS variable.
>   *
> @@ -318,7 +299,6 @@ rte_rcu_qsbr_thread_unregister(struct rte_rcu_qsbr *v, unsigned int thread_id);
>   *   Reader thread with this thread ID will report its quiescent state on
>   *   the QS variable.
>   */
> -__rte_experimental
>  static __rte_always_inline void
>  rte_rcu_qsbr_thread_online(struct rte_rcu_qsbr *v, unsigned int thread_id)
>  {
> @@ -358,9 +338,6 @@ rte_rcu_qsbr_thread_online(struct rte_rcu_qsbr *v, unsigned int thread_id)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Remove a registered reader thread from the list of threads reporting their
>   * quiescent state on a QS variable.
>   *
> @@ -380,7 +357,6 @@ rte_rcu_qsbr_thread_online(struct rte_rcu_qsbr *v, unsigned int thread_id)
>   *   rte_rcu_qsbr_check API will not wait for the reader thread with
>   *   this thread ID to report its quiescent state on the QS variable.
>   */
> -__rte_experimental
>  static __rte_always_inline void
>  rte_rcu_qsbr_thread_offline(struct rte_rcu_qsbr *v, unsigned int thread_id)
>  {
> @@ -399,9 +375,6 @@ rte_rcu_qsbr_thread_offline(struct rte_rcu_qsbr *v, unsigned int thread_id)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Acquire a lock for accessing a shared data structure.
>   *
>   * This is implemented as a lock-free function. It is multi-thread
> @@ -421,7 +394,6 @@ rte_rcu_qsbr_thread_offline(struct rte_rcu_qsbr *v, unsigned int thread_id)
>   * @param thread_id
>   *   Reader thread id
>   */
> -__rte_experimental
>  static __rte_always_inline void
>  rte_rcu_qsbr_lock(__rte_unused struct rte_rcu_qsbr *v,
>  			__rte_unused unsigned int thread_id)
> @@ -436,9 +408,6 @@ rte_rcu_qsbr_lock(__rte_unused struct rte_rcu_qsbr *v,
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Release a lock after accessing a shared data structure.
>   *
>   * This is implemented as a lock-free function. It is multi-thread
> @@ -458,7 +427,6 @@ rte_rcu_qsbr_lock(__rte_unused struct rte_rcu_qsbr *v,
>   * @param thread_id
>   *   Reader thread id
>   */
> -__rte_experimental
>  static __rte_always_inline void
>  rte_rcu_qsbr_unlock(__rte_unused struct rte_rcu_qsbr *v,
>  			__rte_unused unsigned int thread_id)
> @@ -477,9 +445,6 @@ rte_rcu_qsbr_unlock(__rte_unused struct rte_rcu_qsbr *v,
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Ask the reader threads to report the quiescent state
>   * status.
>   *
> @@ -492,7 +457,6 @@ rte_rcu_qsbr_unlock(__rte_unused struct rte_rcu_qsbr *v,
>   *   - This is the token for this call of the API. This should be
>   *     passed to rte_rcu_qsbr_check API.
>   */
> -__rte_experimental
>  static __rte_always_inline uint64_t
>  rte_rcu_qsbr_start(struct rte_rcu_qsbr *v)
>  {
> @@ -511,9 +475,6 @@ rte_rcu_qsbr_start(struct rte_rcu_qsbr *v)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Update quiescent state for a reader thread.
>   *
>   * This is implemented as a lock-free function. It is multi-thread safe.
> @@ -525,7 +486,6 @@ rte_rcu_qsbr_start(struct rte_rcu_qsbr *v)
>   * @param thread_id
>   *   Update the quiescent state for the reader with this thread ID.
>   */
> -__rte_experimental
>  static __rte_always_inline void
>  rte_rcu_qsbr_quiescent(struct rte_rcu_qsbr *v, unsigned int thread_id)
>  {
> @@ -683,9 +643,6 @@ __rte_rcu_qsbr_check_all(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Checks if all the reader threads have entered the quiescent state
>   * referenced by token.
>   *
> @@ -716,7 +673,6 @@ __rte_rcu_qsbr_check_all(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
>   *   - 1 if all reader threads have passed through specified number
>   *     of quiescent states.
>   */
> -__rte_experimental
>  static __rte_always_inline int
>  rte_rcu_qsbr_check(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
>  {
> @@ -740,9 +696,6 @@ rte_rcu_qsbr_check(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
>  }
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Wait till the reader threads have entered quiescent state.
>   *
>   * This is implemented as a lock-free function. It is multi-thread safe.
> @@ -760,14 +713,10 @@ rte_rcu_qsbr_check(struct rte_rcu_qsbr *v, uint64_t t, bool wait)
>   *   on this QS variable (i.e. the calling thread is also part of the
>   *   readside critical section). If not, pass RTE_QSBR_THRID_INVALID.
>   */
> -__rte_experimental
>  void
>  rte_rcu_qsbr_synchronize(struct rte_rcu_qsbr *v, unsigned int thread_id);
>  
>  /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change without prior notice
> - *
>   * Dump the details of a single QS variables to a file.
>   *
>   * It is NOT multi-thread safe.
> @@ -782,7 +731,6 @@ rte_rcu_qsbr_synchronize(struct rte_rcu_qsbr *v, unsigned int thread_id);
>   *   Possible rte_errno codes are:
>   *   - EINVAL - NULL parameters are passed
>   */
> -__rte_experimental
>  int
>  rte_rcu_qsbr_dump(FILE *f, struct rte_rcu_qsbr *v);
>  
> diff --git a/lib/librte_rcu/rte_rcu_version.map b/lib/librte_rcu/rte_rcu_version.map
> index dfac88a37..e40850350 100644
> --- a/lib/librte_rcu/rte_rcu_version.map
> +++ b/lib/librte_rcu/rte_rcu_version.map
> @@ -1,5 +1,5 @@
> -EXPERIMENTAL {
> -	global:
> +DPDK_21 {
> +        global:
Tab pls
>  
>  	rte_rcu_log_type;
>  	rte_rcu_qsbr_dump;
> @@ -8,6 +8,13 @@ EXPERIMENTAL {
>  	rte_rcu_qsbr_synchronize;
>  	rte_rcu_qsbr_thread_register;
>  	rte_rcu_qsbr_thread_unregister;
> +
> +        local: *;
Tab pls

> +};
> +
> +EXPERIMENTAL {
> +	global:
> +
>  	rte_rcu_qsbr_dq_create;
>  	rte_rcu_qsbr_dq_enqueue;
>  	rte_rcu_qsbr_dq_reclaim;
> 

Re: [dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[David Marchand]

On Fri, Sep 11, 2020 at 7:46 AM Joyce Kong <joyce.kong@arm.com> wrote:
>
> Experimental tags can be removed from APIs in module: ticket lock,
> MCS lock, pause (wait until equal APIs), and RCU (except for defer
> queue APIs) as they have been aroud four releases.
>
> Joyce Kong (4):
>   eal/ticketlock: remove experimental tag
>   eal/mcslock: remove experimental tag
>   rcu: remove experimental tag from QSBR mechanism
>   eal/pause: remove experimental tag from wait until equal
>
>  MAINTAINERS                                   |  4 +-
>  lib/librte_eal/include/generic/rte_mcslock.h  | 16 ------
>  lib/librte_eal/include/generic/rte_pause.h    | 12 -----
>  .../include/generic/rte_ticketlock.h          |  9 ----
>  lib/librte_rcu/rte_rcu_qsbr.h                 | 52 -------------------
>  lib/librte_rcu/rte_rcu_version.map            | 11 +++-
>  6 files changed, 11 insertions(+), 93 deletions(-)
>

I will handle the Ray comment on the rcu map.

One additional comment: the wait until equal API should be marked
stable before the ticketlock API, since the latter relies on the
former.
This is just a question of ordering the patches, easy to do when applying.

No need for a v2 on those comments.


-- 
David Marchand

Re: [dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[David Christensen]

On 9/25/20 7:14 AM, Ananyev, Konstantin wrote:
> 
>> On Wed, Sep 16, 2020 at 7:09 PM David Marchand
>> <david.marchand@redhat.com> wrote:
>>>
>>> On Fri, Sep 11, 2020 at 7:46 AM Joyce Kong <joyce.kong@arm.com> wrote:
>>>>
>>>> Experimental tags can be removed from APIs in module: ticket lock,
>>>> MCS lock, pause (wait until equal APIs), and RCU (except for defer
>>>> queue APIs) as they have been aroud four releases.
>>>>
>>>> Joyce Kong (4):
>>>>    eal/ticketlock: remove experimental tag
>>>>    eal/mcslock: remove experimental tag
>>>>    rcu: remove experimental tag from QSBR mechanism
>>>>    eal/pause: remove experimental tag from wait until equal
>>>
>>> This series seems good to me but I prefer to ask other arch maintainers.
>>> Are you fine with those API being marked as stable (especially the
>>> wait until equal API)?
>>
>> Going twice...
>>
> 
> No objections from me.
> Series acked-by: Konstantin Ananyev <konstantin.ananyev@intel.com>

Same here, no objections.

Acked-by: David Christensen <drc@linux.vnet.ibm.com>

Re: [dpdk-dev] [PATCH 0/4] remove experimental tags from APIs

[David Marchand]

On Fri, Sep 11, 2020 at 7:46 AM Joyce Kong <joyce.kong@arm.com> wrote:
>
> Experimental tags can be removed from APIs in module: ticket lock,
> MCS lock, pause (wait until equal APIs), and RCU (except for defer
> queue APIs) as they have been aroud four releases.
>
> Joyce Kong (4):
>   eal/ticketlock: remove experimental tag
>   eal/mcslock: remove experimental tag
>   rcu: remove experimental tag from QSBR mechanism
>   eal/pause: remove experimental tag from wait until equal
>
>  MAINTAINERS                                   |  4 +-
>  lib/librte_eal/include/generic/rte_mcslock.h  | 16 ------
>  lib/librte_eal/include/generic/rte_pause.h    | 12 -----
>  .../include/generic/rte_ticketlock.h          |  9 ----
>  lib/librte_rcu/rte_rcu_qsbr.h                 | 52 -------------------
>  lib/librte_rcu/rte_rcu_version.map            | 11 +++-
>  6 files changed, 11 insertions(+), 93 deletions(-)
>

Series applied, thanks.


-- 
David Marchand

Re: [dpdk-dev] [PATCH 4/4] eal/pause: remove experimental tag from wait until equal

[Stephen Hemminger]

On Fri, 11 Sep 2020 13:45:34 +0800
Joyce Kong <joyce.kong@arm.com> wrote:

> rte_wait_until_equal_xx APIs were introduced in 19.11 release
> and there were no changes in the public APIs since then, it
> should be mature enough to remove the experimental tag.
> 
> Signed-off-by: Joyce Kong <joyce.kong@arm.com>
> Reviewed-by: Phil Yang <phil.yang@arm.com>
> Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>



Acked-by: Stephen Hemminger <stephen@networkplumber.org>