linux-next: build warnings after merge of the tip tree
Subsystems (3)
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
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.
--- drivers/pci/msi/api.c | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-)
drivers/pci/msi/api.c +19 -14
@@ -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
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_msixflags 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")Reported-by Stephen Rothwell <[email protected]>Signed-off-by Bagas Sanjaya <[email protected]>
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 inmsi_add_msi_desc()PCI/MSI: Remove bogus warning inpci_irq_get_affinity()PCI/MSI: Prevent UAF in error path
PCI/MSI: Unbreakpci_irq_get_affinity()PCI/MSI: Usemsi_on_each_desc()
PCI/MSI: Let core code free MSI descriptors PCI/MSI: Usemsi_add_msi_desc()
PCI/MSI: Protect MSI operations
PCI/MSI: Simplifypci_irq_get_affinity()
...
OK, thanks.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Re: [PATCH] PCI/MSI: api: Use bullet lists in kernel-doc comments
In reply to Bagas SanjayaQuoted 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
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
@@ -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
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.
[[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
@@ -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
Bagas Sanjaya
Reviewed-byRe: [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")Reported-by Stephen Rothwell <[email protected]>Signed-off-by Bagas Sanjaya <[email protected]>[[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.]Acked-by Ahmed S. Darwish <[email protected]>---
drivers/pci/msi/api.c | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-)drivers/pci/msi/api.c +14
-12@@ -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