Re: [PATCH v3 2/6] docs: lockdep-design: fix some warning issues

2020-10-22 Thread Boqun Feng 
On Wed, Oct 21, 2020 at 02:17:23PM +0200, Mauro Carvalho Chehab wrote:
> There are several warnings caused by a recent change
> 224ec489d3cd ("lockdep/Documention: Recursive read lock detection reasoning")
> 
> Those are reported by htmldocs build:
> 
> Documentation/locking/lockdep-design.rst:429: WARNING: Definition list 
> ends without a blank line; unexpected unindent.
> Documentation/locking/lockdep-design.rst:452: WARNING: Block quote ends 
> without a blank line; unexpected unindent.
> Documentation/locking/lockdep-design.rst:453: WARNING: Unexpected 
> indentation.
> Documentation/locking/lockdep-design.rst:453: WARNING: Blank line 
> required after table.
> Documentation/locking/lockdep-design.rst:454: WARNING: Block quote ends 
> without a blank line; unexpected unindent.
> Documentation/locking/lockdep-design.rst:455: WARNING: Unexpected 
> indentation.
> Documentation/locking/lockdep-design.rst:455: WARNING: Blank line 
> required after table.
> Documentation/locking/lockdep-design.rst:456: WARNING: Block quote ends 
> without a blank line; unexpected unindent.
> Documentation/locking/lockdep-design.rst:457: WARNING: Unexpected 
> indentation.
> Documentation/locking/lockdep-design.rst:457: WARNING: Blank line 
> required after table.
> 
> Besides the reported issues, there are some missing blank
> lines that ended producing wrong html output, and some
> literals are not properly identified.
> 
> Also, the symbols used at the irq enabled/disable table
> are not displayed as expected, as they're not literals.
> Also, on another table they're using a different notation.
> 
> Fixes: 224ec489d3cd ("lockdep/Documention: Recursive read lock detection 
> reasoning")
> Signed-off-by: Mauro Carvalho Chehab 

Acked-by: Boqun Feng 

Regards,
Boqun

> ---
>  Documentation/locking/lockdep-design.rst | 51 ++--
>  1 file changed, 31 insertions(+), 20 deletions(-)
> 
> diff --git a/Documentation/locking/lockdep-design.rst 
> b/Documentation/locking/lockdep-design.rst
> index cec03bd1294a..9f3cfca9f8a4 100644
> --- a/Documentation/locking/lockdep-design.rst
> +++ b/Documentation/locking/lockdep-design.rst
> @@ -42,6 +42,7 @@ The validator tracks lock-class usage history and divides 
> the usage into
>  (4 usages * n STATEs + 1) categories:
>  
>  where the 4 usages can be:
> +
>  - 'ever held in STATE context'
>  - 'ever held as readlock in STATE context'
>  - 'ever held with STATE enabled'
> @@ -49,10 +50,12 @@ where the 4 usages can be:
>  
>  where the n STATEs are coded in kernel/locking/lockdep_states.h and as of
>  now they include:
> +
>  - hardirq
>  - softirq
>  
>  where the last 1 category is:
> +
>  - 'ever used'   [ == !unused]
>  
>  When locking rules are violated, these usage bits are presented in the
> @@ -96,9 +99,9 @@ exact case is for the lock as of the reporting time.
>+--+-+--+
>|  | irq enabled | irq disabled |
>+--+-+--+
> -  | ever in irq  |  ?  |   -  |
> +  | ever in irq  | '?' |  '-' |
>+--+-+--+
> -  | never in irq |  +  |   .  |
> +  | never in irq | '+' |  '.' |
>+--+-+--+
>  
>  The character '-' suggests irq is disabled because if otherwise the
> @@ -216,7 +219,7 @@ looks like this::
> BD_MUTEX_PARTITION
>};
>  
> -mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
> +  mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
>  
>  In this case the locking is done on a bdev object that is known to be a
>  partition.
> @@ -334,7 +337,7 @@ Troubleshooting:
>  
>  
>  The validator tracks a maximum of MAX_LOCKDEP_KEYS number of lock classes.
> -Exceeding this number will trigger the following lockdep warning:
> +Exceeding this number will trigger the following lockdep warning::
>  
>   (DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS))
>  
> @@ -420,7 +423,8 @@ the critical section of another reader of the same lock 
> instance.
>  
>  The difference between recursive readers and non-recursive readers is 
> because:
>  recursive readers get blocked only by a write lock *holder*, while 
> non-recursive
> -readers could get blocked by a write lock *waiter*. Considering the follow 
> example:
> +readers could get blocked by a write lock *waiter*. Considering the follow
> +example::
>  
>   TASK A: TASK B:
>  
> @@ -448,20 +452,22 @@ There are simply four block conditions:
>  
>  Block condition matrix, Y means the row blocks the column, and N means 
> otherwise.
>  
> - | E | r | R |
>   +---+---+---+---+
> -   E | Y | Y | Y |
> + |   | E | r | R |
>   +---+---+---+---+
> -   r | Y | Y | N |
> + | E | Y | Y | Y |
> + +---+---+---+---+

[PATCH v3 2/6] docs: lockdep-design: fix some warning issues

2020-10-21 Thread Mauro Carvalho Chehab 
There are several warnings caused by a recent change
224ec489d3cd ("lockdep/Documention: Recursive read lock detection reasoning")

Those are reported by htmldocs build:

Documentation/locking/lockdep-design.rst:429: WARNING: Definition list ends 
without a blank line; unexpected unindent.
Documentation/locking/lockdep-design.rst:452: WARNING: Block quote ends 
without a blank line; unexpected unindent.
Documentation/locking/lockdep-design.rst:453: WARNING: Unexpected 
indentation.
Documentation/locking/lockdep-design.rst:453: WARNING: Blank line required 
after table.
Documentation/locking/lockdep-design.rst:454: WARNING: Block quote ends 
without a blank line; unexpected unindent.
Documentation/locking/lockdep-design.rst:455: WARNING: Unexpected 
indentation.
Documentation/locking/lockdep-design.rst:455: WARNING: Blank line required 
after table.
Documentation/locking/lockdep-design.rst:456: WARNING: Block quote ends 
without a blank line; unexpected unindent.
Documentation/locking/lockdep-design.rst:457: WARNING: Unexpected 
indentation.
Documentation/locking/lockdep-design.rst:457: WARNING: Blank line required 
after table.

Besides the reported issues, there are some missing blank
lines that ended producing wrong html output, and some
literals are not properly identified.

Also, the symbols used at the irq enabled/disable table
are not displayed as expected, as they're not literals.
Also, on another table they're using a different notation.

Fixes: 224ec489d3cd ("lockdep/Documention: Recursive read lock detection 
reasoning")
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/locking/lockdep-design.rst | 51 ++--
 1 file changed, 31 insertions(+), 20 deletions(-)

diff --git a/Documentation/locking/lockdep-design.rst 
b/Documentation/locking/lockdep-design.rst
index cec03bd1294a..9f3cfca9f8a4 100644
--- a/Documentation/locking/lockdep-design.rst
+++ b/Documentation/locking/lockdep-design.rst
@@ -42,6 +42,7 @@ The validator tracks lock-class usage history and divides the 
usage into
 (4 usages * n STATEs + 1) categories:
 
 where the 4 usages can be:
+
 - 'ever held in STATE context'
 - 'ever held as readlock in STATE context'
 - 'ever held with STATE enabled'
@@ -49,10 +50,12 @@ where the 4 usages can be:
 
 where the n STATEs are coded in kernel/locking/lockdep_states.h and as of
 now they include:
+
 - hardirq
 - softirq
 
 where the last 1 category is:
+
 - 'ever used'   [ == !unused]
 
 When locking rules are violated, these usage bits are presented in the
@@ -96,9 +99,9 @@ exact case is for the lock as of the reporting time.
   +--+-+--+
   |  | irq enabled | irq disabled |
   +--+-+--+
-  | ever in irq  |  ?  |   -  |
+  | ever in irq  | '?' |  '-' |
   +--+-+--+
-  | never in irq |  +  |   .  |
+  | never in irq | '+' |  '.' |
   +--+-+--+
 
 The character '-' suggests irq is disabled because if otherwise the
@@ -216,7 +219,7 @@ looks like this::
BD_MUTEX_PARTITION
   };
 
-mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+  mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
 
 In this case the locking is done on a bdev object that is known to be a
 partition.
@@ -334,7 +337,7 @@ Troubleshooting:
 
 
 The validator tracks a maximum of MAX_LOCKDEP_KEYS number of lock classes.
-Exceeding this number will trigger the following lockdep warning:
+Exceeding this number will trigger the following lockdep warning::
 
(DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS))
 
@@ -420,7 +423,8 @@ the critical section of another reader of the same lock 
instance.
 
 The difference between recursive readers and non-recursive readers is because:
 recursive readers get blocked only by a write lock *holder*, while 
non-recursive
-readers could get blocked by a write lock *waiter*. Considering the follow 
example:
+readers could get blocked by a write lock *waiter*. Considering the follow
+example::
 
TASK A: TASK B:
 
@@ -448,20 +452,22 @@ There are simply four block conditions:
 
 Block condition matrix, Y means the row blocks the column, and N means 
otherwise.
 
-   | E | r | R |
+---+---+---+---+
- E | Y | Y | Y |
+   |   | E | r | R |
+---+---+---+---+
- r | Y | Y | N |
+   | E | Y | Y | Y |
+   +---+---+---+---+
+   | r | Y | Y | N |
+   +---+---+---+---+
+   | R | Y | Y | N |
+---+---+---+---+
- R | Y | Y | N |
 
(W: writers, r: non-recursive readers, R: recursive readers)
 
 
 acquired recursively. Unlike non-recursive read locks, recursive read locks
 only get blocked by current write lock *holders* other than