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

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

[Mauro Carvalho Chehab]

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 <mchehab+huawei@kernel.org>
---
 .../{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 <dvhart@infradead.org>
 L:	linux-kernel@vger.kernel.org
 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 <rspringer@google.com>
@@ -7519,7 +7519,7 @@ L:	linux-remoteproc@vger.kernel.org
 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

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

[Jonathan Corbet]

On Fri,  1 May 2020 17:37:54 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> 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 <mchehab+huawei@kernel.org>

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

Thanks,

jon

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

[Mauro Carvalho Chehab]

Em Fri, 15 May 2020 12:06:07 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri,  1 May 2020 17:37:54 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> 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 <mchehab+huawei@kernel.org>  
> 
> 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

[PATCH 12/14] docs: move remaining stuff under Documentation/*.txt to Documentation/staging

[Mauro Carvalho Chehab]

There are several files that I was unable to find a proper place
for them, and 3 ones that are still in plain old text format.

Let's place those stuff behind the carpet, as we'd like to keep the
root directory clean.

We can later discuss and move those into better places.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/index.rst                       | 13 ++++++++
 .../{crc32.txt => staging/crc32.rst}          |  0
 Documentation/staging/index.rst               | 32 +++++++++++++++++++
 .../{kprobes.txt => staging/kprobes.rst}      |  0
 Documentation/{lzo.txt => staging/lzo.rst}    |  0
 .../remoteproc.rst}                           |  2 +-
 .../{rpmsg.txt => staging/rpmsg.rst}          |  0
 .../speculation.rst}                          |  8 +++--
 .../static-keys.rst}                          |  0
 Documentation/{tee.txt => staging/tee.rst}    |  1 +
 Documentation/{xz.txt => staging/xz.rst}      |  0
 Documentation/trace/kprobetrace.rst           |  2 +-
 MAINTAINERS                                   | 10 +++---
 include/asm-generic/bitops/atomic.h           |  2 +-
 include/linux/jump_label.h                    |  2 +-
 lib/crc32.c                                   |  2 +-
 lib/lzo/lzo1x_decompress_safe.c               |  2 +-
 lib/xz/Kconfig                                |  2 +-
 samples/kprobes/kprobe_example.c              |  2 +-
 samples/kprobes/kretprobe_example.c           |  2 +-
 20 files changed, 65 insertions(+), 17 deletions(-)
 rename Documentation/{crc32.txt => staging/crc32.rst} (100%)
 create mode 100644 Documentation/staging/index.rst
 rename Documentation/{kprobes.txt => staging/kprobes.rst} (100%)
 rename Documentation/{lzo.txt => staging/lzo.rst} (100%)
 rename Documentation/{remoteproc.txt => staging/remoteproc.rst} (99%)
 rename Documentation/{rpmsg.txt => staging/rpmsg.rst} (100%)
 rename Documentation/{speculation.txt => staging/speculation.rst} (97%)
 rename Documentation/{static-keys.txt => staging/static-keys.rst} (100%)
 rename Documentation/{tee.txt => staging/tee.rst} (99%)
 rename Documentation/{xz.txt => staging/xz.rst} (100%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index af2b87afebc8..9a931e157db2 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -179,6 +179,19 @@ subprojects.
 
    filesystems/ext4/index
 
+Other documentation
+-------------------
+
+There are several unsorted documents that don't seem to fit on other parts
+of the documentation body, or may require some adjustments and/or conversion
+to ReStructured Text format, or are simply too old.
+
+.. toctree::
+   :maxdepth: 2
+
+   staging/index
+
+
 Translations
 ------------
 
diff --git a/Documentation/crc32.txt b/Documentation/staging/crc32.rst
similarity index 100%
rename from Documentation/crc32.txt
rename to Documentation/staging/crc32.rst
diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst
new file mode 100644
index 000000000000..8e98517675ca
--- /dev/null
+++ b/Documentation/staging/index.rst
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Unsorted Documentation
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   crc32
+   kprobes
+   lzo
+   remoteproc
+   rpmsg
+   speculation
+   static-keys
+   tee
+   xz
+
+Atomic Types
+============
+
+.. literalinclude:: ../atomic_t.txt
+
+Atomic bitops
+=============
+
+.. literalinclude:: ../atomic_bitops.txt
+
+Memory Barriers
+===============
+
+.. literalinclude:: ../memory-barriers.txt
diff --git a/Documentation/kprobes.txt b/Documentation/staging/kprobes.rst
similarity index 100%
rename from Documentation/kprobes.txt
rename to Documentation/staging/kprobes.rst
diff --git a/Documentation/lzo.txt b/Documentation/staging/lzo.rst
similarity index 100%
rename from Documentation/lzo.txt
rename to Documentation/staging/lzo.rst
diff --git a/Documentation/remoteproc.txt b/Documentation/staging/remoteproc.rst
similarity index 99%
rename from Documentation/remoteproc.txt
rename to Documentation/staging/remoteproc.rst
index 2be1147256e0..9cccd3dd6a4b 100644
--- a/Documentation/remoteproc.txt
+++ b/Documentation/staging/remoteproc.rst
@@ -22,7 +22,7 @@ for remote processors that supports this kind of communication. This way,
 platform-specific remoteproc drivers only need to provide a few low-level
 handlers, and then all rpmsg drivers will then just work
 (for more information about the virtio-based rpmsg bus and its drivers,
-please read Documentation/rpmsg.txt).
+please read Documentation/staging/rpmsg.rst).
 Registration of other types of virtio devices is now also possible. Firmwares
 just need to publish what kind of virtio devices do they support, and then
 remoteproc will add those devices. This makes it possible to reuse the
diff --git a/Documentation/rpmsg.txt b/Documentation/staging/rpmsg.rst
similarity index 100%
rename from Documentation/rpmsg.txt
rename to Documentation/staging/rpmsg.rst
diff --git a/Documentation/speculation.txt b/Documentation/staging/speculation.rst
similarity index 97%
rename from Documentation/speculation.txt
rename to Documentation/staging/speculation.rst
index 50d7ea857cff..8045d99bcf12 100644
--- a/Documentation/speculation.txt
+++ b/Documentation/staging/speculation.rst
@@ -1,9 +1,11 @@
+===========
+Speculation
+===========
+
 This document explains potential effects of speculation, and how undesirable
 effects can be mitigated portably using common APIs.
 
-===========
-Speculation
-===========
+------------------------------------------------------------------------------
 
 To improve performance and minimize average latencies, many contemporary CPUs
 employ speculative execution techniques such as branch prediction, performing
diff --git a/Documentation/static-keys.txt b/Documentation/staging/static-keys.rst
similarity index 100%
rename from Documentation/static-keys.txt
rename to Documentation/staging/static-keys.rst
diff --git a/Documentation/tee.txt b/Documentation/staging/tee.rst
similarity index 99%
rename from Documentation/tee.txt
rename to Documentation/staging/tee.rst
index c8fad81c4563..324604a15d17 100644
--- a/Documentation/tee.txt
+++ b/Documentation/staging/tee.rst
@@ -162,6 +162,7 @@ The AMD-TEE driver packages the command buffer payload for processing in TEE.
 The command buffer format for the different TEE commands can be found in [7].
 
 The TEE commands supported by AMD-TEE Trusted OS are:
+
 * TEE_CMD_ID_LOAD_TA          - loads a Trusted Application (TA) binary into
                                 TEE environment.
 * TEE_CMD_ID_UNLOAD_TA        - unloads TA binary from TEE environment.
diff --git a/Documentation/xz.txt b/Documentation/staging/xz.rst
similarity index 100%
rename from Documentation/xz.txt
rename to Documentation/staging/xz.rst
diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index cc4c5fc313df..c1709165c553 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -40,7 +40,7 @@ Synopsis of kprobe_events
  MEMADDR	: Address where the probe is inserted.
  MAXACTIVE	: Maximum number of instances of the specified function that
 		  can be probed simultaneously, or 0 for the default value
-		  as defined in Documentation/kprobes.txt section 1.3.1.
+		  as defined in Documentation/staging/kprobes.rst section 1.3.1.
 
  FETCHARGS	: Arguments. Each probe can have up to 128 args.
   %REG		: Fetch register REG
diff --git a/MAINTAINERS b/MAINTAINERS
index 1aa6e89e7424..8aa8f7c0db93 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9494,7 +9494,7 @@ M:	Anil S Keshavamurthy <anil.s.keshavamurthy@intel.com>
 M:	"David S. Miller" <davem@davemloft.net>
 M:	Masami Hiramatsu <mhiramat@kernel.org>
 S:	Maintained
-F:	Documentation/kprobes.txt
+F:	Documentation/staging/kprobes.rst
 F:	include/asm-generic/kprobes.h
 F:	include/linux/kprobes.h
 F:	kernel/kprobes.c
@@ -9855,7 +9855,7 @@ L:	linux-kernel@vger.kernel.org
 L:	linux-arch@vger.kernel.org
 S:	Supported
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
-F:	Documentation/atomic_bitops.txt
+F:	Documentation/staging/atomic_bitops.txt
 F:	Documentation/atomic_t.txt
 F:	Documentation/core-api/atomic_ops.rst
 F:	Documentation/core-api/refcount-vs-atomic.rst
@@ -14357,7 +14357,7 @@ S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git rproc-next
 F:	Documentation/ABI/testing/sysfs-class-remoteproc
 F:	Documentation/devicetree/bindings/remoteproc/
-F:	Documentation/remoteproc.txt
+F:	Documentation/staging/remoteproc.rst
 F:	drivers/remoteproc/
 F:	include/linux/remoteproc.h
 F:	include/linux/remoteproc/
@@ -14369,7 +14369,7 @@ L:	linux-remoteproc@vger.kernel.org
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git rpmsg-next
 F:	Documentation/ABI/testing/sysfs-bus-rpmsg
-F:	Documentation/rpmsg.txt
+F:	Documentation/staging/rpmsg.rst
 F:	drivers/rpmsg/
 F:	include/linux/rpmsg.h
 F:	include/linux/rpmsg/
@@ -16580,7 +16580,7 @@ TEE SUBSYSTEM
 M:	Jens Wiklander <jens.wiklander@linaro.org>
 L:	tee-dev@lists.linaro.org
 S:	Maintained
-F:	Documentation/tee.txt
+F:	Documentation/staging/tee.rst
 F:	drivers/tee/
 F:	include/linux/tee_drv.h
 F:	include/uapi/linux/tee.h
diff --git a/include/asm-generic/bitops/atomic.h b/include/asm-generic/bitops/atomic.h
index dd90c9792909..edeeb8375006 100644
--- a/include/asm-generic/bitops/atomic.h
+++ b/include/asm-generic/bitops/atomic.h
@@ -8,7 +8,7 @@
 
 /*
  * Implementation of atomic bitops using atomic-fetch ops.
- * See Documentation/atomic_bitops.txt for details.
+ * See Documentation/staging/atomic_bitops.txt for details.
  */
 
 static inline void set_bit(unsigned int nr, volatile unsigned long *p)
diff --git a/include/linux/jump_label.h b/include/linux/jump_label.h
index 3526c0aee954..32809624d422 100644
--- a/include/linux/jump_label.h
+++ b/include/linux/jump_label.h
@@ -68,7 +68,7 @@
  * Lacking toolchain and or architecture support, static keys fall back to a
  * simple conditional branch.
  *
- * Additional babbling in: Documentation/static-keys.txt
+ * Additional babbling in: Documentation/staging/static-keys.rst
  */
 
 #ifndef __ASSEMBLY__
diff --git a/lib/crc32.c b/lib/crc32.c
index 4a20455d1f61..35a03d03f973 100644
--- a/lib/crc32.c
+++ b/lib/crc32.c
@@ -24,7 +24,7 @@
  * Version 2.  See the file COPYING for more details.
  */
 
-/* see: Documentation/crc32.txt for a description of algorithms */
+/* see: Documentation/staging/crc32.rst for a description of algorithms */
 
 #include <linux/crc32.h>
 #include <linux/crc32poly.h>
diff --git a/lib/lzo/lzo1x_decompress_safe.c b/lib/lzo/lzo1x_decompress_safe.c
index 2717c7963acd..7892a40cf765 100644
--- a/lib/lzo/lzo1x_decompress_safe.c
+++ b/lib/lzo/lzo1x_decompress_safe.c
@@ -32,7 +32,7 @@
  * depending on the base count. Since the base count is taken from a u8
  * and a few bits, it is safe to assume that it will always be lower than
  * or equal to 2*255, thus we can always prevent any overflow by accepting
- * two less 255 steps. See Documentation/lzo.txt for more information.
+ * two less 255 steps. See Documentation/staging/lzo.rst for more information.
  */
 #define MAX_255_COUNT      ((((size_t)~0) / 255) - 2)
 
diff --git a/lib/xz/Kconfig b/lib/xz/Kconfig
index 22528743d4ce..5cb50245a878 100644
--- a/lib/xz/Kconfig
+++ b/lib/xz/Kconfig
@@ -5,7 +5,7 @@ config XZ_DEC
 	help
 	  LZMA2 compression algorithm and BCJ filters are supported using
 	  the .xz file format as the container. For integrity checking,
-	  CRC32 is supported. See Documentation/xz.txt for more information.
+	  CRC32 is supported. See Documentation/staging/xz.rst for more information.
 
 if XZ_DEC
 
diff --git a/samples/kprobes/kprobe_example.c b/samples/kprobes/kprobe_example.c
index d693c23a85e8..e53603de48b8 100644
--- a/samples/kprobes/kprobe_example.c
+++ b/samples/kprobes/kprobe_example.c
@@ -5,7 +5,7 @@
  * stack trace and selected registers when _do_fork() is called.
  *
  * For more information on theory of operation of kprobes, see
- * Documentation/kprobes.txt
+ * Documentation/staging/kprobes.rst
  *
  * You will see the trace data in /var/log/messages and on the console
  * whenever _do_fork() is invoked to create a new process.
diff --git a/samples/kprobes/kretprobe_example.c b/samples/kprobes/kretprobe_example.c
index 186315ca88b3..3685df980011 100644
--- a/samples/kprobes/kretprobe_example.c
+++ b/samples/kprobes/kretprobe_example.c
@@ -11,7 +11,7 @@
  * If no func_name is specified, _do_fork is instrumented
  *
  * For more information on theory of operation of kretprobes, see
- * Documentation/kprobes.txt
+ * Documentation/staging/kprobes.rst
  *
  * Build and insert the kernel module as done in the kprobe example.
  * You will see the trace data in /var/log/messages and on the console
-- 
2.25.4

Re: [PATCH 12/14] docs: move remaining stuff under Documentation/*.txt to Documentation/staging

[Masami Hiramatsu]

On Fri,  1 May 2020 17:37:56 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> There are several files that I was unable to find a proper place
> for them, and 3 ones that are still in plain old text format.
> 
> Let's place those stuff behind the carpet, as we'd like to keep the
> root directory clean.
> 
> We can later discuss and move those into better places.

Hi Mauro,

Thanks for cleaning it up! Tentatively moving kprobes.txt under
staging/ is good to me.

Acked-by: Masami Hiramatsu <mhiramat@kernel.org>

BTW, I think kprobes.txt is under trace/ or we may be better
making a new core-api/events/ directory and prepare other event
systems (PMU, uprobes, and hw_breakpoint.) 

Thank you,
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/index.rst                       | 13 ++++++++
>  .../{crc32.txt => staging/crc32.rst}          |  0
>  Documentation/staging/index.rst               | 32 +++++++++++++++++++
>  .../{kprobes.txt => staging/kprobes.rst}      |  0
>  Documentation/{lzo.txt => staging/lzo.rst}    |  0
>  .../remoteproc.rst}                           |  2 +-
>  .../{rpmsg.txt => staging/rpmsg.rst}          |  0
>  .../speculation.rst}                          |  8 +++--
>  .../static-keys.rst}                          |  0
>  Documentation/{tee.txt => staging/tee.rst}    |  1 +
>  Documentation/{xz.txt => staging/xz.rst}      |  0
>  Documentation/trace/kprobetrace.rst           |  2 +-
>  MAINTAINERS                                   | 10 +++---
>  include/asm-generic/bitops/atomic.h           |  2 +-
>  include/linux/jump_label.h                    |  2 +-
>  lib/crc32.c                                   |  2 +-
>  lib/lzo/lzo1x_decompress_safe.c               |  2 +-
>  lib/xz/Kconfig                                |  2 +-
>  samples/kprobes/kprobe_example.c              |  2 +-
>  samples/kprobes/kretprobe_example.c           |  2 +-
>  20 files changed, 65 insertions(+), 17 deletions(-)
>  rename Documentation/{crc32.txt => staging/crc32.rst} (100%)
>  create mode 100644 Documentation/staging/index.rst
>  rename Documentation/{kprobes.txt => staging/kprobes.rst} (100%)
>  rename Documentation/{lzo.txt => staging/lzo.rst} (100%)
>  rename Documentation/{remoteproc.txt => staging/remoteproc.rst} (99%)
>  rename Documentation/{rpmsg.txt => staging/rpmsg.rst} (100%)
>  rename Documentation/{speculation.txt => staging/speculation.rst} (97%)
>  rename Documentation/{static-keys.txt => staging/static-keys.rst} (100%)
>  rename Documentation/{tee.txt => staging/tee.rst} (99%)
>  rename Documentation/{xz.txt => staging/xz.rst} (100%)
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index af2b87afebc8..9a931e157db2 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -179,6 +179,19 @@ subprojects.
>  
>     filesystems/ext4/index
>  
> +Other documentation
> +-------------------
> +
> +There are several unsorted documents that don't seem to fit on other parts
> +of the documentation body, or may require some adjustments and/or conversion
> +to ReStructured Text format, or are simply too old.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   staging/index
> +
> +
>  Translations
>  ------------
>  
> diff --git a/Documentation/crc32.txt b/Documentation/staging/crc32.rst
> similarity index 100%
> rename from Documentation/crc32.txt
> rename to Documentation/staging/crc32.rst
> diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst
> new file mode 100644
> index 000000000000..8e98517675ca
> --- /dev/null
> +++ b/Documentation/staging/index.rst
> @@ -0,0 +1,32 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Unsorted Documentation
> +======================
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   crc32
> +   kprobes
> +   lzo
> +   remoteproc
> +   rpmsg
> +   speculation
> +   static-keys
> +   tee
> +   xz
> +
> +Atomic Types
> +============
> +
> +.. literalinclude:: ../atomic_t.txt
> +
> +Atomic bitops
> +=============
> +
> +.. literalinclude:: ../atomic_bitops.txt
> +
> +Memory Barriers
> +===============
> +
> +.. literalinclude:: ../memory-barriers.txt
> diff --git a/Documentation/kprobes.txt b/Documentation/staging/kprobes.rst
> similarity index 100%
> rename from Documentation/kprobes.txt
> rename to Documentation/staging/kprobes.rst
> diff --git a/Documentation/lzo.txt b/Documentation/staging/lzo.rst
> similarity index 100%
> rename from Documentation/lzo.txt
> rename to Documentation/staging/lzo.rst
> diff --git a/Documentation/remoteproc.txt b/Documentation/staging/remoteproc.rst
> similarity index 99%
> rename from Documentation/remoteproc.txt
> rename to Documentation/staging/remoteproc.rst
> index 2be1147256e0..9cccd3dd6a4b 100644
> --- a/Documentation/remoteproc.txt
> +++ b/Documentation/staging/remoteproc.rst
> @@ -22,7 +22,7 @@ for remote processors that supports this kind of communication. This way,
>  platform-specific remoteproc drivers only need to provide a few low-level
>  handlers, and then all rpmsg drivers will then just work
>  (for more information about the virtio-based rpmsg bus and its drivers,
> -please read Documentation/rpmsg.txt).
> +please read Documentation/staging/rpmsg.rst).
>  Registration of other types of virtio devices is now also possible. Firmwares
>  just need to publish what kind of virtio devices do they support, and then
>  remoteproc will add those devices. This makes it possible to reuse the
> diff --git a/Documentation/rpmsg.txt b/Documentation/staging/rpmsg.rst
> similarity index 100%
> rename from Documentation/rpmsg.txt
> rename to Documentation/staging/rpmsg.rst
> diff --git a/Documentation/speculation.txt b/Documentation/staging/speculation.rst
> similarity index 97%
> rename from Documentation/speculation.txt
> rename to Documentation/staging/speculation.rst
> index 50d7ea857cff..8045d99bcf12 100644
> --- a/Documentation/speculation.txt
> +++ b/Documentation/staging/speculation.rst
> @@ -1,9 +1,11 @@
> +===========
> +Speculation
> +===========
> +
>  This document explains potential effects of speculation, and how undesirable
>  effects can be mitigated portably using common APIs.
>  
> -===========
> -Speculation
> -===========
> +------------------------------------------------------------------------------
>  
>  To improve performance and minimize average latencies, many contemporary CPUs
>  employ speculative execution techniques such as branch prediction, performing
> diff --git a/Documentation/static-keys.txt b/Documentation/staging/static-keys.rst
> similarity index 100%
> rename from Documentation/static-keys.txt
> rename to Documentation/staging/static-keys.rst
> diff --git a/Documentation/tee.txt b/Documentation/staging/tee.rst
> similarity index 99%
> rename from Documentation/tee.txt
> rename to Documentation/staging/tee.rst
> index c8fad81c4563..324604a15d17 100644
> --- a/Documentation/tee.txt
> +++ b/Documentation/staging/tee.rst
> @@ -162,6 +162,7 @@ The AMD-TEE driver packages the command buffer payload for processing in TEE.
>  The command buffer format for the different TEE commands can be found in [7].
>  
>  The TEE commands supported by AMD-TEE Trusted OS are:
> +
>  * TEE_CMD_ID_LOAD_TA          - loads a Trusted Application (TA) binary into
>                                  TEE environment.
>  * TEE_CMD_ID_UNLOAD_TA        - unloads TA binary from TEE environment.
> diff --git a/Documentation/xz.txt b/Documentation/staging/xz.rst
> similarity index 100%
> rename from Documentation/xz.txt
> rename to Documentation/staging/xz.rst
> diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
> index cc4c5fc313df..c1709165c553 100644
> --- a/Documentation/trace/kprobetrace.rst
> +++ b/Documentation/trace/kprobetrace.rst
> @@ -40,7 +40,7 @@ Synopsis of kprobe_events
>   MEMADDR	: Address where the probe is inserted.
>   MAXACTIVE	: Maximum number of instances of the specified function that
>  		  can be probed simultaneously, or 0 for the default value
> -		  as defined in Documentation/kprobes.txt section 1.3.1.
> +		  as defined in Documentation/staging/kprobes.rst section 1.3.1.
>  
>   FETCHARGS	: Arguments. Each probe can have up to 128 args.
>    %REG		: Fetch register REG
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 1aa6e89e7424..8aa8f7c0db93 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -9494,7 +9494,7 @@ M:	Anil S Keshavamurthy <anil.s.keshavamurthy@intel.com>
>  M:	"David S. Miller" <davem@davemloft.net>
>  M:	Masami Hiramatsu <mhiramat@kernel.org>
>  S:	Maintained
> -F:	Documentation/kprobes.txt
> +F:	Documentation/staging/kprobes.rst
>  F:	include/asm-generic/kprobes.h
>  F:	include/linux/kprobes.h
>  F:	kernel/kprobes.c
> @@ -9855,7 +9855,7 @@ L:	linux-kernel@vger.kernel.org
>  L:	linux-arch@vger.kernel.org
>  S:	Supported
>  T:	git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
> -F:	Documentation/atomic_bitops.txt
> +F:	Documentation/staging/atomic_bitops.txt
>  F:	Documentation/atomic_t.txt
>  F:	Documentation/core-api/atomic_ops.rst
>  F:	Documentation/core-api/refcount-vs-atomic.rst
> @@ -14357,7 +14357,7 @@ S:	Maintained
>  T:	git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git rproc-next
>  F:	Documentation/ABI/testing/sysfs-class-remoteproc
>  F:	Documentation/devicetree/bindings/remoteproc/
> -F:	Documentation/remoteproc.txt
> +F:	Documentation/staging/remoteproc.rst
>  F:	drivers/remoteproc/
>  F:	include/linux/remoteproc.h
>  F:	include/linux/remoteproc/
> @@ -14369,7 +14369,7 @@ L:	linux-remoteproc@vger.kernel.org
>  S:	Maintained
>  T:	git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.git rpmsg-next
>  F:	Documentation/ABI/testing/sysfs-bus-rpmsg
> -F:	Documentation/rpmsg.txt
> +F:	Documentation/staging/rpmsg.rst
>  F:	drivers/rpmsg/
>  F:	include/linux/rpmsg.h
>  F:	include/linux/rpmsg/
> @@ -16580,7 +16580,7 @@ TEE SUBSYSTEM
>  M:	Jens Wiklander <jens.wiklander@linaro.org>
>  L:	tee-dev@lists.linaro.org
>  S:	Maintained
> -F:	Documentation/tee.txt
> +F:	Documentation/staging/tee.rst
>  F:	drivers/tee/
>  F:	include/linux/tee_drv.h
>  F:	include/uapi/linux/tee.h
> diff --git a/include/asm-generic/bitops/atomic.h b/include/asm-generic/bitops/atomic.h
> index dd90c9792909..edeeb8375006 100644
> --- a/include/asm-generic/bitops/atomic.h
> +++ b/include/asm-generic/bitops/atomic.h
> @@ -8,7 +8,7 @@
>  
>  /*
>   * Implementation of atomic bitops using atomic-fetch ops.
> - * See Documentation/atomic_bitops.txt for details.
> + * See Documentation/staging/atomic_bitops.txt for details.
>   */
>  
>  static inline void set_bit(unsigned int nr, volatile unsigned long *p)
> diff --git a/include/linux/jump_label.h b/include/linux/jump_label.h
> index 3526c0aee954..32809624d422 100644
> --- a/include/linux/jump_label.h
> +++ b/include/linux/jump_label.h
> @@ -68,7 +68,7 @@
>   * Lacking toolchain and or architecture support, static keys fall back to a
>   * simple conditional branch.
>   *
> - * Additional babbling in: Documentation/static-keys.txt
> + * Additional babbling in: Documentation/staging/static-keys.rst
>   */
>  
>  #ifndef __ASSEMBLY__
> diff --git a/lib/crc32.c b/lib/crc32.c
> index 4a20455d1f61..35a03d03f973 100644
> --- a/lib/crc32.c
> +++ b/lib/crc32.c
> @@ -24,7 +24,7 @@
>   * Version 2.  See the file COPYING for more details.
>   */
>  
> -/* see: Documentation/crc32.txt for a description of algorithms */
> +/* see: Documentation/staging/crc32.rst for a description of algorithms */
>  
>  #include <linux/crc32.h>
>  #include <linux/crc32poly.h>
> diff --git a/lib/lzo/lzo1x_decompress_safe.c b/lib/lzo/lzo1x_decompress_safe.c
> index 2717c7963acd..7892a40cf765 100644
> --- a/lib/lzo/lzo1x_decompress_safe.c
> +++ b/lib/lzo/lzo1x_decompress_safe.c
> @@ -32,7 +32,7 @@
>   * depending on the base count. Since the base count is taken from a u8
>   * and a few bits, it is safe to assume that it will always be lower than
>   * or equal to 2*255, thus we can always prevent any overflow by accepting
> - * two less 255 steps. See Documentation/lzo.txt for more information.
> + * two less 255 steps. See Documentation/staging/lzo.rst for more information.
>   */
>  #define MAX_255_COUNT      ((((size_t)~0) / 255) - 2)
>  
> diff --git a/lib/xz/Kconfig b/lib/xz/Kconfig
> index 22528743d4ce..5cb50245a878 100644
> --- a/lib/xz/Kconfig
> +++ b/lib/xz/Kconfig
> @@ -5,7 +5,7 @@ config XZ_DEC
>  	help
>  	  LZMA2 compression algorithm and BCJ filters are supported using
>  	  the .xz file format as the container. For integrity checking,
> -	  CRC32 is supported. See Documentation/xz.txt for more information.
> +	  CRC32 is supported. See Documentation/staging/xz.rst for more information.
>  
>  if XZ_DEC
>  
> diff --git a/samples/kprobes/kprobe_example.c b/samples/kprobes/kprobe_example.c
> index d693c23a85e8..e53603de48b8 100644
> --- a/samples/kprobes/kprobe_example.c
> +++ b/samples/kprobes/kprobe_example.c
> @@ -5,7 +5,7 @@
>   * stack trace and selected registers when _do_fork() is called.
>   *
>   * For more information on theory of operation of kprobes, see
> - * Documentation/kprobes.txt
> + * Documentation/staging/kprobes.rst
>   *
>   * You will see the trace data in /var/log/messages and on the console
>   * whenever _do_fork() is invoked to create a new process.
> diff --git a/samples/kprobes/kretprobe_example.c b/samples/kprobes/kretprobe_example.c
> index 186315ca88b3..3685df980011 100644
> --- a/samples/kprobes/kretprobe_example.c
> +++ b/samples/kprobes/kretprobe_example.c
> @@ -11,7 +11,7 @@
>   * If no func_name is specified, _do_fork is instrumented
>   *
>   * For more information on theory of operation of kretprobes, see
> - * Documentation/kprobes.txt
> + * Documentation/staging/kprobes.rst
>   *
>   * Build and insert the kernel module as done in the kprobe example.
>   * You will see the trace data in /var/log/messages and on the console
> -- 
> 2.25.4
> 


-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [PATCH 12/14] docs: move remaining stuff under Documentation/*.txt to Documentation/staging

[Joe Perches]

On Mon, 2020-05-04 at 08:54 +0900, Masami Hiramatsu wrote:
> On Fri,  1 May 2020 17:37:56 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
[]
> > diff --git a/MAINTAINERS b/MAINTAINERS
[]
> > @@ -9855,7 +9855,7 @@ L:	linux-kernel@vger.kernel.org
> >  L:	linux-arch@vger.kernel.org
> >  S:	Supported
> >  T:	git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
> > -F:	Documentation/atomic_bitops.txt
> > +F:	Documentation/staging/atomic_bitops.txt

Can you please keep the file lists in alphabetic order
and move this entry down appropriately?  Thanks.

> >  F:	Documentation/atomic_t.txt
> >  F:	Documentation/core-api/atomic_ops.rst
> >  F:	Documentation/core-api/refcount-vs-atomic.rst

Re: [PATCH 12/14] docs: move remaining stuff under Documentation/*.txt to Documentation/staging

[Naveen N. Rao]

Masami Hiramatsu wrote:
> On Fri,  1 May 2020 17:37:56 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 
>> There are several files that I was unable to find a proper place
>> for them, and 3 ones that are still in plain old text format.
>> 
>> Let's place those stuff behind the carpet, as we'd like to keep the
>> root directory clean.
>> 
>> We can later discuss and move those into better places.
> 
> Hi Mauro,
> 
> Thanks for cleaning it up! Tentatively moving kprobes.txt under
> staging/ is good to me.
> 
> Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
> 
> BTW, I think kprobes.txt is under trace/ or we may be better
> making a new core-api/events/ directory and prepare other event
> systems (PMU, uprobes, and hw_breakpoint.) 

I think it would be good to move kprobes.txt under trace/ -- all other 
tracing bits are already present there, including uprobes.


- Naveen