Documentation/RCU/stallwarn.rst | 56 ++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 26 deletions(-)
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.1On 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
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
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.
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.
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
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
© 2016 - 2026 Red Hat, Inc.