[PATCH] eal: add notes to SMP memory barrier APIs

[Ruifeng Wang]

> -----Original Message-----
> From: Tyler Retzlaff <roretzla at linux.microsoft.com>
> Sent: Saturday, June 24, 2023 5:51 AM
> To: Mattias Rönnblom <hofors at lysator.liu.se>
> Cc: Ruifeng Wang <Ruifeng.Wang at arm.com>; thomas at monjalon.net; david.marchand at redhat.com;
> dev at dpdk.org; konstantin.v.ananyev at yandex.ru; Honnappa Nagarahalli
> <Honnappa.Nagarahalli at arm.com>; nd <nd at arm.com>
> Subject: Re: [PATCH] eal: add notes to SMP memory barrier APIs
> 
> On Thu, Jun 22, 2023 at 08:19:30PM +0200, Mattias R�nnblom wrote:
> > On 2023-06-21 08:44, Ruifeng Wang wrote:
> > >The rte_smp_xx() APIs are deprecated. But it is not mentioned in the
> > >function header.
> > >Added notes in function header for clarification.
> > >
> > >Signed-off-by: Ruifeng Wang <ruifeng.wang at arm.com>
> > >---
> > >  lib/eal/include/generic/rte_atomic.h | 15 +++++++++++++++
> > >  1 file changed, 15 insertions(+)
> > >
> > >diff --git a/lib/eal/include/generic/rte_atomic.h
> > >b/lib/eal/include/generic/rte_atomic.h
> > >index 58df843c54..542a2c16ff 100644
> > >--- a/lib/eal/include/generic/rte_atomic.h
> > >+++ b/lib/eal/include/generic/rte_atomic.h
> > >@@ -55,6 +55,11 @@ static inline void rte_rmb(void);
> > >   * Guarantees that the LOAD and STORE operations that precede the
> > >   * rte_smp_mb() call are globally visible across the lcores
> > >   * before the LOAD and STORE operations that follows it.
> > >+ *
> > >+ * @note
> > >+ *  This function is deprecated. It adds complexity to the memory
> > >+ model
> > >+ *  used by this project. C11 memory model should always be used.
> > >+ *  rte_atomic_thread_fence() should be used instead.
> >
> > It's somewhat confusing to learn I should use the C11 memory model,
> > and then in the next sentence that I should call a function which is
> > not in C11.
> 
> i wonder if we can just do without the comments until we begin to adopt changes for 23.11
> release because the guidance will be short lived.
> 
> in 23.07 we want to say that only gcc builtins that align with the standard C++ memory
> model should be used.
> 
> in 23.11 we want to say that only standard C11 atomics should be used.

Good point. The memory order parameter will change in 23.11.

> 
> my suggestion i guess is just adapt the patch to be appropriate for
> 23.11 and only merge it after 23.07 release? might be easier to manage.

Agree to only merge it after 23.07. 
I will update the comment for standard C11 atomics.

> 
> >
> > I think it would be helpful to say which memory_model parameters
> > should be used to replace the rte_smp_*mb() calls, and if there are
> > any difference in semantics between the Linux kernel-style barriers
> > and their C11 (near-)equivalents.
> >
> > Is there some particular reason these functions aren't marked
> > __rte_deprecated? Too many warnings?
> >
> > >   */
> > >  static inline void rte_smp_mb(void); @@ -64,6 +69,11 @@ static
> > >inline void rte_smp_mb(void);
> > >   * Guarantees that the STORE operations that precede the
> > >   * rte_smp_wmb() call are globally visible across the lcores
> > >   * before the STORE operations that follows it.
> > >+ *
> > >+ * @note
> > >+ *  This function is deprecated. It adds complexity to the memory
> > >+ model
> > >+ *  used by this project. C11 memory model should always be used.
> > >+ *  rte_atomic_thread_fence() should be used instead.
> > >   */
> > >  static inline void rte_smp_wmb(void); @@ -73,6 +83,11 @@ static
> > >inline void rte_smp_wmb(void);
> > >   * Guarantees that the LOAD operations that precede the
> > >   * rte_smp_rmb() call are globally visible across the lcores
> > >   * before the LOAD operations that follows it.
> > >+ *
> > >+ * @note
> > >+ *  This function is deprecated. It adds complexity to the memory
> > >+ model
> > >+ *  used by this project. C11 memory model should always be used.
> > >+ *  rte_atomic_thread_fence() should be used instead.
> > >   */
> > >  static inline void rte_smp_rmb(void);  ///@}