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

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

[Andrea Parri]

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>
---
 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/".
 
 The purpose of this document is twofold:
 
-- 
2.7.4

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

[Paul E. McKenney]

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@gmail.com>

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?

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/".
> 
>  The purpose of this document is twofold:
> 
> -- 
> 2.7.4
> 

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

[Andrea Parri]

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
> 
> 
> 

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

[Paul E. McKenney]

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?

							Thanx, Paul

>   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
> > 
> > 
> > 
> 

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

[Andrea Parri]

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?

  Andrea


> 
> 							Thanx, Paul
> 
> >   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
> > > 
> > > 
> > > 
> > 
> 

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

[Akira Yokosawa]

On 2018/02/09 21:50, 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?
> 
>   Andrea

Well, I should have kept the author of the patch.
I.e. I guess the author should have been

    From: Andrea Parri <parri.andrea@gmail.com>

???

If you'd like, I can respin the patch.

      Thanks, Akira

> 
> 
>>
>> 							Thanx, Paul
>>
>>>   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
>>>>
>>>>
>>>>
>>>
>>

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

[Paul E. McKenney]

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.

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

[Akira Yokosawa]

On 2018/02/09 23:29, Paul E. McKenney wrote:
> 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.

It's impossible for me to come up with the words "infallible oracle"!
Looks nice.

    Thanks, Akira

>  
>  To repeat, this document is not a specification of what Linux expects from
>  hardware.
> 

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

[Andrea Parri]

On Fri, Feb 09, 2018 at 06:29:23AM -0800, Paul E. McKenney wrote:
> 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?

Even better IMO,

Thanks!

  Andrea


> 
> 							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.
> 

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

[Paul E. McKenney]

On Fri, Feb 09, 2018 at 04:00:53PM +0100, Andrea Parri wrote:
> On Fri, Feb 09, 2018 at 06:29:23AM -0800, Paul E. McKenney wrote:
> > 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?
> 
> Even better IMO,

Very good, thank you both!

I will include this in the version of the series.

							Thanx, Paul

> Thanks!
> 
>   Andrea
> 
> 
> > 
> > 							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.
> > 
>