2020-05-01 15:40:09

by Mauro Carvalho Chehab

[permalink] [raw]
Subject: [PATCH 10/14] docs: move locking-specific documenta to locking/ directory

Several files under Documentation/*.txt describe some type of
locking API. Move them to locking/ subdir and add to the
locking/index.rst index file.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
.../{futex-requeue-pi.txt => locking/futex-requeue-pi.rst} | 0
Documentation/{hwspinlock.txt => locking/hwspinlock.rst} | 0
Documentation/locking/index.rst | 7 +++++++
.../percpu-rw-semaphore.rst} | 0
Documentation/{pi-futex.txt => locking/pi-futex.rst} | 0
.../{preempt-locking.txt => locking/preempt-locking.rst} | 0
.../{robust-futex-ABI.txt => locking/robust-futex-ABI.rst} | 0
.../{robust-futexes.txt => locking/robust-futexes.rst} | 0
Documentation/locking/rt-mutex.rst | 2 +-
MAINTAINERS | 6 +++---
10 files changed, 11 insertions(+), 4 deletions(-)
rename Documentation/{futex-requeue-pi.txt => locking/futex-requeue-pi.rst} (100%)
rename Documentation/{hwspinlock.txt => locking/hwspinlock.rst} (100%)
rename Documentation/{percpu-rw-semaphore.txt => locking/percpu-rw-semaphore.rst} (100%)
rename Documentation/{pi-futex.txt => locking/pi-futex.rst} (100%)
rename Documentation/{preempt-locking.txt => locking/preempt-locking.rst} (100%)
rename Documentation/{robust-futex-ABI.txt => locking/robust-futex-ABI.rst} (100%)
rename Documentation/{robust-futexes.txt => locking/robust-futexes.rst} (100%)

diff --git a/Documentation/futex-requeue-pi.txt b/Documentation/locking/futex-requeue-pi.rst
similarity index 100%
rename from Documentation/futex-requeue-pi.txt
rename to Documentation/locking/futex-requeue-pi.rst
diff --git a/Documentation/hwspinlock.txt b/Documentation/locking/hwspinlock.rst
similarity index 100%
rename from Documentation/hwspinlock.txt
rename to Documentation/locking/hwspinlock.rst
diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst
index 5d6800a723dc..d785878cad65 100644
--- a/Documentation/locking/index.rst
+++ b/Documentation/locking/index.rst
@@ -16,6 +16,13 @@ locking
rt-mutex
spinlocks
ww-mutex-design
+ preempt-locking
+ pi-futex
+ futex-requeue-pi
+ hwspinlock
+ percpu-rw-semaphore
+ robust-futexes
+ robust-futex-ABI

.. only:: subproject and html

diff --git a/Documentation/percpu-rw-semaphore.txt b/Documentation/locking/percpu-rw-semaphore.rst
similarity index 100%
rename from Documentation/percpu-rw-semaphore.txt
rename to Documentation/locking/percpu-rw-semaphore.rst
diff --git a/Documentation/pi-futex.txt b/Documentation/locking/pi-futex.rst
similarity index 100%
rename from Documentation/pi-futex.txt
rename to Documentation/locking/pi-futex.rst
diff --git a/Documentation/preempt-locking.txt b/Documentation/locking/preempt-locking.rst
similarity index 100%
rename from Documentation/preempt-locking.txt
rename to Documentation/locking/preempt-locking.rst
diff --git a/Documentation/robust-futex-ABI.txt b/Documentation/locking/robust-futex-ABI.rst
similarity index 100%
rename from Documentation/robust-futex-ABI.txt
rename to Documentation/locking/robust-futex-ABI.rst
diff --git a/Documentation/robust-futexes.txt b/Documentation/locking/robust-futexes.rst
similarity index 100%
rename from Documentation/robust-futexes.txt
rename to Documentation/locking/robust-futexes.rst
diff --git a/Documentation/locking/rt-mutex.rst b/Documentation/locking/rt-mutex.rst
index c365dc302081..3b5097a380e6 100644
--- a/Documentation/locking/rt-mutex.rst
+++ b/Documentation/locking/rt-mutex.rst
@@ -4,7 +4,7 @@ RT-mutex subsystem with PI support

RT-mutexes with priority inheritance are used to support PI-futexes,
which enable pthread_mutex_t priority inheritance attributes
-(PTHREAD_PRIO_INHERIT). [See Documentation/pi-futex.txt for more details
+(PTHREAD_PRIO_INHERIT). [See Documentation/locking/pi-futex.rst for more details
about PI-futexes.]

This technology was developed in the -rt tree and streamlined for
diff --git a/MAINTAINERS b/MAINTAINERS
index 6eb3d85a646f..1aa6e89e7424 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7042,13 +7042,13 @@ R: Darren Hart <[email protected]>
L: [email protected]
S: Maintained
T: git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git locking/core
-F: Documentation/*futex*
+F: Documentation/locking/*futex*
F: include/asm-generic/futex.h
F: include/linux/futex.h
F: include/uapi/linux/futex.h
F: kernel/futex.c
F: tools/perf/bench/futex*
-F: tools/testing/selftests/futex/
+F: Documentation/locking/*futex*

GASKET DRIVER FRAMEWORK
M: Rob Springer <[email protected]>
@@ -7519,7 +7519,7 @@ L: [email protected]
S: Maintained
T: git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git hwspinlock-next
F: Documentation/devicetree/bindings/hwlock/
-F: Documentation/hwspinlock.txt
+F: Documentation/locking/hwspinlock.rst
F: drivers/hwspinlock/
F: include/linux/hwspinlock.h

--
2.25.4


2020-05-15 18:10:20

by Jonathan Corbet

[permalink] [raw]
Subject: Re: [PATCH 10/14] docs: move locking-specific documenta to locking/ directory

On Fri, 1 May 2020 17:37:54 +0200
Mauro Carvalho Chehab <[email protected]> wrote:

> Several files under Documentation/*.txt describe some type of
> locking API. Move them to locking/ subdir and add to the
> locking/index.rst index file.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>

I've applied this, but it really seems like this belongs in the core-api
manual someday.

Thanks,

jon

2020-05-22 04:42:40

by Mauro Carvalho Chehab

[permalink] [raw]
Subject: Re: [PATCH 10/14] docs: move locking-specific documenta to locking/ directory

Em Fri, 15 May 2020 12:06:07 -0600
Jonathan Corbet <[email protected]> escreveu:

> On Fri, 1 May 2020 17:37:54 +0200
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > Several files under Documentation/*.txt describe some type of
> > locking API. Move them to locking/ subdir and add to the
> > locking/index.rst index file.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> I've applied this, but it really seems like this belongs in the core-api
> manual someday.

Makes sense.

Well, right now, it is at the same level as core-api, just below it:

Kernel API documentation
------------------------

These books get into the details of how specific kernel subsystems work
from the point of view of a kernel developer. Much of the information here
is taken directly from the kernel source, with supplemental material added
as needed (or at least as we managed to add it — probably *not* all that is
needed).

.. toctree::
:maxdepth: 2

driver-api/index
core-api/index
locking/index

Not too bad.

Btw, there are other doc sets that could also fit into the core-api, like:

...
accounting/index
...
security/index
...
bpf/index
...
scheduler/index

while most of the rest should likely be inside driver-api.

Some care should be taken when moving stuff, though: there is a
reason why they weren't moved to driver-api in the first place:
they may contain stuff for the admin guide mixed there.

Thanks,
Mauro