Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-11 14:42:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: Record bottom-bit-zero guarantee for ->next

Browse Source 
This commit records RCU's guarantee that the bottom bit of the rcu_head
structure's ->next field will remain zero for callbacks posted via
call_rcu(), but not necessarily for <tt>kfree_rcu()</tt> or some
possible future call_rcu_lazy() variant that might one day be created
for energy-efficiency purposese.

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
[ paulmck: Updates URLs as suggested by Josh Triplett. ]
This commit is contained in:
Paul E. McKenney 2015-10-07 15:06:44 -07:00
parent 649e4368ff
commit 701e80312f
2 changed files with 86 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
Documentation/RCU/Design/Requirements/Requirements.html
View File

@ -1678,6 +1678,7 @@ Some of the relevant points of interest are as follows:
<li> <a href="#Scheduler and RCU">Scheduler and RCU</a>.
<li> <a href="#Tracing and RCU">Tracing and RCU</a>.
<li> <a href="#Energy Efficiency">Energy Efficiency</a>.
<li> <a href="#Memory Efficiency">Memory Efficiency</a>.
<li> <a href="#Performance, Scalability, Response Time, and Reliability">
Performance, Scalability, Response Time, and Reliability</a>.
</ol>
@ -2006,6 +2007,48 @@ I learned of many of these requirements via angry phone calls:
Flaming me on the Linux-kernel mailing list was apparently not
sufficient to fully vent their ire at RCU's energy-efficiency bugs!
<h3><a name="Memory Efficiency">Memory Efficiency</a></h3>
<p>
Although small-memory non-realtime systems can simply use Tiny RCU,
code size is only one aspect of memory efficiency.
Another aspect is the size of the <tt>rcu_head</tt> structure
used by <tt>call_rcu()</tt> and <tt>kfree_rcu()</tt>.
Although this structure contains nothing more than a pair of pointers,
it does appear in many RCU-protected data structures, including
some that are size critical.
The <tt>page</tt> structure is a case in point, as evidenced by
the many occurrences of the <tt>union</tt> keyword within that structure.
<p>
This need for memory efficiency is one reason that RCU uses hand-crafted
singly linked lists to track the <tt>rcu_head</tt> structures that
are waiting for a grace period to elapse.
It is also the reason why <tt>rcu_head</tt> structures do not contain
debug information, such as fields tracking the file and line of the
<tt>call_rcu()</tt> or <tt>kfree_rcu()</tt> that posted them.
Although this information might appear in debug-only kernel builds at some
point, in the meantime, the <tt>-&gt;func</tt> field will often provide
the needed debug information.
<p>
However, in some cases, the need for memory efficiency leads to even
more extreme measures.
Returning to the <tt>page</tt> structure, the <tt>rcu_head</tt> field
shares storage with a great many other structures that are used at
various points in the corresponding page's lifetime.
In order to correctly resolve certain
<a href="https://lkml.kernel.org/g/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com">race conditions</a>,
the Linux kernel's memory-management subsystem needs a particular bit
to remain zero during all phases of grace-period processing,
and that bit happens to map to the bottom bit of the
<tt>rcu_head</tt> structure's <tt>-&gt;next</tt> field.
RCU makes this guarantee as long as <tt>call_rcu()</tt>
is used to post the callback, as opposed to <tt>kfree_rcu()</tt>
or some future &ldquo;lazy&rdquo;
variant of <tt>call_rcu()</tt> that might one day be created for
energy-efficiency purposes.
<h3><a name="Performance, Scalability, Response Time, and Reliability">
Performance, Scalability, Response Time, and Reliability</a></h3>

43
Documentation/RCU/Design/Requirements/Requirements.htmlx
View File

@ -1837,6 +1837,7 @@ Some of the relevant points of interest are as follows:
<li> <a href="#Scheduler and RCU">Scheduler and RCU</a>.
<li> <a href="#Tracing and RCU">Tracing and RCU</a>.
<li> <a href="#Energy Efficiency">Energy Efficiency</a>.
<li> <a href="#Memory Efficiency">Memory Efficiency</a>.
<li> <a href="#Performance, Scalability, Response Time, and Reliability">
Performance, Scalability, Response Time, and Reliability</a>.
</ol>
@ -2173,6 +2174,48 @@ I learned of many of these requirements via angry phone calls:
Flaming me on the Linux-kernel mailing list was apparently not
sufficient to fully vent their ire at RCU's energy-efficiency bugs!
<h3><a name="Memory Efficiency">Memory Efficiency</a></h3>
<p>
Although small-memory non-realtime systems can simply use Tiny RCU,
code size is only one aspect of memory efficiency.
Another aspect is the size of the <tt>rcu_head</tt> structure
used by <tt>call_rcu()</tt> and <tt>kfree_rcu()</tt>.
Although this structure contains nothing more than a pair of pointers,
it does appear in many RCU-protected data structures, including
some that are size critical.
The <tt>page</tt> structure is a case in point, as evidenced by
the many occurrences of the <tt>union</tt> keyword within that structure.
<p>
This need for memory efficiency is one reason that RCU uses hand-crafted
singly linked lists to track the <tt>rcu_head</tt> structures that
are waiting for a grace period to elapse.
It is also the reason why <tt>rcu_head</tt> structures do not contain
debug information, such as fields tracking the file and line of the
<tt>call_rcu()</tt> or <tt>kfree_rcu()</tt> that posted them.
Although this information might appear in debug-only kernel builds at some
point, in the meantime, the <tt>-&gt;func</tt> field will often provide
the needed debug information.
<p>
However, in some cases, the need for memory efficiency leads to even
more extreme measures.
Returning to the <tt>page</tt> structure, the <tt>rcu_head</tt> field
shares storage with a great many other structures that are used at
various points in the corresponding page's lifetime.
In order to correctly resolve certain
<a href="https://lkml.kernel.org/g/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com">race conditions</a>,
the Linux kernel's memory-management subsystem needs a particular bit
to remain zero during all phases of grace-period processing,
and that bit happens to map to the bottom bit of the
<tt>rcu_head</tt> structure's <tt>-&gt;next</tt> field.
RCU makes this guarantee as long as <tt>call_rcu()</tt>
is used to post the callback, as opposed to <tt>kfree_rcu()</tt>
or some future &ldquo;lazy&rdquo;
variant of <tt>call_rcu()</tt> that might one day be created for
energy-efficiency purposes.
<h3><a name="Performance, Scalability, Response Time, and Reliability">
Performance, Scalability, Response Time, and Reliability</a></h3>