Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755958AbbLEBx5 (ORCPT ); Fri, 4 Dec 2015 20:53:57 -0500 Received: from e32.co.us.ibm.com ([32.97.110.150]:39614 "EHLO e32.co.us.ibm.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751149AbbLEBx4 (ORCPT ); Fri, 4 Dec 2015 20:53:56 -0500 X-IBM-Helo: d03dlp01.boulder.ibm.com X-IBM-MailFrom: paulmck@linux.vnet.ibm.com X-IBM-RcptTo: linux-kernel@vger.kernel.org Date: Fri, 4 Dec 2015 17:54:31 -0800 From: "Paul E. McKenney" To: Josh Triplett Cc: linux-kernel@vger.kernel.org, mingo@kernel.org, jiangshanlai@gmail.com, dipankar@in.ibm.com, akpm@linux-foundation.org, mathieu.desnoyers@efficios.com, tglx@linutronix.de, peterz@infradead.org, rostedt@goodmis.org, dhowells@redhat.com, edumazet@google.com, dvhart@linux.intel.com, fweisbec@gmail.com, oleg@redhat.com, bobby.prani@gmail.com Subject: Re: [PATCH tip/core/rcu 1/8] documentation: Record RCU requirements Message-ID: <20151205015431.GH28602@linux.vnet.ibm.com> Reply-To: paulmck@linux.vnet.ibm.com References: <20151204234952.GA22805@linux.vnet.ibm.com> <1449273026-23633-1-git-send-email-paulmck@linux.vnet.ibm.com> <20151205003443.GC26663@cloud> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20151205003443.GC26663@cloud> User-Agent: Mutt/1.5.21 (2010-09-15) X-TM-AS-MML: disable X-Content-Scanned: Fidelis XPS MAILER x-cbid: 15120501-0005-0000-0000-00001A5BD38A Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 6384 Lines: 188 On Fri, Dec 04, 2015 at 04:34:43PM -0800, Josh Triplett wrote: > The content of the document seems fine; a few comments below on > meta-issues. > > On Fri, Dec 04, 2015 at 03:50:19PM -0800, Paul E. McKenney wrote: > > --- /dev/null > > +++ b/Documentation/RCU/Design/Requirements/Requirements.html > > @@ -0,0 +1,2799 @@ > > + > > + > > + > + "http://www.w3.org/TR/html4/loose.dtd"> > > Nit: these days, this should just be: > Will making this change mean that https://validator.w3.org/ will then require me to make a huge quantity of other changes? > > + > > + A Tour Through RCU's Requirements [LWN.net] > > + > > Is there a good reason to not use charset=utf-8 here? Beats me. Cargo-culted that one. ;-) > > + > > +

A Tour Through RCU's Requirements

> > + > > +

> > If you're aiming for a properly formatted copyright notice, the year > typically comes first, followed by the copyright holder. That said, > your corporate guidelines presumably have a specific format; is this > that format? Indeed it is. Between you and IBM Legal, I unfortunately must follow IBM Legal's advice. ;-) > > +

Author: Paul E. McKenney

> > +

The initial version of this document appeared in the > > +LWN articles > > +here, > > +here, and > > +here.

> > s/http/https/g Will change. > > +

> > +All that aside, here are the categories of currently known RCU requirements: > > +

> > + > > +

> > Anchors don't typically have spaces in them. This may work in some > browsers, but it doesn't validate. You should either use %20 or > (better) use a '-'. It did when I validated it via https://validator.w3.org/. Which is why I questioned your changes to the doctype directive. Alternatively, what are you using to validate this? > > +
> > +This is followed by a summary, > > +which is in turn followed by the inevitable > > +answers to the quick quizzes. > > (Note: when editing anchors, don't forget to handle the target of this > in the generation script.) Good point! > > +
> > +This scenario resembles one of the first uses of RCU in > > +DYNIX/ptx, > > s/http/https/ Will change globally. > > +
> > +However, this temptation must be resisted because there are a > > +surprisingly large number of ways that the compiler > > +(to say nothing of > > +DEC Alpha CPUs) > > This link sadly doesn't seem to work anymore; it redirects to HP's > general page on OpenVMS, not a copy of that specific article.o > Use this instead, assuming no current live version exists: > https://web.archive.org/web/20120720095054/http://www.openvms.compaq.com/wizard/wiz_2637.html Good catch! Its new home is http://h71000.www7.hp.com/wizard/wiz_2637.html. > > +
It is also easy to forget to use rcu_assign_pointer() > > + and rcu_dereference(), perhaps (incorrectly) > > + substituting a simple assignment. > > + To catch this sort of error, a given RCU-protected pointer may be > > + tagged with __rcu, after which running sparse > > + with CONFIG_SPARSE_RCU_POINTER=y will complain > > + about simple-assignment accesses to that pointer. > > + Arnd Bergmann made me aware of this requirement, and also > > + supplied the needed > > + patch series. > > s/http/https/ > > > +
Open-coded use of rcu_assign_pointer() and > > + rcu_dereference() to create typical linked > > + data structures can be surprisingly error-prone. > > + Therefore, RCU-protected > > + linked lists > > s/http/https/ Will fix these. > > +
> > +This all should be quite obvious, but the fact remains that > > +Linus Torvalds recently had to > > +remind > > +me of this requirement. > > I'd suggest using the lkml.kernel.org redirector for this link, along > with a Message-Id. > > > +
> > +The name notwithstanding, some Linux-kernel architectures > > +can have nested NMIs, which RCU must handle correctly. > > +Andy Lutomirski > > +surprised me > > +with this requirement; > > +he also kindly surprised me with > > +an algorithm > > +that meets this requirement. > > These links should both use lkml.kernel.org as well. Doubly important > because lkml.org is often down or has broken messages in its archive. Good point, will look into finding the Message-IDs... > > +
> > +RCU therefore provides > > +rcu_barrier(), > > s/http/https/ > > > +
> > +This pair of mutual scheduler-RCU requirements came as a > > +complete surprise. > > s/http/https/ > > > +This requirement made its presence known after users made it > > +clear that an earlier > > +real-time patch > > s/http/https/ Will fix these. > > +did not meet their needs, in conjunction with some > > +RCU issues > > lkml.kernel.org As above. > > +
> > +The > > +RCU-bh API > > s/http/https/ (and the same for all later lwn links in the document) Will fix. Thanx, Paul -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/