Convert RCU API method text to sub-headings and
add hyperlink and superscript to 2 literary notes
under rcu_dereference() section
Signed-off-by: Amol Grover <[email protected]>
---
Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
1 file changed, 28 insertions(+), 6 deletions(-)
diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index ae40c8bcc56c..3cf6e17d0065 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst
@@ -150,6 +150,7 @@ later. See the kernel docbook documentation for more info, or look directly
at the function header comments.
rcu_read_lock()
+^^^^^^^^^^^^^^^
void rcu_read_lock(void);
@@ -164,6 +165,7 @@ rcu_read_lock()
longer-term references to data structures.
rcu_read_unlock()
+^^^^^^^^^^^^^^^^^
void rcu_read_unlock(void);
@@ -172,6 +174,7 @@ rcu_read_unlock()
read-side critical sections may be nested and/or overlapping.
synchronize_rcu()
+^^^^^^^^^^^^^^^^^
void synchronize_rcu(void);
@@ -225,6 +228,7 @@ synchronize_rcu()
checklist.txt for some approaches to limiting the update rate.
rcu_assign_pointer()
+^^^^^^^^^^^^^^^^^^^^
void rcu_assign_pointer(p, typeof(p) v);
@@ -245,6 +249,7 @@ rcu_assign_pointer()
the _rcu list-manipulation primitives such as list_add_rcu().
rcu_dereference()
+^^^^^^^^^^^^^^^^^
typeof(p) rcu_dereference(p);
@@ -279,8 +284,10 @@ rcu_dereference()
if an update happened while in the critical section, and incur
unnecessary overhead on Alpha CPUs.
+.. _back_to_1:
+
Note that the value returned by rcu_dereference() is valid
- only within the enclosing RCU read-side critical section [1].
+ only within the enclosing RCU read-side critical section |cs_1|.
For example, the following is -not- legal::
rcu_read_lock();
@@ -298,15 +305,27 @@ rcu_dereference()
it was acquired is just as illegal as doing so with normal
locking.
+.. _back_to_2:
+
As with rcu_assign_pointer(), an important function of
rcu_dereference() is to document which pointers are protected by
RCU, in particular, flagging a pointer that is subject to changing
at any time, including immediately after the rcu_dereference().
And, again like rcu_assign_pointer(), rcu_dereference() is
typically used indirectly, via the _rcu list-manipulation
- primitives, such as list_for_each_entry_rcu() [2].
+ primitives, such as list_for_each_entry_rcu() |entry_2|.
+
+.. |cs_1| raw:: html
+
+ <a href="#cs"><sup>[1]</sup></a>
+
+.. |entry_2| raw:: html
- [1] The variant rcu_dereference_protected() can be used outside
+ <a href="#entry"><sup>[2]</sup></a>
+
+.. _cs:
+
+ \ :sup:`[1]`\ The variant rcu_dereference_protected() can be used outside
of an RCU read-side critical section as long as the usage is
protected by locks acquired by the update-side code. This variant
avoids the lockdep warning that would happen when using (for
@@ -317,15 +336,18 @@ rcu_dereference()
a lockdep expression to indicate which locks must be acquired
by the caller. If the indicated protection is not provided,
a lockdep splat is emitted. See Documentation/RCU/Design/Requirements/Requirements.rst
- and the API's code comments for more details and example usage.
+ and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
+
+
+.. _entry:
- [2] If the list_for_each_entry_rcu() instance might be used by
+ \ :sup:`[2]`\ If the list_for_each_entry_rcu() instance might be used by
update-side code as well as by RCU readers, then an additional
lockdep expression can be added to its list of arguments.
For example, given an additional "lock_is_held(&mylock)" argument,
the RCU lockdep code would complain only if this instance was
invoked outside of an RCU read-side critical section and without
- the protection of mylock.
+ the protection of mylock. :ref:`back <back_to_2>`
The following diagram shows how each API communicates among the
reader, updater, and reclaimer.
--
2.20.1
On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:
> Convert RCU API method text to sub-headings and
> add hyperlink and superscript to 2 literary notes
> under rcu_dereference() section
>
> Signed-off-by: Amol Grover <[email protected]>
Good stuff, but Phong Tran beat you to it. If you are suggesting
changes to that patch, please send a reply to her email, which
may be found here:
https://lore.kernel.org/lkml/[email protected]/
There are several options for replying to this email listed at the
bottom of that web page.
Thanx, Paul
> ---
> Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
> 1 file changed, 28 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
> index ae40c8bcc56c..3cf6e17d0065 100644
> --- a/Documentation/RCU/whatisRCU.rst
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -150,6 +150,7 @@ later. See the kernel docbook documentation for more info, or look directly
> at the function header comments.
>
> rcu_read_lock()
> +^^^^^^^^^^^^^^^
>
> void rcu_read_lock(void);
>
> @@ -164,6 +165,7 @@ rcu_read_lock()
> longer-term references to data structures.
>
> rcu_read_unlock()
> +^^^^^^^^^^^^^^^^^
>
> void rcu_read_unlock(void);
>
> @@ -172,6 +174,7 @@ rcu_read_unlock()
> read-side critical sections may be nested and/or overlapping.
>
> synchronize_rcu()
> +^^^^^^^^^^^^^^^^^
>
> void synchronize_rcu(void);
>
> @@ -225,6 +228,7 @@ synchronize_rcu()
> checklist.txt for some approaches to limiting the update rate.
>
> rcu_assign_pointer()
> +^^^^^^^^^^^^^^^^^^^^
>
> void rcu_assign_pointer(p, typeof(p) v);
>
> @@ -245,6 +249,7 @@ rcu_assign_pointer()
> the _rcu list-manipulation primitives such as list_add_rcu().
>
> rcu_dereference()
> +^^^^^^^^^^^^^^^^^
>
> typeof(p) rcu_dereference(p);
>
> @@ -279,8 +284,10 @@ rcu_dereference()
> if an update happened while in the critical section, and incur
> unnecessary overhead on Alpha CPUs.
>
> +.. _back_to_1:
> +
> Note that the value returned by rcu_dereference() is valid
> - only within the enclosing RCU read-side critical section [1].
> + only within the enclosing RCU read-side critical section |cs_1|.
> For example, the following is -not- legal::
>
> rcu_read_lock();
> @@ -298,15 +305,27 @@ rcu_dereference()
> it was acquired is just as illegal as doing so with normal
> locking.
>
> +.. _back_to_2:
> +
> As with rcu_assign_pointer(), an important function of
> rcu_dereference() is to document which pointers are protected by
> RCU, in particular, flagging a pointer that is subject to changing
> at any time, including immediately after the rcu_dereference().
> And, again like rcu_assign_pointer(), rcu_dereference() is
> typically used indirectly, via the _rcu list-manipulation
> - primitives, such as list_for_each_entry_rcu() [2].
> + primitives, such as list_for_each_entry_rcu() |entry_2|.
> +
> +.. |cs_1| raw:: html
> +
> + <a href="#cs"><sup>[1]</sup></a>
> +
> +.. |entry_2| raw:: html
>
> - [1] The variant rcu_dereference_protected() can be used outside
> + <a href="#entry"><sup>[2]</sup></a>
> +
> +.. _cs:
> +
> + \ :sup:`[1]`\ The variant rcu_dereference_protected() can be used outside
> of an RCU read-side critical section as long as the usage is
> protected by locks acquired by the update-side code. This variant
> avoids the lockdep warning that would happen when using (for
> @@ -317,15 +336,18 @@ rcu_dereference()
> a lockdep expression to indicate which locks must be acquired
> by the caller. If the indicated protection is not provided,
> a lockdep splat is emitted. See Documentation/RCU/Design/Requirements/Requirements.rst
> - and the API's code comments for more details and example usage.
> + and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
> +
> +
> +.. _entry:
>
> - [2] If the list_for_each_entry_rcu() instance might be used by
> + \ :sup:`[2]`\ If the list_for_each_entry_rcu() instance might be used by
> update-side code as well as by RCU readers, then an additional
> lockdep expression can be added to its list of arguments.
> For example, given an additional "lock_is_held(&mylock)" argument,
> the RCU lockdep code would complain only if this instance was
> invoked outside of an RCU read-side critical section and without
> - the protection of mylock.
> + the protection of mylock. :ref:`back <back_to_2>`
>
> The following diagram shows how each API communicates among the
> reader, updater, and reclaimer.
> --
> 2.20.1
>
On Mon, 04 Nov 2019, Amol Grover <[email protected]> wrote:
> Convert RCU API method text to sub-headings and
> add hyperlink and superscript to 2 literary notes
> under rcu_dereference() section
>
> Signed-off-by: Amol Grover <[email protected]>
> ---
> Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
> 1 file changed, 28 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
> index ae40c8bcc56c..3cf6e17d0065 100644
> --- a/Documentation/RCU/whatisRCU.rst
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -150,6 +150,7 @@ later. See the kernel docbook documentation for more info, or look directly
> at the function header comments.
>
> rcu_read_lock()
> +^^^^^^^^^^^^^^^
>
> void rcu_read_lock(void);
>
> @@ -164,6 +165,7 @@ rcu_read_lock()
> longer-term references to data structures.
>
> rcu_read_unlock()
> +^^^^^^^^^^^^^^^^^
>
> void rcu_read_unlock(void);
>
> @@ -172,6 +174,7 @@ rcu_read_unlock()
> read-side critical sections may be nested and/or overlapping.
>
> synchronize_rcu()
> +^^^^^^^^^^^^^^^^^
>
> void synchronize_rcu(void);
>
> @@ -225,6 +228,7 @@ synchronize_rcu()
> checklist.txt for some approaches to limiting the update rate.
>
> rcu_assign_pointer()
> +^^^^^^^^^^^^^^^^^^^^
>
> void rcu_assign_pointer(p, typeof(p) v);
>
> @@ -245,6 +249,7 @@ rcu_assign_pointer()
> the _rcu list-manipulation primitives such as list_add_rcu().
>
> rcu_dereference()
> +^^^^^^^^^^^^^^^^^
>
> typeof(p) rcu_dereference(p);
>
> @@ -279,8 +284,10 @@ rcu_dereference()
> if an update happened while in the critical section, and incur
> unnecessary overhead on Alpha CPUs.
>
> +.. _back_to_1:
> +
> Note that the value returned by rcu_dereference() is valid
> - only within the enclosing RCU read-side critical section [1].
> + only within the enclosing RCU read-side critical section |cs_1|.
> For example, the following is -not- legal::
>
> rcu_read_lock();
> @@ -298,15 +305,27 @@ rcu_dereference()
> it was acquired is just as illegal as doing so with normal
> locking.
>
> +.. _back_to_2:
> +
> As with rcu_assign_pointer(), an important function of
> rcu_dereference() is to document which pointers are protected by
> RCU, in particular, flagging a pointer that is subject to changing
> at any time, including immediately after the rcu_dereference().
> And, again like rcu_assign_pointer(), rcu_dereference() is
> typically used indirectly, via the _rcu list-manipulation
> - primitives, such as list_for_each_entry_rcu() [2].
> + primitives, such as list_for_each_entry_rcu() |entry_2|.
> +
> +.. |cs_1| raw:: html
Please don't use raw. It's ugly and error prone. We have some raw output
for latex, but this would be the first for html.
What are you trying to achieve?
BR,
Jani.
> +
> + <a href="#cs"><sup>[1]</sup></a>
> +
> +.. |entry_2| raw:: html
>
> - [1] The variant rcu_dereference_protected() can be used outside
> + <a href="#entry"><sup>[2]</sup></a>
> +
> +.. _cs:
> +
> + \ :sup:`[1]`\ The variant rcu_dereference_protected() can be used outside
> of an RCU read-side critical section as long as the usage is
> protected by locks acquired by the update-side code. This variant
> avoids the lockdep warning that would happen when using (for
> @@ -317,15 +336,18 @@ rcu_dereference()
> a lockdep expression to indicate which locks must be acquired
> by the caller. If the indicated protection is not provided,
> a lockdep splat is emitted. See Documentation/RCU/Design/Requirements/Requirements.rst
> - and the API's code comments for more details and example usage.
> + and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
> +
> +
> +.. _entry:
>
> - [2] If the list_for_each_entry_rcu() instance might be used by
> + \ :sup:`[2]`\ If the list_for_each_entry_rcu() instance might be used by
> update-side code as well as by RCU readers, then an additional
> lockdep expression can be added to its list of arguments.
> For example, given an additional "lock_is_held(&mylock)" argument,
> the RCU lockdep code would complain only if this instance was
> invoked outside of an RCU read-side critical section and without
> - the protection of mylock.
> + the protection of mylock. :ref:`back <back_to_2>`
>
> The following diagram shows how each API communicates among the
> reader, updater, and reclaimer.
--
Jani Nikula, Intel Open Source Graphics Center
On Mon, Nov 04, 2019 at 07:03:28AM -0800, Paul E. McKenney wrote:
> On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:
> > Convert RCU API method text to sub-headings and
> > add hyperlink and superscript to 2 literary notes
> > under rcu_dereference() section
> >
> > Signed-off-by: Amol Grover <[email protected]>
>
> Good stuff, but Phong Tran beat you to it. If you are suggesting
> changes to that patch, please send a reply to her email, which
> may be found here:
>
> https://lore.kernel.org/lkml/[email protected]/
>
> There are several options for replying to this email listed at the
> bottom of that web page.
>
> Thanx, Paul
Thank you Paul! And that is correct, I was suggesting changes to
that patch. However, since that patch was already integrated into
the `dev` branch, I mistakenly believed this patch could be sent
independently. Sorry for the trouble, I'll re-send the patch the
correct way.
Thank you
Amol
>
> > ---
> > Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
> > 1 file changed, 28 insertions(+), 6 deletions(-)
> >
> > diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
> > index ae40c8bcc56c..3cf6e17d0065 100644
> > --- a/Documentation/RCU/whatisRCU.rst
> > +++ b/Documentation/RCU/whatisRCU.rst
> > @@ -150,6 +150,7 @@ later. See the kernel docbook documentation for more info, or look directly
> > at the function header comments.
> >
> > rcu_read_lock()
> > +^^^^^^^^^^^^^^^
> >
> > void rcu_read_lock(void);
> >
> > @@ -164,6 +165,7 @@ rcu_read_lock()
> > longer-term references to data structures.
> >
> > rcu_read_unlock()
> > +^^^^^^^^^^^^^^^^^
> >
> > void rcu_read_unlock(void);
> >
> > @@ -172,6 +174,7 @@ rcu_read_unlock()
> > read-side critical sections may be nested and/or overlapping.
> >
> > synchronize_rcu()
> > +^^^^^^^^^^^^^^^^^
> >
> > void synchronize_rcu(void);
> >
> > @@ -225,6 +228,7 @@ synchronize_rcu()
> > checklist.txt for some approaches to limiting the update rate.
> >
> > rcu_assign_pointer()
> > +^^^^^^^^^^^^^^^^^^^^
> >
> > void rcu_assign_pointer(p, typeof(p) v);
> >
> > @@ -245,6 +249,7 @@ rcu_assign_pointer()
> > the _rcu list-manipulation primitives such as list_add_rcu().
> >
> > rcu_dereference()
> > +^^^^^^^^^^^^^^^^^
> >
> > typeof(p) rcu_dereference(p);
> >
> > @@ -279,8 +284,10 @@ rcu_dereference()
> > if an update happened while in the critical section, and incur
> > unnecessary overhead on Alpha CPUs.
> >
> > +.. _back_to_1:
> > +
> > Note that the value returned by rcu_dereference() is valid
> > - only within the enclosing RCU read-side critical section [1].
> > + only within the enclosing RCU read-side critical section |cs_1|.
> > For example, the following is -not- legal::
> >
> > rcu_read_lock();
> > @@ -298,15 +305,27 @@ rcu_dereference()
> > it was acquired is just as illegal as doing so with normal
> > locking.
> >
> > +.. _back_to_2:
> > +
> > As with rcu_assign_pointer(), an important function of
> > rcu_dereference() is to document which pointers are protected by
> > RCU, in particular, flagging a pointer that is subject to changing
> > at any time, including immediately after the rcu_dereference().
> > And, again like rcu_assign_pointer(), rcu_dereference() is
> > typically used indirectly, via the _rcu list-manipulation
> > - primitives, such as list_for_each_entry_rcu() [2].
> > + primitives, such as list_for_each_entry_rcu() |entry_2|.
> > +
> > +.. |cs_1| raw:: html
> > +
> > + <a href="#cs"><sup>[1]</sup></a>
> > +
> > +.. |entry_2| raw:: html
> >
> > - [1] The variant rcu_dereference_protected() can be used outside
> > + <a href="#entry"><sup>[2]</sup></a>
> > +
> > +.. _cs:
> > +
> > + \ :sup:`[1]`\ The variant rcu_dereference_protected() can be used outside
> > of an RCU read-side critical section as long as the usage is
> > protected by locks acquired by the update-side code. This variant
> > avoids the lockdep warning that would happen when using (for
> > @@ -317,15 +336,18 @@ rcu_dereference()
> > a lockdep expression to indicate which locks must be acquired
> > by the caller. If the indicated protection is not provided,
> > a lockdep splat is emitted. See Documentation/RCU/Design/Requirements/Requirements.rst
> > - and the API's code comments for more details and example usage.
> > + and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
> > +
> > +
> > +.. _entry:
> >
> > - [2] If the list_for_each_entry_rcu() instance might be used by
> > + \ :sup:`[2]`\ If the list_for_each_entry_rcu() instance might be used by
> > update-side code as well as by RCU readers, then an additional
> > lockdep expression can be added to its list of arguments.
> > For example, given an additional "lock_is_held(&mylock)" argument,
> > the RCU lockdep code would complain only if this instance was
> > invoked outside of an RCU read-side critical section and without
> > - the protection of mylock.
> > + the protection of mylock. :ref:`back <back_to_2>`
> >
> > The following diagram shows how each API communicates among the
> > reader, updater, and reclaimer.
> > --
> > 2.20.1
> >
On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote:
> On Mon, 04 Nov 2019, Amol Grover <[email protected]> wrote:
> > Convert RCU API method text to sub-headings and
> > add hyperlink and superscript to 2 literary notes
> > under rcu_dereference() section
> >
> > Signed-off-by: Amol Grover <[email protected]>
> > ---
> > Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
> > 1 file changed, 28 insertions(+), 6 deletions(-)
> >
> > diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
> > index ae40c8bcc56c..3cf6e17d0065 100644
> > --- a/Documentation/RCU/whatisRCU.rst
> > +++ b/Documentation/RCU/whatisRCU.rst
> > @@ -150,6 +150,7 @@ later. See the kernel docbook documentation for more info, or look directly
> > at the function header comments.
> >
> > rcu_read_lock()
> > +^^^^^^^^^^^^^^^
> >
> > void rcu_read_lock(void);
> >
> > @@ -164,6 +165,7 @@ rcu_read_lock()
> > longer-term references to data structures.
> >
> > rcu_read_unlock()
> > +^^^^^^^^^^^^^^^^^
> >
> > void rcu_read_unlock(void);
> >
> > @@ -172,6 +174,7 @@ rcu_read_unlock()
> > read-side critical sections may be nested and/or overlapping.
> >
> > synchronize_rcu()
> > +^^^^^^^^^^^^^^^^^
> >
> > void synchronize_rcu(void);
> >
> > @@ -225,6 +228,7 @@ synchronize_rcu()
> > checklist.txt for some approaches to limiting the update rate.
> >
> > rcu_assign_pointer()
> > +^^^^^^^^^^^^^^^^^^^^
> >
> > void rcu_assign_pointer(p, typeof(p) v);
> >
> > @@ -245,6 +249,7 @@ rcu_assign_pointer()
> > the _rcu list-manipulation primitives such as list_add_rcu().
> >
> > rcu_dereference()
> > +^^^^^^^^^^^^^^^^^
> >
> > typeof(p) rcu_dereference(p);
> >
> > @@ -279,8 +284,10 @@ rcu_dereference()
> > if an update happened while in the critical section, and incur
> > unnecessary overhead on Alpha CPUs.
> >
> > +.. _back_to_1:
> > +
> > Note that the value returned by rcu_dereference() is valid
> > - only within the enclosing RCU read-side critical section [1].
> > + only within the enclosing RCU read-side critical section |cs_1|.
> > For example, the following is -not- legal::
> >
> > rcu_read_lock();
> > @@ -298,15 +305,27 @@ rcu_dereference()
> > it was acquired is just as illegal as doing so with normal
> > locking.
> >
> > +.. _back_to_2:
> > +
> > As with rcu_assign_pointer(), an important function of
> > rcu_dereference() is to document which pointers are protected by
> > RCU, in particular, flagging a pointer that is subject to changing
> > at any time, including immediately after the rcu_dereference().
> > And, again like rcu_assign_pointer(), rcu_dereference() is
> > typically used indirectly, via the _rcu list-manipulation
> > - primitives, such as list_for_each_entry_rcu() [2].
> > + primitives, such as list_for_each_entry_rcu() |entry_2|.
> > +
> > +.. |cs_1| raw:: html
>
> Please don't use raw. It's ugly and error prone. We have some raw output
> for latex, but this would be the first for html.
>
> What are you trying to achieve?
Hi Jani,
While going through the documentation I encountered a few footnotes (numbers
[1] and [2]) which referenced the actual footnote somewhere below the text.
They were particularly not straight-forward to find hence I decided to
link them to the footnote text which could be done using inline markup.
Then I tried to make them more appealing by converting to super-scripts
(the way they look like in books and websites). However, nested inline
markup is not yet possible in reST hence I went with the html way to
achieve the same. Too much?
Thank you
Amol
>
> BR,
> Jani.
>
> > +
> > + <a href="#cs"><sup>[1]</sup></a>
> > +
> > +.. |entry_2| raw:: html
> >
> > - [1] The variant rcu_dereference_protected() can be used outside
> > + <a href="#entry"><sup>[2]</sup></a>
> > +
> > +.. _cs:
> > +
> > + \ :sup:`[1]`\ The variant rcu_dereference_protected() can be used outside
> > of an RCU read-side critical section as long as the usage is
> > protected by locks acquired by the update-side code. This variant
> > avoids the lockdep warning that would happen when using (for
> > @@ -317,15 +336,18 @@ rcu_dereference()
> > a lockdep expression to indicate which locks must be acquired
> > by the caller. If the indicated protection is not provided,
> > a lockdep splat is emitted. See Documentation/RCU/Design/Requirements/Requirements.rst
> > - and the API's code comments for more details and example usage.
> > + and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
> > +
> > +
> > +.. _entry:
> >
> > - [2] If the list_for_each_entry_rcu() instance might be used by
> > + \ :sup:`[2]`\ If the list_for_each_entry_rcu() instance might be used by
> > update-side code as well as by RCU readers, then an additional
> > lockdep expression can be added to its list of arguments.
> > For example, given an additional "lock_is_held(&mylock)" argument,
> > the RCU lockdep code would complain only if this instance was
> > invoked outside of an RCU read-side critical section and without
> > - the protection of mylock.
> > + the protection of mylock. :ref:`back <back_to_2>`
> >
> > The following diagram shows how each API communicates among the
> > reader, updater, and reclaimer.
>
> --
> Jani Nikula, Intel Open Source Graphics Center
On Mon, Nov 04, 2019 at 10:46:41PM +0530, Amol Grover wrote:
> On Mon, Nov 04, 2019 at 07:03:28AM -0800, Paul E. McKenney wrote:
> > On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:
> > > Convert RCU API method text to sub-headings and
> > > add hyperlink and superscript to 2 literary notes
> > > under rcu_dereference() section
> > >
> > > Signed-off-by: Amol Grover <[email protected]>
> >
> > Good stuff, but Phong Tran beat you to it. If you are suggesting
> > changes to that patch, please send a reply to her email, which
> > may be found here:
> >
> > https://lore.kernel.org/lkml/[email protected]/
> >
> > There are several options for replying to this email listed at the
> > bottom of that web page.
>
> Thank you Paul! And that is correct, I was suggesting changes to
> that patch. However, since that patch was already integrated into
> the `dev` branch, I mistakenly believed this patch could be sent
> independently. Sorry for the trouble, I'll re-send the patch the
> correct way.
It is of course only polite to include the author of the previous patch
on CC, both using the "Cc: Phong Tran <[email protected]>" tag
following your "Signed-off" by.
Thanx, Paul
> Thank you
> Amol
>
> >
> > > ---
> > > Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
> > > 1 file changed, 28 insertions(+), 6 deletions(-)
> > >
> > > diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
> > > index ae40c8bcc56c..3cf6e17d0065 100644
> > > --- a/Documentation/RCU/whatisRCU.rst
> > > +++ b/Documentation/RCU/whatisRCU.rst
> > > @@ -150,6 +150,7 @@ later. See the kernel docbook documentation for more info, or look directly
> > > at the function header comments.
> > >
> > > rcu_read_lock()
> > > +^^^^^^^^^^^^^^^
> > >
> > > void rcu_read_lock(void);
> > >
> > > @@ -164,6 +165,7 @@ rcu_read_lock()
> > > longer-term references to data structures.
> > >
> > > rcu_read_unlock()
> > > +^^^^^^^^^^^^^^^^^
> > >
> > > void rcu_read_unlock(void);
> > >
> > > @@ -172,6 +174,7 @@ rcu_read_unlock()
> > > read-side critical sections may be nested and/or overlapping.
> > >
> > > synchronize_rcu()
> > > +^^^^^^^^^^^^^^^^^
> > >
> > > void synchronize_rcu(void);
> > >
> > > @@ -225,6 +228,7 @@ synchronize_rcu()
> > > checklist.txt for some approaches to limiting the update rate.
> > >
> > > rcu_assign_pointer()
> > > +^^^^^^^^^^^^^^^^^^^^
> > >
> > > void rcu_assign_pointer(p, typeof(p) v);
> > >
> > > @@ -245,6 +249,7 @@ rcu_assign_pointer()
> > > the _rcu list-manipulation primitives such as list_add_rcu().
> > >
> > > rcu_dereference()
> > > +^^^^^^^^^^^^^^^^^
> > >
> > > typeof(p) rcu_dereference(p);
> > >
> > > @@ -279,8 +284,10 @@ rcu_dereference()
> > > if an update happened while in the critical section, and incur
> > > unnecessary overhead on Alpha CPUs.
> > >
> > > +.. _back_to_1:
> > > +
> > > Note that the value returned by rcu_dereference() is valid
> > > - only within the enclosing RCU read-side critical section [1].
> > > + only within the enclosing RCU read-side critical section |cs_1|.
> > > For example, the following is -not- legal::
> > >
> > > rcu_read_lock();
> > > @@ -298,15 +305,27 @@ rcu_dereference()
> > > it was acquired is just as illegal as doing so with normal
> > > locking.
> > >
> > > +.. _back_to_2:
> > > +
> > > As with rcu_assign_pointer(), an important function of
> > > rcu_dereference() is to document which pointers are protected by
> > > RCU, in particular, flagging a pointer that is subject to changing
> > > at any time, including immediately after the rcu_dereference().
> > > And, again like rcu_assign_pointer(), rcu_dereference() is
> > > typically used indirectly, via the _rcu list-manipulation
> > > - primitives, such as list_for_each_entry_rcu() [2].
> > > + primitives, such as list_for_each_entry_rcu() |entry_2|.
> > > +
> > > +.. |cs_1| raw:: html
> > > +
> > > + <a href="#cs"><sup>[1]</sup></a>
> > > +
> > > +.. |entry_2| raw:: html
> > >
> > > - [1] The variant rcu_dereference_protected() can be used outside
> > > + <a href="#entry"><sup>[2]</sup></a>
> > > +
> > > +.. _cs:
> > > +
> > > + \ :sup:`[1]`\ The variant rcu_dereference_protected() can be used outside
> > > of an RCU read-side critical section as long as the usage is
> > > protected by locks acquired by the update-side code. This variant
> > > avoids the lockdep warning that would happen when using (for
> > > @@ -317,15 +336,18 @@ rcu_dereference()
> > > a lockdep expression to indicate which locks must be acquired
> > > by the caller. If the indicated protection is not provided,
> > > a lockdep splat is emitted. See Documentation/RCU/Design/Requirements/Requirements.rst
> > > - and the API's code comments for more details and example usage.
> > > + and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
> > > +
> > > +
> > > +.. _entry:
> > >
> > > - [2] If the list_for_each_entry_rcu() instance might be used by
> > > + \ :sup:`[2]`\ If the list_for_each_entry_rcu() instance might be used by
> > > update-side code as well as by RCU readers, then an additional
> > > lockdep expression can be added to its list of arguments.
> > > For example, given an additional "lock_is_held(&mylock)" argument,
> > > the RCU lockdep code would complain only if this instance was
> > > invoked outside of an RCU read-side critical section and without
> > > - the protection of mylock.
> > > + the protection of mylock. :ref:`back <back_to_2>`
> > >
> > > The following diagram shows how each API communicates among the
> > > reader, updater, and reclaimer.
> > > --
> > > 2.20.1
> > >
On Mon, 04 Nov 2019, Amol Grover <[email protected]> wrote:
> On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote:
>> On Mon, 04 Nov 2019, Amol Grover <[email protected]> wrote:
>> > Convert RCU API method text to sub-headings and
>> > add hyperlink and superscript to 2 literary notes
>> > under rcu_dereference() section
>> >
>> > Signed-off-by: Amol Grover <[email protected]>
>> > ---
>> > Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
>> > 1 file changed, 28 insertions(+), 6 deletions(-)
>> >
>> > diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
>> > index ae40c8bcc56c..3cf6e17d0065 100644
>> > --- a/Documentation/RCU/whatisRCU.rst
>> > +++ b/Documentation/RCU/whatisRCU.rst
>> > @@ -150,6 +150,7 @@ later. See the kernel docbook documentation for more info, or look directly
>> > at the function header comments.
>> >
>> > rcu_read_lock()
>> > +^^^^^^^^^^^^^^^
>> >
>> > void rcu_read_lock(void);
>> >
>> > @@ -164,6 +165,7 @@ rcu_read_lock()
>> > longer-term references to data structures.
>> >
>> > rcu_read_unlock()
>> > +^^^^^^^^^^^^^^^^^
>> >
>> > void rcu_read_unlock(void);
>> >
>> > @@ -172,6 +174,7 @@ rcu_read_unlock()
>> > read-side critical sections may be nested and/or overlapping.
>> >
>> > synchronize_rcu()
>> > +^^^^^^^^^^^^^^^^^
>> >
>> > void synchronize_rcu(void);
>> >
>> > @@ -225,6 +228,7 @@ synchronize_rcu()
>> > checklist.txt for some approaches to limiting the update rate.
>> >
>> > rcu_assign_pointer()
>> > +^^^^^^^^^^^^^^^^^^^^
>> >
>> > void rcu_assign_pointer(p, typeof(p) v);
>> >
>> > @@ -245,6 +249,7 @@ rcu_assign_pointer()
>> > the _rcu list-manipulation primitives such as list_add_rcu().
>> >
>> > rcu_dereference()
>> > +^^^^^^^^^^^^^^^^^
>> >
>> > typeof(p) rcu_dereference(p);
>> >
>> > @@ -279,8 +284,10 @@ rcu_dereference()
>> > if an update happened while in the critical section, and incur
>> > unnecessary overhead on Alpha CPUs.
>> >
>> > +.. _back_to_1:
>> > +
>> > Note that the value returned by rcu_dereference() is valid
>> > - only within the enclosing RCU read-side critical section [1].
>> > + only within the enclosing RCU read-side critical section |cs_1|.
>> > For example, the following is -not- legal::
>> >
>> > rcu_read_lock();
>> > @@ -298,15 +305,27 @@ rcu_dereference()
>> > it was acquired is just as illegal as doing so with normal
>> > locking.
>> >
>> > +.. _back_to_2:
>> > +
>> > As with rcu_assign_pointer(), an important function of
>> > rcu_dereference() is to document which pointers are protected by
>> > RCU, in particular, flagging a pointer that is subject to changing
>> > at any time, including immediately after the rcu_dereference().
>> > And, again like rcu_assign_pointer(), rcu_dereference() is
>> > typically used indirectly, via the _rcu list-manipulation
>> > - primitives, such as list_for_each_entry_rcu() [2].
>> > + primitives, such as list_for_each_entry_rcu() |entry_2|.
>> > +
>> > +.. |cs_1| raw:: html
>>
>> Please don't use raw. It's ugly and error prone. We have some raw output
>> for latex, but this would be the first for html.
>>
>> What are you trying to achieve?
>
> Hi Jani,
> While going through the documentation I encountered a few footnotes (numbers
> [1] and [2]) which referenced the actual footnote somewhere below the text.
> They were particularly not straight-forward to find hence I decided to
> link them to the footnote text which could be done using inline markup.
> Then I tried to make them more appealing by converting to super-scripts
> (the way they look like in books and websites). However, nested inline
> markup is not yet possible in reST hence I went with the html way to
> achieve the same. Too much?
I suggest you use rst footnote markup. It's less of an eye sore in the
rst source, but provides you with the links in the generated output. And
typically would be superscript. In particular "autonumber labels" might
fit the bill. [1][2]
BR,
Jani.
[1] http://docutils.sourceforge.net/docs/user/rst/quickref.html#footnotes
[2] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#footnotes
>
> Thank you
> Amol
>
>>
>> BR,
>> Jani.
>>
>> > +
>> > + <a href="#cs"><sup>[1]</sup></a>
>> > +
>> > +.. |entry_2| raw:: html
>> >
>> > - [1] The variant rcu_dereference_protected() can be used outside
>> > + <a href="#entry"><sup>[2]</sup></a>
>> > +
>> > +.. _cs:
>> > +
>> > + \ :sup:`[1]`\ The variant rcu_dereference_protected() can be used outside
>> > of an RCU read-side critical section as long as the usage is
>> > protected by locks acquired by the update-side code. This variant
>> > avoids the lockdep warning that would happen when using (for
>> > @@ -317,15 +336,18 @@ rcu_dereference()
>> > a lockdep expression to indicate which locks must be acquired
>> > by the caller. If the indicated protection is not provided,
>> > a lockdep splat is emitted. See Documentation/RCU/Design/Requirements/Requirements.rst
>> > - and the API's code comments for more details and example usage.
>> > + and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
>> > +
>> > +
>> > +.. _entry:
>> >
>> > - [2] If the list_for_each_entry_rcu() instance might be used by
>> > + \ :sup:`[2]`\ If the list_for_each_entry_rcu() instance might be used by
>> > update-side code as well as by RCU readers, then an additional
>> > lockdep expression can be added to its list of arguments.
>> > For example, given an additional "lock_is_held(&mylock)" argument,
>> > the RCU lockdep code would complain only if this instance was
>> > invoked outside of an RCU read-side critical section and without
>> > - the protection of mylock.
>> > + the protection of mylock. :ref:`back <back_to_2>`
>> >
>> > The following diagram shows how each API communicates among the
>> > reader, updater, and reclaimer.
>>
>> --
>> Jani Nikula, Intel Open Source Graphics Center
--
Jani Nikula, Intel Open Source Graphics Center
On Tue, Nov 05, 2019 at 08:08:50AM +0200, Jani Nikula wrote:
> On Mon, 04 Nov 2019, Amol Grover <[email protected]> wrote:
> > On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote:
> >> On Mon, 04 Nov 2019, Amol Grover <[email protected]> wrote:
> >> > Convert RCU API method text to sub-headings and
> >> > add hyperlink and superscript to 2 literary notes
> >> > under rcu_dereference() section
> >> >
> >> > Signed-off-by: Amol Grover <[email protected]>
> >> > ---
> >> > Documentation/RCU/whatisRCU.rst | 34 +++++++++++++++++++++++++++------
> >> > 1 file changed, 28 insertions(+), 6 deletions(-)
> >> >
> >> > diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
> >> > index ae40c8bcc56c..3cf6e17d0065 100644
> >> > --- a/Documentation/RCU/whatisRCU.rst
> >> > +++ b/Documentation/RCU/whatisRCU.rst
> >> > @@ -150,6 +150,7 @@ later. See the kernel docbook documentation for more info, or look directly
> >> > at the function header comments.
> >> >
> >> > rcu_read_lock()
> >> > +^^^^^^^^^^^^^^^
> >> >
> >> > void rcu_read_lock(void);
> >> >
> >> > @@ -164,6 +165,7 @@ rcu_read_lock()
> >> > longer-term references to data structures.
> >> >
> >> > rcu_read_unlock()
> >> > +^^^^^^^^^^^^^^^^^
> >> >
> >> > void rcu_read_unlock(void);
> >> >
> >> > @@ -172,6 +174,7 @@ rcu_read_unlock()
> >> > read-side critical sections may be nested and/or overlapping.
> >> >
> >> > synchronize_rcu()
> >> > +^^^^^^^^^^^^^^^^^
> >> >
> >> > void synchronize_rcu(void);
> >> >
> >> > @@ -225,6 +228,7 @@ synchronize_rcu()
> >> > checklist.txt for some approaches to limiting the update rate.
> >> >
> >> > rcu_assign_pointer()
> >> > +^^^^^^^^^^^^^^^^^^^^
> >> >
> >> > void rcu_assign_pointer(p, typeof(p) v);
> >> >
> >> > @@ -245,6 +249,7 @@ rcu_assign_pointer()
> >> > the _rcu list-manipulation primitives such as list_add_rcu().
> >> >
> >> > rcu_dereference()
> >> > +^^^^^^^^^^^^^^^^^
> >> >
> >> > typeof(p) rcu_dereference(p);
> >> >
> >> > @@ -279,8 +284,10 @@ rcu_dereference()
> >> > if an update happened while in the critical section, and incur
> >> > unnecessary overhead on Alpha CPUs.
> >> >
> >> > +.. _back_to_1:
> >> > +
> >> > Note that the value returned by rcu_dereference() is valid
> >> > - only within the enclosing RCU read-side critical section [1].
> >> > + only within the enclosing RCU read-side critical section |cs_1|.
> >> > For example, the following is -not- legal::
> >> >
> >> > rcu_read_lock();
> >> > @@ -298,15 +305,27 @@ rcu_dereference()
> >> > it was acquired is just as illegal as doing so with normal
> >> > locking.
> >> >
> >> > +.. _back_to_2:
> >> > +
> >> > As with rcu_assign_pointer(), an important function of
> >> > rcu_dereference() is to document which pointers are protected by
> >> > RCU, in particular, flagging a pointer that is subject to changing
> >> > at any time, including immediately after the rcu_dereference().
> >> > And, again like rcu_assign_pointer(), rcu_dereference() is
> >> > typically used indirectly, via the _rcu list-manipulation
> >> > - primitives, such as list_for_each_entry_rcu() [2].
> >> > + primitives, such as list_for_each_entry_rcu() |entry_2|.
> >> > +
> >> > +.. |cs_1| raw:: html
> >>
> >> Please don't use raw. It's ugly and error prone. We have some raw output
> >> for latex, but this would be the first for html.
> >>
> >> What are you trying to achieve?
> >
> > Hi Jani,
> > While going through the documentation I encountered a few footnotes (numbers
> > [1] and [2]) which referenced the actual footnote somewhere below the text.
> > They were particularly not straight-forward to find hence I decided to
> > link them to the footnote text which could be done using inline markup.
> > Then I tried to make them more appealing by converting to super-scripts
> > (the way they look like in books and websites). However, nested inline
> > markup is not yet possible in reST hence I went with the html way to
> > achieve the same. Too much?
>
> I suggest you use rst footnote markup. It's less of an eye sore in the
> rst source, but provides you with the links in the generated output. And
> typically would be superscript. In particular "autonumber labels" might
> fit the bill. [1][2]
>
> BR,
> Jani.
>
>
> [1] http://docutils.sourceforge.net/docs/user/rst/quickref.html#footnotes
> [2] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#footnotes
>
>
> >
> > Thank you
> > Amol
> >
> >>
> >> BR,
> >> Jani.
> >>
> >> > +
> >> > + <a href="#cs"><sup>[1]</sup></a>
> >> > +
> >> > +.. |entry_2| raw:: html
> >> >
> >> > - [1] The variant rcu_dereference_protected() can be used outside
> >> > + <a href="#entry"><sup>[2]</sup></a>
> >> > +
> >> > +.. _cs:
> >> > +
> >> > + \ :sup:`[1]`\ The variant rcu_dereference_protected() can be used outside
> >> > of an RCU read-side critical section as long as the usage is
> >> > protected by locks acquired by the update-side code. This variant
> >> > avoids the lockdep warning that would happen when using (for
> >> > @@ -317,15 +336,18 @@ rcu_dereference()
> >> > a lockdep expression to indicate which locks must be acquired
> >> > by the caller. If the indicated protection is not provided,
> >> > a lockdep splat is emitted. See Documentation/RCU/Design/Requirements/Requirements.rst
> >> > - and the API's code comments for more details and example usage.
> >> > + and the API's code comments for more details and example usage. :ref:`back <back_to_1>`
> >> > +
> >> > +
> >> > +.. _entry:
> >> >
> >> > - [2] If the list_for_each_entry_rcu() instance might be used by
> >> > + \ :sup:`[2]`\ If the list_for_each_entry_rcu() instance might be used by
> >> > update-side code as well as by RCU readers, then an additional
> >> > lockdep expression can be added to its list of arguments.
> >> > For example, given an additional "lock_is_held(&mylock)" argument,
> >> > the RCU lockdep code would complain only if this instance was
> >> > invoked outside of an RCU read-side critical section and without
> >> > - the protection of mylock.
> >> > + the protection of mylock. :ref:`back <back_to_2>`
> >> >
> >> > The following diagram shows how each API communicates among the
> >> > reader, updater, and reclaimer.
> >>
> >> --
> >> Jani Nikula, Intel Open Source Graphics Center
>
> --
> Jani Nikula, Intel Open Source Graphics Center
Thank you for the feedback Paul and Jani! Sent the updated
patch at
https://lore.kernel.org/lkml/20191105073340.GA3682@workstation-kernel-dev/
with the requested changes.
Thank you
Amol
Hi Amol,
On 11/4/19 12:45 PM, Paul E. McKenney wrote:
> On Mon, Nov 04, 2019 at 10:46:41PM +0530, Amol Grover wrote:
>> On Mon, Nov 04, 2019 at 07:03:28AM -0800, Paul E. McKenney wrote:
>>> On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:
>>>> Convert RCU API method text to sub-headings and
>>>> add hyperlink and superscript to 2 literary notes
>>>> under rcu_dereference() section
>>>>
>>>> Signed-off-by: Amol Grover <[email protected]>
>>>
>>> Good stuff, but Phong Tran beat you to it. If you are suggesting
>>> changes to that patch, please send a reply to her email, which
>>> may be found here:
>>>
Please do a review and send comments and suggestions in an email
instead of a patch.
>>> https://lore.kernel.org/lkml/[email protected]/
>>>
>>> There are several options for replying to this email listed at the
>>> bottom of that web page.
>>
>> Thank you Paul! And that is correct, I was suggesting changes to
>> that patch. However, since that patch was already integrated into
>> the `dev` branch, I mistakenly believed this patch could be sent
>> independently. Sorry for the trouble, I'll re-send the patch the
>> correct way.
>
Please drop your patch and do a review for the patch as suggested by
Paul. This should have been a review and not a patch on top.
thanks,
-- Shuah
On Tue, Nov 05, 2019 at 07:52:59AM -0700, Shuah Khan wrote:
> Hi Amol,
>
> On 11/4/19 12:45 PM, Paul E. McKenney wrote:
> > On Mon, Nov 04, 2019 at 10:46:41PM +0530, Amol Grover wrote:
> > > On Mon, Nov 04, 2019 at 07:03:28AM -0800, Paul E. McKenney wrote:
> > > > On Mon, Nov 04, 2019 at 07:03:15PM +0530, Amol Grover wrote:
> > > > > Convert RCU API method text to sub-headings and
> > > > > add hyperlink and superscript to 2 literary notes
> > > > > under rcu_dereference() section
> > > > >
> > > > > Signed-off-by: Amol Grover <[email protected]>
> > > >
> > > > Good stuff, but Phong Tran beat you to it. If you are suggesting
> > > > changes to that patch, please send a reply to her email, which
> > > > may be found here:
> > > >
>
> Please do a review and send comments and suggestions in an email
> instead of a patch.
Hi Shuah,
Sure thing! I'll do a review and send in the suggestions.
>
> > > > https://lore.kernel.org/lkml/[email protected]/
> > > >
> > > > There are several options for replying to this email listed at the
> > > > bottom of that web page.
> > >
> > > Thank you Paul! And that is correct, I was suggesting changes to
> > > that patch. However, since that patch was already integrated into
> > > the `dev` branch, I mistakenly believed this patch could be sent
> > > independently. Sorry for the trouble, I'll re-send the patch the
> > > correct way.
> >
>
> Please drop your patch and do a review for the patch as suggested by
> Paul. This should have been a review and not a patch on top.
Noted. Will definitely keep this in mind the next time.
Thank you
Amol
>
> thanks,
> -- Shuah