Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

doc: Fix htmldocs build warnings of stallwarn.rst

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 needs to be indented, so this commit adds two spaces
to each line.

In addition, ':', which is used as a boundary in the literal block, is
replaced by '|'.

Link: https://lore.kernel.org/linux-next/20221123163255.48653674@canb.auug.org.au/
Fixes: 3d2788ba4573 ("doc: Document CONFIG_RCU_CPU_STALL_CPUTIME=y stall information")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

authored by

Zhen Lei and committed by
Paul E. McKenney
5e013dc1 eff86459

+30 -26
+30 -26
Documentation/RCU/stallwarn.rst
··· 398 398 rcupdate.rcu_cpu_stall_cputime=1, the following additional information 399 399 is supplied with each RCU CPU stall warning:: 400 400 401 - rcu: hardirqs softirqs csw/system 402 - rcu: number: 624 45 0 403 - rcu: cputime: 69 1 2425 ==> 2500(ms) 401 + rcu: hardirqs softirqs csw/system 402 + rcu: number: 624 45 0 403 + rcu: cputime: 69 1 2425 ==> 2500(ms) 404 404 405 405 These statistics are collected during the sampling period. The values 406 406 in row "number:" are the number of hard interrupts, number of soft ··· 412 412 stalls, these tasks are typically kernel tasks, which is why only the 413 413 system CPU time are considered. 414 414 415 - The sampling period is shown as follows: 416 - :<------------first timeout---------->:<-----second timeout----->: 417 - :<--half timeout-->:<--half timeout-->: : 418 - : :<--first period-->: : 419 - : :<-----------second sampling period---------->: 420 - : : : : 421 - : snapshot time point 1st-stall 2nd-stall 415 + The sampling period is shown as follows:: 422 416 417 + |<------------first timeout---------->|<-----second timeout----->| 418 + |<--half timeout-->|<--half timeout-->| | 419 + | |<--first period-->| | 420 + | |<-----------second sampling period---------->| 421 + | | | | 422 + snapshot time point 1st-stall 2nd-stall 423 423 424 424 The following describes four typical scenarios: 425 425 426 - 1. A CPU looping with interrupts disabled.:: 426 + 1. A CPU looping with interrupts disabled. 427 427 428 - rcu: hardirqs softirqs csw/system 429 - rcu: number: 0 0 0 430 - rcu: cputime: 0 0 0 ==> 2500(ms) 428 + :: 429 + 430 + rcu: hardirqs softirqs csw/system 431 + rcu: number: 0 0 0 432 + rcu: cputime: 0 0 0 ==> 2500(ms) 431 433 432 434 Because interrupts have been disabled throughout the measurement 433 435 interval, there are no interrupts and no context switches. ··· 442 440 443 441 This is similar to the previous example, but with non-zero number of 444 442 and CPU time consumed by hard interrupts, along with non-zero CPU 445 - time consumed by in-kernel execution.:: 443 + time consumed by in-kernel execution:: 446 444 447 - rcu: hardirqs softirqs csw/system 448 - rcu: number: 624 0 0 449 - rcu: cputime: 49 0 2446 ==> 2500(ms) 445 + rcu: hardirqs softirqs csw/system 446 + rcu: number: 624 0 0 447 + rcu: cputime: 49 0 2446 ==> 2500(ms) 450 448 451 449 The fact that there are zero softirqs gives a hint that these were 452 450 disabled, perhaps via local_bh_disable(). It is of course possible ··· 456 454 457 455 3. A CPU looping with preemption disabled. 458 456 459 - Here, only the number of context switches is zero.:: 457 + Here, only the number of context switches is zero:: 460 458 461 - rcu: hardirqs softirqs csw/system 462 - rcu: number: 624 45 0 463 - rcu: cputime: 69 1 2425 ==> 2500(ms) 459 + rcu: hardirqs softirqs csw/system 460 + rcu: number: 624 45 0 461 + rcu: cputime: 69 1 2425 ==> 2500(ms) 464 462 465 463 This situation hints that the stalled CPU was looping with preemption 466 464 disabled. 467 465 468 - 4. No looping, but massive hard and soft interrupts.:: 466 + 4. No looping, but massive hard and soft interrupts. 469 467 470 - rcu: hardirqs softirqs csw/system 471 - rcu: number: xx xx 0 472 - rcu: cputime: xx xx 0 ==> 2500(ms) 468 + :: 469 + 470 + rcu: hardirqs softirqs csw/system 471 + rcu: number: xx xx 0 472 + rcu: cputime: xx xx 0 ==> 2500(ms) 473 473 474 474 Here, the number and CPU time of hard interrupts are all non-zero, 475 475 but the number of context switches and the in-kernel CPU time consumed