Re: [PATCH 1/2] Documentation/memory-barriers.txt: cross-reference "tools/memory-model/"

[Andrea Parri <parri.andrea@gmail.com>]

Hi Akira,

On Mon, Feb 05, 2018 at 01:14:10AM +0900, Akira Yokosawa wrote:
> Hi Paul,
> CC: Andrea
> 
> This is intentionally off the list, as I was not cc'd in the thread.
> If you think it is worthwhile, could you help me join the thread by
> forwarding the following part as a reply to your message, plus CC: to me.

[CCing lists and other people]


> 
> On Fri, Feb 02, 2018 at 17:21:03AM -0800, Paul E. McKenney wrote:
> > On Fri, Feb 02, 2018 at 10:12:48AM +0100, Andrea Parri wrote:
> >> Recent efforts led to the specification of a memory consistency model
> >> for the Linux kernel [1], which "can (roughly speaking) be thought of
> >> as an automated version of memory-barriers.txt" and which is (in turn)
> >> "accompanied by extensive documentation on its use and its design".
> >> 
> >> Make sure that the (occasional) reader of memory-barriers.txt will be
> >> aware of these developments.
> >> 
> >> [1] https://marc.info/?l=linux-kernel&m=151687290114799&w=2
> >> 
> >> Signed-off-by: Andrea Parri <parri.andrea@xxxxxxxxx>
> > 
> > I am inclined to pull in something along these lines, but would like
> > some feedback on the wording, especially how "official" we want to
> > make the memory model to be.
> > 
> > Thoughts?
> 
> The change log of commit e7720af5f9ac ("locking/Documentation: Add disclaimer") says:
>     
>     It appears people are reading this document as a requirements list for
>     building hardware. This is not the intent of this document. Nor is it
>     particularly suited for this purpose.
>     
>     The primary purpose of this document is our collective attempt to define
>     a set of primitives that (hopefully) allow us to write correct code on
>     the myriad of SMP platforms Linux supports.
>     
>     Its a definite work in progress as our understanding of these platforms,
>     and memory ordering in general, progresses.
>     
>     Nor does being mentioned in this document mean we think its a
>     particularly good idea; the data dependency barrier required by Alpha
>     being a prime example. Yes we have it, no you're insane to require it
>     when building new hardware.
> 
> My take on the Linux Kernel memory-consistency model is a supplement of
> memory-barriers.txt and the disclaimer also applies to the memory model.
> 
> > 
> > If I don't hear otherwise in a couple of days, I will pull this as is.
> > 
> > 							Thanx, Paul
> > 
> >> ---
> >>  Documentation/memory-barriers.txt | 4 +++-
> >>  1 file changed, 3 insertions(+), 1 deletion(-)
> >> 
> >> diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
> >> index a863009849a3b..8cc3f098f4a7d 100644
> >> --- a/Documentation/memory-barriers.txt
> >> +++ b/Documentation/memory-barriers.txt
> >> @@ -17,7 +17,9 @@ meant as a guide to using the various memory barriers provided by Linux, but
> >>  in case of any doubt (and there are many) please ask.
> >> 
> >>  To repeat, this document is not a specification of what Linux expects from
> >> -hardware.
> >> +hardware.  For such a specification, in the form of a memory consistency
> >> +model, and for documentation about its usage and its design, the reader is
> >> +referred to "tools/memory-model/".
> >> 
> 
> Adding cross-reference in this way can _weaken_ the message of the disclaimer.

Thank you for your remarks; I do share the same concern.


> What about adding it in the previous sentence as the patch appended bellow?

I do like this idea: I believe that my phrasing (and that "what Linux
expects from hardware") may be easily subject to misinterpretation...
which your solution can avoid.

  Andrea


> 
> The tag use in the change log may need adjustments. I'm not familiar with the
> manner in modifying other persons' patches. Of course, the wording itself can
> be improved further.  Any feedback is welcome.
> 
>      Thanks, Akira
> 
> >>  The purpose of this document is twofold:
> >> 
> >> -- 
> >> 2.7.4
> >> 
> 
> ----8<-------
> From 714e8c4b09acd6e965de116532dce05070b9e636 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@gmail.com>
> Date: Mon, 5 Feb 2018 00:28:36 +0900
> Subject: [PATCH] Documentation/memory-barriers.txt: cross-reference "tools/memory-model/"
> 
> Recent efforts led to the specification of a memory consistency model
> for the Linux kernel [1], which "can (roughly speaking) be thought of
> as an automated version of memory-barriers.txt" and which is (in turn)
> "accompanied by extensive documentation on its use and its design".
> 
> Make sure that the (occasional) reader of memory-barriers.txt will be
> aware of these developments.
> 
> [1] https://marc.info/?l=linux-kernel&m=151687290114799&w=2
> 
> Signed-off-by: Andrea Parri <parri.andrea@gmail.com>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
>  Documentation/memory-barriers.txt | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
> index 479ecec..975488d 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -14,7 +14,9 @@ DISCLAIMER
>  This document is not a specification; it is intentionally (for the sake of
>  brevity) and unintentionally (due to being human) incomplete. This document is
>  meant as a guide to using the various memory barriers provided by Linux, but
> -in case of any doubt (and there are many) please ask.
> +in case of any doubt (and there are many) please ask. For clarification of such
> +doubt, in the form of a memory consistency model, and for documentation about
> +its usage and its design, the reader is referred to "tools/memory-model/".
>  
>  To repeat, this document is not a specification of what Linux expects from
>  hardware.
> -- 
> 2.7.4
> 
> 
>