[PATCH] Docs: locktypes: minor fixes

From: Randy Dunlap
Date: Mon Mar 23 2020 - 11:52:59 EST


From: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

Copy editor fixes:
- add some hyphens to multi-word adjectives
- end some sentences with a period ('.') for consistency
- minor wordsmithing
- use semi-colon instead of comma in a sentence


Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Cc: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
Cc: "Paul E . McKenney" <paulmck@xxxxxxxxxx>
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: Davidlohr Bueso <dave@xxxxxxxxxxxx>
Cc: Joel Fernandes (Google) <joel@xxxxxxxxxxxxxxxxx>
Cc: Sebastian Andrzej Siewior <bigeasy@xxxxxxxxxxxxx>
---
Applies to your PATCH V3 13/20] of 2020-03-21.

Documentation/locking/locktypes.rst | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)

--- linux-next-20200323.orig/Documentation/locking/locktypes.rst
+++ linux-next-20200323/Documentation/locking/locktypes.rst
@@ -73,7 +73,7 @@ rtmutex

RT-mutexes are mutexes with support for priority inheritance (PI).

-PI has limitations on non PREEMPT_RT enabled kernels due to preemption and
+PI has limitations on non-PREEMPT_RT-enabled kernels due to preemption and
interrupt disabled sections.

PI clearly cannot preempt preemption-disabled or interrupt-disabled
@@ -90,11 +90,11 @@ raw_spinlock_t
--------------

raw_spinlock_t is a strict spinning lock implementation regardless of the
-kernel configuration including PREEMPT_RT enabled kernels.
+kernel configuration including PREEMPT_RT-enabled kernels.

raw_spinlock_t is a strict spinning lock implementation in all kernels,
including PREEMPT_RT kernels. Use raw_spinlock_t only in real critical
-core code, low level interrupt handling and places where disabling
+core code, low-level interrupt handling and places where disabling
preemption or interrupts is required, for example, to safely access
hardware state. raw_spinlock_t can sometimes also be used when the
critical section is tiny, thus avoiding RT-mutex overhead.
@@ -104,20 +104,20 @@ spinlock_t

The semantics of spinlock_t change with the state of CONFIG_PREEMPT_RT.

-On a non PREEMPT_RT enabled kernel spinlock_t is mapped to raw_spinlock_t
+On a non-PREEMPT_RT-enabled kernel spinlock_t is mapped to raw_spinlock_t
and has exactly the same semantics.

spinlock_t and PREEMPT_RT
-------------------------

-On a PREEMPT_RT enabled kernel spinlock_t is mapped to a separate
+On a PREEMPT_RT-enabled kernel spinlock_t is mapped to a separate
implementation based on rt_mutex which changes the semantics:

- - Preemption is not disabled
+ - Preemption is not disabled.

- The hard interrupt related suffixes for spin_lock / spin_unlock
operations (_irq, _irqsave / _irqrestore) do not affect the CPUs
- interrupt disabled state
+ interrupt disabled state.

- The soft interrupt related suffix (_bh()) still disables softirq
handlers.
@@ -194,8 +194,8 @@ and is fully equivalent to::

Same applies to rwlock_t and the _irqsave() suffix variants.

-On PREEMPT_RT kernel this code sequence breaks because RT-mutex requires a
-fully preemptible context. Instead, use spin_lock_irq() or
+On a PREEMPT_RT kernel this code sequence breaks because RT-mutex requires
+a fully preemptible context. Instead, use spin_lock_irq() or
spin_lock_irqsave() and their unlock counterparts. In cases where the
interrupt disabling and locking must remain separate, PREEMPT_RT offers a
local_lock mechanism. Acquiring the local_lock pins the task to a CPU,
@@ -257,7 +257,7 @@ The most basic rules are:
These rules apply in general independent of CONFIG_PREEMPT_RT.

As PREEMPT_RT changes the lock category of spinlock_t and rwlock_t from
-spinning to sleeping this has obviously restrictions how they can nest with
+spinning to sleeping this has obvious restrictions on how they can nest with
raw_spinlock_t.

This results in the following nest ordering:
@@ -286,7 +286,7 @@ often used for both serialization and wa
discouraged and should be replaced by separate serialization and wait
mechanisms, such as mutexes and completions.

-rwsems have grown interfaces which allow non owner release for special
+rwsems have grown interfaces which allow non-owner release for special
purposes. This usage is problematic on PREEMPT_RT because PREEMPT_RT
substitutes all locking primitives except semaphores with RT-mutex based
implementations to provide priority inheritance for all lock types except
@@ -295,5 +295,5 @@ obviously impossible.

For now the rwsem non-owner release excludes code which utilizes it from
being used on PREEMPT_RT enabled kernels. In same cases this can be
-mitigated by disabling portions of the code, in other cases the complete
+mitigated by disabling portions of the code; in other cases the complete
functionality has to be disabled until a workable solution has been found.