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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.