lkml.org 
[lkml]   [2022]   [Nov]   [28]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
From
Date


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

\
 
 \ /
  Last update: 2022-11-28 08:05    [W:0.077 / U:0.128 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site