Doc updates to /dev branch
Subsystems (2)
v2 cover Doc updates to /dev branch
This series fixes the rcu/dev branch with the new ReST conversion patches.
Only changes are to documentation.
thanks,
- Joel
Joel Fernandes (Google) (6):
Revert docs from "rcu: Restore barrier() to rcu_read_lock() and rcu_read_unlock()"
Revert docs from "treewide: Rename rcu_dereference_raw_notrace() to _check()"
docs: rcu: Correct links referring to titles
docs: rcu: Increase toctree to 3
Restore docs "treewide: Rename rcu_dereference_raw_notrace() to _check()"
Restore docs "rcu: Restore barrier() to rcu_read_lock() and rcu_read_unlock()"
Mauro Carvalho Chehab (1):
docs: rcu: convert some articles from html to ReST
.../Data-Structures/Data-Structures.html | 1391 ------- .../Data-Structures/Data-Structures.rst | 1163 ++++++ .../Expedited-Grace-Periods.html | 668 ---- .../Expedited-Grace-Periods.rst | 521 +++ .../Memory-Ordering/Tree-RCU-Diagram.html | 9 - .../Tree-RCU-Memory-Ordering.html | 704 ---- .../Tree-RCU-Memory-Ordering.rst | 624 +++ .../RCU/Design/Requirements/Requirements.html | 3401 ----------------- .../RCU/Design/Requirements/Requirements.rst | 2704 +++++++++++++ Documentation/RCU/index.rst | 7 +- Documentation/RCU/whatisRCU.txt | 4 +- 11 files changed, 5020 insertions(+), 6176 deletions(-)
delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst delete mode 100644 Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html create mode 100644 Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html create mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
--
2.22.0.770.g0f2c4a37fd-goog
PATCH v2 1/7 Revert docs from "rcu: Restore barrier() to rcu_read_lock() and rcu_read_unlock()"
This reverts docs from commit d6b9cd7dc8e041ee83cb1362fce59a3cdb1f2709.
--- .../RCU/Design/Requirements/Requirements.html | 71 ------------------- 1 file changed, 71 deletions(-)
Documentation/RCU/Design/Requirements/Requirements.html +0 -71
@@ -2129,8 +2129,6 @@ Some of the relevant points of interest are as follows: <li> <a href="#Hotplug CPU">Hotplug CPU</a>. <li> <a href="#Scheduler and RCU">Scheduler and RCU</a>. <li> <a href="#Tracing and RCU">Tracing and RCU</a>. -<li> <a href="#Accesses to User Memory and RCU"> -Accesses to User Memory and RCU</a>. <li> <a href="#Energy Efficiency">Energy Efficiency</a>. <li> <a href="#Scheduling-Clock Interrupts and RCU"> Scheduling-Clock Interrupts and RCU</a>.
@@ -2523,75 +2521,6 @@ cannot be used. The tracing folks both located the requirement and provided the needed fix, so this surprise requirement was relatively painless. -<h3><a name="Accesses to User Memory and RCU"> -Accesses to User Memory and RCU</a></h3> - -<p> -The kernel needs to access user-space memory, for example, to access -data referenced by system-call parameters. -The <tt>get_user()</tt> macro does this job. - -<p> -However, user-space memory might well be paged out, which means -that <tt>get_user()</tt> might well page-fault and thus block while -waiting for the resulting I/O to complete. -It would be a very bad thing for the compiler to reorder -a <tt>get_user()</tt> invocation into an RCU read-side critical -section. -For example, suppose that the source code looked like this: - -<blockquote> -<pre> - 1 rcu_read_lock(); - 2 p = rcu_dereference(gp); - 3 v = p->value; - 4 rcu_read_unlock(); - 5 get_user(user_v, user_p); - 6 do_something_with(v, user_v); -</pre> -</blockquote> - -<p> -The compiler must not be permitted to transform this source code into -the following: - -<blockquote> -<pre> - 1 rcu_read_lock(); - 2 p = rcu_dereference(gp); - 3 get_user(user_v, user_p); // BUG: POSSIBLE PAGE FAULT!!! - 4 v = p->value; - 5 rcu_read_unlock(); - 6 do_something_with(v, user_v); -</pre> -</blockquote> - -<p> -If the compiler did make this transformation in a -<tt>CONFIG_PREEMPT=n</tt> kernel build, and if <tt>get_user()</tt> did -page fault, the result would be a quiescent state in the middle -of an RCU read-side critical section. -This misplaced quiescent state could result in line 4 being -a use-after-free access, which could be bad for your kernel's -actuarial statistics. -Similar examples can be constructed with the call to <tt>get_user()</tt> -preceding the <tt>rcu_read_lock()</tt>. - -<p> -Unfortunately, <tt>get_user()</tt> doesn't have any particular -ordering properties, and in some architectures the underlying <tt>asm</tt> -isn't even marked <tt>volatile</tt>. -And even if it was marked <tt>volatile</tt>, the above access to -<tt>p->value</tt> is not volatile, so the compiler would not have any -reason to keep those two accesses in order. - -<p> -Therefore, the Linux-kernel definitions of <tt>rcu_read_lock()</tt> -and <tt>rcu_read_unlock()</tt> must act as compiler barriers, -at least for outermost instances of <tt>rcu_read_lock()</tt> and -<tt>rcu_read_unlock()</tt> within a nested set of RCU read-side critical -sections. - <h3><a name="Energy Efficiency">Energy Efficiency</a></h3> <p>
Signature · 1 line
2.22.0.770.g0f2c4a37fd-goog
PATCH v2 2/7 Revert docs from "treewide: Rename rcu_dereference_raw_notrace() to _check()"
In reply to Joel Fernandes (Google)This reverts docs from commit 355e9972da81e803bbb825b76106ae9b358caf8e.
--- Documentation/RCU/Design/Requirements/Requirements.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/Design/Requirements/Requirements.html +1 -1
@@ -2512,7 +2512,7 @@ disabled across the entire RCU read-side critical section. <p> It is possible to use tracing on RCU code, but tracing itself uses RCU. -For this reason, <tt>rcu_dereference_raw_check()</tt> +For this reason, <tt>rcu_dereference_raw_notrace()</tt> is provided for use by tracing, which avoids the destructive recursion that could otherwise ensue. This API is also used by virtualization in some architectures,
Signature · 1 line
2.22.0.770.g0f2c4a37fd-goog
PATCH v2 4/7 docs: rcu: Correct links referring to titles
In reply to Joel Fernandes (Google)Mauro's auto conversion broken these links, fix them.
--- .../Tree-RCU-Memory-Ordering.rst | 17 ++-- .../RCU/Design/Requirements/Requirements.rst | 90 ++++++++----------- 2 files changed, 47 insertions(+), 60 deletions(-)
Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst +8 -9
@@ -230,15 +230,14 @@ Tree RCU Grace Period Memory Ordering Components Tree RCU's grace-period memory-ordering guarantee is provided by a number of RCU components: -#. `Callback Registry <#Callback%20Registry>`__ -#. `Grace-Period Initialization <#Grace-Period%20Initialization>`__ -#. `Self-Reported Quiescent - States <#Self-Reported%20Quiescent%20States>`__ -#. `Dynamic Tick Interface <#Dynamic%20Tick%20Interface>`__ -#. `CPU-Hotplug Interface <#CPU-Hotplug%20Interface>`__ -#. `Forcing Quiescent States <Forcing%20Quiescent%20States>`__ -#. `Grace-Period Cleanup <Grace-Period%20Cleanup>`__ -#. `Callback Invocation <Callback%20Invocation>`__ +#. `Callback Registry`_ +#. `Grace-Period Initialization`_ +#. `Self-Reported Quiescent States`_ +#. `Dynamic Tick Interface`_ +#. `CPU-Hotplug Interface`_ +#. `Forcing Quiescent States`_ +#. `Grace-Period Cleanup`_ +#. `Callback Invocation`_ Each of the following section looks at the corresponding component in detail.
Documentation/RCU/Design/Requirements/Requirements.rst +39 -51
126 lines not on this page · raw message
Signature · 1 line
2.22.0.770.g0f2c4a37fd-goog
PATCH v2 5/7 docs: rcu: Increase toctree to 3
In reply to Joel Fernandes (Google)These documents are long and have various sections. Provide a good toc nesting level.
--- Documentation/RCU/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/index.rst +1 -1
@@ -5,7 +5,7 @@ RCU concepts ============ .. toctree:: - :maxdepth: 1 + :maxdepth: 3 rcu listRCU
Signature · 1 line
2.22.0.770.g0f2c4a37fd-goog
PATCH v2 6/7 Restore docs "treewide: Rename rcu_dereference_raw_notrace() to _check()"
In reply to Joel Fernandes (Google)This restores docs back in ReST format.
--- Documentation/RCU/Design/Requirements/Requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/Design/Requirements/Requirements.rst +1 -1
@@ -1997,7 +1997,7 @@ Tracing and RCU ~~~~~~~~~~~~~~~ It is possible to use tracing on RCU code, but tracing itself uses RCU. -For this reason, ``rcu_dereference_raw_notrace()`` is provided for use +For this reason, ``rcu_dereference_raw_check()`` is provided for use by tracing, which avoids the destructive recursion that could otherwise ensue. This API is also used by virtualization in some architectures, where RCU readers execute in environments in which tracing cannot be
Signature · 1 line
2.22.0.770.g0f2c4a37fd-goog
PATCH v2 7/7 Restore docs "rcu: Restore barrier() to rcu_read_lock() and rcu_read_unlock()"
In reply to Joel Fernandes (Google)This restores docs back in ReST format.
--- .../RCU/Design/Requirements/Requirements.rst | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+)
Documentation/RCU/Design/Requirements/Requirements.rst +54 -0
@@ -1691,6 +1691,7 @@ follows: #. `Hotplug CPU`_ #. `Scheduler and RCU`_ #. `Tracing and RCU`_ +#. `Accesses to User Memory and RCU`_ #. `Energy Efficiency`_ #. `Scheduling-Clock Interrupts and RCU`_ #. `Memory Efficiency`_
@@ -2004,6 +2005,59 @@ where RCU readers execute in environments in which tracing cannot be used. The tracing folks both located the requirement and provided the needed fix, so this surprise requirement was relatively painless. +Accesses to User Memory and RCU +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The kernel needs to access user-space memory, for example, to access data +referenced by system-call parameters. The ``get_user()`` macro does this job. + +However, user-space memory might well be paged out, which means that +``get_user()`` might well page-fault and thus block while waiting for the +resulting I/O to complete. It would be a very bad thing for the compiler to +reorder a ``get_user()`` invocation into an RCU read-side critical section. + +For example, suppose that the source code looked like this: + + :: + + 1 rcu_read_lock(); + 2 p = rcu_dereference(gp); + 3 v = p->value; + 4 rcu_read_unlock(); + 5 get_user(user_v, user_p); + 6 do_something_with(v, user_v); + +The compiler must not be permitted to transform this source code into +the following: + + :: + + 1 rcu_read_lock(); + 2 p = rcu_dereference(gp); + 3 get_user(user_v, user_p); // BUG: POSSIBLE PAGE FAULT!!! + 4 v = p->value; + 5 rcu_read_unlock(); + 6 do_something_with(v, user_v); + +If the compiler did make this transformation in a ``CONFIG_PREEMPT=n`` kernel +build, and if ``get_user()`` did page fault, the result would be a quiescent +state in the middle of an RCU read-side critical section. This misplaced +quiescent state could result in line 4 being a use-after-free access, +which could be bad for your kernel's actuarial statistics. Similar examples +can be constructed with the call to ``get_user()`` preceding the +``rcu_read_lock()``. + +Unfortunately, ``get_user()`` doesn't have any particular ordering properties, +and in some architectures the underlying ``asm`` isn't even marked +``volatile``. And even if it was marked ``volatile``, the above access to +``p->value`` is not volatile, so the compiler would not have any reason to keep +those two accesses in order. + +Therefore, the Linux-kernel definitions of ``rcu_read_lock()`` and +``rcu_read_unlock()`` must act as compiler barriers, at least for outermost +instances of ``rcu_read_lock()`` and ``rcu_read_unlock()`` within a nested set +of RCU read-side critical sections. + Energy Efficiency ~~~~~~~~~~~~~~~~~
Signature · 1 line
2.22.0.770.g0f2c4a37fd-goog
Quoted 3 lines · Joel Fernandes (Google)
This series fixes the rcu/dev branch with the new ReST conversion patches.
And as always, the patch 3/7 made it only to patchwork ;-)
https://lore.kernel.org/patchwork/patch/1109660/