docs: fix documentation build parsing errors
Subsystems (34)
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
PATCH 1/30 .gitignore: docs: ignore sphinx_*/ directories
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
@@ -152,3 +152,6 @@ x509.genkey # Clang's compilation database file /compile_commands.json + +# Documentation toolchain +sphinx_*/
Signature · 1 line
2.26.2
Re: [PATCH 01/30] .gitignore: docs: ignore sphinx_*/ directories
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.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
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
PATCH 2/30 kernel-doc: include line numbers for function prototypes
In reply to Mauro Carvalho ChehabThis 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
@@ -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
PATCH 3/30 dt-bindings: fix references to files converted to yaml
In reply to Mauro Carvalho ChehabThere 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
PATCH 4/30 docs: hwmon: adm1266.rst: fix a broken reference
In reply to Mauro Carvalho ChehabThe 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
@@ -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
PATCH 5/30 docs: scheduler: fix the directory name on two files
In reply to Mauro Carvalho ChehabThe 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
@@ -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
@@ -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
Re: [PATCH 05/30] docs: scheduler: fix the directory name on two files
(+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.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
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@@ -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@@ -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
PATCH 6/30 docs: trace: fix the location of kprobes.rst
In reply to Mauro Carvalho ChehabThis patch was moved out of staging.
--- 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
@@ -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
@@ -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
@@ -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
PATCH 7/30 MAINTAINERS: fix location of qlogic/LICENSE.qla3xxx
In reply to Mauro Carvalho Chehabethernet/qlogic/LICENSE.qla3xxx -> qlogic/LICENSE.qla3xxx
--- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
MAINTAINERS +1 -1
@@ -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
PATCH 8/30 docs: fix location of nommu-mmap.rst file
In reply to Mauro Carvalho Chehabmm/nommu-mmap.rst -> admin-guide/mm/ nommu-mmap.rst
--- init/Kconfig | 2 +- mm/Kconfig | 2 +- mm/nommu.c | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-)
init/Kconfig +1 -1
@@ -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
@@ -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
@@ -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
PATCH 9/30 net: appletalk: Kconfig: Fix docs location
In reply to Mauro Carvalho ChehabThe location of ltpc.rst changed. Update it at Kconfig.
--- drivers/net/appletalk/Kconfig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/net/appletalk/Kconfig +1 -1
@@ -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
PATCH 10/30 drivers: net: hamradio: fix document location
In reply to Mauro Carvalho ChehabThe hamradio docs were moved to a different dir.
Update its location accordingly.
--- drivers/net/hamradio/scc.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/net/hamradio/scc.c +1 -1
@@ -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
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
@@ -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
@@ -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
PATCH 12/30 scripts: device_attr_show.cocci: update location of sysfs doc
In reply to Mauro Carvalho Chehabsysfs.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
@@ -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
PATCH 13/30 docs: SafeSetID: fix a warning
In reply to Mauro Carvalho ChehabAs 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
@@ -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
PATCH 14/30 docs: add some new files to their respective index.rst files
In reply to Mauro Carvalho ChehabThere 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
@@ -10,3 +10,4 @@ Non-Volatile Memory Device (NVDIMM) nvdimm btt security + firmware-activate
Documentation/firmware-guide/acpi/index.rst +1 -0
@@ -26,3 +26,4 @@ ACPI Support lpit video_extension extcon-intel-int3496 + intel-pmc-mux
Documentation/hwmon/index.rst +1 -0
@@ -159,6 +159,7 @@ Hardware Monitoring Kernel Drivers smsc47b397 smsc47m192 smsc47m1 + sparx5-temp tc654 tc74 thmc50
Documentation/vm/index.rst +1 -0
@@ -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
PATCH 15/30 docs: powerpc: syscall64-abi.rst: fix a malformed table
In reply to Mauro Carvalho ChehabAs 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
@@ -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
PATCH 16/30 docs: watch_queue: fix some warnings
In reply to Mauro Carvalho ChehabFix 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
@@ -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
PATCH 17/30 docs: kvm: api.rst: add missing spaces
In reply to Mauro Carvalho ChehabThere 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
@@ -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
PATCH 18/30 block: bio: fix a warning at the kernel-doc markups
In reply to Mauro Carvalho ChehabUsing "@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
@@ -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
PATCH 19/30 docs: soundwire: fix some identation at stream.rst
In reply to Mauro Carvalho ChehabCurrently, 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
@@ -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
PATCH 20/30 docs: dma-buf: fix some warnings
In reply to Mauro Carvalho ChehabFix 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
@@ -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
PATCH 21/30 iio: industrialio-core.c: solve a kernel-doc warning
In reply to Mauro Carvalho Chehabkernel-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
@@ -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
PATCH 22/30 kunit: test.h: solve kernel-doc warnings
In reply to Mauro Carvalho ChehabThere 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
@@ -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
PATCH 23/30 docs: submitting-patches: use :doc: for references
In reply to Mauro Carvalho ChehabThere 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
@@ -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
PATCH 24/30 docs: lockdep-design: fix some warning issues
In reply to Mauro Carvalho ChehabThere are several warnings caused by a recent change224ec489d3cd ("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.
--- Documentation/locking/lockdep-design.rst | 69 ++++++++++++++---------- 1 file changed, 40 insertions(+), 29 deletions(-)
Documentation/locking/lockdep-design.rst +40 -29
@@ -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
PATCH 25/30 docs: admin-guide: net.rst: add a missing blank line
In reply to Mauro Carvalho ChehabThere'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
@@ -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
PATCH 26/30 iio: iio.h: fix a warning at the kernel-doc markup
In reply to Mauro Carvalho ChehabThere'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
@@ -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
Re: [PATCH 26/30] iio: iio.h: fix a warning at the kernel-doc markup
Quoted 11 lines · On Wed, 9 Sep 2020 16:10:57 +0200 Mauro Carvalho Chehab…
There's a warning at
iio.hkernel-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.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
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@@ -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
Jonathan Corbet
maintainerRe: [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.hkernel-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.
Signed-off-by Mauro Carvalho Chehab <[email protected]>Acked-by Jonathan Cameron <[email protected]>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
PATCH 27/30 docs: bio: fix a kerneldoc markup
In reply to Mauro Carvalho ChehabFix 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
@@ -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
PATCH 28/30 drivers: core: fix kernel-doc markup for dev_err_probe()
In reply to Mauro Carvalho ChehabThere 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.
--- drivers/base/core.c | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-)
drivers/base/core.c +5 -2
@@ -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
PATCH 29/30 kunit: test.h: fix a bad kernel-doc markup
In reply to Mauro Carvalho ChehabAs 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
@@ -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
PATCH 30/30 docs: amdgpu: fix a warning when building the documentation
In reply to Mauro Carvalho ChehabAs 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
@@ -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
Jonathan Corbet
maintainerQuoted 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
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