Re: [PATCH tip/core/rcu 1/8] documentation: Record RCU requirements
From: Josh Triplett
Date: Fri Dec 04 2015 - 19:34:53 EST
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>
> + <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?
> +
> +<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?
> +<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
> +<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 '-'.
> +<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.)
> +<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/
> +<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
> +<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/
> +<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.
> +<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/
> +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
> +<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)
- Josh Triplett
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/