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 @@ > > +<!-- DO NOT HAND EDIT. --> > > +<!-- Instead, edit Requirements.htmlx and run 'sh htmlqqz.sh Requirements' > > --> > > +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" > > + "http://www.w3.org/TR/html4/loose.dtd";> > > Nit: these days, this should just be: > <!doctype html>
Will making this change mean that https://validator.w3.org/ will then require me to make a huge quantity of other changes? > > + <html> > > + <head><title>A Tour Through RCU's Requirements [LWN.net]</title> > > + <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; > > charset=iso-8859-1"> > > Is there a good reason to not use charset=utf-8 here? Beats me. Cargo-culted that one. ;-) > > + > > +<h1>A Tour Through RCU's Requirements</h1> > > + > > +<p>Copyright IBM Corporation, 2015</p> > > 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. ;-) > > +<p>Author: Paul E. McKenney</p> > > +<p><i>The initial version of this document appeared in the > > +<a href="http://lwn.net/";>LWN</a> articles > > +<a href="http://lwn.net/Articles/652156/";>here</a>, > > +<a href="http://lwn.net/Articles/652677/";>here</a>, and > > +<a href="http://lwn.net/Articles/653326/";>here</a>.</i></p> > > s/http/https/g Will change. > > +<p> > > +All that aside, here are the categories of currently known RCU > > requirements: > > +</p> > > + > > +<ol> > > +<li> <a href="#Fundamental 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? > > +<p> > > +This is followed by a <a href="#Summary">summary</a>, > > +which is in turn followed by the inevitable > > +<a href="#Answers to Quick Quizzes">answers to the quick quizzes</a>. > > (Note: when editing anchors, don't forget to handle the target of this > in the generation script.) Good point! > > +<p> > > +This scenario resembles one of the first uses of RCU in > > +<a href="http://en.wikipedia.org/wiki/DYNIX";>DYNIX/ptx</a>, > > s/http/https/ Will change globally. > > +<p> > > +However, this temptation must be resisted because there are a > > +surprisingly large number of ways that the compiler > > +(to say nothing of > > +<a href="http://www.openvms.compaq.com/wizard/wiz_2637.html";>DEC Alpha > > CPUs</a>) > > 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. > > +<li> It is also easy to forget to use <tt>rcu_assign_pointer()</tt> > > + and <tt>rcu_dereference()</tt>, perhaps (incorrectly) > > + substituting a simple assignment. > > + To catch this sort of error, a given RCU-protected pointer may be > > + tagged with <tt>__rcu</tt>, after which running sparse > > + with <tt>CONFIG_SPARSE_RCU_POINTER=y</tt> will complain > > + about simple-assignment accesses to that pointer. > > + Arnd Bergmann made me aware of this requirement, and also > > + supplied the needed > > + <a href="http://lwn.net/Articles/376011/";>patch series</a>. > > s/http/https/ > > > +<li> Open-coded use of <tt>rcu_assign_pointer()</tt> and > > + <tt>rcu_dereference()</tt> to create typical linked > > + data structures can be surprisingly error-prone. > > + Therefore, RCU-protected > > + <a href="http://lwn.net/Articles/609973/#RCU List APIs">linked lists</a> > > s/http/https/ Will fix these. > > +<p> > > +This all should be quite obvious, but the fact remains that > > +Linus Torvalds recently had to > > +<a href="http://marc.info/?l=linux-kernel&m=142905739823385";>remind</a> > > +me of this requirement. > > I'd suggest using the lkml.kernel.org redirector for this link, along > with a Message-Id. > > > +<p> > > +The name notwithstanding, some Linux-kernel architectures > > +can have nested NMIs, which RCU must handle correctly. > > +Andy Lutomirski > > +<a href="https://lkml.org/lkml/2014/11/21/642";>surprised me</a> > > +with this requirement; > > +he also kindly surprised me with > > +<a href="https://lkml.org/lkml/2014/11/22/1";>an algorithm</a> > > +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... > > +<p> > > +RCU therefore provides > > +<tt><a href="http://lwn.net/Articles/217484/";>rcu_barrier()</a></tt>, > > s/http/https/ > > > +<p> > > +This pair of mutual scheduler-RCU requirements came as a > > +<a href="http://lwn.net/Articles/453002/";>complete surprise</a>. > > s/http/https/ > > > +This requirement made its presence known after users made it > > +clear that an earlier > > +<a href="http://lwn.net/Articles/107930/";>real-time patch</a> > > s/http/https/ Will fix these. > > +did not meet their needs, in conjunction with some > > +<a href="https://lkml.org/lkml/2005/3/17/199";>RCU issues</a> > > lkml.kernel.org As above. > > +<p> > > +The > > +<a href="http://lwn.net/Articles/609973/#RCU Per-Flavor API Table">RCU-bh > > API</a> > > 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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
