lkml.org 
[lkml]   [2022]   [Nov]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
Date
From
SubjectRe: [PATCH v3] doc: Fix htmldocs build warnings of stallwarn.rst
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.

--
An old man doll... just what I always wanted! - Clara
[unhandled content-type:application/pgp-signature]
\
 
 \ /
  Last update: 2022-11-28 05:10    [W:0.062 / U:0.068 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site