Re: Prototype patch for Linux-kernel memory model

[Andrea Parri <parri.andrea@gmail.com>]

On Fri, Nov 17, 2017 at 07:27:46PM +0800, Boqun Feng wrote:
> On Wed, Nov 15, 2017 at 08:37:49AM -0800, Paul E. McKenney wrote:
> > On Tue, Nov 14, 2017 at 09:15:05AM -0800, Paul E. McKenney wrote:
> > > On Tue, Nov 14, 2017 at 10:19:21AM -0500, Alan Stern wrote:
> > > > On Tue, 14 Nov 2017, Peter Zijlstra wrote:
> > > > 
> > > > > On Mon, Nov 13, 2017 at 10:40:31AM -0800, Paul E. McKenney wrote:
> > > > > > commit 82a1431549b4eae531e83298fd72cd0acea08540
> > > > > > Author: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> > > > > > Date:   Mon Nov 13 10:30:07 2017 -0800
> > > > > > 
> > > > > >     tools: Automate memory-barriers.txt; provide Linux-kernel memory model
> > > > > >     
> > > > > >     There is some reason to believe that Documentation/memory-barriers.txt
> > > > > >     could use some help, and a major purpose of this patch is to provide
> > > > > >     that help in the form of a design-time tool that can produce all valid
> > > > > >     executions of a small fragment of concurrent Linux-kernel code, which is
> > > > > >     called a "litmus test".  This tool's functionality is roughly similar to
> > > > > >     a full state-space search.  Please note that this is a design-time tool,
> > > > > >     not useful for regression testing.  However, we hope that the underlying
> > > > > >     Linux-kernel memory model will be incorporated into other tools capable
> > > > > >     of analyzing large bodies of code for regression-testing purposes.
> > > > > >     
> > > > > >     The main tool is herd7, together with the linux-kernel.bell,
> > > > > >     linux-kernel.cat, linux-kernel.cfg, linux-kernel.def, and lock.cat files
> > > > > >     added by this patch.  The herd7 executable takes the other files as input,
> > > > > >     and all of these files collectively define the Linux-kernel memory memory
> > > > > >     model.  A brief description of each of these other files is provided
> > > > > >     in the README file.  Although this tool does have its limitations,
> > > > > >     which are documented in the README file, it does improve on the version
> > > > > >     reported on in the LWN series (https://lwn.net/Articles/718628/ and
> > > > > >     https://lwn.net/Articles/720550/) by supporting locking and arithmetic,
> > > > > >     including a much wider variety of read-modify-write atomic operations.
> > > > > >     Please note that herd7 is not part of this submission, but is freely
> > > > > >     available from http://diy.inria.fr/sources/index.html (and via "git"
> > > > > >     at https://github.com/herd/herdtools7).
> > > > > >     
> > > > > >     A second tool is klitmus7, which converts litmus tests to loadable
> > > > > >     kernel modules for direct testing.  As with herd7, the klitmus7
> > > > > >     code is freely available from http://diy.inria.fr/sources/index.html
> > > > > >     (and via "git" at https://github.com/herd/herdtools7).
> > > > > >     
> > > > > >     Of course, litmus tests are not always the best way to fully understand a
> > > > > >     memory model, so this patch also includes Documentation/explanation.txt,
> > > > > >     which describes the memory model in detail.  In addition,
> > > > > >     Documentation/recipes.txt provides example known-good and known-bad use
> > > > > >     cases for those who prefer working by example.
> > > > > >     
> > > > > >     This patch also includes a few sample litmus tests, and a great many
> > > > > >     more litmus tests are available at https://github.com/paulmckrcu/litmus.
> > > > > >     
> > > > > >     Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
> > > > > >     Signed-off-by: Andrea Parri <parri.andrea@gmail.com>
> > > > > >     Signed-off-by: Will Deacon <will.deacon@arm.com>
> > > > > >     Signed-off-by: Peter Zijlstra <peterz@infradead.org>
> > > > > >     Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
> > > > > >     Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
> > > > > >     Signed-off-by: David Howells <dhowells@redhat.com>
> > > > > >     Signed-off-by: Jade Alglave <j.alglave@ucl.ac.uk>
> > > > > >     Signed-off-by: Luc Maranget <luc.maranget@inria.fr>
> > > > > >     Signed-off-by: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
> > > > > >     Cc: <linux-arch@vger.kernel.org>
> > > > > 
> > > > > So I think that SoB chains like that are utter crap. I think you meant
> > > > > to have all but the one from you be an Ack or similar.
> > > > 
> > > > That's right.  Git doesn't understand the concept of multiple
> > > > authorship.  Accepted practice is to have one Signed-off-by line and a
> > > > bunch of Acked-by or Reviewed-by tags.
> > > > 
> > > > When there's a chain of Signed-off-by tags, it means the first person 
> > > > was the author, who submitted it to the second person's tree, and it 
> > > > went from there to the third person's tree, etc. (which would imply 
> > > > multiple levels of maintainers and submaintainers).
> > > 
> > > I could add a paragraph just before the Signed-off-by/Acked-by/etc.
> > > block describing the roles and contributions, convert the people who
> > > were directly involved to Reviewed-by and everyone else to Acked-by
> > > (unless they explicitly provided a Reviewed-by).
> > > 
> > > Would that work, or does someone have a better approach?
> > 
> 
> How about using the shiny new "Co-Developed-by"?
> 
> 	https://marc.info/?l=linux-kernel&m=151083859723653&w=2

This seems to be exactly what we were looking for/we needed. Altought
still undocumented in "mainline", the tag has already found some uses
in the past, and it appears in its commit log. I've just modified com-
mit-log.txt in the "memory-model" repo. to adopt this tag.


> 
> Besides, as you know, I've been following and learning a lot from this
> model from maybe very beginning, and I have read throught the documents
> and cat files, and even got a chance to verify some RCU-involved code
> with Andrea using this model ;-) So feel free to add:
> 
> Reviewed-by: Boqun Feng <boqun.feng@gmail.com>

Added. Thanks,

  Andrea


> 
> Regards,
> Boqun
> 
> > Hearing no objections, here is an updated prototype patch.  Thank you
> > all for the review, comments, and updates!
> > 
> > 							Thanx, Paul
> > 
> > ------------------------------------------------------------------------
> > 
> > commit 869b3c396eb908e3dfafbd75ed33421b3bcd50bf
> > Author: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> > Date:   Mon Nov 13 10:30:07 2017 -0800
> > 
> >     tools: Automate memory-barriers.txt; provide Linux-kernel memory model
> >     
> >     There is some reason to believe that Documentation/memory-barriers.txt
> >     could use some help, and a major purpose of this patch is to provide
> >     that help in the form of a design-time tool that can produce all valid
> >     executions of a small fragment of concurrent Linux-kernel code, which is
> >     called a "litmus test".  This tool's functionality is roughly similar to
> >     a full state-space search.  Please note that this is a design-time tool,
> >     not useful for regression testing.  However, we hope that the underlying
> >     Linux-kernel memory model will be incorporated into other tools capable
> >     of analyzing large bodies of code for regression-testing purposes.
> >     
> >     The main tool is herd7, together with the linux-kernel.bell,
> >     linux-kernel.cat, linux-kernel.cfg, linux-kernel.def, and lock.cat files
> >     added by this patch.  The herd7 executable takes the other files as input,
> >     and all of these files collectively define the Linux-kernel memory memory
> >     model.  A brief description of each of these other files is provided
> >     in the README file.  Although this tool does have its limitations,
> >     which are documented in the README file, it does improve on the version
> >     reported on in the LWN series (https://lwn.net/Articles/718628/ and
> >     https://lwn.net/Articles/720550/) by supporting locking and arithmetic,
> >     including a much wider variety of read-modify-write atomic operations.
> >     Please note that herd7 is not part of this submission, but is freely
> >     available from http://diy.inria.fr/sources/index.html (and via "git"
> >     at https://github.com/herd/herdtools7).
> >     
> >     A second tool is klitmus7, which converts litmus tests to loadable
> >     kernel modules for direct testing.  As with herd7, the klitmus7
> >     code is freely available from http://diy.inria.fr/sources/index.html
> >     (and via "git" at https://github.com/herd/herdtools7).
> >     
> >     Of course, litmus tests are not always the best way to fully understand a
> >     memory model, so this patch also includes Documentation/explanation.txt,
> >     which describes the memory model in detail.  In addition,
> >     Documentation/recipes.txt provides example known-good and known-bad use
> >     cases for those who prefer working by example.
> >     
> >     This patch also includes a few sample litmus tests, and a great many
> >     more litmus tests are available at https://github.com/paulmckrcu/litmus.
> >     
> >     This patch was the result of a most excellent collaboration founded
> >     by Jade Alglave and also including Alan Stern, Andrea Parri, and Luc
> >     Maranget.  For more details on the history of this collaboration, please
> >     refer to the Linux-kernel memory model presentations at 2016 LinuxCon EU,
> >     2016 Kernel Summit, 2016 Linux Plumbers Conference, 2017 linux.conf.au,
> >     or 2017 Linux Plumbers Conference microconference.
> >     
> >     Reviewed-by: Alan Stern <stern@rowland.harvard.edu>
> >     Reviewed-by: Andrea Parri <parri.andrea@gmail.com>
> >     Reviewed-by: Jade Alglave <j.alglave@ucl.ac.uk>
> >     Reviewed-by: Luc Maranget <luc.maranget@inria.fr>
> >     Signed-off-by: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
> >     Acked-by: Will Deacon <will.deacon@arm.com>
> >     Acked-by: Peter Zijlstra <peterz@infradead.org>
> >     Acked-by: Boqun Feng <boqun.feng@gmail.com>
> >     Acked-by: Nicholas Piggin <npiggin@gmail.com>
> >     Acked-by: David Howells <dhowells@redhat.com>
> >     Acked-by: "Reshetova, Elena" <elena.reshetova@intel.com>
> >     Cc: <linux-arch@vger.kernel.org>
> > 
> [...]