Re: [PATCH] Documentation: Remove misleading examples of the barriers in wake_*()

[Boqun Feng]

On Sun, Oct 11, 2015 at 05:40:44PM -0700, Paul E. McKenney wrote:
> On Sun, Oct 11, 2015 at 11:26:40PM +0800, Boqun Feng wrote:
> > On Tue, Oct 06, 2015 at 06:06:50PM +0200, Peter Zijlstra wrote:
> > > On Thu, Sep 24, 2015 at 09:21:22PM +0800, Boqun Feng wrote:
> > > > > Included in it are some of the details on this subject, because a wakeup
> > > > > has two prior states that are of importance, the tasks own prior state
> > > > > and the wakeup state, both should be considered in the 'program order'
> > > > > flow.
> > > > > 
> > > > 
> > > > Great and very helpful ;-)
> > > > 
> > > > > So maybe we can reduce the description in memory-barriers to this
> > > > > 'split' program order guarantee, where a woken task must observe both
> > > > > its own prior state and its wakee state.
> > > >                               ^^^^^
> > > > I think you mean "waker" here, right?
> > > 
> > > Yes.
> > > 
> > > > And the waker is not necessarily the same task who set the @cond to
> > > > true, right? 
> > > 
> > > It should be.
> > > 
> > > > If so, I feel like it's really hard to *use* this 'split'
> > > > program order guarantee in other places than sleep/wakeup itself. Could
> > > > you give an example? Thank you.
> > > 
> > > It was not meant to be used in any other scenario; the 'split' PO really
> > > is part of the whole sleep/wakeup. It does not apply to anything else.
> > 
> > Got it. So at this point, I think it's better to remove the entire
> > "Sleep and wake-up functions" section in memory-barriers.txt. Because
> > this order guarantee is not for other users except sleep/wakeup. Any
> > concern, Paul?
> 
> The concern I have with just removing it is that it is all too easy for
> people to assume that they provide ordering.  So we should at least have

Understood.

But, IMO, the position of this section is already misleading:

(*) Implicit kernel memory barriers.
     - Locking functions.
     - Interrupt disabling functions.
   ->- Sleep and wake-up functions.<-
     - Miscellaneous functions.

I read it as that sleep and wake-up functions provide some kernel memory
barriers which we can use *externally*(outside sleep/wakeup themselves).

So how about something like:

(*) Barriers only for internal use
     - Sleep and wake-up functions.

Regards,
Boqun

> a section stating clearly that ordering is not guaranteed without help
> from locks, release-acquire, explicit memory barriers, etc.
> 
> 							Thanx, Paul
>

Attachment: signature.asc
Description: PGP signature