Re: [PATCH tip/core/rcu 01/10] kcsan: Add pointer to access-marking.txt to data_race() bullet

[Paul E. McKenney]

On Thu, May 13, 2021 at 12:53:44PM +0200, Marco Elver wrote:
> On Thu, 13 May 2021 at 12:47, Akira Yokosawa <akiyks@xxxxxxxxx> wrote:
> >
> > Hi Paul,
> >
> > On Tue, 11 May 2021 16:23:52 -0700, Paul E. McKenney wrote:
> > > This commit references tools/memory-model/Documentation/access-marking.txt
> > > in the bullet introducing data_race().  The access-marking.txt file
> > > gives advice on when data_race() should and should not be used.
> > >
> > > Suggested-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> > > Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxx>
> > > ---
> > >  Documentation/dev-tools/kcsan.rst | 4 +++-
> > >  1 file changed, 3 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst
> > > index d85ce238ace7..80894664a44c 100644
> > > --- a/Documentation/dev-tools/kcsan.rst
> > > +++ b/Documentation/dev-tools/kcsan.rst
> > > @@ -106,7 +106,9 @@ the below options are available:
> > >
> > >  * KCSAN understands the ``data_race(expr)`` annotation, which tells KCSAN that
> > >    any data races due to accesses in ``expr`` should be ignored and resulting
> > > -  behaviour when encountering a data race is deemed safe.
> > > +  behaviour when encountering a data race is deemed safe.  Please see
> > > +  ``tools/memory-model/Documentation/access-marking.txt`` in the kernel source
> > > +  tree for more information.
> > >
> > >  * Disabling data race detection for entire functions can be accomplished by
> > >    using the function attribute ``__no_kcsan``::
> > >
> >
> > I think this needs some adjustment for overall consistency.
> > A possible follow-up patch (relative to the change above) would look
> > like the following.
> >
> > Thoughts?
> >
> >         Thanks, Akira
> >
> > -------8<--------
> > From: Akira Yokosawa <akiyks@xxxxxxxxx>
> > Subject: [PATCH] kcsan: Use URL link for pointing access-marking.txt
> >
> > For consistency within kcsan.rst, use a URL link as the same as in
> > section "Data Races".
> >
> > Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> > Cc: Paul E. McKenney <paulmck@xxxxxxxxxx>
> 
> Good catch. I'd be in favour of this change, as it makes it simpler to
> just follow the link. Because in most cases I usually just point folks
> at the rendered version of this:
> https://www.kernel.org/doc/html/latest/dev-tools/kcsan.html
> 
> Acked-by: Marco Elver <elver@xxxxxxxxxx>

Queued with Marco's ack, thank you both!

							Thanx, Paul

> > ---
> >  Documentation/dev-tools/kcsan.rst | 5 +++--
> >  1 file changed, 3 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst
> > index 80894664a44c..151f96b7fef0 100644
> > --- a/Documentation/dev-tools/kcsan.rst
> > +++ b/Documentation/dev-tools/kcsan.rst
> > @@ -107,8 +107,7 @@ the below options are available:
> >  * KCSAN understands the ``data_race(expr)`` annotation, which tells KCSAN that
> >    any data races due to accesses in ``expr`` should be ignored and resulting
> >    behaviour when encountering a data race is deemed safe.  Please see
> > -  ``tools/memory-model/Documentation/access-marking.txt`` in the kernel source
> > -  tree for more information.
> > +  `"Marking Shared-Memory Accesses" in the LKMM`_ for more information.
> >
> >  * Disabling data race detection for entire functions can be accomplished by
> >    using the function attribute ``__no_kcsan``::
> > @@ -130,6 +129,8 @@ the below options are available:
> >
> >      KCSAN_SANITIZE := n
> >
> > +.. _"Marking Shared-Memory Accesses" in the LKMM: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/access-marking.txt
> > +
> >  Furthermore, it is possible to tell KCSAN to show or hide entire classes of
> >  data races, depending on preferences. These can be changed via the following
> >  Kconfig options:
> > --
> > 2.17.1