doc: update atomic operation deprecation
PATCH 1/1 doc: update atomic operation deprecation
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
--- doc/guides/rel_notes/deprecation.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-)
doc/guides/rel_notes/deprecation.rst +8 -8
@@ -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
Signature · 1 line
2.17.1
<snip>
Quoted 28 lines
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 operationssemantics")
Cc: [email protected]Signed-off-by Joyce Kong <[email protected]>Reviewed-by Ruifeng Wang <[email protected]>--- doc/guides/rel_notes/deprecation.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-)doc/guides/rel_notes/deprecation.rst +0
-0@@ -19,16 +19,16 @@ Deprecation Notices * rte_atomicNN_xxx: These APIs do not take memory order parameter. Thisdoes
not allow for writing optimized code for all the CPU architectures supported
- in DPDK. DPDK will adopt C11 atomic operations semantics and provide wrappers
doc/guides/rel_notes/deprecation.rst Deprecation Notices
Quoted 6 lines
doc/guides/rel_notes/deprecation.rst +3
-3- 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.
Quoted 12 lines
* rte_smp_*mb: These APIs provide full barrier functionality. However, many
doc/guides/rel_notes/deprecation.rst +0
-2- 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.
doc/guides/rel_notes/deprecation.rst +5
-2- 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
Quoted 1 line
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.
Quoted 7 lines
* 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
PATCH v2 1/1 doc: update atomic operation deprecation
In reply to Joyce KongUpdate the incorrect description about atomic operations with provided wrappers in deprecation doc[1].
[1]https://mails.dpdk.org/archives/dev/2021-July/213333.html
--- doc/guides/rel_notes/deprecation.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-)
doc/guides/rel_notes/deprecation.rst +10 -8
@@ -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
Signature · 1 line
2.17.1
Thomas Monjalon
Applied23/07/2021 11:49, Joyce Kong:
Quoted 10 lines
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")Signed-off-by Joyce Kong <[email protected]>Reviewed-by Ruifeng Wang <[email protected]>
Applied, thanks.
Considering all the questions regarding usage of atomics, I still think we need a documentation about their correct use.
Quoted 21 lines
-----Original Message-----
From: Thomas Monjalon <[email protected]>
Sent: Saturday, July 31, 2021 3:27 PM
To: Honnappa Nagarahalli <[email protected]>; Ruifeng Wang <[email protected]>; Joyce Kong <[email protected]>
Cc: [email protected]; [email protected]; [email protected]; nd <[email protected]>; [email protected]
Subject: Re: [dpdk-dev] [PATCH v2] doc: update atomic operation deprecation23/07/2021 11:49, Joyce Kong:
Quoted 9 lines
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 operationssemantics")
Cc: [email protected]
Quoted 7 lines
Quoted 2 lines
Signed-off-by Joyce Kong <[email protected]>Reviewed-by Ruifeng Wang <[email protected]>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?
Quoted 1 line
02/08/2021 19:22, Honnappa Nagarahalli:
Quoted 9 lines
From: Thomas Monjalon <[email protected]>
Quoted 3 lines
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_fetchvs__atomic_fetch_add
2) Using__ATOMIC_RELAXEDfor statistics
3) Usingrte_atomic_thread_fenceAPI
That's a good list.
Let's start with that please.
I would like an explanation about when full barrier may be used.