"-foo-" does not work as emphasis in ReST markdown.
Use "*foo*" instead.
Signed-off-by: Akira Yokosawa <[email protected]>
---
Hi Paul,
This is relative to -rcu's dev branch.
I've started learning how to do ReST markdown. ;-)
For emphasis, both "*foo*" and "_bar_" work.
I see several "*foo*" patterns in other .rst files under RCU/.
Yes, I have now sphinx installed in a container for "make htmldocs" to work.
"make pdfdocs" does not work as expected at the moment, though.
Thanks, Akira
--
Documentation/RCU/checklist.rst | 24 ++++++++++++------------
Documentation/RCU/rcu_dereference.rst | 6 +++---
Documentation/RCU/stallwarn.rst | 8 ++++----
3 files changed, 19 insertions(+), 19 deletions(-)
diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
index 1030119294d0..a71d3f134323 100644
--- a/Documentation/RCU/checklist.rst
+++ b/Documentation/RCU/checklist.rst
@@ -37,7 +37,7 @@ over a rather long period of time, but improvements are always welcome!
1. Does the update code have proper mutual exclusion?
- RCU does allow -readers- to run (almost) naked, but -writers- must
+ RCU does allow *readers* to run (almost) naked, but *writers* must
still use some sort of mutual exclusion, such as:
a. locking,
@@ -73,7 +73,7 @@ over a rather long period of time, but improvements are always welcome!
critical section is every bit as bad as letting them leak out
from under a lock. Unless, of course, you have arranged some
other means of protection, such as a lock or a reference count
- -before- letting them out of the RCU read-side critical section.
+ *before* letting them out of the RCU read-side critical section.
3. Does the update code tolerate concurrent accesses?
@@ -101,7 +101,7 @@ over a rather long period of time, but improvements are always welcome!
c. Make updates appear atomic to readers. For example,
pointer updates to properly aligned fields will
appear atomic, as will individual atomic primitives.
- Sequences of operations performed under a lock will -not-
+ Sequences of operations performed under a lock will *not*
appear to be atomic to RCU readers, nor will sequences
of multiple atomic primitives.
@@ -320,7 +320,7 @@ over a rather long period of time, but improvements are always welcome!
for example) may be omitted.
10. Conversely, if you are in an RCU read-side critical section,
- and you don't hold the appropriate update-side lock, you -must-
+ and you don't hold the appropriate update-side lock, you *must*
use the "_rcu()" variants of the list macros. Failing to do so
will break Alpha, cause aggressive compilers to generate bad code,
and confuse people trying to read your code.
@@ -346,12 +346,12 @@ over a rather long period of time, but improvements are always welcome!
callback pending, then that RCU callback will execute on some
surviving CPU. (If this was not the case, a self-spawning RCU
callback would prevent the victim CPU from ever going offline.)
- Furthermore, CPUs designated by rcu_nocbs= might well -always-
+ Furthermore, CPUs designated by rcu_nocbs= might well *always*
have their RCU callbacks executed on some other CPUs, in fact,
for some real-time workloads, this is the whole point of using
the rcu_nocbs= kernel boot parameter.
-13. Unlike other forms of RCU, it -is- permissible to block in an
+13. Unlike other forms of RCU, it *is* permissible to block in an
SRCU read-side critical section (demarked by srcu_read_lock()
and srcu_read_unlock()), hence the "SRCU": "sleepable RCU".
Please note that if you don't need to sleep in read-side critical
@@ -398,16 +398,16 @@ over a rather long period of time, but improvements are always welcome!
14. The whole point of call_rcu(), synchronize_rcu(), and friends
is to wait until all pre-existing readers have finished before
carrying out some otherwise-destructive operation. It is
- therefore critically important to -first- remove any path
+ therefore critically important to *first* remove any path
that readers can follow that could be affected by the
- destructive operation, and -only- -then- invoke call_rcu(),
+ destructive operation, and *only then* invoke call_rcu(),
synchronize_rcu(), or friends.
Because these primitives only wait for pre-existing readers, it
is the caller's responsibility to guarantee that any subsequent
readers will execute safely.
-15. The various RCU read-side primitives do -not- necessarily contain
+15. The various RCU read-side primitives do *not* necessarily contain
memory barriers. You should therefore plan for the CPU
and the compiler to freely reorder code into and out of RCU
read-side critical sections. It is the responsibility of the
@@ -446,8 +446,8 @@ over a rather long period of time, but improvements are always welcome!
pass in a function defined within a loadable module, then it in
necessary to wait for all pending callbacks to be invoked after
the last invocation and before unloading that module. Note that
- it is absolutely -not- sufficient to wait for a grace period!
- The current (say) synchronize_rcu() implementation is -not-
+ it is absolutely *not* sufficient to wait for a grace period!
+ The current (say) synchronize_rcu() implementation is *not*
guaranteed to wait for callbacks registered on other CPUs.
Or even on the current CPU if that CPU recently went offline
and came back online.
@@ -457,7 +457,7 @@ over a rather long period of time, but improvements are always welcome!
- call_rcu() -> rcu_barrier()
- call_srcu() -> srcu_barrier()
- However, these barrier functions are absolutely -not- guaranteed
+ However, these barrier functions are absolutely *not* guaranteed
to wait for a grace period. In fact, if there are no call_rcu()
callbacks waiting anywhere in the system, rcu_barrier() is within
its rights to return immediately.
diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
index f3e587acb4de..0b418a5b243c 100644
--- a/Documentation/RCU/rcu_dereference.rst
+++ b/Documentation/RCU/rcu_dereference.rst
@@ -43,7 +43,7 @@ Follow these rules to keep your RCU code working properly:
- Set bits and clear bits down in the must-be-zero low-order
bits of that pointer. This clearly means that the pointer
must have alignment constraints, for example, this does
- -not- work in general for char* pointers.
+ *not* work in general for char* pointers.
- XOR bits to translate pointers, as is done in some
classic buddy-allocator algorithms.
@@ -174,7 +174,7 @@ Follow these rules to keep your RCU code working properly:
Please see the "CONTROL DEPENDENCIES" section of
Documentation/memory-barriers.txt for more details.
- - The pointers are not equal -and- the compiler does
+ - The pointers are not equal *and* the compiler does
not have enough information to deduce the value of the
pointer. Note that the volatile cast in rcu_dereference()
will normally prevent the compiler from knowing too much.
@@ -360,7 +360,7 @@ in turn destroying the ordering between this load and the loads of the
return values. This can result in "p->b" returning pre-initialization
garbage values.
-In short, rcu_dereference() is -not- optional when you are going to
+In short, rcu_dereference() is *not* optional when you are going to
dereference the resulting pointer.
diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
index 7148e9be08c3..1cc944aec46f 100644
--- a/Documentation/RCU/stallwarn.rst
+++ b/Documentation/RCU/stallwarn.rst
@@ -32,7 +32,7 @@ warnings:
- Booting Linux using a console connection that is too slow to
keep up with the boot-time console-message rate. For example,
- a 115Kbaud serial console can be -way- too slow to keep up
+ a 115Kbaud serial console can be *way* too slow to keep up
with boot-time message rates, and will frequently result in
RCU CPU stall warning messages. Especially if you have added
debug printk()s.
@@ -105,7 +105,7 @@ warnings:
leading the realization that the CPU had failed.
The RCU, RCU-sched, and RCU-tasks implementations have CPU stall warning.
-Note that SRCU does -not- have CPU stall warnings. Please note that
+Note that SRCU does *not* have CPU stall warnings. Please note that
RCU only detects CPU stalls when there is a grace period in progress.
No grace period, no CPU stall warnings.
@@ -145,7 +145,7 @@ CONFIG_RCU_CPU_STALL_TIMEOUT
this parameter is checked only at the beginning of a cycle.
So if you are 10 seconds into a 40-second stall, setting this
sysfs parameter to (say) five will shorten the timeout for the
- -next- stall, or the following warning for the current stall
+ *next* stall, or the following warning for the current stall
(assuming the stall lasts long enough). It will not affect the
timing of the next warning for the current stall.
@@ -202,7 +202,7 @@ causing stalls, and that the stall was affecting RCU-sched. This message
will normally be followed by stack dumps for each CPU. Please note that
PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that
the tasks will be indicated by PID, for example, "P3421". It is even
-possible for an rcu_state stall to be caused by both CPUs -and- tasks,
+possible for an rcu_state stall to be caused by both CPUs *and* tasks,
in which case the offending CPUs and tasks will all be called out in the list.
CPU 2's "(3 GPs behind)" indicates that this CPU has not interacted with
--
2.17.1
On Thu, May 20, 2021 at 01:32:36PM +0900, Akira Yokosawa wrote:
> "-foo-" does not work as emphasis in ReST markdown.
> Use "*foo*" instead.
>
> Signed-off-by: Akira Yokosawa <[email protected]>
Queued, thank you! Or if this should instead go via the Documentation
tree:
Acked-by: Paul E. McKenney <[email protected]>
> ---
> Hi Paul,
>
> This is relative to -rcu's dev branch.
> I've started learning how to do ReST markdown. ;-)
>
> For emphasis, both "*foo*" and "_bar_" work.
> I see several "*foo*" patterns in other .rst files under RCU/.
>
> Yes, I have now sphinx installed in a container for "make htmldocs" to work.
> "make pdfdocs" does not work as expected at the moment, though.
Installing it in a container does sound very good! My experience is
that I hack one version into working, but then it all falls apart
the the next time a sphinx upgrade is needed. :-/
Thanx, Paul
> Thanks, Akira
> --
> Documentation/RCU/checklist.rst | 24 ++++++++++++------------
> Documentation/RCU/rcu_dereference.rst | 6 +++---
> Documentation/RCU/stallwarn.rst | 8 ++++----
> 3 files changed, 19 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
> index 1030119294d0..a71d3f134323 100644
> --- a/Documentation/RCU/checklist.rst
> +++ b/Documentation/RCU/checklist.rst
> @@ -37,7 +37,7 @@ over a rather long period of time, but improvements are always welcome!
>
> 1. Does the update code have proper mutual exclusion?
>
> - RCU does allow -readers- to run (almost) naked, but -writers- must
> + RCU does allow *readers* to run (almost) naked, but *writers* must
> still use some sort of mutual exclusion, such as:
>
> a. locking,
> @@ -73,7 +73,7 @@ over a rather long period of time, but improvements are always welcome!
> critical section is every bit as bad as letting them leak out
> from under a lock. Unless, of course, you have arranged some
> other means of protection, such as a lock or a reference count
> - -before- letting them out of the RCU read-side critical section.
> + *before* letting them out of the RCU read-side critical section.
>
> 3. Does the update code tolerate concurrent accesses?
>
> @@ -101,7 +101,7 @@ over a rather long period of time, but improvements are always welcome!
> c. Make updates appear atomic to readers. For example,
> pointer updates to properly aligned fields will
> appear atomic, as will individual atomic primitives.
> - Sequences of operations performed under a lock will -not-
> + Sequences of operations performed under a lock will *not*
> appear to be atomic to RCU readers, nor will sequences
> of multiple atomic primitives.
>
> @@ -320,7 +320,7 @@ over a rather long period of time, but improvements are always welcome!
> for example) may be omitted.
>
> 10. Conversely, if you are in an RCU read-side critical section,
> - and you don't hold the appropriate update-side lock, you -must-
> + and you don't hold the appropriate update-side lock, you *must*
> use the "_rcu()" variants of the list macros. Failing to do so
> will break Alpha, cause aggressive compilers to generate bad code,
> and confuse people trying to read your code.
> @@ -346,12 +346,12 @@ over a rather long period of time, but improvements are always welcome!
> callback pending, then that RCU callback will execute on some
> surviving CPU. (If this was not the case, a self-spawning RCU
> callback would prevent the victim CPU from ever going offline.)
> - Furthermore, CPUs designated by rcu_nocbs= might well -always-
> + Furthermore, CPUs designated by rcu_nocbs= might well *always*
> have their RCU callbacks executed on some other CPUs, in fact,
> for some real-time workloads, this is the whole point of using
> the rcu_nocbs= kernel boot parameter.
>
> -13. Unlike other forms of RCU, it -is- permissible to block in an
> +13. Unlike other forms of RCU, it *is* permissible to block in an
> SRCU read-side critical section (demarked by srcu_read_lock()
> and srcu_read_unlock()), hence the "SRCU": "sleepable RCU".
> Please note that if you don't need to sleep in read-side critical
> @@ -398,16 +398,16 @@ over a rather long period of time, but improvements are always welcome!
> 14. The whole point of call_rcu(), synchronize_rcu(), and friends
> is to wait until all pre-existing readers have finished before
> carrying out some otherwise-destructive operation. It is
> - therefore critically important to -first- remove any path
> + therefore critically important to *first* remove any path
> that readers can follow that could be affected by the
> - destructive operation, and -only- -then- invoke call_rcu(),
> + destructive operation, and *only then* invoke call_rcu(),
> synchronize_rcu(), or friends.
>
> Because these primitives only wait for pre-existing readers, it
> is the caller's responsibility to guarantee that any subsequent
> readers will execute safely.
>
> -15. The various RCU read-side primitives do -not- necessarily contain
> +15. The various RCU read-side primitives do *not* necessarily contain
> memory barriers. You should therefore plan for the CPU
> and the compiler to freely reorder code into and out of RCU
> read-side critical sections. It is the responsibility of the
> @@ -446,8 +446,8 @@ over a rather long period of time, but improvements are always welcome!
> pass in a function defined within a loadable module, then it in
> necessary to wait for all pending callbacks to be invoked after
> the last invocation and before unloading that module. Note that
> - it is absolutely -not- sufficient to wait for a grace period!
> - The current (say) synchronize_rcu() implementation is -not-
> + it is absolutely *not* sufficient to wait for a grace period!
> + The current (say) synchronize_rcu() implementation is *not*
> guaranteed to wait for callbacks registered on other CPUs.
> Or even on the current CPU if that CPU recently went offline
> and came back online.
> @@ -457,7 +457,7 @@ over a rather long period of time, but improvements are always welcome!
> - call_rcu() -> rcu_barrier()
> - call_srcu() -> srcu_barrier()
>
> - However, these barrier functions are absolutely -not- guaranteed
> + However, these barrier functions are absolutely *not* guaranteed
> to wait for a grace period. In fact, if there are no call_rcu()
> callbacks waiting anywhere in the system, rcu_barrier() is within
> its rights to return immediately.
> diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
> index f3e587acb4de..0b418a5b243c 100644
> --- a/Documentation/RCU/rcu_dereference.rst
> +++ b/Documentation/RCU/rcu_dereference.rst
> @@ -43,7 +43,7 @@ Follow these rules to keep your RCU code working properly:
> - Set bits and clear bits down in the must-be-zero low-order
> bits of that pointer. This clearly means that the pointer
> must have alignment constraints, for example, this does
> - -not- work in general for char* pointers.
> + *not* work in general for char* pointers.
>
> - XOR bits to translate pointers, as is done in some
> classic buddy-allocator algorithms.
> @@ -174,7 +174,7 @@ Follow these rules to keep your RCU code working properly:
> Please see the "CONTROL DEPENDENCIES" section of
> Documentation/memory-barriers.txt for more details.
>
> - - The pointers are not equal -and- the compiler does
> + - The pointers are not equal *and* the compiler does
> not have enough information to deduce the value of the
> pointer. Note that the volatile cast in rcu_dereference()
> will normally prevent the compiler from knowing too much.
> @@ -360,7 +360,7 @@ in turn destroying the ordering between this load and the loads of the
> return values. This can result in "p->b" returning pre-initialization
> garbage values.
>
> -In short, rcu_dereference() is -not- optional when you are going to
> +In short, rcu_dereference() is *not* optional when you are going to
> dereference the resulting pointer.
>
>
> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
> index 7148e9be08c3..1cc944aec46f 100644
> --- a/Documentation/RCU/stallwarn.rst
> +++ b/Documentation/RCU/stallwarn.rst
> @@ -32,7 +32,7 @@ warnings:
>
> - Booting Linux using a console connection that is too slow to
> keep up with the boot-time console-message rate. For example,
> - a 115Kbaud serial console can be -way- too slow to keep up
> + a 115Kbaud serial console can be *way* too slow to keep up
> with boot-time message rates, and will frequently result in
> RCU CPU stall warning messages. Especially if you have added
> debug printk()s.
> @@ -105,7 +105,7 @@ warnings:
> leading the realization that the CPU had failed.
>
> The RCU, RCU-sched, and RCU-tasks implementations have CPU stall warning.
> -Note that SRCU does -not- have CPU stall warnings. Please note that
> +Note that SRCU does *not* have CPU stall warnings. Please note that
> RCU only detects CPU stalls when there is a grace period in progress.
> No grace period, no CPU stall warnings.
>
> @@ -145,7 +145,7 @@ CONFIG_RCU_CPU_STALL_TIMEOUT
> this parameter is checked only at the beginning of a cycle.
> So if you are 10 seconds into a 40-second stall, setting this
> sysfs parameter to (say) five will shorten the timeout for the
> - -next- stall, or the following warning for the current stall
> + *next* stall, or the following warning for the current stall
> (assuming the stall lasts long enough). It will not affect the
> timing of the next warning for the current stall.
>
> @@ -202,7 +202,7 @@ causing stalls, and that the stall was affecting RCU-sched. This message
> will normally be followed by stack dumps for each CPU. Please note that
> PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that
> the tasks will be indicated by PID, for example, "P3421". It is even
> -possible for an rcu_state stall to be caused by both CPUs -and- tasks,
> +possible for an rcu_state stall to be caused by both CPUs *and* tasks,
> in which case the offending CPUs and tasks will all be called out in the list.
>
> CPU 2's "(3 GPs behind)" indicates that this CPU has not interacted with
> --
> 2.17.1
>