Skip to contentSkip to conversation

Fix bad references to documentation files

PATCH In review Otto Sabart 3 participants 13 messages Jan 2, 2019 – Jan 4, 2019

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

cover Fix bad references to documentation files

This series of patches fixes multiple warnings
from $ make refcheckdocs output.

I am still not sure if it's good practise to send these changes in a series (because they touch multiple trees) or as a single commit because it is one "logical" change :).

I have no problem with squashing these commits (or some of them), just let me know.

Otto Sabart (8):
MAINTAINERS: fix bad file reference into Documentation
doc: filesystems: fix bad references to nonexistent ext4.rst file
doc: bindings: fix bad reference to ARM CPU bindings
doc: trace: fix reference to cpuidle documentation file
doc: gpio-mvebu: fix broken reference to cp110-system-controller0.txt file
doc: scsi: remove reference to tmscsim.txt file
doc: pinctrl: fix bad reference to pinctrl.txt file
doc: fix multiple broken references

 Documentation/admin-guide/kernel-parameters.txt             | 2 +-
 Documentation/cgroup-v1/blkio-controller.txt                | 6 ++----
 Documentation/devicetree/bindings/arm/cpu-capacity.txt      | 2 +-
 Documentation/devicetree/bindings/arm/idle-states.txt       | 2 +-
 Documentation/devicetree/bindings/arm/sp810.txt             | 2 +-
 Documentation/devicetree/bindings/arm/topology.txt          | 2 +-
 Documentation/devicetree/bindings/display/arm,pl11x.txt     | 2 +-
 Documentation/devicetree/bindings/gpio/gpio-mvebu.txt       | 2 --
 .../devicetree/bindings/interrupt-controller/arm,gic-v3.txt | 2 +-
 Documentation/filesystems/dax.txt                           | 2 +-
 Documentation/filesystems/ext2.txt                          | 2 +-
 Documentation/trace/coresight-cpu-debug.txt                 | 2 +-
 MAINTAINERS                                                 | 3 +--
 arch/arm64/kernel/kexec_image.c                             | 2 +-
 arch/x86/Kconfig                                            | 2 +-
 drivers/scsi/Kconfig                                        | 2 --
 include/linux/mfd/madera/pdata.h                            | 3 ++-
 mm/Kconfig                                                  | 2 +-
 18 files changed, 18 insertions(+), 24 deletions(-)
Signature · 1 line
2.17.2
#1 lore raw

PATCH 1/8 MAINTAINERS: fix bad file reference into Documentation

There is no samsung,exynos5250-trng.txt file in the documentation and I do not think it ever existed.

---
 MAINTAINERS | 1 -
 1 file changed, 1 deletion(-)
MAINTAINERS +0 -1
index 7ba42fbb2c4a..076288b9a133 100644
@@ -13251,7 +13251,6 @@ M:	Łukasz Stelmach <[email protected]>
 L:	[email protected]
 S:	Maintained
 F:	drivers/char/hw_random/exynos-trng.c
-F:	Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.txt
 
 SAMSUNG FRAMEBUFFER DRIVER
 M:	Jingoo Han <[email protected]>
Signature · 1 line
2.17.2
#2 lore raw

PATCH 2/8 doc: filesystems: fix bad references to nonexistent ext4.rst file

In reply to Otto Sabart

The ext4.rst file does not exist anymore. This patch changes all references to point to the whole ext4 directory.

Fixes d3091215921b ("docs: move ext4 administrative docs to admin-guide/")
---
 Documentation/filesystems/dax.txt  | 2 +-
 Documentation/filesystems/ext2.txt | 2 +-
 MAINTAINERS                        | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
Documentation/filesystems/dax.txt +1 -1
index bc393e0a22b8..6d2c0d340dea 100644
@@ -75,7 +75,7 @@ exposure of uninitialized data through mmap.
 
 These filesystems may be used for inspiration:
 - ext2: see Documentation/filesystems/ext2.txt
-- ext4: see Documentation/filesystems/ext4/ext4.rst
+- ext4: see Documentation/filesystems/ext4/
 - xfs:  see Documentation/filesystems/xfs.txt
 
 
Documentation/filesystems/ext2.txt +1 -1
index a45c9fc0747b..a19973a4dd1e 100644
@@ -358,7 +358,7 @@ and are copied into the filesystem.  If a transaction is incomplete at
 the time of the crash, then there is no guarantee of consistency for
 the blocks in that transaction so they are discarded (which means any
 filesystem changes they represent are also lost).
-Check Documentation/filesystems/ext4/ext4.rst if you want to read more about
+Check Documentation/filesystems/ext4/ if you want to read more about
 ext4 and journaling.
 
 References
MAINTAINERS +1 -1
index 076288b9a133..f6d7a69a9002 100644
@@ -5695,7 +5695,7 @@ W:	http://ext4.wiki.kernel.org
 Q:	http://patchwork.ozlabs.org/project/linux-ext4/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/tytso/ext4.git
 S:	Maintained
-F:	Documentation/filesystems/ext4/ext4.rst
+F:	Documentation/filesystems/ext4/
 F:	fs/ext4/
 
 Extended Verification Module (EVM)
Signature · 1 line
2.17.2
#3 lore raw

PATCH 3/8 doc: bindings: fix bad reference to ARM CPU bindings

In reply to Otto Sabart

The primecell.txt and cpus.txt files were converted into YAML. This patch updates old references with new ones.

Fixes d3c207eeb905 ("dt-bindings: arm: Convert primecell binding to json-schema")
Fixes 672951cbd1b7 ("dt-bindings: arm: Convert cpu binding to json-schema")
---
 Documentation/devicetree/bindings/arm/cpu-capacity.txt          | 2 +-
 Documentation/devicetree/bindings/arm/idle-states.txt           | 2 +-
 Documentation/devicetree/bindings/arm/sp810.txt                 | 2 +-
 Documentation/devicetree/bindings/arm/topology.txt              | 2 +-
 Documentation/devicetree/bindings/display/arm,pl11x.txt         | 2 +-
 .../devicetree/bindings/interrupt-controller/arm,gic-v3.txt     | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)
Documentation/devicetree/bindings/arm/cpu-capacity.txt +1 -1
index 84262cdb8d29..96fa46cb133c 100644
@@ -235,4 +235,4 @@ cpus {
 ===========================================
 
 [1] ARM Linux Kernel documentation - CPUs bindings
-    Documentation/devicetree/bindings/arm/cpus.txt
+    Documentation/devicetree/bindings/arm/cpus.yaml
Documentation/devicetree/bindings/arm/idle-states.txt +1 -1
index 8f0937db55c5..45730ba60af5 100644
@@ -684,7 +684,7 @@ cpus {
 ===========================================
 
 [1] ARM Linux Kernel documentation - CPUs bindings
-    Documentation/devicetree/bindings/arm/cpus.txt
+    Documentation/devicetree/bindings/arm/cpus.yaml
 
 [2] ARM Linux Kernel documentation - PSCI bindings
     Documentation/devicetree/bindings/arm/psci.txt
Documentation/devicetree/bindings/arm/sp810.txt +1 -1
index 1b2ab1ff5587..46652bf65147 100644
@@ -4,7 +4,7 @@ SP810 System Controller
 Required properties:
 
 - compatible:	standard compatible string for a Primecell peripheral,
-		see Documentation/devicetree/bindings/arm/primecell.txt
+		see Documentation/devicetree/bindings/arm/primecell.yaml
 		for more details
 		should be: "arm,sp810", "arm,primecell"
 
Documentation/devicetree/bindings/arm/topology.txt +1 -1
index de9eb0486630..b0d80c0fb265 100644
@@ -472,4 +472,4 @@ cpus {
 
 ===============================================================================
 [1] ARM Linux kernel documentation
-    Documentation/devicetree/bindings/arm/cpus.txt
+    Documentation/devicetree/bindings/arm/cpus.yaml
Documentation/devicetree/bindings/display/arm,pl11x.txt +1 -1
index ef89ab46b2c9..572fa2773ec4 100644
@@ -1,6 +1,6 @@
 * ARM PrimeCell Color LCD Controller PL110/PL111
 
-See also Documentation/devicetree/bindings/arm/primecell.txt
+See also Documentation/devicetree/bindings/arm/primecell.yaml
 
 Required properties:
 
Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt +1 -1
index b83bb8249074..a3be5298a5eb 100644
@@ -78,7 +78,7 @@ Sub-nodes:
 PPI affinity can be expressed as a single "ppi-partitions" node,
 containing a set of sub-nodes, each with the following property:
 - affinity: Should be a list of phandles to CPU nodes (as described in
-Documentation/devicetree/bindings/arm/cpus.txt).
+  Documentation/devicetree/bindings/arm/cpus.yaml).
 
 GICv3 has one or more Interrupt Translation Services (ITS) that are
 used to route Message Signalled Interrupts (MSI) to the CPUs.
Signature · 1 line
2.17.2
#7 lore raw

PATCH 4/8 doc: trace: fix reference to cpuidle documentation file

In reply to Otto Sabart

Old cpuidle/sysfs.txt file was replaced in aa5eee355b46. So, refer to an updated file.

Fixes aa5eee355b46 ("Documentation: admin-guide: PM: Add cpuidle document")
---
 Documentation/trace/coresight-cpu-debug.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/trace/coresight-cpu-debug.txt +1 -1
index 89ab09e78e8d..f07e38094b40 100644
@@ -165,7 +165,7 @@ Do some work...
 The same can also be done from an application program.
 
 Disable specific CPU's specific idle state from cpuidle sysfs (see
-Documentation/cpuidle/sysfs.txt):
+Documentation/admin-guide/pm/cpuidle.rst):
 # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
 
 
Signature · 1 line
2.17.2
#8 lore raw

PATCH 5/8 doc: gpio-mvebu: fix broken reference to cp110-system-controller0.txt file

In reply to Otto Sabart

The cp110-system-controller0.txt file was renamed to cp110-system-controller.txt.

Fixes 4aa5496980e4 ("dt-bindings: cp110: rename cp110 syscon file")
---
 Documentation/devicetree/bindings/gpio/gpio-mvebu.txt | 2 --
 1 file changed, 2 deletions(-)
Documentation/devicetree/bindings/gpio/gpio-mvebu.txt +0 -2
index 38ca2201e8ae..2e097b57f170 100644
@@ -14,8 +14,6 @@ Required properties:
 
     "marvell,armada-8k-gpio" should be used for the Armada 7K and 8K
     SoCs (either from AP or CP), see
-    Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt
-    and
     Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt
     for specific details about the offset property.
 
Signature · 1 line
2.17.2
#9 lore raw

PATCH 6/8 doc: scsi: remove reference to tmscsim.txt file

In reply to Otto Sabart

The tmscsim.txt doc file was removed in c121107d0f84.

Fixes c121107d0f84 ("scsi: documentation: Obsolete documentation references")
---
 drivers/scsi/Kconfig | 2 --
 1 file changed, 2 deletions(-)
drivers/scsi/Kconfig +0 -2
index f38882f6f37d..6cbc391689ad 100644
@@ -1196,8 +1196,6 @@ config SCSI_AM53C974
 	  PCscsi/PCnet (Am53/79C974) solutions.
 	  This is a new implementation base on the generic esp_scsi driver.
 
-	  Documentation can be found in <file:Documentation/scsi/tmscsim.txt>.
-
 	  Note that this driver does NOT support Tekram DC390W/U/F, which are
 	  based on NCR/Symbios chips. Use "NCR53C8XX SCSI support" for those.
 
Signature · 1 line
2.17.2
#10 lore raw

PATCH 7/8 doc: pinctrl: fix bad reference to pinctrl.txt file

In reply to Otto Sabart

The pinctrl.txt file was converted into reStructuredText and moved into driver-api folder. This patch updates the broken reference.

Fixes 5a9b73832e9e ("pinctrl.txt: move it to the driver-api book")
---
 include/linux/mfd/madera/pdata.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
include/linux/mfd/madera/pdata.h +2 -1
index 8dc852402dbb..dd00ab824e5b 100644
@@ -34,7 +34,8 @@ struct madera_codec_pdata;
  * @micvdd:	    Substruct of pdata for the MICVDD regulator
  * @irq_flags:	    Mode for primary IRQ (defaults to active low)
  * @gpio_base:	    Base GPIO number
- * @gpio_configs:   Array of GPIO configurations (See Documentation/pinctrl.txt)
+ * @gpio_configs:   Array of GPIO configurations (See
+ *		    Documentation/driver-api/pinctl.rst)
  * @n_gpio_configs: Number of entries in gpio_configs
  * @gpsw:	    General purpose switch mode setting. Depends on the external
  *		    hardware connected to the switch. (See the SW1_MODE field
Signature · 1 line
2.17.2
#11 lore raw

PATCH 8/8 doc: fix multiple broken references

In reply to Otto Sabart

Some files were moved/converted into reStructuredRext/YAML, some were removed completely. This patch fixes broken references mainly in Documentation tree. There were also broken refs in Kconfigs and one in arch tree.

---
 Documentation/admin-guide/kernel-parameters.txt | 2 +-
 Documentation/cgroup-v1/blkio-controller.txt    | 6 ++----
 arch/arm64/kernel/kexec_image.c                 | 2 +-
 arch/x86/Kconfig                                | 2 +-
 mm/Kconfig                                      | 2 +-
 5 files changed, 6 insertions(+), 8 deletions(-)
Documentation/admin-guide/kernel-parameters.txt +1 -1
index 408781ee142c..1d7624f1d2ac 100644
@@ -2372,7 +2372,7 @@
 			set according to the
 			CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel config
 			option.
-			See Documentation/memory-hotplug.txt.
+			See Documentation/admin-guide/mm/memory-hotplug.rst.
 
 	memmap=exactmap	[KNL,X86] Enable setting of an exact
 			E820 memory map, as specified by the user.
Documentation/cgroup-v1/blkio-controller.txt +2 -4
index 673dc34d3f78..a99fefff9cb9 100644
@@ -108,8 +108,7 @@ If somebody created a hierarchy like as follows.
 		     test3
 
 CFQ by default and throttling with "sane_behavior" will handle the
-hierarchy correctly.  For details on CFQ hierarchy support, refer to
-Documentation/block/cfq-iosched.txt.  For throttling, all limits apply
+hierarchy correctly.  For throttling, all limits apply
 to the whole subtree while all statistics are local to the IOs
 directly generated by tasks in that cgroup.
 
@@ -177,8 +176,7 @@ Proportional weight policy files
 - blkio.leaf_weight[_device]
 	- Equivalents of blkio.weight[_device] for the purpose of
           deciding how much weight tasks in the given cgroup has while
-          competing with the cgroup's child cgroups. For details,
-          please refer to Documentation/block/cfq-iosched.txt.
+          competing with the cgroup's child cgroups.
 
 - blkio.time
 	- disk time allocated to cgroup per device in milliseconds. First
arch/arm64/kernel/kexec_image.c +1 -1
index 07bf740bea91..31cc2f423aa8 100644
@@ -53,7 +53,7 @@ static void *image_load(struct kimage *image,
 
 	/*
 	 * We require a kernel with an unambiguous Image header. Per
-	 * Documentation/booting.txt, this is the case when image_size
+	 * Documentation/arm64/booting.txt, this is the case when image_size
 	 * is non-zero (practically speaking, since v3.17).
 	 */
 	h = (struct arm64_image_header *)kernel;
arch/x86/Kconfig +1 -1
index e260460210e1..8d1e85c01916 100644
@@ -1635,7 +1635,7 @@ config ARCH_MEMORY_PROBE
 	depends on X86_64 && MEMORY_HOTPLUG
 	help
 	  This option enables a sysfs memory/probe interface for testing.
-	  See Documentation/memory-hotplug.txt for more information.
+	  See Documentation/admin-guide/mm/memory-hotplug.rst for more information.
 	  If you are unsure how to answer this question, answer N.
 
 config ARCH_PROC_KCORE_TEXT
mm/Kconfig +1 -1
index 25c71eb8a7db..410e28224d45 100644
@@ -168,7 +168,7 @@ config MEMORY_HOTPLUG_DEFAULT_ONLINE
 	  onlining policy (/sys/devices/system/memory/auto_online_blocks) which
 	  determines what happens to newly added memory regions. Policy setting
 	  can always be changed at runtime.
-	  See Documentation/memory-hotplug.txt for more information.
+	  See Documentation/admin-guide/mm/memory-hotplug.rst for more information.
 
 	  Say Y here if you want all hot-plugged memory blocks to appear in
 	  'online' state by default.
Signature · 1 line
2.17.2
maintainer
#12 lore raw
In reply to Otto Sabart
Quoted 6 lines · On Wed, 2 Jan 2019 21:00:47 +0100 Otto Sabart <[email protected]> wrote:

This series of patches fixes multiple warnings
from $ make refcheckdocs output.

I am still not sure if it's good practise to send these changes in a series (because they touch multiple trees) or as a single commit because it is one "logical" change :).

Definitely not as a single commit for something like this.

It's a good practice to use the get_maintainer.pl script to figure out who should receive any given patch. In particular, the various device-tree patches should go to the device-tree maintainers, the SCSI one to the SCSI list, etc.

I'll go ahead and apply patch 2 (the ext4 one) since it's a pure docs fix. For the rest, I'd suggest doing multiple mailings, being sure to get them to the right maintainers.

Thanks,

jon

#4 lore raw

Re: [PATCH 3/8] doc: bindings: fix bad reference to ARM CPU bindings

In reply to Otto Sabart
Quoted 4 lines · Otto Sabart

The primecell.txt and cpus.txt files were converted into YAML. This patch updates old references with new ones.

Quoted 8 lines
Fixes d3c207eeb905 ("dt-bindings: arm: Convert primecell binding to json-schema")
Fixes 672951cbd1b7 ("dt-bindings: arm: Convert cpu binding to json-schema")

---

As suggested by Jon Corbet, I am *resending* this patch once again to correct maintainers. There are no changes in the code since my previous e-mail.

Please use scripts/get_maintainers.pl so you get the right lists too.

Quoted 2 lines

Please review.

Am I supposed to apply? I don't have a clue because I've only gotten patch 3.

Quoted 8 lines
 Documentation/devicetree/bindings/arm/cpu-capacity.txt          | 2 +-
 Documentation/devicetree/bindings/arm/idle-states.txt           | 2 +-
 Documentation/devicetree/bindings/arm/sp810.txt                 | 2 +-
 Documentation/devicetree/bindings/arm/topology.txt              | 2 +-
 Documentation/devicetree/bindings/display/arm,pl11x.txt         | 2 +-
 .../devicetree/bindings/interrupt-controller/arm,gic-v3.txt     | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)
#5 lore raw

Re: [PATCH 3/8] doc: bindings: fix bad reference to ARM CPU bindings

Quoted 14 lines · Rob Herring
Quoted 4 lines · Otto Sabart

The primecell.txt and cpus.txt files were converted into YAML. This patch updates old references with new ones.

Quoted 8 lines
Fixes d3c207eeb905 ("dt-bindings: arm: Convert primecell binding to json-schema")
Fixes 672951cbd1b7 ("dt-bindings: arm: Convert cpu binding to json-schema")

---

As suggested by Jon Corbet, I am *resending* this patch once again to correct maintainers. There are no changes in the code since my previous e-mail.

Quoted 7 lines

Please use scripts/get_maintainers.pl so you get the right lists too.

Quoted 2 lines

Please review.

Am I supposed to apply? I don't have a clue because I've only gotten patch 3.

Hello Rob,
the thing is I messed up and I sent this series of patches to Jon and linux-doc list only.

Unfortunately these patches touch multiple subsystems so I now have to get them to correct maintainers.

What is the best thing I should do now? Should I resend (with "RESEND PATCH" prefix in subject) *whole* series of patches to right maintainers and lists returned by get_maintainer.pl?

In my case this scripts returns ~60 names and lists. I suppose it is not the right thing to spam all of them... or is it?

Thank you for your time.

Ota

#6 lore raw

Re: [PATCH 3/8] doc: bindings: fix bad reference to ARM CPU bindings

Quoted 31 lines · Otto Sabart
Quoted 14 lines · Rob Herring
Quoted 4 lines · Otto Sabart

The primecell.txt and cpus.txt files were converted into YAML. This patch updates old references with new ones.

Quoted 8 lines
Fixes d3c207eeb905 ("dt-bindings: arm: Convert primecell binding to json-schema")
Fixes 672951cbd1b7 ("dt-bindings: arm: Convert cpu binding to json-schema")

---

As suggested by Jon Corbet, I am *resending* this patch once again to correct maintainers. There are no changes in the code since my previous e-mail.

Quoted 7 lines

Please use scripts/get_maintainers.pl so you get the right lists too.

Quoted 2 lines

Please review.

Am I supposed to apply? I don't have a clue because I've only gotten patch 3.

Hello Rob,
the thing is I messed up and I sent this series of patches to Jon and linux-doc list only.

Unfortunately these patches touch multiple subsystems so I now have to get them to correct maintainers.

Quoted 6 lines

What is the best thing I should do now? Should I resend (with "RESEND PATCH" prefix in subject) *whole* series of patches to right maintainers and lists returned by get_maintainer.pl?

In my case this scripts returns ~60 names and lists. I suppose it is not the right thing to spam all of them... or is it?

That's probably because you're including commit signers which normally you shouldn't (use --nogit-fallback). Typically, you would only add commit signers if they are the author of what you are fixing (but that is me in this case). If you get multiple maintainers of different subsystems, then that's often a sign that a patch should be split up (though there are exceptions).

Also, if there's not any inter-dependency between the patches, then they don't need to be in a series. If a single maintainer should apply the patches, then they can be in a series. To put it another way, send a series per maintainer whenever possible.

Rob