[PATCH 00/17] Address several documentation build warnings

[PATCH 00/17] Address several documentation build warnings

[Mauro Carvalho Chehab]

This patch series is against next-20200317. It addresses several warnings on
random places.

It is worth noticing patch 07/17: It changes kernel-doc parser to accept a
very common pattern on kernel-doc markups. This reduces a lot of
warnings all over the tree.

The remaining patches are just random fixes with the hope to address most
warnings that are shown in red when building the documentation.

Mauro Carvalho Chehab (17):
  docs: amu: supress some Sphinx warnings
  docs: arm64: booting.rst: get rid of some warnings
  docs: pci: boot-interrupts.rst: improve html output
  kernel: futex.c: get rid of a docs build warning
  devfreq: devfreq.h: get rid of some doc warnings
  firewire: firewire-cdev.hL get rid of a docs warning
  scripts: kernel-doc: proper handle @foo->bar()
  lib: bitmap.c: get rid of some doc warnings
  rcu: update.c: get rid of some doc warnings
  net: phy: sfp-bus.c: get rid of docs warnings
  net: core: dev.c: fix a documentation warning
  gpio: gpiolib.c: fix a doc warning
  i2c: include/linux/i2c.h: fix a doc warning
  infiniband: pa_vnic_encap.h: get rid of a warning
  ata: libata-core: fix a doc warning
  fs: inode.c: get rid of docs warnings
  regulator: driver.h: fix regulator_map_* function names

 Documentation/PCI/boot-interrupts.rst         | 34 ++++++++++--------
 Documentation/arm64/amu.rst                   |  5 +++
 Documentation/arm64/booting.rst               | 36 +++++++++++--------
 drivers/ata/libata-core.c                     |  2 +-
 drivers/gpio/gpiolib.c                        |  2 +-
 .../infiniband/ulp/opa_vnic/opa_vnic_encap.h  |  2 +-
 drivers/net/phy/sfp-bus.c                     | 32 +++++++++--------
 fs/inode.c                                    |  6 ++--
 include/linux/devfreq.h                       |  6 ++--
 include/linux/i2c.h                           |  4 +--
 include/linux/regulator/driver.h              |  4 +--
 include/uapi/linux/firewire-cdev.h            |  2 +-
 kernel/futex.c                                |  3 +-
 kernel/rcu/update.c                           |  8 ++---
 lib/bitmap.c                                  | 27 +++++++-------
 net/core/dev.c                                |  2 +-
 scripts/kernel-doc                            |  2 ++
 17 files changed, 101 insertions(+), 76 deletions(-)

-- 
2.24.1

[PATCH 00/17] Address several documentation build warnings

[Mauro Carvalho Chehab]

This patch series is against next-20200317. It addresses several warnings on
random places.

It is worth noticing patch 07/17: It changes kernel-doc parser to accept a
very common pattern on kernel-doc markups. This reduces a lot of
warnings all over the tree.

The remaining patches are just random fixes with the hope to address most
warnings that are shown in red when building the documentation.

Mauro Carvalho Chehab (17):
  docs: amu: supress some Sphinx warnings
  docs: arm64: booting.rst: get rid of some warnings
  docs: pci: boot-interrupts.rst: improve html output
  kernel: futex.c: get rid of a docs build warning
  devfreq: devfreq.h: get rid of some doc warnings
  firewire: firewire-cdev.hL get rid of a docs warning
  scripts: kernel-doc: proper handle @foo->bar()
  lib: bitmap.c: get rid of some doc warnings
  rcu: update.c: get rid of some doc warnings
  net: phy: sfp-bus.c: get rid of docs warnings
  net: core: dev.c: fix a documentation warning
  gpio: gpiolib.c: fix a doc warning
  i2c: include/linux/i2c.h: fix a doc warning
  infiniband: pa_vnic_encap.h: get rid of a warning
  ata: libata-core: fix a doc warning
  fs: inode.c: get rid of docs warnings
  regulator: driver.h: fix regulator_map_* function names

 Documentation/PCI/boot-interrupts.rst         | 34 ++++++++++--------
 Documentation/arm64/amu.rst                   |  5 +++
 Documentation/arm64/booting.rst               | 36 +++++++++++--------
 drivers/ata/libata-core.c                     |  2 +-
 drivers/gpio/gpiolib.c                        |  2 +-
 .../infiniband/ulp/opa_vnic/opa_vnic_encap.h  |  2 +-
 drivers/net/phy/sfp-bus.c                     | 32 +++++++++--------
 fs/inode.c                                    |  6 ++--
 include/linux/devfreq.h                       |  6 ++--
 include/linux/i2c.h                           |  4 +--
 include/linux/regulator/driver.h              |  4 +--
 include/uapi/linux/firewire-cdev.h            |  2 +-
 kernel/futex.c                                |  3 +-
 kernel/rcu/update.c                           |  8 ++---
 lib/bitmap.c                                  | 27 +++++++-------
 net/core/dev.c                                |  2 +-
 scripts/kernel-doc                            |  2 ++
 17 files changed, 101 insertions(+), 76 deletions(-)

-- 
2.24.1



_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

[PATCH 01/17] docs: amu: supress some Sphinx warnings

[Mauro Carvalho Chehab]

Add extra blank lines on some places, in order to avoid those
warnings when building the docs:

    Documentation/arm64/amu.rst:26: WARNING: Unexpected indentation.
    Documentation/arm64/amu.rst:60: WARNING: Unexpected indentation.
    Documentation/arm64/amu.rst:81: WARNING: Unexpected indentation.
    Documentation/arm64/amu.rst:108: WARNING: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/arm64/amu.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/arm64/amu.rst b/Documentation/arm64/amu.rst
index 5057b11100ed..452ec8b115c2 100644
--- a/Documentation/arm64/amu.rst
+++ b/Documentation/arm64/amu.rst
@@ -23,6 +23,7 @@ optional external memory-mapped interface.
 
 Version 1 of the Activity Monitors architecture implements a counter group
 of four fixed and architecturally defined 64-bit event counters.
+
   - CPU cycle counter: increments at the frequency of the CPU.
   - Constant counter: increments at the fixed frequency of the system
     clock.
@@ -57,6 +58,7 @@ counters, only the presence of the extension.
 
 Firmware (code running at higher exception levels, e.g. arm-tf) support is
 needed to:
+
  - Enable access for lower exception levels (EL2 and EL1) to the AMU
    registers.
  - Enable the counters. If not enabled these will read as 0.
@@ -78,6 +80,7 @@ are not trapped in EL2/EL3.
 
 The fixed counters of AMUv1 are accessible though the following system
 register definitions:
+
  - SYS_AMEVCNTR0_CORE_EL0
  - SYS_AMEVCNTR0_CONST_EL0
  - SYS_AMEVCNTR0_INST_RET_EL0
@@ -93,6 +96,7 @@ Userspace access
 ----------------
 
 Currently, access from userspace to the AMU registers is disabled due to:
+
  - Security reasons: they might expose information about code executed in
    secure mode.
  - Purpose: AMU counters are intended for system management use.
@@ -105,6 +109,7 @@ Virtualization
 
 Currently, access from userspace (EL0) and kernelspace (EL1) on the KVM
 guest side is disabled due to:
+
  - Security reasons: they might expose information about code executed
    by other guests or the host.
 
-- 
2.24.1

[PATCH 01/17] docs: amu: supress some Sphinx warnings

[Mauro Carvalho Chehab]

Add extra blank lines on some places, in order to avoid those
warnings when building the docs:

    Documentation/arm64/amu.rst:26: WARNING: Unexpected indentation.
    Documentation/arm64/amu.rst:60: WARNING: Unexpected indentation.
    Documentation/arm64/amu.rst:81: WARNING: Unexpected indentation.
    Documentation/arm64/amu.rst:108: WARNING: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/arm64/amu.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/arm64/amu.rst b/Documentation/arm64/amu.rst
index 5057b11100ed..452ec8b115c2 100644
--- a/Documentation/arm64/amu.rst
+++ b/Documentation/arm64/amu.rst
@@ -23,6 +23,7 @@ optional external memory-mapped interface.
 
 Version 1 of the Activity Monitors architecture implements a counter group
 of four fixed and architecturally defined 64-bit event counters.
+
   - CPU cycle counter: increments at the frequency of the CPU.
   - Constant counter: increments at the fixed frequency of the system
     clock.
@@ -57,6 +58,7 @@ counters, only the presence of the extension.
 
 Firmware (code running at higher exception levels, e.g. arm-tf) support is
 needed to:
+
  - Enable access for lower exception levels (EL2 and EL1) to the AMU
    registers.
  - Enable the counters. If not enabled these will read as 0.
@@ -78,6 +80,7 @@ are not trapped in EL2/EL3.
 
 The fixed counters of AMUv1 are accessible though the following system
 register definitions:
+
  - SYS_AMEVCNTR0_CORE_EL0
  - SYS_AMEVCNTR0_CONST_EL0
  - SYS_AMEVCNTR0_INST_RET_EL0
@@ -93,6 +96,7 @@ Userspace access
 ----------------
 
 Currently, access from userspace to the AMU registers is disabled due to:
+
  - Security reasons: they might expose information about code executed in
    secure mode.
  - Purpose: AMU counters are intended for system management use.
@@ -105,6 +109,7 @@ Virtualization
 
 Currently, access from userspace (EL0) and kernelspace (EL1) on the KVM
 guest side is disabled due to:
+
  - Security reasons: they might expose information about code executed
    by other guests or the host.
 
-- 
2.24.1


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

[PATCH 02/17] docs: arm64: booting.rst: get rid of some warnings

[Mauro Carvalho Chehab]

Get rid of those warnings:

    Documentation/arm64/booting.rst:253: WARNING: Unexpected indentation.
    Documentation/arm64/booting.rst:259: WARNING: Block quote ends without a blank line; unexpected unindent.

By adding an extra blank lines where needed.

While here, use list markups on some places, as otherwise Sphinx
will consider the next lines as continuation of the privious ones.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/arm64/booting.rst | 36 ++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/Documentation/arm64/booting.rst b/Documentation/arm64/booting.rst
index a3f1a47b6f1c..e50186092948 100644
--- a/Documentation/arm64/booting.rst
+++ b/Documentation/arm64/booting.rst
@@ -173,7 +173,9 @@ Before jumping into the kernel, the following conditions must be met:
 - Caches, MMUs
 
   The MMU must be off.
+
   Instruction cache may be on or off.
+
   The address range corresponding to the loaded kernel image must be
   cleaned to the PoC. In the presence of a system cache or other
   coherent masters with caches enabled, this will typically require
@@ -238,6 +240,7 @@ Before jumping into the kernel, the following conditions must be met:
   - The DT or ACPI tables must describe a GICv2 interrupt controller.
 
   For CPUs with pointer authentication functionality:
+
   - If EL3 is present:
 
     - SCR_EL3.APK (bit 16) must be initialised to 0b1
@@ -249,18 +252,22 @@ Before jumping into the kernel, the following conditions must be met:
     - HCR_EL2.API (bit 41) must be initialised to 0b1
 
   For CPUs with Activity Monitors Unit v1 (AMUv1) extension present:
+
   - If EL3 is present:
-    CPTR_EL3.TAM (bit 30) must be initialised to 0b0
-    CPTR_EL2.TAM (bit 30) must be initialised to 0b0
-    AMCNTENSET0_EL0 must be initialised to 0b1111
-    AMCNTENSET1_EL0 must be initialised to a platform specific value
-    having 0b1 set for the corresponding bit for each of the auxiliary
-    counters present.
+
+    - CPTR_EL3.TAM (bit 30) must be initialised to 0b0
+    - CPTR_EL2.TAM (bit 30) must be initialised to 0b0
+    - AMCNTENSET0_EL0 must be initialised to 0b1111
+    - AMCNTENSET1_EL0 must be initialised to a platform specific value
+      having 0b1 set for the corresponding bit for each of the auxiliary
+      counters present.
+
   - If the kernel is entered at EL1:
-    AMCNTENSET0_EL0 must be initialised to 0b1111
-    AMCNTENSET1_EL0 must be initialised to a platform specific value
-    having 0b1 set for the corresponding bit for each of the auxiliary
-    counters present.
+
+    - AMCNTENSET0_EL0 must be initialised to 0b1111
+    - AMCNTENSET1_EL0 must be initialised to a platform specific value
+      having 0b1 set for the corresponding bit for each of the auxiliary
+      counters present.
 
 The requirements described above for CPU mode, caches, MMUs, architected
 timers, coherency and system registers apply to all CPUs.  All CPUs must
@@ -304,7 +311,8 @@ following manner:
   Documentation/devicetree/bindings/arm/psci.yaml.
 
 - Secondary CPU general-purpose register settings
-  x0 = 0 (reserved for future use)
-  x1 = 0 (reserved for future use)
-  x2 = 0 (reserved for future use)
-  x3 = 0 (reserved for future use)
+
+  - x0 = 0 (reserved for future use)
+  - x1 = 0 (reserved for future use)
+  - x2 = 0 (reserved for future use)
+  - x3 = 0 (reserved for future use)
-- 
2.24.1

[PATCH 02/17] docs: arm64: booting.rst: get rid of some warnings

[Mauro Carvalho Chehab]

Get rid of those warnings:

    Documentation/arm64/booting.rst:253: WARNING: Unexpected indentation.
    Documentation/arm64/booting.rst:259: WARNING: Block quote ends without a blank line; unexpected unindent.

By adding an extra blank lines where needed.

While here, use list markups on some places, as otherwise Sphinx
will consider the next lines as continuation of the privious ones.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/arm64/booting.rst | 36 ++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/Documentation/arm64/booting.rst b/Documentation/arm64/booting.rst
index a3f1a47b6f1c..e50186092948 100644
--- a/Documentation/arm64/booting.rst
+++ b/Documentation/arm64/booting.rst
@@ -173,7 +173,9 @@ Before jumping into the kernel, the following conditions must be met:
 - Caches, MMUs
 
   The MMU must be off.
+
   Instruction cache may be on or off.
+
   The address range corresponding to the loaded kernel image must be
   cleaned to the PoC. In the presence of a system cache or other
   coherent masters with caches enabled, this will typically require
@@ -238,6 +240,7 @@ Before jumping into the kernel, the following conditions must be met:
   - The DT or ACPI tables must describe a GICv2 interrupt controller.
 
   For CPUs with pointer authentication functionality:
+
   - If EL3 is present:
 
     - SCR_EL3.APK (bit 16) must be initialised to 0b1
@@ -249,18 +252,22 @@ Before jumping into the kernel, the following conditions must be met:
     - HCR_EL2.API (bit 41) must be initialised to 0b1
 
   For CPUs with Activity Monitors Unit v1 (AMUv1) extension present:
+
   - If EL3 is present:
-    CPTR_EL3.TAM (bit 30) must be initialised to 0b0
-    CPTR_EL2.TAM (bit 30) must be initialised to 0b0
-    AMCNTENSET0_EL0 must be initialised to 0b1111
-    AMCNTENSET1_EL0 must be initialised to a platform specific value
-    having 0b1 set for the corresponding bit for each of the auxiliary
-    counters present.
+
+    - CPTR_EL3.TAM (bit 30) must be initialised to 0b0
+    - CPTR_EL2.TAM (bit 30) must be initialised to 0b0
+    - AMCNTENSET0_EL0 must be initialised to 0b1111
+    - AMCNTENSET1_EL0 must be initialised to a platform specific value
+      having 0b1 set for the corresponding bit for each of the auxiliary
+      counters present.
+
   - If the kernel is entered at EL1:
-    AMCNTENSET0_EL0 must be initialised to 0b1111
-    AMCNTENSET1_EL0 must be initialised to a platform specific value
-    having 0b1 set for the corresponding bit for each of the auxiliary
-    counters present.
+
+    - AMCNTENSET0_EL0 must be initialised to 0b1111
+    - AMCNTENSET1_EL0 must be initialised to a platform specific value
+      having 0b1 set for the corresponding bit for each of the auxiliary
+      counters present.
 
 The requirements described above for CPU mode, caches, MMUs, architected
 timers, coherency and system registers apply to all CPUs.  All CPUs must
@@ -304,7 +311,8 @@ following manner:
   Documentation/devicetree/bindings/arm/psci.yaml.
 
 - Secondary CPU general-purpose register settings
-  x0 = 0 (reserved for future use)
-  x1 = 0 (reserved for future use)
-  x2 = 0 (reserved for future use)
-  x3 = 0 (reserved for future use)
+
+  - x0 = 0 (reserved for future use)
+  - x1 = 0 (reserved for future use)
+  - x2 = 0 (reserved for future use)
+  - x3 = 0 (reserved for future use)
-- 
2.24.1


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

[PATCH 03/17] docs: pci: boot-interrupts.rst: improve html output

[Mauro Carvalho Chehab]

There are some warnings with this file:

    /Documentation/PCI/boot-interrupts.rst:42: WARNING: Unexpected indentation.
    /Documentation/PCI/boot-interrupts.rst:52: WARNING: Block quote ends without a blank line; unexpected unindent.
    /Documentation/PCI/boot-interrupts.rst:92: WARNING: Unexpected indentation.
    /Documentation/PCI/boot-interrupts.rst:98: WARNING: Unexpected indentation.
    /Documentation/PCI/boot-interrupts.rst:136: WARNING: Unexpected indentation.

It turns that this file conversion to ReST could be improved,
in order to remove the warnings and provide a better output.

So, fix the warnings by adjusting blank lines, add a table and
some list markups. Also, mark endnodes as such.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/PCI/boot-interrupts.rst | 34 +++++++++++++++------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/Documentation/PCI/boot-interrupts.rst b/Documentation/PCI/boot-interrupts.rst
index d078ef3eb192..2ec70121bfca 100644
--- a/Documentation/PCI/boot-interrupts.rst
+++ b/Documentation/PCI/boot-interrupts.rst
@@ -32,12 +32,13 @@ interrupt goes unhandled over time, they are tracked by the Linux kernel as
 Spurious Interrupts. The IRQ will be disabled by the Linux kernel after it
 reaches a specific count with the error "nobody cared". This disabled IRQ
 now prevents valid usage by an existing interrupt which may happen to share
-the IRQ line.
+the IRQ line::
 
   irq 19: nobody cared (try booting with the "irqpoll" option)
   CPU: 0 PID: 2988 Comm: irq/34-nipalk Tainted: 4.14.87-rt49-02410-g4a640ec-dirty #1
   Hardware name: National Instruments NI PXIe-8880/NI PXIe-8880, BIOS 2.1.5f1 01/09/2020
   Call Trace:
+
   <IRQ>
    ? dump_stack+0x46/0x5e
    ? __report_bad_irq+0x2e/0xb0
@@ -85,15 +86,18 @@ Mitigations
 The mitigations take the form of PCI quirks. The preference has been to
 first identify and make use of a means to disable the routing to the PCH.
 In such a case a quirk to disable boot interrupt generation can be
-added.[1]
+added. [1]_
 
-  Intel® 6300ESB I/O Controller Hub
+Intel® 6300ESB I/O Controller Hub
   Alternate Base Address Register:
    BIE: Boot Interrupt Enable
-	  0 = Boot interrupt is enabled.
-	  1 = Boot interrupt is disabled.
 
-  Intel® Sandy Bridge through Sky Lake based Xeon servers:
+	  ==  ===========================
+	  0   Boot interrupt is enabled.
+	  1   Boot interrupt is disabled.
+	  ==  ===========================
+
+Intel® Sandy Bridge through Sky Lake based Xeon servers:
   Coherent Interface Protocol Interrupt Control
    dis_intx_route2pch/dis_intx_route2ich/dis_intx_route2dmi2:
 	  When this bit is set. Local INTx messages received from the
@@ -109,12 +113,12 @@ line by default.  Therefore, on chipsets where this INTx routing cannot be
 disabled, the Linux kernel will reroute the valid interrupt to its legacy
 interrupt. This redirection of the handler will prevent the occurrence of
 the spurious interrupt detection which would ordinarily disable the IRQ
-line due to excessive unhandled counts.[2]
+line due to excessive unhandled counts. [2]_
 
 The config option X86_REROUTE_FOR_BROKEN_BOOT_IRQS exists to enable (or
 disable) the redirection of the interrupt handler to the PCH interrupt
 line. The option can be overridden by either pci=ioapicreroute or
-pci=noioapicreroute.[3]
+pci=noioapicreroute. [3]_
 
 
 More Documentation
@@ -127,19 +131,19 @@ into the evolution of its handling with chipsets.
 Example of disabling of the boot interrupt
 ------------------------------------------
 
-Intel® 6300ESB I/O Controller Hub (Document # 300641-004US)
+      - Intel® 6300ESB I/O Controller Hub (Document # 300641-004US)
 	5.7.3 Boot Interrupt
 	https://www.intel.com/content/dam/doc/datasheet/6300esb-io-controller-hub-datasheet.pdf
 
-Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families
-Datasheet - Volume 2: Registers (Document # 330784-003)
+      - Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families
+	Datasheet - Volume 2: Registers (Document # 330784-003)
 	6.6.41 cipintrc Coherent Interface Protocol Interrupt Control
 	https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/xeon-e5-v3-datasheet-vol-2.pdf
 
 Example of handler rerouting
 ----------------------------
 
-Intel® 6700PXH 64-bit PCI Hub (Document # 302628)
+      - Intel® 6700PXH 64-bit PCI Hub (Document # 302628)
 	2.15.2 PCI Express Legacy INTx Support and Boot Interrupt
 	https://www.intel.com/content/dam/doc/datasheet/6700pxh-64-bit-pci-hub-datasheet.pdf
 
@@ -150,6 +154,6 @@ Cheers,
     Sean V Kelley
     sean.v.kelley@linux.intel.com
 
-[1] https://lore.kernel.org/r/12131949181903-git-send-email-sassmann@suse.de/
-[2] https://lore.kernel.org/r/12131949182094-git-send-email-sassmann@suse.de/
-[3] https://lore.kernel.org/r/487C8EA7.6020205@suse.de/
+.. [1] https://lore.kernel.org/r/12131949181903-git-send-email-sassmann@suse.de/
+.. [2] https://lore.kernel.org/r/12131949182094-git-send-email-sassmann@suse.de/
+.. [3] https://lore.kernel.org/r/487C8EA7.6020205@suse.de/
-- 
2.24.1

Re: [PATCH 03/17] docs: pci: boot-interrupts.rst: improve html output

[Bjorn Helgaas]

On Tue, Mar 17, 2020 at 03:54:12PM +0100, Mauro Carvalho Chehab wrote:
> There are some warnings with this file:
> 
>     /Documentation/PCI/boot-interrupts.rst:42: WARNING: Unexpected indentation.
>     /Documentation/PCI/boot-interrupts.rst:52: WARNING: Block quote ends without a blank line; unexpected unindent.
>     /Documentation/PCI/boot-interrupts.rst:92: WARNING: Unexpected indentation.
>     /Documentation/PCI/boot-interrupts.rst:98: WARNING: Unexpected indentation.
>     /Documentation/PCI/boot-interrupts.rst:136: WARNING: Unexpected indentation.
> 
> It turns that this file conversion to ReST could be improved,
> in order to remove the warnings and provide a better output.
> 
> So, fix the warnings by adjusting blank lines, add a table and
> some list markups. Also, mark endnodes as such.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Bjorn Helgaas <bhelgaas@google.com>

> ---
>  Documentation/PCI/boot-interrupts.rst | 34 +++++++++++++++------------
>  1 file changed, 19 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/PCI/boot-interrupts.rst b/Documentation/PCI/boot-interrupts.rst
> index d078ef3eb192..2ec70121bfca 100644
> --- a/Documentation/PCI/boot-interrupts.rst
> +++ b/Documentation/PCI/boot-interrupts.rst
> @@ -32,12 +32,13 @@ interrupt goes unhandled over time, they are tracked by the Linux kernel as
>  Spurious Interrupts. The IRQ will be disabled by the Linux kernel after it
>  reaches a specific count with the error "nobody cared". This disabled IRQ
>  now prevents valid usage by an existing interrupt which may happen to share
> -the IRQ line.
> +the IRQ line::
>  
>    irq 19: nobody cared (try booting with the "irqpoll" option)
>    CPU: 0 PID: 2988 Comm: irq/34-nipalk Tainted: 4.14.87-rt49-02410-g4a640ec-dirty #1
>    Hardware name: National Instruments NI PXIe-8880/NI PXIe-8880, BIOS 2.1.5f1 01/09/2020
>    Call Trace:
> +
>    <IRQ>
>     ? dump_stack+0x46/0x5e
>     ? __report_bad_irq+0x2e/0xb0
> @@ -85,15 +86,18 @@ Mitigations
>  The mitigations take the form of PCI quirks. The preference has been to
>  first identify and make use of a means to disable the routing to the PCH.
>  In such a case a quirk to disable boot interrupt generation can be
> -added.[1]
> +added. [1]_
>  
> -  Intel® 6300ESB I/O Controller Hub
> +Intel® 6300ESB I/O Controller Hub
>    Alternate Base Address Register:
>     BIE: Boot Interrupt Enable
> -	  0 = Boot interrupt is enabled.
> -	  1 = Boot interrupt is disabled.
>  
> -  Intel® Sandy Bridge through Sky Lake based Xeon servers:
> +	  ==  ===========================
> +	  0   Boot interrupt is enabled.
> +	  1   Boot interrupt is disabled.
> +	  ==  ===========================
> +
> +Intel® Sandy Bridge through Sky Lake based Xeon servers:
>    Coherent Interface Protocol Interrupt Control
>     dis_intx_route2pch/dis_intx_route2ich/dis_intx_route2dmi2:
>  	  When this bit is set. Local INTx messages received from the
> @@ -109,12 +113,12 @@ line by default.  Therefore, on chipsets where this INTx routing cannot be
>  disabled, the Linux kernel will reroute the valid interrupt to its legacy
>  interrupt. This redirection of the handler will prevent the occurrence of
>  the spurious interrupt detection which would ordinarily disable the IRQ
> -line due to excessive unhandled counts.[2]
> +line due to excessive unhandled counts. [2]_
>  
>  The config option X86_REROUTE_FOR_BROKEN_BOOT_IRQS exists to enable (or
>  disable) the redirection of the interrupt handler to the PCH interrupt
>  line. The option can be overridden by either pci=ioapicreroute or
> -pci=noioapicreroute.[3]
> +pci=noioapicreroute. [3]_
>  
>  
>  More Documentation
> @@ -127,19 +131,19 @@ into the evolution of its handling with chipsets.
>  Example of disabling of the boot interrupt
>  ------------------------------------------
>  
> -Intel® 6300ESB I/O Controller Hub (Document # 300641-004US)
> +      - Intel® 6300ESB I/O Controller Hub (Document # 300641-004US)
>  	5.7.3 Boot Interrupt
>  	https://www.intel.com/content/dam/doc/datasheet/6300esb-io-controller-hub-datasheet.pdf
>  
> -Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families
> -Datasheet - Volume 2: Registers (Document # 330784-003)
> +      - Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families
> +	Datasheet - Volume 2: Registers (Document # 330784-003)
>  	6.6.41 cipintrc Coherent Interface Protocol Interrupt Control
>  	https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/xeon-e5-v3-datasheet-vol-2.pdf
>  
>  Example of handler rerouting
>  ----------------------------
>  
> -Intel® 6700PXH 64-bit PCI Hub (Document # 302628)
> +      - Intel® 6700PXH 64-bit PCI Hub (Document # 302628)
>  	2.15.2 PCI Express Legacy INTx Support and Boot Interrupt
>  	https://www.intel.com/content/dam/doc/datasheet/6700pxh-64-bit-pci-hub-datasheet.pdf
>  
> @@ -150,6 +154,6 @@ Cheers,
>      Sean V Kelley
>      sean.v.kelley@linux.intel.com
>  
> -[1] https://lore.kernel.org/r/12131949181903-git-send-email-sassmann@suse.de/
> -[2] https://lore.kernel.org/r/12131949182094-git-send-email-sassmann@suse.de/
> -[3] https://lore.kernel.org/r/487C8EA7.6020205@suse.de/
> +.. [1] https://lore.kernel.org/r/12131949181903-git-send-email-sassmann@suse.de/
> +.. [2] https://lore.kernel.org/r/12131949182094-git-send-email-sassmann@suse.de/
> +.. [3] https://lore.kernel.org/r/487C8EA7.6020205@suse.de/
> -- 
> 2.24.1
> 

[PATCH 04/17] kernel: futex.c: get rid of a docs build warning

[Mauro Carvalho Chehab]

Adjust whitespaces and blank lines in order to get rid of this:

	./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 kernel/futex.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/kernel/futex.c b/kernel/futex.c
index 67f004133061..dda6ddbc2e7d 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)
  * The key words are stored in @key on success.
  *
  * For shared mappings (when @fshared), the key is:
- *   ( inode->i_sequence, page->index, offset_within_page )
+ * ( inode->i_sequence, page->index, offset_within_page )
+ *
  * [ also see get_inode_sequence_number() ]
  *
  * For private mappings (or when !@fshared), the key is:
-- 
2.24.1

Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning

[Peter Zijlstra]

On Tue, Mar 17, 2020 at 03:54:13PM +0100, Mauro Carvalho Chehab wrote:
> Adjust whitespaces and blank lines in order to get rid of this:
> 
> 	./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  kernel/futex.c | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/kernel/futex.c b/kernel/futex.c
> index 67f004133061..dda6ddbc2e7d 100644
> --- a/kernel/futex.c
> +++ b/kernel/futex.c
> @@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)
>   * The key words are stored in @key on success.
>   *
>   * For shared mappings (when @fshared), the key is:
> - *   ( inode->i_sequence, page->index, offset_within_page )
> + * ( inode->i_sequence, page->index, offset_within_page )
> + *

WTH, that's less readable.

>   * [ also see get_inode_sequence_number() ]
>   *
>   * For private mappings (or when !@fshared), the key is:
> -- 
> 2.24.1
> 

Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning

[Jonathan Corbet]

On Tue, 17 Mar 2020 17:58:05 +0100
Peter Zijlstra <peterz@infradead.org> wrote:

> On Tue, Mar 17, 2020 at 03:54:13PM +0100, Mauro Carvalho Chehab wrote:
> > Adjust whitespaces and blank lines in order to get rid of this:
> > 
> > 	./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  kernel/futex.c | 3 ++-
> >  1 file changed, 2 insertions(+), 1 deletion(-)
> > 
> > diff --git a/kernel/futex.c b/kernel/futex.c
> > index 67f004133061..dda6ddbc2e7d 100644
> > --- a/kernel/futex.c
> > +++ b/kernel/futex.c
> > @@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)
> >   * The key words are stored in @key on success.
> >   *
> >   * For shared mappings (when @fshared), the key is:
> > - *   ( inode->i_sequence, page->index, offset_within_page )
> > + * ( inode->i_sequence, page->index, offset_within_page )
> > + *  
> 
> WTH, that's less readable.

It won't render well in the build either; that should be a literal block.

jon

Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning

[Peter Zijlstra]

On Tue, Mar 17, 2020 at 11:36:33AM -0600, Jonathan Corbet wrote:
> On Tue, 17 Mar 2020 17:58:05 +0100
> Peter Zijlstra <peterz@infradead.org> wrote:
> 
> > On Tue, Mar 17, 2020 at 03:54:13PM +0100, Mauro Carvalho Chehab wrote:
> > > Adjust whitespaces and blank lines in order to get rid of this:
> > > 
> > > 	./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > > ---
> > >  kernel/futex.c | 3 ++-
> > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > > 
> > > diff --git a/kernel/futex.c b/kernel/futex.c
> > > index 67f004133061..dda6ddbc2e7d 100644
> > > --- a/kernel/futex.c
> > > +++ b/kernel/futex.c
> > > @@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)
> > >   * The key words are stored in @key on success.
> > >   *
> > >   * For shared mappings (when @fshared), the key is:
> > > - *   ( inode->i_sequence, page->index, offset_within_page )
> > > + * ( inode->i_sequence, page->index, offset_within_page )
> > > + *  
> > 
> > WTH, that's less readable.
> 
> It won't render well in the build either; that should be a literal block.

it renders perfectly in an ASCII text editor, which is by far the most
important interface for all this.

Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning

[Thomas Gleixner]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

The subject prefix for this is: 'futex:'

> Adjust whitespaces and blank lines in order to get rid of this:
>
> 	./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  kernel/futex.c | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/kernel/futex.c b/kernel/futex.c
> index 67f004133061..dda6ddbc2e7d 100644
> --- a/kernel/futex.c
> +++ b/kernel/futex.c
> @@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)
>   * The key words are stored in @key on success.
>   *
>   * For shared mappings (when @fshared), the key is:
> - *   ( inode->i_sequence, page->index, offset_within_page )
> + * ( inode->i_sequence, page->index, offset_within_page )

Sigh. Is there no better way to make this look sane both in the file and
in the docs?

Thanks,

        tglx

Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning

[Jonathan Corbet]

On Fri, 20 Mar 2020 16:28:23 +0100
Thomas Gleixner <tglx@linutronix.de> wrote:

> >   * For shared mappings (when @fshared), the key is:
> > - *   ( inode->i_sequence, page->index, offset_within_page )
> > + * ( inode->i_sequence, page->index, offset_within_page )  
> 
> Sigh. Is there no better way to make this look sane both in the file and
> in the docs?

I'd do:

  * For shared mappings (when @fshared), the key is::
  *
  *   ( inode->i_sequence, page->index, offset_within_page )
  *

jon

Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning

[Mauro Carvalho Chehab]

Em Fri, 20 Mar 2020 16:28:23 +0100
Thomas Gleixner <tglx@linutronix.de> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> The subject prefix for this is: 'futex:'

Ok!

> 
> > Adjust whitespaces and blank lines in order to get rid of this:
> >
> > 	./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  kernel/futex.c | 3 ++-
> >  1 file changed, 2 insertions(+), 1 deletion(-)
> >
> > diff --git a/kernel/futex.c b/kernel/futex.c
> > index 67f004133061..dda6ddbc2e7d 100644
> > --- a/kernel/futex.c
> > +++ b/kernel/futex.c
> > @@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)
> >   * The key words are stored in @key on success.
> >   *
> >   * For shared mappings (when @fshared), the key is:
> > - *   ( inode->i_sequence, page->index, offset_within_page )
> > + * ( inode->i_sequence, page->index, offset_within_page )  
> 
> Sigh. Is there no better way to make this look sane both in the file and
> in the docs?

The enclosed patch would do the trick.

I noticed another problem on it, however: "!@fshared" is not properly
parsed by kernel-docs. It basically converts it to "!**fshared**", with is
not what we want.

IMHO, this specific case should be handled by kernel-doc script. I'll
write a patch addressing this issue.

Regards,
Mauro

---


[PATCH 04/17 v2] kernel: futex: get rid of a docs build warning

Adjust whitespaces and blank lines in order to get rid of this:

	./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/kernel/futex.c b/kernel/futex.c
index 67f004133061..81ad379cbadf 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -486,10 +486,13 @@ static u64 get_inode_sequence_number(struct inode *inode)
  * The key words are stored in @key on success.
  *
  * For shared mappings (when @fshared), the key is:
+ *
  *   ( inode->i_sequence, page->index, offset_within_page )
+ *
  * [ also see get_inode_sequence_number() ]
  *
  * For private mappings (or when !@fshared), the key is:
+ *
  *   ( current->mm, address, 0 )
  *
  * This allows (cross process, where applicable) identification of the futex

Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning

[Thomas Gleixner]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Em Fri, 20 Mar 2020 16:28:23 +0100
> Thomas Gleixner <tglx@linutronix.de> escreveu:
>
>> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>> 
>> The subject prefix for this is: 'futex:'
>
> Ok!
>
>> >   * For shared mappings (when @fshared), the key is:
>> > - *   ( inode->i_sequence, page->index, offset_within_page )
>> > + * ( inode->i_sequence, page->index, offset_within_page )  
>> 
>> Sigh. Is there no better way to make this look sane both in the file and
>> in the docs?
>
> The enclosed patch would do the trick.
>
>
> [PATCH 04/17 v2] kernel: futex: get rid of a docs build warning

The prefix is still wrong. See above.

git log --oneline $FILE usually gives you a pretty good hint.

Thanks,

        tglx

[PATCH 05/17] devfreq: devfreq.h: get rid of some doc warnings

[Mauro Carvalho Chehab]

Mark "void *data" as literal, in order to avoid those doc warnings:

	./include/linux/devfreq.h:156: WARNING: Inline emphasis start-string without end-string.
	./include/linux/devfreq.h:259: WARNING: Inline emphasis start-string without end-string.
	./include/linux/devfreq.h:279: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/devfreq.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/linux/devfreq.h b/include/linux/devfreq.h
index 82630fafacde..57e871a559a9 100644
--- a/include/linux/devfreq.h
+++ b/include/linux/devfreq.h
@@ -158,7 +158,7 @@ struct devfreq_stats {
  * functions except for the context of callbacks defined in struct
  * devfreq_governor, the governor should protect its access with the
  * struct mutex lock in struct devfreq. A governor may use this mutex
- * to protect its own private data in void *data as well.
+ * to protect its own private data in ``void *data`` as well.
  */
 struct devfreq {
 	struct list_head node;
@@ -256,7 +256,7 @@ struct devfreq *devfreq_get_devfreq_by_phandle(struct device *dev, int index);
 
 #if IS_ENABLED(CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND)
 /**
- * struct devfreq_simple_ondemand_data - void *data fed to struct devfreq
+ * struct devfreq_simple_ondemand_data - ``void *data`` fed to struct devfreq
  *	and devfreq_add_device
  * @upthreshold:	If the load is over this value, the frequency jumps.
  *			Specify 0 to use the default. Valid value = 0 to 100.
@@ -276,7 +276,7 @@ struct devfreq_simple_ondemand_data {
 
 #if IS_ENABLED(CONFIG_DEVFREQ_GOV_PASSIVE)
 /**
- * struct devfreq_passive_data - void *data fed to struct devfreq
+ * struct devfreq_passive_data - ``void *data`` fed to struct devfreq
  *	and devfreq_add_device
  * @parent:	the devfreq instance of parent device.
  * @get_target_freq:	Optional callback, Returns desired operating frequency
-- 
2.24.1

Re: [PATCH 05/17] devfreq: devfreq.h: get rid of some doc warnings

[Chanwoo Choi]

On 3/17/20 11:54 PM, Mauro Carvalho Chehab wrote:
> Mark "void *data" as literal, in order to avoid those doc warnings:
> 
> 	./include/linux/devfreq.h:156: WARNING: Inline emphasis start-string without end-string.
> 	./include/linux/devfreq.h:259: WARNING: Inline emphasis start-string without end-string.
> 	./include/linux/devfreq.h:279: WARNING: Inline emphasis start-string without end-string.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  include/linux/devfreq.h | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/include/linux/devfreq.h b/include/linux/devfreq.h
> index 82630fafacde..57e871a559a9 100644
> --- a/include/linux/devfreq.h
> +++ b/include/linux/devfreq.h
> @@ -158,7 +158,7 @@ struct devfreq_stats {
>   * functions except for the context of callbacks defined in struct
>   * devfreq_governor, the governor should protect its access with the
>   * struct mutex lock in struct devfreq. A governor may use this mutex
> - * to protect its own private data in void *data as well.
> + * to protect its own private data in ``void *data`` as well.
>   */
>  struct devfreq {
>  	struct list_head node;
> @@ -256,7 +256,7 @@ struct devfreq *devfreq_get_devfreq_by_phandle(struct device *dev, int index);
>  
>  #if IS_ENABLED(CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND)
>  /**
> - * struct devfreq_simple_ondemand_data - void *data fed to struct devfreq
> + * struct devfreq_simple_ondemand_data - ``void *data`` fed to struct devfreq
>   *	and devfreq_add_device
>   * @upthreshold:	If the load is over this value, the frequency jumps.
>   *			Specify 0 to use the default. Valid value = 0 to 100.
> @@ -276,7 +276,7 @@ struct devfreq_simple_ondemand_data {
>  
>  #if IS_ENABLED(CONFIG_DEVFREQ_GOV_PASSIVE)
>  /**
> - * struct devfreq_passive_data - void *data fed to struct devfreq
> + * struct devfreq_passive_data - ``void *data`` fed to struct devfreq
>   *	and devfreq_add_device
>   * @parent:	the devfreq instance of parent device.
>   * @get_target_freq:	Optional callback, Returns desired operating frequency
> 

Applied it. Thanks.

-- 
Best Regards,
Chanwoo Choi
Samsung Electronics

[PATCH 06/17] firewire: firewire-cdev.hL get rid of a docs warning

[Mauro Carvalho Chehab]

This warning:

	./include/uapi/linux/firewire-cdev.h:312: WARNING: Inline literal start-string without end-string.

is because %FOO doesn't work if there's a parenthesis at the
string (as a parenthesis may indicate a function). So, mark
the literal block using the alternate ``FOO`` syntax.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/uapi/linux/firewire-cdev.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/uapi/linux/firewire-cdev.h b/include/uapi/linux/firewire-cdev.h
index 1acd2b179aef..7e5b5c10a49c 100644
--- a/include/uapi/linux/firewire-cdev.h
+++ b/include/uapi/linux/firewire-cdev.h
@@ -308,7 +308,7 @@ struct fw_cdev_event_iso_interrupt_mc {
 /**
  * struct fw_cdev_event_iso_resource - Iso resources were allocated or freed
  * @closure:	See &fw_cdev_event_common;
- *		set by %FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE) ioctl
+ *		set by``FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE)`` ioctl
  * @type:	%FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED or
  *		%FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED
  * @handle:	Reference by which an allocated resource can be deallocated
-- 
2.24.1

Re: [PATCH 06/17] firewire: firewire-cdev.hL get rid of a docs warning

[Stefan Richter]

On Mar 17 Mauro Carvalho Chehab wrote:
> This warning:
> 
> 	./include/uapi/linux/firewire-cdev.h:312: WARNING: Inline literal start-string without end-string.
> 
> is because %FOO doesn't work if there's a parenthesis at the
> string (as a parenthesis may indicate a function). So, mark
> the literal block using the alternate ``FOO`` syntax.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

I figure this is meant to go through the Documentation tree, hence

Acked-by: Stefan Richter <stefanr@s5r6.in-berlin.de>

But if I am to apply it, give me a note.

> ---
>  include/uapi/linux/firewire-cdev.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/uapi/linux/firewire-cdev.h b/include/uapi/linux/firewire-cdev.h
> index 1acd2b179aef..7e5b5c10a49c 100644
> --- a/include/uapi/linux/firewire-cdev.h
> +++ b/include/uapi/linux/firewire-cdev.h
> @@ -308,7 +308,7 @@ struct fw_cdev_event_iso_interrupt_mc {
>  /**
>   * struct fw_cdev_event_iso_resource - Iso resources were allocated or freed
>   * @closure:	See &fw_cdev_event_common;
> - *		set by %FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE) ioctl
> + *		set by``FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE)`` ioctl
>   * @type:	%FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED or
>   *		%FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED
>   * @handle:	Reference by which an allocated resource can be deallocated

-- 
Stefan Richter
-======--=-- --== =---=
http://arcgraph.de/sr/

[PATCH 07/17] scripts: kernel-doc: proper handle @foo->bar()

[Mauro Carvalho Chehab]

The pattern @foo->bar() is valid, as it can be used by a
function pointer inside a struct passed as a parameter.

Right now, it causes a warning:

	./drivers/firewire/core-transaction.c:606: WARNING: Inline strong start-string without end-string.

In this specific case, the kernel-doc markup is:

	/**
	 * fw_core_remove_address_handler() - unregister an address handler
	 * @handler: callback
	 *
	 * To be called in process context.
	 *
	 * When fw_core_remove_address_handler() returns, @handler->callback() is
	 * guaranteed to not run on any CPU anymore.
	 */

With seems valid on my eyes. So, instead of trying to hack
the kernel-doc markup, let's teach it about how to handle
such things. This should likely remove lots of other similar
warnings as well.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f2d73f04e71d..d15c8ea95d93 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -214,6 +214,7 @@ my $type_constant2 = '\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
+my $type_fp_param2 = '\@(\w+->\S+)\(\)';  # Special RST handling for structs with func ptr params
 my $type_env = '(\$\w+)';
 my $type_enum = '\&(enum\s*([_\w]+))';
 my $type_struct = '\&(struct\s*([_\w]+))';
@@ -249,6 +250,7 @@ my @highlights_rst = (
                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
                        [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
 		       [$type_fp_param, "**\$1\\\\(\\\\)**"],
+		       [$type_fp_param2, "**\$1\\\\(\\\\)**"],
                        [$type_func, "\$1()"],
                        [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
                        [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
-- 
2.24.1

[PATCH 08/17] lib: bitmap.c: get rid of some doc warnings

[Mauro Carvalho Chehab]

There are two ascii art drawings there. Use a block markup tag there
in order to get rid of those warnings:

	./lib/bitmap.c:189: WARNING: Unexpected indentation.
	./lib/bitmap.c:190: WARNING: Block quote ends without a blank line; unexpected unindent.
	./lib/bitmap.c:190: WARNING: Unexpected indentation.
	./lib/bitmap.c:191: WARNING: Line block ends without a blank line.

It should be noticed that there's actually a syntax violation
right now, as something like:

	/**
	 ...
	 @src:

will be handled as a definition for @src parameter, and not as
part of a diagram. So, we need to add something before it, in
order for this to be processed the way it should.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 lib/bitmap.c | 27 ++++++++++++++-------------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/lib/bitmap.c b/lib/bitmap.c
index 89260aa342d6..21a7640c5eed 100644
--- a/lib/bitmap.c
+++ b/lib/bitmap.c
@@ -182,21 +182,22 @@ EXPORT_SYMBOL(__bitmap_shift_left);
  *
  * In pictures, example for a big-endian 32-bit architecture:
  *
- * @src:
- * 31                                   63
- * |                                    |
- * 10000000 11000001 11110010 00010101  10000000 11000001 01110010 00010101
- *                 |  |              |                                    |
- *                16  14             0                                   32
+ * The @src bitmap is::
  *
- * if @cut is 3, and @first is 14, bits 14-16 in @src are cut and @dst is:
+ *   31                                   63
+ *   |                                    |
+ *   10000000 11000001 11110010 00010101  10000000 11000001 01110010 00010101
+ *                   |  |              |                                    |
+ *                  16  14             0                                   32
  *
- * 31                                   63
- * |                                    |
- * 10110000 00011000 00110010 00010101  00010000 00011000 00101110 01000010
- *                    |              |                                    |
- *                    14 (bit 17     0                                   32
- *                        from @src)
+ * if @cut is 3, and @first is 14, bits 14-16 in @src are cut and @dst is::
+ *
+ *   31                                   63
+ *   |                                    |
+ *   10110000 00011000 00110010 00010101  00010000 00011000 00101110 01000010
+ *                      |              |                                    |
+ *                      14 (bit 17     0                                   32
+ *                          from @src)
  *
  * Note that @dst and @src might overlap partially or entirely.
  *
-- 
2.24.1

[PATCH 09/17] rcu: update.c: get rid of some doc warnings

[Mauro Carvalho Chehab]

We need to escape *ret, as otherwise the documentation system
thinks that this is an incomplete emphasis block:

	./kernel/rcu/update.c:65: WARNING: Inline emphasis start-string without end-string.
	./kernel/rcu/update.c:65: WARNING: Inline emphasis start-string without end-string.
	./kernel/rcu/update.c:70: WARNING: Inline emphasis start-string without end-string.
	./kernel/rcu/update.c:82: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 kernel/rcu/update.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/kernel/rcu/update.c b/kernel/rcu/update.c
index b1fa519e5890..16058a5e6da4 100644
--- a/kernel/rcu/update.c
+++ b/kernel/rcu/update.c
@@ -63,12 +63,12 @@ module_param(rcu_normal_after_boot, int, 0);
  * rcu_read_lock_held_common() - might we be in RCU-sched read-side critical section?
  * @ret:	Best guess answer if lockdep cannot be relied on
  *
- * Returns true if lockdep must be ignored, in which case *ret contains
+ * Returns true if lockdep must be ignored, in which case ``*ret`` contains
  * the best guess described below.  Otherwise returns false, in which
- * case *ret tells the caller nothing and the caller should instead
+ * case ``*ret`` tells the caller nothing and the caller should instead
  * consult lockdep.
  *
- * If CONFIG_DEBUG_LOCK_ALLOC is selected, set *ret to nonzero iff in an
+ * If CONFIG_DEBUG_LOCK_ALLOC is selected, set ``*ret`` to nonzero iff in an
  * RCU-sched read-side critical section.  In absence of
  * CONFIG_DEBUG_LOCK_ALLOC, this assumes we are in an RCU-sched read-side
  * critical section unless it can prove otherwise.  Note that disabling
@@ -82,7 +82,7 @@ module_param(rcu_normal_after_boot, int, 0);
  *
  * Note that if the CPU is in the idle loop from an RCU point of view (ie:
  * that we are in the section between rcu_idle_enter() and rcu_idle_exit())
- * then rcu_read_lock_held() sets *ret to false even if the CPU did an
+ * then rcu_read_lock_held() sets ``*ret`` to false even if the CPU did an
  * rcu_read_lock().  The reason for this is that RCU ignores CPUs that are
  * in such a section, considering these as in extended quiescent state,
  * so such a CPU is effectively never in an RCU read-side critical section
-- 
2.24.1

Re: [PATCH 09/17] rcu: update.c: get rid of some doc warnings

[Paul E. McKenney]

On Tue, Mar 17, 2020 at 03:54:18PM +0100, Mauro Carvalho Chehab wrote:
> We need to escape *ret, as otherwise the documentation system
> thinks that this is an incomplete emphasis block:
> 
> 	./kernel/rcu/update.c:65: WARNING: Inline emphasis start-string without end-string.
> 	./kernel/rcu/update.c:65: WARNING: Inline emphasis start-string without end-string.
> 	./kernel/rcu/update.c:70: WARNING: Inline emphasis start-string without end-string.
> 	./kernel/rcu/update.c:82: WARNING: Inline emphasis start-string without end-string.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied, thank you!

							Thanx, Paul

> ---
>  kernel/rcu/update.c | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/kernel/rcu/update.c b/kernel/rcu/update.c
> index b1fa519e5890..16058a5e6da4 100644
> --- a/kernel/rcu/update.c
> +++ b/kernel/rcu/update.c
> @@ -63,12 +63,12 @@ module_param(rcu_normal_after_boot, int, 0);
>   * rcu_read_lock_held_common() - might we be in RCU-sched read-side critical section?
>   * @ret:	Best guess answer if lockdep cannot be relied on
>   *
> - * Returns true if lockdep must be ignored, in which case *ret contains
> + * Returns true if lockdep must be ignored, in which case ``*ret`` contains
>   * the best guess described below.  Otherwise returns false, in which
> - * case *ret tells the caller nothing and the caller should instead
> + * case ``*ret`` tells the caller nothing and the caller should instead
>   * consult lockdep.
>   *
> - * If CONFIG_DEBUG_LOCK_ALLOC is selected, set *ret to nonzero iff in an
> + * If CONFIG_DEBUG_LOCK_ALLOC is selected, set ``*ret`` to nonzero iff in an
>   * RCU-sched read-side critical section.  In absence of
>   * CONFIG_DEBUG_LOCK_ALLOC, this assumes we are in an RCU-sched read-side
>   * critical section unless it can prove otherwise.  Note that disabling
> @@ -82,7 +82,7 @@ module_param(rcu_normal_after_boot, int, 0);
>   *
>   * Note that if the CPU is in the idle loop from an RCU point of view (ie:
>   * that we are in the section between rcu_idle_enter() and rcu_idle_exit())
> - * then rcu_read_lock_held() sets *ret to false even if the CPU did an
> + * then rcu_read_lock_held() sets ``*ret`` to false even if the CPU did an
>   * rcu_read_lock().  The reason for this is that RCU ignores CPUs that are
>   * in such a section, considering these as in extended quiescent state,
>   * so such a CPU is effectively never in an RCU read-side critical section
> -- 
> 2.24.1
> 

[PATCH 10/17] net: phy: sfp-bus.c: get rid of docs warnings

[Mauro Carvalho Chehab]

The indentation for the returned values are weird, causing those
warnings:

	./drivers/net/phy/sfp-bus.c:579: WARNING: Unexpected indentation.
	./drivers/net/phy/sfp-bus.c:619: WARNING: Unexpected indentation.

Use a list and change the identation for it to be properly
parsed by the documentation toolchain.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/net/phy/sfp-bus.c | 32 ++++++++++++++++++--------------
 1 file changed, 18 insertions(+), 14 deletions(-)

diff --git a/drivers/net/phy/sfp-bus.c b/drivers/net/phy/sfp-bus.c
index d949ea7b4f8c..6900c68260e0 100644
--- a/drivers/net/phy/sfp-bus.c
+++ b/drivers/net/phy/sfp-bus.c
@@ -572,13 +572,15 @@ static void sfp_upstream_clear(struct sfp_bus *bus)
  * the sfp_bus structure, incrementing its reference count.  This must
  * be put via sfp_bus_put() when done.
  *
- * Returns: on success, a pointer to the sfp_bus structure,
- *	    %NULL if no SFP is specified,
- * 	    on failure, an error pointer value:
- * 		corresponding to the errors detailed for
- * 		fwnode_property_get_reference_args().
- * 	        %-ENOMEM if we failed to allocate the bus.
- *		an error from the upstream's connect_phy() method.
+ * Returns:
+ * 	    - on success, a pointer to the sfp_bus structure,
+ *	    - %NULL if no SFP is specified,
+ * 	    - on failure, an error pointer value:
+ *
+ * 	      - corresponding to the errors detailed for
+ * 	        fwnode_property_get_reference_args().
+ * 	      - %-ENOMEM if we failed to allocate the bus.
+ *	      - an error from the upstream's connect_phy() method.
  */
 struct sfp_bus *sfp_bus_find_fwnode(struct fwnode_handle *fwnode)
 {
@@ -612,13 +614,15 @@ EXPORT_SYMBOL_GPL(sfp_bus_find_fwnode);
  * the SFP bus using sfp_register_upstream().  This takes a reference on the
  * bus, so it is safe to put the bus after this call.
  *
- * Returns: on success, a pointer to the sfp_bus structure,
- *	    %NULL if no SFP is specified,
- * 	    on failure, an error pointer value:
- * 		corresponding to the errors detailed for
- * 		fwnode_property_get_reference_args().
- * 	        %-ENOMEM if we failed to allocate the bus.
- *		an error from the upstream's connect_phy() method.
+ * Returns:
+ * 	    - on success, a pointer to the sfp_bus structure,
+ *	    - %NULL if no SFP is specified,
+ * 	    - on failure, an error pointer value:
+ *
+ * 	      - corresponding to the errors detailed for
+ * 	        fwnode_property_get_reference_args().
+ * 	      - %-ENOMEM if we failed to allocate the bus.
+ *	      - an error from the upstream's connect_phy() method.
  */
 int sfp_bus_add_upstream(struct sfp_bus *bus, void *upstream,
 			 const struct sfp_upstream_ops *ops)
-- 
2.24.1

Re: [PATCH 10/17] net: phy: sfp-bus.c: get rid of docs warnings

[David Miller]

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Tue, 17 Mar 2020 15:54:19 +0100

> The indentation for the returned values are weird, causing those
> warnings:
> 
> 	./drivers/net/phy/sfp-bus.c:579: WARNING: Unexpected indentation.
> 	./drivers/net/phy/sfp-bus.c:619: WARNING: Unexpected indentation.
> 
> Use a list and change the identation for it to be properly
> parsed by the documentation toolchain.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied.

[PATCH 11/17] net: core: dev.c: fix a documentation warning

[Mauro Carvalho Chehab]

There's a markup for link with is "foo_". On this kernel-doc
comment, we don't want this, but instead, place a literal
reference. So, escape the literal with ``foo``, in order to
avoid this warning:

	./net/core/dev.c:5195: WARNING: Unknown target name: "page_is".

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 net/core/dev.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/net/core/dev.c b/net/core/dev.c
index d84541c24446..474762ea256a 100644
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -5195,7 +5195,7 @@ static int __netif_receive_skb_one_core(struct sk_buff *skb, bool pfmemalloc)
  *
  *	More direct receive version of netif_receive_skb().  It should
  *	only be used by callers that have a need to skip RPS and Generic XDP.
- *	Caller must also take care of handling if (page_is_)pfmemalloc.
+ *	Caller must also take care of handling if ``(page_is_)pfmemalloc``.
  *
  *	This function may only be called from softirq context and interrupts
  *	should be enabled.
-- 
2.24.1

Re: [PATCH 11/17] net: core: dev.c: fix a documentation warning

[David Miller]

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Tue, 17 Mar 2020 15:54:20 +0100

> There's a markup for link with is "foo_". On this kernel-doc
> comment, we don't want this, but instead, place a literal
> reference. So, escape the literal with ``foo``, in order to
> avoid this warning:
> 
> 	./net/core/dev.c:5195: WARNING: Unknown target name: "page_is".
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied.

[PATCH 12/17] gpio: gpiolib.c: fix a doc warning

[Mauro Carvalho Chehab]

Use a different markup for the ERR_PTR, as %FOO doesn't work
if there are parenthesis. So, use, instead:

	``ERR_PTR(-EINVAL)``

This fixes the following warning:

	./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpio/gpiolib.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpio/gpiolib.c b/drivers/gpio/gpiolib.c
index f31b1d46599e..74d8973025da 100644
--- a/drivers/gpio/gpiolib.c
+++ b/drivers/gpio/gpiolib.c
@@ -136,7 +136,7 @@ EXPORT_SYMBOL_GPL(gpio_to_desc);
  * @hwnum: hardware number of the GPIO for this chip
  *
  * Returns:
- * A pointer to the GPIO descriptor or %ERR_PTR(-EINVAL) if no GPIO exists
+ * A pointer to the GPIO descriptor or ``ERR_PTR(-EINVAL)`` if no GPIO exists
  * in the given chip for the specified hardware number.
  */
 struct gpio_desc *gpiochip_get_desc(struct gpio_chip *chip,
-- 
2.24.1

Re: [PATCH 12/17] gpio: gpiolib.c: fix a doc warning

[Bartosz Golaszewski]

wt., 17 mar 2020 o 15:54 Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> napisał(a):
>
> Use a different markup for the ERR_PTR, as %FOO doesn't work
> if there are parenthesis. So, use, instead:
>
>         ``ERR_PTR(-EINVAL)``
>
> This fixes the following warning:
>
>         ./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/gpio/gpiolib.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/drivers/gpio/gpiolib.c b/drivers/gpio/gpiolib.c
> index f31b1d46599e..74d8973025da 100644
> --- a/drivers/gpio/gpiolib.c
> +++ b/drivers/gpio/gpiolib.c
> @@ -136,7 +136,7 @@ EXPORT_SYMBOL_GPL(gpio_to_desc);
>   * @hwnum: hardware number of the GPIO for this chip
>   *
>   * Returns:
> - * A pointer to the GPIO descriptor or %ERR_PTR(-EINVAL) if no GPIO exists
> + * A pointer to the GPIO descriptor or ``ERR_PTR(-EINVAL)`` if no GPIO exists
>   * in the given chip for the specified hardware number.
>   */
>  struct gpio_desc *gpiochip_get_desc(struct gpio_chip *chip,
> --
> 2.24.1
>

Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

Re: [PATCH 12/17] gpio: gpiolib.c: fix a doc warning

[Linus Walleij]

On Tue, Mar 17, 2020 at 3:54 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:

> Use a different markup for the ERR_PTR, as %FOO doesn't work
> if there are parenthesis. So, use, instead:
>
>         ``ERR_PTR(-EINVAL)``
>
> This fixes the following warning:
>
>         ./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Mauro are you merging this or do you want me to merge it?

Yours,
Linus Walleij

Re: [PATCH 12/17] gpio: gpiolib.c: fix a doc warning

[Mauro Carvalho Chehab]

Em Fri, 27 Mar 2020 11:22:52 +0100
Linus Walleij <linus.walleij@linaro.org> escreveu:

> On Tue, Mar 17, 2020 at 3:54 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> 
> > Use a different markup for the ERR_PTR, as %FOO doesn't work
> > if there are parenthesis. So, use, instead:
> >
> >         ``ERR_PTR(-EINVAL)``
> >
> > This fixes the following warning:
> >
> >         ./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
> 
> Mauro are you merging this or do you want me to merge it?

Feel free to merge it.

My plan is to rebase my trees after the merge window, re-sending
anything that got missed for them to be either applied directly
or via the docs tree.

Thanks,
Mauro

Re: [PATCH 12/17] gpio: gpiolib.c: fix a doc warning

[Linus Walleij]

On Tue, Mar 17, 2020 at 3:54 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:

> Use a different markup for the ERR_PTR, as %FOO doesn't work
> if there are parenthesis. So, use, instead:
>
>         ``ERR_PTR(-EINVAL)``
>
> This fixes the following warning:
>
>         ./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Patch applied.

Yours,
Linus Walleij

[PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning

[Mauro Carvalho Chehab]

Don't let non-letters inside a literal block without escaping it, as
the toolchain would mis-interpret it:

./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/i2c.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/i2c.h b/include/linux/i2c.h
index f834687989f7..f6b942150631 100644
--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -506,7 +506,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
  * @smbus_xfer_atomic: same as @smbus_xfer. Yet, only using atomic context
  *   so e.g. PMICs can be accessed very late before shutdown. Optional.
  * @functionality: Return the flags that this algorithm/adapter pair supports
- *   from the I2C_FUNC_* flags.
+ *   from the ``I2C_FUNC_*`` flags.
  * @reg_slave: Register given client to I2C slave mode of this adapter
  * @unreg_slave: Unregister given client from I2C slave mode of this adapter
  *
@@ -515,7 +515,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
  * be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584
  * to name two of the most common.
  *
- * The return codes from the @master_xfer{_atomic} fields should indicate the
+ * The return codes from the ``master_xfer{_atomic}`` fields should indicate the
  * type of error code that occurred during the transfer, as documented in the
  * Kernel Documentation file Documentation/i2c/fault-codes.rst.
  */
-- 
2.24.1

Re: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 436 bytes --]

On Tue, Mar 17, 2020 at 03:54:22PM +0100, Mauro Carvalho Chehab wrote:
> Don't let non-letters inside a literal block without escaping it, as
> the toolchain would mis-interpret it:
> 
> ./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Shall I take this via I2C?

If not:

Acked-by: Wolfram Sang <wsa@the-dreams.de>


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning

[Mauro Carvalho Chehab]

Em Tue, 17 Mar 2020 16:03:22 +0100
Wolfram Sang <wsa@the-dreams.de> escreveu:

> On Tue, Mar 17, 2020 at 03:54:22PM +0100, Mauro Carvalho Chehab wrote:
> > Don't let non-letters inside a literal block without escaping it, as
> > the toolchain would mis-interpret it:
> > 
> > ./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> Shall I take this via I2C?

Yeah, feel free to pick it. The patches on this series are pretty
much independent from the others.

Thanks,
Mauro

Re: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 384 bytes --]

On Tue, Mar 17, 2020 at 03:54:22PM +0100, Mauro Carvalho Chehab wrote:
> Don't let non-letters inside a literal block without escaping it, as
> the toolchain would mis-interpret it:
> 
> ./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied to for-current, thanks!


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH 14/17] infiniband: pa_vnic_encap.h: get rid of a warning

[Mauro Carvalho Chehab]

The right markup for a variable is @foo, and not @foo[].

Using a wrong markup caused this warning:

	./drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h b/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
index 0b3570dc606d..d324312a373c 100644
--- a/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
+++ b/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
@@ -239,7 +239,7 @@ struct opa_veswport_mactable_entry {
  * @offset: mac table starting offset
  * @num_entries: Number of entries to get or set
  * @mac_tbl_digest: mac table digest
- * @tbl_entries[]: Array of table entries
+ * @tbl_entries: Array of table entries
  *
  * The EM sends down this structure in a MAD indicating
  * the starting offset in the forwarding table that this
-- 
2.24.1

Re: [PATCH 14/17] infiniband: pa_vnic_encap.h: get rid of a warning

[Jason Gunthorpe]

On Tue, Mar 17, 2020 at 03:54:23PM +0100, Mauro Carvalho Chehab wrote:
> The right markup for a variable is @foo, and not @foo[].
> 
> Using a wrong markup caused this warning:
> 
> 	./drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Do you want this to go to the RDMA tree? I wasn't cc'd on the cover
letter

Otherwise

Acked-by: Jason Gunthorpe <jgg@mellanox.com>
 
Thanks,
Jason

Re: [PATCH 14/17] infiniband: pa_vnic_encap.h: get rid of a warning

[Mauro Carvalho Chehab]

Em Wed, 18 Mar 2020 21:36:45 -0300
Jason Gunthorpe <jgg@ziepe.ca> escreveu:

> On Tue, Mar 17, 2020 at 03:54:23PM +0100, Mauro Carvalho Chehab wrote:
> > The right markup for a variable is @foo, and not @foo[].
> > 
> > Using a wrong markup caused this warning:
> > 
> > 	./drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)  
> 
> Do you want this to go to the RDMA tree? I wasn't cc'd on the cover
> letter

Sorry for not answering earlier. Got sidetracked with other things.

Yeah, if there are still time, feel free to pick it. Otherwise, 
I'll likely send again after the merge window, to be applied either 
by you or via the docs tree.

> 
> Otherwise
> 
> Acked-by: Jason Gunthorpe <jgg@mellanox.com>
>  
> Thanks,
> Jason



Thanks,
Mauro

Re: [PATCH 14/17] infiniband: pa_vnic_encap.h: get rid of a warning

[Jason Gunthorpe]

On Fri, Mar 27, 2020 at 03:32:26PM +0100, Mauro Carvalho Chehab wrote:
> Em Wed, 18 Mar 2020 21:36:45 -0300
> Jason Gunthorpe <jgg@ziepe.ca> escreveu:
> 
> > On Tue, Mar 17, 2020 at 03:54:23PM +0100, Mauro Carvalho Chehab wrote:
> > > The right markup for a variable is @foo, and not @foo[].
> > > 
> > > Using a wrong markup caused this warning:
> > > 
> > > 	./drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > >  drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)  
> > 
> > Do you want this to go to the RDMA tree? I wasn't cc'd on the cover
> > letter
> 
> Sorry for not answering earlier. Got sidetracked with other things.
> 
> Yeah, if there are still time, feel free to pick it. Otherwise, 
> I'll likely send again after the merge window, to be applied either 
> by you or via the docs tree.

Sure, done

Thanks,
Jason

[PATCH 15/17] ata: libata-core: fix a doc warning

[Mauro Carvalho Chehab]

The docs toolchain doesn't recognise this pattern:

	@link->[hw_]sata_spd_limit

As it can't really process it. So, instead, let's mark it with
a literal block markup:

	``link->[hw_]sata_spd_limit``

in order to get rid of the following warning:

	./drivers/ata/libata-core.c:5974: WARNING: Unknown target name: "hw".

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/ata/libata-core.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/ata/libata-core.c b/drivers/ata/libata-core.c
index 175b2a9dc000..ae0230740474 100644
--- a/drivers/ata/libata-core.c
+++ b/drivers/ata/libata-core.c
@@ -5975,7 +5975,7 @@ void ata_link_init(struct ata_port *ap, struct ata_link *link, int pmp)
  *	sata_link_init_spd - Initialize link->sata_spd_limit
  *	@link: Link to configure sata_spd_limit for
  *
- *	Initialize @link->[hw_]sata_spd_limit to the currently
+ *	Initialize ``link->[hw_]sata_spd_limit`` to the currently
  *	configured value.
  *
  *	LOCKING:
-- 
2.24.1

[PATCH 16/17] fs: inode.c: get rid of docs warnings

[Mauro Carvalho Chehab]

Use *foo makes the toolchain to think that this is an emphasis, causing
those warnings:

	./fs/inode.c:1609: WARNING: Inline emphasis start-string without end-string.
	./fs/inode.c:1609: WARNING: Inline emphasis start-string without end-string.
	./fs/inode.c:1615: WARNING: Inline emphasis start-string without end-string.

So, use, instead, ``*foo``, in order to mark it as a literal block.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 fs/inode.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/fs/inode.c b/fs/inode.c
index 93d9252a00ab..37226a9cfa4f 100644
--- a/fs/inode.c
+++ b/fs/inode.c
@@ -1606,14 +1606,14 @@ EXPORT_SYMBOL(iput);
  *	@inode:  inode owning the block number being requested
  *	@block: pointer containing the block to find
  *
- *	Replaces the value in *block with the block number on the device holding
+ *	Replaces the value in ``*block`` with the block number on the device holding
  *	corresponding to the requested block number in the file.
  *	That is, asked for block 4 of inode 1 the function will replace the
- *	4 in *block, with disk block relative to the disk start that holds that
+ *	4 in ``*block``, with disk block relative to the disk start that holds that
  *	block of the file.
  *
  *	Returns -EINVAL in case of error, 0 otherwise. If mapping falls into a
- *	hole, returns 0 and *block is also set to 0.
+ *	hole, returns 0 and ``*block`` is also set to 0.
  */
 int bmap(struct inode *inode, sector_t *block)
 {
-- 
2.24.1

[PATCH 17/17] regulator: driver.h: fix regulator_map_* function names

[Mauro Carvalho Chehab]

The toolchain produces a warning on this driver when building
the docs:

	./include/linux/regulator/driver.h:284: WARNING: Unknown target name: "regulator_regmap_x_voltage".

While fixing it, we notices that there's no function names
with the above pattern. It seems that some previous patch
renamed it to regulator_map_* instead.

So, change the function name, replacing "x" by "*", with is
a more used way to add a wildcard, and escape those with
``literal`` markup, in order to avoid the toolchain to think
that this is a link to some existing document chapter.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/regulator/driver.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/regulator/driver.h b/include/linux/regulator/driver.h
index 9a911bb5fb61..29d920516e0b 100644
--- a/include/linux/regulator/driver.h
+++ b/include/linux/regulator/driver.h
@@ -277,9 +277,9 @@ enum regulator_type {
  * @curr_table: Current limit mapping table (if table based mapping)
  *
  * @vsel_range_reg: Register for range selector when using pickable ranges
- *		    and regulator_regmap_X_voltage_X_pickable functions.
+ *		    and ``regulator_map_*_voltage_*_pickable`` functions.
  * @vsel_range_mask: Mask for register bitfield used for range selector
- * @vsel_reg: Register for selector when using regulator_regmap_X_voltage_
+ * @vsel_reg: Register for selector when using ``regulator_map_*_voltage_*``
  * @vsel_mask: Mask for register bitfield used for selector
  * @vsel_step: Specify the resolution of selector stepping when setting
  *	       voltage. If 0, then no stepping is done (requested selector is
-- 
2.24.1

Applied "regulator: driver.h: fix regulator_map_* function names" to the regulator tree

[Mark Brown]

The patch

   regulator: driver.h: fix regulator_map_* function names

has been applied to the regulator tree at

   https://git.kernel.org/pub/scm/linux/kernel/git/broonie/regulator.git 

All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.  

You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying
to this mail.

Thanks,
Mark

From bd3ebed9304acd2ccddde44675fedf963dbfdc71 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Tue, 17 Mar 2020 15:54:26 +0100
Subject: [PATCH] regulator: driver.h: fix regulator_map_* function names

The toolchain produces a warning on this driver when building
the docs:

	./include/linux/regulator/driver.h:284: WARNING: Unknown target name: "regulator_regmap_x_voltage".

While fixing it, we notices that there's no function names
with the above pattern. It seems that some previous patch
renamed it to regulator_map_* instead.

So, change the function name, replacing "x" by "*", with is
a more used way to add a wildcard, and escape those with
``literal`` markup, in order to avoid the toolchain to think
that this is a link to some existing document chapter.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/b9f5687bcf981a88c9d1fd04d759a540fda53a99.1584456635.git.mchehab+huawei@kernel.org
Signed-off-by: Mark Brown <broonie@kernel.org>
---
 include/linux/regulator/driver.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/regulator/driver.h b/include/linux/regulator/driver.h
index 9a911bb5fb61..29d920516e0b 100644
--- a/include/linux/regulator/driver.h
+++ b/include/linux/regulator/driver.h
@@ -277,9 +277,9 @@ enum regulator_type {
  * @curr_table: Current limit mapping table (if table based mapping)
  *
  * @vsel_range_reg: Register for range selector when using pickable ranges
- *		    and regulator_regmap_X_voltage_X_pickable functions.
+ *		    and ``regulator_map_*_voltage_*_pickable`` functions.
  * @vsel_range_mask: Mask for register bitfield used for range selector
- * @vsel_reg: Register for selector when using regulator_regmap_X_voltage_
+ * @vsel_reg: Register for selector when using ``regulator_map_*_voltage_*``
  * @vsel_mask: Mask for register bitfield used for selector
  * @vsel_step: Specify the resolution of selector stepping when setting
  *	       voltage. If 0, then no stepping is done (requested selector is
-- 
2.20.1