* [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
@ 2022-11-24 6:22 Zhen Lei
2022-11-26 1:30 ` Leizhen (ThunderTown)
` (2 more replies)
0 siblings, 3 replies; 7+ messages in thread
From: Zhen Lei @ 2022-11-24 6:22 UTC (permalink / raw)
To: Paul E . McKenney, Frederic Weisbecker, Neeraj Upadhyay,
Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, rcu, linux-kernel, Stephen Rothwell, linux-next
Cc: Zhen Lei, Bagas Sanjaya
Documentation/RCU/stallwarn.rst:
401: WARNING: Literal block expected; none found.
428: WARNING: Literal block expected; none found.
445: WARNING: Literal block expected; none found.
459: WARNING: Literal block expected; none found.
468: WARNING: Literal block expected; none found.
The literal block need to be indented, so add two spaces to each line.
In addition, ':', which is used as a boundary in the literal block, is
replaced by '|'.
Link: https://lore.kernel.org/linux-next/20221123163255.48653674@canb.auug.org.au/
Fixes: 3d2788ba4573 ("doc: Document CONFIG_RCU_CPU_STALL_CPUTIME=y stall information")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
---
Documentation/RCU/stallwarn.rst | 56 ++++++++++++++++++---------------
1 file changed, 30 insertions(+), 26 deletions(-)
v2 --> v3:
1. Add "Link:", "Fixes:", "Reported-by:".
2. Remove a orphaned pipe (|).
3. Change ". ::" to "::"
v1 --> v2:
For the case that both colons need to be deleted, change "::" to expanded
form or partially minimized form.
diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
index c1e92dfef40d501..ca7b7cd806a16c9 100644
--- a/Documentation/RCU/stallwarn.rst
+++ b/Documentation/RCU/stallwarn.rst
@@ -398,9 +398,9 @@ In kernels built with CONFIG_RCU_CPU_STALL_CPUTIME=y or booted with
rcupdate.rcu_cpu_stall_cputime=1, the following additional information
is supplied with each RCU CPU stall warning::
-rcu: hardirqs softirqs csw/system
-rcu: number: 624 45 0
-rcu: cputime: 69 1 2425 ==> 2500(ms)
+ rcu: hardirqs softirqs csw/system
+ rcu: number: 624 45 0
+ rcu: cputime: 69 1 2425 ==> 2500(ms)
These statistics are collected during the sampling period. The values
in row "number:" are the number of hard interrupts, number of soft
@@ -412,22 +412,24 @@ in milliseconds. Because user-mode tasks normally do not cause RCU CPU
stalls, these tasks are typically kernel tasks, which is why only the
system CPU time are considered.
-The sampling period is shown as follows:
-:<------------first timeout---------->:<-----second timeout----->:
-:<--half timeout-->:<--half timeout-->: :
-: :<--first period-->: :
-: :<-----------second sampling period---------->:
-: : : :
-: snapshot time point 1st-stall 2nd-stall
+The sampling period is shown as follows::
+ |<------------first timeout---------->|<-----second timeout----->|
+ |<--half timeout-->|<--half timeout-->| |
+ | |<--first period-->| |
+ | |<-----------second sampling period---------->|
+ | | | |
+ snapshot time point 1st-stall 2nd-stall
The following describes four typical scenarios:
-1. A CPU looping with interrupts disabled.::
+1. A CPU looping with interrupts disabled.
- rcu: hardirqs softirqs csw/system
- rcu: number: 0 0 0
- rcu: cputime: 0 0 0 ==> 2500(ms)
+ ::
+
+ rcu: hardirqs softirqs csw/system
+ rcu: number: 0 0 0
+ rcu: cputime: 0 0 0 ==> 2500(ms)
Because interrupts have been disabled throughout the measurement
interval, there are no interrupts and no context switches.
@@ -440,11 +442,11 @@ The following describes four typical scenarios:
This is similar to the previous example, but with non-zero number of
and CPU time consumed by hard interrupts, along with non-zero CPU
- time consumed by in-kernel execution.::
+ time consumed by in-kernel execution::
- rcu: hardirqs softirqs csw/system
- rcu: number: 624 0 0
- rcu: cputime: 49 0 2446 ==> 2500(ms)
+ rcu: hardirqs softirqs csw/system
+ rcu: number: 624 0 0
+ rcu: cputime: 49 0 2446 ==> 2500(ms)
The fact that there are zero softirqs gives a hint that these were
disabled, perhaps via local_bh_disable(). It is of course possible
@@ -454,20 +456,22 @@ The following describes four typical scenarios:
3. A CPU looping with preemption disabled.
- Here, only the number of context switches is zero.::
+ Here, only the number of context switches is zero::
- rcu: hardirqs softirqs csw/system
- rcu: number: 624 45 0
- rcu: cputime: 69 1 2425 ==> 2500(ms)
+ rcu: hardirqs softirqs csw/system
+ rcu: number: 624 45 0
+ rcu: cputime: 69 1 2425 ==> 2500(ms)
This situation hints that the stalled CPU was looping with preemption
disabled.
-4. No looping, but massive hard and soft interrupts.::
+4. No looping, but massive hard and soft interrupts.
+
+ ::
- rcu: hardirqs softirqs csw/system
- rcu: number: xx xx 0
- rcu: cputime: xx xx 0 ==> 2500(ms)
+ rcu: hardirqs softirqs csw/system
+ rcu: number: xx xx 0
+ rcu: cputime: xx xx 0 ==> 2500(ms)
Here, the number and CPU time of hard interrupts are all non-zero,
but the number of context switches and the in-kernel CPU time consumed
--
2.25.1
^ permalink raw reply related [flat|nested] 7+ messages in thread* Re: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
2022-11-24 6:22 [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst Zhen Lei
@ 2022-11-26 1:30 ` Leizhen (ThunderTown)
2022-11-28 4:03 ` Bagas Sanjaya
2022-11-26 3:09 ` Akira Yokosawa
2022-11-28 4:08 ` Bagas Sanjaya
2 siblings, 1 reply; 7+ messages in thread
From: Leizhen (ThunderTown) @ 2022-11-26 1:30 UTC (permalink / raw)
To: Paul E . McKenney, Frederic Weisbecker, Neeraj Upadhyay,
Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, rcu, linux-kernel, Stephen Rothwell, linux-next
Cc: Bagas Sanjaya
On 2022/11/24 14:22, Zhen Lei wrote:
> Documentation/RCU/stallwarn.rst:
> 401: WARNING: Literal block expected; none found.
> 428: WARNING: Literal block expected; none found.
> 445: WARNING: Literal block expected; none found.
> 459: WARNING: Literal block expected; none found.
> 468: WARNING: Literal block expected; none found.
>
> The literal block need to be indented, so add two spaces to each line.
>
> In addition, ':', which is used as a boundary in the literal block, is
> replaced by '|'.
>
> Link: https://lore.kernel.org/linux-next/20221123163255.48653674@canb.auug.org.au/
> Fixes: 3d2788ba4573 ("doc: Document CONFIG_RCU_CPU_STALL_CPUTIME=y stall information")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
> ---
> Documentation/RCU/stallwarn.rst | 56 ++++++++++++++++++---------------
> 1 file changed, 30 insertions(+), 26 deletions(-)
>
> v2 --> v3:
> 1. Add "Link:", "Fixes:", "Reported-by:".
> 2. Remove a orphaned pipe (|).
> 3. Change ". ::" to "::"
Hi, Bagas Sanjaya:
Do you have time to review this patch again? Your review comments are important
because you made comments in the previous version.
>
> v1 --> v2:
> For the case that both colons need to be deleted, change "::" to expanded
> form or partially minimized form.
>
> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
> index c1e92dfef40d501..ca7b7cd806a16c9 100644
> --- a/Documentation/RCU/stallwarn.rst
> +++ b/Documentation/RCU/stallwarn.rst
> @@ -398,9 +398,9 @@ In kernels built with CONFIG_RCU_CPU_STALL_CPUTIME=y or booted with
> rcupdate.rcu_cpu_stall_cputime=1, the following additional information
> is supplied with each RCU CPU stall warning::
>
> -rcu: hardirqs softirqs csw/system
> -rcu: number: 624 45 0
> -rcu: cputime: 69 1 2425 ==> 2500(ms)
> + rcu: hardirqs softirqs csw/system
> + rcu: number: 624 45 0
> + rcu: cputime: 69 1 2425 ==> 2500(ms)
>
> These statistics are collected during the sampling period. The values
> in row "number:" are the number of hard interrupts, number of soft
> @@ -412,22 +412,24 @@ in milliseconds. Because user-mode tasks normally do not cause RCU CPU
> stalls, these tasks are typically kernel tasks, which is why only the
> system CPU time are considered.
>
> -The sampling period is shown as follows:
> -:<------------first timeout---------->:<-----second timeout----->:
> -:<--half timeout-->:<--half timeout-->: :
> -: :<--first period-->: :
> -: :<-----------second sampling period---------->:
> -: : : :
> -: snapshot time point 1st-stall 2nd-stall
> +The sampling period is shown as follows::
>
> + |<------------first timeout---------->|<-----second timeout----->|
> + |<--half timeout-->|<--half timeout-->| |
> + | |<--first period-->| |
> + | |<-----------second sampling period---------->|
> + | | | |
> + snapshot time point 1st-stall 2nd-stall
>
> The following describes four typical scenarios:
>
> -1. A CPU looping with interrupts disabled.::
> +1. A CPU looping with interrupts disabled.
>
> - rcu: hardirqs softirqs csw/system
> - rcu: number: 0 0 0
> - rcu: cputime: 0 0 0 ==> 2500(ms)
> + ::
> +
> + rcu: hardirqs softirqs csw/system
> + rcu: number: 0 0 0
> + rcu: cputime: 0 0 0 ==> 2500(ms)
>
> Because interrupts have been disabled throughout the measurement
> interval, there are no interrupts and no context switches.
> @@ -440,11 +442,11 @@ The following describes four typical scenarios:
>
> This is similar to the previous example, but with non-zero number of
> and CPU time consumed by hard interrupts, along with non-zero CPU
> - time consumed by in-kernel execution.::
> + time consumed by in-kernel execution::
>
> - rcu: hardirqs softirqs csw/system
> - rcu: number: 624 0 0
> - rcu: cputime: 49 0 2446 ==> 2500(ms)
> + rcu: hardirqs softirqs csw/system
> + rcu: number: 624 0 0
> + rcu: cputime: 49 0 2446 ==> 2500(ms)
>
> The fact that there are zero softirqs gives a hint that these were
> disabled, perhaps via local_bh_disable(). It is of course possible
> @@ -454,20 +456,22 @@ The following describes four typical scenarios:
>
> 3. A CPU looping with preemption disabled.
>
> - Here, only the number of context switches is zero.::
> + Here, only the number of context switches is zero::
>
> - rcu: hardirqs softirqs csw/system
> - rcu: number: 624 45 0
> - rcu: cputime: 69 1 2425 ==> 2500(ms)
> + rcu: hardirqs softirqs csw/system
> + rcu: number: 624 45 0
> + rcu: cputime: 69 1 2425 ==> 2500(ms)
>
> This situation hints that the stalled CPU was looping with preemption
> disabled.
>
> -4. No looping, but massive hard and soft interrupts.::
> +4. No looping, but massive hard and soft interrupts.
> +
> + ::
>
> - rcu: hardirqs softirqs csw/system
> - rcu: number: xx xx 0
> - rcu: cputime: xx xx 0 ==> 2500(ms)
> + rcu: hardirqs softirqs csw/system
> + rcu: number: xx xx 0
> + rcu: cputime: xx xx 0 ==> 2500(ms)
>
> Here, the number and CPU time of hard interrupts are all non-zero,
> but the number of context switches and the in-kernel CPU time consumed
>
--
Regards,
Zhen Lei
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
2022-11-26 1:30 ` Leizhen (ThunderTown)
@ 2022-11-28 4:03 ` Bagas Sanjaya
0 siblings, 0 replies; 7+ messages in thread
From: Bagas Sanjaya @ 2022-11-28 4:03 UTC (permalink / raw)
To: Leizhen (ThunderTown)
Cc: Paul E . McKenney, Frederic Weisbecker, Neeraj Upadhyay,
Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, rcu, linux-kernel, Stephen Rothwell, linux-next
[-- Attachment #1: Type: text/plain, Size: 323 bytes --]
On Sat, Nov 26, 2022 at 09:30:32AM +0800, Leizhen (ThunderTown) wrote:
>
> Hi, Bagas Sanjaya:
> Do you have time to review this patch again? Your review comments are important
> because you made comments in the previous version.
>
OK, will review.
--
An old man doll... just what I always wanted! - Clara
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
2022-11-24 6:22 [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst Zhen Lei
2022-11-26 1:30 ` Leizhen (ThunderTown)
@ 2022-11-26 3:09 ` Akira Yokosawa
2022-11-29 1:07 ` Paul E. McKenney
2022-11-28 4:08 ` Bagas Sanjaya
2 siblings, 1 reply; 7+ messages in thread
From: Akira Yokosawa @ 2022-11-26 3:09 UTC (permalink / raw)
To: Zhen Lei, Paul E. McKenney
Cc: bagasdotme, frederic, jiangshanlai, joel, josh, linux-kernel,
linux-next, mathieu.desnoyers, quic_neeraju, rcu, rostedt, sfr,
Akira Yokosawa
Hi,
On Thu, 24 Nov 2022 14:22:03 +0800, Zhen Lei wrote:
> Documentation/RCU/stallwarn.rst:
> 401: WARNING: Literal block expected; none found.
> 428: WARNING: Literal block expected; none found.
> 445: WARNING: Literal block expected; none found.
> 459: WARNING: Literal block expected; none found.
> 468: WARNING: Literal block expected; none found.
>
> The literal block need to be indented, so add two spaces to each line.
>
> In addition, ':', which is used as a boundary in the literal block, is
> replaced by '|'.
>
> Link: https://lore.kernel.org/linux-next/20221123163255.48653674@canb.auug.org.au/
> Fixes: 3d2788ba4573 ("doc: Document CONFIG_RCU_CPU_STALL_CPUTIME=y stall information")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
Tested "make htmldocs" on top of -rcu tree's dev.
Resulting stallwarn.html looks much better!
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Thanks, Akira
> ---
> Documentation/RCU/stallwarn.rst | 56 ++++++++++++++++++---------------
> 1 file changed, 30 insertions(+), 26 deletions(-)
>
> v2 --> v3:
> 1. Add "Link:", "Fixes:", "Reported-by:".
> 2. Remove a orphaned pipe (|).
> 3. Change ". ::" to "::"
>
> v1 --> v2:
> For the case that both colons need to be deleted, change "::" to expanded
> form or partially minimized form.
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
2022-11-26 3:09 ` Akira Yokosawa
@ 2022-11-29 1:07 ` Paul E. McKenney
0 siblings, 0 replies; 7+ messages in thread
From: Paul E. McKenney @ 2022-11-29 1:07 UTC (permalink / raw)
To: Akira Yokosawa
Cc: Zhen Lei, bagasdotme, frederic, jiangshanlai, joel, josh,
linux-kernel, linux-next, mathieu.desnoyers, quic_neeraju, rcu,
rostedt, sfr
On Sat, Nov 26, 2022 at 12:09:01PM +0900, Akira Yokosawa wrote:
> Hi,
>
> On Thu, 24 Nov 2022 14:22:03 +0800, Zhen Lei wrote:
> > Documentation/RCU/stallwarn.rst:
> > 401: WARNING: Literal block expected; none found.
> > 428: WARNING: Literal block expected; none found.
> > 445: WARNING: Literal block expected; none found.
> > 459: WARNING: Literal block expected; none found.
> > 468: WARNING: Literal block expected; none found.
> >
> > The literal block need to be indented, so add two spaces to each line.
> >
> > In addition, ':', which is used as a boundary in the literal block, is
> > replaced by '|'.
> >
> > Link: https://lore.kernel.org/linux-next/20221123163255.48653674@canb.auug.org.au/
> > Fixes: 3d2788ba4573 ("doc: Document CONFIG_RCU_CPU_STALL_CPUTIME=y stall information")
> > Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> > Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
>
> Tested "make htmldocs" on top of -rcu tree's dev.
> Resulting stallwarn.html looks much better!
>
> Tested-by: Akira Yokosawa <akiyks@gmail.com>
Queued for further testing and review, thank you all!
Thanx, Paul
> Thanks, Akira
>
> > ---
> > Documentation/RCU/stallwarn.rst | 56 ++++++++++++++++++---------------
> > 1 file changed, 30 insertions(+), 26 deletions(-)
> >
> > v2 --> v3:
> > 1. Add "Link:", "Fixes:", "Reported-by:".
> > 2. Remove a orphaned pipe (|).
> > 3. Change ". ::" to "::"
> >
> > v1 --> v2:
> > For the case that both colons need to be deleted, change "::" to expanded
> > form or partially minimized form.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
2022-11-24 6:22 [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst Zhen Lei
2022-11-26 1:30 ` Leizhen (ThunderTown)
2022-11-26 3:09 ` Akira Yokosawa
@ 2022-11-28 4:08 ` Bagas Sanjaya
2022-11-28 7:05 ` Leizhen (ThunderTown)
2 siblings, 1 reply; 7+ messages in thread
From: Bagas Sanjaya @ 2022-11-28 4:08 UTC (permalink / raw)
To: Zhen Lei
Cc: Paul E . McKenney, Frederic Weisbecker, Neeraj Upadhyay,
Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, rcu, linux-kernel, Stephen Rothwell, linux-next
[-- Attachment #1: Type: text/plain, Size: 5205 bytes --]
On Thu, Nov 24, 2022 at 02:22:03PM +0800, Zhen Lei wrote:
> Documentation/RCU/stallwarn.rst:
> 401: WARNING: Literal block expected; none found.
> 428: WARNING: Literal block expected; none found.
> 445: WARNING: Literal block expected; none found.
> 459: WARNING: Literal block expected; none found.
> 468: WARNING: Literal block expected; none found.
>
> The literal block need to be indented, so add two spaces to each line.
>
What about following patch description below instead?
```
When merging rcu tree for linux-next, Stephen Rothwell reported htmldocs
warnings:
<warnings>...
These are due to unindented literal blocks. Indent them to fix these
warnings.
```
> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
> index c1e92dfef40d501..ca7b7cd806a16c9 100644
> --- a/Documentation/RCU/stallwarn.rst
> +++ b/Documentation/RCU/stallwarn.rst
> @@ -398,9 +398,9 @@ In kernels built with CONFIG_RCU_CPU_STALL_CPUTIME=y or booted with
> rcupdate.rcu_cpu_stall_cputime=1, the following additional information
> is supplied with each RCU CPU stall warning::
>
> -rcu: hardirqs softirqs csw/system
> -rcu: number: 624 45 0
> -rcu: cputime: 69 1 2425 ==> 2500(ms)
> + rcu: hardirqs softirqs csw/system
> + rcu: number: 624 45 0
> + rcu: cputime: 69 1 2425 ==> 2500(ms)
>
OK.
> -The sampling period is shown as follows:
> -:<------------first timeout---------->:<-----second timeout----->:
> -:<--half timeout-->:<--half timeout-->: :
> -: :<--first period-->: :
> -: :<-----------second sampling period---------->:
> -: : : :
> -: snapshot time point 1st-stall 2nd-stall
> +The sampling period is shown as follows::
>
> + |<------------first timeout---------->|<-----second timeout----->|
> + |<--half timeout-->|<--half timeout-->| |
> + | |<--first period-->| |
> + | |<-----------second sampling period---------->|
> + | | | |
> + snapshot time point 1st-stall 2nd-stall
>
OK.
> The following describes four typical scenarios:
>
> -1. A CPU looping with interrupts disabled.::
> +1. A CPU looping with interrupts disabled.
>
> - rcu: hardirqs softirqs csw/system
> - rcu: number: 0 0 0
> - rcu: cputime: 0 0 0 ==> 2500(ms)
> + ::
> +
> + rcu: hardirqs softirqs csw/system
> + rcu: number: 0 0 0
> + rcu: cputime: 0 0 0 ==> 2500(ms)
OK.
> This is similar to the previous example, but with non-zero number of
> and CPU time consumed by hard interrupts, along with non-zero CPU
> - time consumed by in-kernel execution.::
> + time consumed by in-kernel execution::
>
> - rcu: hardirqs softirqs csw/system
> - rcu: number: 624 0 0
> - rcu: cputime: 49 0 2446 ==> 2500(ms)
> + rcu: hardirqs softirqs csw/system
> + rcu: number: 624 0 0
> + rcu: cputime: 49 0 2446 ==> 2500(ms)
OK.
>
> 3. A CPU looping with preemption disabled.
>
> - Here, only the number of context switches is zero.::
> + Here, only the number of context switches is zero::
>
> - rcu: hardirqs softirqs csw/system
> - rcu: number: 624 45 0
> - rcu: cputime: 69 1 2425 ==> 2500(ms)
> + rcu: hardirqs softirqs csw/system
> + rcu: number: 624 45 0
> + rcu: cputime: 69 1 2425 ==> 2500(ms)
OK.
>
> This situation hints that the stalled CPU was looping with preemption
> disabled.
>
> -4. No looping, but massive hard and soft interrupts.::
> +4. No looping, but massive hard and soft interrupts.
> +
> + ::
No, no that way. For consistency, the item sentence should also be end with
double colon marker:
---- >8 ----
diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
index ca7b7cd806a16c..056127ef2b8e7e 100644
--- a/Documentation/RCU/stallwarn.rst
+++ b/Documentation/RCU/stallwarn.rst
@@ -465,9 +465,7 @@ The following describes four typical scenarios:
This situation hints that the stalled CPU was looping with preemption
disabled.
-4. No looping, but massive hard and soft interrupts.
-
- ::
+4. No looping, but massive hard and soft interrupts::
rcu: hardirqs softirqs csw/system
rcu: number: xx xx 0
Thanks.
--
An old man doll... just what I always wanted! - Clara
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
^ permalink raw reply related [flat|nested] 7+ messages in thread* Re: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
2022-11-28 4:08 ` Bagas Sanjaya
@ 2022-11-28 7:05 ` Leizhen (ThunderTown)
0 siblings, 0 replies; 7+ messages in thread
From: Leizhen (ThunderTown) @ 2022-11-28 7:05 UTC (permalink / raw)
To: Bagas Sanjaya
Cc: Paul E . McKenney, Frederic Weisbecker, Neeraj Upadhyay,
Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, rcu, linux-kernel, Stephen Rothwell, linux-next
On 2022/11/28 12:08, Bagas Sanjaya wrote:
> On Thu, Nov 24, 2022 at 02:22:03PM +0800, Zhen Lei wrote:
>> Documentation/RCU/stallwarn.rst:
>> 401: WARNING: Literal block expected; none found.
>> 428: WARNING: Literal block expected; none found.
>> 445: WARNING: Literal block expected; none found.
>> 459: WARNING: Literal block expected; none found.
>> 468: WARNING: Literal block expected; none found.
>>
>> The literal block need to be indented, so add two spaces to each line.
>>
>
> What about following patch description below instead?
>
> ```
> When merging rcu tree for linux-next, Stephen Rothwell reported htmldocs
> warnings:
>
> <warnings>...
>
> These are due to unindented literal blocks. Indent them to fix these
> warnings.
> ```
That's great. Thanks.
>
>> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
>> index c1e92dfef40d501..ca7b7cd806a16c9 100644
>> --- a/Documentation/RCU/stallwarn.rst
>> +++ b/Documentation/RCU/stallwarn.rst
>> @@ -398,9 +398,9 @@ In kernels built with CONFIG_RCU_CPU_STALL_CPUTIME=y or booted with
>> rcupdate.rcu_cpu_stall_cputime=1, the following additional information
>> is supplied with each RCU CPU stall warning::
>>
>> -rcu: hardirqs softirqs csw/system
>> -rcu: number: 624 45 0
>> -rcu: cputime: 69 1 2425 ==> 2500(ms)
>> + rcu: hardirqs softirqs csw/system
>> + rcu: number: 624 45 0
>> + rcu: cputime: 69 1 2425 ==> 2500(ms)
>>
>
> OK.
>
>> -The sampling period is shown as follows:
>> -:<------------first timeout---------->:<-----second timeout----->:
>> -:<--half timeout-->:<--half timeout-->: :
>> -: :<--first period-->: :
>> -: :<-----------second sampling period---------->:
>> -: : : :
>> -: snapshot time point 1st-stall 2nd-stall
>> +The sampling period is shown as follows::
>>
>> + |<------------first timeout---------->|<-----second timeout----->|
>> + |<--half timeout-->|<--half timeout-->| |
>> + | |<--first period-->| |
>> + | |<-----------second sampling period---------->|
>> + | | | |
>> + snapshot time point 1st-stall 2nd-stall
>>
>
> OK.
>
>> The following describes four typical scenarios:
>>
>> -1. A CPU looping with interrupts disabled.::
>> +1. A CPU looping with interrupts disabled.
>>
>> - rcu: hardirqs softirqs csw/system
>> - rcu: number: 0 0 0
>> - rcu: cputime: 0 0 0 ==> 2500(ms)
>> + ::
>> +
>> + rcu: hardirqs softirqs csw/system
>> + rcu: number: 0 0 0
>> + rcu: cputime: 0 0 0 ==> 2500(ms)
>
> OK.
>
>> This is similar to the previous example, but with non-zero number of
>> and CPU time consumed by hard interrupts, along with non-zero CPU
>> - time consumed by in-kernel execution.::
>> + time consumed by in-kernel execution::
>>
>> - rcu: hardirqs softirqs csw/system
>> - rcu: number: 624 0 0
>> - rcu: cputime: 49 0 2446 ==> 2500(ms)
>> + rcu: hardirqs softirqs csw/system
>> + rcu: number: 624 0 0
>> + rcu: cputime: 49 0 2446 ==> 2500(ms)
>
> OK.
>
>>
>> 3. A CPU looping with preemption disabled.
>>
>> - Here, only the number of context switches is zero.::
>> + Here, only the number of context switches is zero::
>>
>> - rcu: hardirqs softirqs csw/system
>> - rcu: number: 624 45 0
>> - rcu: cputime: 69 1 2425 ==> 2500(ms)
>> + rcu: hardirqs softirqs csw/system
>> + rcu: number: 624 45 0
>> + rcu: cputime: 69 1 2425 ==> 2500(ms)
>
> OK.
>
>>
>> This situation hints that the stalled CPU was looping with preemption
>> disabled.
>>
>> -4. No looping, but massive hard and soft interrupts.::
>> +4. No looping, but massive hard and soft interrupts.
>> +
>> + ::
>
> No, no that way. For consistency, the item sentence should also be end with
> double colon marker:
If you open Documentation/output/RCU/stallwarn.html on a web page, you'll find
that my current change is correct. Indented paragraphs are displayed in smaller
fonts. I want the following four sentences to end with a dot. Subparagraphs that
are subordinate to them are additionally indented. So there's no need to use
colons to emphasize it.
1. A CPU looping with interrupts disabled.
2. A CPU looping with bottom halves disabled.
3. A CPU looping with preemption disabled.
4. No looping, but massive hard and soft interrupts.
>
> ---- >8 ----
>
> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
> index ca7b7cd806a16c..056127ef2b8e7e 100644
> --- a/Documentation/RCU/stallwarn.rst
> +++ b/Documentation/RCU/stallwarn.rst
> @@ -465,9 +465,7 @@ The following describes four typical scenarios:
> This situation hints that the stalled CPU was looping with preemption
> disabled.
>
> -4. No looping, but massive hard and soft interrupts.
> -
> - ::
> +4. No looping, but massive hard and soft interrupts::
>
> rcu: hardirqs softirqs csw/system
> rcu: number: xx xx 0
>
> Thanks.
>
--
Regards,
Zhen Lei
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2022-11-29 1:07 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-11-24 6:22 [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst Zhen Lei
2022-11-26 1:30 ` Leizhen (ThunderTown)
2022-11-28 4:03 ` Bagas Sanjaya
2022-11-26 3:09 ` Akira Yokosawa
2022-11-29 1:07 ` Paul E. McKenney
2022-11-28 4:08 ` Bagas Sanjaya
2022-11-28 7:05 ` Leizhen (ThunderTown)
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox