Re: [PATCH v2] doc: Fix htmldocs build warnings of stallwarn.rst

From: Leizhen (ThunderTown)
Date: Wed Nov 23 2022 - 22:57:38 EST




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