From: Phong Tran <tranmanphong@gmail.com>
To: madhuparnabhowmik04@gmail.com
Cc: paulmck@kernel.org, corbet@lwn.net, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, rcu@vger.kernel.org,
joel@joelfernandes.org,
linux-kernel-mentees@lists.linuxfoundation.org
Subject: Re: [Linux-kernel-mentees] [PATCH] Documentation: RCU: NMI-RCU: Converted NMI-RCU.txt to NMI-RCU.rst.
Date: Tue, 5 Nov 2019 20:40:05 +0700 [thread overview]
Message-ID: <5bab8828-76e4-c67f-5855-ea4e4f43eaa5@gmail.com> (raw)
In-Reply-To: <20191028214252.17580-1-madhuparnabhowmik04@gmail.com>
On 10/29/19 4:42 AM, madhuparnabhowmik04@gmail.com wrote:
> 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>
> -- > .../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 881353fd5bff..da5861f6a433 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.::
>
there is just a minor ":" redundant in html page.There are some same in
this patch.
eg:
brief explanation.:
Other things look good to me.
Tested-by: Phong Tran <tranmanphong@gmail.com>
Regards,
Phong.
> 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 8d20d44f8fd4..627128c230dc 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
>
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
next prev parent reply other threads:[~2019-11-05 13:40 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-10-28 21:42 [Linux-kernel-mentees] [PATCH] Documentation: RCU: NMI-RCU: Converted NMI-RCU.txt to NMI-RCU.rst madhuparnabhowmik04
2019-10-28 21:42 ` madhuparnabhowmik04
2019-10-29 10:06 ` paulmck
2019-10-29 10:06 ` Paul E. McKenney
2019-11-05 13:40 ` Phong Tran [this message]
2019-11-05 13:55 ` Paul E. McKenney
2019-11-05 14:02 ` Phong Tran
2019-11-05 14:05 ` Paul E. McKenney
2019-11-05 21:37 ` Madhuparna Bhowmik
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=5bab8828-76e4-c67f-5855-ea4e4f43eaa5@gmail.com \
--to=tranmanphong@gmail.com \
--cc=corbet@lwn.net \
--cc=joel@joelfernandes.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel-mentees@lists.linuxfoundation.org \
--cc=linux-kernel@vger.kernel.org \
--cc=madhuparnabhowmik04@gmail.com \
--cc=paulmck@kernel.org \
--cc=rcu@vger.kernel.org \
/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).