lkml.org 
[lkml]   [2017]   [Jul]   [26]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [RFC][PATCH v3]: documentation,atomic: Add new documents
From
Date
nits... <chirping>

On 07/26/2017 04:53 AM, Peter Zijlstra wrote:
> ---
> Subject: documentation,atomic: Add new documents
> From: Peter Zijlstra <peterz@infradead.org>
> Date: Mon Jun 12 14:50:27 CEST 2017
>
> Since we've vastly expanded the atomic_t interface in recent years the
> existing documentation is woefully out of date and people seem to get
> confused a bit.
>
> Start a new document to hopefully better explain the current state of
> affairs.
>
> The old atomic_ops.txt also covers bitmaps and a few more details so
> this is not a full replacement and we'll therefore keep that document
> around until such a time that we've managed to write more text to cover
> its entire.
>
> Also please, ReST people, go away.
>
> Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
> ---
> Documentation/atomic_bitops.txt | 66 ++++++++++++
> Documentation/atomic_t.txt | 200 ++++++++++++++++++++++++++++++++++++++
> Documentation/memory-barriers.txt | 88 ----------------
> 3 files changed, 269 insertions(+), 85 deletions(-)
>
> --- /dev/null
> +++ b/Documentation/atomic_bitops.txt
> @@ -0,0 +1,66 @@
> +
> +On atomic bitops.
> +
> +
> +While our bitmap_{}() functions are non-atomic, we have a number of operations
> +operating on single bits in a bitmap that are atomic.
> +
> +
> +API
> +---
> +
> +The single bit operations are:
> +
> +Non RmW ops:

Non-RmW ops:

> +
> + test_bit()
> +

[]

> --- /dev/null
> +++ b/Documentation/atomic_t.txt
> @@ -0,0 +1,200 @@
> +
> +On atomic types (atomic_t atomic64_t and atomic_long_t).
> +
> +The atomic type provides an interface to the architecture's means of atomic
> +RmW operations between CPUs (atomic operations on MMIO are not supported and
> +can lead to fatal traps on some platforms).
> +
> +API
> +---
> +
> +The 'full' API consists of (atomic64_ and atomic_long_ prefixes omitted for
> +brevity):
> +
> +Non RmW ops:

Non-RmW ops:

> +
> + atomic_read(), atomic_set()
> + atomic_read_acquire(), atomic_set_release()
> +
> +
> +RmW atomic operations:
> +
> +Arithmetic:
> +
> + atomic_{add,sub,inc,dec}()
> + atomic_{add,sub,inc,dec}_return{,_relaxed,_acquire,_release}()
> + atomic_fetch_{add,sub,inc,dec}{,_relaxed,_acquire,_release}()
> +
> +
> +Bitwise:
> +
> + atomic_{and,or,xor,andnot}()
> + atomic_fetch_{and,or,xor,andnot}{,_relaxed,_acquire,_release}()
> +
> +
> +Swap:
> +
> + atomic_xchg{,_relaxed,_acquire,_release}()
> + atomic_cmpxchg{,_relaxed,_acquire,_release}()
> + atomic_try_cmpxchg{,_relaxed,_acquire,_release}()
> +
> +
> +Reference count (but please see refcount_t):
> +
> + atomic_add_unless(), atomic_inc_not_zero()
> + atomic_sub_and_test(), atomic_dec_and_test()
> +
> +
> +Misc:
> +
> + atomic_inc_and_test(), atomic_add_negative()
> + atomic_dec_unless_positive(), atomic_inc_unless_negative()
> +
> +
> +Barriers:
> +
> + smp_mb__{before,after}_atomic()
> +
> +
> +
> +SEMANTICS
> +---------
> +
> +Non RmW ops:

Non-RmW ops:

> +
> +The non-RmW ops are (typically) regular LOADs and STOREs and are canonically
> +implemented using READ_ONCE(), WRITE_ONCE(), smp_load_acquire() and
> +smp_store_release() respectively.
> +
> +The one detail to this is that atomic_set{}() should be observable to the RmW
> +ops. That is:
> +
> + C atomic-set
> +
> + {
> + atomic_set(v, 1);
> + }
> +
> + P1(atomic_t *v)
> + {
> + atomic_add_unless(v, 1, 0);
> + }
> +
> + P2(atomic_t *v)
> + {
> + atomic_set(v, 0);
> + }
> +
> + exists
> + (v=2)
> +
> +In this case we would expect the atomic_set() from CPU1 to either happen
> +before the atomic_add_unless(), in which case that latter one would no-op, or
> +_after_ in which case we'd overwrite its result. In no case is "2" a valid
> +outcome.
> +
> +This is typically true on 'normal' platforms, where a regular competing STORE
> +will invalidate a LL/SC or fail a CMPXCHG.
> +
> +The obvious case where this is not so is when we need to implement atomic ops
> +with a lock:
> +
> + CPU0 CPU1
> +
> + atomic_add_unless(v, 1, 0);
> + lock();
> + ret = READ_ONCE(v->counter); // == 1
> + atomic_set(v, 0);
> + if (ret != u) WRITE_ONCE(v->counter, 0);
> + WRITE_ONCE(v->counter, ret + 1);
> + unlock();
> +
> +the typical solution is to then implement atomic_set{}() with atomic_xchg().
> +
> +
> +RmW ops:

I prefer (and have usually seen) RMW, but it's your document -- er, text file. :)


> +
> +These come in various forms:
> +

[]

> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -498,7 +498,7 @@ VARIETIES OF MEMORY BARRIER
> This means that ACQUIRE acts as a minimal "acquire" operation and
> RELEASE acts as a minimal "release" operation.
>
> -A subset of the atomic operations described in core-api/atomic_ops.rst have
> +A subset of the atomic operations described in atomic_t.txt have ACQUIRE
> ACQUIRE and RELEASE variants in addition to fully-ordered and relaxed (no

duplicate ACQUIRE.

> barrier semantics) definitions. For compound atomics performing both a load
> and a store, ACQUIRE semantics apply only to the load and RELEASE semantics



--
~Randy

\
 
 \ /
  Last update: 2017-07-26 18:29    [W:0.162 / U:1.476 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site