| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Date: Mon, 28 Nov 2022 15:05:18 +0800
From: "Leizhen (ThunderTown)" <thunder.leizhen@...wei.com>
To: Bagas Sanjaya <bagasdotme@...il.com>
CC: "Paul E . McKenney" <paulmck@...nel.org>,
Frederic Weisbecker <frederic@...nel.org>,
Neeraj Upadhyay <quic_neeraju@...cinc.com>,
"Josh Triplett" <josh@...htriplett.org>,
Steven Rostedt <rostedt@...dmis.org>,
Mathieu Desnoyers <mathieu.desnoyers@...icios.com>,
Lai Jiangshan <jiangshanlai@...il.com>,
Joel Fernandes <joel@...lfernandes.org>, <rcu@...r.kernel.org>,
<linux-kernel@...r.kernel.org>,
Stephen Rothwell <sfr@...b.auug.org.au>,
<linux-next@...r.kernel.org>
Subject: Re: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
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
Powered by blists - more mailing lists