* [PATCH v2 02/24] tools: docs: memory-model: fix references for some files [not found] <cover.1602590106.git.mchehab+huawei@kernel.org> @ 2020-10-13 12:14 ` Mauro Carvalho Chehab 2020-10-13 16:33 ` Paul E. McKenney 0 siblings, 1 reply; 10+ messages in thread From: Mauro Carvalho Chehab @ 2020-10-13 12:14 UTC (permalink / raw) To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab, Jonathan Corbet, Paul E. McKenney, Akira Yokosawa, Alan Stern, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel - The sysfs.txt file was converted to ReST and renamed; - The control-dependencies.txt is not at Documentation/control-dependencies.txt. As it is at the same dir as the README file, which mentions it, just remove Documentation/. With that, ./scripts/documentation-file-ref-check script is now happy again for files under tools/. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- tools/memory-model/Documentation/README | 2 +- tools/memory-model/Documentation/ordering.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README index 16177aaa9752..004969992bac 100644 --- a/tools/memory-model/Documentation/README +++ b/tools/memory-model/Documentation/README @@ -55,7 +55,7 @@ README Documentation/cheatsheet.txt Quick-reference guide to the Linux-kernel memory model. -Documentation/control-dependencies.txt +control-dependencies.txt A guide to preventing compiler optimizations from destroying your control dependencies. diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt index 3d020bed8585..629b19ae64a6 100644 --- a/tools/memory-model/Documentation/ordering.txt +++ b/tools/memory-model/Documentation/ordering.txt @@ -346,7 +346,7 @@ o Accessing RCU-protected pointers via rcu_dereference() If there is any significant processing of the pointer value between the rcu_dereference() that returned it and a later - dereference(), please read Documentation/RCU/rcu_dereference.txt. + dereference(), please read Documentation/RCU/rcu_dereference.rst. It can also be quite helpful to review uses in the Linux kernel. -- 2.26.2 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-13 12:14 ` [PATCH v2 02/24] tools: docs: memory-model: fix references for some files Mauro Carvalho Chehab @ 2020-10-13 16:33 ` Paul E. McKenney 2020-10-13 16:38 ` Alan Stern 0 siblings, 1 reply; 10+ messages in thread From: Paul E. McKenney @ 2020-10-13 16:33 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa, Alan Stern, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote: > - The sysfs.txt file was converted to ReST and renamed; > - The control-dependencies.txt is not at > Documentation/control-dependencies.txt. As it is at the > same dir as the README file, which mentions it, just > remove Documentation/. > > With that, ./scripts/documentation-file-ref-check script > is now happy again for files under tools/. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Queued for review and testing, likely target v5.11. Thanx, Paul > --- > tools/memory-model/Documentation/README | 2 +- > tools/memory-model/Documentation/ordering.txt | 2 +- > 2 files changed, 2 insertions(+), 2 deletions(-) > > diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README > index 16177aaa9752..004969992bac 100644 > --- a/tools/memory-model/Documentation/README > +++ b/tools/memory-model/Documentation/README > @@ -55,7 +55,7 @@ README > Documentation/cheatsheet.txt > Quick-reference guide to the Linux-kernel memory model. > > -Documentation/control-dependencies.txt > +control-dependencies.txt > A guide to preventing compiler optimizations from destroying > your control dependencies. > > diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt > index 3d020bed8585..629b19ae64a6 100644 > --- a/tools/memory-model/Documentation/ordering.txt > +++ b/tools/memory-model/Documentation/ordering.txt > @@ -346,7 +346,7 @@ o Accessing RCU-protected pointers via rcu_dereference() > > If there is any significant processing of the pointer value > between the rcu_dereference() that returned it and a later > - dereference(), please read Documentation/RCU/rcu_dereference.txt. > + dereference(), please read Documentation/RCU/rcu_dereference.rst. > > It can also be quite helpful to review uses in the Linux kernel. > > -- > 2.26.2 > ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-13 16:33 ` Paul E. McKenney @ 2020-10-13 16:38 ` Alan Stern 2020-10-14 1:58 ` Paul E. McKenney 0 siblings, 1 reply; 10+ messages in thread From: Alan Stern @ 2020-10-13 16:38 UTC (permalink / raw) To: Paul E. McKenney Cc: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote: > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote: > > - The sysfs.txt file was converted to ReST and renamed; > > - The control-dependencies.txt is not at > > Documentation/control-dependencies.txt. As it is at the > > same dir as the README file, which mentions it, just > > remove Documentation/. > > > > With that, ./scripts/documentation-file-ref-check script > > is now happy again for files under tools/. > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > Queued for review and testing, likely target v5.11. Instead of changing the path in the README reference, shouldn't tools/memory-model/control-dependencies.txt be moved to its proper position in .../Documentation? Alan Stern ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-13 16:38 ` Alan Stern @ 2020-10-14 1:58 ` Paul E. McKenney 2020-10-14 7:56 ` Mauro Carvalho Chehab 2020-10-14 18:57 ` Paul E. McKenney 0 siblings, 2 replies; 10+ messages in thread From: Paul E. McKenney @ 2020-10-14 1:58 UTC (permalink / raw) To: Alan Stern Cc: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote: > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote: > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote: > > > - The sysfs.txt file was converted to ReST and renamed; > > > - The control-dependencies.txt is not at > > > Documentation/control-dependencies.txt. As it is at the > > > same dir as the README file, which mentions it, just > > > remove Documentation/. > > > > > > With that, ./scripts/documentation-file-ref-check script > > > is now happy again for files under tools/. > > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > > > Queued for review and testing, likely target v5.11. > > Instead of changing the path in the README reference, shouldn't > tools/memory-model/control-dependencies.txt be moved to its proper > position in .../Documentation? You are of course quite right. My thought is to let Mauro go ahead, given his short deadline. We can then make this "git mv" change once v5.10-rc1 comes out, given that it should have Mauro's patches. I have added a reminder to my calendar. Thanx, Paul ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-14 1:58 ` Paul E. McKenney @ 2020-10-14 7:56 ` Mauro Carvalho Chehab 2020-10-14 14:14 ` Akira Yokosawa 2020-10-14 18:57 ` Paul E. McKenney 1 sibling, 1 reply; 10+ messages in thread From: Mauro Carvalho Chehab @ 2020-10-14 7:56 UTC (permalink / raw) To: Paul E. McKenney Cc: Alan Stern, Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel Em Tue, 13 Oct 2020 18:58:40 -0700 "Paul E. McKenney" <paulmck@kernel.org> escreveu: > On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote: > > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote: > > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote: > > > > - The sysfs.txt file was converted to ReST and renamed; > > > > - The control-dependencies.txt is not at > > > > Documentation/control-dependencies.txt. As it is at the > > > > same dir as the README file, which mentions it, just > > > > remove Documentation/. > > > > > > > > With that, ./scripts/documentation-file-ref-check script > > > > is now happy again for files under tools/. > > > > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > > > > > Queued for review and testing, likely target v5.11. > > > > Instead of changing the path in the README reference, shouldn't > > tools/memory-model/control-dependencies.txt be moved to its proper > > position in .../Documentation? > > You are of course quite right. My thought is to let Mauro go ahead, > given his short deadline. We can then make this "git mv" change once > v5.10-rc1 comes out, given that it should have Mauro's patches. I have > added a reminder to my calendar. Sounds like a plan to me. If it helps on 5.11 plans, converting this file to ReST format is quite trivial: it just needs to use "::" for C/asm code literal blocks, and to replace "(*) " by something that matches ReST syntax for lists, like "(#) " or just "* ": https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists See enclosed. Thanks, Mauro [PATCH] convert control-dependencies.rst to ReST - Mark literal blocks as such; - Use a numbered list at the summary. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> diff --git a/tools/memory-model/Documentation/control-dependencies.rst b/tools/memory-model/Documentation/control-dependencies.rst index 366520cac937..52dc6a5bc173 100644 --- a/tools/memory-model/Documentation/control-dependencies.rst +++ b/tools/memory-model/Documentation/control-dependencies.rst @@ -7,7 +7,7 @@ the compiler's ignorance from breaking your code. A load-load control dependency requires a full read memory barrier, not simply a data dependency barrier to make it work correctly. Consider the -following bit of code: +following bit of code:: q = READ_ONCE(a); if (q) { @@ -19,7 +19,7 @@ This will not have the desired effect because there is no actual data dependency, but rather a control dependency that the CPU may short-circuit by attempting to predict the outcome in advance, so that other CPUs see the load from b as having happened before the load from a. In such a -case what's actually required is: +case what's actually required is:: q = READ_ONCE(a); if (q) { @@ -28,7 +28,7 @@ case what's actually required is: } However, stores are not speculated. This means that ordering -is- provided -for load-store control dependencies, as in the following example: +for load-store control dependencies, as in the following example:: q = READ_ONCE(a); if (q) { @@ -45,7 +45,7 @@ or, worse yet, convert the store into a check followed by a store. Worse yet, if the compiler is able to prove (say) that the value of variable "a" is always non-zero, it would be well within its rights to optimize the original example by eliminating the "if" statement -as follows: +as follows:: q = a; b = 1; /* BUG: Compiler and CPU can both reorder!!! */ @@ -53,7 +53,7 @@ as follows: So don't leave out either the READ_ONCE() or the WRITE_ONCE(). It is tempting to try to enforce ordering on identical stores on both -branches of the "if" statement as follows: +branches of the "if" statement as follows:: q = READ_ONCE(a); if (q) { @@ -67,7 +67,7 @@ branches of the "if" statement as follows: } Unfortunately, current compilers will transform this as follows at high -optimization levels: +optimization levels:: q = READ_ONCE(a); barrier(); @@ -85,7 +85,7 @@ Now there is no conditional between the load from "a" and the store to The conditional is absolutely required, and must be present in the assembly code even after all compiler optimizations have been applied. Therefore, if you need ordering in this example, you need explicit -memory barriers, for example, smp_store_release(): +memory barriers, for example, smp_store_release():: q = READ_ONCE(a); if (q) { @@ -97,7 +97,7 @@ memory barriers, for example, smp_store_release(): } In contrast, without explicit memory barriers, two-legged-if control -ordering is guaranteed only when the stores differ, for example: +ordering is guaranteed only when the stores differ, for example:: q = READ_ONCE(a); if (q) { @@ -113,7 +113,7 @@ proving the value of "a". In addition, you need to be careful what you do with the local variable "q", otherwise the compiler might be able to guess the value and again remove -the needed conditional. For example: +the needed conditional. For example:: q = READ_ONCE(a); if (q % MAX) { @@ -126,7 +126,7 @@ the needed conditional. For example: If MAX is defined to be 1, then the compiler knows that (q % MAX) is equal to zero, in which case the compiler is within its rights to -transform the above code into the following: +transform the above code into the following:: q = READ_ONCE(a); WRITE_ONCE(b, 2); @@ -137,7 +137,7 @@ between the load from variable "a" and the store to variable "b". It is tempting to add a barrier(), but this does not help. The conditional is gone, and the barrier won't bring it back. Therefore, if you are relying on this ordering, you should make sure that MAX is greater than -one, perhaps as follows: +one, perhaps as follows:: q = READ_ONCE(a); BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */ @@ -154,7 +154,7 @@ identical, as noted earlier, the compiler could pull this store outside of the 'if' statement. You must also be careful not to rely too much on boolean short-circuit -evaluation. Consider this example: +evaluation. Consider this example:: q = READ_ONCE(a); if (q || 1 > 0) @@ -162,7 +162,7 @@ evaluation. Consider this example: Because the first condition cannot fault and the second condition is always true, the compiler can transform this example as following, -defeating control dependency: +defeating control dependency:: q = READ_ONCE(a); WRITE_ONCE(b, 1); @@ -174,7 +174,7 @@ the compiler to use the results. In addition, control dependencies apply only to the then-clause and else-clause of the if-statement in question. In particular, it does -not necessarily apply to code following the if-statement: +not necessarily apply to code following the if-statement:: q = READ_ONCE(a); if (q) { @@ -189,7 +189,7 @@ compiler cannot reorder volatile accesses and also cannot reorder the writes to "b" with the condition. Unfortunately for this line of reasoning, the compiler might compile the two writes to "b" as conditional-move instructions, as in this fanciful pseudo-assembly -language: +language:: ld r1,a cmp r1,$0 @@ -213,14 +213,14 @@ for more information. In summary: - (*) Control dependencies can order prior loads against later stores. + (#) Control dependencies can order prior loads against later stores. However, they do -not- guarantee any other sort of ordering: Not prior loads against later loads, nor prior stores against later anything. If you need these other forms of ordering, use smp_rmb(), smp_wmb(), or, in the case of prior stores and later loads, smp_mb(). - (*) If both legs of the "if" statement begin with identical stores to + (#) If both legs of the "if" statement begin with identical stores to the same variable, then those stores must be ordered, either by preceding both of them with smp_mb() or by using smp_store_release() to carry out the stores. Please note that it is -not- sufficient @@ -229,28 +229,28 @@ In summary: destroy the control dependency while respecting the letter of the barrier() law. - (*) Control dependencies require at least one run-time conditional + (#) Control dependencies require at least one run-time conditional between the prior load and the subsequent store, and this conditional must involve the prior load. If the compiler is able to optimize the conditional away, it will have also optimized away the ordering. Careful use of READ_ONCE() and WRITE_ONCE() can help to preserve the needed conditional. - (*) Control dependencies require that the compiler avoid reordering the + (#) Control dependencies require that the compiler avoid reordering the dependency into nonexistence. Careful use of READ_ONCE() or atomic{,64}_read() can help to preserve your control dependency. Please see the COMPILER BARRIER section for more information. - (*) Control dependencies apply only to the then-clause and else-clause + (#) Control dependencies apply only to the then-clause and else-clause of the if-statement containing the control dependency, including any functions that these two clauses call. Control dependencies do -not- apply to code following the if-statement containing the control dependency. - (*) Control dependencies pair normally with other types of barriers. + (#) Control dependencies pair normally with other types of barriers. - (*) Control dependencies do -not- provide multicopy atomicity. If you + (#) Control dependencies do -not- provide multicopy atomicity. If you need all the CPUs to see a given store at the same time, use smp_mb(). - (*) Compilers do not understand control dependencies. It is therefore + (#) Compilers do not understand control dependencies. It is therefore your job to ensure that they do not break your code. ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-14 7:56 ` Mauro Carvalho Chehab @ 2020-10-14 14:14 ` Akira Yokosawa 2020-10-14 14:39 ` Mauro Carvalho Chehab 0 siblings, 1 reply; 10+ messages in thread From: Akira Yokosawa @ 2020-10-14 14:14 UTC (permalink / raw) To: Mauro Carvalho Chehab, Paul E. McKenney Cc: Alan Stern, Linux Doc Mailing List, Jonathan Corbet, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel, Akira Yokosawa On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote: > Em Tue, 13 Oct 2020 18:58:40 -0700 > "Paul E. McKenney" <paulmck@kernel.org> escreveu: > >> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote: >>> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote: >>>> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote: >>>>> - The sysfs.txt file was converted to ReST and renamed; >>>>> - The control-dependencies.txt is not at >>>>> Documentation/control-dependencies.txt. As it is at the >>>>> same dir as the README file, which mentions it, just >>>>> remove Documentation/. >>>>> >>>>> With that, ./scripts/documentation-file-ref-check script >>>>> is now happy again for files under tools/. >>>>> >>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> >>>> >>>> Queued for review and testing, likely target v5.11. >>> >>> Instead of changing the path in the README reference, shouldn't >>> tools/memory-model/control-dependencies.txt be moved to its proper >>> position in .../Documentation? >> >> You are of course quite right. My thought is to let Mauro go ahead, >> given his short deadline. We can then make this "git mv" change once >> v5.10-rc1 comes out, given that it should have Mauro's patches. I have >> added a reminder to my calendar. > > Sounds like a plan to me. > > > If it helps on 5.11 plans, converting this file to ReST format is quite > trivial: it just needs to use "::" for C/asm code literal blocks, and > to replace "(*) " by something that matches ReST syntax for lists, > like "(#) " or just "* ": > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists > > See enclosed. I'm afraid conversion of LKMM documents to ReST is unlikely to happen any time soon. It should wait until such time comes when the auto markup tools become clever enough and .rst files looks exactly the same as plain .txt files. Am I asking too much? :-) Thanks, Akira > > Thanks, > Mauro > > [PATCH] convert control-dependencies.rst to ReST > [snip] ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-14 14:14 ` Akira Yokosawa @ 2020-10-14 14:39 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 10+ messages in thread From: Mauro Carvalho Chehab @ 2020-10-14 14:39 UTC (permalink / raw) To: Akira Yokosawa Cc: Paul E. McKenney, Alan Stern, Linux Doc Mailing List, Jonathan Corbet, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel Em Wed, 14 Oct 2020 23:14:00 +0900 Akira Yokosawa <akiyks@gmail.com> escreveu: > On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote: > > Em Tue, 13 Oct 2020 18:58:40 -0700 > > "Paul E. McKenney" <paulmck@kernel.org> escreveu: > > > >> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote: > >>> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote: > >>>> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote: > >>>>> - The sysfs.txt file was converted to ReST and renamed; > >>>>> - The control-dependencies.txt is not at > >>>>> Documentation/control-dependencies.txt. As it is at the > >>>>> same dir as the README file, which mentions it, just > >>>>> remove Documentation/. > >>>>> > >>>>> With that, ./scripts/documentation-file-ref-check script > >>>>> is now happy again for files under tools/. > >>>>> > >>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > >>>> > >>>> Queued for review and testing, likely target v5.11. > >>> > >>> Instead of changing the path in the README reference, shouldn't > >>> tools/memory-model/control-dependencies.txt be moved to its proper > >>> position in .../Documentation? > >> > >> You are of course quite right. My thought is to let Mauro go ahead, > >> given his short deadline. We can then make this "git mv" change once > >> v5.10-rc1 comes out, given that it should have Mauro's patches. I have > >> added a reminder to my calendar. > > > > Sounds like a plan to me. > > > > > > If it helps on 5.11 plans, converting this file to ReST format is quite > > trivial: it just needs to use "::" for C/asm code literal blocks, and > > to replace "(*) " by something that matches ReST syntax for lists, > > like "(#) " or just "* ": > > > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists > > > > See enclosed. > > I'm afraid conversion of LKMM documents to ReST is unlikely to happen > any time soon. > It should wait until such time comes when the auto markup tools become > clever enough and .rst files looks exactly the same as plain .txt files. > > Am I asking too much? :-) > > Thanks, Akira Yes :-) $ git log --author akiyks@gmail.com Documentation/sphinx $ The auto markup tools don't write themselves alone. Someone needs to write them and test if no regressions will happen with the existing documents. - That's said, I suspect that one of the hardest things for something like that to be possible is to be able to distinguish something like: (some text) From something like: /* some C code snippet or bash script, or other literal block */ So, at least "::" (or some other markup replacing it) is needed. If you have some bright idea about how to implement it, feel free to contribute with patches. Thanks, Mauro ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-14 1:58 ` Paul E. McKenney 2020-10-14 7:56 ` Mauro Carvalho Chehab @ 2020-10-14 18:57 ` Paul E. McKenney 2020-10-15 5:15 ` Mauro Carvalho Chehab 1 sibling, 1 reply; 10+ messages in thread From: Paul E. McKenney @ 2020-10-14 18:57 UTC (permalink / raw) To: Alan Stern Cc: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel On Tue, Oct 13, 2020 at 06:58:40PM -0700, Paul E. McKenney wrote: > On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote: > > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote: > > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote: > > > > - The sysfs.txt file was converted to ReST and renamed; > > > > - The control-dependencies.txt is not at > > > > Documentation/control-dependencies.txt. As it is at the > > > > same dir as the README file, which mentions it, just > > > > remove Documentation/. > > > > > > > > With that, ./scripts/documentation-file-ref-check script > > > > is now happy again for files under tools/. > > > > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > > > > > Queued for review and testing, likely target v5.11. > > > > Instead of changing the path in the README reference, shouldn't > > tools/memory-model/control-dependencies.txt be moved to its proper > > position in .../Documentation? > > You are of course quite right. My thought is to let Mauro go ahead, > given his short deadline. We can then make this "git mv" change once > v5.10-rc1 comes out, given that it should have Mauro's patches. I have > added a reminder to my calendar. Except that I cannot find a commit where control-dependencies.txt is in tools/memory-model. And this file is not yet in mainline, but only in -rcu and -next. In both places, it is here: tools/memory-model/Documentation/control-dependencies.txt Mauro, to what commit in what tree are you applying this patch? Thanx, Paul ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-14 18:57 ` Paul E. McKenney @ 2020-10-15 5:15 ` Mauro Carvalho Chehab 2020-10-15 10:30 ` Peter Zijlstra 0 siblings, 1 reply; 10+ messages in thread From: Mauro Carvalho Chehab @ 2020-10-15 5:15 UTC (permalink / raw) To: Paul E. McKenney Cc: Alan Stern, Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Peter Zijlstra, Will Deacon, linux-arch, linux-kernel Hi Paul, Em Wed, 14 Oct 2020 11:57:20 -0700 "Paul E. McKenney" <paulmck@kernel.org> escreveu: > On Tue, Oct 13, 2020 at 06:58:40PM -0700, Paul E. McKenney wrote: > > On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote: > > > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote: > > > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote: > > > > > - The sysfs.txt file was converted to ReST and renamed; > > > > > - The control-dependencies.txt is not at > > > > > Documentation/control-dependencies.txt. As it is at the > > > > > same dir as the README file, which mentions it, just > > > > > remove Documentation/. > > > > > > > > > > With that, ./scripts/documentation-file-ref-check script > > > > > is now happy again for files under tools/. > > > > > > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > > > > > > > Queued for review and testing, likely target v5.11. > > > > > > Instead of changing the path in the README reference, shouldn't > > > tools/memory-model/control-dependencies.txt be moved to its proper > > > position in .../Documentation? > > > > You are of course quite right. My thought is to let Mauro go ahead, > > given his short deadline. I guess there might be some misunderstanding here. My fault. The plan is to have zero doc warnings for 5.10[1]. In order to get there, The patches for it were split on two series, both for 5.10: - The /80 series with patches that already applies on the top of master; - This /24 patch series, which depends on trees that weren't merged upstream yet (back on Oct, 13). Those applies on the top of next-20201013. I'm intending to submit later today (after next-20201015) a PR with patches from the /80 series. The remaining ones should be sent as a late pull request by the end of the merge window, if the patch that caused the issue gets merged for 5.10. That's the case of this patch. [1] With Sphinx < 3. Sphinx 3 and above brings some additional warnings that depends on a fix at the toolset. The fixup patches for Sphinx were proposed yesterday by the Sphinx maintainer of the C domain parser. More details can be seen here: https://github.com/sphinx-doc/sphinx/pull/8313 > > We can then make this "git mv" change once > > v5.10-rc1 comes out, given that it should have Mauro's patches. I have > > added a reminder to my calendar. > > Except that I cannot find a commit where control-dependencies.txt is > in tools/memory-model. And this file is not yet in mainline, but > only in -rcu and -next. In both places, it is here: > > tools/memory-model/Documentation/control-dependencies.txt > > Mauro, to what commit in what tree are you applying this patch? This is against next-20201013. The specific commit adding README and control-dependencies.txt is this one: commit d34a972f67252457158122e5ba7a0ce5ece62067 Author: Paul E. McKenney <paulmck@kernel.org> AuthorDate: Tue Aug 11 11:27:33 2020 -0700 Commit: Paul E. McKenney <paulmck@kernel.org> CommitDate: Sun Oct 4 17:21:31 2020 -0700 tools/memory-model: Document categories of ordering primitives The Linux kernel has a number of categories of ordering primitives, which are recorded in the LKMM implementation and hinted at by cheatsheet.txt. But there is no overview of these categories, and such an overview is needed in order to understand multithreaded LKMM litmus tests. This commit therefore adds an ordering.txt as well as extracting a control-dependencies.txt from memory-barriers.txt. It also updates the README file. [ paulmck: Apply Akira Yokosawa file-placement feedback. ] [ paulmck: Apply Alan Stern feedback. ] Signed-off-by: Paul E. McKenney <paulmck@kernel.org> Btw, after re-checking the patch, I would drop this hunk: diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README index 16177aaa9752..004969992bac 100644 --- a/tools/memory-model/Documentation/README +++ b/tools/memory-model/Documentation/README @@ -55,7 +55,7 @@ README Documentation/cheatsheet.txt Quick-reference guide to the Linux-kernel memory model. -Documentation/control-dependencies.txt +control-dependencies.txt A guide to preventing compiler optimizations from destroying your control dependencies. The ./scripts/documentation-file-ref-check doesn't complain about broken references for Documentation/ files outside the main docs dir. So, this hunk is not really needed to fix warnings with 5.10. Besides that, there are other references to those files: $ git grep Documentation tools/memory-model/Documentation/README tools/memory-model/Documentation/README:tools/memory-model/Documentation directory. It has been said that at tools/memory-model/Documentation/README:Documentation/cheatsheet.txt tools/memory-model/Documentation/README:Documentation/control-dependencies.txt tools/memory-model/Documentation/README:Documentation/explanation.txt tools/memory-model/Documentation/README:Documentation/litmus-tests.txt tools/memory-model/Documentation/README:Documentation/ordering.txt tools/memory-model/Documentation/README:Documentation/recipes.txt tools/memory-model/Documentation/README:Documentation/references.txt tools/memory-model/Documentation/README:Documentation/simple.txt That also refer to the files inside tools/memory-model/Documentation/. So, they should ether all be replaced to just the file name without the directory (IMHO, that makes more sense) or kept as-is. In any case, for 5.10, all we need is to fix this reference: Documentation/RCU/rcu_dereference.txt -> Documentation/RCU/rcu_dereference.rst Also, the patch description is wrong. I suspect that, when this patch was originally written, there were more hunks being touched, but fixes for everything else were already merged. So, the only thing that is left is the above change. It follows a new version. feel free to either pick (or merge) this one at the same tree as tools/memory-model/Documentation/ordering.txt if you think that this works best for you. Otherwise, I'll keep this on my -next tree together with this series, aiming to submit by the end of the merge window, if ordering.txt gets merged for 5.10. Thanks, Mauro [PATCH v2.1 02/24] tools/memory-model: fix a broken doc reference Documentation/RCU/rcu_dereference.txt -> Documentation/RCU/rcu_dereference.rst Fixes: d34a972f6725 ("tools/memory-model: Document categories of ordering primitives") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt index 3d020bed8585..629b19ae64a6 100644 --- a/tools/memory-model/Documentation/ordering.txt +++ b/tools/memory-model/Documentation/ordering.txt @@ -346,7 +346,7 @@ o Accessing RCU-protected pointers via rcu_dereference() If there is any significant processing of the pointer value between the rcu_dereference() that returned it and a later - dereference(), please read Documentation/RCU/rcu_dereference.txt. + dereference(), please read Documentation/RCU/rcu_dereference.rst. It can also be quite helpful to review uses in the Linux kernel. ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files 2020-10-15 5:15 ` Mauro Carvalho Chehab @ 2020-10-15 10:30 ` Peter Zijlstra 0 siblings, 0 replies; 10+ messages in thread From: Peter Zijlstra @ 2020-10-15 10:30 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Paul E. McKenney, Alan Stern, Linux Doc Mailing List, Jonathan Corbet, Akira Yokosawa, Andrea Parri, Boqun Feng, Daniel Lustig, David Howells, Jade Alglave, Joel Fernandes, Luc Maranget, Nicholas Piggin, Will Deacon, linux-arch, linux-kernel On Thu, Oct 15, 2020 at 07:15:18AM +0200, Mauro Carvalho Chehab wrote: > I guess there might be some misunderstanding here. My fault. The plan > is to have zero doc warnings for 5.10[1]. I'd be glad to help and convert all the documentation under my maintainership to .txt files for you. ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2020-10-15 10:31 UTC | newest] Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- [not found] <cover.1602590106.git.mchehab+huawei@kernel.org> 2020-10-13 12:14 ` [PATCH v2 02/24] tools: docs: memory-model: fix references for some files Mauro Carvalho Chehab 2020-10-13 16:33 ` Paul E. McKenney 2020-10-13 16:38 ` Alan Stern 2020-10-14 1:58 ` Paul E. McKenney 2020-10-14 7:56 ` Mauro Carvalho Chehab 2020-10-14 14:14 ` Akira Yokosawa 2020-10-14 14:39 ` Mauro Carvalho Chehab 2020-10-14 18:57 ` Paul E. McKenney 2020-10-15 5:15 ` Mauro Carvalho Chehab 2020-10-15 10:30 ` Peter Zijlstra
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).