From: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
To: Josh Triplett <josh@joshtriplett.org>
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
Date: Fri, 4 Dec 2015 17:54:31 -0800 [thread overview]
Message-ID: <20151205015431.GH28602@linux.vnet.ibm.com> (raw)
In-Reply-To: <20151205003443.GC26663@cloud>
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
next prev parent reply other threads:[~2015-12-05 1:53 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-12-04 23:49 [PATCH tip/core/rcu 0/8] Documentation updates for 4.5 Paul E. McKenney
2015-12-04 23:50 ` [PATCH tip/core/rcu 1/8] documentation: Record RCU requirements Paul E. McKenney
2015-12-05 0:07 ` Josh Triplett
2015-12-05 0:33 ` Paul E. McKenney
2015-12-05 0:38 ` Josh Triplett
2015-12-05 1:56 ` Paul E. McKenney
2015-12-05 21:19 ` Paul E. McKenney
2015-12-05 0:34 ` Josh Triplett
2015-12-05 1:54 ` Paul E. McKenney [this message]
2015-12-05 20:19 ` Paul E. McKenney
2015-12-04 23:50 ` [PATCH tip/core/rcu 2/8] Documentation: Record bottom-bit-zero guarantee for ->next Paul E. McKenney
2015-12-04 23:50 ` [PATCH tip/core/rcu 3/8] documentation: Cover requirements controlling stall warnings Paul E. McKenney
2015-12-04 23:50 ` [PATCH tip/core/rcu 4/8] documentation: Composability analogies Paul E. McKenney
2015-12-04 23:50 ` [PATCH tip/core/rcu 5/8] documentation: Expand on scheduler/RCU deadlock requirements Paul E. McKenney
2015-12-04 23:50 ` [PATCH tip/core/rcu 6/8] documentation: Clarify RCU memory barriers and requirements Paul E. McKenney
2015-12-04 23:50 ` [PATCH tip/core/rcu 7/8] documentation: Update RCU requirements based on expedited changes Paul E. McKenney
2015-12-04 23:50 ` [PATCH tip/core/rcu 8/8] Documentation/memory-barriers.txt: Fix ACCESS_ONCE thinko Paul E. McKenney
2015-12-05 0:42 ` [PATCH tip/core/rcu 0/8] Documentation updates for 4.5 Josh Triplett
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20151205015431.GH28602@linux.vnet.ibm.com \
--to=paulmck@linux.vnet.ibm.com \
--cc=akpm@linux-foundation.org \
--cc=bobby.prani@gmail.com \
--cc=dhowells@redhat.com \
--cc=dipankar@in.ibm.com \
--cc=dvhart@linux.intel.com \
--cc=edumazet@google.com \
--cc=fweisbec@gmail.com \
--cc=jiangshanlai@gmail.com \
--cc=josh@joshtriplett.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mathieu.desnoyers@efficios.com \
--cc=mingo@kernel.org \
--cc=oleg@redhat.com \
--cc=peterz@infradead.org \
--cc=rostedt@goodmis.org \
--cc=tglx@linutronix.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox