lkml.org 
[lkml]   [2022]   [Mar]   [30]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
SubjectRe: [PATCH -rcu] rcu: docs: Update cross-references as suggested in doc-guide
From
On Wed, 30 Mar 2022 11:38:02 -0700,
Paul E. McKenney wrote:
> On Wed, Mar 30, 2022 at 11:41:00PM +0900, Akira Yokosawa wrote:
>> There are cross references which are sub-optimal with regard
>> to the practices mentioned in doc-guide/sphinx.rst.
>>
>> There are also a couple of references to RCU documentation via URL.
>> They can be expressed by file paths.
>>
>> Update them and adjust surrounding words.
>>
>> Summary of changes:
>>
>> - out-of-date plaintext file names (*.txt) -> *.rst
>> - references by :ref: tags -> path names of *.rst
>> * use relative paths to .rst files under the RCU/ subdirectory
>> * use abs paths of Documentation/xxx for other .rst files
>> - references by URL under https://www.kernel.org/ -> paths of *.rst
>> - adjust surrounding words of some of updated references.
>>
>> Note:
>> The automarkup.py script interprets references via "*.txt" as if they
>> were via "*.rst", so the hyperlinks in the resulting HTML pages works
>> without this change.
>>
>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>> Cc: rcu@vger.kernel.org
>> Cc: linux-doc@vger.kernel.org
>
> Nice! I have queued these for testing and review, thank you!
>
> (As usual, I could not resist a bit of wordsmithing, so please check
> to see if I messed something up.)
>
> Thanx, Paul
>
> ------------------------------------------------------------------------
>
> commit 66150a50090d7bd97d572bc40fd676ab9c1a0d35
> Author: Akira Yokosawa <akiyks@gmail.com>
> Date: Wed Mar 30 23:41:00 2022 +0900
>
> docs: Update RCU cross-references as suggested in doc-guide
>
> The RCU documentation contains old-style cross references which
> do not follow the best practices outlined in doc-guide/sphinx.rst.
> In addition, some of the cross references use URLs that should be replaced
> by pathnames.
>
> Update all of these cross references and adjust the surrounding words.
>
> Summary of changes:
>
> - out-of-date plaintext file names (*.txt) -> *.rst
> - references by :ref: tags -> path names of *.rst
> * use relative paths to .rst files under the RCU/ subdirectory
> * use abs paths of Documentation/xxx for other .rst files
> - references by URL under https://www.kernel.org/ -> paths of *.rst
> - adjust surrounding words of some of updated references.
>
> Note:
> The automarkup.py script interprets references via "*.txt" as if they
> were via "*.rst", so the *.txt -> *.rst changes should be regarded as
> cleanups rather than bug fixes.

Looks pretty nice and easy to follow. ;-)

Thanks, Akira

>
> Cc: rcu@vger.kernel.org
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
>
> diff --git a/Documentation/RCU/Design/Data-Structures/Data-Structures.rst b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
> index f4efd6897b09..b34990c7c377 100644
> --- a/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
> +++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
> @@ -973,7 +973,7 @@ The ``->dynticks`` field counts the corresponding CPU's transitions to
> and from either dyntick-idle or user mode, so that this counter has an
> even value when the CPU is in dyntick-idle mode or user mode and an odd
> value otherwise. The transitions to/from user mode need to be counted
> -for user mode adaptive-ticks support (see timers/NO_HZ.txt).
> +for user mode adaptive-ticks support (see Documentation/timers/no_hz.rst).
>
> The ``->rcu_need_heavy_qs`` field is used to record the fact that the
> RCU core code would really like to see a quiescent state from the
> diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
> index 6f89cf1e567d..c9c957c85bac 100644
> --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
> +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
> @@ -406,7 +406,7 @@ In earlier implementations, the task requesting the expedited grace
> period also drove it to completion. This straightforward approach had
> the disadvantage of needing to account for POSIX signals sent to user
> tasks, so more recent implemementations use the Linux kernel's
> -`workqueues <https://www.kernel.org/doc/Documentation/core-api/workqueue.rst>`__.
> +workqueues (see Documentation/core-api/workqueue.rst).
>
> The requesting task still does counter snapshotting and funnel-lock
> processing, but the task reaching the top of the funnel lock does a
> diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
> index ff2be1ac54c4..04ed8bf27a0e 100644
> --- a/Documentation/RCU/Design/Requirements/Requirements.rst
> +++ b/Documentation/RCU/Design/Requirements/Requirements.rst
> @@ -370,8 +370,8 @@ pointer fetched by rcu_dereference() may not be used outside of the
> outermost RCU read-side critical section containing that
> rcu_dereference(), unless protection of the corresponding data
> element has been passed from RCU to some other synchronization
> -mechanism, most commonly locking or `reference
> -counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
> +mechanism, most commonly locking or reference counting
> +(see ../../rcuref.rst).
>
> .. |high-quality implementation of C11 memory_order_consume [PDF]| replace:: high-quality implementation of C11 ``memory_order_consume`` [PDF]
> .. _high-quality implementation of C11 memory_order_consume [PDF]: http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf
> diff --git a/Documentation/RCU/arrayRCU.rst b/Documentation/RCU/arrayRCU.rst
> index 4051ea3871ef..a5f2ff8fc54c 100644
> --- a/Documentation/RCU/arrayRCU.rst
> +++ b/Documentation/RCU/arrayRCU.rst
> @@ -33,8 +33,8 @@ Situation 1: Hash Tables
>
> Hash tables are often implemented as an array, where each array entry
> has a linked-list hash chain. Each hash chain can be protected by RCU
> -as described in the listRCU.txt document. This approach also applies
> -to other array-of-list situations, such as radix trees.
> +as described in listRCU.rst. This approach also applies to other
> +array-of-list situations, such as radix trees.
>
> .. _static_arrays:
>
> diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
> index f4545b7c9a63..42cc5d891bd2 100644
> --- a/Documentation/RCU/checklist.rst
> +++ b/Documentation/RCU/checklist.rst
> @@ -140,8 +140,7 @@ over a rather long period of time, but improvements are always welcome!
> prevents destructive compiler optimizations. However,
> with a bit of devious creativity, it is possible to
> mishandle the return value from rcu_dereference().
> - Please see rcu_dereference.txt in this directory for
> - more information.
> + Please see rcu_dereference.rst for more information.
>
> The rcu_dereference() primitive is used by the
> various "_rcu()" list-traversal primitives, such
> @@ -151,7 +150,7 @@ over a rather long period of time, but improvements are always welcome!
> primitives. This is particularly useful in code that
> is common to readers and updaters. However, lockdep
> will complain if you access rcu_dereference() outside
> - of an RCU read-side critical section. See lockdep.txt
> + of an RCU read-side critical section. See lockdep.rst
> to learn what to do about this.
>
> Of course, neither rcu_dereference() nor the "_rcu()"
> @@ -323,7 +322,7 @@ over a rather long period of time, but improvements are always welcome!
> primitives when the update-side lock is held is that doing so
> can be quite helpful in reducing code bloat when common code is
> shared between readers and updaters. Additional primitives
> - are provided for this case, as discussed in lockdep.txt.
> + are provided for this case, as discussed in lockdep.rst.
>
> One exception to this rule is when data is only ever added to
> the linked data structure, and is never removed during any
> @@ -480,4 +479,4 @@ over a rather long period of time, but improvements are always welcome!
> both rcu_barrier() and synchronize_rcu(), if necessary, using
> something like workqueues to to execute them concurrently.
>
> - See rcubarrier.txt for more information.
> + See rcubarrier.rst for more information.
> diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
> index 0e03c6ef3147..3cfe01ba9a49 100644
> --- a/Documentation/RCU/rcu.rst
> +++ b/Documentation/RCU/rcu.rst
> @@ -10,9 +10,8 @@ A "grace period" must elapse between the two parts, and this grace period
> must be long enough that any readers accessing the item being deleted have
> since dropped their references. For example, an RCU-protected deletion
> from a linked list would first remove the item from the list, wait for
> -a grace period to elapse, then free the element. See the
> -:ref:`Documentation/RCU/listRCU.rst <list_rcu_doc>` for more information on
> -using RCU with linked lists.
> +a grace period to elapse, then free the element. See listRCU.rst for more
> +information on using RCU with linked lists.
>
> Frequently Asked Questions
> --------------------------
> @@ -50,7 +49,7 @@ Frequently Asked Questions
> - If I am running on a uniprocessor kernel, which can only do one
> thing at a time, why should I wait for a grace period?
>
> - See :ref:`Documentation/RCU/UP.rst <up_doc>` for more information.
> + See UP.rst for more information.
>
> - How can I see where RCU is currently used in the Linux kernel?
>
> @@ -64,13 +63,13 @@ Frequently Asked Questions
>
> - What guidelines should I follow when writing code that uses RCU?
>
> - See the checklist.txt file in this directory.
> + See checklist.rst.
>
> - Why the name "RCU"?
>
> "RCU" stands for "read-copy update".
> - :ref:`Documentation/RCU/listRCU.rst <list_rcu_doc>` has more information on where
> - this name came from, search for "read-copy update" to find it.
> + listRCU.rst has more information on where this name came from, search
> + for "read-copy update" to find it.
>
> - I hear that RCU is patented? What is with that?
>
> diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
> index a9fc774bc400..ca4692775ad4 100644
> --- a/Documentation/RCU/rculist_nulls.rst
> +++ b/Documentation/RCU/rculist_nulls.rst
> @@ -8,7 +8,7 @@ This section describes how to use hlist_nulls to
> protect read-mostly linked lists and
> objects using SLAB_TYPESAFE_BY_RCU allocations.
>
> -Please read the basics in Documentation/RCU/listRCU.rst
> +Please read the basics in listRCU.rst.
>
> Using 'nulls'
> =============
> diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
> index c34d2212eaca..77ea260efd12 100644
> --- a/Documentation/RCU/whatisRCU.rst
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -224,7 +224,7 @@ synchronize_rcu()
> be delayed. This property results in system resilience in face
> of denial-of-service attacks. Code using call_rcu() should limit
> update rate in order to gain this same sort of resilience. See
> - checklist.txt for some approaches to limiting the update rate.
> + checklist.rst for some approaches to limiting the update rate.
>
> rcu_assign_pointer()
> ^^^^^^^^^^^^^^^^^^^^
> @@ -318,7 +318,7 @@ rcu_dereference()
> must prohibit. The rcu_dereference_protected() variant takes
> 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
> + a lockdep splat is emitted. See Design/Requirements/Requirements.rst
> and the API's code comments for more details and example usage.
>
> .. [2] If the list_for_each_entry_rcu() instance might be used by
> @@ -399,8 +399,7 @@ for specialized uses, but are relatively uncommon.
>
> This section shows a simple use of the core RCU API to protect a
> global pointer to a dynamically allocated structure. More-typical
> -uses of RCU may be found in :ref:`listRCU.rst <list_rcu_doc>`,
> -:ref:`arrayRCU.rst <array_rcu_doc>`, and :ref:`NMI-RCU.rst <NMI_rcu_doc>`.
> +uses of RCU may be found in listRCU.rst, arrayRCU.rst, and NMI-RCU.rst.
> ::
>
> struct foo {
> @@ -482,10 +481,9 @@ So, to sum up:
> RCU read-side critical sections that might be referencing that
> data item.
>
> -See checklist.txt for additional rules to follow when using RCU.
> -And again, more-typical uses of RCU may be found in :ref:`listRCU.rst
> -<list_rcu_doc>`, :ref:`arrayRCU.rst <array_rcu_doc>`, and :ref:`NMI-RCU.rst
> -<NMI_rcu_doc>`.
> +See checklist.rst for additional rules to follow when using RCU.
> +And again, more-typical uses of RCU may be found in listRCU.rst,
> +arrayRCU.rst, and NMI-RCU.rst.
>
> .. _4_whatisRCU:
>
> @@ -579,7 +577,7 @@ to avoid having to write your own callback::
>
> kfree_rcu(old_fp, rcu);
>
> -Again, see checklist.txt for additional rules governing the use of RCU.
> +Again, see checklist.rst for additional rules governing the use of RCU.
>
> .. _5_whatisRCU:
>
> @@ -663,7 +661,7 @@ been able to write-acquire the lock otherwise. The smp_mb__after_spinlock()
> promotes synchronize_rcu() to a full memory barrier in compliance with
> the "Memory-Barrier Guarantees" listed in:
>
> - Documentation/RCU/Design/Requirements/Requirements.rst
> + Design/Requirements/Requirements.rst
>
> It is possible to nest rcu_read_lock(), since reader-writer locks may
> be recursively acquired. Note also that rcu_read_lock() is immune

\
 
 \ /
  Last update: 2022-03-31 03:11    [W:0.065 / U:0.348 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site