Skip to contentSkip to conversation

Move the ReST files from Documentation/*.txt

PATCH Applied Mauro Carvalho Chehab 11 participants 41 messages May 1, 2020 – May 22, 2020 2 messages not in the archive

Subsystems (33)
lore
Share & tools
lore
#0 lore raw

cover Move the ReST files from Documentation/*.txt

The main goal of this series is to cleanup the Documentation/ directory.

Most of the files under Documentation/*.txt are already in ReST format. They just need to be moved to some place. So, most of the work here is to just move files for them to generate an output using the docs building system.

After this change, the Documentation/ dir will contain:

- the main ReST file:
- index.rst

- TUX and its copyright:
- logo.gif and COPYING-logo

- Files required to do ReST builds:
- .gitignore, Makefile, conf.py, docutils.conf, Kconfig

- A pre-git file used to generate patches:
- dontdiff
(I guess we should get rid of it, as I doubt this is useful those days).

-

Besides the above rightful files, the Documentation/ dir will also contain some left-overs:

- two somewhat new ReST files that should be moved to somewhere:
- asm-annotations.rst and watch_queue.rst

- Two files that helps people looking for some well known documents that are referenced at the web, pointing to their new location inside the process/ dir:
- SubmittingPatches and CodingStyle

- Three .txt files that weren't converted to ReST:
- atomic_bitops.txt, memory-barriers.txt, atomic_t.txt

It should be noticed that I'm in doubt about the location of some files, and some stuff may well belong to a trash can. So, this series create a temporary place for orphaned documents in the form of a Documentation/staging directory.

This series is also on my development git tree, at:

https://git.linuxtv.org/mchehab/experimental.git/log/?h=rename-main-docs

The built output documentation on html format is at:

https://www.infradead.org/~mchehab/kernel_docs/

(it contains also other documents I converted to ReST)

Mauro Carvalho Chehab (14):
docs: move DMA kAPI to Documentation/core-api
docs: add bus-virt-phys-mapping.txt to core-api
docs: fix references for DMA*.txt files
docs: move IPMI.txt to the driver API book
docs: fix references for ipmi.rst file
docs: debugging-via-ohci1394.txt: add it to the core-api book
docs: add IRQ documentation at the core-api book
docs: move kobject and kref docs into the core-api book
docs: move digsig docs to the security book
docs: move locking-specific documenta to locking/ directory
docs: move other kAPI documents to core-api
docs: move remaining stuff under Documentation/*.txt to
Documentation/staging
docs: staging: don't use literalinclude
docs: staging: use small font for literal includes

 Documentation/PCI/pci.rst                     |  6 +-
 Documentation/admin-guide/hw-vuln/l1tf.rst    |  2 +-
 .../admin-guide/kernel-parameters.txt         |  2 +-
 .../admin-guide/kernel-per-CPU-kthreads.rst   |  2 +-
 Documentation/admin-guide/sysctl/vm.rst       |  2 +-
 Documentation/block/biodoc.rst                |  2 +-
 .../bus-virt-phys-mapping.rst}                |  2 +-
 .../debugging-via-ohci1394.rst}               |  0
 .../dma-api-howto.rst}                        |  0
 .../{DMA-API.txt => core-api/dma-api.rst}     |  6 +-
 .../dma-attributes.rst}                       |  0
 .../dma-isa-lpc.rst}                          |  2 +-
 Documentation/core-api/index.rst              | 14 +++++
 .../{IRQ.txt => core-api/irq/concepts.rst}    |  0
 Documentation/core-api/irq/index.rst          | 11 ++++
 .../irq/irq-affinity.rst}                     |  0
 .../irq/irq-domain.rst}                       |  3 +-
 .../irq/irqflags-tracing.rst}                 |  0
 Documentation/core-api/kobject.rst            |  2 +-
 Documentation/{kref.txt => core-api/kref.rst} |  0
 .../{mailbox.txt => core-api/mailbox.rst}     |  0
 .../nommu-mmap.rst}                           |  0
 .../this_cpu_ops.rst}                         |  0
 .../unaligned-memory-access.rst}              |  0
 Documentation/driver-api/index.rst            |  1 +
 .../{IPMI.txt => driver-api/ipmi.rst}         |  0
 Documentation/driver-api/usb/dma.rst          |  6 +-
 Documentation/gpu/drm-mm.rst                  |  2 +-
 Documentation/ia64/irq-redir.rst              |  2 +-
 Documentation/index.rst                       | 13 ++++
 .../futex-requeue-pi.rst}                     |  0
 .../hwspinlock.rst}                           |  0
 Documentation/locking/index.rst               |  7 +++
 .../percpu-rw-semaphore.rst}                  |  0
 .../{pi-futex.txt => locking/pi-futex.rst}    |  0
 .../preempt-locking.rst}                      |  0
 .../robust-futex-ABI.rst}                     |  0
 .../robust-futexes.rst}                       |  0
 Documentation/locking/rt-mutex.rst            |  2 +-
 Documentation/memory-barriers.txt             |  6 +-
 Documentation/networking/scaling.rst          |  4 +-
 .../{digsig.txt => security/digsig.rst}       |  0
 Documentation/security/index.rst              |  1 +
 .../{crc32.txt => staging/crc32.rst}          |  0
 Documentation/staging/index.rst               | 59 +++++++++++++++++++
 .../{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 +-
 .../translations/ko_KR/memory-barriers.txt    |  6 +-
 Documentation/translations/zh_CN/IRQ.txt      |  4 +-
 MAINTAINERS                                   | 20 +++----
 arch/Kconfig                                  |  2 +-
 arch/ia64/hp/common/sba_iommu.c               | 12 ++--
 arch/parisc/kernel/pci-dma.c                  |  2 +-
 arch/x86/include/asm/dma-mapping.h            |  4 +-
 arch/x86/kernel/amd_gart_64.c                 |  2 +-
 drivers/char/ipmi/Kconfig                     |  2 +-
 drivers/char/ipmi/ipmi_si_hotmod.c            |  2 +-
 drivers/char/ipmi/ipmi_si_intf.c              |  2 +-
 drivers/parisc/sba_iommu.c                    | 14 ++---
 include/asm-generic/bitops/atomic.h           |  2 +-
 include/linux/dma-mapping.h                   |  2 +-
 include/linux/jump_label.h                    |  2 +-
 include/media/videobuf-dma-sg.h               |  2 +-
 init/Kconfig                                  |  2 +-
 kernel/dma/debug.c                            |  2 +-
 lib/Kconfig.debug                             |  2 +-
 lib/crc32.c                                   |  2 +-
 lib/lzo/lzo1x_decompress_safe.c               |  2 +-
 lib/xz/Kconfig                                |  2 +-
 mm/Kconfig                                    |  2 +-
 mm/nommu.c                                    |  2 +-
 samples/kprobes/kprobe_example.c              |  2 +-
 samples/kprobes/kretprobe_example.c           |  2 +-
 80 files changed, 191 insertions(+), 81 deletions(-)
 rename Documentation/{bus-virt-phys-mapping.txt => core-api/bus-virt-phys-mapping.rst} (99%)
 rename Documentation/{debugging-via-ohci1394.txt => core-api/debugging-via-ohci1394.rst} (100%)
 rename Documentation/{DMA-API-HOWTO.txt => core-api/dma-api-howto.rst} (100%)
 rename Documentation/{DMA-API.txt => core-api/dma-api.rst} (99%)
 rename Documentation/{DMA-attributes.txt => core-api/dma-attributes.rst} (100%)
 rename Documentation/{DMA-ISA-LPC.txt => core-api/dma-isa-lpc.rst} (98%)
 rename Documentation/{IRQ.txt => core-api/irq/concepts.rst} (100%)
 create mode 100644 Documentation/core-api/irq/index.rst
 rename Documentation/{IRQ-affinity.txt => core-api/irq/irq-affinity.rst} (100%)
 rename Documentation/{IRQ-domain.txt => core-api/irq/irq-domain.rst} (99%)
 rename Documentation/{irqflags-tracing.txt => core-api/irq/irqflags-tracing.rst} (100%)
 rename Documentation/{kref.txt => core-api/kref.rst} (100%)
 rename Documentation/{mailbox.txt => core-api/mailbox.rst} (100%)
 rename Documentation/{nommu-mmap.txt => core-api/nommu-mmap.rst} (100%)
 rename Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst} (100%)
 rename Documentation/{unaligned-memory-access.txt => core-api/unaligned-memory-access.rst} (100%)
 rename Documentation/{IPMI.txt => driver-api/ipmi.rst} (100%)
 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%)
 rename Documentation/{digsig.txt => security/digsig.rst} (100%)
 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%)
Signature · 1 line
2.25.4

A message that is not in the archive (sent off-list or not yet received): cover.1588345503.git.mchehab+huawei-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org

#2 lore raw

PATCH 3/14 docs: fix references for DMA*.txt files

As we moved those files to core-api, fix references to point to their newer locations.

---
 Documentation/PCI/pci.rst                          |  6 +++---
 Documentation/block/biodoc.rst                     |  2 +-
 Documentation/core-api/bus-virt-phys-mapping.rst   |  2 +-
 Documentation/core-api/dma-api.rst                 |  6 +++---
 Documentation/core-api/dma-isa-lpc.rst             |  2 +-
 Documentation/driver-api/usb/dma.rst               |  6 +++---
 Documentation/memory-barriers.txt                  |  6 +++---
 .../translations/ko_KR/memory-barriers.txt         |  6 +++---
 arch/ia64/hp/common/sba_iommu.c                    | 12 ++++++------
 arch/parisc/kernel/pci-dma.c                       |  2 +-
 arch/x86/include/asm/dma-mapping.h                 |  4 ++--
 arch/x86/kernel/amd_gart_64.c                      |  2 +-
 drivers/parisc/sba_iommu.c                         | 14 +++++++-------
 include/linux/dma-mapping.h                        |  2 +-
 include/media/videobuf-dma-sg.h                    |  2 +-
 kernel/dma/debug.c                                 |  2 +-
 16 files changed, 38 insertions(+), 38 deletions(-)
Documentation/PCI/pci.rst +3 -3
index 8c016d8c9862..d10d3fe604c5 100644
@@ -265,7 +265,7 @@ Set the DMA mask size
 ---------------------
 .. note::
    If anything below doesn't make sense, please refer to
-   Documentation/DMA-API.txt. This section is just a reminder that
+   :doc:`/core-api/dma-api`. This section is just a reminder that
    drivers need to indicate DMA capabilities of the device and is not
    an authoritative source for DMA interfaces.
 
@@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
 Setup shared control data
 -------------------------
 Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
-memory.  See Documentation/DMA-API.txt for a full description of
+memory.  See :doc:`/core-api/dma-api` for a full description of
 the DMA APIs. This section is just a reminder that it needs to be done
 before enabling DMA on the device.
 
@@ -421,7 +421,7 @@ owners if there is one.
 
 Then clean up "consistent" buffers which contain the control data.
 
-See Documentation/DMA-API.txt for details on unmapping interfaces.
+See :doc:`/core-api/dma-api` for details on unmapping interfaces.
 
 
 Unregister from other subsystems
Documentation/block/biodoc.rst +1 -1
index b964796ec9c7..ba7f45d0271c 100644
@@ -196,7 +196,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
 do not have a corresponding kernel virtual address space mapping) and
 low-memory pages.
 
-Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion
+Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion
 on PCI high mem DMA aspects and mapping of scatter gather lists, and support
 for 64 bit PCI.
 
Documentation/core-api/bus-virt-phys-mapping.rst +1 -1
index 4bb07c2f3e7d..c7bc99cd2e21 100644
@@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers
 
 	The virt_to_bus() and bus_to_virt() functions have been
 	superseded by the functionality provided by the PCI DMA interface
-	(see Documentation/DMA-API-HOWTO.txt).  They continue
+	(see :doc:`/core-api/dma-api-howto`).  They continue
 	to be documented below for historical purposes, but new code
 	must not use them. --davidm 00/12/12
 
Documentation/core-api/dma-api.rst +3 -3
index 2d8d2fed7317..63b4a2f20867 100644
@@ -5,7 +5,7 @@ Dynamic DMA mapping using the generic device
 :Author: James E.J. Bottomley <[email protected]>
 
 This document describes the DMA API.  For a more gentle introduction
-of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
+of the API (and actual examples), see :doc:`/core-api/dma-api-howto`.
 
 This API is split into two pieces.  Part I describes the basic API.
 Part II describes extensions for supporting non-consistent memory
@@ -471,7 +471,7 @@ without the _attrs suffixes, except that they pass an optional
 dma_attrs.
 
 The interpretation of DMA attributes is architecture-specific, and
-each attribute should be documented in Documentation/DMA-attributes.txt.
+each attribute should be documented in :doc:`/core-api/dma-attributes`.
 
 If dma_attrs are 0, the semantics of each of these functions
 is identical to those of the corresponding function
@@ -484,7 +484,7 @@ for DMA::
 
 	#include <linux/dma-mapping.h>
 	/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
-	* documented in Documentation/DMA-attributes.txt */
+	* documented in Documentation/core-api/dma-attributes.rst */
 	...
 
 		unsigned long attr;
Documentation/core-api/dma-isa-lpc.rst +1 -1
index b1ec7b16c21f..e59a3d35a93d 100644
@@ -17,7 +17,7 @@ To do ISA style DMA you need to include two headers::
 	#include <asm/dma.h>
 
 The first is the generic DMA API used to convert virtual addresses to
-bus addresses (see Documentation/DMA-API.txt for details).
+bus addresses (see :doc:`/core-api/dma-api` for details).
 
 The second contains the routines specific to ISA DMA transfers. Since
 this is not present on all platforms make sure you construct your
Documentation/driver-api/usb/dma.rst +3 -3
index 59d5aee89e37..2b3dbd3265b4 100644
@@ -10,7 +10,7 @@ API overview
 
 The big picture is that USB drivers can continue to ignore most DMA issues,
 though they still must provide DMA-ready buffers (see
-``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+:doc:`/core-api/dma-api-howto`).  That's how they've worked through
 the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
 DMA-aware usb drivers:
@@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties.
   force a consistent memory access ordering by using memory barriers.  It's
   not using a streaming DMA mapping, so it's good for small transfers on
   systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and
+  :doc:`/core-api/dma-api-howto` for definitions of "coherent" and
   "streaming" DMA mappings.)
 
   Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -91,7 +91,7 @@ Working with existing buffers
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  However, most buffers passed to your
 driver can safely be used with such DMA mapping.  (See the first section
-of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
+of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?")
 
 - When you're using scatterlists, you can map everything at once.  On some
   systems, this kicks in an IOMMU and turns the scatterlists into single
Documentation/memory-barriers.txt +3 -3
index eaabc3134294..0e4947a8282d 100644
@@ -546,8 +546,8 @@ There are certain things that the Linux kernel memory barriers do not guarantee:
 	[*] For information on bus mastering DMA and coherency please read:
 
 	    Documentation/driver-api/pci/pci.rst
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
+	    Documentation/core-api/dma-api-howto.rst
+	    Documentation/core-api/dma-api.rst
 
 
 DATA DEPENDENCY BARRIERS (HISTORICAL)
@@ -1932,7 +1932,7 @@ There are some more advanced barrier functions:
      here.
 
      See the subsection "Kernel I/O barrier effects" for more information on
-     relaxed I/O accessors and the Documentation/DMA-API.txt file for more
+     relaxed I/O accessors and the Documentation/core-api/dma-api.rst file for more
      information on consistent memory.
 
 
Documentation/translations/ko_KR/memory-barriers.txt +3 -3
index e50fe6541335..037e82ade93c 100644
@@ -570,8 +570,8 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 
 	[*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다:
 
 	    Documentation/driver-api/pci/pci.rst
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
+	    Documentation/core-api/dma-api-howto.rst
+	    Documentation/core-api/dma-api.rst
 
 
 데이터 의존성 배리어 (역사적)
@@ -1904,7 +1904,7 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효
 
      writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는
      "커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을
-     위해선 Documentation/DMA-API.txt 문서를 참고하세요.
+     위해선 Documentation/core-api/dma-api.rst 문서를 참고하세요.
 
 
 =========================
arch/ia64/hp/common/sba_iommu.c +6 -6
index a806227c1fad..656a4888c300 100644
@@ -907,7 +907,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
  * @dir: dma direction
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static dma_addr_t sba_map_page(struct device *dev, struct page *page,
 			       unsigned long poff, size_t size,
@@ -1028,7 +1028,7 @@ sba_mark_clean(struct ioc *ioc, dma_addr_t iova, size_t size)
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
 			   enum dma_data_direction dir, unsigned long attrs)
@@ -1105,7 +1105,7 @@ static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
  * @size:  number of bytes mapped in driver buffer.
  * @dma_handle:  IOVA of new buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void *
 sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
@@ -1162,7 +1162,7 @@ sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
  * @vaddr:  virtual address IOVA of "consistent" buffer.
  * @dma_handler:  IO virtual address of "consistent" buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void sba_free_coherent(struct device *dev, size_t size, void *vaddr,
 			      dma_addr_t dma_handle, unsigned long attrs)
@@ -1425,7 +1425,7 @@ static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
 			    int nents, enum dma_data_direction dir,
@@ -1524,7 +1524,7 @@ static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
 			       int nents, enum dma_data_direction dir,
arch/parisc/kernel/pci-dma.c +1 -1
index 0f1b460ee715..a86c9456b3c1 100644
@@ -3,7 +3,7 @@
 ** PARISC 1.1 Dynamic DMA mapping support.
 ** This implementation is for PA-RISC platforms that do not support
 ** I/O TLBs (aka DMA address translation hardware).
-** See Documentation/DMA-API-HOWTO.txt for interface definitions.
+** See Documentation/core-api/dma-api-howto.rst for interface definitions.
 **
 **      (c) Copyright 1999,2000 Hewlett-Packard Company
 **      (c) Copyright 2000 Grant Grundler
arch/x86/include/asm/dma-mapping.h +2 -2
index 6b15a24930e0..fed67eafcacc 100644
@@ -3,8 +3,8 @@
 #define _ASM_X86_DMA_MAPPING_H
 
 /*
- * IOMMU interface. See Documentation/DMA-API-HOWTO.txt and
- * Documentation/DMA-API.txt for documentation.
+ * IOMMU interface. See Documentation/core-api/dma-api-howto.rst and
+ * Documentation/core-api/dma-api.rst for documentation.
  */
 
 #include <linux/scatterlist.h>
arch/x86/kernel/amd_gart_64.c +1 -1
index 5f816861f5d2..13386e13d711 100644
@@ -6,7 +6,7 @@
  * This allows to use PCI devices that only support 32bit addresses on systems
  * with more than 4GB.
  *
- * See Documentation/DMA-API-HOWTO.txt for the interface specification.
+ * See Documentation/core-api/dma-api-howto.rst for the interface specification.
  *
  * Copyright 2002 Andi Kleen, SuSE Labs.
  */
drivers/parisc/sba_iommu.c +7 -7
index 7e112829d250..5368452eb5a6 100644
@@ -666,7 +666,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
  * @dev: instance of PCI owned by the driver that's asking
  * @mask:  number of address bits this PCI device can handle
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static int sba_dma_supported( struct device *dev, u64 mask)
 {
@@ -698,7 +698,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
  * @size:  number of bytes to map in driver buffer.
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static dma_addr_t
 sba_map_single(struct device *dev, void *addr, size_t size,
@@ -788,7 +788,7 @@ sba_map_page(struct device *dev, struct page *page, unsigned long offset,
  * @size:  number of bytes mapped in driver buffer.
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void
 sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
@@ -867,7 +867,7 @@ sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
  * @size:  number of bytes mapped in driver buffer.
  * @dma_handle:  IOVA of new buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle,
 		gfp_t gfp, unsigned long attrs)
@@ -898,7 +898,7 @@ static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle
  * @vaddr:  virtual address IOVA of "consistent" buffer.
  * @dma_handler:  IO virtual address of "consistent" buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void
 sba_free(struct device *hwdev, size_t size, void *vaddr,
@@ -933,7 +933,7 @@ int dump_run_sg = 0;
  * @nents:  number of entries in list
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static int
 sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
@@ -1017,7 +1017,7 @@ sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
  * @nents:  number of entries in list
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void 
 sba_unmap_sg(struct device *dev, struct scatterlist *sglist, int nents,
include/linux/dma-mapping.h +1 -1
index b43116a6405d..f893a6bb3125 100644
@@ -14,7 +14,7 @@
 
 /**
  * List of possible attributes associated with a DMA mapping. The semantics
- * of each attribute should be defined in Documentation/DMA-attributes.txt.
+ * of each attribute should be defined in Documentation/core-api/dma-attributes.rst.
  */
 
 /*
include/media/videobuf-dma-sg.h +1 -1
index b89d5e31f172..34450f7ad510 100644
@@ -31,7 +31,7 @@
  *	does memory allocation too using vmalloc_32().
  *
  * videobuf_dma_*()
- *	see Documentation/DMA-API-HOWTO.txt, these functions to
+ *	see Documentation/core-api/dma-api-howto.rst, these functions to
  *	basically the same.  The map function does also build a
  *	scatterlist for the buffer (and unmap frees it ...)
  *
kernel/dma/debug.c +1 -1
index 36c962a86bf2..f97f088ace7e 100644
@@ -1071,7 +1071,7 @@ static void check_unmap(struct dma_debug_entry *ref)
 	/*
 	 * Drivers should use dma_mapping_error() to check the returned
 	 * addresses of dma_map_single() and dma_map_page().
-	 * If not, print this warning message. See Documentation/DMA-API.txt.
+	 * If not, print this warning message. See Documentation/core-api/dma-api.rst.
 	 */
 	if (entry->map_err_type == MAP_ERR_NOT_CHECKED) {
 		err_printk(ref->dev, entry,
Signature · 6 lines
2.25.4

_______________________________________________
iommu mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/iommu

A message that is not in the archive (sent off-list or not yet received): 0539f4b4b442dba92358b6c8d9e8fb5eafcec693.1588345503.git.mchehab+huawei-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org

#4 lore raw

Re: [PATCH 03/14] docs: fix references for DMA*.txt files

Quoted 4 lines · Mauro Carvalho Chehab

As we moved those files to core-api, fix references to point to their newer locations.

Quoted 8 lines
---
 Documentation/PCI/pci.rst                          |  6 +++---
 Documentation/block/biodoc.rst                     |  2 +-
 Documentation/core-api/bus-virt-phys-mapping.rst   |  2 +-
 Documentation/core-api/dma-api.rst                 |  6 +++---
 Documentation/core-api/dma-isa-lpc.rst             |  2 +-
 Documentation/driver-api/usb/dma.rst               |  6 +++---
 Documentation/memory-barriers.txt                  |  6 +++---

For memory-barriers.txt:

Quoted 399 lines
 .../translations/ko_KR/memory-barriers.txt         |  6 +++---
 arch/ia64/hp/common/sba_iommu.c                    | 12 ++++++------
 arch/parisc/kernel/pci-dma.c                       |  2 +-
 arch/x86/include/asm/dma-mapping.h                 |  4 ++--
 arch/x86/kernel/amd_gart_64.c                      |  2 +-
 drivers/parisc/sba_iommu.c                         | 14 +++++++-------
 include/linux/dma-mapping.h                        |  2 +-
 include/media/videobuf-dma-sg.h                    |  2 +-
 kernel/dma/debug.c                                 |  2 +-
 16 files changed, 38 insertions(+), 38 deletions(-)
Documentation/PCI/pci.rst +3 -3
index 8c016d8c9862..d10d3fe604c5 100644
@@ -265,7 +265,7 @@ Set the DMA mask size
 ---------------------
 .. note::
    If anything below doesn't make sense, please refer to
-   Documentation/DMA-API.txt. This section is just a reminder that
+   :doc:`/core-api/dma-api`. This section is just a reminder that
    drivers need to indicate DMA capabilities of the device and is not
    an authoritative source for DMA interfaces.
 
@@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
 Setup shared control data
 -------------------------
 Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
-memory.  See Documentation/DMA-API.txt for a full description of
+memory.  See :doc:`/core-api/dma-api` for a full description of
 the DMA APIs. This section is just a reminder that it needs to be done
 before enabling DMA on the device.
 
@@ -421,7 +421,7 @@ owners if there is one.
 
 Then clean up "consistent" buffers which contain the control data.
 
-See Documentation/DMA-API.txt for details on unmapping interfaces.
+See :doc:`/core-api/dma-api` for details on unmapping interfaces.
 
 
 Unregister from other subsystems
Documentation/block/biodoc.rst +1 -1
index b964796ec9c7..ba7f45d0271c 100644
@@ -196,7 +196,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
 do not have a corresponding kernel virtual address space mapping) and
 low-memory pages.
 
-Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion
+Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion
 on PCI high mem DMA aspects and mapping of scatter gather lists, and support
 for 64 bit PCI.
 
Documentation/core-api/bus-virt-phys-mapping.rst +1 -1
index 4bb07c2f3e7d..c7bc99cd2e21 100644
@@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers
 
 	The virt_to_bus() and bus_to_virt() functions have been
 	superseded by the functionality provided by the PCI DMA interface
-	(see Documentation/DMA-API-HOWTO.txt).  They continue
+	(see :doc:`/core-api/dma-api-howto`).  They continue
 	to be documented below for historical purposes, but new code
 	must not use them. --davidm 00/12/12
 
Documentation/core-api/dma-api.rst +3 -3
index 2d8d2fed7317..63b4a2f20867 100644
@@ -5,7 +5,7 @@ Dynamic DMA mapping using the generic device
 :Author: James E.J. Bottomley <[email protected]>
 
 This document describes the DMA API.  For a more gentle introduction
-of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
+of the API (and actual examples), see :doc:`/core-api/dma-api-howto`.
 
 This API is split into two pieces.  Part I describes the basic API.
 Part II describes extensions for supporting non-consistent memory
@@ -471,7 +471,7 @@ without the _attrs suffixes, except that they pass an optional
 dma_attrs.
 
 The interpretation of DMA attributes is architecture-specific, and
-each attribute should be documented in Documentation/DMA-attributes.txt.
+each attribute should be documented in :doc:`/core-api/dma-attributes`.
 
 If dma_attrs are 0, the semantics of each of these functions
 is identical to those of the corresponding function
@@ -484,7 +484,7 @@ for DMA::
 
 	#include <linux/dma-mapping.h>
 	/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
-	* documented in Documentation/DMA-attributes.txt */
+	* documented in Documentation/core-api/dma-attributes.rst */
...
 
 		unsigned long attr;
Documentation/core-api/dma-isa-lpc.rst +1 -1
index b1ec7b16c21f..e59a3d35a93d 100644
@@ -17,7 +17,7 @@ To do ISA style DMA you need to include two headers::
 	#include <asm/dma.h>
 
 The first is the generic DMA API used to convert virtual addresses to
-bus addresses (see Documentation/DMA-API.txt for details).
+bus addresses (see :doc:`/core-api/dma-api` for details).
 
 The second contains the routines specific to ISA DMA transfers. Since
 this is not present on all platforms make sure you construct your
Documentation/driver-api/usb/dma.rst +3 -3
index 59d5aee89e37..2b3dbd3265b4 100644
@@ -10,7 +10,7 @@ API overview
 
 The big picture is that USB drivers can continue to ignore most DMA issues,
 though they still must provide DMA-ready buffers (see
-``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+:doc:`/core-api/dma-api-howto`).  That's how they've worked through
 the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
 DMA-aware usb drivers:
@@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties.
   force a consistent memory access ordering by using memory barriers.  It's
   not using a streaming DMA mapping, so it's good for small transfers on
   systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and
+  :doc:`/core-api/dma-api-howto` for definitions of "coherent" and
   "streaming" DMA mappings.)
 
   Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -91,7 +91,7 @@ Working with existing buffers
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  However, most buffers passed to your
 driver can safely be used with such DMA mapping.  (See the first section
-of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
+of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?")
 
 - When you're using scatterlists, you can map everything at once.  On some
   systems, this kicks in an IOMMU and turns the scatterlists into single
Documentation/memory-barriers.txt +3 -3
index eaabc3134294..0e4947a8282d 100644
@@ -546,8 +546,8 @@ There are certain things that the Linux kernel memory barriers do not guarantee:
 	[*] For information on bus mastering DMA and coherency please read:
 
 	    Documentation/driver-api/pci/pci.rst
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
+	    Documentation/core-api/dma-api-howto.rst
+	    Documentation/core-api/dma-api.rst
 
 
 DATA DEPENDENCY BARRIERS (HISTORICAL)
@@ -1932,7 +1932,7 @@ There are some more advanced barrier functions:
      here.
 
      See the subsection "Kernel I/O barrier effects" for more information on
-     relaxed I/O accessors and the Documentation/DMA-API.txt file for more
+     relaxed I/O accessors and the Documentation/core-api/dma-api.rst file for more
      information on consistent memory.
 
 
Documentation/translations/ko_KR/memory-barriers.txt +3 -3
index e50fe6541335..037e82ade93c 100644
@@ -570,8 +570,8 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 
 	[*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다:
 
 	    Documentation/driver-api/pci/pci.rst
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
+	    Documentation/core-api/dma-api-howto.rst
+	    Documentation/core-api/dma-api.rst
 
 
 데이터 의존성 배리어 (역사적)
@@ -1904,7 +1904,7 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효
 
      writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는
      "커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을
-     위해선 Documentation/DMA-API.txt 문서를 참고하세요.
+     위해선 Documentation/core-api/dma-api.rst 문서를 참고하세요.
 
 
 =========================
arch/ia64/hp/common/sba_iommu.c +6 -6
index a806227c1fad..656a4888c300 100644
@@ -907,7 +907,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
  * @dir: dma direction
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static dma_addr_t sba_map_page(struct device *dev, struct page *page,
 			       unsigned long poff, size_t size,
@@ -1028,7 +1028,7 @@ sba_mark_clean(struct ioc *ioc, dma_addr_t iova, size_t size)
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
 			   enum dma_data_direction dir, unsigned long attrs)
@@ -1105,7 +1105,7 @@ static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
  * @size:  number of bytes mapped in driver buffer.
  * @dma_handle:  IOVA of new buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void *
 sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
@@ -1162,7 +1162,7 @@ sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
  * @vaddr:  virtual address IOVA of "consistent" buffer.
  * @dma_handler:  IO virtual address of "consistent" buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void sba_free_coherent(struct device *dev, size_t size, void *vaddr,
 			      dma_addr_t dma_handle, unsigned long attrs)
@@ -1425,7 +1425,7 @@ static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
 			    int nents, enum dma_data_direction dir,
@@ -1524,7 +1524,7 @@ static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
 			       int nents, enum dma_data_direction dir,
arch/parisc/kernel/pci-dma.c +1 -1
index 0f1b460ee715..a86c9456b3c1 100644
@@ -3,7 +3,7 @@
 ** PARISC 1.1 Dynamic DMA mapping support.
 ** This implementation is for PA-RISC platforms that do not support
 ** I/O TLBs (aka DMA address translation hardware).
-** See Documentation/DMA-API-HOWTO.txt for interface definitions.
+** See Documentation/core-api/dma-api-howto.rst for interface definitions.
 **
 **      (c) Copyright 1999,2000 Hewlett-Packard Company
 **      (c) Copyright 2000 Grant Grundler
arch/x86/include/asm/dma-mapping.h +2 -2
index 6b15a24930e0..fed67eafcacc 100644
@@ -3,8 +3,8 @@
 #define _ASM_X86_DMA_MAPPING_H
 
 /*
- * IOMMU interface. See Documentation/DMA-API-HOWTO.txt and
- * Documentation/DMA-API.txt for documentation.
+ * IOMMU interface. See Documentation/core-api/dma-api-howto.rst and
+ * Documentation/core-api/dma-api.rst for documentation.
  */
 
 #include <linux/scatterlist.h>
arch/x86/kernel/amd_gart_64.c +1 -1
index 5f816861f5d2..13386e13d711 100644
@@ -6,7 +6,7 @@
  * This allows to use PCI devices that only support 32bit addresses on systems
  * with more than 4GB.
  *
- * See Documentation/DMA-API-HOWTO.txt for the interface specification.
+ * See Documentation/core-api/dma-api-howto.rst for the interface specification.
  *
  * Copyright 2002 Andi Kleen, SuSE Labs.
  */
drivers/parisc/sba_iommu.c +7 -7
index 7e112829d250..5368452eb5a6 100644
@@ -666,7 +666,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
  * @dev: instance of PCI owned by the driver that's asking
  * @mask:  number of address bits this PCI device can handle
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static int sba_dma_supported( struct device *dev, u64 mask)
 {
@@ -698,7 +698,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
  * @size:  number of bytes to map in driver buffer.
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static dma_addr_t
 sba_map_single(struct device *dev, void *addr, size_t size,
@@ -788,7 +788,7 @@ sba_map_page(struct device *dev, struct page *page, unsigned long offset,
  * @size:  number of bytes mapped in driver buffer.
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void
 sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
@@ -867,7 +867,7 @@ sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
  * @size:  number of bytes mapped in driver buffer.
  * @dma_handle:  IOVA of new buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle,
 		gfp_t gfp, unsigned long attrs)
@@ -898,7 +898,7 @@ static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle
  * @vaddr:  virtual address IOVA of "consistent" buffer.
  * @dma_handler:  IO virtual address of "consistent" buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void
 sba_free(struct device *hwdev, size_t size, void *vaddr,
@@ -933,7 +933,7 @@ int dump_run_sg = 0;
  * @nents:  number of entries in list
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static int
 sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
@@ -1017,7 +1017,7 @@ sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
  * @nents:  number of entries in list
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/core-api/dma-api-howto.rst
  */
 static void 
 sba_unmap_sg(struct device *dev, struct scatterlist *sglist, int nents,
include/linux/dma-mapping.h +1 -1
index b43116a6405d..f893a6bb3125 100644
@@ -14,7 +14,7 @@
 
 /**
  * List of possible attributes associated with a DMA mapping. The semantics
- * of each attribute should be defined in Documentation/DMA-attributes.txt.
+ * of each attribute should be defined in Documentation/core-api/dma-attributes.rst.
  */
 
 /*
include/media/videobuf-dma-sg.h +1 -1
index b89d5e31f172..34450f7ad510 100644
@@ -31,7 +31,7 @@
  *	does memory allocation too using vmalloc_32().
  *
  * videobuf_dma_*()
- *	see Documentation/DMA-API-HOWTO.txt, these functions to
+ *	see Documentation/core-api/dma-api-howto.rst, these functions to
  *	basically the same.  The map function does also build a
  *	scatterlist for the buffer (and unmap frees it ...)
  *
kernel/dma/debug.c +1 -1
index 36c962a86bf2..f97f088ace7e 100644
@@ -1071,7 +1071,7 @@ static void check_unmap(struct dma_debug_entry *ref)
 	/*
 	 * Drivers should use dma_mapping_error() to check the returned
 	 * addresses of dma_map_single() and dma_map_page().
-	 * If not, print this warning message. See Documentation/DMA-API.txt.
+	 * If not, print this warning message. See Documentation/core-api/dma-api.rst.
 	 */
 	if (entry->map_err_type == MAP_ERR_NOT_CHECKED) {
 		err_printk(ref->dev, entry,
Signature · 1 line
2.25.4

_______________________________________________
iommu mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/iommu

#5 lore raw

Re: [PATCH 03/14] docs: fix references for DMA*.txt files

In reply to a message not in the archive
Quoted 14 lines · On Fri, 1 May 2020 17:37:47 +0200 Mauro Carvalho Chehab…

As we moved those files to core-api, fix references to point to their newer locations.

---
 Documentation/PCI/pci.rst                          |  6 +++---
 Documentation/block/biodoc.rst                     |  2 +-
 Documentation/core-api/bus-virt-phys-mapping.rst   |  2 +-
 Documentation/core-api/dma-api.rst                 |  6 +++---
 Documentation/core-api/dma-isa-lpc.rst             |  2 +-
 Documentation/driver-api/usb/dma.rst               |  6 +++---
 Documentation/memory-barriers.txt                  |  6 +++---
 .../translations/ko_KR/memory-barriers.txt         |  6 +++---
 arch/ia64/hp/common/sba_iommu.c                    | 12 ++++++------
Quoted 8 lines
 arch/parisc/kernel/pci-dma.c                       |  2 +-
 arch/x86/include/asm/dma-mapping.h                 |  4 ++--
 arch/x86/kernel/amd_gart_64.c                      |  2 +-
 drivers/parisc/sba_iommu.c                         | 14 +++++++-------
 include/linux/dma-mapping.h                        |  2 +-
 include/media/videobuf-dma-sg.h                    |  2 +-
 kernel/dma/debug.c                                 |  2 +-
 16 files changed, 38 insertions(+), 38 deletions(-)

...of course, not applying patch 2 causes this one to not apply, so holding off for now...

jon

#6 lore raw

PATCH 1/14 docs: move DMA kAPI to Documentation/core-api

In reply to Mauro Carvalho Chehab

Move those files to the core-api, where they belong, renaming them to ReST and adding to the core API index file.

---
 .../{DMA-API-HOWTO.txt => core-api/dma-api-howto.rst}         | 0
 Documentation/{DMA-API.txt => core-api/dma-api.rst}           | 0
 .../{DMA-attributes.txt => core-api/dma-attributes.rst}       | 0
 Documentation/{DMA-ISA-LPC.txt => core-api/dma-isa-lpc.rst}   | 0
 Documentation/core-api/index.rst                              | 4 ++++
 5 files changed, 4 insertions(+)
 rename Documentation/{DMA-API-HOWTO.txt => core-api/dma-api-howto.rst} (100%)
 rename Documentation/{DMA-API.txt => core-api/dma-api.rst} (100%)
 rename Documentation/{DMA-attributes.txt => core-api/dma-attributes.rst} (100%)
 rename Documentation/{DMA-ISA-LPC.txt => core-api/dma-isa-lpc.rst} (100%)
Documentation/core-api/dma-api-howto.rst renamed from Documentation/DMA-API-HOWTO.txt +0 -0
similarity index 100%
rename from Documentation/DMA-API-HOWTO.txt
rename to Documentation/core-api/dma-api-howto.rst
Documentation/core-api/dma-api.rst renamed from Documentation/DMA-API.txt +0 -0
similarity index 100%
rename from Documentation/DMA-API.txt
rename to Documentation/core-api/dma-api.rst
Documentation/core-api/dma-attributes.rst renamed from Documentation/DMA-attributes.txt +0 -0
similarity index 100%
rename from Documentation/DMA-attributes.txt
rename to Documentation/core-api/dma-attributes.rst
Documentation/core-api/dma-isa-lpc.rst renamed from Documentation/DMA-ISA-LPC.txt +0 -0
similarity index 100%
rename from Documentation/DMA-ISA-LPC.txt
rename to Documentation/core-api/dma-isa-lpc.rst
Documentation/core-api/index.rst +4 -0
index b29c4a07beda..c00aef843341 100644
@@ -80,6 +80,10 @@ more memory-management documentation in :doc:`/vm/index`.
    :maxdepth: 1
 
    memory-allocation
+   dma-api
+   dma-api-howto
+   dma-attributes
+   dma-isa-lpc
    mm-api
    genalloc
    pin_user_pages
Signature · 1 line
2.25.4
maintainer
#7 lore raw

Re: [PATCH 01/14] docs: move DMA kAPI to Documentation/core-api

Quoted 4 lines · On Fri, 1 May 2020 17:37:45 +0200 Mauro Carvalho Chehab…

Move those files to the core-api, where they belong, renaming them to ReST and adding to the core API index file.

Quoted 11 lines
---
 .../{DMA-API-HOWTO.txt => core-api/dma-api-howto.rst}         | 0
 Documentation/{DMA-API.txt => core-api/dma-api.rst}           | 0
 .../{DMA-attributes.txt => core-api/dma-attributes.rst}       | 0
 Documentation/{DMA-ISA-LPC.txt => core-api/dma-isa-lpc.rst}   | 0
 Documentation/core-api/index.rst                              | 4 ++++
 5 files changed, 4 insertions(+)
 rename Documentation/{DMA-API-HOWTO.txt => core-api/dma-api-howto.rst} (100%)
 rename Documentation/{DMA-API.txt => core-api/dma-api.rst} (100%)
 rename Documentation/{DMA-attributes.txt => core-api/dma-attributes.rst} (100%)
 rename Documentation/{DMA-ISA-LPC.txt => core-api/dma-isa-lpc.rst} (100%)

This one seems obvious, applied.

jon

#8 lore raw

PATCH 2/14 docs: add bus-virt-phys-mapping.txt to core-api

In reply to Mauro Carvalho Chehab

This describes an old interface used prior the new DMA-API interfaces. Add it to the core-api guide, just after the DMA stuff.

---
 .../bus-virt-phys-mapping.rst}                                   | 0
 Documentation/core-api/index.rst                                 | 1 +
 2 files changed, 1 insertion(+)
 rename Documentation/{bus-virt-phys-mapping.txt => core-api/bus-virt-phys-mapping.rst} (100%)
Documentation/core-api/bus-virt-phys-mapping.rst renamed from Documentation/bus-virt-phys-mapping.txt +0 -0
similarity index 100%
rename from Documentation/bus-virt-phys-mapping.txt
rename to Documentation/core-api/bus-virt-phys-mapping.rst
Documentation/core-api/index.rst +1 -0
index c00aef843341..b70039d458a7 100644
@@ -84,6 +84,7 @@ more memory-management documentation in :doc:`/vm/index`.
    dma-api-howto
    dma-attributes
    dma-isa-lpc
+   bus-virt-phys-mapping
    mm-api
    genalloc
    pin_user_pages
Signature · 1 line
2.25.4
maintainer
#9 lore raw

Re: [PATCH 02/14] docs: add bus-virt-phys-mapping.txt to core-api

Quoted 10 lines · On Fri, 1 May 2020 17:37:46 +0200 Mauro Carvalho Chehab…

This describes an old interface used prior the new DMA-API interfaces. Add it to the core-api guide, just after the DMA stuff.

---
 .../bus-virt-phys-mapping.rst}                                   | 0
 Documentation/core-api/index.rst                                 | 1 +
 2 files changed, 1 insertion(+)
 rename Documentation/{bus-virt-phys-mapping.txt => core-api/bus-virt-phys-mapping.rst} (100%)

For this one, I think we should maybe just delete the file. It contains a warning from *20 years ago* saying not to use it, and talks about functions like isa_readl() that haven't existed i the kernel for some time. Is there any reason to keep dragging it around?

jon

#10 lore raw

Re: [PATCH 02/14] docs: add bus-virt-phys-mapping.txt to core-api

Em Fri, 15 May 2020 11:53:21 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 14 lines
Quoted 10 lines · On Fri, 1 May 2020 17:37:46 +0200 Mauro Carvalho Chehab…

This describes an old interface used prior the new DMA-API interfaces. Add it to the core-api guide, just after the DMA stuff.

---
 .../bus-virt-phys-mapping.rst}                                   | 0
 Documentation/core-api/index.rst                                 | 1 +
 2 files changed, 1 insertion(+)
 rename Documentation/{bus-virt-phys-mapping.txt => core-api/bus-virt-phys-mapping.rst} (100%)  
Quoted 4 lines

For this one, I think we should maybe just delete the file. It contains a warning from *20 years ago* saying not to use it, and talks about functions like isa_readl() that haven't existed i the kernel for some time. Is there any reason to keep dragging it around?

Except for "keeping it for historical reasons" (as mentioned at the file), I don't see any reason why to keep it.

It might be useful if someone wants to port some OOT code based on a legacy kernel.

Yet, if you prefer to just trash it, I'm ok with that.

Thanks,
Mauro

#11 lore raw

PATCH 4/14 docs: move IPMI.txt to the driver API book

In reply to Mauro Carvalho Chehab

The IPMI is under drivers/char. This doc describes the kAPI part of the IPMI (mainly).

So, move it to the driver-api directory and add it to the corresponding index.rst file.

---
 Documentation/driver-api/index.rst              | 1 +
 Documentation/{IPMI.txt => driver-api/ipmi.rst} | 0
 2 files changed, 1 insertion(+)
 rename Documentation/{IPMI.txt => driver-api/ipmi.rst} (100%)
Documentation/driver-api/index.rst +1 -0
index dcc47c029f8e..6567187e7687 100644
@@ -39,6 +39,7 @@ available subsections can be seen below.
    spi
    i2c
    ipmb
+   ipmi
    i3c/index
    interconnect
    devfreq
Documentation/driver-api/ipmi.rst renamed from Documentation/IPMI.txt +0 -0
similarity index 100%
rename from Documentation/IPMI.txt
rename to Documentation/driver-api/ipmi.rst
Signature · 1 line
2.25.4
Acked-by on v1 4/14
#12 lore raw

Re: [PATCH 04/14] docs: move IPMI.txt to the driver API book

Quoted 7 lines · Mauro Carvalho Chehab

The IPMI is under drivers/char. This doc describes the kAPI part of the IPMI (mainly).

So, move it to the driver-api directory and add it to the corresponding index.rst file.

This is fine with me.

Quoted 25 lines
---
 Documentation/driver-api/index.rst              | 1 +
 Documentation/{IPMI.txt => driver-api/ipmi.rst} | 0
 2 files changed, 1 insertion(+)
 rename Documentation/{IPMI.txt => driver-api/ipmi.rst} (100%)
Documentation/driver-api/index.rst +1 -0
index dcc47c029f8e..6567187e7687 100644
@@ -39,6 +39,7 @@ available subsections can be seen below.
    spi
    i2c
    ipmb
+   ipmi
    i3c/index
    interconnect
    devfreq
Documentation/driver-api/ipmi.rst renamed from Documentation/IPMI.txt +0 -0
similarity index 100%
rename from Documentation/IPMI.txt
rename to Documentation/driver-api/ipmi.rst
Signature · 1 line
2.25.4
maintainer Applied
#13 lore raw

Re: [PATCH 04/14] docs: move IPMI.txt to the driver API book

In reply to Mauro Carvalho Chehab
Quoted 7 lines · On Fri, 1 May 2020 17:37:48 +0200 Mauro Carvalho Chehab…

The IPMI is under drivers/char. This doc describes the kAPI part of the IPMI (mainly).

So, move it to the driver-api directory and add it to the corresponding index.rst file.

Applied this one (and the fixups in patch 5), thanks.

jon

#14 lore raw

PATCH 5/14 docs: fix references for ipmi.rst file

In reply to Mauro Carvalho Chehab

As this file got moved, fix references for it.

---
 MAINTAINERS                        | 2 +-
 drivers/char/ipmi/Kconfig          | 2 +-
 drivers/char/ipmi/ipmi_si_hotmod.c | 2 +-
 drivers/char/ipmi/ipmi_si_intf.c   | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)
MAINTAINERS +1 -1
index b0cf6c358136..a1d7af532950 100644
@@ -8932,7 +8932,7 @@ M:	Corey Minyard <[email protected]>
 L:	[email protected] (moderated for non-subscribers)
 S:	Supported
 W:	http://openipmi.sourceforge.net/
-F:	Documentation/IPMI.txt
+F:	Documentation/driver-api/ipmi.rst
 F:	Documentation/devicetree/bindings/ipmi/
 F:	drivers/char/ipmi/
 F:	include/linux/ipmi*
drivers/char/ipmi/Kconfig +1 -1
index 7dc2c3ec4051..07847d9a459a 100644
@@ -14,7 +14,7 @@ menuconfig IPMI_HANDLER
 	  IPMI is a standard for managing sensors (temperature,
 	  voltage, etc.) in a system.
 
-	  See <file:Documentation/IPMI.txt> for more details on the driver.
+	  See <file:Documentation/driver-api/ipmi.rst> for more details on the driver.
 
 	  If unsure, say N.
 
drivers/char/ipmi/ipmi_si_hotmod.c +1 -1
index 42a925f8cf69..4fbb4e18bae2 100644
@@ -18,7 +18,7 @@ static int hotmod_handler(const char *val, const struct kernel_param *kp);
 
 module_param_call(hotmod, hotmod_handler, NULL, NULL, 0200);
 MODULE_PARM_DESC(hotmod, "Add and remove interfaces.  See"
-		 " Documentation/IPMI.txt in the kernel sources for the"
+		 " Documentation/driver-api/ipmi.rst in the kernel sources for the"
 		 " gory details.");
 
 /*
drivers/char/ipmi/ipmi_si_intf.c +1 -1
index c7cc8538b84a..77b8d551ae7f 100644
@@ -968,7 +968,7 @@ static inline bool ipmi_thread_busy_wait(enum si_sm_result smi_result,
  * that are not BT and do not have interrupts.  It starts spinning
  * when an operation is complete or until max_busy tells it to stop
  * (if that is enabled).  See the paragraph on kimid_max_busy_us in
- * Documentation/IPMI.txt for details.
+ * Documentation/driver-api/ipmi.rst for details.
  */
 static int ipmi_thread(void *data)
 {
Signature · 1 line
2.25.4
#15 lore raw

PATCH 6/14 docs: debugging-via-ohci1394.txt: add it to the core-api book

In reply to Mauro Carvalho Chehab

There is an special chapter inside the core-api book about some debug infrastructure like tracepoints and debug objects.

It sounded to me that this is the best place to add a chapter explaining how to use a FireWire controller to do remote kernel debugging, as explained on this document.

---
 Documentation/admin-guide/kernel-parameters.txt                 | 2 +-
 .../debugging-via-ohci1394.rst}                                 | 0
 Documentation/core-api/index.rst                                | 1 +
 lib/Kconfig.debug                                               | 2 +-
 4 files changed, 3 insertions(+), 2 deletions(-)
 rename Documentation/{debugging-via-ohci1394.txt => core-api/debugging-via-ohci1394.rst} (100%)
Documentation/admin-guide/kernel-parameters.txt +1 -1
index 25644daa36ea..d9b61da7809d 100644
@@ -3350,7 +3350,7 @@
 			See Documentation/admin-guide/sysctl/vm.rst for details.
 
 	ohci1394_dma=early	[HW] enable debugging via the ohci1394 driver.
-			See Documentation/debugging-via-ohci1394.txt for more
+			See Documentation/core-api/debugging-via-ohci1394.rst for more
 			info.
 
 	olpc_ec_timeout= [OLPC] ms delay when issuing EC commands
Documentation/core-api/debugging-via-ohci1394.rst renamed from Documentation/debugging-via-ohci1394.txt +0 -0
similarity index 100%
rename from Documentation/debugging-via-ohci1394.txt
rename to Documentation/core-api/debugging-via-ohci1394.rst
Documentation/core-api/index.rst +1 -0
index b70039d458a7..ab056b3626f4 100644
@@ -99,6 +99,7 @@ Interfaces for kernel debugging
 
    debug-objects
    tracepoint
+   debugging-via-ohci1394
 
 Everything else
 ===============
lib/Kconfig.debug +1 -1
index 8e4aded46281..4e631f294737 100644
@@ -1552,7 +1552,7 @@ config PROVIDE_OHCI1394_DMA_INIT
 	  This code (~1k) is freed after boot. By then, the firewire stack
 	  in charge of the OHCI-1394 controllers should be used instead.
 
-	  See Documentation/debugging-via-ohci1394.txt for more information.
+	  See Documentation/core-api/debugging-via-ohci1394.rst for more information.
 
 source "samples/Kconfig"
 
Signature · 1 line
2.25.4
maintainer
#16 lore raw

Re: [PATCH 06/14] docs: debugging-via-ohci1394.txt: add it to the core-api book

Quoted 8 lines · On Fri, 1 May 2020 17:37:50 +0200 Mauro Carvalho Chehab…

There is an special chapter inside the core-api book about some debug infrastructure like tracepoints and debug objects.

It sounded to me that this is the best place to add a chapter explaining how to use a FireWire controller to do remote kernel debugging, as explained on this document.

I've applied this, but core-api really seems like the wrong place for this. It would be good to rethink our layout a bit at some point in the near future...

Thanks,

jon

#17 lore raw

Re: [PATCH 06/14] docs: debugging-via-ohci1394.txt: add it to the core-api book

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

Quoted 10 lines
Quoted 7 lines · On Fri, 1 May 2020 17:37:50 +0200 Mauro Carvalho Chehab…

There is an special chapter inside the core-api book about some debug infrastructure like tracepoints and debug objects.

It sounded to me that this is the best place to add a chapter explaining how to use a FireWire controller to do remote kernel debugging, as explained on this document.

Quoted 5 lines
Quoted 1 line

I've applied this, but core-api really seems like the wrong place for this. It would be good to rethink our layout a bit at some point in the near future...

Yeah, agreed. Debug functionality should likely deserve a separate chapter outside core-api.

Now that we'll have all docs converted, it should be easier to view the hole picture and re-design the doc organization.

Thanks,
Mauro

#18 lore raw

PATCH 7/14 docs: add IRQ documentation at the core-api book

In reply to Mauro Carvalho Chehab

There are 4 IRQ documentation files under Documentation/*.txt.

Move them into a new directory (core-api/irq) and add a new index file for it.

While here, use a title markup for the Debugging section of the irq-domain.rst file.

---
 Documentation/admin-guide/hw-vuln/l1tf.rst            |  2 +-
 Documentation/admin-guide/kernel-per-CPU-kthreads.rst |  2 +-
 Documentation/core-api/index.rst                      |  1 +
 Documentation/{IRQ.txt => core-api/irq/concepts.rst}  |  0
 Documentation/core-api/irq/index.rst                  | 11 +++++++++++
 .../irq/irq-affinity.rst}                             |  0
 .../{IRQ-domain.txt => core-api/irq/irq-domain.rst}   |  3 ++-
 .../irq/irqflags-tracing.rst}                         |  0
 Documentation/ia64/irq-redir.rst                      |  2 +-
 Documentation/networking/scaling.rst                  |  4 ++--
 Documentation/translations/zh_CN/IRQ.txt              |  4 ++--
 MAINTAINERS                                           |  2 +-
 12 files changed, 22 insertions(+), 9 deletions(-)
 rename Documentation/{IRQ.txt => core-api/irq/concepts.rst} (100%)
 create mode 100644 Documentation/core-api/irq/index.rst
 rename Documentation/{IRQ-affinity.txt => core-api/irq/irq-affinity.rst} (100%)
 rename Documentation/{IRQ-domain.txt => core-api/irq/irq-domain.rst} (99%)
 rename Documentation/{irqflags-tracing.txt => core-api/irq/irqflags-tracing.rst} (100%)
Documentation/admin-guide/hw-vuln/l1tf.rst +1 -1
index f83212fae4d5..3eeeb488d955 100644
@@ -268,7 +268,7 @@ Guest mitigation mechanisms
    /proc/irq/$NR/smp_affinity[_list] files. Limited documentation is
    available at:
 
-   https://www.kernel.org/doc/Documentation/IRQ-affinity.txt
+   https://www.kernel.org/doc/Documentation/core-api/irq/irq-affinity.rst
 
 .. _smt_control:
 
Documentation/admin-guide/kernel-per-CPU-kthreads.rst +1 -1
index 21818aca4708..dc36aeb65d0a 100644
@@ -10,7 +10,7 @@ them to a "housekeeping" CPU dedicated to such work.
 References
 =====
 
--	Documentation/IRQ-affinity.txt:  Binding interrupts to sets of CPUs.
+-	Documentation/core-api/irq/irq-affinity.rst:  Binding interrupts to sets of CPUs.
 
 -	Documentation/admin-guide/cgroup-v1:  Using cgroups to bind tasks to sets of CPUs.
 
Documentation/core-api/index.rst +1 -0
index ab056b3626f4..49a885e83a55 100644
@@ -52,6 +52,7 @@ How Linux keeps everything from happening at the same time.  See
 
    atomic_ops
    refcount-vs-atomic
+   irq/index
    local_ops
    padata
    ../RCU/index
Documentation/core-api/irq/concepts.rst renamed from Documentation/IRQ.txt +0 -0
similarity index 100%
rename from Documentation/IRQ.txt
rename to Documentation/core-api/irq/concepts.rst
Documentation/core-api/irq/index.rst new file +11 -0
new file mode 100644
index 000000000000..0d65d11e5420
@@ -0,0 +1,11 @@
+==
+IRQs
+==
+
+.. toctree::
+   :maxdepth: 1
+
+   concepts
+   irq-affinity
+   irq-domain
+   irqflags-tracing
Documentation/core-api/irq/irq-affinity.rst renamed from Documentation/IRQ-affinity.txt +0 -0
similarity index 100%
rename from Documentation/IRQ-affinity.txt
rename to Documentation/core-api/irq/irq-affinity.rst
Documentation/core-api/irq/irq-domain.rst renamed from Documentation/IRQ-domain.txt +1 -1
similarity index 99%
rename from Documentation/IRQ-domain.txt
rename to Documentation/core-api/irq/irq-domain.rst
index 507775cce753..096db12f32d5 100644
@@ -263,7 +263,8 @@ needs to:
 Hierarchy irq_domain is in no way x86 specific, and is heavily used to
 support other architectures, such as ARM, ARM64 etc.
 
-== Debugging =+Debugging
+==== 
 Most of the internals of the IRQ subsystem are exposed in debugfs by
 turning CONFIG_GENERIC_IRQ_DEBUGFS on.
Documentation/core-api/irq/irqflags-tracing.rst renamed from Documentation/irqflags-tracing.txt +0 -0
similarity index 100%
rename from Documentation/irqflags-tracing.txt
rename to Documentation/core-api/irq/irqflags-tracing.rst
Documentation/ia64/irq-redir.rst +1 -1
index 39bf94484a15..6bbbbe4f73ef 100644
@@ -7,7 +7,7 @@ IRQ affinity on IA64 platforms
 
 By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
 controlled. The behavior on IA64 platforms is slightly different from
-that described in Documentation/IRQ-affinity.txt for i386 systems.
+that described in Documentation/core-api/irq/irq-affinity.rst for i386 systems.
 
 Because of the usage of SAPIC mode and physical destination mode the
 IRQ target is one particular CPU and cannot be a mask of several
Documentation/networking/scaling.rst +2 -2
index f78d7bf27ff5..8f0347b9fb3d 100644
@@ -81,7 +81,7 @@ of queues to IRQs can be determined from /proc/interrupts. By default,
 an IRQ may be handled on any CPU. Because a non-negligible part of packet
 processing takes place in receive interrupt handling, it is advantageous
 to spread receive interrupts between CPUs. To manually adjust the IRQ
-affinity of each interrupt see Documentation/IRQ-affinity.txt. Some systems
+affinity of each interrupt see Documentation/core-api/irq/irq-affinity.rst. Some systems
 will be running irqbalance, a daemon that dynamically optimizes IRQ
 assignments and as a result may override any manual settings.
 
@@ -160,7 +160,7 @@ can be configured for each receive queue using a sysfs file entry::
 
 This file implements a bitmap of CPUs. RPS is disabled when it is zero
 (the default), in which case packets are processed on the interrupting
-CPU. Documentation/IRQ-affinity.txt explains how CPUs are assigned to
+CPU. Documentation/core-api/irq/irq-affinity.rst explains how CPUs are assigned to
 the bitmap.
 
 
Documentation/translations/zh_CN/IRQ.txt +2 -2
index 956026d5cf82..9aec8dca4fcf 100644
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/IRQ.txt
+Chinese translated version of Documentation/core-api/irq/index.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Eric W. Biederman <[email protected]>
 Chinese maintainer: Fu Wei <[email protected]>
 ---------------------------------------------------------------------
-Documentation/IRQ.txt 的中文翻译
+Documentation/core-api/irq/index.rst 的中文翻译
 
 如果想评论或更新本文的内容,请直接联系原文档的维护者。如果你使用英文
 交流有困难的话,也可以向中文版维护者求助。如果本翻译更新不及时或者翻
MAINTAINERS +1 -1
index a1d7af532950..6eb3d85a646f 100644
@@ -8974,7 +8974,7 @@ IRQ DOMAINS (IRQ NUMBER MAPPING LIBRARY)
 M:	Marc Zyngier <[email protected]>
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git irq/core
-F:	Documentation/IRQ-domain.txt
+F:	Documentation/core-api/irq/irq-domain.rst
 F:	include/linux/irqdomain.h
 F:	kernel/irq/irqdomain.c
 F:	kernel/irq/msi.c
Signature · 1 line
2.25.4
#19 lore raw

Re: [PATCH 07/14] docs: add IRQ documentation at the core-api book

Hello Mauro,

Quoted 4 lines · Mauro Carvalho Chehab

There are 4 IRQ documentation files under Documentation/*.txt.

Move them into a new directory (core-api/irq) and add a new index file for it.

Just curious, why IRQ docs got their subdirectory and DMA didn't :)

Quoted 176 lines

While here, use a title markup for the Debugging section of the irq-domain.rst file.

---
 Documentation/admin-guide/hw-vuln/l1tf.rst            |  2 +-
 Documentation/admin-guide/kernel-per-CPU-kthreads.rst |  2 +-
 Documentation/core-api/index.rst                      |  1 +
 Documentation/{IRQ.txt => core-api/irq/concepts.rst}  |  0
 Documentation/core-api/irq/index.rst                  | 11 +++++++++++
 .../irq/irq-affinity.rst}                             |  0
 .../{IRQ-domain.txt => core-api/irq/irq-domain.rst}   |  3 ++-
 .../irq/irqflags-tracing.rst}                         |  0
 Documentation/ia64/irq-redir.rst                      |  2 +-
 Documentation/networking/scaling.rst                  |  4 ++--
 Documentation/translations/zh_CN/IRQ.txt              |  4 ++--
 MAINTAINERS                                           |  2 +-
 12 files changed, 22 insertions(+), 9 deletions(-)
 rename Documentation/{IRQ.txt => core-api/irq/concepts.rst} (100%)
 create mode 100644 Documentation/core-api/irq/index.rst
 rename Documentation/{IRQ-affinity.txt => core-api/irq/irq-affinity.rst} (100%)
 rename Documentation/{IRQ-domain.txt => core-api/irq/irq-domain.rst} (99%)
 rename Documentation/{irqflags-tracing.txt => core-api/irq/irqflags-tracing.rst} (100%)
Documentation/admin-guide/hw-vuln/l1tf.rst +1 -1
index f83212fae4d5..3eeeb488d955 100644
@@ -268,7 +268,7 @@ Guest mitigation mechanisms
    /proc/irq/$NR/smp_affinity[_list] files. Limited documentation is
    available at:
 
-   https://www.kernel.org/doc/Documentation/IRQ-affinity.txt
+   https://www.kernel.org/doc/Documentation/core-api/irq/irq-affinity.rst
 
 .. _smt_control:
 
Documentation/admin-guide/kernel-per-CPU-kthreads.rst +1 -1
index 21818aca4708..dc36aeb65d0a 100644
@@ -10,7 +10,7 @@ them to a "housekeeping" CPU dedicated to such work.
 References
 =====
 
--	Documentation/IRQ-affinity.txt:  Binding interrupts to sets of CPUs.
+-	Documentation/core-api/irq/irq-affinity.rst:  Binding interrupts to sets of CPUs.
 
 -	Documentation/admin-guide/cgroup-v1:  Using cgroups to bind tasks to sets of CPUs.
 
Documentation/core-api/index.rst +1 -0
index ab056b3626f4..49a885e83a55 100644
@@ -52,6 +52,7 @@ How Linux keeps everything from happening at the same time.  See
 
    atomic_ops
    refcount-vs-atomic
+   irq/index
    local_ops
    padata
    ../RCU/index
Documentation/core-api/irq/concepts.rst renamed from Documentation/IRQ.txt +0 -0
similarity index 100%
rename from Documentation/IRQ.txt
rename to Documentation/core-api/irq/concepts.rst
Documentation/core-api/irq/index.rst new file +11 -0
new file mode 100644
index 000000000000..0d65d11e5420
@@ -0,0 +1,11 @@
+==
+IRQs
+==
+
+.. toctree::
+   :maxdepth: 1
+
+   concepts
+   irq-affinity
+   irq-domain
+   irqflags-tracing
Documentation/core-api/irq/irq-affinity.rst renamed from Documentation/IRQ-affinity.txt +0 -0
similarity index 100%
rename from Documentation/IRQ-affinity.txt
rename to Documentation/core-api/irq/irq-affinity.rst
Documentation/core-api/irq/irq-domain.rst renamed from Documentation/IRQ-domain.txt +1 -1
similarity index 99%
rename from Documentation/IRQ-domain.txt
rename to Documentation/core-api/irq/irq-domain.rst
index 507775cce753..096db12f32d5 100644
@@ -263,7 +263,8 @@ needs to:
 Hierarchy irq_domain is in no way x86 specific, and is heavily used to
 support other architectures, such as ARM, ARM64 etc.
 
-== Debugging => +Debugging
+====>  
 Most of the internals of the IRQ subsystem are exposed in debugfs by
 turning CONFIG_GENERIC_IRQ_DEBUGFS on.
Documentation/core-api/irq/irqflags-tracing.rst renamed from Documentation/irqflags-tracing.txt +0 -0
similarity index 100%
rename from Documentation/irqflags-tracing.txt
rename to Documentation/core-api/irq/irqflags-tracing.rst
Documentation/ia64/irq-redir.rst +1 -1
index 39bf94484a15..6bbbbe4f73ef 100644
@@ -7,7 +7,7 @@ IRQ affinity on IA64 platforms
 
 By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
 controlled. The behavior on IA64 platforms is slightly different from
-that described in Documentation/IRQ-affinity.txt for i386 systems.
+that described in Documentation/core-api/irq/irq-affinity.rst for i386 systems.
 
 Because of the usage of SAPIC mode and physical destination mode the
 IRQ target is one particular CPU and cannot be a mask of several
Documentation/networking/scaling.rst +2 -2
index f78d7bf27ff5..8f0347b9fb3d 100644
@@ -81,7 +81,7 @@ of queues to IRQs can be determined from /proc/interrupts. By default,
 an IRQ may be handled on any CPU. Because a non-negligible part of packet
 processing takes place in receive interrupt handling, it is advantageous
 to spread receive interrupts between CPUs. To manually adjust the IRQ
-affinity of each interrupt see Documentation/IRQ-affinity.txt. Some systems
+affinity of each interrupt see Documentation/core-api/irq/irq-affinity.rst. Some systems
 will be running irqbalance, a daemon that dynamically optimizes IRQ
 assignments and as a result may override any manual settings.
 
@@ -160,7 +160,7 @@ can be configured for each receive queue using a sysfs file entry::
 
 This file implements a bitmap of CPUs. RPS is disabled when it is zero
 (the default), in which case packets are processed on the interrupting
-CPU. Documentation/IRQ-affinity.txt explains how CPUs are assigned to
+CPU. Documentation/core-api/irq/irq-affinity.rst explains how CPUs are assigned to
 the bitmap.
 
 
Documentation/translations/zh_CN/IRQ.txt +2 -2
index 956026d5cf82..9aec8dca4fcf 100644
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/IRQ.txt
+Chinese translated version of Documentation/core-api/irq/index.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Eric W. Biederman <[email protected]>
 Chinese maintainer: Fu Wei <[email protected]>
 ---------------------------------------------------------------------
-Documentation/IRQ.txt 的中文翻译
+Documentation/core-api/irq/index.rst 的中文翻译
 
 如果想评论或更新本文的内容,请直接联系原文档的维护者。如果你使用英文
 交流有困难的话,也可以向中文版维护者求助。如果本翻译更新不及时或者翻
MAINTAINERS +1 -1
index a1d7af532950..6eb3d85a646f 100644
@@ -8974,7 +8974,7 @@ IRQ DOMAINS (IRQ NUMBER MAPPING LIBRARY)
 M:	Marc Zyngier <[email protected]>
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git irq/core
-F:	Documentation/IRQ-domain.txt
+F:	Documentation/core-api/irq/irq-domain.rst
 F:	include/linux/irqdomain.h
 F:	kernel/irq/irqdomain.c
 F:	kernel/irq/msi.c
Signature · 1 line
2.25.4
Signature · 2 lines
Sincerely yours,
Mike.
#20 lore raw

Re: [PATCH 07/14] docs: add IRQ documentation at the core-api book

Em Sat, 2 May 2020 10:41:33 +0300
Mike Rapoport <[email protected]> escreveu:

Quoted 9 lines

Hello Mauro,

Quoted 4 lines · Mauro Carvalho Chehab

There are 4 IRQ documentation files under Documentation/*.txt.

Move them into a new directory (core-api/irq) and add a new index file for it.

Just curious, why IRQ docs got their subdirectory and DMA didn't :)

Heh, you got me... :-)

The rationale I used is that DMA fits nicely being close to other memory related documents. As those currently don't have a subdir, I opted to not create a DMA-specific dir. I admit that his is a weak reason. I wouldn't mind placing them on a separate subdir, if you think it would be worth.

Thanks,
Mauro

#21 lore raw

Re: [PATCH 07/14] docs: add IRQ documentation at the core-api book

Quoted 13 lines · Mauro Carvalho Chehab

Em Sat, 2 May 2020 10:41:33 +0300
Mike Rapoport <[email protected]> escreveu:

Quoted 9 lines

Hello Mauro,

Quoted 4 lines · Mauro Carvalho Chehab

There are 4 IRQ documentation files under Documentation/*.txt.

Move them into a new directory (core-api/irq) and add a new index file for it.

Just curious, why IRQ docs got their subdirectory and DMA didn't :)

Quoted 7 lines

Heh, you got me... :-)

The rationale I used is that DMA fits nicely being close to other memory related documents. As those currently don't have a subdir, I opted to not create a DMA-specific dir. I admit that his is a weak reason. I wouldn't mind placing them on a separate subdir, if you think it would be worth.

I'm Ok without a dir as well :)

Quoted 2 lines

Thanks,
Mauro

Signature · 2 lines
Sincerely yours,
Mike.
maintainer Applied
#22 lore raw

Re: [PATCH 07/14] docs: add IRQ documentation at the core-api book

In reply to Mauro Carvalho Chehab
Quoted 9 lines · On Fri, 1 May 2020 17:37:51 +0200 Mauro Carvalho Chehab…

There are 4 IRQ documentation files under Documentation/*.txt.

Move them into a new directory (core-api/irq) and add a new index file for it.

While here, use a title markup for the Debugging section of the irq-domain.rst file.

Applied, thanks.

jon

#23 lore raw

PATCH 8/14 docs: move kobject and kref docs into the core-api book

In reply to Mauro Carvalho Chehab

Both documents are documenting Kernel core objects. So, add them into the core-api book.

---
 Documentation/core-api/index.rst              | 1 +
 Documentation/core-api/kobject.rst            | 2 +-
 Documentation/{kref.txt => core-api/kref.rst} | 0
 3 files changed, 2 insertions(+), 1 deletion(-)
 rename Documentation/{kref.txt => core-api/kref.rst} (100%)
Documentation/core-api/index.rst +1 -0
index 49a885e83a55..eeac63ba17c3 100644
@@ -31,6 +31,7 @@ Library functionality that is used throughout the kernel.
    :maxdepth: 1
 
    kobject
+   kref
    assoc_array
    xarray
    idr
Documentation/core-api/kobject.rst +1 -1
index 1f62d4d7d966..44c02be65475 100644
@@ -210,7 +210,7 @@ statically and will warn the developer of this improper usage.
 If all that you want to use a kobject for is to provide a reference counter
 for your structure, please use the struct kref instead; a kobject would be
 overkill.  For more information on how to use struct kref, please see the
-file Documentation/kref.txt in the Linux kernel source tree.
+file Documentation/core-api/kref.rst in the Linux kernel source tree.
 
 
 Creating "simple" kobjects
Documentation/core-api/kref.rst renamed from Documentation/kref.txt +0 -0
similarity index 100%
rename from Documentation/kref.txt
rename to Documentation/core-api/kref.rst
Signature · 1 line
2.25.4
maintainer
#24 lore raw

Re: [PATCH 08/14] docs: move kobject and kref docs into the core-api book

Quoted 10 lines · On Fri, 1 May 2020 17:37:52 +0200 Mauro Carvalho Chehab…

Both documents are documenting Kernel core objects. So, add them into the core-api book.

---
 Documentation/core-api/index.rst              | 1 +
 Documentation/core-api/kobject.rst            | 2 +-
 Documentation/{kref.txt => core-api/kref.rst} | 0
 3 files changed, 2 insertions(+), 1 deletion(-)
 rename Documentation/{kref.txt => core-api/kref.rst} (100%)

Applied with a tweaked changelog, since it's not actually moving the kobject doc.

jon

#25 lore raw

PATCH 9/14 docs: move digsig docs to the security book

In reply to Mauro Carvalho Chehab
---
 Documentation/{digsig.txt => security/digsig.rst} | 0
 Documentation/security/index.rst                  | 1 +
 2 files changed, 1 insertion(+)
 rename Documentation/{digsig.txt => security/digsig.rst} (100%)
Documentation/security/digsig.rst renamed from Documentation/digsig.txt +0 -0
similarity index 100%
rename from Documentation/digsig.txt
rename to Documentation/security/digsig.rst
Documentation/security/index.rst +1 -0
index fc503dd689a7..8129405eb2cc 100644
@@ -15,3 +15,4 @@ Security Documentation
    self-protection
    siphash
    tpm/index
+   digsig
Signature · 1 line
2.25.4
maintainer Applied
#26 lore raw

Re: [PATCH 09/14] docs: move digsig docs to the security book

Quoted 16 lines · On Fri, 1 May 2020 17:37:53 +0200 Mauro Carvalho Chehab…
---
 Documentation/{digsig.txt => security/digsig.rst} | 0
 Documentation/security/index.rst                  | 1 +
 2 files changed, 1 insertion(+)
 rename Documentation/{digsig.txt => security/digsig.rst} (100%)
Documentation/security/digsig.rst renamed from Documentation/digsig.txt +0 -0
similarity index 100%
rename from Documentation/digsig.txt
rename to Documentation/security/digsig.rst
Documentation/security/index.rst +0 -0
index fc503dd689a7..8129405eb2cc 100644

Documentation/security/index.rst Security Documentation · line 18

Quoted 4 lines
Documentation/security/index.rst +1 -0
@@ -15,3 +15,4 @@ Security Documentation
    self-protection
    siphash
    tpm/index
+   digsig

Applied, thanks.

jon

#27 lore raw

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

In reply to 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.

---
 .../{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%)
Documentation/locking/futex-requeue-pi.rst renamed from Documentation/futex-requeue-pi.txt +0 -0
similarity index 100%
rename from Documentation/futex-requeue-pi.txt
rename to Documentation/locking/futex-requeue-pi.rst
Documentation/locking/hwspinlock.rst renamed from Documentation/hwspinlock.txt +0 -0
similarity index 100%
rename from Documentation/hwspinlock.txt
rename to Documentation/locking/hwspinlock.rst
Documentation/locking/index.rst +7 -0
index 5d6800a723dc..d785878cad65 100644
@@ -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
 
Documentation/locking/percpu-rw-semaphore.rst renamed from Documentation/percpu-rw-semaphore.txt +0 -0
similarity index 100%
rename from Documentation/percpu-rw-semaphore.txt
rename to Documentation/locking/percpu-rw-semaphore.rst
Documentation/locking/pi-futex.rst renamed from Documentation/pi-futex.txt +0 -0
similarity index 100%
rename from Documentation/pi-futex.txt
rename to Documentation/locking/pi-futex.rst
Documentation/locking/preempt-locking.rst renamed from Documentation/preempt-locking.txt +0 -0
similarity index 100%
rename from Documentation/preempt-locking.txt
rename to Documentation/locking/preempt-locking.rst
Documentation/locking/robust-futex-ABI.rst renamed from Documentation/robust-futex-ABI.txt +0 -0
similarity index 100%
rename from Documentation/robust-futex-ABI.txt
rename to Documentation/locking/robust-futex-ABI.rst
Documentation/locking/robust-futexes.rst renamed from Documentation/robust-futexes.txt +0 -0
similarity index 100%
rename from Documentation/robust-futexes.txt
rename to Documentation/locking/robust-futexes.rst
Documentation/locking/rt-mutex.rst +1 -1
index c365dc302081..3b5097a380e6 100644
@@ -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
MAINTAINERS +3 -3
index 6eb3d85a646f..1aa6e89e7424 100644
@@ -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
 
Signature · 1 line
2.25.4
maintainer
#28 lore raw

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

Quoted 5 lines · On Fri, 1 May 2020 17:37:54 +0200 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.

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

Thanks,

jon

#29 lore raw

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:

Quoted 11 lines
Quoted 5 lines · On Fri, 1 May 2020 17:37:54 +0200 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.

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

#30 lore raw

PATCH 11/14 docs: move other kAPI documents to core-api

In reply to Mauro Carvalho Chehab

There are a number of random documents that seem to be describing some aspects of the core-api. Move them to such directory, adding them at the core-api/index.rst file.

---
 Documentation/admin-guide/sysctl/vm.rst                     | 2 +-
 Documentation/core-api/index.rst                            | 6 ++++++
 Documentation/{mailbox.txt => core-api/mailbox.rst}         | 0
 Documentation/{nommu-mmap.txt => core-api/nommu-mmap.rst}   | 0
 .../{this_cpu_ops.txt => core-api/this_cpu_ops.rst}         | 0
 .../unaligned-memory-access.rst}                            | 0
 Documentation/gpu/drm-mm.rst                                | 2 +-
 arch/Kconfig                                                | 2 +-
 init/Kconfig                                                | 2 +-
 mm/Kconfig                                                  | 2 +-
 mm/nommu.c                                                  | 2 +-
 11 files changed, 12 insertions(+), 6 deletions(-)
 rename Documentation/{mailbox.txt => core-api/mailbox.rst} (100%)
 rename Documentation/{nommu-mmap.txt => core-api/nommu-mmap.rst} (100%)
 rename Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst} (100%)
 rename Documentation/{unaligned-memory-access.txt => core-api/unaligned-memory-access.rst} (100%)
Documentation/admin-guide/sysctl/vm.rst +1 -1
index 0329a4d3fa9e..0bf2f2a84a9f 100644
@@ -583,7 +583,7 @@ trimming of allocations is initiated.
 
 The default value is 1.
 
-See Documentation/nommu-mmap.txt for more information.
+See Documentation/core-api/nommu-mmap.rst for more information.
 
 
 numa_zonelist_order
Documentation/core-api/index.rst +6 -0
index eeac63ba17c3..fe03a639a91a 100644
@@ -38,10 +38,14 @@ Library functionality that is used throughout the kernel.
    circular-buffers
    rbtree
    generic-radix-tree
+   mailbox
    packing
+   rbtree
+   this_cpu_ops
    timekeeping
    errseq
 
+
 Concurrency primitives
 ======================
 
@@ -82,11 +86,13 @@ more memory-management documentation in :doc:`/vm/index`.
    :maxdepth: 1
 
    memory-allocation
+   unaligned-memory-access
    dma-api
    dma-api-howto
    dma-attributes
    dma-isa-lpc
    bus-virt-phys-mapping
+   nommu-mmap
    mm-api
    genalloc
    pin_user_pages
Documentation/core-api/mailbox.rst renamed from Documentation/mailbox.txt +0 -0
similarity index 100%
rename from Documentation/mailbox.txt
rename to Documentation/core-api/mailbox.rst
Documentation/core-api/nommu-mmap.rst renamed from Documentation/nommu-mmap.txt +0 -0
similarity index 100%
rename from Documentation/nommu-mmap.txt
rename to Documentation/core-api/nommu-mmap.rst
Documentation/core-api/this_cpu_ops.rst renamed from Documentation/this_cpu_ops.txt +0 -0
similarity index 100%
rename from Documentation/this_cpu_ops.txt
rename to Documentation/core-api/this_cpu_ops.rst
Documentation/core-api/unaligned-memory-access.rst renamed from Documentation/unaligned-memory-access.txt +0 -0
similarity index 100%
rename from Documentation/unaligned-memory-access.txt
rename to Documentation/core-api/unaligned-memory-access.rst
Documentation/gpu/drm-mm.rst +1 -1
index 1839762044be..e0bbcbb6f512 100644
@@ -314,7 +314,7 @@ To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct
 a pointer on drm_gem_cma_get_unmapped_area().
 
 More detailed information about get_unmapped_area can be found in
-Documentation/nommu-mmap.txt
+Documentation/core-api/nommu-mmap.rst
 
 Memory Coherency
 ----------------
arch/Kconfig +1 -1
index 786a85d4ad40..b0b4046c9d13 100644
@@ -147,7 +147,7 @@ config HAVE_EFFICIENT_UNALIGNED_ACCESS
 	  problems with received packets if doing so would not help
 	  much.
 
-	  See Documentation/unaligned-memory-access.txt for more
+	  See Documentation/core-api/unaligned-memory-access.rst for more
 	  information on the topic of unaligned memory accesses.
 
 config ARCH_USE_BUILTIN_BSWAP
init/Kconfig +1 -1
index 492bb7000aa4..61ccfd9243e3 100644
@@ -1950,7 +1950,7 @@ config MMAP_ALLOW_UNINITIALIZED
 	  userspace.  Since that isn't generally a problem on no-MMU systems,
 	  it is normally safe to say Y here.
 
-	  See Documentation/nommu-mmap.txt for more information.
+	  See Documentation/core-api/nommu-mmap.rst for more information.
 
 config SYSTEM_DATA_VERIFICATION
 	def_bool n
mm/Kconfig +1 -1
index db626b8d4fdb..2a133c40a4b7 100644
@@ -382,7 +382,7 @@ config NOMMU_INITIAL_TRIM_EXCESS
 	  This option specifies the initial value of this option.  The default
 	  of 1 says that all excess pages should be trimmed.
 
-	  See Documentation/nommu-mmap.txt for more information.
+	  See Documentation/core-api/nommu-mmap.rst for more information.
 
 config TRANSPARENT_HUGEPAGE
 	bool "Transparent Hugepage Support"
mm/nommu.c +1 -1
index 371697bf372d..e3e707d6f124 100644
@@ -5,7 +5,7 @@
  *  Replacement code for mm functions to support CPU's that don't
  *  have any form of memory management unit (thus no virtual memory).
  *
- *  See Documentation/nommu-mmap.txt
+ *  See Documentation/core-api/nommu-mmap.rst
  *
  *  Copyright (c) 2004-2008 David Howells <[email protected]>
  *  Copyright (c) 2000-2003 David McCullough <[email protected]>
Signature · 6 lines
2.25.4

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#31 lore raw

Re: [PATCH 11/14] docs: move other kAPI documents to core-api

Hello Mauro,

Quoted 10 lines · Mauro Carvalho Chehab

There are a number of random documents that seem to be describing some aspects of the core-api. Move them to such directory, adding them at the core-api/index.rst file.

---
 Documentation/admin-guide/sysctl/vm.rst                     | 2 +-
 Documentation/core-api/index.rst                            | 6 ++++++
 Documentation/{mailbox.txt => core-api/mailbox.rst}         | 0
 Documentation/{nommu-mmap.txt => core-api/nommu-mmap.rst}   | 0

The nommu-mmap mostly provides description of user visible behaviuour. I think it's bettter to have it in admin-guide/mm/.

Quoted 143 lines
 .../{this_cpu_ops.txt => core-api/this_cpu_ops.rst}         | 0
 .../unaligned-memory-access.rst}                            | 0
 Documentation/gpu/drm-mm.rst                                | 2 +-
 arch/Kconfig                                                | 2 +-
 init/Kconfig                                                | 2 +-
 mm/Kconfig                                                  | 2 +-
 mm/nommu.c                                                  | 2 +-
 11 files changed, 12 insertions(+), 6 deletions(-)
 rename Documentation/{mailbox.txt => core-api/mailbox.rst} (100%)
 rename Documentation/{nommu-mmap.txt => core-api/nommu-mmap.rst} (100%)
 rename Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst} (100%)
 rename Documentation/{unaligned-memory-access.txt => core-api/unaligned-memory-access.rst} (100%)
Documentation/admin-guide/sysctl/vm.rst +1 -1
index 0329a4d3fa9e..0bf2f2a84a9f 100644
@@ -583,7 +583,7 @@ trimming of allocations is initiated.
 
 The default value is 1.
 
-See Documentation/nommu-mmap.txt for more information.
+See Documentation/core-api/nommu-mmap.rst for more information.
 
 
 numa_zonelist_order
Documentation/core-api/index.rst +6 -0
index eeac63ba17c3..fe03a639a91a 100644
@@ -38,10 +38,14 @@ Library functionality that is used throughout the kernel.
    circular-buffers
    rbtree
    generic-radix-tree
+   mailbox
    packing
+   rbtree
+   this_cpu_ops
    timekeeping
    errseq
 
+
 Concurrency primitives
 ======================
 
@@ -82,11 +86,13 @@ more memory-management documentation in :doc:`/vm/index`.
    :maxdepth: 1
 
    memory-allocation
+   unaligned-memory-access
    dma-api
    dma-api-howto
    dma-attributes
    dma-isa-lpc
    bus-virt-phys-mapping
+   nommu-mmap
    mm-api
    genalloc
    pin_user_pages
Documentation/core-api/mailbox.rst renamed from Documentation/mailbox.txt +0 -0
similarity index 100%
rename from Documentation/mailbox.txt
rename to Documentation/core-api/mailbox.rst
Documentation/core-api/nommu-mmap.rst renamed from Documentation/nommu-mmap.txt +0 -0
similarity index 100%
rename from Documentation/nommu-mmap.txt
rename to Documentation/core-api/nommu-mmap.rst
Documentation/core-api/this_cpu_ops.rst renamed from Documentation/this_cpu_ops.txt +0 -0
similarity index 100%
rename from Documentation/this_cpu_ops.txt
rename to Documentation/core-api/this_cpu_ops.rst
Documentation/core-api/unaligned-memory-access.rst renamed from Documentation/unaligned-memory-access.txt +0 -0
similarity index 100%
rename from Documentation/unaligned-memory-access.txt
rename to Documentation/core-api/unaligned-memory-access.rst
Documentation/gpu/drm-mm.rst +1 -1
index 1839762044be..e0bbcbb6f512 100644
@@ -314,7 +314,7 @@ To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct
 a pointer on drm_gem_cma_get_unmapped_area().
 
 More detailed information about get_unmapped_area can be found in
-Documentation/nommu-mmap.txt
+Documentation/core-api/nommu-mmap.rst
 
 Memory Coherency
 ----------------
arch/Kconfig +1 -1
index 786a85d4ad40..b0b4046c9d13 100644
@@ -147,7 +147,7 @@ config HAVE_EFFICIENT_UNALIGNED_ACCESS
 	  problems with received packets if doing so would not help
 	  much.
 
-	  See Documentation/unaligned-memory-access.txt for more
+	  See Documentation/core-api/unaligned-memory-access.rst for more
 	  information on the topic of unaligned memory accesses.
 
 config ARCH_USE_BUILTIN_BSWAP
init/Kconfig +1 -1
index 492bb7000aa4..61ccfd9243e3 100644
@@ -1950,7 +1950,7 @@ config MMAP_ALLOW_UNINITIALIZED
 	  userspace.  Since that isn't generally a problem on no-MMU systems,
 	  it is normally safe to say Y here.
 
-	  See Documentation/nommu-mmap.txt for more information.
+	  See Documentation/core-api/nommu-mmap.rst for more information.
 
 config SYSTEM_DATA_VERIFICATION
 	def_bool n
mm/Kconfig +1 -1
index db626b8d4fdb..2a133c40a4b7 100644
@@ -382,7 +382,7 @@ config NOMMU_INITIAL_TRIM_EXCESS
 	  This option specifies the initial value of this option.  The default
 	  of 1 says that all excess pages should be trimmed.
 
-	  See Documentation/nommu-mmap.txt for more information.
+	  See Documentation/core-api/nommu-mmap.rst for more information.
 
 config TRANSPARENT_HUGEPAGE
 	bool "Transparent Hugepage Support"
mm/nommu.c +1 -1
index 371697bf372d..e3e707d6f124 100644
@@ -5,7 +5,7 @@
  *  Replacement code for mm functions to support CPU's that don't
  *  have any form of memory management unit (thus no virtual memory).
  *
- *  See Documentation/nommu-mmap.txt
+ *  See Documentation/core-api/nommu-mmap.rst
  *
  *  Copyright (c) 2004-2008 David Howells <[email protected]>
  *  Copyright (c) 2000-2003 David McCullough <[email protected]>
Signature · 1 line
2.25.4
Signature · 2 lines
Sincerely yours,
Mike.
maintainer
#32 lore raw

Re: [PATCH 11/14] docs: move other kAPI documents to core-api

In reply to Mauro Carvalho Chehab
Quoted 14 lines · On Fri, 1 May 2020 17:37:55 +0200 Mauro Carvalho Chehab…

There are a number of random documents that seem to be describing some aspects of the core-api. Move them to such directory, adding them at the core-api/index.rst file.

---
 Documentation/admin-guide/sysctl/vm.rst                     | 2 +-
 Documentation/core-api/index.rst                            | 6 ++++++
 Documentation/{mailbox.txt => core-api/mailbox.rst}         | 0
 Documentation/{nommu-mmap.txt => core-api/nommu-mmap.rst}   | 0
 .../{this_cpu_ops.txt => core-api/this_cpu_ops.rst}         | 0
 .../unaligned-memory-access.rst}                            | 0
 Documentation/gpu/drm-mm.rst                                | 2 +-
 arch/Kconfig                                                | 2 +-
Quoted 8 lines
 init/Kconfig                                                | 2 +-
 mm/Kconfig                                                  | 2 +-
 mm/nommu.c                                                  | 2 +-
 11 files changed, 12 insertions(+), 6 deletions(-)
 rename Documentation/{mailbox.txt => core-api/mailbox.rst} (100%)
 rename Documentation/{nommu-mmap.txt => core-api/nommu-mmap.rst} (100%)
 rename Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst} (100%)
 rename Documentation/{unaligned-memory-access.txt => core-api/unaligned-memory-access.rst} (100%)

This one doesn't apply for me. Beyond that, I'm not entirely convinced about a couple of the moves...

- mailbox.txt seems like driver-api stuff to me?
- nommu-mmap.txt is mostly (though not completely) about the semantic of mmap() options as seen by user space, so perhaps belongs in that manual...?

Thanks,

jon

#33 lore raw

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

In reply to 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.

---
 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%)
Documentation/index.rst +13 -0
index af2b87afebc8..9a931e157db2 100644
@@ -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
 ------------
 
Documentation/staging/crc32.rst renamed from Documentation/crc32.txt +0 -0
similarity index 100%
rename from Documentation/crc32.txt
rename to Documentation/staging/crc32.rst
Documentation/staging/index.rst new file +32 -0
new file mode 100644
index 000000000000..8e98517675ca
@@ -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
Documentation/staging/kprobes.rst renamed from Documentation/kprobes.txt +0 -0
similarity index 100%
rename from Documentation/kprobes.txt
rename to Documentation/staging/kprobes.rst
Documentation/staging/lzo.rst renamed from Documentation/lzo.txt +0 -0
similarity index 100%
rename from Documentation/lzo.txt
rename to Documentation/staging/lzo.rst
Documentation/staging/remoteproc.rst renamed from Documentation/remoteproc.txt +1 -1
similarity index 99%
rename from Documentation/remoteproc.txt
rename to Documentation/staging/remoteproc.rst
index 2be1147256e0..9cccd3dd6a4b 100644
@@ -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
Documentation/staging/rpmsg.rst renamed from Documentation/rpmsg.txt +0 -0
similarity index 100%
rename from Documentation/rpmsg.txt
rename to Documentation/staging/rpmsg.rst
Documentation/staging/speculation.rst renamed from Documentation/speculation.txt +5 -3
similarity index 97%
rename from Documentation/speculation.txt
rename to Documentation/staging/speculation.rst
index 50d7ea857cff..8045d99bcf12 100644
@@ -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
Documentation/staging/static-keys.rst renamed from Documentation/static-keys.txt +0 -0
similarity index 100%
rename from Documentation/static-keys.txt
rename to Documentation/staging/static-keys.rst
Documentation/staging/tee.rst renamed from Documentation/tee.txt +1 -0
similarity index 99%
rename from Documentation/tee.txt
rename to Documentation/staging/tee.rst
index c8fad81c4563..324604a15d17 100644
@@ -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.
Documentation/staging/xz.rst renamed from Documentation/xz.txt +0 -0
similarity index 100%
rename from Documentation/xz.txt
rename to Documentation/staging/xz.rst
Documentation/trace/kprobetrace.rst +1 -1
index cc4c5fc313df..c1709165c553 100644
@@ -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
MAINTAINERS +5 -5
index 1aa6e89e7424..8aa8f7c0db93 100644
@@ -9494,7 +9494,7 @@ M:	Anil S Keshavamurthy <[email protected]>
 M:	"David S. Miller" <[email protected]>
 M:	Masami Hiramatsu <[email protected]>
 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:	[email protected]
 L:	[email protected]
 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:	[email protected]
 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 <[email protected]>
 L:	[email protected]
 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
include/asm-generic/bitops/atomic.h +1 -1
index dd90c9792909..edeeb8375006 100644
@@ -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)
include/linux/jump_label.h +1 -1
index 3526c0aee954..32809624d422 100644
@@ -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__
lib/crc32.c +1 -1
index 4a20455d1f61..35a03d03f973 100644
@@ -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>
lib/lzo/lzo1x_decompress_safe.c +1 -1
index 2717c7963acd..7892a40cf765 100644
@@ -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)
 
lib/xz/Kconfig +1 -1
index 22528743d4ce..5cb50245a878 100644
@@ -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
 
samples/kprobes/kprobe_example.c +1 -1
index d693c23a85e8..e53603de48b8 100644
@@ -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.
samples/kprobes/kretprobe_example.c +1 -1
index 186315ca88b3..3685df980011 100644
@@ -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
Signature · 1 line
2.25.4
maintainer Acked-by on v1 12/14
#34 lore raw

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

Quoted 7 lines · On Fri, 1 May 2020 17:37:56 +0200 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.

Hi Mauro,

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

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,

Quoted 330 lines
---
 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%)
Documentation/index.rst +13 -0
index af2b87afebc8..9a931e157db2 100644
@@ -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
 ------------
 
Documentation/staging/crc32.rst renamed from Documentation/crc32.txt +0 -0
similarity index 100%
rename from Documentation/crc32.txt
rename to Documentation/staging/crc32.rst
Documentation/staging/index.rst new file +32 -0
new file mode 100644
index 000000000000..8e98517675ca
@@ -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
Documentation/staging/kprobes.rst renamed from Documentation/kprobes.txt +0 -0
similarity index 100%
rename from Documentation/kprobes.txt
rename to Documentation/staging/kprobes.rst
Documentation/staging/lzo.rst renamed from Documentation/lzo.txt +0 -0
similarity index 100%
rename from Documentation/lzo.txt
rename to Documentation/staging/lzo.rst
Documentation/staging/remoteproc.rst renamed from Documentation/remoteproc.txt +1 -1
similarity index 99%
rename from Documentation/remoteproc.txt
rename to Documentation/staging/remoteproc.rst
index 2be1147256e0..9cccd3dd6a4b 100644
@@ -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
Documentation/staging/rpmsg.rst renamed from Documentation/rpmsg.txt +0 -0
similarity index 100%
rename from Documentation/rpmsg.txt
rename to Documentation/staging/rpmsg.rst
Documentation/staging/speculation.rst renamed from Documentation/speculation.txt +5 -3
similarity index 97%
rename from Documentation/speculation.txt
rename to Documentation/staging/speculation.rst
index 50d7ea857cff..8045d99bcf12 100644
@@ -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
Documentation/staging/static-keys.rst renamed from Documentation/static-keys.txt +0 -0
similarity index 100%
rename from Documentation/static-keys.txt
rename to Documentation/staging/static-keys.rst
Documentation/staging/tee.rst renamed from Documentation/tee.txt +1 -0
similarity index 99%
rename from Documentation/tee.txt
rename to Documentation/staging/tee.rst
index c8fad81c4563..324604a15d17 100644
@@ -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.
Documentation/staging/xz.rst renamed from Documentation/xz.txt +0 -0
similarity index 100%
rename from Documentation/xz.txt
rename to Documentation/staging/xz.rst
Documentation/trace/kprobetrace.rst +1 -1
index cc4c5fc313df..c1709165c553 100644
@@ -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
MAINTAINERS +5 -5
index 1aa6e89e7424..8aa8f7c0db93 100644
@@ -9494,7 +9494,7 @@ M:	Anil S Keshavamurthy <[email protected]>
 M:	"David S. Miller" <[email protected]>
 M:	Masami Hiramatsu <[email protected]>
 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:	[email protected]
 L:	[email protected]
 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:	[email protected]
 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 <[email protected]>
 L:	[email protected]
 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
include/asm-generic/bitops/atomic.h +1 -1
index dd90c9792909..edeeb8375006 100644
@@ -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)
include/linux/jump_label.h +1 -1
index 3526c0aee954..32809624d422 100644
@@ -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__
lib/crc32.c +1 -1
index 4a20455d1f61..35a03d03f973 100644
@@ -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>
lib/lzo/lzo1x_decompress_safe.c +1 -1
index 2717c7963acd..7892a40cf765 100644
@@ -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)
 
lib/xz/Kconfig +1 -1
index 22528743d4ce..5cb50245a878 100644
@@ -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
 
samples/kprobes/kprobe_example.c +1 -1
index d693c23a85e8..e53603de48b8 100644
@@ -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.
samples/kprobes/kretprobe_example.c +1 -1
index 186315ca88b3..3685df980011 100644
@@ -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
Signature · 1 line
2.25.4
Signature · 1 line
Masami Hiramatsu <[email protected]>
#35 lore raw

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

Quoted 2 lines · Masami Hiramatsu

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

[]

Quoted 1 line

MAINTAINERS

Quoted 1 line
MAINTAINERS +0 -0

[]

Quoted 6 lines

MAINTAINERS L: [email protected] · line 9858

Quoted 6 lines
MAINTAINERS +1 -1
@@ -9855,7 +9855,7 @@ L:	[email protected]
 L:	[email protected]
 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.

Quoted 3 lines
Quoted 3 lines
MAINTAINERS +0 -0
 F:	Documentation/atomic_t.txt
 F:	Documentation/core-api/atomic_ops.rst
 F:	Documentation/core-api/refcount-vs-atomic.rst
#36 lore raw

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

In reply to Masami Hiramatsu
Quoted 13 lines · Masami Hiramatsu
Quoted 7 lines · On Fri, 1 May 2020 17:37:56 +0200 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.

Hi Mauro,

Quoted 8 lines

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

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

#37 lore raw

PATCH 13/14 docs: staging: don't use literalinclude

In reply to Mauro Carvalho Chehab

Such directive cause troubles with PDF output.

---
 Documentation/staging/index.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
Documentation/staging/index.rst +6 -3
index 8e98517675ca..8cc9d94b0a13 100644
@@ -19,14 +19,17 @@ Unsorted Documentation
 Atomic Types
 ============
 
-.. literalinclude:: ../atomic_t.txt
+.. include:: ../atomic_t.txt
+   :literal:
 
 Atomic bitops
 =============
 
-.. literalinclude:: ../atomic_bitops.txt
+.. include:: ../atomic_bitops.txt
+   :literal:
 
 Memory Barriers
 ===============
 
-.. literalinclude:: ../memory-barriers.txt
+.. include:: ../memory-barriers.txt
+   :literal:
Signature · 1 line
2.25.4
#38 lore raw

PATCH 14/14 docs: staging: use small font for literal includes

In reply to Mauro Carvalho Chehab

The normal font is too big to display 80 columns, causing extra breaks to be added at weird places.

change to the footnotesize, as this would fit a little bit better.

---
 Documentation/staging/index.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
Documentation/staging/index.rst +24 -0
index 8cc9d94b0a13..184e6aece0a7 100644
@@ -19,17 +19,41 @@ Unsorted Documentation
 Atomic Types
 ============
 
+.. raw:: latex
+
+    \footnotesize
+
 .. include:: ../atomic_t.txt
    :literal:
 
+.. raw:: latex
+
+    \normalsize
+
 Atomic bitops
 =============
 
+.. raw:: latex
+
+    \footnotesize
+
 .. include:: ../atomic_bitops.txt
    :literal:
 
+.. raw:: latex
+
+    \normalsize
+
 Memory Barriers
 ===============
 
+.. raw:: latex
+
+    \footnotesize
+
 .. include:: ../memory-barriers.txt
    :literal:
+
+.. raw:: latex
+
+    \normalsize
Signature · 1 line
2.25.4
#39 lore raw

Re: [PATCH 14/14] docs: staging: use small font for literal includes

Quoted 5 lines · Mauro Carvalho Chehab

The normal font is too big to display 80 columns, causing extra breaks to be added at weird places.

change to the footnotesize, as this would fit a little bit better.

[]

Documentation/staging/index.rst

Quoted 1 line
Documentation/staging/index.rst +0 -0

[]

Documentation/staging/index.rst Unsorted Documentation · line 24

Quoted 7 lines
Documentation/staging/index.rst +3 -0
@@ -19,17 +19,41 @@ Unsorted Documentation
 Atomic Types
 ============
 
+.. raw:: latex
+
+    \footnotesize

Please don't make the markup too invasive.

Quoted 35 lines
Documentation/staging/index.rst +21 -0
+
 .. include:: ../atomic_t.txt
    :literal:
 
+.. raw:: latex
+
+    \normalsize
+
 Atomic bitops
 =============
 
+.. raw:: latex
+
+    \footnotesize
+
 .. include:: ../atomic_bitops.txt
    :literal:
 
+.. raw:: latex
+
+    \normalsize
+
 Memory Barriers
 ===============
 
+.. raw:: latex
+
+    \footnotesize
+
 .. include:: ../memory-barriers.txt
    :literal:
+
+.. raw:: latex
+
+    \normalsize
#40 lore raw

Re: [PATCH 14/14] docs: staging: use small font for literal includes

Em Fri, 01 May 2020 17:10:00 -0700
Joe Perches <[email protected]> escreveu:

Quoted 13 lines · Mauro Carvalho Chehab
Quoted 5 lines

The normal font is too big to display 80 columns, causing extra breaks to be added at weird places.

change to the footnotesize, as this would fit a little bit better.

[]

Documentation/staging/index.rst

Quoted 1 line
Documentation/staging/index.rst +0 -0

[]

Quoted 4 lines
Documentation/staging/index.rst +0 -0
@@ -19,17 +19,41 @@ Unsorted Documentation
 Atomic Types
 ============
 
Quoted 5 lines

Documentation/staging/index.rst Unsorted Documentation · line 24

Quoted 3 lines
Documentation/staging/index.rst +3 -0
+.. raw:: latex
+
+    \footnotesize  

Please don't make the markup too invasive.

With the current status, this is unavoidable.

The only way to avoid those would be to convert the document itself to ReST, but the document writer was not convinced yet to even minimal ReST markups on 3 files.

The problem with a text file is that the lines produced at the PDF output with a mono-spaced font, on LaTeX have lot less than 80 colums. So, some markups should tell Sphinx to use a reduced font for those includes.

However, there's no "fontsize" directive (nor any other directive that would allow adjusting font parameters on an included file) on Sphinx. So, we need to use the above.

Thanks,
Mauro

#41 lore raw
In reply to Mauro Carvalho Chehab

(CC to documentation, get_maintainer, and LKMM maintainers)

Hi Mauro,

As I didn't receive "[PATCH 12/14] docs: move remaining stuff under Documentation/*.txt to Documentation/staging", I'm replying to [PATCH 00/14].

Quoted 180 lines · Mauro Carvalho Chehab

The main goal of this series is to cleanup the Documentation/ directory.

Most of the files under Documentation/*.txt are already in ReST format. They just need to be moved to some place. So, most of the work here is to just move files for them to generate an output using the docs building system.

After this change, the Documentation/ dir will contain:

- the main ReST file:
- index.rst

- TUX and its copyright:
- logo.gif and COPYING-logo

- Files required to do ReST builds:
- .gitignore, Makefile, conf.py, docutils.conf, Kconfig

- A pre-git file used to generate patches:
- dontdiff
(I guess we should get rid of it, as I doubt this is useful those days).

-

Besides the above rightful files, the Documentation/ dir will also contain some left-overs:

- two somewhat new ReST files that should be moved to somewhere:
- asm-annotations.rst and watch_queue.rst

- Two files that helps people looking for some well known documents that are referenced at the web, pointing to their new location inside the process/ dir:
- SubmittingPatches and CodingStyle

- Three .txt files that weren't converted to ReST:
- atomic_bitops.txt, memory-barriers.txt, atomic_t.txt

It should be noticed that I'm in doubt about the location of some files, and some stuff may well belong to a trash can. So, this series create a temporary place for orphaned documents in the form of a Documentation/staging directory.

This series is also on my development git tree, at:

https://git.linuxtv.org/mchehab/experimental.git/log/?h=rename-main-docs

The built output documentation on html format is at:

https://www.infradead.org/~mchehab/kernel_docs/

(it contains also other documents I converted to ReST)

Mauro Carvalho Chehab (14):
docs: move DMA kAPI to Documentation/core-api
docs: add bus-virt-phys-mapping.txt to core-api
docs: fix references for DMA*.txt files
docs: move IPMI.txt to the driver API book
docs: fix references for ipmi.rst file
docs: debugging-via-ohci1394.txt: add it to the core-api book
docs: add IRQ documentation at the core-api book
docs: move kobject and kref docs into the core-api book
docs: move digsig docs to the security book
docs: move locking-specific documenta to locking/ directory
docs: move other kAPI documents to core-api
docs: move remaining stuff under Documentation/*.txt to
Documentation/staging
docs: staging: don't use literalinclude
docs: staging: use small font for literal includes

 Documentation/PCI/pci.rst                     |  6 +-
 Documentation/admin-guide/hw-vuln/l1tf.rst    |  2 +-
 .../admin-guide/kernel-parameters.txt         |  2 +-
 .../admin-guide/kernel-per-CPU-kthreads.rst   |  2 +-
 Documentation/admin-guide/sysctl/vm.rst       |  2 +-
 Documentation/block/biodoc.rst                |  2 +-
 .../bus-virt-phys-mapping.rst}                |  2 +-
 .../debugging-via-ohci1394.rst}               |  0
 .../dma-api-howto.rst}                        |  0
 .../{DMA-API.txt => core-api/dma-api.rst}     |  6 +-
 .../dma-attributes.rst}                       |  0
 .../dma-isa-lpc.rst}                          |  2 +-
 Documentation/core-api/index.rst              | 14 +++++
 .../{IRQ.txt => core-api/irq/concepts.rst}    |  0
 Documentation/core-api/irq/index.rst          | 11 ++++
 .../irq/irq-affinity.rst}                     |  0
 .../irq/irq-domain.rst}                       |  3 +-
 .../irq/irqflags-tracing.rst}                 |  0
 Documentation/core-api/kobject.rst            |  2 +-
 Documentation/{kref.txt => core-api/kref.rst} |  0
 .../{mailbox.txt => core-api/mailbox.rst}     |  0
 .../nommu-mmap.rst}                           |  0
 .../this_cpu_ops.rst}                         |  0
 .../unaligned-memory-access.rst}              |  0
 Documentation/driver-api/index.rst            |  1 +
 .../{IPMI.txt => driver-api/ipmi.rst}         |  0
 Documentation/driver-api/usb/dma.rst          |  6 +-
 Documentation/gpu/drm-mm.rst                  |  2 +-
 Documentation/ia64/irq-redir.rst              |  2 +-
 Documentation/index.rst                       | 13 ++++
 .../futex-requeue-pi.rst}                     |  0
 .../hwspinlock.rst}                           |  0
 Documentation/locking/index.rst               |  7 +++
 .../percpu-rw-semaphore.rst}                  |  0
 .../{pi-futex.txt => locking/pi-futex.rst}    |  0
 .../preempt-locking.rst}                      |  0
 .../robust-futex-ABI.rst}                     |  0
 .../robust-futexes.rst}                       |  0
 Documentation/locking/rt-mutex.rst            |  2 +-
 Documentation/memory-barriers.txt             |  6 +-
 Documentation/networking/scaling.rst          |  4 +-
 .../{digsig.txt => security/digsig.rst}       |  0
 Documentation/security/index.rst              |  1 +
 .../{crc32.txt => staging/crc32.rst}          |  0
 Documentation/staging/index.rst               | 59 +++++++++++++++++++
 .../{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 +-
 .../translations/ko_KR/memory-barriers.txt    |  6 +-
 Documentation/translations/zh_CN/IRQ.txt      |  4 +-
 MAINTAINERS                                   | 20 +++----
 arch/Kconfig                                  |  2 +-
 arch/ia64/hp/common/sba_iommu.c               | 12 ++--
 arch/parisc/kernel/pci-dma.c                  |  2 +-
 arch/x86/include/asm/dma-mapping.h            |  4 +-
 arch/x86/kernel/amd_gart_64.c                 |  2 +-
 drivers/char/ipmi/Kconfig                     |  2 +-
 drivers/char/ipmi/ipmi_si_hotmod.c            |  2 +-
 drivers/char/ipmi/ipmi_si_intf.c              |  2 +-
 drivers/parisc/sba_iommu.c                    | 14 ++---
 include/asm-generic/bitops/atomic.h           |  2 +-
 include/linux/dma-mapping.h                   |  2 +-
 include/linux/jump_label.h                    |  2 +-
 include/media/videobuf-dma-sg.h               |  2 +-
 init/Kconfig                                  |  2 +-
 kernel/dma/debug.c                            |  2 +-
 lib/Kconfig.debug                             |  2 +-
 lib/crc32.c                                   |  2 +-
 lib/lzo/lzo1x_decompress_safe.c               |  2 +-
 lib/xz/Kconfig                                |  2 +-
 mm/Kconfig                                    |  2 +-
 mm/nommu.c                                    |  2 +-
 samples/kprobes/kprobe_example.c              |  2 +-
 samples/kprobes/kretprobe_example.c           |  2 +-
 80 files changed, 191 insertions(+), 81 deletions(-)
 rename Documentation/{bus-virt-phys-mapping.txt => core-api/bus-virt-phys-mapping.rst} (99%)
 rename Documentation/{debugging-via-ohci1394.txt => core-api/debugging-via-ohci1394.rst} (100%)
 rename Documentation/{DMA-API-HOWTO.txt => core-api/dma-api-howto.rst} (100%)
 rename Documentation/{DMA-API.txt => core-api/dma-api.rst} (99%)
 rename Documentation/{DMA-attributes.txt => core-api/dma-attributes.rst} (100%)
 rename Documentation/{DMA-ISA-LPC.txt => core-api/dma-isa-lpc.rst} (98%)
 rename Documentation/{IRQ.txt => core-api/irq/concepts.rst} (100%)
 create mode 100644 Documentation/core-api/irq/index.rst
 rename Documentation/{IRQ-affinity.txt => core-api/irq/irq-affinity.rst} (100%)
 rename Documentation/{IRQ-domain.txt => core-api/irq/irq-domain.rst} (99%)
 rename Documentation/{irqflags-tracing.txt => core-api/irq/irqflags-tracing.rst} (100%)
 rename Documentation/{kref.txt => core-api/kref.rst} (100%)
 rename Documentation/{mailbox.txt => core-api/mailbox.rst} (100%)
 rename Documentation/{nommu-mmap.txt => core-api/nommu-mmap.rst} (100%)
 rename Documentation/{this_cpu_ops.txt => core-api/this_cpu_ops.rst} (100%)
 rename Documentation/{unaligned-memory-access.txt => core-api/unaligned-memory-access.rst} (100%)
 rename Documentation/{IPMI.txt => driver-api/ipmi.rst} (100%)
 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%)
 rename Documentation/{digsig.txt => security/digsig.rst} (100%)
 rename Documentation/{crc32.txt => staging/crc32.rst} (100%)
 create mode 100644 Documentation/staging/index.rst
Quoted 9 lines
 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 stat above shows you are not moving Documentation/atomic_bitops.txt in this series. However, PATCH 12/14 contains the following hunks:

Quoted 4 lines
MAINTAINERS +0 -0
index 1aa6e89e7424..8aa8f7c0db93 100644

[...]

Quoted 9 lines
MAINTAINERS +1 -1
@@ -9855,7 +9855,7 @@ L:	[email protected]
 L:	[email protected]
 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

[...]

include/asm-generic/bitops/atomic.h line 14

Quoted 13 lines
include/asm-generic/bitops/atomic.h +1 -1
index dd90c9792909..edeeb8375006 100644
@@ -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)

Please drop them.

Thanks, Akira

#42 lore raw

Em Mon, 4 May 2020 18:25:51 +0900
Akira Yokosawa <[email protected]> escreveu:

Quoted 40 lines

(CC to documentation, get_maintainer, and LKMM maintainers)

Hi Mauro,

As I didn't receive "[PATCH 12/14] docs: move remaining stuff under Documentation/*.txt to Documentation/staging", I'm replying to [PATCH 00/14].

diff stat above shows you are not moving Documentation/atomic_bitops.txt in this series. However, PATCH 12/14 contains the following hunks:

Quoted 4 lines
MAINTAINERS +0 -0
index 1aa6e89e7424..8aa8f7c0db93 100644

[...]

Quoted 9 lines
MAINTAINERS +1 -1
@@ -9855,7 +9855,7 @@ L:	[email protected]
 L:	[email protected]
 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  

[...]

Quoted 12 lines
include/asm-generic/bitops/atomic.h +1 -1
index dd90c9792909..edeeb8375006 100644
@@ -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.
  */
 
Quoted 3 lines

include/asm-generic/bitops/atomic.h line 14

Quoted 1 line
include/asm-generic/bitops/atomic.h +0 -0
 static inline void set_bit(unsigned int nr, volatile unsigned long *p)  

Please drop them.

Thanks for pointing! Yeah, I noticed that too from Joe's review. Already dropped locally. I'll post a new version without such change.

Thanks,
Mauro