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

Fix a non-compliant kernel-doc used to describe struct and enum types and functions in the pcie-iproc.c, pcie-iproc-msi.c and pcie-iproc.h files.

Add missing documentation of the "mem" filed of the struct iproc_pcie, and the enum values "IPROC_PCIE_IB_MAP_MEM", "IPROC_PCIE_IB_MAP_IO" and "IPROC_PCIE_IB_MAP_INVALID" of the enum iproc_pcie_ib_map_type.

Thus, 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.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_MEM' not described in enum 'iproc_pcie_ib_map_type' drivers/pci/controller/pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_IO' not described in enum 'iproc_pcie_ib_map_type' drivers/pci/controller/pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_INVALID' not described in enum 'iproc_pcie_ib_map_type'

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

drivers/pci/controller/pcie-iproc.h:11: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.h:28: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.h:39: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.h:51: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst drivers/pci/controller/pcie-iproc.h:112: warning: Function parameter or member 'mem' not described in 'iproc_pcie'

No change to functionality intended.

---
 drivers/pci/controller/pcie-iproc-msi.c | 54 +++++++--------
 drivers/pci/controller/pcie-iproc.c     | 49 +++++++-------
 drivers/pci/controller/pcie-iproc.h     | 88 +++++++++++++++----------
 3 files changed, 103 insertions(+), 88 deletions(-)

index eede4e8f3f75..d20e66319774 100644
@@ -49,14 +49,14 @@ enum iproc_msi_reg {
 struct iproc_msi;
 
 /**
- * iProc MSI group
+ * struct iproc_msi_grp - iProc MSI group.
  *
- * One MSI group is allocated per GIC interrupt, serviced by one iProc MSI
- * event queue.
+ * @msi:	Pointer to iProc MSI data.
+ * @gic_irq:	GIC interrupt.
+ * @eq:		Event queue number.
  *
- * @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,30 +65,30 @@ struct iproc_msi_grp {
 };
 
 /**
- * iProc event queue based MSI
+ * struct iproc_msi - iProc event queue based MSI.
+ *
+ * @pcie:		Pointer to iProc PCIe data.
+ * @reg_offsets:	MSI register offsets.
+ * @grps:		MSI groups.
+ * @nr_irqs:		Number of total interrupts connected to GIC.
+ * @nr_cpus:		Number of toal CPUs.
+ * @has_inten_reg:	Indicates the MSI interrupt enable register needs to be
+ *			set explicitly (required for some legacy platforms).
+ * @bitmap:		MSI vector bitmap.
+ * @bitmap_lock:	Lock to protect access to the MSI bitmap.
+ * @nr_msi_vecs:	Total number of MSI vectors.
+ * @inner_domain:	Inner IRQ domain.
+ * @msi_domain:		MSI IRQ domain.
+ * @nr_eq_region:	Required number of 4K aligned memory region for MSI
+ *			event queues.
+ * @nr_msi_region:	Required number of 4K aligned address region for MSI
+ *			posted writes.
+ * @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.
- *
- * @pcie: pointer to iProc PCIe data
- * @reg_offsets: MSI register offsets
- * @grps: MSI groups
- * @nr_irqs: number of total interrupts connected to GIC
- * @nr_cpus: number of toal CPUs
- * @has_inten_reg: indicates the MSI interrupt enable register needs to be
- * set explicitly (required for some legacy platforms)
- * @bitmap: MSI vector bitmap
- * @bitmap_lock: lock to protect access to the MSI bitmap
- * @nr_msi_vecs: total number of MSI vectors
- * @inner_domain: inner IRQ domain
- * @msi_domain: MSI IRQ domain
- * @nr_eq_region: required number of 4K aligned memory region for MSI event
- * queues
- * @nr_msi_region: required number of 4K aligned address region for MSI posted
- * writes
- * @eq_cpu: pointer to allocated memory region for MSI event queues
- * @eq_dma: DMA address of MSI event queues
- * @msi_addr: MSI address
  */
 struct iproc_msi {
 	struct iproc_pcie *pcie;

2.32.0

thanks.

~Randy

Hi Randy,

This patch has been superseded by the following series:
https://lore.kernel.org/linux-pci/[email protected]/T/

New patch as been reworked as per feedback from Lukas Wunner. I sincerely apologise for all the commotion with these trivial patches.

Krzysztof