Documentation/memory-barriers: fix wrong comment in example
Subsystems (2)
PATCH 1/1 Documentation/memory-barriers: fix wrong comment in example
There is wrong comment in example for compiler store omit behavior. It shows example of the problem and than problem solved version code. However, the comment in the solved version is still same with not solved version. Fix the wrong statement with this commit.
--- Documentation/memory-barriers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/memory-barriers.txt +1 -1
@@ -1471,7 +1471,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + /* Code that does store to variable a. */ WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless
Signature · 1 line
1.9.1
Quoted 6 lines · SeongJae Park
There is wrong comment in example for compiler store omit behavior. It shows example of the problem and than problem solved version code. However, the comment in the solved version is still same with not solved version. Fix the wrong statement with this commit.
Signed-off-by SeongJae Park <[email protected]>
Hmmm... The code between the two stores of zero to "a" is intended to remain the same in the broken and fixed versions. So the only change is from "a = 0" to "WRITE_ONCE(a, 0)". Note that it is some other CPU that did the third store to "a".
Or am I missing your point here?
Thanx, Paul
Quoted 20 lines
--- Documentation/memory-barriers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/memory-barriers.txt +1
-1@@ -1471,7 +1471,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + /* Code that does store to variable a. */ WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unlessSignature · 1 line
1.9.1
Quoted 6 lines · Paul E. McKenney
Quoted 5 lines · SeongJae Park
There is wrong comment in example for compiler store omit behavior. It shows example of the problem and than problem solved version code. However, the comment in the solved version is still same with not solved version. Fix the wrong statement with this commit.
Quoted 6 lines
Quoted 1 line
Signed-off-by SeongJae Park <[email protected]>Hmmm... The code between the two stores of zero to "a" is intended to remain the same in the broken and fixed versions. So the only change is from "a = 0" to "
WRITE_ONCE(a, 0)". Note that it is some other CPU that did the third store to "a".
Agree, of course.
Quoted 2 lines
Or am I missing your point here?
My point is about the comment.
I thought the comment in broken version is saying "Below line(a = 0) says it will store to variable 'a', but it will not in actual because a compiler can omit it".
However, in fixed version, because the compiler cannot omit the store now, I thought the comment also should be changed to say the difference between broken and fixed version.
If I am understanding anything wrong, please let me know.
Thanks,
SeongJae Park
Quoted 24 lines
Thanx, Paul
Quoted 20 lines
--- Documentation/memory-barriers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/memory-barriers.txt +1
-2@@ -1471,7 +1471,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + /* Code that does store to variable a. */ WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless --1.9.1
Quoted 28 lines · SeongJae Park
Quoted 6 lines · Paul E. McKenney
Quoted 5 lines · SeongJae Park
There is wrong comment in example for compiler store omit behavior. It shows example of the problem and than problem solved version code. However, the comment in the solved version is still same with not solved version. Fix the wrong statement with this commit.
Quoted 6 lines
Quoted 1 line
Signed-off-by SeongJae Park <[email protected]>Hmmm... The code between the two stores of zero to "a" is intended to remain the same in the broken and fixed versions. So the only change is from "a = 0" to "
WRITE_ONCE(a, 0)". Note that it is some other CPU that did the third store to "a".Agree, of course.
Quoted 2 lines
Or am I missing your point here?
My point is about the comment.
I thought the comment in broken version is saying "Below line(a = 0) says it will store to variable 'a', but it will not in actual because a compiler can omit it".
However, in fixed version, because the compiler cannot omit the store now, I thought the comment also should be changed to say the difference between broken and fixed version.
Quoted 1 line
If I am understanding anything wrong, please let me know.
Hmmm... The intent of the comment is to act as a placeholder for arbitrary code that does not affect the value of "a". The current comment is clearly not doing that for you. Possible changes include:
o Adding test to the comment making the intent more clear.
o Replacing the comment with a function call, perhaps to
does_not_change_a() or some similar name.
o Keeping the current comment, but adding a call to something
like does_not_change_a() after it.
Other thoughts?
Thanx, Paul
Quoted 28 lines
Thanks,
SeongJae ParkQuoted 24 lines
Thanx, Paul
Quoted 20 lines
--- Documentation/memory-barriers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/memory-barriers.txt +1
-2@@ -1471,7 +1471,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + /* Code that does store to variable a. */ WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless --1.9.1
Quoted 35 lines · Paul E. McKenney
Quoted 28 lines · SeongJae Park
Quoted 6 lines · Paul E. McKenney
Quoted 5 lines · SeongJae Park
There is wrong comment in example for compiler store omit behavior. It shows example of the problem and than problem solved version code. However, the comment in the solved version is still same with not solved version. Fix the wrong statement with this commit.
Quoted 6 lines
Quoted 1 line
Signed-off-by SeongJae Park <[email protected]>Hmmm... The code between the two stores of zero to "a" is intended to remain the same in the broken and fixed versions. So the only change is from "a = 0" to "
WRITE_ONCE(a, 0)". Note that it is some other CPU that did the third store to "a".Agree, of course.
Quoted 2 lines
Or am I missing your point here?
My point is about the comment.
I thought the comment in broken version is saying "Below line(a = 0) says it will store to variable 'a', but it will not in actual because a compiler can omit it".
However, in fixed version, because the compiler cannot omit the store now, I thought the comment also should be changed to say the difference between broken and fixed version.Quoted 1 line
If I am understanding anything wrong, please let me know.
Hmmm... The intent of the comment is to act as a placeholder for arbitrary code that does not affect the value of "a". The current comment is clearly not doing that for you. Possible changes include:
Quoted 7 lines
o Adding test to the comment making the intent more clear.
o Replacing the comment with a function call, perhaps to
does_not_change_a()or some similar name.
o Keeping the current comment, but adding a call to something
likedoes_not_change_a()after it.Other thoughts?
Ah, now I understood the original intent. Thank you for the kind explanation. I think your third option will be most helpful for me. How about the patch below?
BTW, the problem looks trivial rather than critical. If you think so, feel free to ignore my patch, please.
Thanks,
SeongJae Park
========================== >3 ==========================
Quoted 1 line
From
77e0b1c77d64c358b329b097cffcdacd2c484867Mon Sep 17 00:00:00 2001
From: SeongJae Park <[email protected]>
Date: Sun, 21 Feb 2016 15:18:16 +0900
Subject: [PATCH] Documentation/memory-barriers: polish compiler store omit
example
Comments of examples about compiler store omit in memory-barriers.txt is about code that could be possible at that point. However, someone could interpret the comment as an explanation about below line. This commit exploits the intent more explicitly by adding a function call below the comment.
--- Documentation/memory-barriers.txt | 2 ++ 1 file changed, 2 insertions(+)
(quoted diff) +0 -0
b/Documentation/memory-barriers.txt
index 904ee42..3a17d66 100644
Documentation/memory-barriers.txt +2 -0
@@ -1460,6 +1460,7 @@ of optimizations: a = 0; /* Code that does not store to variable a. */ + does_not_change_a(); a = 0; The compiler sees that the value of variable 'a' is already zero, so
@@ -1472,6 +1473,7 @@ of optimizations: WRITE_ONCE(a, 0); /* Code that does not store to variable a. */ + does_not_change_a(); WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless
Signature · 1 line
1.9.1
Quoted 32 lines
Thanx, Paul
Quoted 28 lines
Thanks,
SeongJae ParkQuoted 24 lines
Thanx, Paul
Quoted 20 lines
--- Documentation/memory-barriers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/memory-barriers.txt +1
-2@@ -1471,7 +1471,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + /* Code that does store to variable a. */ WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless --1.9.1
David Howells
maintainerQuoted 4 lines · SeongJae Park
a = 0;
/* Code that does not store to variable a. */
+does_not_change_a();
a = 0;
Since it's not actually code that's meant to be executed, you could make it:
a = 0; ... code that does not store to variable a ... a = 0;
David
Quoted 7 lines · David Howells
Quoted 4 lines · SeongJae Park
a = 0;
/* Code that does not store to variable a. */
+does_not_change_a();
a = 0;
Quoted 5 lines
Since it's not actually code that's meant to be executed, you could make it:
a = 0; ... code that does not store to variable a ... a = 0;
I selected Paul's third option because the function could be noop (In this case, it doesn't break the original meaning) and it makes the code looks complete.
However, your suggestion looks much better than the comment, too.
So, I am attaching a patch that applying your suggestion below.
=============================== >3 ====================================
Quoted 1 line
From
f7b5677790771599f418f1d95536935be971ae86Mon Sep 17 00:00:00 2001
From: SeongJae Park <[email protected]>
Date: Mon, 22 Feb 2016 19:26:18 +0900
Subject: [PATCH] Documentation/memory-barriers: polish compiler store omit
example
Comments of examples about compiler store omit in memory-barriers.txt is about code that could be possible at that point. However, someone could interpret the comment as an explanation about below line. This commit exploits the intent more explicitly by changing the comment to be seems like a possible code rather than explanation about below line.
--- Documentation/memory-barriers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/memory-barriers.txt +2 -2
@@ -1459,7 +1459,7 @@ of optimizations: the following: a = 0; - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... a = 0; The compiler sees that the value of variable 'a' is already zero, so
@@ -1471,7 +1471,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless
--
1.9.1
Quoted 3 lines
David
Quoted 32 lines · SeongJae Park
From
f7b5677790771599f418f1d95536935be971ae86Mon Sep 17 00:00:00 2001
From: SeongJae Park <[email protected]>
Date: Mon, 22 Feb 2016 19:26:18 +0900
Subject: [PATCH]Documentation/memory-barriers: polish compiler store omit
exampleComments of examples about compiler store omit in memory-barriers.txt is about code that could be possible at that point. However, someone could interpret the comment as an explanation about below line. This commit exploits the intent more explicitly by changing the comment to be seems like a possible code rather than explanation about below line.
Signed-off-by SeongJae Park <[email protected]>--- Documentation/memory-barriers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/memory-barriers.txt +1
-1@@ -1459,7 +1459,7 @@ of optimizations: the following: a = 0; - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... a = 0; The compiler sees that the value of variable 'a' is already zero, so
Documentation/memory-barriers.txt of optimizations: · line 1477
Quoted 8 lines
Documentation/memory-barriers.txt +1
-1@@ -1471,7 +1471,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless
Paul E. McKenney
Acked-by David HowellsQuoted 36 lines · David Howells
Quoted 34 lines · SeongJae Park
From
f7b5677790771599f418f1d95536935be971ae86Mon Sep 17 00:00:00 2001
From: SeongJae Park <[email protected]>
Date: Mon, 22 Feb 2016 19:26:18 +0900
Subject: [PATCH]Documentation/memory-barriers: polish compiler store omit
exampleComments of examples about compiler store omit in memory-barriers.txt is about code that could be possible at that point. However, someone could interpret the comment as an explanation about below line. This commit exploits the intent more explicitly by changing the comment to be seems like a possible code rather than explanation about below line.
Signed-off-by SeongJae Park <[email protected]>--- Documentation/memory-barriers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/memory-barriers.txt +1
-1@@ -1459,7 +1459,7 @@ of optimizations: the following: a = 0; - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... a = 0; The compiler sees that the value of variable 'a' is already zero, so@@ -1471,7 +1471,7 @@ of optimizations: wrong guess:
Quoted 8 lines
Documentation/memory-barriers.txt of optimizations: · line 1477
Quoted 6 lines
Documentation/memory-barriers.txt +1
-1WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unlessAcked-by David Howells <[email protected]>
Thank you both! Patch with updated commit log below, please let me know if you have any objections to the changes.
Thanx, Paul
------------------------------------------------------------------------
commit 0a41feb6ab4da3218192e2cde1a54fcc5d8f5658
Author: SeongJae Park <[email protected]> Date: Mon Feb 22 08:28:29 2016 -0800
documentation: Clarify compiler store-fusion example
The compiler store-fusion example in memory-barriers.txt uses a C comment to represent arbitrary code that does not update a given variable. Unfortunately, someone could reasonably interpret the comment as instead referring to the following line of code. This commit therefore replaces the comment with a string that more clearly represents the arbitrary code.
Documentation/memory-barriers.txt +2 -2
@@ -1550,7 +1550,7 @@ of optimizations: the following: a = 0; - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... a = 0; The compiler sees that the value of variable 'a' is already zero, so
@@ -1562,7 +1562,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless
Quoted 42 lines · Paul E. McKenney
Quoted 41 lines · David Howells
Quoted 39 lines · SeongJae Park
From
f7b5677790771599f418f1d95536935be971ae86Mon Sep 17 00:00:00 2001
From: SeongJae Park <[email protected]>
Date: Mon, 22 Feb 2016 19:26:18 +0900
Subject: [PATCH]Documentation/memory-barriers: polish compiler store omit
exampleComments of examples about compiler store omit in memory-barriers.txt is about code that could be possible at that point. However, someone could interpret the comment as an explanation about below line. This commit exploits the intent more explicitly by changing the comment to be seems like a possible code rather than explanation about below line.
Signed-off-by SeongJae Park <[email protected]>--- Documentation/memory-barriers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)Documentation/memory-barriers.txt +2
-2@@ -1459,7 +1459,7 @@ of optimizations: the following: a = 0; - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... a = 0; The compiler sees that the value of variable 'a' is already zero, so@@ -1471,7 +1471,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... WRITE_ONCE(a, 0);
Quoted 6 lines
Quoted 3 lines
Documentation/memory-barriers.txt of optimizations: · line 1568
Quoted 1 line
Documentation/memory-barriers.txt +0
-0(*) The compiler is within its rights to reorder memory accesses unlessAcked-by David Howells <[email protected]>Thank you both! Patch with updated commit log below, please let me know if you have any objections to the changes.
Looks good to me :)
Thanks,
SeongJae Park
Quoted 45 lines
Thanx, Paul
------------------------------------------------------------------------
commit
0a41feb6ab4da3218192e2cde1a54fcc5d8f5658Author: SeongJae Park <[email protected]> Date: Mon Feb 22 08:28:29 2016 -0800documentation: Clarify compiler store-fusion example
The compiler store-fusion example in memory-barriers.txt uses a C comment to represent arbitrary code that does not update a given variable. Unfortunately, someone could reasonably interpret the comment as instead referring to the following line of code. This commit therefore replaces the comment with a string that more clearly represents the arbitrary code.
Signed-off-by SeongJae Park <[email protected]>Acked-by David Howells <[email protected]>Signed-off-by Paul E. McKenney <[email protected]>Documentation/memory-barriers.txt +2
-2@@ -1550,7 +1550,7 @@ of optimizations: the following: a = 0; - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... a = 0; The compiler sees that the value of variable 'a' is already zero, so@@ -1562,7 +1562,7 @@ of optimizations: wrong guess: WRITE_ONCE(a, 0); - /* Code that does not store to variable a. */ + ... Code that does not store to variable a ... WRITE_ONCE(a, 0); (*) The compiler is within its rights to reorder memory accesses unless