Skip to contentSkip to conversation

Documentation/memory-barriers.txt: cross-reference "tools/memory-model/"

PATCH In review Andrea Parri 3 participants 10 messages Feb 2, 2018 – Feb 10, 2018 1 message not in the archive

Subsystems (2)
lore
Share & tools
lore

Andrea Parri

author maintainer
#0 lore raw

PATCH 1/2 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

---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +3 -1
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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:
 
Signature · 1 line
2.7.4
#1 lore raw
Quoted 11 lines · 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

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

Quoted 22 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +3 -1
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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:
 
Signature · 1 line
2.7.4

A message that is not in the archive (sent off-list or not yet received): [email protected]

author maintainer
#3 lore raw

Hi Akira,

Quoted 6 lines · Akira Yokosawa

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]

Quoted 58 lines · Paul E. McKenney
Quoted 11 lines · Andrea Parri
Quoted 10 lines

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

Quoted 7 lines
Quoted 1 line

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.

Quoted 16 lines

If I don't hear otherwise in a couple of days, I will pull this as is.

Thanx, Paul

Quoted 11 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +0 -0
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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.
 
Quoted 8 lines
Quoted 6 lines

Documentation/memory-barriers.txt meant as a guide to using the various memory barriers provided by Linux, but · line 23

Quoted 6 lines
Documentation/memory-barriers.txt +3 -1
 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.

Quoted 1 line

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

Quoted 55 lines

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

Quoted 5 lines
Quoted 5 lines
Documentation/memory-barriers.txt +0 -0
 The purpose of this document is twofold:
 
Signature · 1 line
2.7.4

----8<-------
From 714e8c4b09acd6e965de116532dce05070b9e636 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
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

---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +3 -1
index 479ecec..975488d 100644
@@ -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.
Signature · 1 line
2.7.4
#4 lore raw
Quoted 80 lines · Andrea Parri

Hi Akira,

Quoted 6 lines · Akira Yokosawa

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]

Quoted 58 lines · Paul E. McKenney
Quoted 11 lines · Andrea Parri
Quoted 10 lines

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

Quoted 7 lines
Quoted 1 line

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.

Quoted 16 lines

If I don't hear otherwise in a couple of days, I will pull this as is.

Thanx, Paul

Quoted 11 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +0 -0
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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.
 
Quoted 8 lines
Quoted 6 lines

Documentation/memory-barriers.txt meant as a guide to using the various memory barriers provided by Linux, but · line 23

Quoted 6 lines
Documentation/memory-barriers.txt +3 -1
 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.

Quoted 7 lines

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

Quoted 1 line

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

Quoted 59 lines

Andrea

Quoted 55 lines

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

Quoted 5 lines
Quoted 5 lines
Documentation/memory-barriers.txt +0 -0
 The purpose of this document is twofold:
 
Signature · 1 line
2.7.4

----8<-------
From 714e8c4b09acd6e965de116532dce05070b9e636 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
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

---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +3 -1
index 479ecec..975488d 100644
@@ -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.
Signature · 1 line
2.7.4
author maintainer
#5 lore raw
Quoted 85 lines · Paul E. McKenney
Quoted 84 lines · Andrea Parri

Hi Akira,

Quoted 6 lines · Akira Yokosawa

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]

Quoted 58 lines · Paul E. McKenney
Quoted 11 lines · Andrea Parri
Quoted 10 lines

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

Quoted 7 lines
Quoted 1 line

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.

Quoted 16 lines

If I don't hear otherwise in a couple of days, I will pull this as is.

Thanx, Paul

Quoted 11 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +0 -0
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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.
 
Quoted 8 lines
Quoted 6 lines

Documentation/memory-barriers.txt meant as a guide to using the various memory barriers provided by Linux, but · line 23

Quoted 6 lines
Documentation/memory-barriers.txt +3 -1
 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.

Quoted 1 line

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

Quoted 8 lines
Quoted 3 lines

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

Quoted 63 lines

Thanx, Paul

Quoted 59 lines

Andrea

Quoted 55 lines

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

Quoted 5 lines
Quoted 5 lines
Documentation/memory-barriers.txt +0 -0
 The purpose of this document is twofold:
 
Signature · 1 line
2.7.4

----8<-------
From 714e8c4b09acd6e965de116532dce05070b9e636 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
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

---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +3 -1
index 479ecec..975488d 100644
@@ -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.
Signature · 1 line
2.7.4
#6 lore raw
Quoted 93 lines · Andrea Parri
Quoted 92 lines · Paul E. McKenney
Quoted 80 lines · Andrea Parri

Hi Akira,

Quoted 6 lines · Akira Yokosawa

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]

Quoted 58 lines · Paul E. McKenney
Quoted 11 lines · Andrea Parri
Quoted 10 lines

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

Quoted 7 lines
Quoted 1 line

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.

Quoted 16 lines

If I don't hear otherwise in a couple of days, I will pull this as is.

Thanx, Paul

Quoted 11 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +0 -0
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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.
 
Quoted 8 lines
Quoted 6 lines

Documentation/memory-barriers.txt meant as a guide to using the various memory barriers provided by Linux, but · line 23

Quoted 6 lines
Documentation/memory-barriers.txt +3 -1
 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.

Quoted 7 lines

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

Quoted 1 line

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

Quoted 6 lines
Quoted 1 line

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 <[email protected]>

???

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

Thanks, Akira

Quoted 65 lines
Quoted 65 lines

Thanx, Paul

Quoted 59 lines

Andrea

Quoted 55 lines

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

Quoted 5 lines
Quoted 5 lines
Documentation/memory-barriers.txt +0 -0
 The purpose of this document is twofold:
 
Signature · 1 line
2.7.4

----8<-------
From 714e8c4b09acd6e965de116532dce05070b9e636 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
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

---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +3 -1
index 479ecec..975488d 100644
@@ -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.
Signature · 1 line
2.7.4
#7 lore raw
In reply to Andrea Parri
Quoted 90 lines · Andrea Parri
Quoted 89 lines · Paul E. McKenney
Quoted 87 lines · Andrea Parri

Hi Akira,

Quoted 6 lines · Akira Yokosawa

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]

Quoted 58 lines · Paul E. McKenney
Quoted 11 lines · Andrea Parri
Quoted 10 lines

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

Quoted 7 lines
Quoted 1 line

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.

Quoted 16 lines

If I don't hear otherwise in a couple of days, I will pull this as is.

Thanx, Paul

Quoted 11 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +0 -0
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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.
 
Quoted 8 lines
Quoted 6 lines

Documentation/memory-barriers.txt meant as a guide to using the various memory barriers provided by Linux, but · line 23

Quoted 6 lines
Documentation/memory-barriers.txt +3 -1
 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.

Quoted 1 line

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.

Quoted 7 lines
Quoted 4 lines

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 <[email protected]>
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

Documentation/memory-barriers.txt +5 -1
index 479ecec80593..74ad222d11ed 100644
@@ -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.
#8 lore raw
Quoted 134 lines · Paul E. McKenney
Quoted 90 lines · Andrea Parri
Quoted 89 lines · Paul E. McKenney
Quoted 87 lines · Andrea Parri

Hi Akira,

Quoted 6 lines · Akira Yokosawa

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]

Quoted 58 lines · Paul E. McKenney
Quoted 11 lines · Andrea Parri
Quoted 10 lines

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

Quoted 7 lines
Quoted 1 line

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.

Quoted 16 lines

If I don't hear otherwise in a couple of days, I will pull this as is.

Thanx, Paul

Quoted 11 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +0 -0
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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.
 
Quoted 8 lines
Quoted 6 lines

Documentation/memory-barriers.txt meant as a guide to using the various memory barriers provided by Linux, but · line 23

Quoted 6 lines
Documentation/memory-barriers.txt +3 -1
 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.

Quoted 1 line

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.

Quoted 7 lines
Quoted 4 lines

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 <[email protected]>
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

Documentation/memory-barriers.txt +0 -0
index 479ecec80593..74ad222d11ed 100644

Documentation/memory-barriers.txt DISCLAIMER · line 21

Quoted 9 lines
Documentation/memory-barriers.txt +5 -1
@@ -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

Quoted 4 lines
Documentation/memory-barriers.txt +0 -0
 To repeat, this document is not a specification of what Linux expects from
 hardware.
 
author maintainer
#9 lore raw
In reply to Paul E. McKenney
Quoted 94 lines · Paul E. McKenney
Quoted 93 lines · Andrea Parri
Quoted 92 lines · Paul E. McKenney
Quoted 80 lines · Andrea Parri

Hi Akira,

Quoted 6 lines · Akira Yokosawa

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]

Quoted 58 lines · Paul E. McKenney
Quoted 11 lines · Andrea Parri
Quoted 10 lines

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

Quoted 7 lines
Quoted 1 line

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.

Quoted 16 lines

If I don't hear otherwise in a couple of days, I will pull this as is.

Thanx, Paul

Quoted 11 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +0 -0
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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.
 
Quoted 8 lines
Quoted 6 lines

Documentation/memory-barriers.txt meant as a guide to using the various memory barriers provided by Linux, but · line 23

Quoted 6 lines
Documentation/memory-barriers.txt +3 -1
 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.

Quoted 7 lines

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

Quoted 1 line

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

Quoted 8 lines
Quoted 4 lines
Quoted 1 line

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

Quoted 45 lines

Thanx, Paul

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

commit 9370f98c312d658afe88e548d469549d8f31e402

Author: Andrea Parri <[email protected]>
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

Documentation/memory-barriers.txt +5 -1
index 479ecec80593..74ad222d11ed 100644
@@ -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.
#10 lore raw
Quoted 97 lines · Andrea Parri
Quoted 96 lines · Paul E. McKenney
Quoted 95 lines · Andrea Parri
Quoted 93 lines · Paul E. McKenney
Quoted 80 lines · Andrea Parri

Hi Akira,

Quoted 6 lines · Akira Yokosawa

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]

Quoted 58 lines · Paul E. McKenney
Quoted 11 lines · Andrea Parri
Quoted 10 lines

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

Quoted 7 lines
Quoted 1 line

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.

Quoted 16 lines

If I don't hear otherwise in a couple of days, I will pull this as is.

Thanx, Paul

Quoted 11 lines
---
 Documentation/memory-barriers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/memory-barriers.txt +0 -0
index a863009849a3b..8cc3f098f4a7d 100644
@@ -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.
 
Quoted 8 lines
Quoted 6 lines

Documentation/memory-barriers.txt meant as a guide to using the various memory barriers provided by Linux, but · line 23

Quoted 6 lines
Documentation/memory-barriers.txt +3 -1
 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.

Quoted 7 lines

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

Quoted 1 line

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?

Quoted 8 lines
Quoted 6 lines
Quoted 2 lines

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

Quoted 51 lines

Thanks!

Andrea

Quoted 45 lines

Thanx, Paul

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

commit 9370f98c312d658afe88e548d469549d8f31e402

Author: Andrea Parri <[email protected]>
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

Documentation/memory-barriers.txt +5 -1
index 479ecec80593..74ad222d11ed 100644
@@ -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.