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

From: Akira Yokosawa
Date: Fri Feb 09 2018 - 09:53:43 EST


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@xxxxxxxxx>
> 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@xxxxxxxxx>
> Co-developed-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> Signed-off-by: Andrea Parri <parri.andrea@xxxxxxxxx>
> Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxxxxxxxxxx>
>
> 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.
>