Skip to contentSkip to conversation

linux-next: build warnings after merge of the tip tree

PATCH Superseded Stephen Rothwell 4 participants 8 messages Nov 21, 2022 – Nov 22, 2022

Subsystems (3)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

Hi all,

After merging the tip tree, today's linux-next build (htmldocs) produced these warnings:

Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:148: ERROR: Unexpected indentation. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:149: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:236: ERROR: Unexpected indentation. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:259: ERROR: Unexpected indentation.

Introduced by commits

5c0997dc33ac ("PCI/MSI: Move pci_alloc_irq_vectors() to api.c") 017239c8db20 ("PCI/MSI: Move pci_irq_vector() to api.c") be37b8428b7b ("PCI/MSI: Move pci_irq_get_affinity() to api.c")

Signature · 2 lines
Cheers,
Stephen Rothwell
#1 lore raw

PATCH 1/1 PCI/MSI: api: Use bullet lists in kernel-doc comments

Stephen Rothwell reported htmldocs warnings when merging tip tree:

Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:148: ERROR: Unexpected indentation. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:149: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:236: ERROR: Unexpected indentation. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:259: ERROR: Unexpected indentation.

Use bullet lists syntax for pci_disable_msix flags and interrupt mode lists to fix these warnings.

Fixes 5c0997dc33ac24 ("PCI/MSI: Move pci_alloc_irq_vectors() to api.c")
Fixes 017239c8db2093 ("PCI/MSI: Move pci_irq_vector() to api.c")
Fixes be37b8428b7b77 ("PCI/MSI: Move pci_irq_get_affinity() to api.c")
---
 drivers/pci/msi/api.c | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)
drivers/pci/msi/api.c +19 -14
index 6c3ad4863850c3..d48c21295a88c6 100644
@@ -142,12 +142,15 @@ EXPORT_SYMBOL(pci_disable_msix);
  * @min_vecs: minimum required number of vectors (must be >= 1)
  * @max_vecs: maximum desired number of vectors
  * @flags:    One or more of:
- *            %PCI_IRQ_MSIX      Allow trying MSI-X vector allocations
- *            %PCI_IRQ_MSI       Allow trying MSI vector allocations
- *            %PCI_IRQ_LEGACY    Allow trying legacy INTx interrupts, if
- *                               and only if @min_vecs == 1
- *            %PCI_IRQ_AFFINITY  Auto-manage IRQs affinity by spreading
- *                               the vectors around available CPUs
+ *
+ *            * %PCI_IRQ_MSIX - Allow trying MSI-X vector allocations
+ *            * %PCI_IRQ_MSI - Allow trying MSI vector allocations
+ *
+ *            * %PCI_IRQ_LEGACY - Allow trying legacy INTx interrupts, if
+ *              and only if @min_vecs == 1
+ *
+ *            * %PCI_IRQ_AFFINITY - Auto-manage IRQs affinity by spreading
+ *              the vectors around available CPUs
  *
  * Allocate up to @max_vecs interrupt vectors on device. MSI-X irq
  * vector allocation has a higher precedence over plain MSI, which has a
@@ -232,10 +235,11 @@ EXPORT_SYMBOL(pci_alloc_irq_vectors_affinity);
  * pci_irq_vector() - Get Linux IRQ number of a device interrupt vector
  * @dev: the PCI device to operate on
  * @nr:  device-relative interrupt vector index (0-based); has different
- *       meanings, depending on interrupt mode
- *         MSI-X        the index in the MSI-X vector table
- *         MSI          the index of the enabled MSI vectors
- *         INTx         must be 0
+ *       meanings, depending on interrupt mode:
+ *
+ *         * MSI-X - the index in the MSI-X vector table
+ *         * MSI - the index of the enabled MSI vectors
+ *         * INTx - must be 0
  *
  * Return: the Linux IRQ number, or -EINVAL if @nr is out of range
  */
@@ -255,10 +259,11 @@ EXPORT_SYMBOL(pci_irq_vector);
  * pci_irq_get_affinity() - Get a device interrupt vector affinity
  * @dev: the PCI device to operate on
  * @nr:  device-relative interrupt vector index (0-based); has different
- *       meanings, depending on interrupt mode
- *         MSI-X        the index in the MSI-X vector table
- *         MSI          the index of the enabled MSI vectors
- *         INTx         must be 0
+ *       meanings, depending on interrupt mode:
+ *
+ *         * MSI-X - the index in the MSI-X vector table
+ *         * MSI - the index of the enabled MSI vectors
+ *         * INTx - must be 0
  *
  * Return: MSI/MSI-X vector affinity, NULL if @nr is out of range or if
  * the MSI(-X) vector was allocated without explicit affinity

base-commit: 15ce088a8698c22cf5a18799dda16f04ed1d1cb7

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

Re: [PATCH] PCI/MSI: api: Use bullet lists in kernel-doc comments

Hi Bagas,

If you have opportunity, please update the subject line to remove "api: " to match previous history:

PCI/MSI: Correct 'can_mask' test in msi_add_msi_desc() PCI/MSI: Remove bogus warning in pci_irq_get_affinity() PCI/MSI: Prevent UAF in error path
PCI/MSI: Unbreak pci_irq_get_affinity() PCI/MSI: Use msi_on_each_desc()
PCI/MSI: Let core code free MSI descriptors PCI/MSI: Use msi_add_msi_desc()
PCI/MSI: Protect MSI operations
PCI/MSI: Simplify pci_irq_get_affinity()
...

Quoted 16 lines · Bagas Sanjaya

Stephen Rothwell reported htmldocs warnings when merging tip tree:

Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:148: ERROR: Unexpected indentation. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:149: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:236: ERROR: Unexpected indentation. Documentation/PCI/msi-howto:380: drivers/pci/msi/api.c:259: ERROR: Unexpected indentation.

Use bullet lists syntax for pci_disable_msix flags and interrupt mode lists to fix these warnings.

Fixes 5c0997dc33ac24 ("PCI/MSI: Move pci_alloc_irq_vectors() to api.c")
Fixes 017239c8db2093 ("PCI/MSI: Move pci_irq_vector() to api.c")
Fixes be37b8428b7b77 ("PCI/MSI: Move pci_irq_get_affinity() to api.c")
#3 lore raw

Re: [PATCH] PCI/MSI: api: Use bullet lists in kernel-doc comments

Quoted 5 lines · Bjorn Helgaas

Hi Bagas,

If you have opportunity, please update the subject line to remove "api: " to match previous history:

Quoted 10 lines

PCI/MSI: Correct 'can_mask' test in msi_add_msi_desc() PCI/MSI: Remove bogus warning in pci_irq_get_affinity() PCI/MSI: Prevent UAF in error path
PCI/MSI: Unbreak pci_irq_get_affinity() PCI/MSI: Use msi_on_each_desc()
PCI/MSI: Let core code free MSI descriptors PCI/MSI: Use msi_add_msi_desc()
PCI/MSI: Protect MSI operations
PCI/MSI: Simplify pci_irq_get_affinity()
...

OK, thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#4 lore raw

Re: [PATCH] PCI/MSI: api: Use bullet lists in kernel-doc comments

In reply to Bagas Sanjaya
Quoted 16 lines · Bagas Sanjaya
  * @flags:    One or more of:
- *            %PCI_IRQ_MSIX      Allow trying MSI-X vector allocations
- *            %PCI_IRQ_MSI       Allow trying MSI vector allocations
- *            %PCI_IRQ_LEGACY    Allow trying legacy INTx interrupts, if
- *                               and only if @min_vecs == 1
- *            %PCI_IRQ_AFFINITY  Auto-manage IRQs affinity by spreading
- *                               the vectors around available CPUs

+ *
+ * * %PCI_IRQ_MSIX - Allow trying MSI-X vector allocations
+ * * %PCI_IRQ_MSI - Allow trying MSI vector allocations
+ *
+ * * %PCI_IRQ_LEGACY - Allow trying legacy INTx interrupts, if
+ * and only if @min_vecs == 1
+ *
+ * * %PCI_IRQ_AFFINITY - Auto-manage IRQs affinity by spreading
+ * the vectors around available CPUs

...

Quoted 9 lines

- * meanings, depending on interrupt mode

- *         MSI-X        the index in the MSI-X vector table
- *         MSI          the index of the enabled MSI vectors
- *         INTx         must be 0
+ *       meanings, depending on interrupt mode:
+ *
+ *         * MSI-X - the index in the MSI-X vector table
+ *         * MSI - the index of the enabled MSI vectors
+ *         * INTx - must be 0

Sorry for the trouble.

While at it, can we please keep the alignment in the original patch? This is supposed to be pretty too for people who look at the C code (most of the actual readers).

That is:

+ *

 + *            * %PCI_IRQ_MSIX     -  Allow trying MSI-X vector allocations
 + *            * %PCI_IRQ_MSI      -  Allow trying MSI vector allocations
 + *            * %PCI_IRQ_LEGACY   -  Allow trying legacy INTx interrupts, if

+ * and only if @min_vecs == 1
+ * * %PCI_IRQ_AFFINITY - Auto-manage IRQs affinity by spreading
+ * the vectors around available CPUs

and:

Quoted 5 lines

+ * meanings, depending on interrupt mode:
+ *

+ *         * MSI-X - the index in the MSI-X vector table
+ *         * MSI   - the index of the enabled MSI vectors
+ *         * INTx  - must be 0

Thanks,

--
Ahmed S. Darwish
Linutronix GmbH

#5 lore raw

Re: [PATCH] PCI/MSI: api: Use bullet lists in kernel-doc comments

Quoted 8 lines · Ahmed S. Darwish

Sorry for the trouble.

While at it, can we please keep the alignment in the original patch? This is supposed to be pretty too for people who look at the C code (most of the actual readers).

That is:

Quoted 8 lines

+ *

 + *            * %PCI_IRQ_MSIX     -  Allow trying MSI-X vector allocations
 + *            * %PCI_IRQ_MSI      -  Allow trying MSI vector allocations
 + *            * %PCI_IRQ_LEGACY   -  Allow trying legacy INTx interrupts, if

+ * and only if @min_vecs == 1
+ * * %PCI_IRQ_AFFINITY - Auto-manage IRQs affinity by spreading
+ * the vectors around available CPUs

For the list above, no, since if the alignment is kept, like:

---- >8 ----

drivers/pci/msi/api.c +9 -9
index d48c21295a88c6..13f612bbbb29b2 100644
@@ -143,14 +143,14 @@ EXPORT_SYMBOL(pci_disable_msix);
  * @max_vecs: maximum desired number of vectors
  * @flags:    One or more of:
  *
- *            * %PCI_IRQ_MSIX - Allow trying MSI-X vector allocations
- *            * %PCI_IRQ_MSI - Allow trying MSI vector allocations
+ *            * %PCI_IRQ_MSIX     - Allow trying MSI-X vector allocations
+ *            * %PCI_IRQ_MSI      - Allow trying MSI vector allocations
  *
- *            * %PCI_IRQ_LEGACY - Allow trying legacy INTx interrupts, if
- *              and only if @min_vecs == 1
+ *            * %PCI_IRQ_LEGACY   - Allow trying legacy INTx interrupts, if
+ *                                  and only if @min_vecs == 1
  *
  *            * %PCI_IRQ_AFFINITY - Auto-manage IRQs affinity by spreading
- *              the vectors around available CPUs
+ *                                  the vectors around available CPUs
  *
  * Allocate up to @max_vecs interrupt vectors on device. MSI-X irq
  * vector allocation has a higher precedence over plain MSI, which has a
@@ -238,8 +238,8 @@ EXPORT_SYMBOL(pci_alloc_irq_vectors_affinity);
  *       meanings, depending on interrupt mode:
  *
  *         * MSI-X - the index in the MSI-X vector table
- *         * MSI - the index of the enabled MSI vectors
- *         * INTx - must be 0
+ *         * MSI   - the index of the enabled MSI vectors
+ *         * INTx  - must be 0
  *
  * Return: the Linux IRQ number, or -EINVAL if @nr is out of range
  */
@@ -262,8 +262,8 @@ EXPORT_SYMBOL(pci_irq_vector);
  *       meanings, depending on interrupt mode:
  *
  *         * MSI-X - the index in the MSI-X vector table
- *         * MSI - the index of the enabled MSI vectors
- *         * INTx - must be 0
+ *         * MSI   - the index of the enabled MSI vectors
+ *         * INTx  - must be 0
  *
  * Return: MSI/MSI-X vector affinity, NULL if @nr is out of range or if
  * the MSI(-X) vector was allocated without explicit affinity

, multi-line entries will be rendered as definition list instead. So, these entries must have hanging indent of two spaces after bullet marker (*), following alignment of first line of the entry.

Also, these entries must be separated from other entries by a line, otherwise the list will be broken (rendered inline).

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
Acked-by NAK
#6 lore raw

Re: [PATCH] PCI/MSI: api: Use bullet lists in kernel-doc comments

Quoted 3 lines · Bagas Sanjaya

For the list above, no, since if the alignment is kept, like:

NAK.

Below patch works properly on my side, no Sphinx errors and proper HTML view, while still keeping proper-alignment in the C code.

Sorry, you're too focusing on the HTML side.

Making the C code readable, not just the HTML output, is quite important.

=>

From: Bagas Sanjaya <[email protected]>

Use bullet-list RST syntax for kernel-doc parameters' flags and interrupt mode descriptions. Otherwise Sphinx produces "Unexpected identation" errors and warnings.

Fixes 5c0997dc33ac24 ("PCI/MSI: Move pci_alloc_irq_vectors() to api.c")
Fixes 017239c8db2093 ("PCI/MSI: Move pci_irq_vector() to api.c")
Fixes be37b8428b7b77 ("PCI/MSI: Move pci_irq_get_affinity() to api.c")
[[email protected]: Match subject-line with other subystem commits]
[[email protected]: Remove verbose Sphinx log from commit log]

[[email protected]: For C kernel-doc comments legibility, keep
the flags and interrupt mode descriptions aligned.]

---

 drivers/pci/msi/api.c | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)
drivers/pci/msi/api.c +19 -14
index dfcaa77108de..6c0c0f3ad3b8 100644
@@ -209,12 +209,15 @@ EXPORT_SYMBOL(pci_disable_msix);
  * @min_vecs: minimum required number of vectors (must be >= 1)
  * @max_vecs: maximum desired number of vectors
  * @flags:    One or more of:
- *            %PCI_IRQ_MSIX      Allow trying MSI-X vector allocations
- *            %PCI_IRQ_MSI       Allow trying MSI vector allocations
- *            %PCI_IRQ_LEGACY    Allow trying legacy INTx interrupts, if
- *                               and only if @min_vecs == 1
- *            %PCI_IRQ_AFFINITY  Auto-manage IRQs affinity by spreading
- *                               the vectors around available CPUs
+ *
+ *            * %PCI_IRQ_MSIX      Allow trying MSI-X vector allocations
+ *            * %PCI_IRQ_MSI       Allow trying MSI vector allocations
+ *
+ *            * %PCI_IRQ_LEGACY    Allow trying legacy INTx interrupts, if
+ *              and only if @min_vecs == 1
+ *
+ *            * %PCI_IRQ_AFFINITY  Auto-manage IRQs affinity by spreading
+ *              the vectors around available CPUs
  *
  * Allocate up to @max_vecs interrupt vectors on device. MSI-X irq
  * vector allocation has a higher precedence over plain MSI, which has a
@@ -299,10 +302,11 @@ EXPORT_SYMBOL(pci_alloc_irq_vectors_affinity);
  * pci_irq_vector() - Get Linux IRQ number of a device interrupt vector
  * @dev: the PCI device to operate on
  * @nr:  device-relative interrupt vector index (0-based); has different
- *       meanings, depending on interrupt mode
- *         MSI-X        the index in the MSI-X vector table
- *         MSI          the index of the enabled MSI vectors
- *         INTx         must be 0
+ *       meanings, depending on interrupt mode:
+ *
+ *         * MSI-X     the index in the MSI-X vector table
+ *         * MSI       the index of the enabled MSI vectors
+ *         * INTx      must be 0
  *
  * Return: the Linux IRQ number, or -EINVAL if @nr is out of range
  */
@@ -322,10 +326,11 @@ EXPORT_SYMBOL(pci_irq_vector);
  * pci_irq_get_affinity() - Get a device interrupt vector affinity
  * @dev: the PCI device to operate on
  * @nr:  device-relative interrupt vector index (0-based); has different
- *       meanings, depending on interrupt mode
- *         MSI-X        the index in the MSI-X vector table
- *         MSI          the index of the enabled MSI vectors
- *         INTx         must be 0
+ *       meanings, depending on interrupt mode:
+ *
+ *         * MSI-X     the index in the MSI-X vector table
+ *         * MSI       the index of the enabled MSI vectors
+ *         * INTx      must be 0
  *
  * Return: MSI/MSI-X vector affinity, NULL if @nr is out of range or if
  * the MSI(-X) vector was allocated without explicit affinity

--
2.38.1

Reviewed-by
#7 lore raw

Re: [PATCH] PCI/MSI: api: Use bullet lists in kernel-doc comments

Quoted 87 lines · Ahmed S. Darwish
Quoted 3 lines · Bagas Sanjaya

For the list above, no, since if the alignment is kept, like:

NAK.

Below patch works properly on my side, no Sphinx errors and proper HTML view, while still keeping proper-alignment in the C code.

Sorry, you're too focusing on the HTML side.

Making the C code readable, not just the HTML output, is quite important.

=>

From: Bagas Sanjaya <[email protected]>

Use bullet-list RST syntax for kernel-doc parameters' flags and interrupt mode descriptions. Otherwise Sphinx produces "Unexpected identation" errors and warnings.

Fixes 5c0997dc33ac24 ("PCI/MSI: Move pci_alloc_irq_vectors() to api.c")
Fixes 017239c8db2093 ("PCI/MSI: Move pci_irq_vector() to api.c")
Fixes be37b8428b7b77 ("PCI/MSI: Move pci_irq_get_affinity() to api.c")
[[email protected]: Match subject-line with other subystem commits]
[[email protected]: Remove verbose Sphinx log from commit log]

[[email protected]: For C kernel-doc comments legibility, keep
the flags and interrupt mode descriptions aligned.]

---

 drivers/pci/msi/api.c | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)
drivers/pci/msi/api.c +14 -12
index dfcaa77108de..6c0c0f3ad3b8 100644
@@ -209,12 +209,15 @@ EXPORT_SYMBOL(pci_disable_msix);
  * @min_vecs: minimum required number of vectors (must be >= 1)
  * @max_vecs: maximum desired number of vectors
  * @flags:    One or more of:
- *            %PCI_IRQ_MSIX      Allow trying MSI-X vector allocations
- *            %PCI_IRQ_MSI       Allow trying MSI vector allocations
- *            %PCI_IRQ_LEGACY    Allow trying legacy INTx interrupts, if
- *                               and only if @min_vecs == 1
- *            %PCI_IRQ_AFFINITY  Auto-manage IRQs affinity by spreading
- *                               the vectors around available CPUs
+ *
+ *            * %PCI_IRQ_MSIX      Allow trying MSI-X vector allocations
+ *            * %PCI_IRQ_MSI       Allow trying MSI vector allocations
+ *
+ *            * %PCI_IRQ_LEGACY    Allow trying legacy INTx interrupts, if
+ *              and only if @min_vecs == 1
+ *
+ *            * %PCI_IRQ_AFFINITY  Auto-manage IRQs affinity by spreading
+ *              the vectors around available CPUs
  *
  * Allocate up to @max_vecs interrupt vectors on device. MSI-X irq
  * vector allocation has a higher precedence over plain MSI, which has a
@@ -299,10 +302,11 @@ EXPORT_SYMBOL(pci_alloc_irq_vectors_affinity);
  * pci_irq_vector() - Get Linux IRQ number of a device interrupt vector
  * @dev: the PCI device to operate on
  * @nr:  device-relative interrupt vector index (0-based); has different
- *       meanings, depending on interrupt mode
- *         MSI-X        the index in the MSI-X vector table
- *         MSI          the index of the enabled MSI vectors
- *         INTx         must be 0
+ *       meanings, depending on interrupt mode:
+ *
+ *         * MSI-X     the index in the MSI-X vector table
+ *         * MSI       the index of the enabled MSI vectors
+ *         * INTx      must be 0
  *
  * Return: the Linux IRQ number, or -EINVAL if @nr is out of range
  */
@@ -322,10 +326,11 @@ EXPORT_SYMBOL(pci_irq_vector);
  * pci_irq_get_affinity() - Get a device interrupt vector affinity
  * @dev: the PCI device to operate on
  * @nr:  device-relative interrupt vector index (0-based); has different
- *       meanings, depending on interrupt mode
- *         MSI-X        the index in the MSI-X vector table

drivers/pci/msi/api.c EXPORT_SYMBOL(pci_irq_vector); · line 336

Quoted 10 lines
drivers/pci/msi/api.c +5 -2
- *         MSI          the index of the enabled MSI vectors
- *         INTx         must be 0
+ *       meanings, depending on interrupt mode:
+ *
+ *         * MSI-X     the index in the MSI-X vector table
+ *         * MSI       the index of the enabled MSI vectors
+ *         * INTx      must be 0
  *
  * Return: MSI/MSI-X vector affinity, NULL if @nr is out of range or if
  * the MSI(-X) vector was allocated without explicit affinity

Personally I'd like to write the entries as:

* term - definition

But anyway, your suggestion patch LGTM. Thanks!

Signature · 1 line
An old man doll... just what I always wanted! - Clara