On 2022/11/24 11:34, Leizhen (ThunderTown) wrote: > > > On 2022/11/23 21:54, Bagas Sanjaya wrote: >> On Wed, Nov 23, 2022 at 08:02:38PM +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. >> >> Indenting to match alignment of lists texts? > > It's required by reStructuredText Markup Specification. > > Indented Literal Blocks > Indented literal blocks are indicated by indentation relative to the > surrounding text (leading whitespace on each line). The literal block > ends with the end of the indentation. > > The surrounding text need to be indented, relative to the paragraphs > above and below it and at the same level. > >> >>> Signed-off-by: Zhen Lei <thunder.leizhen@xxxxxxxxxx> >> >> You miss crediting linux-next list, so please add: >> >> Link: https://lore.kernel.org/linux-next/20221123163255.48653674@xxxxxxxxxxxxxxxx/ >> Fixes: 3d2788ba4573 ("doc: Document CONFIG_RCU_CPU_STALL_CPUTIME=y stall information") >> Reported-by: Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx> > > OK, thanks. > >> >>> -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 beginning pipe (|) on the last line of diagram above shouldn't be there >> (axis label?). > > OK, it might look better to delete it. > > The text in literal block is treated as plain text. > > >> >>> >>> 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 >>> >> >> Because paragraphs below the snippets directly refers to them,just use colon: > > This makes the style inconsistent when viewed on the web page. So I decided not > to change it. > > Take your advice and the end result will be as follows: (1 and 4 followed by a > colon, 2 and 3 followed by a dot) > > 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: Oh, I accept the suggestions for items 2 and 3. > >> >> ---- >8 ---- >> >> diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst >> index f15b766d39b8d9..4f6b91be03cfe0 100644 >> --- a/Documentation/RCU/stallwarn.rst >> +++ b/Documentation/RCU/stallwarn.rst >> @@ -423,9 +423,7 @@ The sampling period is shown as follows:: >> >> 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 >> @@ -442,7 +440,7 @@ 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 >> @@ -456,7 +454,7 @@ 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 >> @@ -465,9 +463,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
