Date:   Sat, 11 Nov 2017 22:26:32 +0900
From:   Byungchul Park <byungchul.park@....com>
To:     peterz@...radead.org, mingo@...nel.org
Cc:     tglx@...utronix.de, linux-kernel@...r.kernel.org,
        linux-mm@...ck.org, linux-block@...r.kernel.org,
        kernel-team@....com
Subject: [PATCH v3 5/5] locking/Documentation: Align crossrelease.txt with the width

No change of contents at all. Only adjust the width.

(Please merge this to another after the review.)

Signed-off-by: Byungchul Park <byungchul.park@....com>
---
 Documentation/locking/crossrelease.txt | 59 +++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 29 deletions(-)

diff --git a/Documentation/locking/crossrelease.txt b/Documentation/locking/crossrelease.txt
index dac56f4..c6d628b 100644
--- a/Documentation/locking/crossrelease.txt
+++ b/Documentation/locking/crossrelease.txt
@@ -61,9 +61,9 @@ turn cannot be triggered if event B does not happen, which in turn
 cannot be triggered if event C does not happen. After all, no event can
 be triggered since any of them never meets its condition to wake up.
 
-A dependency might exist between two waiters and a deadlock happens
-due to an incorrect relationship between dependencies. Thus, we must
-define what a dependency is first. A dependency exists if:
+A dependency might exist between two waiters and a deadlock happens due
+to an incorrect relationship between dependencies. Thus, we must define
+what a dependency is first. A dependency exists if:
 
    1. There are two waiters waiting for each event at a given time.
    2. The only way to wake up each waiter is to trigger its event.
@@ -304,10 +304,10 @@ Considering only typical locks, lockdep builds nothing. However,
 relaxing the limitation, a dependency 'A -> B' can be added, giving us
 more chances to check circular dependencies.
 
-However, it might suffer performance degradation since
-relaxing the limitation, with which design and implementation of lockdep
-can be efficient, might introduce inefficiency inevitably. So lockdep
-should provide two options, strong detection and efficient detection.
+However, it might suffer performance degradation since relaxing the
+limitation, with which design and implementation of lockdep can be
+efficient, might introduce inefficiency inevitably. So lockdep should
+provide two options, strong detection and efficient detection.
 
 Choosing efficient detection:
 
@@ -404,8 +404,8 @@ There are four types of dependencies:
 
    When acquiring BX, lockdep cannot identify the dependency because
    there's no way to know if it's in the AX's release context. It has
-   to wait until the decision can be made. Commit is necessary.
-   But, handling CC type is not implemented yet. It's a future work.
+   to wait until the decision can be made. Commit is necessary. But,
+   handling CC type is not implemented yet. It's a future work.
 
 Lockdep can work without commit for typical locks, but the step is
 necessary once crosslocks are involved. Introducing commit, lockdep
@@ -442,9 +442,9 @@ Crossrelease introduces two main data structures.
 
    This is an array embedded in task_struct, for keeping lock history so
    that dependencies can be added using them at the commit step. Since
-   they are local data, they can be accessed locklessly in the owner context.
-   The array is filled at the acquisition step and consumed at the
-   commit step. And it's managed in a circular manner.
+   they are local data, they can be accessed locklessly in the owner
+   context. The array is filled at the acquisition step and consumed at
+   the commit step. And it's managed in a circular manner.
 
 2. cross_lock
 
@@ -470,8 +470,8 @@ works for typical locks, without crossrelease.
 
    where A, B, and C are different lock classes.
 
-Lockdep adds 'the top of held_locks -> the lock to acquire'
-dependency every time acquiring a lock.
+Lockdep adds 'the top of held_locks -> the lock to acquire' dependency
+every time acquiring a lock.
 
 After adding 'A -> B', the dependency graph will be:
 
@@ -561,10 +561,10 @@ for A, B, and C, the graph will be:
    NOTE: A dependency 'A -> C' is optimized out.
 
 We can see the former graph built without the commit step is same as the
-latter graph. Of course, the former way leads to
-earlier finish for building the graph, which means we can detect a
-deadlock or its possibility sooner. So the former way would be preferred
-when possible. But we cannot avoid using the latter way for crosslocks.
+latter graph. Of course, the former way leads to earlier finish for
+building the graph, which means we can detect a deadlock or its
+possibility sooner. So the former way would be preferred when possible.
+But we cannot avoid using the latter way for crosslocks.
 
 Lastly, let's look at how commit works for crosslocks in practice.
 
@@ -685,10 +685,10 @@ Lastly, let's look at how commit works for crosslocks in practice.
 
 Crossrelease considers all acquisitions following acquiring BX because
 they can create dependencies with BX. The dependencies will be
-determined in the release context of BX. Meanwhile,
-all typical locks are queued so that they can be used at the commit step.
-Finally, two dependencies 'BX -> C' and 'BX -> E' will be added at the
-commit step, when identifying the release context.
+determined in the release context of BX. Meanwhile, all typical locks
+are queued so that they can be used at the commit step. Finally, two
+dependencies 'BX -> C' and 'BX -> E' will be added at the commit step,
+when identifying the release context.
 
 The final graph will be, with crossrelease:
 
@@ -737,8 +737,8 @@ Make hot paths lockless
 To keep all locks for later use at the commit step, crossrelease adopts
 a local array embedded in task_struct, which makes the data locklessly
 accessible by forcing it to happen only within the owner context. It's
-like how lockdep handles held_locks. Lockless implementation is important
-since typical locks are very frequently acquired and released.
+like how lockdep handles held_locks. Lockless implementation is
+important since typical locks are very frequently acquired and released.
 
 
 =================================================
@@ -751,9 +751,10 @@ deadlock exists if the problematic dependencies exist. Thus, it's
 meaningful to detect not only an actual deadlock but also its potential
 possibility. The latter is rather valuable. When a deadlock actually
 occurs, we can identify what happens in the system by some means or
-other even without lockdep. However, there's no way to detect a possibility
-without lockdep, unless the whole code is parsed in the head. It's terrible.
-Lockdep does the both, and crossrelease only focuses on the latter.
+other even without lockdep. However, there's no way to detect a
+possibility without lockdep, unless the whole code is parsed in the head.
+It's terrible. Lockdep does the both, and crossrelease only focuses on
+the latter.
 
 Whether or not a deadlock actually occurs depends on several factors.
 For example, what order contexts are switched in is a factor. Assuming
@@ -845,8 +846,8 @@ we can ensure nothing but what actually happened. Relying on what
 actually happens at runtime, we can anyway add only true ones, though
 they might be a subset of true ones. It's similar to how lockdep works
 for typical locks. There might be more true dependencies than lockdep
-has detected. Lockdep has no choice but to rely on
-what actually happens. Crossrelease also relies on it.
+has detected. Lockdep has no choice but to rely on what actually happens.
+Crossrelease also relies on it.
 
 CONCLUSION
 
-- 
1.9.1

Powered by blists - more mailing lists