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. > -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
