* [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 @ 2019-11-04 13:33 Amol Grover 2019-11-04 15:03 ` Paul E. McKenney 2019-11-04 15:15 ` Jani Nikula 0 siblings, 2 replies; 10+ messages in thread From: Amol Grover @ 2019-11-04 13:33 UTC (permalink / raw) To: Paul E. McKenney, Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet Cc: rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan, Joel Fernandes 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 <frextrite@gmail.com> --- 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-04 13:33 [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 Amol Grover @ 2019-11-04 15:03 ` Paul E. McKenney 2019-11-04 17:16 ` Amol Grover 2019-11-04 15:15 ` Jani Nikula 1 sibling, 1 reply; 10+ messages in thread From: Paul E. McKenney @ 2019-11-04 15:03 UTC (permalink / raw) To: Amol Grover Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan 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 <frextrite@gmail.com> 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/20191030233128.14997-1-tranmanphong@gmail.com/ 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 > ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-04 15:03 ` Paul E. McKenney @ 2019-11-04 17:16 ` Amol Grover 2019-11-04 19:45 ` Paul E. McKenney 0 siblings, 1 reply; 10+ messages in thread From: Amol Grover @ 2019-11-04 17:16 UTC (permalink / raw) To: Paul E. McKenney Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan 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 <frextrite@gmail.com> > > 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/20191030233128.14997-1-tranmanphong@gmail.com/ > > 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 > > ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-04 17:16 ` Amol Grover @ 2019-11-04 19:45 ` Paul E. McKenney 2019-11-05 14:52 ` Shuah Khan 0 siblings, 1 reply; 10+ messages in thread From: Paul E. McKenney @ 2019-11-04 19:45 UTC (permalink / raw) To: Amol Grover Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan 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 <frextrite@gmail.com> > > > > 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/20191030233128.14997-1-tranmanphong@gmail.com/ > > > > 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 <tranmanphong@gmail.com>" 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 > > > ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-04 19:45 ` Paul E. McKenney @ 2019-11-05 14:52 ` Shuah Khan 2019-11-05 16:20 ` Amol Grover 0 siblings, 1 reply; 10+ messages in thread From: Shuah Khan @ 2019-11-05 14:52 UTC (permalink / raw) To: paulmck, Amol Grover Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan 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 <frextrite@gmail.com> >>> >>> 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/20191030233128.14997-1-tranmanphong@gmail.com/ >>> >>> 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-05 14:52 ` Shuah Khan @ 2019-11-05 16:20 ` Amol Grover 0 siblings, 0 replies; 10+ messages in thread From: Amol Grover @ 2019-11-05 16:20 UTC (permalink / raw) To: Shuah Khan Cc: paulmck, Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel, linux-kernel-mentees 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 <frextrite@gmail.com> > > > > > > > > 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/20191030233128.14997-1-tranmanphong@gmail.com/ > > > > > > > > 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-04 13:33 [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 Amol Grover 2019-11-04 15:03 ` Paul E. McKenney @ 2019-11-04 15:15 ` Jani Nikula 2019-11-04 17:31 ` Amol Grover 1 sibling, 1 reply; 10+ messages in thread From: Jani Nikula @ 2019-11-04 15:15 UTC (permalink / raw) To: Amol Grover, Paul E. McKenney, Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet Cc: rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan, Joel Fernandes On Mon, 04 Nov 2019, Amol Grover <frextrite@gmail.com> 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 <frextrite@gmail.com> > --- > 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-04 15:15 ` Jani Nikula @ 2019-11-04 17:31 ` Amol Grover 2019-11-05 6:08 ` Jani Nikula 0 siblings, 1 reply; 10+ messages in thread From: Amol Grover @ 2019-11-04 17:31 UTC (permalink / raw) To: Jani Nikula Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote: > On Mon, 04 Nov 2019, Amol Grover <frextrite@gmail.com> 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 <frextrite@gmail.com> > > --- > > 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-04 17:31 ` Amol Grover @ 2019-11-05 6:08 ` Jani Nikula 2019-11-05 7:41 ` Amol Grover 0 siblings, 1 reply; 10+ messages in thread From: Jani Nikula @ 2019-11-05 6:08 UTC (permalink / raw) To: Amol Grover Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan On Mon, 04 Nov 2019, Amol Grover <frextrite@gmail.com> wrote: > On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote: >> On Mon, 04 Nov 2019, Amol Grover <frextrite@gmail.com> 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 <frextrite@gmail.com> >> > --- >> > 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 2019-11-05 6:08 ` Jani Nikula @ 2019-11-05 7:41 ` Amol Grover 0 siblings, 0 replies; 10+ messages in thread From: Amol Grover @ 2019-11-05 7:41 UTC (permalink / raw) To: Jani Nikula Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet, rcu, linux-doc, linux-kernel, linux-kernel-mentees, Shuah Khan On Tue, Nov 05, 2019 at 08:08:50AM +0200, Jani Nikula wrote: > On Mon, 04 Nov 2019, Amol Grover <frextrite@gmail.com> wrote: > > On Mon, Nov 04, 2019 at 05:15:34PM +0200, Jani Nikula wrote: > >> On Mon, 04 Nov 2019, Amol Grover <frextrite@gmail.com> 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 <frextrite@gmail.com> > >> > --- > >> > 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2019-11-05 16:20 UTC | newest] Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2019-11-04 13:33 [PATCH] Documentation: RCU: whatisRCU: Fix formatting for section 2 Amol Grover 2019-11-04 15:03 ` Paul E. McKenney 2019-11-04 17:16 ` Amol Grover 2019-11-04 19:45 ` Paul E. McKenney 2019-11-05 14:52 ` Shuah Khan 2019-11-05 16:20 ` Amol Grover 2019-11-04 15:15 ` Jani Nikula 2019-11-04 17:31 ` Amol Grover 2019-11-05 6:08 ` Jani Nikula 2019-11-05 7:41 ` Amol Grover
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).