| Message ID | 20221124062204.1932-1-thunder.leizhen@huawei.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | c8af7430ce657490ad95a192bd1ab64e3e95b5c5 |
| Headers | show |
| Series | [v3] doc: Fix htmldocs build warnings of stallwarn.rst | expand |
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 >
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 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.
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.
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. >
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.
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
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.