Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Fri, 9 Feb 2018 06:29:23 -0800
From:   "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
To:     Andrea Parri <parri.andrea@gmail.com>
Cc:     Akira Yokosawa <akiyks@gmail.com>, linux-kernel@vger.kernel.org,
        linux-doc@vger.kernel.org, stern@rowland.harvard.edu,
        will.deacon@arm.com, peterz@infradead.org, boqun.feng@gmail.com,
        npiggin@gmail.com, dhowells@redhat.com, j.alglave@ucl.ac.uk,
        luc.maranget@inria.fr, corbet@lwn.net
Subject: Re: [PATCH 1/2] Documentation/memory-barriers.txt: cross-reference
 "tools/memory-model/"
Reply-To: paulmck@linux.vnet.ibm.com
References: <20180203012103.GD3617@linux.vnet.ibm.com>
 <8b4db282-2705-ed96-cf23-b0cdf94bbac8@gmail.com>
 <20180204183708.GA10437@andrea>
 <20180209123100.GY3617@linux.vnet.ibm.com>
 <20180209125051.GA21678@andrea>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180209125051.GA21678@andrea>
User-Agent: Mutt/1.5.21 (2010-09-15)
Message-Id: <20180209142923.GB3617@linux.vnet.ibm.com>
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Fri, Feb 09, 2018 at 01:50:51PM +0100, Andrea Parri wrote:
> On Fri, Feb 09, 2018 at 04:31:00AM -0800, Paul E. McKenney wrote:
> > On Sun, Feb 04, 2018 at 07:37:08PM +0100, Andrea Parri wrote:
> > > 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.
> > 
> > Any objections to Akira's patch below?  (Give or take the usual
> > wordsmithing.)
> > 
> > Andrea, should I interpret your paragraph above ask an Acked-by?
> 
> Well, I am among the Signed-off-by: of the patch; it didn't seem too fair
> to me to Ack my own patch... ;-) Is the wording sound? other suggestions?

Good point, too many all-day meetings last week.  ;-)

How about the following?

							Thanx, Paul

------------------------------------------------------------------------

commit 9370f98c312d658afe88e548d469549d8f31e402
Author: Andrea Parri <parri.andrea@gmail.com>
Date:   Fri Feb 9 06:26:08 2018 -0800

    Documentation/memory-barriers.txt: Cross-reference "tools/memory-model/"
    
    A memory consistency model is now available 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".
    
    Inform the (occasional) reader of memory-barriers.txt of these
    developments.
    
    [1] https://marc.info/?l=linux-kernel&m=151687290114799&w=2
    
    Co-developed-by: Andrea Parri <parri.andrea@gmail.com>
    Co-developed-by: Akira Yokosawa <akiyks@gmail.com>
    Signed-off-by: Andrea Parri <parri.andrea@gmail.com>
    Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
    Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>

diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 479ecec80593..74ad222d11ed 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -14,7 +14,11 @@ 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.  Some doubts may be
+resolved by referring to the formal memory consistency model and related
+documentation at tools/memory-model/.  Nevertheless, even this memory
+model should be viewed as the collective opinion of its maintainers rather
+than as an infallible oracle.
 
 To repeat, this document is not a specification of what Linux expects from
 hardware.