Skip to contentSkip to conversation

PCI: iproc: Fix a non-compliant kernel-doc

PATCH Superseded Krzysztof Wilczyński 2 participants 4 messages May 19, 2021 – Jul 2, 2021

Subsystems (3)
PCI PCI native host bridge and endpoint drivers Broadcom iproc Arm architecture

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Krzysztof Wilczyński

author
#0 lore raw

PATCH v2 1/1 PCI: iproc: Fix a non-compliant kernel-doc

Correct a non-compliant kernel-doc used to describe struct and enum types and functions in the pcie-iproc.c and pcie-iproc-msi.c files, and resolve the following build time warning related to kernel-doc:

drivers/pci/controller/pcie-iproc.c:92: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:139: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:153: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:441: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:623: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:901: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst

drivers/pci/controller/pcie-iproc-msi.c:52: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc-msi.c:68: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst

No change to functionality intended.

Signed-off-by Krzysztof Wilczyński <[email protected]>
---
 drivers/pci/controller/pcie-iproc-msi.c | 16 ++++++++--------
 drivers/pci/controller/pcie-iproc.c     | 14 ++++++++------
 2 files changed, 16 insertions(+), 14 deletions(-)
drivers/pci/controller/pcie-iproc-msi.c +8 -8
index eede4e8f3f75..65ea83d2abfa 100644
@@ -49,14 +49,14 @@ enum iproc_msi_reg {
 struct iproc_msi;
 
 /**
- * iProc MSI group
- *
- * One MSI group is allocated per GIC interrupt, serviced by one iProc MSI
- * event queue.
+ * struct iproc_msi_grp - iProc MSI group
  *
  * @msi: pointer to iProc MSI data
  * @gic_irq: GIC interrupt
  * @eq: Event queue number
+ *
+ * One MSI group is allocated per GIC interrupt, serviced by one iProc MSI
+ * event queue.
  */
 struct iproc_msi_grp {
 	struct iproc_msi *msi;

@@ -65,10 +65,7 @@ struct iproc_msi_grp {
 };
 
 /**
- * iProc event queue based MSI
- *
- * Only meant to be used on platforms without MSI support integrated into the
- * GIC.
+ * struct iproc_msi - iProc event queue based MSI
  *
  * @pcie: pointer to iProc PCIe data
  * @reg_offsets: MSI register offsets

@@ -89,6 +86,9 @@ struct iproc_msi_grp {
  * @eq_cpu: pointer to allocated memory region for MSI event queues
  * @eq_dma: DMA address of MSI event queues
  * @msi_addr: MSI address
+ *
+ * Only meant to be used on platforms without MSI support integrated into the
+ * GIC.
  */
 struct iproc_msi {
 	struct iproc_pcie *pcie;
drivers/pci/controller/pcie-iproc.c +8 -6
index 02e52f698eeb..8e45288c9abc 100644
@@ -89,7 +89,8 @@
 #define IPROC_PCIE_REG_INVALID		0xffff
 
 /**
- * iProc PCIe outbound mapping controller specific parameters
+ * struct iproc_pcie_ob_map - iProc PCIe outbound mapping controller specific
+ *			      parameters.
  *
  * @window_sizes: list of supported outbound mapping window sizes in MB
  * @nr_sizes: number of supported outbound mapping window sizes

@@ -136,7 +137,7 @@ static const struct iproc_pcie_ob_map paxb_v2_ob_map[] = {
 };
 
 /**
- * iProc PCIe inbound mapping type
+ * enum iproc_pcie_ib_map_type - iProc PCIe inbound mapping type.
  */
 enum iproc_pcie_ib_map_type {
 	/* for DDR memory */

@@ -150,7 +151,8 @@ enum iproc_pcie_ib_map_type {
 };
 
 /**
- * iProc PCIe inbound mapping controller specific parameters
+ * struct iproc_pcie_ib_map - iProc PCIe inbound mapping controller specific
+ *			      parameters.
  *
  * @type: inbound mapping region type
  * @size_unit: inbound mapping region size unit, could be SZ_1K, SZ_1M, or

@@ -437,7 +439,7 @@ static inline void iproc_pcie_write_reg(struct iproc_pcie *pcie,
 	writel(val, pcie->base + offset);
 }
 
-/**
+/*
  * APB error forwarding can be disabled during access of configuration
  * registers of the endpoint device, to prevent unsupported requests
  * (typically seen during enumeration with multi-function devices) from

@@ -619,7 +621,7 @@ static int iproc_pcie_config_read(struct pci_bus *bus, unsigned int devfn,
 	return PCIBIOS_SUCCESSFUL;
 }
 
-/**
+/*
  * Note access to the configuration registers are protected at the higher layer
  * by 'pci_lock' in drivers/pci/access.c
  */

@@ -897,7 +899,7 @@ static inline int iproc_pcie_ob_write(struct iproc_pcie *pcie, int window_idx,
 	return 0;
 }
 
-/**
+/*
  * Some iProc SoCs require the SW to configure the outbound address mapping
  *
  * Outbound address translation:
Signature · 1 line
2.31.1
Acked-by Tested-by on v2 1/1
#1 lore raw

Hi,

This is a really good cleanup, but there is still one kernel-doc warning remaining after this patch is applied. Please see below.

Quoted 33 lines · Krzysztof Wilczyński

Correct a non-compliant kernel-doc used to describe struct and enum types and functions in the pcie-iproc.c and pcie-iproc-msi.c files, and resolve the following build time warning related to kernel-doc:

drivers/pci/controller/pcie-iproc.c:92: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:139: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:153: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:441: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:623: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.c:901: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst

drivers/pci/controller/pcie-iproc-msi.c:52: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc-msi.c:68: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst

No change to functionality intended.

Signed-off-by Krzysztof Wilczyński <[email protected]>
---
 drivers/pci/controller/pcie-iproc-msi.c | 16 ++++++++--------
 drivers/pci/controller/pcie-iproc.c     | 14 ++++++++------
 2 files changed, 16 insertions(+), 14 deletions(-)
drivers/pci/controller/pcie-iproc-msi.c +0 -0
index eede4e8f3f75..65ea83d2abfa 100644
drivers/pci/controller/pcie-iproc.c +0 -0
index 02e52f698eeb..8e45288c9abc 100644

drivers/pci/controller/pcie-iproc.c static const struct iproc_pcie_ob_map paxb_v2_ob_map[] = { · line 143

Quoted 8 lines
drivers/pci/controller/pcie-iproc.c +1 -1
@@ -136,7 +137,7 @@ static const struct iproc_pcie_ob_map paxb_v2_ob_map[] = {
 };
 
 /**
- * iProc PCIe inbound mapping type
+ * enum iproc_pcie_ib_map_type - iProc PCIe inbound mapping type.
  */
 enum iproc_pcie_ib_map_type {
 	/* for DDR memory */

The above gives me this:

pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_MEM' not described in enum 'iproc_pcie_ib_map_type' pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_IO' not described in enum 'iproc_pcie_ib_map_type' pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_INVALID' not described in enum 'iproc_pcie_ib_map_type'

If you could fix that, it would be Nice. :)

Even if not, it's a good cleanup. Thanks.

Acked-by Randy Dunlap <[email protected]>
Tested-by Randy Dunlap <[email protected]>
Signature · 1 line
~Randy
author
#2 lore raw

Hi,

Quoted 2 lines

This is a really good cleanup, but there is still one kernel-doc warning remaining after this patch is applied. Please see below.

[...]

Quoted 2 lines
Quoted 2 lines

- * iProc PCIe inbound mapping type
+ * enum iproc_pcie_ib_map_type - iProc PCIe inbound mapping type.

[...]

Quoted 11 lines

The above gives me this:

pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_MEM' not described in enum 'iproc_pcie_ib_map_type' pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_IO' not described in enum 'iproc_pcie_ib_map_type' pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_INVALID' not described in enum 'iproc_pcie_ib_map_type'

If you could fix that, it would be Nice. :)

Even if not, it's a good cleanup. Thanks.

Doh! Apologies! This is my bad - correcting the format of the kernel-doc made the parser go and check for the fields to be properly documented, thus this new warning. I need to also take care about this too, a very good point!

Thank you for catching this! I will update everything accordingly.

Krzysztof

author
#3 lore raw

Hi Randy,

[...]

Quoted 1 line

I will update everything accordingly.

Sorry for the delay! I just sent a v3 of this patch.

Krzysztof