On Thu, Nov 05, 2020 at 02:00:14PM -0800, paul...@kernel.org wrote:
> From: "Paul E. McKenney" <paul...@kernel.org>
>
> Signed-off-by: Paul E. McKenney <paul...@kernel.org>
> ---
> tools/memory-model/Documentation/glossary.txt | 155
> ++++++++++++++++++++++++++
> 1 file changed, 155 insertions(+)
> create mode 100644 tools/memory-model/Documentation/glossary.txt
>
> diff --git a/tools/memory-model/Documentation/glossary.txt
> b/tools/memory-model/Documentation/glossary.txt
> new file mode 100644
> index 0000000..036fa28
> --- /dev/null
> +++ b/tools/memory-model/Documentation/glossary.txt
> @@ -0,0 +1,155 @@
> +This document contains brief definitions of LKMM-related terms. Like most
> +glossaries, it is not intended to be read front to back (except perhaps
> +as a way of confirming a diagnosis of OCD), but rather to be searched
> +for specific terms.
> +
> +
> +Address Dependency: When the address of a later memory access is computed
> + based on the value returned by an earlier load, an "address
> + dependency" extends from that load extending to the later access.
> + Address dependencies are quite common in RCU read-side critical
> + sections:
> +
> + 1 rcu_read_lock();
> + 2 p = rcu_dereference(gp);
> + 3 do_something(p->a);
> + 4 rcu_read_unlock();
> +
> + In this case, because the address of "p->a" on line 3 is computed
> + from the value returned by the rcu_dereference() on line 2, the
> + address dependency extends from that rcu_dereference() to that
> + "p->a". In rare cases, optimizing compilers can destroy address
> + dependencies. Please see Documentation/RCU/rcu_dereference.txt
> + for more information.
> +
> + See also "Control Dependency".
> +
> +Acquire: With respect to a lock, acquiring that lock, for example,
> + using spin_lock(). With respect to a non-lock shared variable,
> + a special operation that includes a load and which orders that
> + load before later memory references running on that same CPU.
> + An example special acquire operation is smp_load_acquire(),
> + but atomic_read_acquire() and atomic_xchg_acquire() also include
> + acquire loads.
> +
> + When an acquire load returns the value stored by a release store
> + to that same variable, then all operations preceding that store
Change this to:
When an acquire load reads-from a release store
, and put a reference to "Reads-from"? I think this makes the document
more consistent in that it makes clear "an acquire load returns the
value stored by a release store to the same variable" is not a special
case, it's simple a "Reads-from".
> + happen before any operations following that load acquire.
Add a reference to the definition of "happen before" in explanation.txt?
Regards,
Boqun
> +
> + See also "Relaxed" and "Release".
> +
[...]
