Update the incorrect description about atomic operations with provided wrappers in deprecation doc[1]. [1]https://mails.dpdk.org/archives/dev/2021-July/213333.html Fixes: 7518c5c4ae6a ("doc: announce adoption of C11 atomic operations semantics") Cc: stable@dpdk.org Signed-off-by: Joyce Kong <joyce.kong@arm.com> Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com> --- doc/guides/rel_notes/deprecation.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index 9584d6bfd7..4142315842 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -19,16 +19,16 @@ Deprecation Notices * rte_atomicNN_xxx: These APIs do not take memory order parameter. This does not allow for writing optimized code for all the CPU architectures supported - in DPDK. DPDK will adopt C11 atomic operations semantics and provide wrappers - using C11 atomic built-ins. These wrappers must be used for patches that - need to be merged in 20.08 onwards. This change will not introduce any - performance degradation. + in DPDK. DPDK has adopted atomic operations semantics. GCC atomic built-ins + must be used for patches that need to be merged in 20.08 onwards. This change + will not introduce any performance degradation. * rte_smp_*mb: These APIs provide full barrier functionality. However, many - use cases do not require full barriers. To support such use cases, DPDK will - adopt C11 barrier semantics and provide wrappers using C11 atomic built-ins. - These wrappers must be used for patches that need to be merged in 20.08 - onwards. This change will not introduce any performance degradation. + use cases do not require full barriers. To support such use cases, DPDK has + adopted atomic barrier semantics. GCC atomic built-ins and a new wrapper + ``rte_atomic_thread_fence`` instead of ``__atomic_thread_fence`` must be + used for patches that need to be merged in 20.08 onwards. This change will + not introduce any performance degradation. * lib: will fix extending some enum/define breaking the ABI. There are multiple samples in DPDK that enum/define terminated with a ``.*MAX.*`` value which is -- 2.17.1
<snip> > > Update the incorrect description about atomic operations with provided > wrappers in deprecation doc[1]. > > [1]https://mails.dpdk.org/archives/dev/2021-July/213333.html > > Fixes: 7518c5c4ae6a ("doc: announce adoption of C11 atomic operations > semantics") > Cc: stable@dpdk.org > > Signed-off-by: Joyce Kong <joyce.kong@arm.com> > Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com> > --- > doc/guides/rel_notes/deprecation.rst | 16 ++++++++-------- > 1 file changed, 8 insertions(+), 8 deletions(-) > > diff --git a/doc/guides/rel_notes/deprecation.rst > b/doc/guides/rel_notes/deprecation.rst > index 9584d6bfd7..4142315842 100644 > --- a/doc/guides/rel_notes/deprecation.rst > +++ b/doc/guides/rel_notes/deprecation.rst > @@ -19,16 +19,16 @@ Deprecation Notices > > * rte_atomicNN_xxx: These APIs do not take memory order parameter. This > does > not allow for writing optimized code for all the CPU architectures supported > - in DPDK. DPDK will adopt C11 atomic operations semantics and provide > wrappers > - using C11 atomic built-ins. These wrappers must be used for patches that > - need to be merged in 20.08 onwards. This change will not introduce any > - performance degradation. > + in DPDK. DPDK has adopted atomic operations semantics. GCC atomic > + built-ins must be used for patches that need to be merged in 20.08 > + onwards. This change will not introduce any performance degradation. Since there have been objections to the language used to refer to GCC C11 atomic built-ins, may be we add a reference to the GCC pages? DPDK has adopted the atomic operations from https://gcc.gnu.org/onlinedocs/gcc/_005f_005fatomic-Builtins.html. These operations must be used for patches that need to be merged in 20.08 onwards. This change will not introduce any performance degradation. > > * rte_smp_*mb: These APIs provide full barrier functionality. However, many > - use cases do not require full barriers. To support such use cases, DPDK will > - adopt C11 barrier semantics and provide wrappers using C11 atomic built- > ins. > - These wrappers must be used for patches that need to be merged in 20.08 > - onwards. This change will not introduce any performance degradation. > + use cases do not require full barriers. To support such use cases, > + DPDK has adopted atomic barrier semantics. GCC atomic built-ins and a > + new wrapper ``rte_atomic_thread_fence`` instead of > + ``__atomic_thread_fence`` must be used for patches that need to be > + merged in 20.08 onwards. This change will not introduce any performance > degradation. Same here. To support such use cases, DPDK has adopted atomic operations from https://gcc.gnu.org/onlinedocs/gcc/_005f_005fatomic-Builtins.html. A new wrapper ``rte_atomic_thread_fence`` instead of ``__atomic_thread_fence`` must be used for patches that need to be merged in 20.08 onwards. This change will not introduce any performance degradation. > > * lib: will fix extending some enum/define breaking the ABI. There are > multiple > samples in DPDK that enum/define terminated with a ``.*MAX.*`` value > which is > -- > 2.17.1
Update the incorrect description about atomic operations with provided wrappers in deprecation doc[1]. [1]https://mails.dpdk.org/archives/dev/2021-July/213333.html Fixes: 7518c5c4ae6a ("doc: announce adoption of C11 atomic operations semantics") Cc: stable@dpdk.org Signed-off-by: Joyce Kong <joyce.kong@arm.com> Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com> --- doc/guides/rel_notes/deprecation.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index 9584d6bfd7..a4f350fa09 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -19,16 +19,18 @@ Deprecation Notices * rte_atomicNN_xxx: These APIs do not take memory order parameter. This does not allow for writing optimized code for all the CPU architectures supported - in DPDK. DPDK will adopt C11 atomic operations semantics and provide wrappers - using C11 atomic built-ins. These wrappers must be used for patches that - need to be merged in 20.08 onwards. This change will not introduce any - performance degradation. + in DPDK. DPDK has adopted the atomic operations from + https://gcc.gnu.org/onlinedocs/gcc/_005f_005fatomic-Builtins.html. These + operations must be used for patches that need to be merged in 20.08 onwards. + This change will not introduce any performance degradation. * rte_smp_*mb: These APIs provide full barrier functionality. However, many - use cases do not require full barriers. To support such use cases, DPDK will - adopt C11 barrier semantics and provide wrappers using C11 atomic built-ins. - These wrappers must be used for patches that need to be merged in 20.08 - onwards. This change will not introduce any performance degradation. + use cases do not require full barriers. To support such use cases, DPDK has + adopted atomic operations from + https://gcc.gnu.org/onlinedocs/gcc/_005f_005fatomic-Builtins.html. These + operations and a new wrapper ``rte_atomic_thread_fence`` instead of + ``__atomic_thread_fence`` must be used for patches that need to be merged in + 20.08 onwards. This change will not introduce any performance degradation. * lib: will fix extending some enum/define breaking the ABI. There are multiple samples in DPDK that enum/define terminated with a ``.*MAX.*`` value which is -- 2.17.1
23/07/2021 11:49, Joyce Kong:
> Update the incorrect description about atomic operations
> with provided wrappers in deprecation doc[1].
>
> [1]https://mails.dpdk.org/archives/dev/2021-July/213333.html
>
> Fixes: 7518c5c4ae6a ("doc: announce adoption of C11 atomic operations semantics")
> Cc: stable@dpdk.org
>
> Signed-off-by: Joyce Kong <joyce.kong@arm.com>
> Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
Applied, thanks.
Considering all the questions regarding usage of atomics,
I still think we need a documentation about their correct use.
> -----Original Message----- > From: Thomas Monjalon <thomas@monjalon.net> > Sent: Saturday, July 31, 2021 3:27 PM > To: Honnappa Nagarahalli <Honnappa.Nagarahalli@arm.com>; Ruifeng Wang > <Ruifeng.Wang@arm.com>; Joyce Kong <Joyce.Kong@arm.com> > Cc: stephen@networkplumber.org; mdr@ashroe.eu; dev@dpdk.org; nd > <nd@arm.com>; stable@dpdk.org > Subject: Re: [dpdk-dev] [PATCH v2] doc: update atomic operation deprecation > > 23/07/2021 11:49, Joyce Kong: > > Update the incorrect description about atomic operations with provided > > wrappers in deprecation doc[1]. > > > > [1]https://mails.dpdk.org/archives/dev/2021-July/213333.html > > > > Fixes: 7518c5c4ae6a ("doc: announce adoption of C11 atomic operations > > semantics") > > Cc: stable@dpdk.org > > > > Signed-off-by: Joyce Kong <joyce.kong@arm.com> > > Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com> > > Applied, thanks. > > Considering all the questions regarding usage of atomics, I still think we need a > documentation about their correct use. I think few things to document are: 1) Use of __atomic_add_fetch vs __atomic_fetch_add 2) Using __ATOMIC_RELAXED for statistics 3) Using rte_atomic_thread_fence API Anything else? >
02/08/2021 19:22, Honnappa Nagarahalli:
> From: Thomas Monjalon <thomas@monjalon.net>
> > 23/07/2021 11:49, Joyce Kong:
> > Considering all the questions regarding usage of atomics, I still think we need a
> > documentation about their correct use.
>
> I think few things to document are:
> 1) Use of __atomic_add_fetch vs __atomic_fetch_add
> 2) Using __ATOMIC_RELAXED for statistics
> 3) Using rte_atomic_thread_fence API
That's a good list.
Let's start with that please.
I would like an explanation about when full barrier may be used.