From: paulmck@kernel.org
To: rcu@vger.kernel.org
Cc: linux-kernel@vger.kernel.org, kernel-team@fb.com,
mingo@kernel.org, jiangshanlai@gmail.com, dipankar@in.ibm.com,
akpm@linux-foundation.org, mathieu.desnoyers@efficios.com,
josh@joshtriplett.org, tglx@linutronix.de, peterz@infradead.org,
rostedt@goodmis.org, dhowells@redhat.com, edumazet@google.com,
fweisbec@gmail.com, oleg@redhat.com, joel@joelfernandes.org,
Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>,
"Paul E . McKenney" <paulmck@kernel.org>
Subject: [PATCH tip/core/rcu 2/7] doc: Converted NMI-RCU.txt to NMI-RCU.rst.
Date: Mon, 9 Dec 2019 19:56:36 -0800 [thread overview]
Message-ID: <20191210035641.2226-2-paulmck@kernel.org> (raw)
In-Reply-To: <20191210035539.GA792@paulmck-ThinkPad-P72>
From: Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>
This patch converts NMI-RCU from txt to rst format.
Also adds NMI-RCU in the index.rst file.
Signed-off-by: Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>
[ paulmck: Apply feedback from Phong Tran. ]
Tested-by: Phong Tran <tranmanphong@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
---
Documentation/RCU/{NMI-RCU.txt => NMI-RCU.rst} | 53 ++++++++++++++------------
Documentation/RCU/index.rst | 1 +
2 files changed, 29 insertions(+), 25 deletions(-)
rename Documentation/RCU/{NMI-RCU.txt => NMI-RCU.rst} (73%)
diff --git a/Documentation/RCU/NMI-RCU.txt b/Documentation/RCU/NMI-RCU.rst
similarity index 73%
rename from Documentation/RCU/NMI-RCU.txt
rename to Documentation/RCU/NMI-RCU.rst
index 881353f..1809583 100644
--- a/Documentation/RCU/NMI-RCU.txt
+++ b/Documentation/RCU/NMI-RCU.rst
@@ -1,4 +1,7 @@
+.. _NMI_rcu_doc:
+
Using RCU to Protect Dynamic NMI Handlers
+=========================================
Although RCU is usually used to protect read-mostly data structures,
@@ -9,7 +12,7 @@ work in "arch/x86/oprofile/nmi_timer_int.c" and in
"arch/x86/kernel/traps.c".
The relevant pieces of code are listed below, each followed by a
-brief explanation.
+brief explanation::
static int dummy_nmi_callback(struct pt_regs *regs, int cpu)
{
@@ -18,12 +21,12 @@ brief explanation.
The dummy_nmi_callback() function is a "dummy" NMI handler that does
nothing, but returns zero, thus saying that it did nothing, allowing
-the NMI handler to take the default machine-specific action.
+the NMI handler to take the default machine-specific action::
static nmi_callback_t nmi_callback = dummy_nmi_callback;
This nmi_callback variable is a global function pointer to the current
-NMI handler.
+NMI handler::
void do_nmi(struct pt_regs * regs, long error_code)
{
@@ -53,11 +56,12 @@ anyway. However, in practice it is a good documentation aid, particularly
for anyone attempting to do something similar on Alpha or on systems
with aggressive optimizing compilers.
-Quick Quiz: Why might the rcu_dereference_sched() be necessary on Alpha,
- given that the code referenced by the pointer is read-only?
+Quick Quiz:
+ Why might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?
+:ref:`Answer to Quick Quiz <answer_quick_quiz_NMI>`
-Back to the discussion of NMI and RCU...
+Back to the discussion of NMI and RCU::
void set_nmi_callback(nmi_callback_t callback)
{
@@ -68,7 +72,7 @@ The set_nmi_callback() function registers an NMI handler. Note that any
data that is to be used by the callback must be initialized up -before-
the call to set_nmi_callback(). On architectures that do not order
writes, the rcu_assign_pointer() ensures that the NMI handler sees the
-initialized values.
+initialized values::
void unset_nmi_callback(void)
{
@@ -82,7 +86,7 @@ up any data structures used by the old NMI handler until execution
of it completes on all other CPUs.
One way to accomplish this is via synchronize_rcu(), perhaps as
-follows:
+follows::
unset_nmi_callback();
synchronize_rcu();
@@ -98,24 +102,23 @@ to free up the handler's data as soon as synchronize_rcu() returns.
Important note: for this to work, the architecture in question must
invoke nmi_enter() and nmi_exit() on NMI entry and exit, respectively.
+.. _answer_quick_quiz_NMI:
-Answer to Quick Quiz
-
- Why might the rcu_dereference_sched() be necessary on Alpha, given
- that the code referenced by the pointer is read-only?
+Answer to Quick Quiz:
+ Why might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?
- Answer: The caller to set_nmi_callback() might well have
- initialized some data that is to be used by the new NMI
- handler. In this case, the rcu_dereference_sched() would
- be needed, because otherwise a CPU that received an NMI
- just after the new handler was set might see the pointer
- to the new NMI handler, but the old pre-initialized
- version of the handler's data.
+ The caller to set_nmi_callback() might well have
+ initialized some data that is to be used by the new NMI
+ handler. In this case, the rcu_dereference_sched() would
+ be needed, because otherwise a CPU that received an NMI
+ just after the new handler was set might see the pointer
+ to the new NMI handler, but the old pre-initialized
+ version of the handler's data.
- This same sad story can happen on other CPUs when using
- a compiler with aggressive pointer-value speculation
- optimizations.
+ This same sad story can happen on other CPUs when using
+ a compiler with aggressive pointer-value speculation
+ optimizations.
- More important, the rcu_dereference_sched() makes it
- clear to someone reading the code that the pointer is
- being protected by RCU-sched.
+ More important, the rcu_dereference_sched() makes it
+ clear to someone reading the code that the pointer is
+ being protected by RCU-sched.
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 8d20d44..627128c 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -10,6 +10,7 @@ RCU concepts
arrayRCU
rcu
listRCU
+ NMI-RCU
UP
Design/Memory-Ordering/Tree-RCU-Memory-Ordering
--
2.9.5
next prev parent reply other threads:[~2019-12-10 3:56 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-12-10 3:55 [PATCH tip/core/rcu 0/7] Documentation updates for v5.6 Paul E. McKenney
2019-12-10 3:56 ` [PATCH tip/core/rcu 1/7] doc: Convert arrayRCU.txt to arrayRCU.rst paulmck
2019-12-10 3:56 ` paulmck [this message]
2019-12-10 3:56 ` [PATCH tip/core/rcu 3/7] doc: Convert whatisRCU.txt to .rst paulmck
2019-12-10 3:56 ` [PATCH tip/core/rcu 4/7] doc: Convert to rcu_dereference.txt to rcu_dereference.rst paulmck
2019-12-10 3:56 ` [PATCH tip/core/rcu 5/7] doc: Convert to rcubarrier.txt to ReST paulmck
2019-12-10 3:56 ` [PATCH tip/core/rcu 6/7] doc: Updated full list of RCU API in whatisRCU.rst paulmck
2019-12-10 3:56 ` [PATCH tip/core/rcu 7/7] doc: Fix typo s/deference/dereference/ paulmck
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=20191210035641.2226-2-paulmck@kernel.org \
--to=paulmck@kernel.org \
--cc=akpm@linux-foundation.org \
--cc=dhowells@redhat.com \
--cc=dipankar@in.ibm.com \
--cc=edumazet@google.com \
--cc=fweisbec@gmail.com \
--cc=jiangshanlai@gmail.com \
--cc=joel@joelfernandes.org \
--cc=josh@joshtriplett.org \
--cc=kernel-team@fb.com \
--cc=linux-kernel@vger.kernel.org \
--cc=madhuparnabhowmik04@gmail.com \
--cc=mathieu.desnoyers@efficios.com \
--cc=mingo@kernel.org \
--cc=oleg@redhat.com \
--cc=peterz@infradead.org \
--cc=rcu@vger.kernel.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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).