Documentation updates for 4.8
Subsystems (2)
cover Documentation updates for 4.8
Hello!
This series provides a few minor documentation updates for RCU:
1. Add reference to the 2014 RCU API LWN article.
2. Add references to 2010 and 2014 Big API Tables.
3. Add RCU_NONIDLE() restrictions to requirements.
4. Fix a typo, courtesy of Eric Engestrom.
I am still harboring fantasies of getting another block of the RCU design documentation done in time for the merge window, but it is currently not yet even ready for review.
Thanx, Paul
------------------------------------------------------------------------
Design/Requirements/Requirements.html | 35 ++++++++++++++++++++++++++++++++++ stallwarn.txt | 2 - whatisRCU.txt | 3 ++ 3 files changed, 39 insertions(+), 1 deletion(-)
PATCH 1/4 documentation: Add reference to 2014 RCU API LWN article
Reported-by Jim Roskind <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/whatisRCU.txt | 1 + 1 file changed, 1 insertion(+)
Documentation/RCU/whatisRCU.txt +1 -0
@@ -5,6 +5,7 @@ to start learning about RCU: 2. What is RCU? Part 2: Usage http://lwn.net/Articles/263130/ 3. RCU part 3: the RCU API http://lwn.net/Articles/264090/ 4. The RCU API, 2010 Edition http://lwn.net/Articles/418853/ +5. The RCU API, 2014 Edition http://lwn.net/Articles/609904/ What is RCU?
Signature · 1 line
2.5.2
PATCH 2/4 documentation: Add references to 2010 and 2014 Big API Tables
In reply to Paul E. McKenneyReported-by Jim Roskind <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/whatisRCU.txt | 2 ++ 1 file changed, 2 insertions(+)
Documentation/RCU/whatisRCU.txt +2 -0
@@ -5,7 +5,9 @@ to start learning about RCU: 2. What is RCU? Part 2: Usage http://lwn.net/Articles/263130/ 3. RCU part 3: the RCU API http://lwn.net/Articles/264090/ 4. The RCU API, 2010 Edition http://lwn.net/Articles/418853/ + 2010 Big API Table http://lwn.net/Articles/419086/ 5. The RCU API, 2014 Edition http://lwn.net/Articles/609904/ + 2014 Big API Table http://lwn.net/Articles/609973/ What is RCU?
Signature · 1 line
2.5.2
PATCH 3/4 documentation: Add RCU_NONIDLE() restrictions to requirements
In reply to Paul E. McKenneySigned-off-by Paul E. McKenney <[email protected]>
--- .../RCU/Design/Requirements/Requirements.html | 35 ++++++++++++++++++++++ 1 file changed, 35 insertions(+)
Documentation/RCU/Design/Requirements/Requirements.html +35 -0
@@ -2391,6 +2391,41 @@ and <tt>RCU_NONIDLE()</tt> on the other while inspecting idle-loop code. Steven Rostedt supplied <tt>_rcuidle</tt> event tracing, which is used quite heavily in the idle loop. +However, there are some restrictions on the code placed within +<tt>RCU_NONIDLE()</tt>: + +<ol> +<li> Blocking is prohibited. + In practice, this is not a serious restriction given that idle + tasks are prohibited from blocking to begin with. +<li> Although nesting <tt>RCU_NONIDLE()</tt> is permited, they cannot + nest indefinitely deeply. + However, given that they can be nested on the order of a million + deep, even on 32-bit systems, this should not be a serious + restriction. + This nesting limit would probably be reached long after the + compiler OOMed or the stack overflowed. +<li> Any code path that enters <tt>RCU_NONIDLE()</tt> must sequence + out of that same <tt>RCU_NONIDLE()</tt>. + For example, the following is grossly illegal: + + <blockquote> + <pre> + 1 RCU_NONIDLE({ + 2 do_something(); + 3 goto bad_idea; /* BUG!!! */ + 4 do_something_else();}); + 5 bad_idea: + </pre> + </blockquote> + + <p> + It is just as illegal to transfer control into the middle of + <tt>RCU_NONIDLE()</tt>'s argument. + Yes, in theory, you could transfer in as long as you also + transferred out, but in practice you could also expect to get sharply + worded review comments. +</ol> <p> It is similarly socially unacceptable to interrupt an
Signature · 1 line
2.5.2
PATCH 4/4 Documentation: Fix spelling mistake
In reply to Paul E. McKenneyFrom: Eric Engestrom <[email protected]>
Signed-off-by Eric Engestrom <[email protected]>
Reviewed-by Josh Triplett <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/stallwarn.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/stallwarn.txt +1 -1
@@ -49,7 +49,7 @@ rcupdate.rcu_task_stall_timeout This boot/sysfs parameter controls the RCU-tasks stall warning interval. A value of zero or less suppresses RCU-tasks stall warnings. A positive value sets the stall-warning interval - in jiffies. An RCU-tasks stall warning starts wtih the line: + in jiffies. An RCU-tasks stall warning starts with the line: INFO: rcu_tasks detected stalls on tasks:
Signature · 1 line
2.5.2