From e814bccbafece52a24e152d2395b5d49eef55841 Mon Sep 17 00:00:00 2001 From: Will Deacon Date: Wed, 29 Nov 2017 15:20:03 +0000 Subject: [PATCH 1/5] scripts/kernel-doc: Don't fail with status != 0 if error encountered with -none My bisect scripts starting running into build failures when trying to compile 4.15-rc1 with the builds failing with things like: drivers/net/wireless/broadcom/brcm80211/brcmfmac/sdio.c:2078: error: Cannot parse struct or union! The line in question is actually just a #define, but after some digging it turns out that my scripts pass W=1 and since commit 3a025e1d1c2ea ("Add optional check for bad kernel-doc comments") that results in kernel-doc running on each source file. The file in question has a badly formatted comment immediately before the #define: /** * struct brcmf_skbuff_cb reserves first two bytes in sk_buff::cb for * bus layer usage. */ which causes the regex in dump_struct to fail (lack of braces following struct declaration) and kernel-doc returns 1, which causes the build to fail. Fix the issue by always returning 0 from kernel-doc when invoked with -none. It successfully generates no documentation, and prints out any issues. Cc: Matthew Wilcox Cc: Jonathan Corbet Signed-off-by: Will Deacon Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index bd29a92b4b48..df0f045a9a89 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -3248,4 +3248,4 @@ if ($verbose && $warnings) { print STDERR "$warnings warnings\n"; } -exit($errors); +exit($output_mode eq "none" ? 0 : $errors); From e50806a9fd0132402a62cb3161d786335662072f Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Wed, 29 Nov 2017 00:16:56 +0900 Subject: [PATCH 2/5] dmaengine: doc : Fix warning "Title underline too short" while make xmldocs This patch fix following warning during 'make xmldocs' Documentation/driver-api/dmaengine/client.rst:188: WARNING: Title underline too short. Further APIs: ------------ Signed-off-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/driver-api/dmaengine/client.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index 6245c99af8c1..fbbb2831f29f 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -185,7 +185,7 @@ The details of these operations are: void dma_async_issue_pending(struct dma_chan *chan); Further APIs: ------------- +------------- 1. Terminate APIs From 0f83aaa3c07a46b41b2d5d8ee6b88617eb2c2f09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Neusch=C3=A4fer?= Date: Tue, 28 Nov 2017 06:16:21 +0100 Subject: [PATCH 3/5] genericirq.rst: Remove :c:func:`...` in code blocks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In code blocks, :c:func:`...` annotations don't result in cross-references. Instead, they are rendered verbatim. Remove these broken annotations, and mark function calls with parentheses() again. Fixes: 76d40fae1351 ("genericirq.rst: add cross-reference links and use monospaced fonts") Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/core-api/genericirq.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 0054bd48be84..4da67b65cecf 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -225,9 +225,9 @@ interrupts. The following control flow is implemented (simplified excerpt):: - :c:func:`desc->irq_data.chip->irq_mask_ack`; + desc->irq_data.chip->irq_mask_ack(); handle_irq_event(desc->action); - :c:func:`desc->irq_data.chip->irq_unmask`; + desc->irq_data.chip->irq_unmask(); Default Fast EOI IRQ flow handler @@ -239,7 +239,7 @@ which only need an EOI at the end of the handler. The following control flow is implemented (simplified excerpt):: handle_irq_event(desc->action); - :c:func:`desc->irq_data.chip->irq_eoi`; + desc->irq_data.chip->irq_eoi(); Default Edge IRQ flow handler @@ -251,15 +251,15 @@ interrupts. The following control flow is implemented (simplified excerpt):: if (desc->status & running) { - :c:func:`desc->irq_data.chip->irq_mask_ack`; + desc->irq_data.chip->irq_mask_ack(); desc->status |= pending | masked; return; } - :c:func:`desc->irq_data.chip->irq_ack`; + desc->irq_data.chip->irq_ack(); desc->status |= running; do { if (desc->status & masked) - :c:func:`desc->irq_data.chip->irq_unmask`; + desc->irq_data.chip->irq_unmask(); desc->status &= ~pending; handle_irq_event(desc->action); } while (status & pending); @@ -293,10 +293,10 @@ simplified version without locking. The following control flow is implemented (simplified excerpt):: if (desc->irq_data.chip->irq_ack) - :c:func:`desc->irq_data.chip->irq_ack`; + desc->irq_data.chip->irq_ack(); handle_irq_event(desc->action); if (desc->irq_data.chip->irq_eoi) - :c:func:`desc->irq_data.chip->irq_eoi`; + desc->irq_data.chip->irq_eoi(); EOI Edge IRQ flow handler From a08415ea2a8b3f0173fd0612317d5cba5b57fedb Mon Sep 17 00:00:00 2001 From: John Pittman Date: Wed, 22 Nov 2017 12:56:22 -0500 Subject: [PATCH 4/5] scsi: documentation: Fix case of 'scsi_device' struct mention(s) In scsi_mid_low_api.txt a the scsi_device structure is mentioned several times, but the leading 's' is uppercase (Scsi_device) and should be lowercase (scsi_device). Fixed by this commit. Signed-off-by: John Pittman Signed-off-by: Jonathan Corbet --- Documentation/scsi/scsi_mid_low_api.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 6338400eed73..2c31d9ee6776 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -319,12 +319,12 @@ struct Scsi_Host: instance. If the reference count reaches 0 then the given instance is freed -The Scsi_device structure has had reference counting infrastructure added. -This effectively spreads the ownership of struct Scsi_device instances +The scsi_device structure has had reference counting infrastructure added. +This effectively spreads the ownership of struct scsi_device instances across the various SCSI layers which use them. Previously such instances were exclusively owned by the mid level. See the access functions declared towards the end of include/scsi/scsi_device.h . If an LLD wants to keep -a copy of a pointer to a Scsi_device instance it should use scsi_device_get() +a copy of a pointer to a scsi_device instance it should use scsi_device_get() to bump its reference count. When it is finished with the pointer it can use scsi_device_put() to decrement its reference count (and potentially delete it). From 9956cfef3409177d9e24ea4b7910148a18073a6f Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 3 Dec 2017 13:15:39 -0800 Subject: [PATCH 5/5] Documentation: fix docs build error after source file removed The pci/htirq.c file was removed so remove it from the documentation file also. Error: Cannot open file ../drivers/pci/htirq.c WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno -export ../drivers/pci/htirq.c' failed with return code 2 Fixes: fd2fa6c18b72 ("x86/PCI: Remove unused HyperTransport interrupt support") Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet --- Documentation/driver-api/pci.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Documentation/driver-api/pci.rst b/Documentation/driver-api/pci.rst index 01a6c8b7d3a7..ca85e5e78b2c 100644 --- a/Documentation/driver-api/pci.rst +++ b/Documentation/driver-api/pci.rst @@ -25,9 +25,6 @@ PCI Support Library .. kernel-doc:: drivers/pci/irq.c :export: -.. kernel-doc:: drivers/pci/htirq.c - :export: - .. kernel-doc:: drivers/pci/probe.c :export: