Re: [PATCH 10/18] rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff()

[Paul E. McKenney]

On Wed, May 09, 2018 at 08:55:33AM -0300, Mauro Carvalho Chehab wrote:
> Em Mon, 7 May 2018 07:23:22 -0700
> "Paul E. McKenney" <paul...@linux.vnet.ibm.com> escreveu:
> 
> > On Mon, May 07, 2018 at 06:35:46AM -0300, Mauro Carvalho Chehab wrote:
> > > The code example at rcupdate.h currently produce lots of warnings:
> > > 
> > >   ./include/linux/rcupdate.h:572: WARNING: Unexpected indentation.
> > >   ./include/linux/rcupdate.h:576: WARNING: Unexpected indentation.
> > >   ./include/linux/rcupdate.h:580: WARNING: Block quote ends without a 
> > > blank line; unexpected unindent.
> > >   ./include/linux/rcupdate.h:582: WARNING: Block quote ends without a 
> > > blank line; unexpected unindent.
> > >   ./include/linux/rcupdate.h:582: WARNING: Inline literal start-string 
> > > without end-string.
> > > 
> > > Change it to a code-block.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>  
> > 
> > Acked-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> > 
> > If you don't tell me otherwise, I will assume that you are pushing this.
> > If you would rather that I take it, please let me know!
> 
> Hi Paul,
> 
> Feel free to merge it via your tree. It seems that Jon prefers to have
> code changes merged via the usual maintainers.

I have queued it for v4.19, thank you!

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 10/18] rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff()

[Paul E. McKenney]

On Mon, May 07, 2018 at 06:35:46AM -0300, Mauro Carvalho Chehab wrote:
> The code example at rcupdate.h currently produce lots of warnings:
> 
>   ./include/linux/rcupdate.h:572: WARNING: Unexpected indentation.
>   ./include/linux/rcupdate.h:576: WARNING: Unexpected indentation.
>   ./include/linux/rcupdate.h:580: WARNING: Block quote ends without a 
> blank line; unexpected unindent.
>   ./include/linux/rcupdate.h:582: WARNING: Block quote ends without a 
> blank line; unexpected unindent.
>   ./include/linux/rcupdate.h:582: WARNING: Inline literal start-string 
> without end-string.
> 
> Change it to a code-block.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+sams...@kernel.org>

Acked-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

If you don't tell me otherwise, I will assume that you are pushing this.
If you would rather that I take it, please let me know!

Thanx, Paul

> ---
>  include/linux/rcupdate.h | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
> 
> diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
> index 36360d07f25b..c890d10978fa 100644
> --- a/include/linux/rcupdate.h
> +++ b/include/linux/rcupdate.h
> @@ -568,8 +568,8 @@ static inline void rcu_preempt_sleep_check(void) { }
>   * This is simply an identity function, but it documents where a pointer
>   * is handed off from RCU to some other synchronization mechanism, for
>   * example, reference counting or locking.  In C11, it would map to
> - * kill_dependency().  It could be used as follows:
> - * ``
> + * kill_dependency().  It could be used as follows::
> + *
>   *   rcu_read_lock();
>   *   p = rcu_dereference(gp);
>   *   long_lived = is_long_lived(p);
> @@ -580,7 +580,6 @@ static inline void rcu_preempt_sleep_check(void) { }
>   *   p = rcu_pointer_handoff(p);
>   *   }
>   *   rcu_read_unlock();
> - *``
>   */
>  #define rcu_pointer_handoff(p) (p)
> 
> -- 
> 2.17.0
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] atomic_ops.rst: Fix wrong example code

[Paul E. McKenney]

On Thu, Apr 19, 2018 at 05:42:44PM +0900, SeongJae Park wrote:
> Example code snippets for necessary of READ_ONCE() and WRITE_ONCE() has
> an unnecessary line of code and wrong condition.  This commit fixes
> them.
> 
> Signed-off-by: SeongJae Park 

Good catch!!!  I queued and pushed both patches for further review,
thank you!

Thanx, Paul

> ---
>  Documentation/core-api/atomic_ops.rst | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/Documentation/core-api/atomic_ops.rst 
> b/Documentation/core-api/atomic_ops.rst
> index fce929144ccd..4ea4af71e68a 100644
> --- a/Documentation/core-api/atomic_ops.rst
> +++ b/Documentation/core-api/atomic_ops.rst
> @@ -111,7 +111,6 @@ If the compiler can prove that do_something() does not 
> store to the
>  variable a, then the compiler is within its rights transforming this to
>  the following::
> 
> - tmp = a;
>   if (a > 0)
>   for (;;)
>   do_something();
> @@ -119,7 +118,7 @@ the following::
>  If you don't want the compiler to do this (and you probably don't), then
>  you should use something like the following::
> 
> - while (READ_ONCE(a) < 0)
> + while (READ_ONCE(a) > 0)
>   do_something();
> 
>  Alternatively, you could place a barrier() call in the loop.
> -- 
> 2.13.0
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs/memory-barriers.txt: Fix broken DMA vs MMIO ordering example

[Paul E. McKenney]

On Tue, Mar 27, 2018 at 02:11:27PM +0100, Will Deacon wrote:
> The section of memory-barriers.txt that describes the dma_Xmb() barriers
> has an incorrect example claiming that a wmb() is required after writing
> to coherent memory in order for those writes to be visible to a device
> before a subsequent MMIO access using writel() can reach the device.
> 
> In fact, this ordering guarantee is provided (at significant cost on some
> architectures such as arm and power) by writel, so the wmb() is not
> necessary. writel_relaxed exists for cases where this ordering is not
> required.
> 
> Fix the example and update the text to make this clearer.
> 
> Cc: Benjamin Herrenschmidt <b...@kernel.crashing.org>
> Cc: Arnd Bergmann <a...@arndb.de>
> Cc: Jason Gunthorpe <j...@ziepe.ca>
> Cc: "Paul E. McKenney" <paul...@linux.vnet.ibm.com>
> Cc: Peter Zijlstra <pet...@infradead.org>
> Cc: Ingo Molnar <mi...@redhat.com>
> Cc: Jonathan Corbet <cor...@lwn.net>
> Reported-by: Sinan Kaya <ok...@codeaurora.org>
> Signed-off-by: Will Deacon <will.dea...@arm.com>

Good catch, queued on my lkmm branch, thank you!

Thanx, Paul

> ---
>  Documentation/memory-barriers.txt | 17 +
>  1 file changed, 9 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index a863009849a3..3247547d1c36 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -1909,9 +1909,6 @@ There are some more advanced barrier functions:
>   /* assign ownership */
>   desc->status = DEVICE_OWN;
> 
> - /* force memory to sync before notifying device via MMIO */
> - wmb();
> -
>   /* notify device of new descriptors */
>   writel(DESC_NOTIFY, doorbell);
>   }
> @@ -1919,11 +1916,15 @@ There are some more advanced barrier functions:
>   The dma_rmb() allows us guarantee the device has released ownership
>   before we read the data from the descriptor, and the dma_wmb() allows
>   us to guarantee the data is written to the descriptor before the device
> - can see it now has ownership.  The wmb() is needed to guarantee that the
> - cache coherent memory writes have completed before attempting a write to
> - the cache incoherent MMIO region.
> -
> - See Documentation/DMA-API.txt for more information on consistent memory.
> + can see it now has ownership.  Note that, when using writel(), a prior
> + wmb() is not needed to guarantee that the cache coherent memory writes
> + have completed before writing to the MMIO region.  The cheaper
> + writel_relaxed() does not provide this guarantee and must not be used
> + here.
> +
> + See the subsection "Kernel I/O barrier effects" for more information on
> + relaxed I/O accessors and the Documentation/DMA-API.txt file for more
> + information on consistent memory.
> 
> 
>  MMIO WRITE BARRIER
> -- 
> 2.1.4
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Paul E. McKenney]

On Fri, Feb 09, 2018 at 04:00:53PM +0100, Andrea Parri wrote:
> On Fri, Feb 09, 2018 at 06:29:23AM -0800, Paul E. McKenney wrote:
> > On Fri, Feb 09, 2018 at 01:50:51PM +0100, Andrea Parri wrote:
> > > On Fri, Feb 09, 2018 at 04:31:00AM -0800, Paul E. McKenney wrote:
> > > > On Sun, Feb 04, 2018 at 07:37:08PM +0100, Andrea Parri wrote:
> > > > > Hi Akira,
> > > > > 
> > > > > On Mon, Feb 05, 2018 at 01:14:10AM +0900, Akira Yokosawa wrote:
> > > > > > Hi Paul,
> > > > > > CC: Andrea
> > > > > > 
> > > > > > This is intentionally off the list, as I was not cc'd in the thread.
> > > > > > If you think it is worthwhile, could you help me join the thread by
> > > > > > forwarding the following part as a reply to your message, plus CC: 
> > > > > > to me.
> > > > > 
> > > > > [CCing lists and other people]
> > > > > 
> > > > > 
> > > > > > 
> > > > > > On Fri, Feb 02, 2018 at 17:21:03AM -0800, Paul E. McKenney wrote:
> > > > > > > On Fri, Feb 02, 2018 at 10:12:48AM +0100, Andrea Parri wrote:
> > > > > > >> Recent efforts led to the specification of a memory consistency 
> > > > > > >> model
> > > > > > >> for the Linux kernel [1], which "can (roughly speaking) be 
> > > > > > >> thought of
> > > > > > >> as an automated version of memory-barriers.txt" and which is (in 
> > > > > > >> turn)
> > > > > > >> "accompanied by extensive documentation on its use and its 
> > > > > > >> design".
> > > > > > >> 
> > > > > > >> Make sure that the (occasional) reader of memory-barriers.txt 
> > > > > > >> will be
> > > > > > >> aware of these developments.
> > > > > > >> 
> > > > > > >> [1] https://marc.info/?l=linux-kernel=151687290114799=2
> > > > > > >> 
> > > > > > >> Signed-off-by: Andrea Parri <parri.andrea@x>
> > > > > > > 
> > > > > > > I am inclined to pull in something along these lines, but would 
> > > > > > > like
> > > > > > > some feedback on the wording, especially how "official" we want to
> > > > > > > make the memory model to be.
> > > > > > > 
> > > > > > > Thoughts?
> > > > > > 
> > > > > > The change log of commit e7720af5f9ac ("locking/Documentation: Add 
> > > > > > disclaimer") says:
> > > > > > 
> > > > > > It appears people are reading this document as a requirements 
> > > > > > list for
> > > > > > building hardware. This is not the intent of this document. Nor 
> > > > > > is it
> > > > > > particularly suited for this purpose.
> > > > > > 
> > > > > > The primary purpose of this document is our collective attempt 
> > > > > > to define
> > > > > > a set of primitives that (hopefully) allow us to write correct 
> > > > > > code on
> > > > > > the myriad of SMP platforms Linux supports.
> > > > > > 
> > > > > > Its a definite work in progress as our understanding of these 
> > > > > > platforms,
> > > > > > and memory ordering in general, progresses.
> > > > > > 
> > > > > > Nor does being mentioned in this document mean we think its a
> > > > > > particularly good idea; the data dependency barrier required by 
> > > > > > Alpha
> > > > > > being a prime example. Yes we have it, no you're insane to 
> > > > > > require it
> > > > > > when building new hardware.
> > > > > > 
> > > > > > My take on the Linux Kernel memory-consistency model is a 
> > > > > > supplement of
> > > > > > memory-barriers.txt and the disclaimer also applies to the memory 
> > > > > > model.
> > > > > > 
> > > > > > > 
> > > > > > > If I don't hear otherwise 

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

[Paul E. McKenney]

On Fri, Feb 09, 2018 at 01:50:51PM +0100, Andrea Parri wrote:
> On Fri, Feb 09, 2018 at 04:31:00AM -0800, Paul E. McKenney wrote:
> > On Sun, Feb 04, 2018 at 07:37:08PM +0100, Andrea Parri wrote:
> > > Hi Akira,
> > > 
> > > On Mon, Feb 05, 2018 at 01:14:10AM +0900, Akira Yokosawa wrote:
> > > > Hi Paul,
> > > > CC: Andrea
> > > > 
> > > > This is intentionally off the list, as I was not cc'd in the thread.
> > > > If you think it is worthwhile, could you help me join the thread by
> > > > forwarding the following part as a reply to your message, plus CC: to 
> > > > me.
> > > 
> > > [CCing lists and other people]
> > > 
> > > 
> > > > 
> > > > On Fri, Feb 02, 2018 at 17:21:03AM -0800, Paul E. McKenney wrote:
> > > > > On Fri, Feb 02, 2018 at 10:12:48AM +0100, Andrea Parri wrote:
> > > > >> Recent efforts led to the specification of a memory consistency model
> > > > >> for the Linux kernel [1], which "can (roughly speaking) be thought of
> > > > >> as an automated version of memory-barriers.txt" and which is (in 
> > > > >> turn)
> > > > >> "accompanied by extensive documentation on its use and its design".
> > > > >> 
> > > > >> Make sure that the (occasional) reader of memory-barriers.txt will be
> > > > >> aware of these developments.
> > > > >> 
> > > > >> [1] https://marc.info/?l=linux-kernel=151687290114799=2
> > > > >> 
> > > > >> Signed-off-by: Andrea Parri <parri.andrea@x>
> > > > > 
> > > > > I am inclined to pull in something along these lines, but would like
> > > > > some feedback on the wording, especially how "official" we want to
> > > > > make the memory model to be.
> > > > > 
> > > > > Thoughts?
> > > > 
> > > > The change log of commit e7720af5f9ac ("locking/Documentation: Add 
> > > > disclaimer") says:
> > > > 
> > > > It appears people are reading this document as a requirements list 
> > > > for
> > > > building hardware. This is not the intent of this document. Nor is 
> > > > it
> > > > particularly suited for this purpose.
> > > > 
> > > > The primary purpose of this document is our collective attempt to 
> > > > define
> > > > a set of primitives that (hopefully) allow us to write correct code 
> > > > on
> > > > the myriad of SMP platforms Linux supports.
> > > > 
> > > > Its a definite work in progress as our understanding of these 
> > > > platforms,
> > > > and memory ordering in general, progresses.
> > > > 
> > > > Nor does being mentioned in this document mean we think its a
> > > > particularly good idea; the data dependency barrier required by 
> > > > Alpha
> > > > being a prime example. Yes we have it, no you're insane to require 
> > > > it
> > > > when building new hardware.
> > > > 
> > > > My take on the Linux Kernel memory-consistency model is a supplement of
> > > > memory-barriers.txt and the disclaimer also applies to the memory model.
> > > > 
> > > > > 
> > > > > If I don't hear otherwise in a couple of days, I will pull this as is.
> > > > > 
> > > > >   Thanx, Paul
> > > > > 
> > > > >> ---
> > > > >>  Documentation/memory-barriers.txt | 4 +++-
> > > > >>  1 file changed, 3 insertions(+), 1 deletion(-)
> > > > >> 
> > > > >> diff --git a/Documentation/memory-barriers.txt 
> > > > >> b/Documentation/memory-barriers.txt
> > > > >> index a863009849a3b..8cc3f098f4a7d 100644
> > > > >> --- a/Documentation/memory-barriers.txt
> > > > >> +++ b/Documentation/memory-barriers.txt
> > > > >> @@ -17,7 +17,9 @@ meant as a guide to using the various memory 
> > > > >> barriers provided by Linux, but
> > > > >>  in case of any doubt (and there are many) please ask.
> > > > >> 
> > > > >>  T

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

[Paul E. McKenney]

On Sun, Feb 04, 2018 at 07:37:08PM +0100, Andrea Parri wrote:
> Hi Akira,
> 
> On Mon, Feb 05, 2018 at 01:14:10AM +0900, Akira Yokosawa wrote:
> > Hi Paul,
> > CC: Andrea
> > 
> > This is intentionally off the list, as I was not cc'd in the thread.
> > If you think it is worthwhile, could you help me join the thread by
> > forwarding the following part as a reply to your message, plus CC: to me.
> 
> [CCing lists and other people]
> 
> 
> > 
> > On Fri, Feb 02, 2018 at 17:21:03AM -0800, Paul E. McKenney wrote:
> > > On Fri, Feb 02, 2018 at 10:12:48AM +0100, Andrea Parri wrote:
> > >> Recent efforts led to the specification of a memory consistency model
> > >> for the Linux kernel [1], which "can (roughly speaking) be thought of
> > >> as an automated version of memory-barriers.txt" and which is (in turn)
> > >> "accompanied by extensive documentation on its use and its design".
> > >> 
> > >> Make sure that the (occasional) reader of memory-barriers.txt will be
> > >> aware of these developments.
> > >> 
> > >> [1] https://marc.info/?l=linux-kernel=151687290114799=2
> > >> 
> > >> Signed-off-by: Andrea Parri <parri.andrea@x>
> > > 
> > > I am inclined to pull in something along these lines, but would like
> > > some feedback on the wording, especially how "official" we want to
> > > make the memory model to be.
> > > 
> > > Thoughts?
> > 
> > The change log of commit e7720af5f9ac ("locking/Documentation: Add 
> > disclaimer") says:
> > 
> > It appears people are reading this document as a requirements list for
> > building hardware. This is not the intent of this document. Nor is it
> > particularly suited for this purpose.
> > 
> > The primary purpose of this document is our collective attempt to define
> > a set of primitives that (hopefully) allow us to write correct code on
> > the myriad of SMP platforms Linux supports.
> > 
> > Its a definite work in progress as our understanding of these platforms,
> > and memory ordering in general, progresses.
> > 
> > Nor does being mentioned in this document mean we think its a
> > particularly good idea; the data dependency barrier required by Alpha
> > being a prime example. Yes we have it, no you're insane to require it
> > when building new hardware.
> > 
> > My take on the Linux Kernel memory-consistency model is a supplement of
> > memory-barriers.txt and the disclaimer also applies to the memory model.
> > 
> > > 
> > > If I don't hear otherwise in a couple of days, I will pull this as is.
> > > 
> > >   Thanx, Paul
> > > 
> > >> ---
> > >>  Documentation/memory-barriers.txt | 4 +++-
> > >>  1 file changed, 3 insertions(+), 1 deletion(-)
> > >> 
> > >> diff --git a/Documentation/memory-barriers.txt 
> > >> b/Documentation/memory-barriers.txt
> > >> index a863009849a3b..8cc3f098f4a7d 100644
> > >> --- a/Documentation/memory-barriers.txt
> > >> +++ b/Documentation/memory-barriers.txt
> > >> @@ -17,7 +17,9 @@ meant as a guide to using the various memory barriers 
> > >> provided by Linux, but
> > >>  in case of any doubt (and there are many) please ask.
> > >> 
> > >>  To repeat, this document is not a specification of what Linux expects 
> > >> from
> > >> -hardware.
> > >> +hardware.  For such a specification, in the form of a memory consistency
> > >> +model, and for documentation about its usage and its design, the reader 
> > >> is
> > >> +referred to "tools/memory-model/".
> > >> 
> > 
> > Adding cross-reference in this way can _weaken_ the message of the 
> > disclaimer.
> 
> Thank you for your remarks; I do share the same concern.
> 
> > What about adding it in the previous sentence as the patch appended bellow?
> 
> I do like this idea: I believe that my phrasing (and that "what Linux
> expects from hardware") may be easily subject to misinterpretation...
> which your solution can avoid.

Any objections to Akira's patch below?  (Give or take the usual
wordsmithing.)

Andrea, should I interpret your paragraph above ask an Acked-by?

Thanx, Paul

>   Andrea
> 
> 
> 

Re: [PATCH 2/2] MAINTAINERS: list file memory-barriers.txt within the LKMM entry

[Paul E. McKenney]

On Sat, Feb 03, 2018 at 02:08:00AM +0100, Andrea Parri wrote:
> On Fri, Feb 02, 2018 at 03:51:02PM -0800, Paul E. McKenney wrote:
> > On Fri, Feb 02, 2018 at 10:13:42AM +0100, Andrea Parri wrote:
> > > Now that a formal specification of the LKMM has become available to
> > > the developer, some concern about how to track changes to the model
> > > on the level of the "high-level documentation" was raised.
> > > 
> > > A first "mitigation" to this issue, suggested by Will, is to assign
> > > maintainership (and responsibility!!)  of such documentation (here,
> > > memory-barriers.txt) to the maintainers of the LKMM themselves.
> > > 
> > > Suggested-by: Will Deacon <will.dea...@arm.com>
> > > Signed-off-by: Andrea Parri <parri.and...@gmail.com>
> > 
> > Very good, thank you, queued!  Please see below for the usual commit-log
> > rework.  BTW, in future submissions, could you please capitalize the
> > first word after the colon (":") in the subject line?  It is all too
> > easy for me to forget to change this, as Ingo can attest.  ;-)
> 
> Sorry, I'll do my best! ;-)
> 
> 
> > 
> > If we are going to continue to use the LKMM acronym, should we make the
> > first line of the MAINTAINERS block look something like this?
> 
> I've no strong opinion about whether we should, but it makes sense to me.
> (The acronym is currently defined (and heavily used) in explanation.txt.)

I have added an experimental commit to this effect (see the "EXP" at
the beginning of the subject line).  If there are no objections, I will
squash it into 12a62a1d0703 ("MAINTAINERS: Add the Memory Consistency
Model subsystem").

Thanx, Paul

> Thanks,
>   Andrea
> 
> 
> > 
> > LINUX KERNEL MEMORY CONSISTENCY MODEL (LKMM)
> > 
> > One alternative would be to start calling it LKMCM, though that does
> > look a bit like a Roman numeral.  ;-)
> > 
> > Thanx, Paul
> > 
> > 
> > 
> > commit 2f80571625dc2d1977acdef79267ba1645b07c53
> > Author: Andrea Parri <parri.and...@gmail.com>
> > Date:   Fri Feb 2 10:13:42 2018 +0100
> > 
> > MAINTAINERS: List file memory-barriers.txt within the LKMM entry
> > 
> > We now have a shiny new Linux-kernel memory model (LKMM) and the old
> > tried-and-true Documentation/memory-barrier.txt.  It would be good to
> > keep these automatically synchronized, but in the meantime we need at
> > least let people know that they are related.  Will suggested adding the
> >     Documentation/memory-barrier.txt file to the LKMM maintainership list,
> > thus making the LKMM maintainers responsible for both the old and the 
> > new.
> > This commit follows Will's excellent suggestion.
> > 
> > Suggested-by: Will Deacon <will.dea...@arm.com>
> > Signed-off-by: Andrea Parri <parri.and...@gmail.com>
> > Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> > 
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index ba4dc08fbe95..e6ad9b44e8fb 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -8101,6 +8101,7 @@ L:linux-ker...@vger.kernel.org
> >  S: Supported
> >  T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git
> >  F: tools/memory-model/
> > +F: Documentation/memory-barriers.txt
> >  
> >  LINUX SECURITY MODULE (LSM) FRAMEWORK
> >  M: Chris Wright <chr...@sous-sol.org>
> > 
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Paul E. McKenney]

On Fri, Feb 02, 2018 at 10:12:48AM +0100, Andrea Parri wrote:
> Recent efforts led to the specification of a memory consistency model
> for the Linux kernel [1], which "can (roughly speaking) be thought of
> as an automated version of memory-barriers.txt" and which is (in turn)
> "accompanied by extensive documentation on its use and its design".
> 
> Make sure that the (occasional) reader of memory-barriers.txt will be
> aware of these developments.
> 
> [1] https://marc.info/?l=linux-kernel=151687290114799=2
> 
> Signed-off-by: Andrea Parri 

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

> ---
>  Documentation/memory-barriers.txt | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index a863009849a3b..8cc3f098f4a7d 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -17,7 +17,9 @@ meant as a guide to using the various memory barriers 
> provided by Linux, but
>  in case of any doubt (and there are many) please ask.
> 
>  To repeat, this document is not a specification of what Linux expects from
> -hardware.
> +hardware.  For such a specification, in the form of a memory consistency
> +model, and for documentation about its usage and its design, the reader is
> +referred to "tools/memory-model/".
> 
>  The purpose of this document is twofold:
> 
> -- 
> 2.7.4
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] MAINTAINERS: list file memory-barriers.txt within the LKMM entry

[Paul E. McKenney]

On Fri, Feb 02, 2018 at 10:13:42AM +0100, Andrea Parri wrote:
> Now that a formal specification of the LKMM has become available to
> the developer, some concern about how to track changes to the model
> on the level of the "high-level documentation" was raised.
> 
> A first "mitigation" to this issue, suggested by Will, is to assign
> maintainership (and responsibility!!)  of such documentation (here,
> memory-barriers.txt) to the maintainers of the LKMM themselves.
> 
> Suggested-by: Will Deacon <will.dea...@arm.com>
> Signed-off-by: Andrea Parri <parri.and...@gmail.com>

Very good, thank you, queued!  Please see below for the usual commit-log
rework.  BTW, in future submissions, could you please capitalize the
first word after the colon (":") in the subject line?  It is all too
easy for me to forget to change this, as Ingo can attest.  ;-)

If we are going to continue to use the LKMM acronym, should we make the
first line of the MAINTAINERS block look something like this?

LINUX KERNEL MEMORY CONSISTENCY MODEL (LKMM)

One alternative would be to start calling it LKMCM, though that does
look a bit like a Roman numeral.  ;-)

Thanx, Paul



commit 2f80571625dc2d1977acdef79267ba1645b07c53
Author: Andrea Parri <parri.and...@gmail.com>
Date:   Fri Feb 2 10:13:42 2018 +0100

MAINTAINERS: List file memory-barriers.txt within the LKMM entry

We now have a shiny new Linux-kernel memory model (LKMM) and the old
tried-and-true Documentation/memory-barrier.txt.  It would be good to
keep these automatically synchronized, but in the meantime we need at
least let people know that they are related.  Will suggested adding the
Documentation/memory-barrier.txt file to the LKMM maintainership list,
thus making the LKMM maintainers responsible for both the old and the new.
This commit follows Will's excellent suggestion.

Suggested-by: Will Deacon <will.dea...@arm.com>
Signed-off-by: Andrea Parri <parri.and...@gmail.com>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

diff --git a/MAINTAINERS b/MAINTAINERS
index ba4dc08fbe95..e6ad9b44e8fb 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8101,6 +8101,7 @@ L:linux-ker...@vger.kernel.org
 S: Supported
 T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git
 F: tools/memory-model/
+F: Documentation/memory-barriers.txt
 
 LINUX SECURITY MODULE (LSM) FRAMEWORK
 M: Chris Wright <chr...@sous-sol.org>

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] doc: fix code snippet build warnings

[Paul E. McKenney]

On Thu, Jan 11, 2018 at 07:30:07AM +1100, Tobin C. Harding wrote:
> On Wed, Jan 10, 2018 at 08:37:02AM -0800, Paul E. McKenney wrote:
> > On Wed, Jan 10, 2018 at 03:04:53PM +1100, Tobin C. Harding wrote:
> > > Posting as RFC in the hope that someone knows how to massage sphinx
> > > correctly to fix this patch.
> > 
> > I would welcome that.  ;-)
> > 
> > > Currently function kernel-doc contains a multi-line code snippet. This
> > > is causing sphinx to emit 5 build warnings
> > > 
> > >   WARNING: Unexpected indentation.
> > >   WARNING: Unexpected indentation.
> > >   WARNING: Block quote ends without a blank line; unexpected unindent.
> > >   WARNING: Block quote ends without a blank line; unexpected unindent.
> > >   WARNING: Inline literal start-string without end-string.
> > > 
> > > And the snippet is not rendering correctly in HTML.
> > > 
> > > We can stop shpinx complaining by using '::' instead of the currently
> > > used '``' however this still does not render correctly in HTML. The
> > > rendering is [arguably] better but still incorrect. Sphinx renders two
> > > function calls thus:
> > > 
> > >   :c:func:`rcu_read_lock()`;
> > > 
> > > The rest of the snippet does however have correct spacing.
> > > 
> > > Use '::' to pre-fix code snippet. Clears build warnings but does not
> > > render correctly.
> > 
> > If the usual docbook suspects ack this, I would be happy to carry it.
> > 
> > Cue debate over silent vs. noisy errors.  ;-)
> 
> Besides making me laugh out loud I did not think of this issue while
> patching. FWIW, now you have mentioned it, I favour noisy errors :)

Very good, will leave this one alone, then.  ;-)

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] doc: fix code snippet build warnings

[Paul E. McKenney]

On Wed, Jan 10, 2018 at 03:04:53PM +1100, Tobin C. Harding wrote:
> Posting as RFC in the hope that someone knows how to massage sphinx
> correctly to fix this patch.

I would welcome that.  ;-)

> Currently function kernel-doc contains a multi-line code snippet. This
> is causing sphinx to emit 5 build warnings
> 
>   WARNING: Unexpected indentation.
>   WARNING: Unexpected indentation.
>   WARNING: Block quote ends without a blank line; unexpected unindent.
>   WARNING: Block quote ends without a blank line; unexpected unindent.
>   WARNING: Inline literal start-string without end-string.
> 
> And the snippet is not rendering correctly in HTML.
> 
> We can stop shpinx complaining by using '::' instead of the currently
> used '``' however this still does not render correctly in HTML. The
> rendering is [arguably] better but still incorrect. Sphinx renders two
> function calls thus:
> 
>   :c:func:`rcu_read_lock()`;
> 
> The rest of the snippet does however have correct spacing.
> 
> Use '::' to pre-fix code snippet. Clears build warnings but does not
> render correctly.

If the usual docbook suspects ack this, I would be happy to carry it.

Cue debate over silent vs. noisy errors.  ;-)

Thanx, Paul

> Signed-off-by: Tobin C. Harding 
> ---
> 
> To view current broken rendering see
> 
> https://www.kernel.org/doc/html/latest/core-api/kernel-api.html?highlight=rcu_pointer_handoff#c.rcu_pointer_handoff
> 
>  include/linux/rcupdate.h | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
> index a6ddc42f87a5..cc10e772e3e9 100644
> --- a/include/linux/rcupdate.h
> +++ b/include/linux/rcupdate.h
> @@ -568,7 +568,8 @@ static inline void rcu_preempt_sleep_check(void) { }
>   * is handed off from RCU to some other synchronization mechanism, for
>   * example, reference counting or locking.  In C11, it would map to
>   * kill_dependency().  It could be used as follows:
> - * ``
> + * ::
> + *
>   *   rcu_read_lock();
>   *   p = rcu_dereference(gp);
>   *   long_lived = is_long_lived(p);
> @@ -579,7 +580,6 @@ static inline void rcu_preempt_sleep_check(void) { }
>   *   p = rcu_pointer_handoff(p);
>   *   }
>   *   rcu_read_unlock();
> - *``
>   */
>  #define rcu_pointer_handoff(p) (p)
> 
> -- 
> 2.7.4
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: reST and rcupdate.h

[Paul E. McKenney]

On Thu, Nov 16, 2017 at 04:43:18PM -0800, Randy Dunlap wrote:
> 4.14 docs build tells me:
> 
> ../include/linux/rcupdate.h:571: ERROR: Unexpected indentation.
> ../include/linux/rcupdate.h:575: ERROR: Unexpected indentation.
> ../include/linux/rcupdate.h:579: WARNING: Block quote ends without a blank 
> line; unexpected unindent.
> ../include/linux/rcupdate.h:581: WARNING: Block quote ends without a blank 
> line; unexpected unindent.
> ../include/linux/rcupdate.h:581: WARNING: Inline literal start-string without 
> end-string.
> 
> and I have been mucking around trying to clean this up, but I am not
> getting very far with it.
> 
> If I change `` to .. code-block:: c
> it's a little better:
> 
> ../include/linux/rcupdate.h:576: ERROR: Unexpected indentation.
> ../include/linux/rcupdate.h:580: WARNING: Block quote ends without a blank 
> line; unexpected unindent.
> 
> 
> but I can't seem to eliminate the last 2 problems, and the generated output 
> is bad
> when I view it (html) in a web browser.
> 
> 
> Any ideas/suggestions?

When I asked a few weeks ago, I was told that this was due to a bug in
the sphinx code.

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Wed, Oct 18, 2017 at 10:36:47AM -0600, Jonathan Corbet wrote:
> On Wed, 18 Oct 2017 09:27:01 -0700
> "Paul E. McKenney" <paul...@linux.vnet.ibm.com> wrote:
> 
> > On a related topic...  Is there anything that test-builds docbook prior
> > to patches hitting mainline?  My experience indicates that the answer is
> > "no".
> 
> The zero-day robot is said to be testing for new doc-build errors, but I
> haven't actually seen much of that.

Well, on the good side, Linus did take the fixes.  I will leave it
to you guys to sort things as needed with Fengguang.  ;-)

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH doc/rcu 2/2] doc: Fix various RCU docbook comment-header problems

[Paul E. McKenney]

Because many of RCU's files have not been included into docbook, a
number of errors have accumulated.  This commit fixes them.

Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
---
 include/linux/rculist.h  |  2 +-
 include/linux/rcupdate.h | 22 ++
 include/linux/srcu.h |  1 +
 kernel/rcu/srcutree.c|  2 +-
 kernel/rcu/sync.c|  9 ++---
 kernel/rcu/tree.c| 18 ++
 6 files changed, 33 insertions(+), 21 deletions(-)

diff --git a/include/linux/rculist.h b/include/linux/rculist.h
index b1fd8bf85fdc..2bea1d5e9930 100644
--- a/include/linux/rculist.h
+++ b/include/linux/rculist.h
@@ -276,7 +276,7 @@ static inline void list_splice_tail_init_rcu(struct 
list_head *list,
 #define list_entry_rcu(ptr, type, member) \
container_of(lockless_dereference(ptr), type, member)
 
-/**
+/*
  * Where are list_empty_rcu() and list_first_entry_rcu()?
  *
  * Implementing those functions following their counterparts list_empty() and
diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
index de50d8a4cf41..1a9f70d44af9 100644
--- a/include/linux/rcupdate.h
+++ b/include/linux/rcupdate.h
@@ -523,7 +523,7 @@ static inline void rcu_preempt_sleep_check(void) { }
  * Return the value of the specified RCU-protected pointer, but omit
  * both the smp_read_barrier_depends() and the READ_ONCE().  This
  * is useful in cases where update-side locks prevent the value of the
- * pointer from changing.  Please note that this primitive does -not-
+ * pointer from changing.  Please note that this primitive does *not*
  * prevent the compiler from repeating this reference or combining it
  * with other references, so it should not be used without protection
  * of appropriate locks.
@@ -568,7 +568,7 @@ static inline void rcu_preempt_sleep_check(void) { }
  * is handed off from RCU to some other synchronization mechanism, for
  * example, reference counting or locking.  In C11, it would map to
  * kill_dependency().  It could be used as follows:
- *
+ * ``
  * rcu_read_lock();
  * p = rcu_dereference(gp);
  * long_lived = is_long_lived(p);
@@ -579,6 +579,7 @@ static inline void rcu_preempt_sleep_check(void) { }
  * p = rcu_pointer_handoff(p);
  * }
  * rcu_read_unlock();
+ *``
  */
 #define rcu_pointer_handoff(p) (p)
 
@@ -778,18 +779,21 @@ static inline notrace void 
rcu_read_unlock_sched_notrace(void)
 
 /**
  * RCU_INIT_POINTER() - initialize an RCU protected pointer
+ * @p: The pointer to be initialized.
+ * @v: The value to initialized the pointer to.
  *
  * Initialize an RCU-protected pointer in special cases where readers
  * do not need ordering constraints on the CPU or the compiler.  These
  * special cases are:
  *
- * 1.  This use of RCU_INIT_POINTER() is NULLing out the pointer -or-
+ * 1.  This use of RCU_INIT_POINTER() is NULLing out the pointer *or*
  * 2.  The caller has taken whatever steps are required to prevent
- * RCU readers from concurrently accessing this pointer -or-
+ * RCU readers from concurrently accessing this pointer *or*
  * 3.  The referenced data structure has already been exposed to
- * readers either at compile time or via rcu_assign_pointer() -and-
- * a.  You have not made -any- reader-visible changes to
- * this structure since then -or-
+ * readers either at compile time or via rcu_assign_pointer() *and*
+ *
+ * a.  You have not made *any* reader-visible changes to
+ * this structure since then *or*
  * b.  It is OK for readers accessing this structure from its
  * new location to see the old state of the structure.  (For
  * example, the changes were to statistical counters or to
@@ -805,7 +809,7 @@ static inline notrace void 
rcu_read_unlock_sched_notrace(void)
  * by a single external-to-structure RCU-protected pointer, then you may
  * use RCU_INIT_POINTER() to initialize the internal RCU-protected
  * pointers, but you must use rcu_assign_pointer() to initialize the
- * external-to-structure pointer -after- you have completely initialized
+ * external-to-structure pointer *after* you have completely initialized
  * the reader-accessible portions of the linked structure.
  *
  * Note that unlike rcu_assign_pointer(), RCU_INIT_POINTER() provides no
@@ -819,6 +823,8 @@ static inline notrace void 
rcu_read_unlock_sched_notrace(void)
 
 /**
  * RCU_POINTER_INITIALIZER() - statically initialize an RCU protected pointer
+ * @p: The pointer to be initialized.
+ * @v: The value to initialized the pointer to.
  *
  * GCC-style initialization for an RCU-protected pointer in a structure field.
  */
diff --git a/include/linux/srcu.h b/include/linux/srcu.h
index 39af9bc0f653..62be8966e837 100644
--- a/include/linux/srcu.h
+++ b/include/linux/srcu.h
@@ -78,6 +78,7 @@ void synchronize_srcu(struct srcu_struct *sp);
 
 /**
  * srcu_read_lock_held - might we be in SRCU read-side critical s

[PATCH doc/rcu 1/2] doc: Fix RCU's docbook options

[Paul E. McKenney]

Commit 764f80798b95 ("doc: Add RCU files to docbook-generation files")
added :external: options for RCU source files in the file
Documentation/core-api/kernel-api.rst.  However, this now means
nothing, so this commit removes them.

Reported-by: Randy Dunlap <rdun...@infradead.org>
Reported-by: Akira Yokosawa <aki...@gmail.com>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
---
 Documentation/core-api/kernel-api.rst | 14 --
 1 file changed, 14 deletions(-)

diff --git a/Documentation/core-api/kernel-api.rst 
b/Documentation/core-api/kernel-api.rst
index 8282099e0cbf..5da10184d908 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -352,44 +352,30 @@ Read-Copy Update (RCU)
 --
 
 .. kernel-doc:: include/linux/rcupdate.h
-   :external:
 
 .. kernel-doc:: include/linux/rcupdate_wait.h
-   :external:
 
 .. kernel-doc:: include/linux/rcutree.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/tree.c
-   :external:
 
 .. kernel-doc:: kernel/rcu/tree_plugin.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/tree_exp.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/update.c
-   :external:
 
 .. kernel-doc:: include/linux/srcu.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/srcutree.c
-   :external:
 
 .. kernel-doc:: include/linux/rculist_bl.h
-   :external:
 
 .. kernel-doc:: include/linux/rculist.h
-   :external:
 
 .. kernel-doc:: include/linux/rculist_nulls.h
-   :external:
 
 .. kernel-doc:: include/linux/rcu_sync.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/sync.c
-   :external:
 
-- 
2.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH doc/rcu 2/2] doc: Fix various RCU docbook comment-header problems

[Paul E. McKenney]

Because many of RCU's files have not been included into docbook, a
number of errors have accumulated.  This commit fixes them.

Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
---
 include/linux/rculist.h  |  2 +-
 include/linux/rcupdate.h | 22 ++
 include/linux/srcu.h |  1 +
 kernel/rcu/srcutree.c|  2 +-
 kernel/rcu/sync.c|  9 ++---
 kernel/rcu/tree.c| 18 ++
 6 files changed, 33 insertions(+), 21 deletions(-)

diff --git a/include/linux/rculist.h b/include/linux/rculist.h
index b1fd8bf85fdc..2bea1d5e9930 100644
--- a/include/linux/rculist.h
+++ b/include/linux/rculist.h
@@ -276,7 +276,7 @@ static inline void list_splice_tail_init_rcu(struct 
list_head *list,
 #define list_entry_rcu(ptr, type, member) \
container_of(lockless_dereference(ptr), type, member)
 
-/**
+/*
  * Where are list_empty_rcu() and list_first_entry_rcu()?
  *
  * Implementing those functions following their counterparts list_empty() and
diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
index de50d8a4cf41..1a9f70d44af9 100644
--- a/include/linux/rcupdate.h
+++ b/include/linux/rcupdate.h
@@ -523,7 +523,7 @@ static inline void rcu_preempt_sleep_check(void) { }
  * Return the value of the specified RCU-protected pointer, but omit
  * both the smp_read_barrier_depends() and the READ_ONCE().  This
  * is useful in cases where update-side locks prevent the value of the
- * pointer from changing.  Please note that this primitive does -not-
+ * pointer from changing.  Please note that this primitive does *not*
  * prevent the compiler from repeating this reference or combining it
  * with other references, so it should not be used without protection
  * of appropriate locks.
@@ -568,7 +568,7 @@ static inline void rcu_preempt_sleep_check(void) { }
  * is handed off from RCU to some other synchronization mechanism, for
  * example, reference counting or locking.  In C11, it would map to
  * kill_dependency().  It could be used as follows:
- *
+ * ``
  * rcu_read_lock();
  * p = rcu_dereference(gp);
  * long_lived = is_long_lived(p);
@@ -579,6 +579,7 @@ static inline void rcu_preempt_sleep_check(void) { }
  * p = rcu_pointer_handoff(p);
  * }
  * rcu_read_unlock();
+ *``
  */
 #define rcu_pointer_handoff(p) (p)
 
@@ -778,18 +779,21 @@ static inline notrace void 
rcu_read_unlock_sched_notrace(void)
 
 /**
  * RCU_INIT_POINTER() - initialize an RCU protected pointer
+ * @p: The pointer to be initialized.
+ * @v: The value to initialized the pointer to.
  *
  * Initialize an RCU-protected pointer in special cases where readers
  * do not need ordering constraints on the CPU or the compiler.  These
  * special cases are:
  *
- * 1.  This use of RCU_INIT_POINTER() is NULLing out the pointer -or-
+ * 1.  This use of RCU_INIT_POINTER() is NULLing out the pointer *or*
  * 2.  The caller has taken whatever steps are required to prevent
- * RCU readers from concurrently accessing this pointer -or-
+ * RCU readers from concurrently accessing this pointer *or*
  * 3.  The referenced data structure has already been exposed to
- * readers either at compile time or via rcu_assign_pointer() -and-
- * a.  You have not made -any- reader-visible changes to
- * this structure since then -or-
+ * readers either at compile time or via rcu_assign_pointer() *and*
+ *
+ * a.  You have not made *any* reader-visible changes to
+ * this structure since then *or*
  * b.  It is OK for readers accessing this structure from its
  * new location to see the old state of the structure.  (For
  * example, the changes were to statistical counters or to
@@ -805,7 +809,7 @@ static inline notrace void 
rcu_read_unlock_sched_notrace(void)
  * by a single external-to-structure RCU-protected pointer, then you may
  * use RCU_INIT_POINTER() to initialize the internal RCU-protected
  * pointers, but you must use rcu_assign_pointer() to initialize the
- * external-to-structure pointer -after- you have completely initialized
+ * external-to-structure pointer *after* you have completely initialized
  * the reader-accessible portions of the linked structure.
  *
  * Note that unlike rcu_assign_pointer(), RCU_INIT_POINTER() provides no
@@ -819,6 +823,8 @@ static inline notrace void 
rcu_read_unlock_sched_notrace(void)
 
 /**
  * RCU_POINTER_INITIALIZER() - statically initialize an RCU protected pointer
+ * @p: The pointer to be initialized.
+ * @v: The value to initialized the pointer to.
  *
  * GCC-style initialization for an RCU-protected pointer in a structure field.
  */
diff --git a/include/linux/srcu.h b/include/linux/srcu.h
index 39af9bc0f653..62be8966e837 100644
--- a/include/linux/srcu.h
+++ b/include/linux/srcu.h
@@ -78,6 +78,7 @@ void synchronize_srcu(struct srcu_struct *sp);
 
 /**
  * srcu_read_lock_held - might we be in SRCU read-side critical s

[PATCH doc/rcu 1/2] doc: Fix RCU's docbook options

[Paul E. McKenney]

Commit 764f80798b95 ("doc: Add RCU files to docbook-generation files")
added :external: options for RCU source files in the file
Documentation/core-api/kernel-api.rst.  However, this now means
nothing, so this commit removes them.

Reported-by: Randy Dunlap <rdun...@infradead.org>
Reported-by: Akira Yokosawa <aki...@gmail.com>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
---
 Documentation/core-api/kernel-api.rst | 14 --
 1 file changed, 14 deletions(-)

diff --git a/Documentation/core-api/kernel-api.rst 
b/Documentation/core-api/kernel-api.rst
index 8282099e0cbf..5da10184d908 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -352,44 +352,30 @@ Read-Copy Update (RCU)
 --
 
 .. kernel-doc:: include/linux/rcupdate.h
-   :external:
 
 .. kernel-doc:: include/linux/rcupdate_wait.h
-   :external:
 
 .. kernel-doc:: include/linux/rcutree.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/tree.c
-   :external:
 
 .. kernel-doc:: kernel/rcu/tree_plugin.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/tree_exp.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/update.c
-   :external:
 
 .. kernel-doc:: include/linux/srcu.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/srcutree.c
-   :external:
 
 .. kernel-doc:: include/linux/rculist_bl.h
-   :external:
 
 .. kernel-doc:: include/linux/rculist.h
-   :external:
 
 .. kernel-doc:: include/linux/rculist_nulls.h
-   :external:
 
 .. kernel-doc:: include/linux/rcu_sync.h
-   :external:
 
 .. kernel-doc:: kernel/rcu/sync.c
-   :external:
 
-- 
2.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH doc/rcu 0/2] Fix docbook regression

[Paul E. McKenney]

Hello, Linus,

Commit 764f80798b95 ("doc: Add RCU files to docbook-generation files"),
which is in v4.14-rc1, added :external: options for RCU source files
in the file Documentation/core-api/kernel-api.rst.  However, this now
means nothing, and furthermore breaks builds of the docbook, which has
led to popular demand for this to be fixed in v4.14:

lkml.kernel.org/r/20171018100340.7f34a...@lwn.net

This series therefore contains the following two patches:

1.  Remove the erroneous :external: options.

2.  Fix the many docbook build complaints that have crept into RCU's
docbook comment headers.  These fixes include one non-comment
change where the name of rcu_sync_func()'s argument is changed
to match RCU convention.

Thanx, Paul



 Documentation/core-api/kernel-api.rst |   14 --
 include/linux/rculist.h   |2 +-
 include/linux/rcupdate.h  |   22 ++
 include/linux/srcu.h  |1 +
 kernel/rcu/srcutree.c |2 +-
 kernel/rcu/sync.c |9 ++---
 kernel/rcu/tree.c |   18 ++
 7 files changed, 33 insertions(+), 35 deletions(-)

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Wed, Oct 18, 2017 at 10:03:40AM -0600, Jonathan Corbet wrote:
> On Mon, 16 Oct 2017 13:26:19 -0700
> "Paul E. McKenney" <paul...@linux.vnet.ibm.com> wrote:
> 
> > OK, how about if I submit them to the 4.15 merge window, but add the
> > appropriate -stable tags to get them backported?  Yes, these are bugs,
> > but I cannot in good conscience claim that they are v4.14 regressions.
> > 
> > But if Jon agrees with you, I will of course create a patch series,
> > pull request, or whatever and send it along to him.
> 
> [Sorry for being slow ... $EXCUSES ... ]
> 
> One could argue that they are indeed a regression; they introduced a bunch
> of build errors into 4.14.  I think it would be better to see it fixed if
> possible.  I don't care that much about how it gets there; Paul, I can
> send it Linusward if you don't want to.

I never have pushed directly to Linus, so I might as well get started
doing so.

On a related topic...  Is there anything that test-builds docbook prior
to patches hitting mainline?  My experience indicates that the answer is
"no".

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Mon, Oct 16, 2017 at 02:46:15PM -0700, Randy Dunlap wrote:
> On 10/16/17 13:26, Paul E. McKenney wrote:
> > On Mon, Oct 16, 2017 at 01:18:14PM -0700, Randy Dunlap wrote:
> >> On 10/16/17 13:07, Paul E. McKenney wrote:
> >>> On Mon, Oct 16, 2017 at 12:58:28PM -0700, Randy Dunlap wrote:
> >>>> Hi Jonathan and Paul,
> >>>>
> >>>> Please include these fixes before 4.14 final.
> >>>
> >>> Hello, Randy,
> >>>
> >>> I currently have them queued up for the 4.15 merge window.  Will that
> >>> work for you?
> >>
> >> They should be fixed in 4.14 final IMO.
> > 
> > OK, how about if I submit them to the 4.15 merge window, but add the
> > appropriate -stable tags to get them backported?  Yes, these are bugs,
> > but I cannot in good conscience claim that they are v4.14 regressions.
> > 
> > But if Jon agrees with you, I will of course create a patch series,
> > pull request, or whatever and send it along to him.
> 
> You or Jon could just revert this commit then:
> 
> commit 764f80798b958f74dbf0c6e76a8294d183dd9c16
> Author: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> Date:   Tue Jul 4 14:42:20 2017 -0700
> 
> doc: Add RCU files to docbook-generation files
> 
> Suggested-by: Jonathan Corbet <cor...@lwn.net>
> Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> 
> But the current condition is bad.

Jon, what would you prefer?

    Thanx, Paul

> >>>> Thanks.
> >>>>
> >>>> On 09/17/17 12:49, Paul E. McKenney wrote:
> >>>>> On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> >>>>>> On 09/17/17 10:47, Paul E. McKenney wrote:
> >>>>>>> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> >>>>>>>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> >>>>>>>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> >>>>>>>>>
> >>>>>>>>> .. kernel-doc:: include/linux/rcupdate.h
> >>>>>>>>>:external:
> >>>>>>>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in 
> >>>>>>>>> "kernel-doc" directive:
> >>>>>>>>> unknown option: "external".
> >>>>>>>>
> >>>>>>>> $ grep external include/linux/rcupdate.h
> >>>>>>>>  * by a single external-to-structure RCU-protected pointer, then you 
> >>>>>>>> may
> >>>>>>>>  * external-to-structure pointer -after- you have completely 
> >>>>>>>> initialized
> >>>>>>>>
> >>>>>>>> Do these comments somehow qualify as an "external" option?  If so, 
> >>>>>>>> how
> >>>>>>>> do I tell kernel-doc to ignore them?  Or must I reword them to avoid
> >>>>>>>> the word "external"?
> >>>>>>>>
> >>>>>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>>>>>>>>:external:
> >>>>>>>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in 
> >>>>>>>>> "kernel-doc" directive:
> >>>>>>>>> unknown option: "external".
> >>>>>>>>
> >>>>>>>> $ grep external include/linux/rcupdate_wait.h
> >>>>>>>>
> >>>>>>>> There is no occurrence of the string "external" in this file.  So 
> >>>>>>>> this
> >>>>>>>> "external" option is unknown to me as well.  So, any hints on how I
> >>>>>>>> should interpret these error messages?
> >>>>>>>
> >>>>>>> And thanks to Akira Yokosawa for pointing out my confusion in reading
> >>>>>>> these error messages.  The line numbers of course apply to the file
> >>>>>>> Documentation/core-api/kernel-api.rst rather than the various RCU
> >>>>>>> C-language source files.
> >>>>>>>
> >>>>>>> The patch below removes the error messages for me.  Is this what you

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Mon, Oct 16, 2017 at 12:58:28PM -0700, Randy Dunlap wrote:
> Hi Jonathan and Paul,
> 
> Please include these fixes before 4.14 final.

Hello, Randy,

I currently have them queued up for the 4.15 merge window.  Will that
work for you?

Thanx, Paul

> Thanks.
> 
> On 09/17/17 12:49, Paul E. McKenney wrote:
> > On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> >> On 09/17/17 10:47, Paul E. McKenney wrote:
> >>> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> >>>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> >>>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rcupdate.h
> >>>>>:external:
> >>>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in 
> >>>>> "kernel-doc" directive:
> >>>>> unknown option: "external".
> >>>>
> >>>> $ grep external include/linux/rcupdate.h
> >>>>  * by a single external-to-structure RCU-protected pointer, then you may
> >>>>  * external-to-structure pointer -after- you have completely initialized
> >>>>
> >>>> Do these comments somehow qualify as an "external" option?  If so, how
> >>>> do I tell kernel-doc to ignore them?  Or must I reword them to avoid
> >>>> the word "external"?
> >>>>
> >>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>>>>:external:
> >>>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in 
> >>>>> "kernel-doc" directive:
> >>>>> unknown option: "external".
> >>>>
> >>>> $ grep external include/linux/rcupdate_wait.h
> >>>>
> >>>> There is no occurrence of the string "external" in this file.  So this
> >>>> "external" option is unknown to me as well.  So, any hints on how I
> >>>> should interpret these error messages?
> >>>
> >>> And thanks to Akira Yokosawa for pointing out my confusion in reading
> >>> these error messages.  The line numbers of course apply to the file
> >>> Documentation/core-api/kernel-api.rst rather than the various RCU
> >>> C-language source files.
> >>>
> >>> The patch below removes the error messages for me.  Is this what you
> >>> had in mind?  (Might need other options at some point, but somewhere
> >>> to start.)
> >>>
> >>
> >> Yes, much better.  Thanks.
> >>
> >> Just some missing kernel-doc on parameters mostly remaining:
> > 
> > I have now fixed a number of these, thank you.
> > 
> > Any hints for how to represent code samples within a "/**" comment?
> > 
> > /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected 
> > indentation.
> > /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote 
> > ends without a blank line; unexpected unindent.
> > /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected 
> > indentation.
> > /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote 
> > ends without a blank line; unexpected unindent.
> > 
> > Thanx, Paul
> > 
> >> ../include/linux/rcupdate.h:818: warning: No description found for 
> >> parameter 'p'
> >> ../include/linux/rcupdate.h:818: warning: No description found for 
> >> parameter 'v'
> >> ../include/linux/rcupdate.h:826: warning: No description found for 
> >> parameter 'p'
> >> ../include/linux/rcupdate.h:826: warning: No description found for 
> >> parameter 'v'
> >> ../include/linux/srcu.h:95: warning: No description found for parameter 
> >> 'sp'
> >> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 
> >> 'rhp'
> >> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' 
> >> description in 'call_srcu'
> >> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc 
> >> format:  * list_first_or_null_rcu - get the first element from a list
> >> ../include/linux/rculist.h:317: warning: No description found for 
> >> parameter 'ptr'
> >> ../include/linux/rculist.h:317: warning: No description found 

Re: [PATCH v2] Documentation: rewrite confusing statement about memory barriers

[Paul E. McKenney]

On Thu, Sep 21, 2017 at 04:29:01PM -0300, Guilherme G. Piccoli wrote:
> In this specific portion of the write memory barriers description,
> the documentation mentions sequential order of stores, which is
> confusing since sequential ordering is not guaranteed.
> 
> This patch tries to improve the doc in order to avoid any
> mis-understanding.
> 
> Cc: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> Signed-off-by: Guilherme G. Piccoli <gpicc...@linux.vnet.ibm.com>

Good catch, and you are quite correct, a write barrier orders only
before and after itself, doing nothing to impose order on preceding
writes among themselves.

Applied, thank you!

Thanx, Paul

> ---
> 
> v2: added Paul in CC.
> 
>  Documentation/memory-barriers.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index b759a60624fd..a4bbbd1b63a0 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -383,8 +383,8 @@ Memory barriers come in four basic varieties:
>   to have any effect on loads.
> 
>   A CPU can be viewed as committing a sequence of store operations to the
> - memory system as time progresses.  All stores before a write barrier 
> will
> - occur in the sequence _before_ all the stores after the write barrier.
> + memory system as time progresses.  All stores _before_ a write barrier
> + will occur _before_ all the stores after the write barrier.
> 
>   [!] Note that write barriers should normally be paired with read or data
>   dependency barriers; see the "SMP barrier pairing" subsection.
> -- 
> 2.14.1
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Mon, Sep 18, 2017 at 09:30:01AM +0200, Markus Heiser wrote:
> 
> > Am 18.09.2017 um 04:40 schrieb Paul E. McKenney 
> > <paul...@linux.vnet.ibm.com>:
> [...]
> > And after some playing around, I did get rid of the error messages.
> > The code-block output looks a bit strange though, hints?  I preceded
> > the code block with "::", again at Akira's suggestion.  It looks fine
> > except for the :c:func: and backquotes on the first and last lines.
> > 
> > Thanx, Paul
> > 
> > 
> > 
> > :c:func:`rcu_read_lock()`;
> > p = rcu_dereference(gp);
> > long_lived = is_long_lived(p);
> > if (long_lived) {
> >   if (!atomic_inc_not_zero(p->refcnt))
> > long_lived = false;
> > else
> > p = rcu_pointer_handoff(p);
> > }
> > :c:func:`rcu_read_unlock()`;
> 
> FYI: 
> 
> such replacements in code-blocks are comming from the "Highlights
> and cross-references" see:
> 
>  
> https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#highlights-and-cross-references
> 
> and this is still a bug in the kernel-doc parser:
> 
>  https://www.mail-archive.com/linux-doc@vger.kernel.org/msg14409.html

Thank you for the pointer!  I will try it out.  Except that v4.14-rc1
apparently needs a later version of sphinx...

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Sun, Sep 17, 2017 at 12:49:10PM -0700, Paul E. McKenney wrote:
> On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> > On 09/17/17 10:47, Paul E. McKenney wrote:
> > > On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> > >> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> > >>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> > >>>
> > >>> .. kernel-doc:: include/linux/rcupdate.h
> > >>>:external:
> > >>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in 
> > >>> "kernel-doc" directive:
> > >>> unknown option: "external".
> > >>
> > >> $ grep external include/linux/rcupdate.h
> > >>  * by a single external-to-structure RCU-protected pointer, then you may
> > >>  * external-to-structure pointer -after- you have completely initialized
> > >>
> > >> Do these comments somehow qualify as an "external" option?  If so, how
> > >> do I tell kernel-doc to ignore them?  Or must I reword them to avoid
> > >> the word "external"?
> > >>
> > >>> .. kernel-doc:: include/linux/rcupdate_wait.h
> > >>>:external:
> > >>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in 
> > >>> "kernel-doc" directive:
> > >>> unknown option: "external".
> > >>
> > >> $ grep external include/linux/rcupdate_wait.h
> > >>
> > >> There is no occurrence of the string "external" in this file.  So this
> > >> "external" option is unknown to me as well.  So, any hints on how I
> > >> should interpret these error messages?
> > > 
> > > And thanks to Akira Yokosawa for pointing out my confusion in reading
> > > these error messages.  The line numbers of course apply to the file
> > > Documentation/core-api/kernel-api.rst rather than the various RCU
> > > C-language source files.
> > > 
> > > The patch below removes the error messages for me.  Is this what you
> > > had in mind?  (Might need other options at some point, but somewhere
> > > to start.)
> > > 
> > 
> > Yes, much better.  Thanks.
> > 
> > Just some missing kernel-doc on parameters mostly remaining:
> 
> I have now fixed a number of these, thank you.
> 
> Any hints for how to represent code samples within a "/**" comment?
> 
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected 
> indentation.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote 
> ends without a blank line; unexpected unindent.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected 
> indentation.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote 
> ends without a blank line; unexpected unindent.

And after some playing around, I did get rid of the error messages.
The code-block output looks a bit strange though, hints?  I preceded
the code block with "::", again at Akira's suggestion.  It looks fine
except for the :c:func: and backquotes on the first and last lines.

Thanx, Paul



:c:func:`rcu_read_lock()`;
p = rcu_dereference(gp);
long_lived = is_long_lived(p);
if (long_lived) {
if (!atomic_inc_not_zero(p->refcnt))
long_lived = false;
else
p = rcu_pointer_handoff(p);
}
:c:func:`rcu_read_unlock()`;

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> On 09/17/17 10:47, Paul E. McKenney wrote:
> > On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> >> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> >>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> >>>
> >>> .. kernel-doc:: include/linux/rcupdate.h
> >>>:external:
> >>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" 
> >>> directive:
> >>> unknown option: "external".
> >>
> >> $ grep external include/linux/rcupdate.h
> >>  * by a single external-to-structure RCU-protected pointer, then you may
> >>  * external-to-structure pointer -after- you have completely initialized
> >>
> >> Do these comments somehow qualify as an "external" option?  If so, how
> >> do I tell kernel-doc to ignore them?  Or must I reword them to avoid
> >> the word "external"?
> >>
> >>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>>:external:
> >>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" 
> >>> directive:
> >>> unknown option: "external".
> >>
> >> $ grep external include/linux/rcupdate_wait.h
> >>
> >> There is no occurrence of the string "external" in this file.  So this
> >> "external" option is unknown to me as well.  So, any hints on how I
> >> should interpret these error messages?
> > 
> > And thanks to Akira Yokosawa for pointing out my confusion in reading
> > these error messages.  The line numbers of course apply to the file
> > Documentation/core-api/kernel-api.rst rather than the various RCU
> > C-language source files.
> > 
> > The patch below removes the error messages for me.  Is this what you
> > had in mind?  (Might need other options at some point, but somewhere
> > to start.)
> > 
> 
> Yes, much better.  Thanks.
> 
> Just some missing kernel-doc on parameters mostly remaining:

I have now fixed a number of these, thank you.

Any hints for how to represent code samples within a "/**" comment?

/home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected 
indentation.
/home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends 
without a blank line; unexpected unindent.
/home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected 
indentation.
/home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends 
without a blank line; unexpected unindent.

Thanx, Paul

> ../include/linux/rcupdate.h:818: warning: No description found for parameter 
> 'p'
> ../include/linux/rcupdate.h:818: warning: No description found for parameter 
> 'v'
> ../include/linux/rcupdate.h:826: warning: No description found for parameter 
> 'p'
> ../include/linux/rcupdate.h:826: warning: No description found for parameter 
> 'v'
> ../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 
> 'rhp'
> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' 
> description in 'call_srcu'
> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format:  
> * list_first_or_null_rcu - get the first element from a list
> ../include/linux/rculist.h:317: warning: No description found for parameter 
> 'ptr'
> ../include/linux/rculist.h:317: warning: No description found for parameter 
> 'type'
> ../include/linux/rculist.h:317: warning: No description found for parameter 
> 'member'
> ../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
> ../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
> ../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' 
> description in 'rcu_sync_func'
> 
> > 
> > 
> > 
> > diff --git a/Documentation/core-api/kernel-api.rst 
> > b/Documentation/core-api/kernel-api.rst
> > index 8282099e0cbf..30b2666bf494 100644
> > --- a/Documentation/core-api/kernel-api.rst
> > +++ b/Documentation/core-api/kernel-api.rst
> > @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
> >  --
> >  
> >  .. kernel-doc:: include/linux/rcupdate.h
> > -   :external:
> > +   :export
> >  
> >  .. kernel-doc:: include/linux/rcupdate_wait.h
> > -   :external:
> > +   :e

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> > On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> > 
> > .. kernel-doc:: include/linux/rcupdate.h
> >:external:
> > ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" 
> > directive:
> > unknown option: "external".
> 
> $ grep external include/linux/rcupdate.h
>  * by a single external-to-structure RCU-protected pointer, then you may
>  * external-to-structure pointer -after- you have completely initialized
> 
> Do these comments somehow qualify as an "external" option?  If so, how
> do I tell kernel-doc to ignore them?  Or must I reword them to avoid
> the word "external"?
> 
> > .. kernel-doc:: include/linux/rcupdate_wait.h
> >:external:
> > ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" 
> > directive:
> > unknown option: "external".
> 
> $ grep external include/linux/rcupdate_wait.h
> 
> There is no occurrence of the string "external" in this file.  So this
> "external" option is unknown to me as well.  So, any hints on how I
> should interpret these error messages?

And thanks to Akira Yokosawa for pointing out my confusion in reading
these error messages.  The line numbers of course apply to the file
Documentation/core-api/kernel-api.rst rather than the various RCU
C-language source files.

The patch below removes the error messages for me.  Is this what you
had in mind?  (Might need other options at some point, but somewhere
to start.)

Thanx, Paul



diff --git a/Documentation/core-api/kernel-api.rst 
b/Documentation/core-api/kernel-api.rst
index 8282099e0cbf..30b2666bf494 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -352,44 +352,44 @@ Read-Copy Update (RCU)
 --
 
 .. kernel-doc:: include/linux/rcupdate.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rcupdate_wait.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rcutree.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/tree.c
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/tree_plugin.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/tree_exp.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/update.c
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/srcu.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/srcutree.c
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rculist_bl.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rculist.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rculist_nulls.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rcu_sync.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/sync.c
-   :external:
+   :export
 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: rcu kernel-doc issues (4.14-rc1)

[Paul E. McKenney]

On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> 
> .. kernel-doc:: include/linux/rcupdate.h
>:external:
> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".

$ grep external include/linux/rcupdate.h
 * by a single external-to-structure RCU-protected pointer, then you may
 * external-to-structure pointer -after- you have completely initialized

Do these comments somehow qualify as an "external" option?  If so, how
do I tell kernel-doc to ignore them?  Or must I reword them to avoid
the word "external"?

> .. kernel-doc:: include/linux/rcupdate_wait.h
>:external:
> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".

$ grep external include/linux/rcupdate_wait.h

There is no occurrence of the string "external" in this file.  So this
"external" option is unknown to me as well.  So, any hints on how I
should interpret these error messages?

Thanx, Paul

> .. kernel-doc:: include/linux/rcutree.h
>:external:
> ./Documentation/core-api/kernel-api.rst:363: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: kernel/rcu/tree.c
>:external:
> ./Documentation/core-api/kernel-api.rst:366: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: kernel/rcu/tree_plugin.h
>:external:
> ./Documentation/core-api/kernel-api.rst:369: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: kernel/rcu/tree_exp.h
>:external:
> ./Documentation/core-api/kernel-api.rst:372: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: kernel/rcu/update.c
>:external:
> ./Documentation/core-api/kernel-api.rst:375: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: include/linux/srcu.h
>:external:
> ./Documentation/core-api/kernel-api.rst:378: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: kernel/rcu/srcutree.c
>:external:
> ./Documentation/core-api/kernel-api.rst:381: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: include/linux/rculist_bl.h
>:external:
> ./Documentation/core-api/kernel-api.rst:384: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: include/linux/rculist.h
>:external:
> ./Documentation/core-api/kernel-api.rst:387: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: include/linux/rculist_nulls.h
>:external:
> ./Documentation/core-api/kernel-api.rst:390: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: include/linux/rcu_sync.h
>:external:
> ./Documentation/core-api/kernel-api.rst:393: ERROR: Error in "kernel-doc" 
> directive:
> unknown option: "external".
> 
> .. kernel-doc:: kernel/rcu/sync.c
>:external:
> 
> ../kernel/rcu/tree.c:3091: ERROR: Unexpected indentation.
> ../kernel/rcu/tree.c:3118: ERROR: Unexpected indentation.
> ../kernel/rcu/tree.c:3119: WARNING: Bullet list ends without a blank line; 
> unexpected unindent.
> 
> 
> -- 
> ~Randy
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4] printk: Add monotonic, boottime, and realtime timestamps

[Paul E. McKenney]

On Tue, Aug 08, 2017 at 07:08:00PM -0400, Prarit Bhargava wrote:
> 
> 
> On 08/08/2017 04:28 AM, Peter Zijlstra wrote:
> > On Mon, Aug 07, 2017 at 01:36:39PM -0700, Paul E. McKenney wrote:
> >> On Mon, Aug 07, 2017 at 04:06:09PM -0400, Prarit Bhargava wrote:
> > 
> >>> peterz?  Want to offer a suggestion?  The issue is that I'm changing a 
> >>> bool
> >>> config option to an int and that impacts all the arch's defconfigs.  John 
> >>> points
> >>> out that this is a lot of churn and we're both wondering if there's a 
> >>> better way
> >>> to do the configs.
> >>
> >> The usual approach is to keep the old bool Kconfig option, and add another
> >> int Kconfig option that depends on the original one.  The tests for
> >> the int value get a bit more complex, but one way to handle this is to
> >> define a cpp macro something like the following:
> >>
> >> #ifdef CONFIG_OLD_OPTION
> >> #define CPP_NEW_OPTION 0
> >> #else
> >> #define CPP_NEW_OPTION CONFIG_NEW_OPTION
> >> #endif
> >>
> >> Then use CPP_NEW_OPTION, where zero means disabled and other numbers
> >> select the available options.
> >>
> >> Adjust to suit depending on what values mean what.
> >>
> >> Another approach is to make the range of the new Kconfig option
> >> depend on the old option:
> >>
> >> config NEW_OPTION
> >>int "your description here"
> >>range 1 5 if OLD_OPTION
> >>range 0 0 if !OLD_OPTION
> >>default 0
> >>help
> >>  your help here
> >>
> >> Again, adjust to suit depending on what values mean what.
> > 
> > Right this. Except I don't see the !OLD_OPTION working as expected.
> > A 'new' config will not include the old one, so the !OLD_OPTION thing
> > will 'always' be true.
> > 
> > So your:
> > 
> >> @@ -1,8 +1,46 @@
> >>  menu "printk and dmesg options"
> >>
> >> +choice
> >> +   prompt "printk default clock"
> >> +   config PRINTK_TIME_DISABLE
> >> +   bool "Disabled"
> >> +   help
> >> +Selecting this option disables the time stamps of printk().
> >> +
> >> +   config PRINTK_TIME_LOCAL
> >> +   bool "Local Clock"
> >> +   help
> >> + Selecting this option causes the time stamps of printk() to be
> >> + stamped with the unadjusted hardware clock.
> >> +
> >> +   config PRINTK_TIME_BOOT
> >> +   bool "CLOCK_BOOTTIME"
> >> +   help
> >> + Selecting this option causes the time stamps of printk() to be
> >> + stamped with the adjusted boottime clock.
> >> +
> >> +   config PRINTK_TIME_MONO
> >> +   bool "CLOCK_MONOTONIC"
> >> +   help
> >> + Selecting this option causes the time stamps of printk() to be
> >> + stamped with the adjusted monotonic clock.
> >> +
> >> +   config PRINTK_TIME_REAL
> >> +   bool "CLOCK_REALTIME"
> >> +   help
> >> + Selecting this option causes the time stamps of printk() to be
> >> + stamped with the adjusted realtime clock.
> >> +
> >> +endchoice
> >> +
> >>  config PRINTK_TIME
> > 
> > Change that into something like:
> > 
> > config PRINTK_CLOCK
> > 
> > 
> >> -   bool "Show timing information on printks"
> >> +   int "Show time stamp information on printks"
> >> depends on PRINTK
> >> +   default 0 if PRINTK_TIME_DISABLE
> >> +   default 1 if PRINTK_TIME_LOCAL
> > 
> > And that into:
> > 
> > default 1 if PRINTK_TIME_LOCAL || PRINTK_TIME
> > 
> >> +   default 2 if PRINTK_TIME_BOOT
> >> +   default 3 if PRINTK_TIME_MONO
> >> +   default 4 if PRINTK_TIME_REAL
> >>  help
> >>Selecting this option causes time stamps of the printk()
> > 
> > Then the old PRINTK_TIME symbol will auto-convert into the new
> > equivalent.
> > 
> 
> I don't think there's an easy code way around this.  Essentially this Kconfig
> code boils down to properly evaluating
> 
> config PRINTK_CLOCK
>   default 1 if PRINTK_TIME
>   default 0
> 
> where there is no Kconfig entry for PRINTK_TIME.
> 
> If undefined CONFIG_PRINTK_TIME is used in a config, it is immediately
> scrubbed by the kconfig script so it doesn't "exist" when CONFIG_PRINTK_CLOCK
> is evaluated.  The result of that is CONFIG_PRINT_CLOCK=0.
> 
> I tried
> 
> config PRINTK_TIME
>   bool "old config option"
> 
> then I end up with both a CONFIG_PRINTK_CLOCK=1 and a CONFIG_PRINTK_TIME=y in
> the resulting config which is confusing.
> 
> I've debated using the other suggestion that Paul made but TBH (sorry
> Paul) it seems like I'm avoiding the real but noisy solution of
> 
>   s/PRINTK_TIME=y/PRINTK_TIME=1/g
> 
> I'm obviously open to other suggestions...

It is someone else's turn to provide a suggestion.  ;-)

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4] printk: Add monotonic, boottime, and realtime timestamps

[Paul E. McKenney]

On Mon, Aug 07, 2017 at 04:06:09PM -0400, Prarit Bhargava wrote:
> 
> 
> On 08/07/2017 02:47 PM, John Stultz wrote:
> > On Mon, Aug 7, 2017 at 11:04 AM, Prarit Bhargava  wrote:
> >> On 08/07/2017 12:52 PM, John Stultz wrote:
> >>> Still not quite following why you're updating all the defconfigs. I'd
> >>> make sure the Kconfig default settings are right, and leave updating
> >>> the defconfig to arch/device maintainers. It adds a lot of noise to
> >>> the patch.
> >>
> >> Hmm ... I thought it was up to the patch submitter to make sure that
> >> 'make defconfig' still worked?  Are you sure I can leave that broken?
> >>
> >> /me *really* doesn't want to get yelled at by every arch maintainer.
> > 
> > No. Don't break systems, but at the same time, can't you use the
> > default value in Kconfig to set it properly so the old defconfig
> > settings don't really matter?
> > 
> > Apologies if I've not followed the issue properly, but it is odd, as
> > I'm not sure I can think of a patch I've seen before that had so much
> > defconfig noise in it.  Again, I've not looked into it closely, so it
> > may just be my own ignorance, but it makes me suspect there is a
> > better way.
> > 
> 
> peterz?  Want to offer a suggestion?  The issue is that I'm changing a bool
> config option to an int and that impacts all the arch's defconfigs.  John 
> points
> out that this is a lot of churn and we're both wondering if there's a better 
> way
> to do the configs.

The usual approach is to keep the old bool Kconfig option, and add another
int Kconfig option that depends on the original one.  The tests for
the int value get a bit more complex, but one way to handle this is to
define a cpp macro something like the following:

#ifdef CONFIG_OLD_OPTION
#define CPP_NEW_OPTION 0
#else
#define CPP_NEW_OPTION CONFIG_NEW_OPTION
#endif

Then use CPP_NEW_OPTION, where zero means disabled and other numbers
select the available options.

Adjust to suit depending on what values mean what.

Another approach is to make the range of the new Kconfig option
depend on the old option:

config NEW_OPTION
int "your description here"
range 1 5 if OLD_OPTION
range 0 0 if !OLD_OPTION
default 0
help
  your help here

Again, adjust to suit depending on what values mean what.

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Sat, Jul 22, 2017 at 08:38:57AM +0900, Akira Yokosawa wrote:
> On 2017/07/20 16:07:14 -0700, Paul E. McKenney wrote:
> > On Fri, Jul 21, 2017 at 07:52:03AM +0900, Akira Yokosawa wrote:
> >> On 2017/07/20 14:42:34 -0700, Paul E. McKenney wrote:
> [...]
> >>> For the compilers I know about at the present time, yes.
> >>
> >> So if I respin the patch with the extern, would you still feel reluctant?
> > 
> > Yes, because I am not seeing how this change helps.  What is this telling
> > the reader that the original did not, and how does it help the reader
> > generate good concurrent code?
> 
> Well, what bothers me in the ">" version of two-CPU example is the
> explanation in memory-barriers.txt that follows:
> 
> > These two examples are the LB and WWC litmus tests from this paper:
> > http://www.cl.cam.ac.uk/users/pes20/ppc-supplemental/test6.pdf and this
> > site: https://www.cl.cam.ac.uk/~pes20/ppcmem/index.html.
> 
> I'm wondering if calling the ">" version as an "LB" litmus test is correct.
> Because it always results in "r1 == 0 && r2 == 0", 100%.

As it should, because nothing can become non-zero unless something was
already non-zero.  It is possible to create similarly single-outcome
tests with address dependencies.

But yes, converting to ">=" makes the stores unconditional, and thus
allows more outcomes.  Perhaps we need both?  Another approach is to
write a second value in an "else" statement, keeping the original ">".

I agree that some of these examples can be a bit hard on one's intuition,
but the plain fact is that when it comes to memory models, one's intuition
is not always one's friend.

> An LB litmus test with full memory barriers would be:
> 
>   CPU 0 CPU 1
>   ===   ===
>   r1 = READ_ONCE(x);r2 = READ_ONCE(y);
>   smp_mb(); smp_mb();
>   WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> 
>   assert(!(r1 == 1 && r2 == 1));
> 
> and this will result in either of
> 
> r1 == 0 && r2 == 0
> r1 == 0 && r2 == 1
> r1 == 1 && r2 == 0
> 
> but never "r1 == 1 && r2 == 1".

Agreed, because unlike the control-dependency example, the WRITE_ONCE()s
happen unconditionally.

> The difference in the behavior distracts me in reading this part
> of memory-barriers.txt.

Then it likely needs more explanation.

> Your priority seemed to be in reducing the chance of the "if" statement
> to be optimized away.  So I suggested to use "extern" as a compromise.

If the various tools accept the "extern", this might not be a bad thing
to do.

But what this really means is that I need to take another tilt at
the "volatile" windmill in the committee.

> Another way would be to express the ">=" version in a pseudo-asm form.
> 
>   CPU 0 CPU 1
>   ===   ===
>   r1 = LOAD x   r2 = LOAD y
>   if (r1 >= 0)  if (r2 >= 0)
> STORE y = 1   STORE x = 1
> 
>   assert(!(r1 == 1 && r2 == 1));
> 
> This should eliminate any concern of compiler optimization.
> In this final part of CONTROL DEPENDENCIES section, separating the
> problem of optimization and transitivity would clarify the point
> (at least for me).

The problem is that people really do use C-language control dependencies
in the Linux kernel, so we need to describe them.  Maybe someday it
will be necessary to convert them to asm, but I am hoping that we can
avoid that.

> Thoughts?

My hope is that the memory model can help here, but that will in any
case take time.

Thanx, Paul

> Regards, Akira
> 
> > 
> > Thanx, Paul
> > 
> >>  Regards, Akira
> >>
> >>>
> >>> The underlying problem is that the standard says almost nothing about what
> >>> volatile does.  I usually argue that it was intended to be used for MMIO,
> >>> so any optimization that would prevent a device driver from working must
> >>> be prohibited on volatiles.  A lot of people really don't like volatile,
> >>> and would like to eliminate it, and these people also aren't very happy
> >>> about any attempt to better define volatile.
> >>>
> >>> Keeps things entertaining.  ;-)
> >>>
> >>>   Thanx, Paul
> >>>
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Fri, Jul 21, 2017 at 08:24:40AM +0800, Boqun Feng wrote:
> On Thu, Jul 20, 2017 at 04:07:14PM -0700, Paul E. McKenney wrote:
> [...]
> > > 
> > > So if I respin the patch with the extern, would you still feel reluctant?
> > 
> > Yes, because I am not seeing how this change helps.  What is this telling
> > the reader that the original did not, and how does it help the reader
> > generate good concurrent code?
> 
> One thing I think we probably should do is to make READ_ONCE() semantics
> more clear, i.e. call it out that in our conceptual model for kernel
> programming we always rely on the compiler to be serious about the
> return value of READ_ONCE(). I didn't find the comment before
> READ_ONCE() or memory-barriers.txt talking about something similar.
> 
> Or am I the only one having this kinda semantics guarantee in mind?

That sounds like a good idea to me.  The C++ standards committee might
be reluctant to provide a good definition of "volatile", but we can at
least provide a definition of our own.  It should be possible to leverage
the need for "volatile" to support MMIO accesses, as there is general
agreement that this was and still is its main purpose.  Given those
guarantees, there is no reason we cannot apply them in other situations,
for example, interacting with irq handlers and preventing inappropriate
optimizations for concurrent code.

Even better, with tests to find compiler bugs in this area!

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Fri, Jul 21, 2017 at 07:52:03AM +0900, Akira Yokosawa wrote:
> On 2017/07/20 14:42:34 -0700, Paul E. McKenney wrote:
> > On Fri, Jul 21, 2017 at 06:12:56AM +0900, Akira Yokosawa wrote:
> >> On 2017/07/20 09:11:52AM -0700, Paul E. McKenney wrote:
> >>> On Thu, Jul 20, 2017 at 09:55:31PM +0900, Akira Yokosawa wrote:
> >>>> On 2017/07/20 14:47, Paul E. McKenney wrote:
> >>>>> On Thu, Jul 20, 2017 at 09:31:41AM +0800, Boqun Feng wrote:
> >>>>>> On Wed, Jul 19, 2017 at 02:56:02PM -0700, Paul E. McKenney wrote:
> >>>>>>> On Thu, Jul 20, 2017 at 06:33:26AM +0900, Akira Yokosawa wrote:
> >>>>>>>> On 2017/07/20 2:43, Paul E. McKenney wrote:
> >>>>>>>>> On Mon, Jul 17, 2017 at 05:24:42PM +0900, Akira Yokosawa wrote:
> >>>>>>>>>> >From b798b9b631e237d285aa8699da00bfb8ced33bea Mon Sep 17 00:00:00 
> >>>>>>>>>> >2001
> >>>>>>>>>> From: Akira Yokosawa <aki...@gmail.com>
> >>>>>>>>>> Date: Mon, 17 Jul 2017 16:25:33 +0900
> >>>>>>>>>> Subject: [PATCH] documentation: Fix two-CPU control-dependency 
> >>>>>>>>>> example
> >>>>>>>>>>
> >>>>>>>>>> In commit 5646f7acc95f ("memory-barriers: Fix control-ordering
> >>>>>>>>>> no-transitivity example"), the operator in "if" statement of
> >>>>>>>>>> the two-CPU example was modified from ">=" to ">".
> >>>>>>>>>> Now the example misses the point because there is no party
> >>>>>>>>>> who will modify "x" nor "y". So each CPU performs only the
> >>>>>>>>>> READ_ONCE().
> >>>>>>>>>>
> >>>>>>>>>> The point of this example is to use control dependency for 
> >>>>>>>>>> ordering,
> >>>>>>>>>> and the WRITE_ONCE() should always be executed.
> >>>>>>>>>>
> >>>>>>>>>> So it was correct prior to the above mentioned commit. Partial
> >>>>>>>>>> revert of the commit (with context adjustments regarding other
> >>>>>>>>>> changes thereafter) restores the point.
> >>>>>>>>>>
> >>>>>>>>>> Note that the three-CPU example demonstrating the lack of
> >>>>>>>>>> transitivity stands regardless of this partial revert.
> >>>>>>>>>>
> >>>>>>>>>> Signed-off-by: Akira Yokosawa <aki...@gmail.com>
> >>>>>>>>>
> >>>>>>>>> Hello, Akira,
> >>>>>>>>>
> >>>>>>>>> You are quite right that many compilers would generate 
> >>>>>>>>> straightforward
> >>>>>>>>> code for the code fragment below, and in that case, the assertion 
> >>>>>>>>> could
> >>>>>>>>> never trigger due to either TSO or control dependencies, depending 
> >>>>>>>>> on
> >>>>>>>>> the architecture this was running on.
> >>>>>>>>>
> >>>>>>>>> However, if the compiler was too smart for our good, it could figure
> >>>>>>>>> out that "x" and "y" only take on the values zero and one, so that
> >>>>>>>>> the "if" would always be taken.  At that point, the compiler could
> >>>>>>>>> simply ignore the "if" with the result shown below.
> >>>>>>>>>
> >>>>>>>>>> ---
> >>>>>>>>>>  Documentation/memory-barriers.txt | 2 +-
> >>>>>>>>>>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>>>>>>>>>
> >>>>>>>>>> diff --git a/Documentation/memory-barriers.txt 
> >>>>>>>>>> b/Documentation/memory-barriers.txt
> >>>>>>>>>> index c4ddfcd..c1ebe99 100644
> >>>>>>>>>> --- a/Documentation/memory-barriers.txt
> 

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Fri, Jul 21, 2017 at 06:12:56AM +0900, Akira Yokosawa wrote:
> On 2017/07/20 09:11:52AM -0700, Paul E. McKenney wrote:
> > On Thu, Jul 20, 2017 at 09:55:31PM +0900, Akira Yokosawa wrote:
> >> On 2017/07/20 14:47, Paul E. McKenney wrote:
> >>> On Thu, Jul 20, 2017 at 09:31:41AM +0800, Boqun Feng wrote:
> >>>> On Wed, Jul 19, 2017 at 02:56:02PM -0700, Paul E. McKenney wrote:
> >>>>> On Thu, Jul 20, 2017 at 06:33:26AM +0900, Akira Yokosawa wrote:
> >>>>>> On 2017/07/20 2:43, Paul E. McKenney wrote:
> >>>>>>> On Mon, Jul 17, 2017 at 05:24:42PM +0900, Akira Yokosawa wrote:
> >>>>>>>> >From b798b9b631e237d285aa8699da00bfb8ced33bea Mon Sep 17 00:00:00 
> >>>>>>>> >2001
> >>>>>>>> From: Akira Yokosawa <aki...@gmail.com>
> >>>>>>>> Date: Mon, 17 Jul 2017 16:25:33 +0900
> >>>>>>>> Subject: [PATCH] documentation: Fix two-CPU control-dependency 
> >>>>>>>> example
> >>>>>>>>
> >>>>>>>> In commit 5646f7acc95f ("memory-barriers: Fix control-ordering
> >>>>>>>> no-transitivity example"), the operator in "if" statement of
> >>>>>>>> the two-CPU example was modified from ">=" to ">".
> >>>>>>>> Now the example misses the point because there is no party
> >>>>>>>> who will modify "x" nor "y". So each CPU performs only the
> >>>>>>>> READ_ONCE().
> >>>>>>>>
> >>>>>>>> The point of this example is to use control dependency for ordering,
> >>>>>>>> and the WRITE_ONCE() should always be executed.
> >>>>>>>>
> >>>>>>>> So it was correct prior to the above mentioned commit. Partial
> >>>>>>>> revert of the commit (with context adjustments regarding other
> >>>>>>>> changes thereafter) restores the point.
> >>>>>>>>
> >>>>>>>> Note that the three-CPU example demonstrating the lack of
> >>>>>>>> transitivity stands regardless of this partial revert.
> >>>>>>>>
> >>>>>>>> Signed-off-by: Akira Yokosawa <aki...@gmail.com>
> >>>>>>>
> >>>>>>> Hello, Akira,
> >>>>>>>
> >>>>>>> You are quite right that many compilers would generate straightforward
> >>>>>>> code for the code fragment below, and in that case, the assertion 
> >>>>>>> could
> >>>>>>> never trigger due to either TSO or control dependencies, depending on
> >>>>>>> the architecture this was running on.
> >>>>>>>
> >>>>>>> However, if the compiler was too smart for our good, it could figure
> >>>>>>> out that "x" and "y" only take on the values zero and one, so that
> >>>>>>> the "if" would always be taken.  At that point, the compiler could
> >>>>>>> simply ignore the "if" with the result shown below.
> >>>>>>>
> >>>>>>>> ---
> >>>>>>>>  Documentation/memory-barriers.txt | 2 +-
> >>>>>>>>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>>>>>>>
> >>>>>>>> diff --git a/Documentation/memory-barriers.txt 
> >>>>>>>> b/Documentation/memory-barriers.txt
> >>>>>>>> index c4ddfcd..c1ebe99 100644
> >>>>>>>> --- a/Documentation/memory-barriers.txt
> >>>>>>>> +++ b/Documentation/memory-barriers.txt
> >>>>>>>> @@ -851,7 +851,7 @@ demonstrated by two related examples, with the 
> >>>>>>>> initial values of
> >>>>>>>>  CPU 0 CPU 1
> >>>>>>>>  ===   ===
> >>>>>>>>  r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> >>>>>>>> -if (r1 > 0)   if (r2 > 0)
> >>>>>>>> +if (r1 >= 0)  if (r2 >= 0)
> >>>>>>>>  

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Thu, Jul 20, 2017 at 09:55:31PM +0900, Akira Yokosawa wrote:
> On 2017/07/20 14:47, Paul E. McKenney wrote:
> > On Thu, Jul 20, 2017 at 09:31:41AM +0800, Boqun Feng wrote:
> >> On Wed, Jul 19, 2017 at 02:56:02PM -0700, Paul E. McKenney wrote:
> >>> On Thu, Jul 20, 2017 at 06:33:26AM +0900, Akira Yokosawa wrote:
> >>>> On 2017/07/20 2:43, Paul E. McKenney wrote:
> >>>>> On Mon, Jul 17, 2017 at 05:24:42PM +0900, Akira Yokosawa wrote:
> >>>>>> >From b798b9b631e237d285aa8699da00bfb8ced33bea Mon Sep 17 00:00:00 2001
> >>>>>> From: Akira Yokosawa <aki...@gmail.com>
> >>>>>> Date: Mon, 17 Jul 2017 16:25:33 +0900
> >>>>>> Subject: [PATCH] documentation: Fix two-CPU control-dependency example
> >>>>>>
> >>>>>> In commit 5646f7acc95f ("memory-barriers: Fix control-ordering
> >>>>>> no-transitivity example"), the operator in "if" statement of
> >>>>>> the two-CPU example was modified from ">=" to ">".
> >>>>>> Now the example misses the point because there is no party
> >>>>>> who will modify "x" nor "y". So each CPU performs only the
> >>>>>> READ_ONCE().
> >>>>>>
> >>>>>> The point of this example is to use control dependency for ordering,
> >>>>>> and the WRITE_ONCE() should always be executed.
> >>>>>>
> >>>>>> So it was correct prior to the above mentioned commit. Partial
> >>>>>> revert of the commit (with context adjustments regarding other
> >>>>>> changes thereafter) restores the point.
> >>>>>>
> >>>>>> Note that the three-CPU example demonstrating the lack of
> >>>>>> transitivity stands regardless of this partial revert.
> >>>>>>
> >>>>>> Signed-off-by: Akira Yokosawa <aki...@gmail.com>
> >>>>>
> >>>>> Hello, Akira,
> >>>>>
> >>>>> You are quite right that many compilers would generate straightforward
> >>>>> code for the code fragment below, and in that case, the assertion could
> >>>>> never trigger due to either TSO or control dependencies, depending on
> >>>>> the architecture this was running on.
> >>>>>
> >>>>> However, if the compiler was too smart for our good, it could figure
> >>>>> out that "x" and "y" only take on the values zero and one, so that
> >>>>> the "if" would always be taken.  At that point, the compiler could
> >>>>> simply ignore the "if" with the result shown below.
> >>>>>
> >>>>>> ---
> >>>>>>  Documentation/memory-barriers.txt | 2 +-
> >>>>>>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>>>>>
> >>>>>> diff --git a/Documentation/memory-barriers.txt 
> >>>>>> b/Documentation/memory-barriers.txt
> >>>>>> index c4ddfcd..c1ebe99 100644
> >>>>>> --- a/Documentation/memory-barriers.txt
> >>>>>> +++ b/Documentation/memory-barriers.txt
> >>>>>> @@ -851,7 +851,7 @@ demonstrated by two related examples, with the 
> >>>>>> initial values of
> >>>>>>CPU 0 CPU 1
> >>>>>>===   ===
> >>>>>>r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> >>>>>> -  if (r1 > 0)   if (r2 > 0)
> >>>>>> +  if (r1 >= 0)  if (r2 >= 0)
> >>>>>>  WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> >>>>>>
> >>>>>>assert(!(r1 == 1 && r2 == 1));
> >>>>>
> >>>>> Original program:
> >>>>>
> >>>>> CPU 0 CPU 1
> >>>>> ===   ===
> >>>>> r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> >>>>> if (r1 >= 0)  if (r2 >= 0)
> >>>>>   WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> >>>>>
> >>>>> assert(!(r1 ==

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Thu, Jul 20, 2017 at 02:14:34PM +0800, Boqun Feng wrote:
> On Wed, Jul 19, 2017 at 10:47:04PM -0700, Paul E. McKenney wrote:
> [...]
> > > Hi Paul,
> > > 
> > > I know the compiler could optimize atomics in very interesting ways, but
> > > this case is about volatile, so I guess our case is still fine? ;-)
> > 
> > Hello, Boqun,
> > 
> > When I asked that question, the answer I got was "the compiler must
> > emit the load instruction, but is under no obligation to actually use the
> > value loaded".
> > 
> > I don't happen to like that answer, by the way.  ;-)
> > 
> 
> Me neither, seems to me the kernel happens to work well at
> compiler-optimization's mercy ;-/
> 
> With claim like that, compiler could do optimization as turning:
> 
>   struct task_struct *owner;
> 
>   for (;;) {
>   owner = READ_ONCE(lock->owner);
>   if (owner && !mutex_spin_on_owner(lock, owner))
>   break;
>   /* ... */
> 
> into:
> 
>   struct task_struct *owner;
> 
>   owner = READ_ONCE(lock->owner);
> 
>   for (;;READ_ONCE(lock->owner)) {
>   if (owner && !mutex_spin_on_owner(lock, owner))
>   break;
>   /* ... */
> 
> Because the load executed in every loop, and they just happen to choose
> not to use the values. And this is within their rights!

Well, this is one reason that I attend standards-committee meetings.
As does Will Deacon.  That way, there is someone there to protest when
people argue that the above behavior is just fine.  ;-)

Thanx, Paul

> Regards,
> Boqun
> 
> > Thanx, Paul
> > 
> > > > http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0062r1.html
> > > > 
> > > 
> > > Great material to wake up mind in the morning! Thanks.
> > > 
> > > Regards,
> > > Boqun
> > > 
> > > > What are your thoughts on this?
> > > > 
> > > > Thanx, Paul
> > > > 
> > > > > Thanks, Akira
> > > > > 
> > > > > > That said, I very much welcome critical reviews of 
> > > > > > memory-barriers.txt,
> > > > > > so please do feel free to continue doing that!
> > > > > > 
> > > > > > Thanx, Paul
> > > > > > 
> > > > > > 
> > > > > 
> > > > 
> > > 
> > 
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Thu, Jul 20, 2017 at 09:31:41AM +0800, Boqun Feng wrote:
> On Wed, Jul 19, 2017 at 02:56:02PM -0700, Paul E. McKenney wrote:
> > On Thu, Jul 20, 2017 at 06:33:26AM +0900, Akira Yokosawa wrote:
> > > On 2017/07/20 2:43, Paul E. McKenney wrote:
> > > > On Mon, Jul 17, 2017 at 05:24:42PM +0900, Akira Yokosawa wrote:
> > > >> >From b798b9b631e237d285aa8699da00bfb8ced33bea Mon Sep 17 00:00:00 2001
> > > >> From: Akira Yokosawa <aki...@gmail.com>
> > > >> Date: Mon, 17 Jul 2017 16:25:33 +0900
> > > >> Subject: [PATCH] documentation: Fix two-CPU control-dependency example
> > > >>
> > > >> In commit 5646f7acc95f ("memory-barriers: Fix control-ordering
> > > >> no-transitivity example"), the operator in "if" statement of
> > > >> the two-CPU example was modified from ">=" to ">".
> > > >> Now the example misses the point because there is no party
> > > >> who will modify "x" nor "y". So each CPU performs only the
> > > >> READ_ONCE().
> > > >>
> > > >> The point of this example is to use control dependency for ordering,
> > > >> and the WRITE_ONCE() should always be executed.
> > > >>
> > > >> So it was correct prior to the above mentioned commit. Partial
> > > >> revert of the commit (with context adjustments regarding other
> > > >> changes thereafter) restores the point.
> > > >>
> > > >> Note that the three-CPU example demonstrating the lack of
> > > >> transitivity stands regardless of this partial revert.
> > > >>
> > > >> Signed-off-by: Akira Yokosawa <aki...@gmail.com>
> > > > 
> > > > Hello, Akira,
> > > > 
> > > > You are quite right that many compilers would generate straightforward
> > > > code for the code fragment below, and in that case, the assertion could
> > > > never trigger due to either TSO or control dependencies, depending on
> > > > the architecture this was running on.
> > > > 
> > > > However, if the compiler was too smart for our good, it could figure
> > > > out that "x" and "y" only take on the values zero and one, so that
> > > > the "if" would always be taken.  At that point, the compiler could
> > > > simply ignore the "if" with the result shown below.
> > > > 
> > > >> ---
> > > >>  Documentation/memory-barriers.txt | 2 +-
> > > >>  1 file changed, 1 insertion(+), 1 deletion(-)
> > > >>
> > > >> diff --git a/Documentation/memory-barriers.txt 
> > > >> b/Documentation/memory-barriers.txt
> > > >> index c4ddfcd..c1ebe99 100644
> > > >> --- a/Documentation/memory-barriers.txt
> > > >> +++ b/Documentation/memory-barriers.txt
> > > >> @@ -851,7 +851,7 @@ demonstrated by two related examples, with the 
> > > >> initial values of
> > > >>CPU 0 CPU 1
> > > >>===   ===
> > > >>r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> > > >> -  if (r1 > 0)   if (r2 > 0)
> > > >> +  if (r1 >= 0)  if (r2 >= 0)
> > > >>  WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> > > >>
> > > >>assert(!(r1 == 1 && r2 == 1));
> > > > 
> > > > Original program:
> > > > 
> > > > CPU 0 CPU 1
> > > > ===   ===
> > > > r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> > > > if (r1 >= 0)  if (r2 >= 0)
> > > >   WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> > > > 
> > > > assert(!(r1 == 1 && r2 == 1));
> > > > 
> > > > Enthusiastically optimized program:
> > > > 
> > > > CPU 0 CPU 1
> > > > ===   ===
> > > > r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> > > > WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> > > > 
> > > > assert(!(r1 == 1 && r2 == 1));
> > > > 
>

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Thu, Jul 20, 2017 at 06:33:26AM +0900, Akira Yokosawa wrote:
> On 2017/07/20 2:43, Paul E. McKenney wrote:
> > On Mon, Jul 17, 2017 at 05:24:42PM +0900, Akira Yokosawa wrote:
> >> >From b798b9b631e237d285aa8699da00bfb8ced33bea Mon Sep 17 00:00:00 2001
> >> From: Akira Yokosawa <aki...@gmail.com>
> >> Date: Mon, 17 Jul 2017 16:25:33 +0900
> >> Subject: [PATCH] documentation: Fix two-CPU control-dependency example
> >>
> >> In commit 5646f7acc95f ("memory-barriers: Fix control-ordering
> >> no-transitivity example"), the operator in "if" statement of
> >> the two-CPU example was modified from ">=" to ">".
> >> Now the example misses the point because there is no party
> >> who will modify "x" nor "y". So each CPU performs only the
> >> READ_ONCE().
> >>
> >> The point of this example is to use control dependency for ordering,
> >> and the WRITE_ONCE() should always be executed.
> >>
> >> So it was correct prior to the above mentioned commit. Partial
> >> revert of the commit (with context adjustments regarding other
> >> changes thereafter) restores the point.
> >>
> >> Note that the three-CPU example demonstrating the lack of
> >> transitivity stands regardless of this partial revert.
> >>
> >> Signed-off-by: Akira Yokosawa <aki...@gmail.com>
> > 
> > Hello, Akira,
> > 
> > You are quite right that many compilers would generate straightforward
> > code for the code fragment below, and in that case, the assertion could
> > never trigger due to either TSO or control dependencies, depending on
> > the architecture this was running on.
> > 
> > However, if the compiler was too smart for our good, it could figure
> > out that "x" and "y" only take on the values zero and one, so that
> > the "if" would always be taken.  At that point, the compiler could
> > simply ignore the "if" with the result shown below.
> > 
> >> ---
> >>  Documentation/memory-barriers.txt | 2 +-
> >>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>
> >> diff --git a/Documentation/memory-barriers.txt 
> >> b/Documentation/memory-barriers.txt
> >> index c4ddfcd..c1ebe99 100644
> >> --- a/Documentation/memory-barriers.txt
> >> +++ b/Documentation/memory-barriers.txt
> >> @@ -851,7 +851,7 @@ demonstrated by two related examples, with the initial 
> >> values of
> >>CPU 0 CPU 1
> >>===   ===
> >>r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> >> -  if (r1 > 0)   if (r2 > 0)
> >> +  if (r1 >= 0)  if (r2 >= 0)
> >>  WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> >>
> >>assert(!(r1 == 1 && r2 == 1));
> > 
> > Original program:
> > 
> > CPU 0 CPU 1
> > ===   ===
> > r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> > if (r1 >= 0)  if (r2 >= 0)
> >   WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> > 
> > assert(!(r1 == 1 && r2 == 1));
> > 
> > Enthusiastically optimized program:
> > 
> > CPU 0 CPU 1
> > ===   ===
> > r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> > WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> > 
> > assert(!(r1 == 1 && r2 == 1));
> > 
> > This optimized version could trigger the assertion.
> > 
> > So we do need to stick with the ">" comparison.
> 
> Well but,
> 
> Current example:
> 
>   CPU 0 CPU 1
>   ===   ===
>   r1 = READ_ONCE(x);r2 = READ_ONCE(y);
>   if (r1 > 0)   if (r2 > 0)
> WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> 
>   assert(!(r1 == 1 && r2 == 1));
> 
> Such a clever compiler might be able to prove that "x" and "y"
> are never modified and end up in the following:
> 
>   CPU 0 CPU 1
>   ===   ===
>   r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> 
>   assert(!(r1 == 1 && r2 == 1));
> 
> This means it is impossible to describe this example in C,
> doesn't it?

That is a matter of some

Re: [PATCH] documentation: Fix two-CPU control-dependency example

[Paul E. McKenney]

On Mon, Jul 17, 2017 at 05:24:42PM +0900, Akira Yokosawa wrote:
> >From b798b9b631e237d285aa8699da00bfb8ced33bea Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa 
> Date: Mon, 17 Jul 2017 16:25:33 +0900
> Subject: [PATCH] documentation: Fix two-CPU control-dependency example
> 
> In commit 5646f7acc95f ("memory-barriers: Fix control-ordering
> no-transitivity example"), the operator in "if" statement of
> the two-CPU example was modified from ">=" to ">".
> Now the example misses the point because there is no party
> who will modify "x" nor "y". So each CPU performs only the
> READ_ONCE().
> 
> The point of this example is to use control dependency for ordering,
> and the WRITE_ONCE() should always be executed.
> 
> So it was correct prior to the above mentioned commit. Partial
> revert of the commit (with context adjustments regarding other
> changes thereafter) restores the point.
> 
> Note that the three-CPU example demonstrating the lack of
> transitivity stands regardless of this partial revert.
> 
> Signed-off-by: Akira Yokosawa 

Hello, Akira,

You are quite right that many compilers would generate straightforward
code for the code fragment below, and in that case, the assertion could
never trigger due to either TSO or control dependencies, depending on
the architecture this was running on.

However, if the compiler was too smart for our good, it could figure
out that "x" and "y" only take on the values zero and one, so that
the "if" would always be taken.  At that point, the compiler could
simply ignore the "if" with the result shown below.

> ---
>  Documentation/memory-barriers.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index c4ddfcd..c1ebe99 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -851,7 +851,7 @@ demonstrated by two related examples, with the initial 
> values of
>   CPU 0 CPU 1
>   ===   ===
>   r1 = READ_ONCE(x);r2 = READ_ONCE(y);
> - if (r1 > 0)   if (r2 > 0)
> + if (r1 >= 0)  if (r2 >= 0)
> WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);
> 
>   assert(!(r1 == 1 && r2 == 1));

Original program:

CPU 0 CPU 1
===   ===
r1 = READ_ONCE(x);r2 = READ_ONCE(y);
if (r1 >= 0)  if (r2 >= 0)
  WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);

assert(!(r1 == 1 && r2 == 1));

Enthusiastically optimized program:

CPU 0 CPU 1
===   ===
r1 = READ_ONCE(x);r2 = READ_ONCE(y);
WRITE_ONCE(y, 1); WRITE_ONCE(x, 1);

assert(!(r1 == 1 && r2 == 1));

This optimized version could trigger the assertion.

So we do need to stick with the ">" comparison.

That said, I very much welcome critical reviews of memory-barriers.txt,
so please do feel free to continue doing that!

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs: Do not include from kernel/rcu/srcu.c

[Paul E. McKenney]

On Tue, Jul 04, 2017 at 01:26:47PM -0600, Jonathan Corbet wrote:
> That file went away with commit bd8cc5a062f4 (srcu: Remove Classic SRCU)
> during the 4.13 merge window, leading to errors like:
> 
>   Error: Cannot open file ./kernel/rcu/srcu.c
> 
> during the docs build.
> 
> Reported-by: Linus Torvalds <torva...@linux-foundation.org>
> Signed-off-by: Jonathan Corbet <cor...@lwn.net>

Acked-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

> ---
> Probably we should really put the RCU documentation into the core-API
> manual, but that's a change for another day.

Would it make sense to have checkpatch.pl to point to these files as well as
to MAINTAINERS when files are added or removed?  I freely confess that I
have only rarely updated the kernel-doc files.

Here are the list of RCU-related files containing kernel-doc headers:

$ grep -l "/\*\*" include/linux/*rcu* kernel/rcu/*
include/linux/rculist_bl.h
include/linux/rculist.h
include/linux/rculist_nulls.h
include/linux/rcupdate.h
include/linux/rcupdate_wait.h
include/linux/rcu_sync.h
include/linux/rcutree.h
include/linux/srcu.h
kernel/rcu/srcutree.c
kernel/rcu/sync.c
kernel/rcu/tree.c
kernel/rcu/tree_exp.h
kernel/rcu/tree_plugin.h
kernel/rcu/update.c

>  Documentation/driver-api/basics.rst | 3 ---
>  1 file changed, 3 deletions(-)
> 
> diff --git a/Documentation/driver-api/basics.rst 
> b/Documentation/driver-api/basics.rst
> index 472e7a664d13..ab82250c7727 100644
> --- a/Documentation/driver-api/basics.rst
> +++ b/Documentation/driver-api/basics.rst
> @@ -106,9 +106,6 @@ Kernel utility functions
>  .. kernel-doc:: kernel/sys.c
> :export:
> 
> -.. kernel-doc:: kernel/rcu/srcu.c
> -   :export:
> -
>  .. kernel-doc:: kernel/rcu/tree.c
> :export:

So something like this, ignoring the Documentation/driver-api/basics.rst
cleanup that would be needed (for the moment)?

Thanx, Paul

--------

commit 565fde68a1d3d77386ddc0e6881cf11b52ca2578
Author: Paul E. McKenney <paul...@linux.vnet.ibm.com>
Date:   Tue Jul 4 14:42:20 2017 -0700

doc: Add RCU files to docbook-generation files

Suggested-by: Jonathan Corbet <cor...@lwn.net>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

diff --git a/Documentation/core-api/kernel-api.rst 
b/Documentation/core-api/kernel-api.rst
index 9ec8488319dc..252452dc5ffd 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -344,3 +344,52 @@ codecs, and devices with strict requirements for interface 
clocking.
 
 .. kernel-doc:: include/linux/clk.h
:internal:
+
+Synchronization Primitives
+==
+
+Read-Copy Update (RCU)
+--
+
+.. kernel-doc:: include/linux/rcupdate.h
+   :external:
+
+.. kernel-doc:: include/linux/rcupdate_wait.h
+   :external:
+
+.. kernel-doc:: include/linux/rcutree.h
+   :external:
+
+.. kernel-doc:: kernel/rcu/tree.c
+   :external:
+
+.. kernel-doc:: kernel/rcu/tree_plugin.h
+   :external:
+
+.. kernel-doc:: kernel/rcu/tree_exp.h
+   :external:
+
+.. kernel-doc:: kernel/rcu/update.c
+   :external:
+
+.. kernel-doc:: include/linux/srcu.h
+   :external:
+
+.. kernel-doc:: kernel/rcu/srcutree.c
+   :external:
+
+.. kernel-doc:: include/linux/rculist_bl.h
+   :external:
+
+.. kernel-doc:: include/linux/rculist.h
+   :external:
+
+.. kernel-doc:: include/linux/rculist_nulls.h
+   :external:
+
+.. kernel-doc:: include/linux/rcu_sync.h
+   :external:
+
+.. kernel-doc:: kernel/rcu/sync.c
+   :external:
+

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: atomic_ops.txt is core-api/atomic_ops.rst

[Paul E. McKenney]

On Fri, Jun 23, 2017 at 01:31:39PM -0700, Palmer Dabbelt wrote:
> I was reading the memory barries documentation in order to make sure the
> RISC-V barries were correct, and I found a broken link to the atomic
> operations documentation.
> 
> Signed-off-by: Palmer Dabbelt <pal...@dabbelt.com>
> Acked-by: Will Deacon <will.dea...@arm.com>

Good catch!

Acked-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

> ---
>  Documentation/memory-barriers.txt | 10 +-
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index 732f10ea382e..f1c9eaa45a57 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -498,11 +498,11 @@ And a couple of implicit varieties:
>   This means that ACQUIRE acts as a minimal "acquire" operation and
>   RELEASE acts as a minimal "release" operation.
> 
> -A subset of the atomic operations described in atomic_ops.txt have ACQUIRE
> -and RELEASE variants in addition to fully-ordered and relaxed (no barrier
> -semantics) definitions.  For compound atomics performing both a load and a
> -store, ACQUIRE semantics apply only to the load and RELEASE semantics apply
> -only to the store portion of the operation.
> +A subset of the atomic operations described in core-api/atomic_ops.rst have
> +ACQUIRE and RELEASE variants in addition to fully-ordered and relaxed (no
> +barrier semantics) definitions.  For compound atomics performing both a load
> +and a store, ACQUIRE semantics apply only to the load and RELEASE semantics
> +apply only to the store portion of the operation.
> 
>  Memory barriers are only required where there's a possibility of interaction
>  between two CPUs or between a CPU and a device.  If it can be guaranteed that
> -- 
> 2.13.0
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs: typo in Documentation/memory-barriers.txt

[Paul E. McKenney]

On Thu, Apr 20, 2017 at 11:03:36AM +0200, Stan Drozd wrote:
> So here we are, this is my first contribution. I looked through the file with
> ":set spell" and this seems like the only real typo. It's not much, but I've 
> got
> more coming.
> 
> Stan
> 
> Signed-off-by: Stan Drozd <drozdzi...@gmail.com>

Thank you, queued for 4.13 (or whenever Jon wants to take it).  Good
show on getting your first patch posted!

I reworked your subject line and commit log, please see below (and
please let me know if my reworking was in any way problematic).
The word following the ":" on the subject line must be capitalized,
and the subject line should describe the change rather than the bug.

The body of the commit log is almost optional for this type of fix,
but if present it should describe the bug and fix.

Thanx, Paul



commit 79b64f114cbfd5daa6117c60c38b1689f6e80ee5
Author: Stan Drozd <drozdzi...@gmail.com>
Date:   Thu Apr 20 11:03:36 2017 +0200

docs: Fix typo in Documentation/memory-barriers.txt

This commit changes "architecure" to the correct spelling,
"architecture".
    
    Signed-off-by: Stan Drozd <drozdzi...@gmail.com>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index 08329cb857ed..6805accbba4f 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -27,7 +27,7 @@ The purpose of this document is twofold:
  (2) to provide a guide as to how to use the barriers that are available.
 
 Note that an architecture can provide more than the minimum requirement
-for any particular barrier, but if the architecure provides less than
+for any particular barrier, but if the architecture provides less than
 that, that architecture is incorrect.
 
 Note also that it is possible that a barrier may be a no-op for an

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/1] doc: Update control-dependencies section of memory-barriers.txt

[Paul E. McKenney]

On Fri, Apr 07, 2017 at 10:15:07AM +0100, Will Deacon wrote:
> On Fri, Apr 07, 2017 at 02:37:36PM +0800, pierre Kuo wrote:
> > for below example, if MAX is defined to be 1, then the compiler knows (Q
> > % MAX) is equal to zero.
> > so compiler will transform the "else" part of code.
> > 
> > q = READ_ONCE(a);
> > if (q % MAX) {
> > WRITE_ONCE(b, 1);
> > do_something();
> > } else {
> > WRITE_ONCE(b, 2);
> > do_something_else();
> > }
> > 
> > So we modify the original document as below:
> > 
> > q = READ_ONCE(a);
> > -   WRITE_ONCE(b, 1);
> > +   WRITE_ONCE(b, 2);
> > do_something_else();
> > 
> > Signed-off-by: pierre Kuo 
> > ---
> >  Documentation/memory-barriers.txt | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> Yup, looks like a typo since the do_something_else() part is correct.
> Thanks for the fix:
> 
> Acked-by: Will Deacon 
> 
> I'm assuming somebody will pick this up.

I have queued it with you ack, thank you both!

Thanx, Paul

> Will
> 
> > diff --git a/Documentation/memory-barriers.txt 
> > b/Documentation/memory-barriers.txt
> > index d2b0a8d..08329cb 100644
> > --- a/Documentation/memory-barriers.txt
> > +++ b/Documentation/memory-barriers.txt
> > @@ -768,7 +768,7 @@ equal to zero, in which case the compiler is within its 
> > rights to
> >  transform the above code into the following:
> >  
> > q = READ_ONCE(a);
> > -   WRITE_ONCE(b, 1);
> > +   WRITE_ONCE(b, 2);
> > do_something_else();
> >  
> >  Given this transformation, the CPU is not required to respect the ordering
> > -- 
> > 1.9.1
> > 
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: circular-buffers: use READ_ONCE()

[Paul E. McKenney]

On Wed, Nov 16, 2016 at 11:12:49AM +, Mark Rutland wrote:
> While the {READ,WRITE}_ONCE() macros should be used in preference to
> ACCESS_ONCE(), the circular buffer documentation uses the latter
> exclusively.
> 
> To point people in the right direction, and as a step towards the
> eventual removal of ACCESS_ONCE(), update the documentation to use
> READ_ONCE(), as ACCESS_ONCE() is only used in a reader context in the
> circular buffer documentation.
> 
> Signed-off-by: Mark Rutland <mark.rutl...@arm.com>
> Cc: David Howells <dhowe...@redhat.com>
> Cc: Jonathan Corbet <cor...@lwn.net>
> Cc: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> Cc: linux-doc@vger.kernel.org
> Cc: linux-ker...@vger.kernel.org

Acked-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

> ---
>  Documentation/circular-buffers.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/circular-buffers.txt 
> b/Documentation/circular-buffers.txt
> index 88951b1..4a824d2 100644
> --- a/Documentation/circular-buffers.txt
> +++ b/Documentation/circular-buffers.txt
> @@ -161,7 +161,7 @@ The producer will look something like this:
> 
>   unsigned long head = buffer->head;
>   /* The spin_unlock() and next spin_lock() provide needed ordering. */
> - unsigned long tail = ACCESS_ONCE(buffer->tail);
> + unsigned long tail = READ_ONCE(buffer->tail);
> 
>   if (CIRC_SPACE(head, tail, buffer->size) >= 1) {
>   /* insert one item into the buffer */
> @@ -222,7 +222,7 @@ This will instruct the CPU to make sure the index is up 
> to date before reading
>  the new item, and then it shall make sure the CPU has finished reading the 
> item
>  before it writes the new tail pointer, which will erase the item.
> 
> -Note the use of ACCESS_ONCE() and smp_load_acquire() to read the
> +Note the use of READ_ONCE() and smp_load_acquire() to read the
>  opposition index.  This prevents the compiler from discarding and
>  reloading its cached value - which some compilers will do across
>  smp_read_barrier_depends().  This isn't strictly needed if you can
> -- 
> 1.9.1
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: atomic_ops: use {READ,WRITE}_ONCE()

[Paul E. McKenney]

On Wed, Nov 16, 2016 at 11:13:59AM +, Mark Rutland wrote:
> While the {READ,WRITE}_ONCE() macros should be used in preference to
> ACCESS_ONCE(), the atomic documentation uses the latter exclusively.
> 
> To point people in the right direction, and as a step towards the
> eventual removal of ACCESS_ONCE(), update the documentation to use the
> {READ,WRITE}_ONCE() macros as appropriate.
> 
> Signed-off-by: Mark Rutland <mark.rutl...@arm.com>
> Cc: Boqun Feng <boqun.f...@gmail.com>
> Cc: Jonathan Corbet <cor...@lwn.net>
> Cc: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> Cc: Peter Zijlstra <pet...@infradead.org>
> Cc: Will Deacon <will.dea...@arm.com>
> Cc: linux-doc@vger.kernel.org
> Cc: linux-ker...@vger.kernel.org

Acked-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

> ---
>  Documentation/atomic_ops.txt | 18 +-
>  1 file changed, 9 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt
> index c9d1cac..a1b9a54 100644
> --- a/Documentation/atomic_ops.txt
> +++ b/Documentation/atomic_ops.txt
> @@ -90,10 +90,10 @@ compiler optimizes the section accessing atomic_t 
> variables.
> 
>  Properly aligned pointers, longs, ints, and chars (and unsigned
>  equivalents) may be atomically loaded from and stored to in the same
> -sense as described for atomic_read() and atomic_set().  The ACCESS_ONCE()
> -macro should be used to prevent the compiler from using optimizations
> -that might otherwise optimize accesses out of existence on the one hand,
> -or that might create unsolicited accesses on the other.
> +sense as described for atomic_read() and atomic_set().  The READ_ONCE()
> +and WRITE_ONCE() macros should be used to prevent the compiler from using
> +optimizations that might otherwise optimize accesses out of existence on
> +the one hand, or that might create unsolicited accesses on the other.
> 
>  For example consider the following code:
> 
> @@ -112,7 +112,7 @@ the following:
>  If you don't want the compiler to do this (and you probably don't), then
>  you should use something like the following:
> 
> - while (ACCESS_ONCE(a) < 0)
> + while (READ_ONCE(a) < 0)
>   do_something();
> 
>  Alternatively, you could place a barrier() call in the loop.
> @@ -141,7 +141,7 @@ of registers: reloading from variable a could save a 
> flush to the
>  stack and later reload.  To prevent the compiler from attacking your
>  code in this manner, write the following:
> 
> - tmp_a = ACCESS_ONCE(a);
> + tmp_a = READ_ONCE(a);
>   do_something_with(tmp_a);
>   do_something_else_with(tmp_a);
> 
> @@ -166,14 +166,14 @@ that expected b to never have the value 42 if a was 
> zero.  To prevent
>  the compiler from doing this, write something like:
> 
>   if (a)
> - ACCESS_ONCE(b) = 9;
> + WRITE_ONCE(b, 9);
>   else
> - ACCESS_ONCE(b) = 42;
> + WRITE_ONCE(b, 42);
> 
>  Don't even -think- about doing this without proper use of memory barriers,
>  locks, or atomic operations if variable a can change at runtime!
> 
> -*** WARNING: ACCESS_ONCE() DOES NOT IMPLY A BARRIER! ***
> +*** WARNING: READ_ONCE() OR WRITE_ONCE() DO NOT IMPLY A BARRIER! ***
> 
>  Now, we move onto the atomic operation interfaces typically implemented with
>  the help of assembly code.
> -- 
> 1.9.1
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/RCU: Fix minor typo

[Paul E. McKenney]

On Tue, Oct 18, 2016 at 12:43:24AM -0700, Josh Triplett wrote:
> On Tue, Oct 18, 2016 at 12:54:03AM -0400, Pranith Kumar wrote:
> > deference should actually be dereference.
> > 
> > Signed-off-by: Pranith Kumar 
> 
> Good catch.
> 
> Reviewed-by: Josh Triplett 

Applied, thank you both!

Thanx, Paul

> >  Documentation/RCU/whatisRCU.txt | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/RCU/whatisRCU.txt 
> > b/Documentation/RCU/whatisRCU.txt
> > index 2044227..5cbd8b2 100644
> > --- a/Documentation/RCU/whatisRCU.txt
> > +++ b/Documentation/RCU/whatisRCU.txt
> > @@ -237,7 +237,7 @@ rcu_dereference()
> >  
> > The reader uses rcu_dereference() to fetch an RCU-protected
> > pointer, which returns a value that may then be safely
> > -   dereferenced.  Note that rcu_deference() does not actually
> > +   dereferenced.  Note that rcu_dereference() does not actually
> > dereference the pointer, instead, it protects the pointer for
> > later dereferencing.  It also executes any needed memory-barrier
> > instructions for a given CPU architecture.  Currently, only Alpha
> > -- 
> > 2.10.1
> > 
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v15 04/13] task_isolation: add initial support

[Paul E. McKenney]

On Tue, Sep 27, 2016 at 04:22:20PM +0200, Frederic Weisbecker wrote:
> On Fri, Sep 02, 2016 at 10:28:00AM -0700, Andy Lutomirski wrote:
> > 
> > Unless I'm missing something (which is reasonably likely), couldn't
> > the isolation code just force or require rcu_nocbs on the isolated
> > CPUs to avoid this problem entirely.
> 
> rcu_nocb is already implied by nohz_full. Which means that RCU callbacks
> are offlined outside the nohz_full set of CPUs.

Indeed, at boot time, RCU makes any nohz_full CPU also be a rcu_nocb
CPU.

> > I admit I still don't understand why the RCU context tracking code
> > can't just run the callback right away instead of waiting however many
> > microseconds in general.  I feel like paulmck has explained it to me
> > at least once, but that doesn't mean I remember the answer.
> 
> The RCU context tracking doesn't take care of callbacks. It's only there
> to tell the RCU core whether the CPU runs code that may or may not run
> RCU read side critical sections. This is assumed by "kernel may use RCU,
> userspace can't".

And RCU has to wait for read-side critical sections to complete before
invoking callbacks.

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] documentation: fix broken lkml archive links in RCU requirements

[Paul E. McKenney]

On Thu, Sep 15, 2016 at 09:18:28AM -0400, Steven Rostedt wrote:
> On Thu, 15 Sep 2016 14:17:06 +0200
> Michael Opdenacker  wrote:
> 
> > Fix 4 LKML archive links that became broken
> > (issue with https://lkml.kernel.org/g/ redirection links)
> > 
> > Signed-off-by: Michael Opdenacker 
> > ---
> >  Documentation/RCU/Design/Requirements/Requirements.html | 8 
> >  1 file changed, 4 insertions(+), 4 deletions(-)
> > 
> > diff --git a/Documentation/RCU/Design/Requirements/Requirements.html 
> > b/Documentation/RCU/Design/Requirements/Requirements.html
> > index ece410f40436..1c39a2362911 100644
> > --- a/Documentation/RCU/Design/Requirements/Requirements.html
> > +++ b/Documentation/RCU/Design/Requirements/Requirements.html
> > @@ -1527,7 +1527,7 @@ However, as I learned from Matt Mackall's
> >  http://elinux.org/Linux_Tiny-FAQ;>bloatwatch
> >  efforts, memory footprint is critically important on single-CPU systems 
> > with
> >  non-preemptible (CONFIG_PREEMPT=n) kernels, and thus
> > - > href="https://lkml.kernel.org/g/20090113221724.ga15...@linux.vnet.ibm.com;>tiny
> >  RCU
> > + > href="https://lkml.kernel.org/r/20090113221724.ga15...@linux.vnet.ibm.com;>tiny
> >  RCU
> >  was born.
> >  Josh Triplett has since taken over the small-memory banner with his
> >  https://tiny.wiki.kernel.org/;>Linux kernel tinification
> > @@ -1975,7 +1975,7 @@ guard against mishaps and misuse:
> > and cleaned up with destroy_rcu_head().
> > Mathieu Desnoyers made me aware of this requirement, and also
> > supplied the needed
> > -> href="https://lkml.kernel.org/g/20100319013024.GA28456@Krystal;>patch.
> > +> href="https://lkml.kernel.org/r/20100319013024.GA28456@Krystal;>patch.
> > An infinite loop in an RCU read-side critical section will
> > eventually trigger an RCU CPU stall warning splat, with
> > the duration of eventually being controlled by the
> > @@ -2088,7 +2088,7 @@ be hidden behind a CONFIG_RCU_EXPERT 
> > Kconfig option.
> >  
> >  This all should be quite obvious, but the fact remains that
> >  Linus Torvalds recently had to
> > - > href="https://lkml.kernel.org/g/ca+55afy4wccwal4okts8wxhgz5h-ibecy_meg9c4mnqrunw...@mail.gmail.com;>remind
> > + > href="https://lkml.kernel.org/r/ca+55afy4wccwal4okts8wxhgz5h-ibecy_meg9c4mnqrunw...@mail.gmail.com;>remind
> >  me of this requirement.
> >  
> >  Firmware Interface
> > @@ -2229,7 +2229,7 @@ Thankfully, RCU update-side primitives, including
> >  The name notwithstanding, some Linux-kernel architectures
> >  can have nested NMIs, which RCU must handle correctly.
> >  Andy Lutomirski
> > - > href="https://lkml.kernel.org/g/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anb...@mail.gmail.com;>surprised
> >  me
> > + > href="https://lkml.kernel.org/r/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anb...@mail.gmail.com;>surprised
> >  me
> >  with this requirement;
> >  he also kindly surprised me with
> >   > href="https://lkml.kernel.org/g/CALCETrXSY9JpW3uE6H8WYk81sg56qasA2aqmjMPsq5dOtzso=g...@mail.gmail.com;>an
> >  algorithm
> 
> Strange that this one still works. Anyway...
> 
> 
> Acked-by: Steven Rostedt 

So we are confident that these links won't be fixed by the next merge
window?

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] documentation: fix broken lkml archive links in RCU requirements

[Paul E. McKenney]

On Fri, Sep 09, 2016 at 04:17:14PM +0200, Richard Weinberger wrote:
> Michael,
> 
> On Fri, Sep 9, 2016 at 3:43 PM, Michael Opdenacker
>  wrote:
> > Fix 4 LKML archive links that became broken (data loss
> > on mail-archive.com?)
> >
> > Working links were found on Paul McKenney's RCU articles
> > on LWN.net, from which the documentation originates:
> > http://lwn.net/Articles/652156/
> > http://lwn.net/Articles/652677/
> > http://lwn.net/Articles/653326/
> >
> > Signed-off-by: Michael Opdenacker 
> > ---
> >  Documentation/RCU/Design/Requirements/Requirements.html | 8 
> >  1 file changed, 4 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/RCU/Design/Requirements/Requirements.html 
> > b/Documentation/RCU/Design/Requirements/Requirements.html
> > index ece410f40436..2adb3d43ce44 100644
> > --- a/Documentation/RCU/Design/Requirements/Requirements.html
> > +++ b/Documentation/RCU/Design/Requirements/Requirements.html
> > @@ -1527,7 +1527,7 @@ However, as I learned from Matt Mackall's
> >  http://elinux.org/Linux_Tiny-FAQ;>bloatwatch
> >  efforts, memory footprint is critically important on single-CPU systems 
> > with
> >  non-preemptible (CONFIG_PREEMPT=n) kernels, and thus
> > - > href="https://lkml.kernel.org/g/20090113221724.ga15...@linux.vnet.ibm.com;>tiny
> >  RCU
> > +http://lkml.org/lkml/2009/1/14/449;>tiny RCU
> >  was born.
> >  Josh Triplett has since taken over the small-memory banner with his
> >  https://tiny.wiki.kernel.org/;>Linux kernel tinification
> > @@ -1975,7 +1975,7 @@ guard against mishaps and misuse:
> > and cleaned up with destroy_rcu_head().
> > Mathieu Desnoyers made me aware of this requirement, and also
> > supplied the needed
> > -> href="https://lkml.kernel.org/g/20100319013024.GA28456@Krystal;>patch.
> > +   https://lkml.org/lkml/2010/3/18/417;>patch.
> 
> Please don't add lkml.org. It does not use message ids for indexing.
> With knowing the message id you can query any other archive.
> e.g. http://marc.info/?i=20100319013024.GA28456@Krystal
> By adding lkml.org you kill that information. Archives come and go,
> the message id is the only common query id we have.
> 
> IMHO kernel.org admins should fix/improve their redirection service to
> point to a working service.

There has been some instability in the kernel.org redirection.  Right
now, the /r/ services seems to work, though as noted the /g/ does not.
Please report this to the Kernel.org administrators:

https://kernel.org/category/contact-us.html

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: clocksource_watchdog causing scheduling of timers every second (was [v13] support "task_isolation" mode)

[Paul E. McKenney]

On Fri, Aug 12, 2016 at 04:26:13PM +0200, Frederic Weisbecker wrote:
> On Fri, Aug 12, 2016 at 09:23:13AM -0500, Christoph Lameter wrote:
> > On Thu, 11 Aug 2016, Paul E. McKenney wrote:
> > 
> > > Heh!  The only really good idea is for clocks to be reliably in sync.
> > >
> > > But if they go out of sync, what do you want to do instead?
> > 
> > For a NOHZ task? Write a message to the syslog and reenable tick.

Fair enough!  Kicking off a low-priority task would achieve the latter
but not necessarily the former.  And of course assumes that the worker
thread is at real-time priority with various scheduler anti-starvation
features disabled.

> Indeed, a strong clocksource is a requirement for a full tickless machine.

No disagrement here!  ;-)

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: clocksource_watchdog causing scheduling of timers every second (was [v13] support "task_isolation" mode)

[Paul E. McKenney]

On Thu, Aug 11, 2016 at 06:02:34PM -0500, Christoph Lameter wrote:
> On Thu, 11 Aug 2016, Paul E. McKenney wrote:
> 
> > > With modern Intel we could run it on one CPU per package I think, but at
> > > the same time, too much in NOHZ_FULL assumes the TSC is indeed sane so
> > > it doesn't make sense to me to keep the watchdog running, when it
> > > triggers it would also have to kill all NOHZ_FULL stuff, which would
> > > probably bring the entire machine down..
> >
> > Well, you -could- force a very low priority CPU-bound task to run on
> > all nohz_full CPUs.  Not necessarily a good idea, but a relatively
> > non-intrusive response to that particular error condition.
> 
> Given that we want the cpu only to run the user task I would think that is
> not a good idea.

Heh!  The only really good idea is for clocks to be reliably in sync.

But if they go out of sync, what do you want to do instead?

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v5 2/2] Doc/memory-barriers: Add Korean translation

[Paul E. McKenney]

On Thu, Jul 21, 2016 at 06:15:33PM +0200, Ingo Molnar wrote:
> 
> * Paul E. McKenney <paul...@linux.vnet.ibm.com> wrote:
> 
> > On Thu, Jul 21, 2016 at 10:10:58AM +0900, SeongJae Park wrote:
> > > This commit adds Korean version of memory-barriers.txt document.  The
> > > header is refered to HOWTO Korean version.
> > > 
> > > The translation has started from Feb, 2016 and using a public git
> > > repository[1] to maintain the work.  It's commit history says that it is
> > > following upstream changes as well.
> > > 
> > > [1] https://github.com/sjp38/linux.doc_trans_membarrier
> > > 
> > > Acked-by: David Howells <dhowe...@redhat.com>
> > > Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> > > Acked-by: Minchan Kim <minc...@kernel.org>
> > > Signed-off-by: SeongJae Park <sj38.p...@gmail.com>
> > 
> > If Minchan is OK with this version, if Ingo and Jon have no objections,
> > and given the small change below, I will take it.
> 
> Acked-by: Ingo Molnar <mi...@kernel.org>

Thank you both!

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v5 1/2] Doc/memory-barriers: Fix a typo of example result

[Paul E. McKenney]

On Thu, Jul 21, 2016 at 10:10:57AM +0900, SeongJae Park wrote:
> An example result for data dependent write has a typo.  This commit
> fixes the wrong typo.
> 
> Signed-off-by: SeongJae Park 

Good catch!  Queued, thank you!

Thanx, Paul

> ---
>  Documentation/memory-barriers.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index 19c8eb6..ba818ec 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -609,7 +609,7 @@ A data-dependency barrier must also order against 
> dependent writes:
>  The data-dependency barrier must order the read into Q with the store
>  into *Q.  This prohibits this outcome:
> 
> - (Q == B) && (B == 4)
> + (Q == ) && (B == 4)
> 
>  Please note that this pattern should be rare.  After all, the whole point
>  of dependency ordering is to -prevent- writes to the data structure, along
> -- 
> 1.9.1
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4 0/3] Doc/memory-barriers: Add Korean translation

[Paul E. McKenney]

On Mon, Jul 04, 2016 at 08:27:05AM +0900, SeongJae Park wrote:
> This patchset adds Korean translation of memory-barriers.txt and fix few
> nitpicks found during the translation.  The translation has started from Feb,
> 2016 and using private git tree[1] to manage the work.  It's commit history
> says that it is following upstream changes as well.
> 
> Change from v3:
>  - Polish readability for overall text:
>`1 file changed, 533 insertions(+), 505 deletions(-)`
> 
>  - Add disclaimer of translation
> 
> SeongJae Park (3):
>   memory-barriers.txt: maintain consistent blank line
>   memory-barriers.txt: fix wrong section reference
>   Doc/memory-barriers: Add Korean translation

I applied the first two, thank you very much!

I must defer to Ingo Molnar and Jonathan Corbet on the translation.

Thanx, Paul

>  Documentation/ko_KR/memory-barriers.txt | 3123 
> +++
>  Documentation/memory-barriers.txt   |3 +-
>  2 files changed, 3125 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/ko_KR/memory-barriers.txt
> 
> -- 
> 1.9.1
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] rcutorture: Remove outdated config option description

[Paul E. McKenney]

On Mon, Jun 20, 2016 at 07:51:22AM +0900, SeongJae Park wrote:
> CONFIG_RCU_TORTURE_TEST_RUNNABLE has removed by commit 4e9a073f60367
> ("torture: Remove CONFIG_RCU_TORTURE_TEST_RUNNABLE, simplify code")
> entirely but the document has not updated.  This commit updates the
> document to remove the description for the config option and adding a
> description for the alternative module parameter.
> 
> Signed-off-by: SeongJae Park 

Good catch on CONFIG_RCU_TORTURE_TEST_RUNNABLE, queued for testing and
review.

I had to drop the other hunk for torture_runnable, though.  This
capability is instead controlled by several parameters that are documented
in Documentation/kernel-parameters.txt.

Thanx, Paul

> ---
>  Documentation/RCU/torture.txt | 20 +---
>  1 file changed, 5 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
> index 118e7c1..4bd9d86 100644
> --- a/Documentation/RCU/torture.txt
> +++ b/Documentation/RCU/torture.txt
> @@ -10,21 +10,6 @@ status messages via printk(), which can be examined via 
> the dmesg
>  command (perhaps grepping for "torture").  The test is started
>  when the module is loaded, and stops when the module is unloaded.
> 
> -CONFIG_RCU_TORTURE_TEST_RUNNABLE
> -
> -It is also possible to specify CONFIG_RCU_TORTURE_TEST=y, which will
> -result in the tests being loaded into the base kernel.  In this case,
> -the CONFIG_RCU_TORTURE_TEST_RUNNABLE config option is used to specify
> -whether the RCU torture tests are to be started immediately during
> -boot or whether the /proc/sys/kernel/rcutorture_runnable file is used
> -to enable them.  This /proc file can be used to repeatedly pause and
> -restart the tests, regardless of the initial state specified by the
> -CONFIG_RCU_TORTURE_TEST_RUNNABLE config option.
> -
> -You will normally -not- want to start the RCU torture tests during boot
> -(and thus the default is CONFIG_RCU_TORTURE_TEST_RUNNABLE=n), but doing
> -this can sometimes be useful in finding boot-time bugs.
> -
> 
>  MODULE PARAMETERS
> 
> @@ -164,6 +149,11 @@ test_no_idle_hz  Whether or not to test the ability of 
> RCU to operate in
>   idle CPUs.  Boolean parameter, "1" to test, "0" otherwise.
>   Defaults to omitting this test.
> 
> +torture_runnable  Start rcutorture at boot time in the case where the
> +   module is built into the kernel, otherwise wait for
> +   torture_runnable to be set via sysfs before starting.
> +   By default it will begin once the module is loaded.
> +
>  torture_type The type of RCU to test, with string values as follows:
> 
>   "rcu":  rcu_read_lock(), rcu_read_unlock() and call_rcu(),
> -- 
> 1.9.1
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH Documentation/memory-barriers.txt] Clarify limited control-dependency scope

[Paul E. McKenney]

On Fri, Jun 17, 2016 at 09:53:50AM +0200, Ingo Molnar wrote:
> 
> * Paul E. McKenney <paul...@linux.vnet.ibm.com> wrote:
> 
> > Nothing in the control-dependencies section of memory-barriers.txt
> > says that control dependencies don't extend beyond the end of the
> > if-statement containing the control dependency.  Worse yet, in many
> > situations, they do extend beyond that if-statement.  In particular,
> > the compiler cannot destroy the control dependency given proper use of
> > READ_ONCE() and WRITE_ONCE().  However, a weakly ordered system having
> > a conditional-move instruction provides the control-dependency guarantee
> > only to code within the scope of the if-statement itself.
> > 
> > This commit therefore adds words and an example demonstrating this
> > limitation of control dependencies.
> > 
> > Reported-by: Will Deacon <will.dea...@arm.com>
> > Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
> > Acked-by: Peter Zijlstra (Intel) <pet...@infradead.org>
> > 
> > diff --git a/Documentation/memory-barriers.txt 
> > b/Documentation/memory-barriers.txt
> > index 147ae8ec836f..a4d0a99de04d 100644
> > --- a/Documentation/memory-barriers.txt
> > +++ b/Documentation/memory-barriers.txt
> > @@ -806,6 +806,41 @@ out-guess your code.  More generally, although 
> > READ_ONCE() does force
> >  the compiler to actually emit code for a given load, it does not force
> >  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:
> > +
> > +   q = READ_ONCE(a);
> > +   if (q) {
> > +   WRITE_ONCE(b, p);
> > +   } else {
> > +   WRITE_ONCE(b, r);
> > +   }
> > +   WRITE_ONCE(c, 1);  /* BUG: No ordering against the read from "a". */
> > +
> > +It is tempting to argue that there in fact is ordering because the
> > +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:
> 
> While CMOV would be the typical situation, even without CMOV the compiler 
> could 
> also internally transform it to:
> 
> > +   if (q)
> > +   WRITE_ONCE(b, p);
> > +   if (!q)
> > +   WRITE_ONCE(b, r);
> 
> ... and CPU speculation flow could get past the two branches without seeing 
> any 
> ordering constraint with the writes to 'b'.
> 
> I.e. conditions are not 'atomic', they can be 'torn' by the compiler just as 
> much 
> as reads or writes can be torn.

That is an interesting test case!

PowerPC prohibits speculating the writes in your transformed case, that is,
prohibits the writes to "b" from being reordered with the read from "a".
I believe that ARM also prohibits it in that case, but must defer to
Will Deacon.  Not sure about MIPS.

Or am I misunderstanding your intent with that example?

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH Documentation/memory-barriers.txt] Clarify limited control-dependency scope

[Paul E. McKenney]

Nothing in the control-dependencies section of memory-barriers.txt
says that control dependencies don't extend beyond the end of the
if-statement containing the control dependency.  Worse yet, in many
situations, they do extend beyond that if-statement.  In particular,
the compiler cannot destroy the control dependency given proper use of
READ_ONCE() and WRITE_ONCE().  However, a weakly ordered system having
a conditional-move instruction provides the control-dependency guarantee
only to code within the scope of the if-statement itself.

This commit therefore adds words and an example demonstrating this
limitation of control dependencies.

Reported-by: Will Deacon <will.dea...@arm.com>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
Acked-by: Peter Zijlstra (Intel) <pet...@infradead.org>

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index 147ae8ec836f..a4d0a99de04d 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -806,6 +806,41 @@ out-guess your code.  More generally, although READ_ONCE() 
does force
 the compiler to actually emit code for a given load, it does not force
 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:
+
+   q = READ_ONCE(a);
+   if (q) {
+   WRITE_ONCE(b, p);
+   } else {
+   WRITE_ONCE(b, r);
+   }
+   WRITE_ONCE(c, 1);  /* BUG: No ordering against the read from "a". */
+
+It is tempting to argue that there in fact is ordering because the
+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:
+
+   ld r1,a
+   ld r2,p
+   ld r3,r
+   cmp r1,$0
+   cmov,ne r4,r2
+   cmov,eq r4,r3
+   st r4,b
+   st $1,c
+
+A weakly ordered CPU would have no dependency of any sort between the load
+from "a" and the store to "c".  The control dependencies would extend
+only to the pair of cmov instructions and the store depending on them.
+In short, control dependencies apply only to the stores in the then-clause
+and else-clause of the if-statement in question (including functions
+invoked by those two clauses), not to code following that if-statement.
+
 Finally, control dependencies do -not- provide transitivity.  This is
 demonstrated by two related examples, with the initial values of
 x and y both being zero:
@@ -869,6 +904,12 @@ In summary:
   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
+  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 do -not- provide transitivity.  If you

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH locking 4/4] locktorture: Simplify torture_runnable computation

[Paul E. McKenney]

This commit replaces a #ifdef with IS_ENABLED(), saving five lines.

Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
---
 kernel/locking/locktorture.c | 7 +--
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/kernel/locking/locktorture.c b/kernel/locking/locktorture.c
index d066a50dc87e..f8c5af52a131 100644
--- a/kernel/locking/locktorture.c
+++ b/kernel/locking/locktorture.c
@@ -75,12 +75,7 @@ struct lock_stress_stats {
long n_lock_acquired;
 };
 
-#if defined(MODULE)
-#define LOCKTORTURE_RUNNABLE_INIT 1
-#else
-#define LOCKTORTURE_RUNNABLE_INIT 0
-#endif
-int torture_runnable = LOCKTORTURE_RUNNABLE_INIT;
+int torture_runnable = IS_ENABLED(MODULE);
 module_param(torture_runnable, int, 0444);
 MODULE_PARM_DESC(torture_runnable, "Start locktorture at module init");
 
-- 
2.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH locking 2/4] documentation: State purpose of memory-barriers.txt

[Paul E. McKenney]

From: David Howells <dhowe...@redhat.com>

There has been some confusion about the purpose of memory-barriers.txt,
so this commit adds a statement of purpose.

Signed-off-by: David Howells <dhowe...@redhat.com>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
---
 Documentation/memory-barriers.txt | 16 
 1 file changed, 16 insertions(+)

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index fb2dd35a823a..8b11e54238bf 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -19,6 +19,22 @@ 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.
 
+The purpose of this document is twofold:
+
+ (1) to specify the minimum functionality that one can rely on for any
+ particular barrier, and
+
+ (2) to provide a guide as to how to use the barriers that are available.
+
+Note that an architecture can provide more than the minimum requirement
+for any particular barrier, but if the architecure provides less than
+that, that architecture is incorrect.
+
+Note also that it is possible that a barrier may be a no-op for an
+architecture because the way that arch works renders an explicit barrier
+unnecessary in that case.
+
+
 
 CONTENTS
 
-- 
2.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH locking 3/4] documentation: ACQUIRE applies to loads, RELEASE applies to stores

[Paul E. McKenney]

From: Will Deacon <will.dea...@arm.com>

For compound atomics performing both a load and a store operation, make
it clear that _acquire and _release variants refer only to the load and
store portions of compound atomic. For example, xchg_acquire is an xchg
operation where the load takes on ACQUIRE semantics.

Cc: Paul E. McKenney <paul...@linux.vnet.ibm.com>
Cc: Peter Zijlstra <pet...@infradead.org>
Signed-off-by: Will Deacon <will.dea...@arm.com>
Acked-by: Peter Zijlstra (Intel) <pet...@infradead.org>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
---
 Documentation/memory-barriers.txt | 5 +
 1 file changed, 5 insertions(+)

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index 8b11e54238bf..147ae8ec836f 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -498,6 +498,11 @@ And a couple of implicit varieties:
  This means that ACQUIRE acts as a minimal "acquire" operation and
  RELEASE acts as a minimal "release" operation.
 
+A subset of the atomic operations described in atomic_ops.txt have ACQUIRE
+and RELEASE variants in addition to fully-ordered and relaxed (no barrier
+semantics) definitions.  For compound atomics performing both a load and a
+store, ACQUIRE semantics apply only to the load and RELEASE semantics apply
+only to the store portion of the operation.
 
 Memory barriers are only required where there's a possibility of interaction
 between two CPUs or between a CPU and a device.  If it can be guaranteed that
-- 
2.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH locking 1/4] documentation: Add disclaimer

[Paul E. McKenney]

From: Peter Zijlstra <pet...@infradead.org>

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.

Signed-off-by: Peter Zijlstra (Intel) <pet...@infradead.org>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
---
 Documentation/memory-barriers.txt | 18 +-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index a9454b1c73bd..fb2dd35a823a 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -4,8 +4,24 @@
 
 By: David Howells <dhowe...@redhat.com>
 Paul E. McKenney <paul...@linux.vnet.ibm.com>
+Will Deacon <will.dea...@arm.com>
+Peter Zijlstra <pet...@infradead.org>
 
-Contents:
+==
+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.
+
+To repeat, this document is not a specification of what Linux expects from
+hardware.
+
+
+CONTENTS
+
 
  (*) Abstract memory access model.
 
-- 
2.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH locking 0/4] locktorture and memory-barriers.txt updates

[Paul E. McKenney]

Hello!

This series contains a few memory-barriers.txt updates and a locktorture
cleanup:

1.  Add a disclaimer to memory-barrier.txt, courtesy of
Peter Zijlstra.

2.  Explicitly state the purpose of memory-barrier.txt, courtesy
of David Howells.

3.  Explicitly state that ACQUIRE applies to loads and that
RELEASE applies to stores, courtesy of Will Deacon.

4.  Simplify torture_runnable computation in locktorture, replacing
a multiline #ifdef with an IS_ENABLED() that fits into an
existing line.

Thanx, Paul



 Documentation/memory-barriers.txt |   39 +-
 kernel/locking/locktorture.c  |7 --
 2 files changed, 39 insertions(+), 7 deletions(-)

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 33/41] Documentation: RCU: fix spelling mistake

[Paul E. McKenney]

On Mon, Apr 25, 2016 at 12:48:13AM -0700, Josh Triplett wrote:
> On Mon, Apr 25, 2016 at 07:36:59AM +0100, Eric Engestrom wrote:
> > Signed-off-by: Eric Engestrom 
> 
> Good catch.
> 
> Reviewed-by: Josh Triplett 

Queued, thank you both!

Thanx, Paul

> > ---
> >  Documentation/RCU/stallwarn.txt | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/RCU/stallwarn.txt 
> > b/Documentation/RCU/stallwarn.txt
> > index 0f7fb42..e93d041 100644
> > --- a/Documentation/RCU/stallwarn.txt
> > +++ b/Documentation/RCU/stallwarn.txt
> > @@ -49,7 +49,7 @@ rcupdate.rcu_task_stall_timeout
> > This boot/sysfs parameter controls the RCU-tasks stall warning
> > interval.  A value of zero or less suppresses RCU-tasks stall
> > warnings.  A positive value sets the stall-warning interval
> > -   in jiffies.  An RCU-tasks stall warning starts wtih the line:
> > +   in jiffies.  An RCU-tasks stall warning starts with the line:
> >  
> > INFO: rcu_tasks detected stalls on tasks:
> >  
> > -- 
> > 2.8.0
> > 
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/5] Add Korean translation of memory-barriers.txt

[Paul E. McKenney]

On Tue, Mar 15, 2016 at 08:36:05AM +0900, Minchan Kim wrote:
> On Tue, Mar 15, 2016 at 06:52:11AM +0900, SeongJae Park wrote:
> > On Tue, Mar 15, 2016 at 5:17 AM, Paul E. McKenney
> > <paul...@linux.vnet.ibm.com> wrote:
> > > On Fri, Mar 11, 2016 at 12:06:55AM +0900, SeongJae Park wrote:
> > >> This patchset aims to add Korean translation of memory-barriers document.
> > >>
> > >> The patchset starts from fixing minor and trivial problems in the 
> > >> original
> > >> document that found during translation.  After that, the final patch 
> > >> adds the
> > >> Korean translation of the document.
> > >>
> > >> The patches are based on recent next tree:
> > >> 0f6dd067b9c3c712b1177fa2fc0deb21805c771c ("Add linux-next specific files 
> > >> for
> > >> 20160309")
> > >
> > > Queued, thank you!  I am going to have to trust you on the Korean, good
> > > thing you list yourself as maintainer.  ;-)
> > 
> > Thank you, Paul!  I believe this change may help future Korean hackers.  
> > Also,
> > I will do my best to maintain the document up to date with good quality.
> 
> +1
> 
> I cannot expect when someone who knows Korean, understand memory-barrier stuff
> very well and have enough time to reivew comes up. Anyway, if the translation
> has a problem, we could fix it later so I really appreciate SeongJae's nice
> contribution translated one of hardest document but valuable.
> 
> Acked-by: Minchan Kim <minc...@kernel.org>

Very good, I have added your Acked-by.

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/5] Add Korean translation of memory-barriers.txt

[Paul E. McKenney]

On Thu, Mar 10, 2016 at 09:48:54AM +0900, SeongJae Park wrote:
> This patchset aims to add Korean translation of memory-barriers document.
> 
> The patchset starts from fixing minor and trivial problems in the original
> document that found during translation.  After that, the final patch adds the
> Korean translation of the document.
> 
> The patches are based on recent next tree:
> 0f6dd067b9c3c712b1177fa2fc0deb21805c771c ("Add linux-next specific files for
> 20160309")

I have queued this series for review, thank you!

Of course, I cannot do anything to the Korean translation other than to
pass it through unchanged.  ;-)

Thanx, Paul

> SeongJae Park (5):
>   doc/memory-barriers: fix missed renaming: s/lock/acquire
>   doc/memory-barriers: add missed subsection in TOC
>   doc/memory-barriers: fix typo
>   doc/memory-barriers: Insert white spaces consistently
>   Doc/memory-barriers: add Korean translation
> 
>  Documentation/ko_KR/memory-barriers.txt | 3048 
> +++
>  Documentation/memory-barriers.txt   |   62 +-
>  2 files changed, 3081 insertions(+), 29 deletions(-)
>  create mode 100644 Documentation/ko_KR/memory-barriers.txt
> 
> -- 
> 1.9.1
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] x86: PAT: Documentation: rewrite "MTRR effects on PAT / non-PAT systems"

[Paul E. McKenney]

On Fri, Mar 04, 2016 at 02:45:01PM -0800, Luis R. Rodriguez wrote:
> The current documentation refers to using set_memory_wc() as a
> possible hole strategy when you have overlapping ioremap() regions,
> that's incorrect as set_memory_*() helpers can only be used on RAM,
> not IO memory. Using set_memory_wc() will not fail, that's a problem
> which must be corrected in the future. This fixes that, and updates
> the documention to *strongly* discourage overlapping ioremap() memory
> uses, but also documents a possible solution should there really be
> no other option to remain compatible on both PAT and MTRR memory
> constarained systems. While at it, this provides some same guidlines
> to system designers to remain sane and compatible on both PAT and
> non-PAT systems.
> 
> As per Toshi this also fixes the table for the effective memory type
> when using MTRR WC on PAT UC- to WC.
> 
> Signed-off-by: Luis R. Rodriguez 

And I was really confused during my earlier reply.  For some reason
I read the filename as memory-barriers.txt.

This one is not mine.  Too much time in standards committee meetings,
I guess.  ;-)

Thanx, Paul

> ---
>  Documentation/x86/pat.txt | 54 
> +++
>  1 file changed, 41 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/x86/pat.txt b/Documentation/x86/pat.txt
> index 54944c71b819..6323f24f3b59 100644
> --- a/Documentation/x86/pat.txt
> +++ b/Documentation/x86/pat.txt
> @@ -112,19 +112,47 @@ before the page is freed to free pool.
>  MTRR effects on PAT / non-PAT systems
>  -
> 
> +As of v4.3 mtrr_add() has been phased out in favor of arch_phys_wc_add(),
> +these calls are a no-op on PAT enabled systems but remain MTRR effective
> +on non-PAT systems. In order for this to work properly on both PAT and
> +non-PAT systems the region over which an arch_phys_wc_add() is made should be
> +ioremapped with WC attributes or PAT entries, using ioremap_wc().
> +
> +To enable simplifying device drivers, and to help support PAT and remain
> +compatible with non-PAT systems, PCI devices are encouraged to dedicate a 
> full
> +PCI bar for different intended regions of IO, for instance one PCI BAR for
> +MMIO and another PCI BAR for write-combing, if needed.
> +
> +Firmware should always expose to the operating system where write-combining 
> is
> +desirable, otherwise PAT cannot be supported, PAT systems need to know the
> +physical address of the area where write-combining is desirable.
> +
> +Devices which use a single PCI BAR to combine different areas of IO memory
> +must use separate ioremap() calls for each type of intended IO memory.
> +Physically overlapping ioremap calls are strongly discouraged and may soon be
> +disallowed. Devices that have one PCI BAR with an area of IO where
> +write-combining is desirable followed contiguously by an area of MMIO
> +should ioremap_wc() only on the area where write-combining is desired,
> +followed by a physically non-overlapping ioremap_uc() for MMIO. Since MTRR
> +calls are limited, and since MTRR calls must be done with orders of power of 
> 2
> +on both the size and base address one may be constrained to use just one MTRR
> +call which will include the full MMIO range. In such cases, in order to 
> remain
> +compatible with PAT and functional on non-PAT systems arch_phys_wc_add() can
> +be used to enable MTRR WC on the entire PCI BAR for all the combined IO range
> +(both write-combining and MMIO range). Using ioremap_uc() ensures that a
> +MTRR WC applied to it effectively yields UC, while using ioremap_wc()
> +white-lists the MTRR WC effects over its region. For an example of this
> +strategy refer to commit 3cc2dac5be ("drivers/video/fbdev/atyfb: Replace
> +MTRR UC hole with strong UC"). Such use is nevertheless heavily discouraged
> +as the effective memory type for the write-combined area on non-PAT is
> +technically considered implementation defined. This strategy should only be
> +used used as a last resort measure.
> +
> +You cannot use set_memory_*() helpers on ioremap'd regions (IO memory), even
> +though its use currently gives no hint of an error.
> +
>  The following table provides the effects of using write-combining MTRRs when
> -using ioremap*() calls on x86 for both non-PAT and PAT systems. Ideally
> -mtrr_add() usage will be phased out in favor of arch_phys_wc_add() which will
> -be a no-op on PAT enabled systems. The region over which a arch_phys_wc_add()
> -is made, should already have been ioremapped with WC attributes or PAT 
> entries,
> -this can be done by using ioremap_wc() / set_memory_wc().  Devices which
> -combine areas of IO memory desired to remain uncacheable with areas where
> -write-combining is desirable should consider use of ioremap_uc() followed by
> -set_memory_wc() to white-list effective write-combined areas.  Such use is
> -nevertheless 

Re: [PATCH] x86: PAT: Documentation: update overlapping ioremap hack recommendation

[Paul E. McKenney]

On Fri, Mar 04, 2016 at 08:23:26PM +0100, Luis R. Rodriguez wrote:
> On Thu, Mar 03, 2016 at 01:42:33PM -0800, Paul E. McKenney wrote:
> > On Thu, Mar 03, 2016 at 01:21:48PM -0800, Luis R. Rodriguez wrote:
> > > The current documentation refers to using set_memor_wc() as a
> > > possible hole strategy when you have overlapping ioremap() regions,
> > > that's incorrect as set_memory_*() helpers can only be used on RAM,
> > > not IO memory. This fixes that, and updates the documention to
> > > *strongly* discourage overlapping ioremap() memory uses, but also
> > > documents a possible solution should there really be no other
> > > option.
> > > 
> > > Signed-off-by: Luis R. Rodriguez <mcg...@kernel.org>
> > 
> > Given an Acked-by or better from the guys on the TO line, I would be
> > happy to queue it.
> 
> I'll need to respin as fortunately I ended up actually not needing
> to do an overlap on atyfb, and instead just let MTRR be effective
> over an entire range that included both write-combining and strong
> UC attributes. It was a bit fuzzy as this while ago, and since its
> also obscure, its more reason to document now.
> 
> Will spin a v2.

Sounds good!

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/memory-barriers: fix wrong comment in example

[Paul E. McKenney]

On Mon, Feb 22, 2016 at 11:16:39AM +, David Howells wrote:
> SeongJae Park <sj38.p...@gmail.com> wrote:
> 
> > From f7b5677790771599f418f1d95536935be971ae86 Mon Sep 17 00:00:00 2001
> > From: SeongJae Park <sj38.p...@gmail.com>
> > 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.
> > 
> > Signed-off-by: SeongJae Park <sj38.p...@gmail.com>
> > ---
> >  Documentation/memory-barriers.txt | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/memory-barriers.txt
> > b/Documentation/memory-barriers.txt
> > index 904ee42..dc66351 100644
> > --- a/Documentation/memory-barriers.txt
> > +++ b/Documentation/memory-barriers.txt
> > @@ -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
> 
> Acked-by: David Howells <dhowe...@redhat.com>

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 <sj38.p...@gmail.com>
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.

Signed-off-by: SeongJae Park <sj38.p...@gmail.com>
Acked-by: David Howells <dhowe...@redhat.com>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index 8367d393cba2..3729cbe60e41 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/memory-barriers: fix wrong comment in example

[Paul E. McKenney]

On Sun, Feb 21, 2016 at 07:50:19AM +0900, SeongJae Park wrote:
> On Sun, Feb 21, 2016 at 4:57 AM, Paul E. McKenney
> <paul...@linux.vnet.ibm.com> wrote:
> > On Sat, Feb 20, 2016 at 03:01:08PM +0900, SeongJae Park wrote:
> >> 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 <sj38.p...@gmail.com>
> >
> > 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.
> 
> >
> > 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.

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

> Thanks,
> SeongJae Park
> 
> >
> > Thanx, Paul
> >
> >> ---
> >>  Documentation/memory-barriers.txt | 2 +-
> >>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>
> >> diff --git a/Documentation/memory-barriers.txt 
> >> b/Documentation/memory-barriers.txt
> >> index 061ff29..b4754c7 100644
> >> --- a/Documentation/memory-barriers.txt
> >> +++ b/Documentation/memory-barriers.txt
> >> @@ -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
> >>
> >
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/memory-barriers: fix wrong comment in example

[Paul E. McKenney]

On Sat, Feb 20, 2016 at 03:01:08PM +0900, SeongJae Park wrote:
> 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 

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

> ---
>  Documentation/memory-barriers.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/memory-barriers.txt 
> b/Documentation/memory-barriers.txt
> index 061ff29..b4754c7 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -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
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html