Skip to contentSkip to conversation

docs: fix documentation build parsing errors

PATCH Applied Mauro Carvalho Chehab 4 participants 37 messages Sep 9, 2020 – Sep 11, 2020

Subsystems (34)
lore
Share & tools
lore
#10 lore raw

PATCH 8/30 docs: fix location of nommu-mmap.rst file

In reply to Mauro Carvalho Chehab

mm/nommu-mmap.rst -> admin-guide/mm/ nommu-mmap.rst

Fixes 800c02f5d030 ("docs: move nommu-mmap.txt to admin-guide and rename to ReST")
---
 init/Kconfig | 2 +-
 mm/Kconfig   | 2 +-
 mm/nommu.c   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
init/Kconfig +1 -1
index 91456ac0ef20..c9446911cf41 100644
@@ -1990,7 +1990,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/mm/nommu-mmap.rst for more information.
+	  See Documentation/admin-guide/mm/nommu-mmap.rst for more information.
 
 config SYSTEM_DATA_VERIFICATION
 	def_bool n
mm/Kconfig +1 -1
index 7d56281ff41e..c7f30f8b282b 100644
@@ -383,7 +383,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/mm/nommu-mmap.rst for more information.
+	  See Documentation/admin-guide/mm/nommu-mmap.rst for more information.
 
 config TRANSPARENT_HUGEPAGE
 	bool "Transparent Hugepage Support"
mm/nommu.c +1 -1
index 75a327149af1..0df7ca321314 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/mm/nommu-mmap.rst
+ *  See Documentation/admin-guide/mm/nommu-mmap.rst
  *
  *  Copyright (c) 2004-2008 David Howells <[email protected]>
  *  Copyright (c) 2000-2003 David McCullough <[email protected]>
Signature · 1 line
2.26.2
#16 lore raw

PATCH 14/30 docs: add some new files to their respective index.rst files

In reply to Mauro Carvalho Chehab

There were some new file additions for Kernel 5.7 and 5.8 that weren't added at the corresponding index file.

---
 Documentation/driver-api/nvdimm/index.rst   | 1 +
 Documentation/firmware-guide/acpi/index.rst | 1 +
 Documentation/hwmon/index.rst               | 1 +
 Documentation/vm/index.rst                  | 1 +
 4 files changed, 4 insertions(+)
Documentation/driver-api/nvdimm/index.rst +1 -0
index a4f8f98aeb94..5863bd04f056 100644
@@ -10,3 +10,4 @@ Non-Volatile Memory Device (NVDIMM)
    nvdimm
    btt
    security
+   firmware-activate
Documentation/firmware-guide/acpi/index.rst +1 -0
index ad3b5afdae77..f72b5f1769fb 100644
@@ -26,3 +26,4 @@ ACPI Support
    lpit
    video_extension
    extcon-intel-int3496
+   intel-pmc-mux
Documentation/hwmon/index.rst +1 -0
index af064a9ad42f..a926f1abaec3 100644
@@ -159,6 +159,7 @@ Hardware Monitoring Kernel Drivers
    smsc47b397
    smsc47m192
    smsc47m1
+   sparx5-temp
    tc654
    tc74
    thmc50
Documentation/vm/index.rst +1 -0
index 611140ffef7e..eff5fbd492d0 100644
@@ -29,6 +29,7 @@ descriptions of data structures and algorithms.
    :maxdepth: 1
 
    active_mm
+   arch_pgtable_helpers
    balance
    cleancache
    free_page_reporting
Signature · 1 line
2.26.2
#5 lore raw

PATCH 4/30 docs: hwmon: adm1266.rst: fix a broken reference

In reply to Mauro Carvalho Chehab

The reference was missing the extension, causing the check script to complain.

---
 Documentation/hwmon/adm1266.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/hwmon/adm1266.rst +1 -1
index 9257f8a48650..2b877011cfdf 100644
@@ -20,7 +20,7 @@ ADM1266 is a sequencer that features voltage readback from 17 channels via an
 integrated 12 bit SAR ADC, accessed using a PMBus interface.
 
 The driver is a client driver to the core PMBus driver. Please see
-Documentation/hwmon/pmbus for details on PMBus client drivers.
+Documentation/hwmon/pmbus.rst for details on PMBus client drivers.
 
 
 Sysfs entries
Signature · 1 line
2.26.2
#9 lore raw

PATCH 7/30 MAINTAINERS: fix location of qlogic/LICENSE.qla3xxx

In reply to Mauro Carvalho Chehab

ethernet/qlogic/LICENSE.qla3xxx -> qlogic/LICENSE.qla3xxx

---
 MAINTAINERS | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
MAINTAINERS +1 -1
index f3fee4140272..f9d044b6aa42 100644
@@ -14322,7 +14322,7 @@ QLOGIC QLA3XXX NETWORK DRIVER
 M:	[email protected]
 L:	[email protected]
 S:	Supported
-F:	Documentation/networking/device_drivers/ethernet/qlogic/LICENSE.qla3xxx
+F:	Documentation/networking/device_drivers/qlogic/LICENSE.qla3xxx
 F:	drivers/net/ethernet/qlogic/qla3xxx.*
 
 QLOGIC QLA4XXX iSCSI DRIVER
Signature · 1 line
2.26.2
#14 lore raw

PATCH 12/30 scripts: device_attr_show.cocci: update location of sysfs doc

In reply to Mauro Carvalho Chehab

sysfs.txt was converted and renamed to sysfs.rst.

Update device_attr_show.cocci script accordingly.

---
 scripts/coccinelle/api/device_attr_show.cocci | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
scripts/coccinelle/api/device_attr_show.cocci +1 -1
index d8ec4bb8ac41..a28dc061653a 100644
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: GPL-2.0-only
 ///
-/// From Documentation/filesystems/sysfs.txt:
+/// From Documentation/filesystems/sysfs.rst:
 ///  show() must not use snprintf() when formatting the value to be
 ///  returned to user space. If you can guarantee that an overflow
 ///  will never happen you can use sprintf() otherwise you must use
Signature · 1 line
2.26.2
#8 lore raw

PATCH 6/30 docs: trace: fix the location of kprobes.rst

In reply to Mauro Carvalho Chehab

This patch was moved out of staging.

Fixes 2165b82fde82 ("docs: Move kprobes.rst from staging/ to trace/")
---
 Documentation/trace/kprobetrace.rst | 2 +-
 samples/kprobes/kprobe_example.c    | 2 +-
 samples/kprobes/kretprobe_example.c | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
Documentation/trace/kprobetrace.rst +1 -1
index c1709165c553..10850a9e9af3 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/staging/kprobes.rst section 1.3.1.
+		  as defined in Documentation/trace/kprobes.rst section 1.3.1.
 
  FETCHARGS	: Arguments. Each probe can have up to 128 args.
   %REG		: Fetch register REG
samples/kprobes/kprobe_example.c +1 -1
index a02f53836ee1..365905cb24b1 100644
@@ -5,7 +5,7 @@
  * stack trace and selected registers when kernel_clone() is called.
  *
  * For more information on theory of operation of kprobes, see
- * Documentation/staging/kprobes.rst
+ * Documentation/trace/kprobes.rst
  *
  * You will see the trace data in /var/log/messages and on the console
  * whenever kernel_clone() is invoked to create a new process.
samples/kprobes/kretprobe_example.c +1 -1
index 0c40f7236989..5dc1bf3baa98 100644
@@ -11,7 +11,7 @@
  * If no func_name is specified, kernel_clone is instrumented
  *
  * For more information on theory of operation of kretprobes, see
- * Documentation/staging/kprobes.rst
+ * Documentation/trace/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.26.2
#31 lore raw

PATCH 27/30 docs: bio: fix a kerneldoc markup

In reply to Mauro Carvalho Chehab

Fix this warning:

./block/bio.c:1098: WARNING: Inline emphasis start-string without end-string.

The thing is that *iter is not a valid markup.

That seems to be a typo:

	*iter -> @iter
---
 block/bio.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
block/bio.c +1 -1
index ccd3ab549d41..ce9446a7b081 100644
@@ -1093,7 +1093,7 @@ static int __bio_iov_append_get_pages(struct bio *bio, struct iov_iter *iter)
  * released.
  *
  * The function tries, but does not guarantee, to pin as many pages as
- * fit into the bio, or are requested in *iter, whatever is smaller. If
+ * fit into the bio, or are requested in @iter, whatever is smaller. If
  * MM encounters an error pinning the requested pages, it stops. Error
  * is returned only if 0 pages could be pinned.
  */
Signature · 1 line
2.26.2
#26 lore raw

PATCH 24/30 docs: lockdep-design: fix some warning issues

In reply to Mauro Carvalho Chehab

There are several warnings caused by a recent change
224ec489d3cd ("lockdep/Documention: Recursive read lock detection reasoning")

Those are reported by htmldocs build:

Documentation/locking/lockdep-design.rst:429: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/locking/lockdep-design.rst:452: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/locking/lockdep-design.rst:453: WARNING: Unexpected indentation. Documentation/locking/lockdep-design.rst:453: WARNING: Blank line required after table. Documentation/locking/lockdep-design.rst:454: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/locking/lockdep-design.rst:455: WARNING: Unexpected indentation. Documentation/locking/lockdep-design.rst:455: WARNING: Blank line required after table. Documentation/locking/lockdep-design.rst:456: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/locking/lockdep-design.rst:457: WARNING: Unexpected indentation. Documentation/locking/lockdep-design.rst:457: WARNING: Blank line required after table.

Besides the reported issues, there are some missing blank lines that ended producing wrong html output, and some literals are not properly identified.

Also, the symbols used at the irq enabled/disable table are not displayed as expected, as they're not literals. Also, on another table they're using a different notation.

Fixes 224ec489d3cd ("lockdep/Documention: Recursive read lock detection reasoning")
---
 Documentation/locking/lockdep-design.rst | 69 ++++++++++++++----------
 1 file changed, 40 insertions(+), 29 deletions(-)
Documentation/locking/lockdep-design.rst +40 -29
index cec03bd1294a..7ac0c5092c21 100644
@@ -42,6 +42,7 @@ The validator tracks lock-class usage history and divides the usage into
 (4 usages * n STATEs + 1) categories:
 
 where the 4 usages can be:
+
 - 'ever held in STATE context'
 - 'ever held as readlock in STATE context'
 - 'ever held with STATE enabled'
@@ -49,10 +50,12 @@ where the 4 usages can be:
 
 where the n STATEs are coded in kernel/locking/lockdep_states.h and as of
 now they include:
+
 - hardirq
 - softirq
 
 where the last 1 category is:
+
 - 'ever used'                                       [ == !unused        ]
 
 When locking rules are violated, these usage bits are presented in the
@@ -71,12 +74,12 @@ of the lock and readlock (if exists), for each of the n STATEs listed
 above respectively, and the character displayed at each bit position
 indicates:
 
-   ===  ===================================================
-   '.'  acquired while irqs disabled and not in irq context
-   '-'  acquired in irq context
-   '+'  acquired with irqs enabled
-   '?'  acquired in irq context with irqs enabled.
-   ===  ===================================================
+   =====  ===================================================
+   ``.``  acquired while irqs disabled and not in irq context
+   ``-``  acquired in irq context
+   ``+``  acquired with irqs enabled
+   ``?``  acquired in irq context with irqs enabled.
+   =====  ===================================================
 
 The bits are illustrated with an example::
 
@@ -96,14 +99,14 @@ exact case is for the lock as of the reporting time.
   +--------------+-------------+--------------+
   |              | irq enabled | irq disabled |
   +--------------+-------------+--------------+
-  | ever in irq  |      ?      |       -      |
+  | ever in irq  |    ``?``    |     ``-``    |
   +--------------+-------------+--------------+
-  | never in irq |      +      |       .      |
+  | never in irq |    ``+``    |     ``.``    |
   +--------------+-------------+--------------+
 
-The character '-' suggests irq is disabled because if otherwise the
-charactor '?' would have been shown instead. Similar deduction can be
-applied for '+' too.
+The character ``-`` suggests irq is disabled because if otherwise the
+charactor ``?`` would have been shown instead. Similar deduction can be
+applied for ``+`` too.
 
 Unused locks (e.g., mutexes) cannot be part of the cause of an error.
 
@@ -216,7 +219,7 @@ looks like this::
        BD_MUTEX_PARTITION
   };
 
-mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+  mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
 
 In this case the locking is done on a bdev object that is known to be a
 partition.
@@ -334,7 +337,7 @@ Troubleshooting:
 ----------------
 
 The validator tracks a maximum of MAX_LOCKDEP_KEYS number of lock classes.
-Exceeding this number will trigger the following lockdep warning:
+Exceeding this number will trigger the following lockdep warning::
 
 	(DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS))
 
@@ -420,7 +423,8 @@ the critical section of another reader of the same lock instance.
 
 The difference between recursive readers and non-recursive readers is because:
 recursive readers get blocked only by a write lock *holder*, while non-recursive
-readers could get blocked by a write lock *waiter*. Considering the follow example:
+readers could get blocked by a write lock *waiter*. Considering the follow
+example::
 
 	TASK A:			TASK B:
 
@@ -448,20 +452,22 @@ There are simply four block conditions:
 
 Block condition matrix, Y means the row blocks the column, and N means otherwise.
 
-	    | E | r | R |
 	+---+---+---+---+
-	  E | Y | Y | Y |
+	|   | E | r | R |
 	+---+---+---+---+
-	  r | Y | Y | N |
+	| E | Y | Y | Y |
+	+---+---+---+---+
+	| r | Y | Y | N |
+	+---+---+---+---+
+	| R | Y | Y | N |
 	+---+---+---+---+
-	  R | Y | Y | N |
 
 	(W: writers, r: non-recursive readers, R: recursive readers)
 
 
 acquired recursively. Unlike non-recursive read locks, recursive read locks
 only get blocked by current write lock *holders* other than write lock
-*waiters*, for example:
+*waiters*, for example::
 
 	TASK A:			TASK B:
 
@@ -491,7 +497,7 @@ Recursive locks don't block each other, while non-recursive locks do (this is
 even true for two non-recursive read locks). A non-recursive lock can block the
 corresponding recursive lock, and vice versa.
 
-A deadlock case with recursive locks involved is as follow:
+A deadlock case with recursive locks involved is as follow::
 
 	TASK A:			TASK B:
 
@@ -510,7 +516,7 @@ because there are 3 types for lockers, there are, in theory, 9 types of lock
 dependencies, but we can show that 4 types of lock dependencies are enough for
 deadlock detection.
 
-For each lock dependency:
+For each lock dependency::
 
 	L1 -> L2
 
@@ -525,20 +531,25 @@ same types).
 With the above combination for simplification, there are 4 types of dependency edges
 in the lockdep graph:
 
-1) -(ER)->: exclusive writer to recursive reader dependency, "X -(ER)-> Y" means
+1) -(ER)->:
+	    exclusive writer to recursive reader dependency, "X -(ER)-> Y" means
 	    X -> Y and X is a writer and Y is a recursive reader.
 
-2) -(EN)->: exclusive writer to non-recursive locker dependency, "X -(EN)-> Y" means
+2) -(EN)->:
+	    exclusive writer to non-recursive locker dependency, "X -(EN)-> Y" means
 	    X -> Y and X is a writer and Y is either a writer or non-recursive reader.
 
-3) -(SR)->: shared reader to recursive reader dependency, "X -(SR)-> Y" means
+3) -(SR)->:
+	    shared reader to recursive reader dependency, "X -(SR)-> Y" means
 	    X -> Y and X is a reader (recursive or not) and Y is a recursive reader.
 
-4) -(SN)->: shared reader to non-recursive locker dependency, "X -(SN)-> Y" means
+4) -(SN)->:
+	    shared reader to non-recursive locker dependency, "X -(SN)-> Y" means
 	    X -> Y and X is a reader (recursive or not) and Y is either a writer or
 	    non-recursive reader.
 
-Note that given two locks, they may have multiple dependencies between them, for example:
+Note that given two locks, they may have multiple dependencies between them,
+for example::
 
 	TASK A:
 
@@ -592,11 +603,11 @@ circles that won't cause deadlocks.
 
 Proof for sufficiency (Lemma 1):
 
-Let's say we have a strong circle:
+Let's say we have a strong circle::
 
 	L1 -> L2 ... -> Ln -> L1
 
-, which means we have dependencies:
+, which means we have dependencies::
 
 	L1 -> L2
 	L2 -> L3
@@ -633,7 +644,7 @@ a lock held by P2, and P2 is waiting for a lock held by P3, ... and Pn is waitin
 for a lock held by P1. Let's name the lock Px is waiting as Lx, so since P1 is waiting
 for L1 and holding Ln, so we will have Ln -> L1 in the dependency graph. Similarly,
 we have L1 -> L2, L2 -> L3, ..., Ln-1 -> Ln in the dependency graph, which means we
-have a circle:
+have a circle::
 
 	Ln -> L1 -> L2 -> ... -> Ln
 
Signature · 1 line
2.26.2
#32 lore raw

PATCH 28/30 drivers: core: fix kernel-doc markup for dev_err_probe()

In reply to Mauro Carvalho Chehab

There are two literal blocks there. Fix the markups, in order to produce the right html output and solve those warnings:

./drivers/base/core.c:4218: WARNING: Unexpected indentation. ./drivers/base/core.c:4222: WARNING: Definition list ends without a blank line; unexpected unindent. ./drivers/base/core.c:4223: WARNING: Block quote ends without a blank line; unexpected unindent.

Fixes a787e5400a1c ("driver core: add device probe log helper")
---
 drivers/base/core.c | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)
drivers/base/core.c +5 -2
index 8dd753539c06..21f8ae132fff 100644
@@ -4211,13 +4211,16 @@ define_dev_printk_level(_dev_info, KERN_INFO);
  * -EPROBE_DEFER and propagate error upwards.
  * In case of -EPROBE_DEFER it sets also defer probe reason, which can be
  * checked later by reading devices_deferred debugfs attribute.
- * It replaces code sequence:
+ * It replaces code sequence::
+ *
  * 	if (err != -EPROBE_DEFER)
  * 		dev_err(dev, ...);
  * 	else
  * 		dev_dbg(dev, ...);
  * 	return err;
- * with
+ *
+ * with::
+ *
  * 	return dev_err_probe(dev, err, ...);
  *
  * Returns @err.
Signature · 1 line
2.26.2
#17 lore raw

PATCH 15/30 docs: powerpc: syscall64-abi.rst: fix a malformed table

In reply to Mauro Carvalho Chehab

As reported:

Documentation/powerpc/syscall64-abi.rst:53: WARNING: Malformed table. Text in column margin in table line 2.

=========== ============= ======================================== --- For the sc instruction, differences with the ELF ABI ---
r0 Volatile (System call number.)

This table requires a different notation to be valid.

---
 Documentation/powerpc/syscall64-abi.rst | 32 ++++++++++++-------------
 1 file changed, 16 insertions(+), 16 deletions(-)
Documentation/powerpc/syscall64-abi.rst +16 -16
index 379817ca64d2..cf9b2857c72a 100644
@@ -49,22 +49,22 @@ Register preservation rules
 Register preservation rules match the ELF ABI calling sequence with the
 following differences:
 
---- For the sc instruction, differences with the ELF ABI ---
-=========== ============= ========================================
-r0          Volatile      (System call number.)
-r3          Volatile      (Parameter 1, and return value.)
-r4-r8       Volatile      (Parameters 2-6.)
-cr0         Volatile      (cr0.SO is the return error condition.)
-cr1, cr5-7  Nonvolatile
-lr          Nonvolatile
-=========== ============= ========================================
-
---- For the scv 0 instruction, differences with the ELF ABI ---
-=========== ============= ========================================
-r0          Volatile      (System call number.)
-r3          Volatile      (Parameter 1, and return value.)
-r4-r8       Volatile      (Parameters 2-6.)
-=========== ============= ========================================
++------------------------------------------------------------------------+
+|        For the sc instruction, differences with the ELF ABI		 |
++--------------+--------------+------------------------------------------+
+| r0           | Volatile     | (System call number.)			 |
+| rr3          | Volatile     | (Parameter 1, and return value.)	 |
+| rr4-r8       | Volatile     | (Parameters 2-6.)			 |
+| rcr0         | Volatile     | (cr0.SO is the return error condition.)	 |
+| rcr1, cr5-7  | Nonvolatile  |						 |
+| rlr          | Nonvolatile  |						 |
++--------------+--------------+------------------------------------------+
+|      For the scv 0 instruction, differences with the ELF ABI		 |
++--------------+--------------+------------------------------------------+
+| r0           | Volatile     | (System call number.)			 |
+| r3           | Volatile     | (Parameter 1, and return value.)	 |
+| r4-r8        | Volatile     | (Parameters 2-6.)			 |
++--------------+--------------+------------------------------------------+
 
 All floating point and vector data registers as well as control and status
 registers are nonvolatile.
Signature · 1 line
2.26.2
#34 lore raw

PATCH 30/30 docs: amdgpu: fix a warning when building the documentation

In reply to Mauro Carvalho Chehab

As reported by Sphinx:

Documentation/gpu/amdgpu.rst:200: WARNING: Inline emphasis start-string without end-string.

---
 Documentation/gpu/amdgpu.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/gpu/amdgpu.rst +2 -2
index 29ca5f5feb35..9656f5f5bbcf 100644
@@ -197,8 +197,8 @@ pp_power_profile_mode
 .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c
    :doc: pp_power_profile_mode
 
-*_busy_percent
-~~~~~~~~~~~~~~
+\*_busy_percent
+~~~~~~~~~~~~~~~
 
 .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c
    :doc: gpu_busy_percent
Signature · 1 line
2.26.2
#33 lore raw

PATCH 29/30 kunit: test.h: fix a bad kernel-doc markup

In reply to Mauro Carvalho Chehab

As warned by:

./include/kunit/test.h:504: WARNING: Block quote ends without a blank line; unexpected unindent.

The right way to describe a function is:

name - description

Instead, kunit_remove_resource was using:

name: description

Causing it to be improperly parsed.

---
 include/kunit/test.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/kunit/test.h +2 -2
index 41b3a266bf8c..5c5ed262a950 100644
@@ -498,8 +498,8 @@ static inline int kunit_destroy_named_resource(struct kunit *test,
 }
 
 /**
- * kunit_remove_resource: remove resource from resource list associated with
- *			  test.
+ * kunit_remove_resource() - remove resource from resource list associated with
+ *			     test.
  * @test: The test context object.
  * @res: The resource to be removed.
  *
Signature · 1 line
2.26.2
#1 lore raw

PATCH 1/30 .gitignore: docs: ignore sphinx_*/ directories

In reply to Mauro Carvalho Chehab

The default way of building documentation is to use Sphinx toolchain installed via pip, inside the Kernel tree main directory. That's what's recommended by:

scripts/sphinx-pre-install

As it usually provides a better version of this package than the one installed, specially on LTS distros.

So, add the directories created by running the commands suggested by the script.

---
 .gitignore | 3 +++
 1 file changed, 3 insertions(+)
.gitignore +3 -0
index 162bd2b67bdf..d01cda8e1177 100644
@@ -152,3 +152,6 @@ x509.genkey
 
 # Clang's compilation database file
 /compile_commands.json
+
+# Documentation toolchain
+sphinx_*/
Signature · 1 line
2.26.2
#28 lore raw

PATCH 26/30 iio: iio.h: fix a warning at the kernel-doc markup

In reply to Mauro Carvalho Chehab

There's a warning at iio.h kernel-doc markup:

./include/linux/iio/iio.h:644: WARNING: Unknown target name: "devm".

Because it is using {devm_}foo notation. Well, this is not a valid kernel-doc notation. Also, it prevents creating hyperlinks to other documentation functions.

So, replace it to a better notation.

---
 include/linux/iio/iio.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/iio/iio.h +1 -1
index e2df67a3b9ab..f1daaba9e706 100644
@@ -641,7 +641,7 @@ static inline struct iio_dev *iio_device_get(struct iio_dev *indio_dev)
  *
  * This utility must be called between IIO device allocation
  * (via devm_iio_device_alloc()) & IIO device registration
- * (via {devm_}iio_device_register()).
+ * (via iio_device_register() and devm_iio_device_register())).
  * By default, the device allocation will also assign a parent device to
  * the IIO device object. In cases where devm_iio_device_alloc() is used,
  * sometimes the parent device must be different than the device used to
Signature · 1 line
2.26.2
#25 lore raw

PATCH 23/30 docs: submitting-patches: use :doc: for references

In reply to Mauro Carvalho Chehab

There are two broken references at submitting-patches.rst:

Documentation/process/submitting-patches.rst:240: WARNING: undefined label: security-bugs (if the link has no caption the label must precede a section header) Documentation/process/submitting-patches.rst:336: WARNING: undefined label: documentation/process/email-clients.rst (if the link has no caption the label must precede a section header)

Those are due to some recent renames and file moves.

It turns that maintaining :ref: is currently harder than using :doc:, as we now have a script to help checking such references.

So, replace :ref: to :doc: there, making them to point to the current file name.

---
 Documentation/process/submitting-patches.rst | 20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)
Documentation/process/submitting-patches.rst +8 -12
index 04cd41567186..58586ffe2808 100644
@@ -10,13 +10,10 @@ can greatly increase the chances of your change being accepted.
 
 This document contains a large number of suggestions in a relatively terse
 format.  For detailed information on how the kernel development process
-works, see :ref:`Documentation/process <development_process_main>`.
-Also, read :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`
-for a list of items to check before
-submitting code.  If you are submitting a driver, also read
-:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`;
-for device tree binding patches, read
-Documentation/devicetree/bindings/submitting-patches.rst.
+works, see :doc:`development-process`. Also, read :doc:`submit-checklist`
+for a list of items to check before submitting code.  If you are submitting
+a driver, also read :doc:`submitting-drivers`; for device tree binding patches,
+read :doc:`submitting-patches`.
 
 This documentation assumes that you're using ``git`` to prepare your patches.
 If you're unfamiliar with ``git``, you would be well-advised to learn how to
@@ -241,7 +238,7 @@ If you have a patch that fixes an exploitable security bug, send that patch
 to [email protected].  For severe bugs, a short embargo may be considered
 to allow distributors to get the patch out to users; in such cases,
 obviously, the patch should not be sent to any public lists. See also
-:ref:`Documentation/admin-guide/security-bugs.rst <security-bugs>`.
+:doc:`/admin-guide/security-bugs`.
 
 Patches that fix a severe bug in a released kernel should be directed
 toward the stable maintainers by putting a line like this::
@@ -313,9 +310,8 @@ decreasing the likelihood of your MIME-attached change being accepted.
 Exception:  If your mailer is mangling patches then someone may ask
 you to re-send them using MIME.
 
-See :ref:`Documentation/process/email-clients.rst <email_clients>`
-for hints about configuring your e-mail client so that it sends your patches
-untouched.
+See :doc:`/process/email-clients` for hints about configuring your e-mail
+client so that it sends your patches untouched.
 
 Respond to review comments
 --------------------------
@@ -333,7 +329,7 @@ for their time.  Code review is a tiring and time-consuming process, and
 reviewers sometimes get grumpy.  Even in that case, though, respond
 politely and address the problems they have pointed out.
 
-See :ref:`Documentation/process/email-clients.rst` for recommendations on email
+See :doc:`email-clients` for recommendations on email
 clients and mailing list etiquette.
 
 
Signature · 1 line
2.26.2
#21 lore raw

PATCH 19/30 docs: soundwire: fix some identation at stream.rst

In reply to Mauro Carvalho Chehab

Currently, sphinx emits one warning on this file:

Documentation/driver-api/soundwire/stream.rst:522: WARNING: Block quote ends without a blank line; unexpected unindent.

That's due to some extra spaces before the title of a chapter.

Yet, the list afterwards is missing identation.

So, address both issues.

---
 Documentation/driver-api/soundwire/stream.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/driver-api/soundwire/stream.rst +4 -4
index 8858cea7bfe0..b432a2de45d3 100644
@@ -518,10 +518,10 @@ typically called during a dailink .shutdown() callback, which clears
 the stream pointer for all DAIS connected to a stream and releases the
 memory allocated for the stream.
 
-  Not Supported
+Not Supported
 =============
 
 1. A single port with multiple channels supported cannot be used between two
-streams or across stream. For example a port with 4 channels cannot be used
-to handle 2 independent stereo streams even though it's possible in theory
-in SoundWire.
+   streams or across stream. For example a port with 4 channels cannot be used
+   to handle 2 independent stereo streams even though it's possible in theory
+   in SoundWire.
Signature · 1 line
2.26.2
#13 lore raw

PATCH 11/30 tools: docs: memory-model: fix references for some files

In reply to Mauro Carvalho Chehab

- The sysfs.txt file was converted to ReST and renamed;
- The control-dependencies.txt is not at Documentation/control-dependencies.txt. As it is at the same dir as the README file, which mentions it, just remove Documentation/.

With that, ./scripts/documentation-file-ref-check script is now happy again for files under tools/.

---
 tools/memory-model/Documentation/README       | 2 +-
 tools/memory-model/Documentation/ordering.txt | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
tools/memory-model/Documentation/README +1 -1
index 16177aaa9752..004969992bac 100644
@@ -55,7 +55,7 @@ README
 Documentation/cheatsheet.txt
 	Quick-reference guide to the Linux-kernel memory model.
 
-Documentation/control-dependencies.txt
+control-dependencies.txt
 	A guide to preventing compiler optimizations from destroying
 	your control dependencies.
 
tools/memory-model/Documentation/ordering.txt +1 -1
index 3d020bed8585..629b19ae64a6 100644
@@ -346,7 +346,7 @@ o	Accessing RCU-protected pointers via rcu_dereference()
 
 	If there is any significant processing of the pointer value
 	between the rcu_dereference() that returned it and a later
-	dereference(), please read Documentation/RCU/rcu_dereference.txt.
+	dereference(), please read Documentation/RCU/rcu_dereference.rst.
 
 It can also be quite helpful to review uses in the Linux kernel.
 
Signature · 1 line
2.26.2
#18 lore raw

PATCH 16/30 docs: watch_queue: fix some warnings

In reply to Mauro Carvalho Chehab

Fix those warnings:

Documentation/watch_queue.rst:108: WARNING: Inline literal start-string without end-string. Documentation/watch_queue.rst:108: WARNING: Inline emphasis start-string without end-string. Documentation/watch_queue.rst:108: WARNING: Inline emphasis start-string without end-string. Documentation/watch_queue.rst:108: WARNING: Inline emphasis start-string without end-string. Documentation/watch_queue.rst:185: WARNING: Inline literal start-string without end-string. Documentation/watch_queue.rst:185: WARNING: Inline emphasis start-string without end-string. Documentation/watch_queue.rst:184: WARNING: Inline emphasis start-string without end-string.

The problem here is that the ``notation`` doesn't accept multi lines. So, replace it to a code block using:

	::

		notation
---
 Documentation/watch_queue.rst | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)
Documentation/watch_queue.rst +9 -5
index 3e647992be31..85565e8a15da 100644
@@ -104,8 +104,10 @@ watch that specific key).
 
 To manage a watch list, the following functions are provided:
 
-  * ``void init_watch_list(struct watch_list *wlist,
-			   void (*release_watch)(struct watch *wlist));``
+  * ::
+
+	void init_watch_list(struct watch_list *wlist,
+			     void (*release_watch)(struct watch *wlist));
 
     Initialise a watch list.  If ``release_watch`` is not NULL, then this
     indicates a function that should be called when the watch_list object is
@@ -180,9 +182,11 @@ The following functions are provided to manage watches:
     driver-settable fields in the watch struct must have been set before this
     is called.
 
-  * ``int remove_watch_from_object(struct watch_list *wlist,
-				   struct watch_queue *wqueue,
-				   u64 id, false);``
+  * ::
+
+	int remove_watch_from_object(struct watch_list *wlist,
+				     struct watch_queue *wqueue,
+				     u64 id, false);
 
     Remove a watch from a watch list, where the watch must match the specified
     watch queue (``wqueue``) and object identifier (``id``).  A notification
Signature · 1 line
2.26.2
#24 lore raw

PATCH 22/30 kunit: test.h: solve kernel-doc warnings

In reply to Mauro Carvalho Chehab

There are some warnings there:
./include/kunit/test.h:90: warning: Function parameter or member 'name' not described in 'kunit_resource' ./include/kunit/test.h:353: warning: Function parameter or member 'res' not described in 'kunit_add_resource' ./include/kunit/test.h:367: warning: Function parameter or member 'res' not described in 'kunit_add_named_resource' ./include/kunit/test.h:367: warning: Function parameter or member 'name' not described in 'kunit_add_named_resource' ./include/kunit/test.h:367: warning: Function parameter or member 'data' not described in 'kunit_add_named_resource' ./include/kunit/test.h:367: warning: Excess function parameter 'name_data' description in 'kunit_add_named_resource'

Address them, ensuring that all non-private arguments will be properly described. With that regards, at struct kunit_resource, the free argument is described as user-provided. So, this doesn't seem to belong to the "private" part of the struct.

---
 include/kunit/test.h | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)
include/kunit/test.h +8 -4
index 59f3144f009a..41b3a266bf8c 100644
@@ -25,6 +25,7 @@ typedef void (*kunit_resource_free_t)(struct kunit_resource *);
 /**
  * struct kunit_resource - represents a *test managed resource*
  * @data: for the user to store arbitrary data.
+ * @name: optional name
  * @free: a user supplied function to free the resource. Populated by
  * kunit_resource_alloc().
  *
@@ -80,10 +81,10 @@ typedef void (*kunit_resource_free_t)(struct kunit_resource *);
  */
 struct kunit_resource {
 	void *data;
-	const char *name;		/* optional name */
-
-	/* private: internal use only. */
+	const char *name;
 	kunit_resource_free_t free;
+
+	/* private: internal use only. */
 	struct kref refcount;
 	struct list_head node;
 };
@@ -343,6 +344,7 @@ static inline void kunit_put_resource(struct kunit_resource *res)
  *        none is supplied, the resource data value is simply set to @data.
  *	  If an init function is supplied, @data is passed to it instead.
  * @free: a user-supplied function to free the resource (if needed).
+ * @res: The resource.
  * @data: value to pass to init function or set in resource data field.
  */
 int kunit_add_resource(struct kunit *test,
@@ -356,7 +358,9 @@ int kunit_add_resource(struct kunit *test,
  * @test: The test context object.
  * @init: a user-supplied function to initialize the resource data, if needed.
  * @free: a user-supplied function to free the resource data, if needed.
- * @name_data: name and data to be set for resource.
+ * @res: The resource.
+ * @name: name to be set for resource.
+ * @data: value to pass to init function or set in resource data field.
  */
 int kunit_add_named_resource(struct kunit *test,
 			     kunit_resource_init_t init,
Signature · 1 line
2.26.2
#20 lore raw

PATCH 18/30 block: bio: fix a warning at the kernel-doc markups

In reply to Mauro Carvalho Chehab

Using "@bio's parent" causes the following waring:
./block/bio.c:10: WARNING: Inline emphasis start-string without end-string.

The main problem here is that this would be converted into:

	**bio**'s parent

By kernel-doc, which is not a valid notation. It would be possible to use, instead, this kernel-doc markup:

	``bio's`` parent

Yet, here, is probably simpler to just use an altenative language:

the parent of @bio

---
 block/bio.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
block/bio.c +1 -1
index a9931f23d933..ccd3ab549d41 100644
@@ -327,7 +327,7 @@ static void bio_chain_endio(struct bio *bio)
 /**
  * bio_chain - chain bio completions
  * @bio: the target bio
- * @parent: the @bio's parent bio
+ * @parent: the parent bio of @bio
  *
  * The caller won't have a bi_end_io called when @bio completes - instead,
  * @parent's bi_end_io won't be called until both @parent and @bio have
Signature · 1 line
2.26.2
#12 lore raw

PATCH 10/30 drivers: net: hamradio: fix document location

In reply to Mauro Carvalho Chehab

The hamradio docs were moved to a different dir.
Update its location accordingly.

Fixes 14474950252c ("docs: networking: move z8530 to the hw driver section")
---
 drivers/net/hamradio/scc.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/net/hamradio/scc.c +1 -1
index 1e915871baa7..36eeb80406f2 100644
@@ -7,7 +7,7 @@
  *            ------------------
  *
  * You can find a subset of the documentation in 
- * Documentation/networking/device_drivers/wan/z8530drv.rst.
+ * Documentation/networking/device_drivers/hamradio/z8530drv.rst.
  */
 
 /*
Signature · 1 line
2.26.2
#19 lore raw

PATCH 17/30 docs: kvm: api.rst: add missing spaces

In reply to Mauro Carvalho Chehab

There are some warnings:

Documentation/virt/kvm/api.rst:4354: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/virt/kvm/api.rst:4358: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/virt/kvm/api.rst:4363: WARNING: Definition list ends without a blank line; unexpected unindent.

Produced by the lack of identation on a single line. That caused the literal block to end prematurely.

---
 Documentation/virt/kvm/api.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/virt/kvm/api.rst +1 -1
index d2b733dc7892..24e8046ec083 100644
@@ -4343,7 +4343,7 @@ Errors:
   #define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE	0x00000001
   #define KVM_STATE_NESTED_VMX_SMM_VMXON	0x00000002
 
-#define KVM_STATE_VMX_PREEMPTION_TIMER_DEADLINE 0x00000001
+  #define KVM_STATE_VMX_PREEMPTION_TIMER_DEADLINE 0x00000001
 
   struct kvm_vmx_nested_state_hdr {
 	__u64 vmxon_pa;
Signature · 1 line
2.26.2
#15 lore raw

PATCH 13/30 docs: SafeSetID: fix a warning

In reply to Mauro Carvalho Chehab

As reported by Sphinx 2.4.4:

docs/Documentation/admin-guide/LSM/SafeSetID.rst:110: WARNING: Title underline too short.

Note on GID policies and setgroups()
==================

---
 Documentation/admin-guide/LSM/SafeSetID.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/admin-guide/LSM/SafeSetID.rst +1 -1
index 17996c9070e2..0ec34863c674 100644
@@ -107,7 +107,7 @@ for a UID/GID will prevent that UID/GID from obtaining auxiliary setid
 privileges, such as allowing a user to set up user namespace UID/GID mappings.
 
 Note on GID policies and setgroups()
-==================
+====================================
 In v5.9 we are adding support for limiting CAP_SETGID privileges as was done
 previously for CAP_SETUID. However, for compatibility with common sandboxing
 related code conventions in userspace, we currently allow arbitrary
Signature · 1 line
2.26.2
#23 lore raw

PATCH 21/30 iio: industrialio-core.c: solve a kernel-doc warning

In reply to Mauro Carvalho Chehab

kernel-doc currently compains with:
./drivers/iio/industrialio-core.c:177: warning: Function parameter or member 'indio_dev' not described in 'iio_get_debugfs_dentry' ./drivers/iio/industrialio-core.c:1530: warning: Function parameter or member 'parent' not described in 'iio_device_alloc'

The problem is that the comment just before iio_get_debugfs_dentry() is just a comment, and not really a kernel-doc markup.

---
 drivers/iio/industrialio-core.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/iio/industrialio-core.c +1 -1
index d882c7f31ba9..b05ff9154310 100644
@@ -169,7 +169,7 @@ static const char * const iio_chan_info_postfix[] = {
 };
 
 #if defined(CONFIG_DEBUG_FS)
-/**
+/*
  * There's also a CONFIG_DEBUG_FS guard in include/linux/iio/iio.h for
  * iio_get_debugfs_dentry() to make it inline if CONFIG_DEBUG_FS is undefined
  */
Signature · 1 line
2.26.2
#22 lore raw

PATCH 20/30 docs: dma-buf: fix some warnings

In reply to Mauro Carvalho Chehab

Fix those warnings:

Documentation/driver-api/dma-buf.rst:182: WARNING: Title underline too short.

Indefinite DMA Fences
~~~~~~~~~~~~~~~~~~~~

Documentation/driver-api/dma-buf.rst:88: WARNING: Unknown target name: "fence poll support".

The first one is due to a shorter markup. The second one is because the chapter name was wrong.

---
 Documentation/driver-api/dma-buf.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/driver-api/dma-buf.rst +1 -1
index 13ea0cc0a3fa..4144b669e80c 100644
@@ -85,7 +85,7 @@ consider though:
 - Memory mapping the contents of the DMA buffer is also supported. See the
   discussion below on `CPU Access to DMA Buffer Objects`_ for the full details.
 
-- The DMA buffer FD is also pollable, see `Fence Poll Support`_ below for
+- The DMA buffer FD is also pollable, see `Implicit Fence Poll Support`_ below for
   details.
 
 Basic Operation and Device DMA Access
Signature · 1 line
2.26.2
#3 lore raw

PATCH 2/30 kernel-doc: include line numbers for function prototypes

In reply to Mauro Carvalho Chehab

This should solve bad error reports like this one:

./include/linux/iio/iio.h:0: WARNING: Unknown target name: "devm".

---
 scripts/kernel-doc | 2 ++
 1 file changed, 2 insertions(+)
scripts/kernel-doc +2 -0
index d1b445665ad6..3982d47048a7 100755
@@ -1594,6 +1594,8 @@ sub dump_function($$) {
     my $file = shift;
     my $noret = 0;
 
+    print_lineno($.);
+
     $prototype =~ s/^static +//;
     $prototype =~ s/^extern +//;
     $prototype =~ s/^asmlinkage +//;
Signature · 1 line
2.26.2
#4 lore raw

PATCH 3/30 dt-bindings: fix references to files converted to yaml

In reply to Mauro Carvalho Chehab

There were several files converted to yaml, but the .txt file is still referenced somewhere else.

Update the references for them to point to the right file.

---
 .../bindings/display/tilcdc/tilcdc.txt         |  2 +-
 .../bindings/mailbox/omap-mailbox.txt          |  2 +-
 .../devicetree/bindings/media/i2c/tvp5150.txt  |  2 +-
 .../bindings/pwm/google,cros-ec-pwm.yaml       |  2 +-
 .../bindings/soc/qcom/qcom,smd-rpm.yaml        |  2 +-
 .../bindings/sound/google,cros-ec-codec.yaml   |  2 +-
 MAINTAINERS                                    | 18 +++++++++---------
 .../bindings/net/wireless/siliabs,wfx.txt      |  2 +-
 8 files changed, 16 insertions(+), 16 deletions(-)
Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt +1 -1
index 8b2a71395647..3e64075ac7ec 100644
@@ -37,7 +37,7 @@ Optional nodes:
    supports a single port with a single endpoint.
 
  - See also Documentation/devicetree/bindings/display/tilcdc/panel.txt and
-   Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt for connecting
+   Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml for connecting
    tfp410 DVI encoder or lcd panel to lcdc
 
 [1] There is an errata about AM335x color wiring. For 16-bit color mode
Documentation/devicetree/bindings/mailbox/omap-mailbox.txt +1 -1
index 35c3f56b7f7b..5fe80c1c19fc 100644
@@ -69,7 +69,7 @@ The following are mandatory properties for the K3 AM65x and J721E SoCs only:
 			the interrupt routes between the IP and the main GIC
 			controllers. See the following binding for additional
 			details,
-			Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt
+			Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml
 
 Child Nodes:
 ============
Documentation/devicetree/bindings/media/i2c/tvp5150.txt +1 -1
index 6c88ce858d08..719b2995dc17 100644
@@ -56,7 +56,7 @@ Optional Connector Properties:
                   instead of using the autodetection mechnism. Please look at
                   [1] for more information.
 
-[1] Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt.
+[1] Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml.
 
 Example - three input sources:
 #include <dt-bindings/display/sdtv-standards.h>
Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml +1 -1
index 41ece1d85315..4cfbffd8414a 100644
@@ -14,7 +14,7 @@ description: |
   Google's ChromeOS EC PWM is a simple PWM attached to the Embedded Controller
   (EC) and controlled via a host-command interface.
   An EC PWM node should be only found as a sub-node of the EC node (see
-  Documentation/devicetree/bindings/mfd/cros-ec.txt).
+  Documentation/devicetree/bindings/mfd/google,cros-ec.yaml).
 
 properties:
   compatible:
Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml +1 -1
index 468d658ce3e7..2684f22a1d85 100644
@@ -20,7 +20,7 @@ description: |
   present and this subnode may contain children that designate regulator
   resources.
 
-  Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt
+  Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml
   for information on the regulator subnodes that can exist under the
   rpm_requests.
 
Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml +1 -1
index c84e656afb0a..3b9143af2c7c 100644
@@ -13,7 +13,7 @@ description: |
   Google's ChromeOS EC codec is a digital mic codec provided by the
   Embedded Controller (EC) and is controlled via a host-command interface.
   An EC codec node should only be found as a sub-node of the EC node (see
-  Documentation/devicetree/bindings/mfd/cros-ec.txt).
+  Documentation/devicetree/bindings/mfd/google,cros-ec.yaml).
 
 properties:
   compatible:
MAINTAINERS +9 -9
index 3c0692404907..f3fee4140272 100644
@@ -1544,7 +1544,7 @@ L:	[email protected] (moderated for non-subscribers)
 S:	Maintained
 F:	Documentation/devicetree/bindings/arm/actions.yaml
 F:	Documentation/devicetree/bindings/clock/actions,owl-cmu.txt
-F:	Documentation/devicetree/bindings/dma/owl-dma.txt
+F:	Documentation/devicetree/bindings/dma/owl-dma.yaml
 F:	Documentation/devicetree/bindings/i2c/i2c-owl.txt
 F:	Documentation/devicetree/bindings/mmc/owl-mmc.yaml
 F:	Documentation/devicetree/bindings/pinctrl/actions,*
@@ -5634,7 +5634,7 @@ DRM DRIVER FOR ROCKTECH JH057N00900 PANELS
 M:	Guido Günther <[email protected]>
 R:	Purism Kernel Team <[email protected]>
 S:	Maintained
-F:	Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt
+F:	Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml
 F:	drivers/gpu/drm/panel/panel-rocktech-jh057n00900.c
 
 DRM DRIVER FOR SAVAGE VIDEO CARDS
@@ -5883,7 +5883,7 @@ L:	[email protected]
 S:	Supported
 T:	git git://linuxtv.org/pinchartl/media drm/du/next
 F:	Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt
-F:	Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt
+F:	Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml
 F:	Documentation/devicetree/bindings/display/renesas,du.txt
 F:	drivers/gpu/drm/rcar-du/
 F:	drivers/gpu/drm/shmobile/
@@ -7013,7 +7013,7 @@ M:	Frank Li <[email protected]>
 L:	[email protected]
 S:	Maintained
 F:	Documentation/admin-guide/perf/imx-ddr.rst
-F:	Documentation/devicetree/bindings/perf/fsl-imx-ddr.txt
+F:	Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml
 F:	drivers/perf/fsl_imx8_ddr_perf.c
 
 FREESCALE IMX I2C DRIVER
@@ -7021,7 +7021,7 @@ M:	Oleksij Rempel <[email protected]>
 R:	Pengutronix Kernel Team <[email protected]>
 L:	[email protected]
 S:	Maintained
-F:	Documentation/devicetree/bindings/i2c/i2c-imx.txt
+F:	Documentation/devicetree/bindings/i2c/i2c-imx.yaml
 F:	drivers/i2c/busses/i2c-imx.c
 
 FREESCALE IMX LPI2C DRIVER
@@ -7029,7 +7029,7 @@ M:	Dong Aisheng <[email protected]>
 L:	[email protected]
 L:	[email protected]
 S:	Maintained
-F:	Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt
+F:	Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml
 F:	drivers/i2c/busses/i2c-imx-lpi2c.c
 
 FREESCALE QORIQ DPAA ETHERNET DRIVER
@@ -11673,7 +11673,7 @@ MIPS GENERIC PLATFORM
 M:	Paul Burton <[email protected]>
 L:	[email protected]
 S:	Supported
-F:	Documentation/devicetree/bindings/power/mti,mips-cpc.txt
+F:	Documentation/devicetree/bindings/power/mti,mips-cpc.yaml
 F:	arch/mips/generic/
 F:	arch/mips/tools/generic-board-config.sh
 
@@ -12534,7 +12534,7 @@ NXP SGTL5000 DRIVER
 M:	Fabio Estevam <[email protected]>
 L:	[email protected] (moderated for non-subscribers)
 S:	Maintained
-F:	Documentation/devicetree/bindings/sound/sgtl5000.txt
+F:	Documentation/devicetree/bindings/sound/sgtl5000.yaml
 F:	sound/soc/codecs/sgtl5000*
 
 NXP SJA1105 ETHERNET SWITCH DRIVER
@@ -16827,7 +16827,7 @@ SYNOPSYS DESIGNWARE DMAC DRIVER
 M:	Viresh Kumar <[email protected]>
 R:	Andy Shevchenko <[email protected]>
 S:	Maintained
-F:	Documentation/devicetree/bindings/dma/snps-dma.txt
+F:	Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml
 F:	drivers/dma/dw/
 F:	include/dt-bindings/dma/dw-dmac.h
 F:	include/linux/dma/dw.h
drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/siliabs,wfx.txt +1 -1
index 17db67559f5e..362af9f0b7e3 100644
@@ -51,7 +51,7 @@ Required properties:
 In addition, it is recommended to declare a mmc-pwrseq on SDIO host above WFx.
 Without it, you may encounter issues with warm boot. mmc-pwrseq should be
 compatible with mmc-pwrseq-simple. Please consult
-Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt for more
+Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml for more
 information.
 
 Example:
Signature · 1 line
2.26.2
#27 lore raw

PATCH 25/30 docs: admin-guide: net.rst: add a missing blank line

In reply to Mauro Carvalho Chehab

There's a missing blank line after a literal block, which causes this warning:

Documentation/admin-guide/sysctl/net.rst:303: WARNING: Literal block ends without a blank line; unexpected unindent.

---
 Documentation/admin-guide/sysctl/net.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/admin-guide/sysctl/net.rst +1 -0
index 57fd6ce68fe0..f2ab8a5b6a4b 100644
@@ -300,6 +300,7 @@ Note:
       0:    0     1     2     3     4     5     6     7
   RSS hash key:
   84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89
+
 netdev_tstamp_prequeue
 ----------------------
 
Signature · 1 line
2.26.2
#0 lore raw

cover docs: fix documentation build parsing errors

Currently, there are several warnings/errors produced when building the documentation with "make htmldocs".

This series fixes almost all such errors. It is produced against linux-next, branch next-20200909.

Some of the patches here were already sent individually, but nobody picked them. So, I'm re-sending the full series.

After this series, there will be just two parse warnings due to Documentation/bpf/ringbuf.rst, which seems to have been included at linux-next before the actual feature. I already wrote an e-mail to the author asking for a fix.

There are still plenty warnings produced by kernel-doc, but those are due to missing files and/or parameters, like:

./include/linux/blk-mq.h:267: warning: Function parameter or member 'active_queues_shared_sbitmap' not described in 'blk_mq_tag_set' ./drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c:1: warning: no structured comments found ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init' ./drivers/usb/typec/bus.c:1: warning: 'typec_altmode_unregister_driver' not found

As time allows, I will try to cleanup most of those too, although some may require a deeper knowledge of the affected subsystems.

Jon,

I know that you don't like very much patches against linux-next, but that seems to be the only way to address issues when building the docs, as warnings can come from random trees.

My suggestion would be for you to pick at least the ones that apply cleanly on your tree. I can rebase the ones later for them to be applied along the merge window.

I'm aiming here to have Kernel 5.10 free of documentation warnings. Hopefully, people will take more care to avoid introducing new warnings once we get rid of all of them.

Mauro Carvalho Chehab (30):
.gitignore: docs: ignore sphinx_*/ directories
kernel-doc: include line numbers for function prototypes
dt-bindings: fix references to files converted to yaml
docs: hwmon: adm1266.rst: fix a broken reference
docs: scheduler: fix the directory name on two files
docs: trace: fix the location of kprobes.rst
MAINTAINERS: fix location of qlogic/LICENSE.qla3xxx
docs: fix location of nommu-mmap.rst file
net: appletalk: Kconfig: Fix docs location
drivers: net: hamradio: fix document location
tools: docs: memory-model: fix references for some files
scripts: device_attr_show.cocci: update location of sysfs doc
docs: SafeSetID: fix a warning
docs: add some new files to their respective index.rst files
docs: powerpc: syscall64-abi.rst: fix a malformed table
docs: watch_queue: fix some warnings
docs: kvm: api.rst: add missing spaces
block: bio: fix a warning at the kernel-doc markups
docs: soundwire: fix some identation at stream.rst
docs: dma-buf: fix some warnings
iio: industrialio-core.c: solve a kernel-doc warning
kunit: test.h: solve kernel-doc warnings
docs: submitting-patches: use :doc: for references
docs: lockdep-design: fix some warning issues
docs: admin-guide: net.rst: add a missing blank line
iio: iio.h: fix a warning at the kernel-doc markup
docs: bio: fix a kerneldoc markup
drivers: core: fix kernel-doc markup for dev_err_probe()
kunit: test.h: fix a bad kernel-doc markup
docs: amdgpu: fix a warning when building the documentation

 .gitignore                                    |  3 +
 Documentation/admin-guide/LSM/SafeSetID.rst   |  2 +-
 Documentation/admin-guide/sysctl/net.rst      |  1 +
 .../bindings/display/tilcdc/tilcdc.txt        |  2 +-
 .../bindings/mailbox/omap-mailbox.txt         |  2 +-
 .../devicetree/bindings/media/i2c/tvp5150.txt |  2 +-
 .../bindings/pwm/google,cros-ec-pwm.yaml      |  2 +-
 .../bindings/soc/qcom/qcom,smd-rpm.yaml       |  2 +-
 .../bindings/sound/google,cros-ec-codec.yaml  |  2 +-
 Documentation/driver-api/dma-buf.rst          |  2 +-
 Documentation/driver-api/nvdimm/index.rst     |  1 +
 Documentation/driver-api/soundwire/stream.rst |  8 +--
 Documentation/firmware-guide/acpi/index.rst   |  1 +
 Documentation/gpu/amdgpu.rst                  |  4 +-
 Documentation/hwmon/adm1266.rst               |  2 +-
 Documentation/hwmon/index.rst                 |  1 +
 Documentation/locking/lockdep-design.rst      | 69 +++++++++++--------
 Documentation/powerpc/syscall64-abi.rst       | 32 ++++-----
 Documentation/process/submitting-patches.rst  | 20 +++---
 Documentation/scheduler/sched-capacity.rst    |  2 +-
 Documentation/scheduler/sched-energy.rst      |  2 +-
 Documentation/trace/kprobetrace.rst           |  2 +-
 Documentation/virt/kvm/api.rst                |  2 +-
 Documentation/vm/index.rst                    |  1 +
 Documentation/watch_queue.rst                 | 14 ++--
 MAINTAINERS                                   | 20 +++---
 block/bio.c                                   |  4 +-
 drivers/base/core.c                           |  7 +-
 drivers/iio/industrialio-core.c               |  2 +-
 drivers/net/appletalk/Kconfig                 |  2 +-
 drivers/net/hamradio/scc.c                    |  2 +-
 .../bindings/net/wireless/siliabs,wfx.txt     |  2 +-
 include/kunit/test.h                          | 16 +++--
 include/linux/iio/iio.h                       |  2 +-
 init/Kconfig                                  |  2 +-
 mm/Kconfig                                    |  2 +-
 mm/nommu.c                                    |  2 +-
 samples/kprobes/kprobe_example.c              |  2 +-
 samples/kprobes/kretprobe_example.c           |  2 +-
 scripts/coccinelle/api/device_attr_show.cocci |  2 +-
 scripts/kernel-doc                            |  2 +
 tools/memory-model/Documentation/README       |  2 +-
 tools/memory-model/Documentation/ordering.txt |  2 +-
 43 files changed, 142 insertions(+), 114 deletions(-)
Signature · 1 line
2.26.2
#6 lore raw

PATCH 5/30 docs: scheduler: fix the directory name on two files

The name of the directory where the schedule docs are stored are wrong on those files.

---
 Documentation/scheduler/sched-capacity.rst | 2 +-
 Documentation/scheduler/sched-energy.rst   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
Documentation/scheduler/sched-capacity.rst +1 -1
index 00bf0d011e2a..9b7cbe43b2d1 100644
@@ -365,7 +365,7 @@ giving it a high uclamp.min value.
 .. note::
 
   Wakeup CPU selection in CFS can be eclipsed by Energy Aware Scheduling
-  (EAS), which is described in Documentation/scheduling/sched-energy.rst.
+  (EAS), which is described in Documentation/scheduler/sched-energy.rst.
 
 5.1.3 Load balancing
 ~~~~~~~~~~~~~~~~~~~~
Documentation/scheduler/sched-energy.rst +1 -1
index 78f850778982..001e09c95e1d 100644
@@ -331,7 +331,7 @@ asymmetric CPU topologies for now. This requirement is checked at run-time by
 looking for the presence of the SD_ASYM_CPUCAPACITY flag when the scheduling
 domains are built.
 
-See Documentation/sched/sched-capacity.rst for requirements to be met for this
+See Documentation/scheduler/sched-capacity.rst for requirements to be met for this
 flag to be set in the sched_domain hierarchy.
 
 Please note that EAS is not fundamentally incompatible with SMP, but no
Signature · 1 line
2.26.2
#11 lore raw

PATCH 9/30 net: appletalk: Kconfig: Fix docs location

In reply to Mauro Carvalho Chehab

The location of ltpc.rst changed. Update it at Kconfig.

Fixes 4daedf7abb41 ("docs: networking: move AppleTalk / LocalTalk drivers to the hw driver section")
---
 drivers/net/appletalk/Kconfig | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/net/appletalk/Kconfig +1 -1
index d4f22a2e5be4..43918398f0d3 100644
@@ -48,7 +48,7 @@ config LTPC
 	  If you are in doubt, this card is the one with the 65C02 chip on it.
 	  You also need version 1.3.3 or later of the netatalk package.
 	  This driver is experimental, which means that it may not work.
-	  See the file <file:Documentation/networking/ltpc.rst>.
+	  See the file <file:Documentation/networking/device_drivers/appletalk/ltpc.rst>.
 
 config COPS
 	tristate "COPS LocalTalk PC support"
Signature · 1 line
2.26.2
Reviewed-by on v1 5/30
#7 lore raw

Re: [PATCH 05/30] docs: scheduler: fix the directory name on two files

In reply to Mauro Carvalho Chehab

(+Cc Ingo, Peter)

Quoted 4 lines · Mauro Carvalho Chehab

The name of the directory where the schedule docs are stored are wrong on those files.

This still stands from last posting:

In the cover letter you mention resending a bunch of these (including this one) as they weren't picked up. Ingo / Peter, would you guys mind picking this one up in tip? AFAICT it's the only scheduler-related patch of the series.

Quoted 31 lines
---
 Documentation/scheduler/sched-capacity.rst | 2 +-
 Documentation/scheduler/sched-energy.rst   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
Documentation/scheduler/sched-capacity.rst +1 -1
index 00bf0d011e2a..9b7cbe43b2d1 100644
@@ -365,7 +365,7 @@ giving it a high uclamp.min value.
 .. note::
 
   Wakeup CPU selection in CFS can be eclipsed by Energy Aware Scheduling
-  (EAS), which is described in Documentation/scheduling/sched-energy.rst.
+  (EAS), which is described in Documentation/scheduler/sched-energy.rst.
 
 5.1.3 Load balancing
 ~~~~~~~~~~~~~~~~~~~~
Documentation/scheduler/sched-energy.rst +1 -1
index 78f850778982..001e09c95e1d 100644
@@ -331,7 +331,7 @@ asymmetric CPU topologies for now. This requirement is checked at run-time by
 looking for the presence of the SD_ASYM_CPUCAPACITY flag when the scheduling
 domains are built.
 
-See Documentation/sched/sched-capacity.rst for requirements to be met for this
+See Documentation/scheduler/sched-capacity.rst for requirements to be met for this
 flag to be set in the sched_domain hierarchy.
 
 Please note that EAS is not fundamentally incompatible with SMP, but no
maintainer
#35 lore raw
In reply to Mauro Carvalho Chehab
Quoted 8 lines · On Wed, 9 Sep 2020 16:10:31 +0200 Mauro Carvalho Chehab…

Currently, there are several warnings/errors produced when building the documentation with "make htmldocs".

This series fixes almost all such errors. It is produced against linux-next, branch next-20200909.

Some of the patches here were already sent individually, but nobody picked them. So, I'm re-sending the full series.

I'd sure love to just apply the whole series and clean up a lot of this stuff, but (1) I'm not entirely comfortable taking a few through docs-next, and (2) some of them don't apply even if I catch up to -rc4. So I'm going to pass through them individually and snag as many as I can...

Thanks,

jon

maintainer Applied
#2 lore raw

Re: [PATCH 01/30] .gitignore: docs: ignore sphinx_*/ directories

In reply to Mauro Carvalho Chehab
Quoted 6 lines · On Wed, 9 Sep 2020 16:10:32 +0200 Mauro Carvalho Chehab…

The default way of building documentation is to use Sphinx toolchain installed via pip, inside the Kernel tree main directory. That's what's recommended by:

scripts/sphinx-pre-install

Quoted 7 lines

As it usually provides a better version of this package than the one installed, specially on LTS distros.

So, add the directories created by running the commands suggested by the script.

Applied, thanks.

Also applied parts 2, 5, 6, 7, 12, 14, 16, 17, 19, 20, and 23. Many of the others don't apply at all; they're going to need to go to the relevant maintainers.

Thanks,

jon

#36 lore raw
In reply to Jonathan Corbet

Em Thu, 10 Sep 2020 10:42:50 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 9 lines
Quoted 6 lines · On Wed, 9 Sep 2020 16:10:31 +0200 Mauro Carvalho Chehab…

Currently, there are several warnings/errors produced when building the documentation with "make htmldocs".

This series fixes almost all such errors. It is produced against linux-next, branch next-20200909.

Quoted 7 lines
Quoted 2 lines

Some of the patches here were already sent individually, but nobody picked them. So, I'm re-sending the full series.

I'd sure love to just apply the whole series and clean up a lot of this stuff, but (1) I'm not entirely comfortable taking a few through docs-next, and (2) some of them don't apply even if I catch up to -rc4. So I'm going to pass through them individually and snag as many as I can...

Yeah. As I commented on the other series, as warnings reach upstream from different trees, the only sane way to fix them is by using linux-next.

I'll keep rebase those. This way, if something ends being lost, we could submit upstream by the end of the merge window.

Btw, as Andrii gently submitted a fix for the two remaining litmus doc warnings, once everything gets merged, htmldocs should now produce zero doc warnings.

I'll keep track on this. Hopefully, we can make 5.10 free of doc warnings, and build robots can start warning about newly introduced ones.

Thanks,
Mauro

Acked-by on v1 26/30
#29 lore raw

Re: [PATCH 26/30] iio: iio.h: fix a warning at the kernel-doc markup

In reply to Mauro Carvalho Chehab
Quoted 11 lines · On Wed, 9 Sep 2020 16:10:57 +0200 Mauro Carvalho Chehab…

There's a warning at iio.h kernel-doc markup:

./include/linux/iio/iio.h:644: WARNING: Unknown target name: "devm".

Because it is using {devm_}foo notation. Well, this is not a valid kernel-doc notation. Also, it prevents creating hyperlinks to other documentation functions.

So, replace it to a better notation.

Not much going on in that file at the moment, so fine if Jon picks this up directly.

Jonathan

Quoted 17 lines
---
 include/linux/iio/iio.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/iio/iio.h +1 -1
index e2df67a3b9ab..f1daaba9e706 100644
@@ -641,7 +641,7 @@ static inline struct iio_dev *iio_device_get(struct iio_dev *indio_dev)
  *
  * This utility must be called between IIO device allocation
  * (via devm_iio_device_alloc()) & IIO device registration
- * (via {devm_}iio_device_register()).
+ * (via iio_device_register() and devm_iio_device_register())).
  * By default, the device allocation will also assign a parent device to
  * the IIO device object. In cases where devm_iio_device_alloc() is used,
  * sometimes the parent device must be different than the device used to
maintainer
#30 lore raw

Re: [PATCH 26/30] iio: iio.h: fix a warning at the kernel-doc markup

Quoted 11 lines · On Fri, 11 Sep 2020 09:32:56 +0100 Jonathan Cameron…
Quoted 8 lines · On Wed, 9 Sep 2020 16:10:57 +0200 Mauro Carvalho Chehab…

There's a warning at iio.h kernel-doc markup:

./include/linux/iio/iio.h:644: WARNING: Unknown target name: "devm".

Because it is using {devm_}foo notation. Well, this is not a valid kernel-doc notation. Also, it prevents creating hyperlinks to other documentation functions.

Quoted 8 lines
Quoted 3 lines

So, replace it to a better notation.

Not much going on in that file at the moment, so fine if Jon picks this up directly.

OK, I've done that.

Thanks,

jon