[PATCH v3 0/6] PCI: Minor kerneldoc warning fixes

[PATCH v3 0/6] PCI: Minor kerneldoc warning fixes

[Krzysztof Kozlowski]

Hi,

Changes since v2:
1. Fix almost all warnings, except:
   drivers/pci/controller/pci-hyperv.c:2534: warning: Function parameter or member 'version' not described in 'hv_pci_protocol_negotiation'
   drivers/pci/controller/pci-hyperv.c:2534: warning: Function parameter or member 'num_version' not described in 'hv_pci_protocol_negotiation'
   Not sure what are these.

2. New patches, split per driver or subdirectory

Best regards,
Krzysztof

Krzysztof Kozlowski (6):
  PCI: Fix kerneldoc
  PCI: endpoint: Fix kerneldoc
  PCI: hotplug: Fix kerneldoc
  PCI: dwc: Fix kerneldoc
  PCI: rockchip: Fix kerneldoc
  PCI: xilinx: Fix kerneldoc

 drivers/pci/ats.c                               | 3 ++-
 drivers/pci/controller/dwc/pcie-designware-ep.c | 2 +-
 drivers/pci/controller/pcie-rockchip-ep.c       | 1 +
 drivers/pci/controller/pcie-xilinx-cpm.c        | 1 +
 drivers/pci/endpoint/functions/pci-epf-test.c   | 2 +-
 drivers/pci/endpoint/pci-ep-cfs.c               | 2 +-
 drivers/pci/endpoint/pci-epc-core.c             | 2 +-
 drivers/pci/endpoint/pci-epc-mem.c              | 2 +-
 drivers/pci/endpoint/pci-epf-core.c             | 4 +++-
 drivers/pci/hotplug/acpi_pcihp.c                | 4 ++--
 drivers/pci/hotplug/pciehp_core.c               | 1 +
 drivers/pci/of.c                                | 2 ++
 drivers/pci/pci-pf-stub.c                       | 2 +-
 drivers/pci/setup-bus.c                         | 1 +
 drivers/pci/vc.c                                | 1 -
 15 files changed, 19 insertions(+), 11 deletions(-)

-- 
2.17.1

[PATCH v3 1/6] PCI: Fix kerneldoc

[Krzysztof Kozlowski]

Fix W=1 compile warnings (invalid kerneldoc):

    drivers/pci/ats.c:196: warning: Function parameter or member 'pdev' not described in 'pci_enable_pri'
    drivers/pci/ats.c:196: warning: Function parameter or member 'reqs' not described in 'pci_enable_pri'
    drivers/pci/of.c:262: warning: Function parameter or member 'ib_resources' not described in 'devm_of_pci_get_host_bridge_resources'
    drivers/pci/pci-pf-stub.c:20: warning: cannot understand function prototype: 'const struct pci_device_id pci_pf_stub_whitelist[] = '
    drivers/pci/setup-bus.c:62: warning: Function parameter or member 'min_align' not described in 'add_to_list'
    drivers/pci/vc.c:188: warning: Excess function parameter 'name' description in 'pci_vc_do_save_buffer'

Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
---
 drivers/pci/ats.c         | 3 ++-
 drivers/pci/of.c          | 2 ++
 drivers/pci/pci-pf-stub.c | 2 +-
 drivers/pci/setup-bus.c   | 1 +
 drivers/pci/vc.c          | 1 -
 5 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/drivers/pci/ats.c b/drivers/pci/ats.c
index b761c1f72f67..2e1073052509 100644
--- a/drivers/pci/ats.c
+++ b/drivers/pci/ats.c
@@ -188,7 +188,8 @@ void pci_pri_init(struct pci_dev *pdev)
 
 /**
  * pci_enable_pri - Enable PRI capability
- * @ pdev: PCI device structure
+ * @pdev: PCI device structure
+ * @reqs: outstanding requests
  *
  * Returns 0 on success, negative value on error
  */
diff --git a/drivers/pci/of.c b/drivers/pci/of.c
index 22727fc9558d..d9621a603702 100644
--- a/drivers/pci/of.c
+++ b/drivers/pci/of.c
@@ -243,6 +243,8 @@ EXPORT_SYMBOL_GPL(of_pci_check_probe_only);
  * @busno: bus number associated with the bridge root bus
  * @bus_max: maximum number of buses for this bridge
  * @resources: list where the range of resources will be added after DT parsing
+ * @ib_resources: list where the range of inbound resources (with addresses
+ *                from 'dma-ranges' will be added after DT parsing
  * @io_base: pointer to a variable that will contain on return the physical
  * address for the start of the I/O range. Can be NULL if the caller doesn't
  * expect I/O ranges to be present in the device tree.
diff --git a/drivers/pci/pci-pf-stub.c b/drivers/pci/pci-pf-stub.c
index ef293e735c55..a0b2bd6c918a 100644
--- a/drivers/pci/pci-pf-stub.c
+++ b/drivers/pci/pci-pf-stub.c
@@ -9,7 +9,7 @@
 #include <linux/module.h>
 #include <linux/pci.h>
 
-/**
+/*
  * pci_pf_stub_whitelist - White list of devices to bind pci-pf-stub onto
  *
  * This table provides the list of IDs this driver is supposed to bind
diff --git a/drivers/pci/setup-bus.c b/drivers/pci/setup-bus.c
index 4d870ed89385..3951e02b7ded 100644
--- a/drivers/pci/setup-bus.c
+++ b/drivers/pci/setup-bus.c
@@ -55,6 +55,7 @@ static void free_list(struct list_head *head)
  * @dev:	Device to which the resource belongs
  * @res:	Resource to be tracked
  * @add_size:	Additional size to be optionally added to the resource
+ * @min_align:	Minimum memory window alignment
  */
 static int add_to_list(struct list_head *head, struct pci_dev *dev,
 		       struct resource *res, resource_size_t add_size,
diff --git a/drivers/pci/vc.c b/drivers/pci/vc.c
index 5486f8768c86..5fc59ac31145 100644
--- a/drivers/pci/vc.c
+++ b/drivers/pci/vc.c
@@ -172,7 +172,6 @@ static void pci_vc_enable(struct pci_dev *dev, int pos, int res)
  * @dev: device
  * @pos: starting position of VC capability (VC/VC9/MFVC)
  * @save_state: buffer for save/restore
- * @name: for error message
  * @save: if provided a buffer, this indicates what to do with it
  *
  * Walking Virtual Channel config space to size, save, or restore it
-- 
2.17.1

[PATCH v3 2/6] PCI: endpoint: Fix kerneldoc

[Krzysztof Kozlowski]

Fix W=1 compile warnings (invalid kerneldoc):

    drivers/pci/endpoint/pci-epc-core.c:18: warning: cannot understand function prototype: 'struct class *pci_epc_class; '
    drivers/pci/endpoint/pci-ep-cfs.c:17: warning: Function parameter or member 'functions_idr' not described in 'DEFINE_IDR'
    drivers/pci/endpoint/pci-epf-core.c:18: warning: Function parameter or member 'pci_epf_mutex' not described in 'DEFINE_MUTEX'
    drivers/pci/endpoint/pci-epf-core.c:80: warning: Function parameter or member 'epf' not described in 'pci_epf_free_space'
    drivers/pci/endpoint/pci-epf-core.c:107: warning: Function parameter or member 'epf' not described in 'pci_epf_alloc_space'
    drivers/pci/endpoint/pci-epc-mem.c:16: warning: Incorrect use of kernel-doc format:  * pci_epc_mem_get_order() - determine the allocation order of a memory size
    drivers/pci/endpoint/pci-epc-mem.c:24: warning: Function parameter or member 'mem' not described in 'pci_epc_mem_get_order'
    drivers/pci/endpoint/pci-epc-mem.c:24: warning: Function parameter or member 'size' not described in 'pci_epc_mem_get_order'
    drivers/pci/endpoint/functions/pci-epf-test.c:189: warning: Function parameter or member 'epf_test' not described in 'pci_epf_test_clean_dma_chan'
    drivers/pci/endpoint/functions/pci-epf-test.c:189: warning: Excess function parameter 'epf' description in 'pci_epf_test_clean_dma_chan'

Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
---
 drivers/pci/endpoint/functions/pci-epf-test.c | 2 +-
 drivers/pci/endpoint/pci-ep-cfs.c             | 2 +-
 drivers/pci/endpoint/pci-epc-core.c           | 2 +-
 drivers/pci/endpoint/pci-epc-mem.c            | 2 +-
 drivers/pci/endpoint/pci-epf-core.c           | 4 +++-
 5 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/drivers/pci/endpoint/functions/pci-epf-test.c b/drivers/pci/endpoint/functions/pci-epf-test.c
index c89a9561439f..e4e51d884553 100644
--- a/drivers/pci/endpoint/functions/pci-epf-test.c
+++ b/drivers/pci/endpoint/functions/pci-epf-test.c
@@ -181,7 +181,7 @@ static int pci_epf_test_init_dma_chan(struct pci_epf_test *epf_test)
 
 /**
  * pci_epf_test_clean_dma_chan() - Function to cleanup EPF test DMA channel
- * @epf: the EPF test device that performs data transfer operation
+ * @epf_test: the EPF test device that performs data transfer operation
  *
  * Helper to cleanup EPF test DMA channel.
  */
diff --git a/drivers/pci/endpoint/pci-ep-cfs.c b/drivers/pci/endpoint/pci-ep-cfs.c
index 55edce50be96..3710adf51912 100644
--- a/drivers/pci/endpoint/pci-ep-cfs.c
+++ b/drivers/pci/endpoint/pci-ep-cfs.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * configfs to configure the PCI endpoint
  *
  * Copyright (C) 2017 Texas Instruments
diff --git a/drivers/pci/endpoint/pci-epc-core.c b/drivers/pci/endpoint/pci-epc-core.c
index 82ba0dc7f2f5..cadd3db0cbb0 100644
--- a/drivers/pci/endpoint/pci-epc-core.c
+++ b/drivers/pci/endpoint/pci-epc-core.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * PCI Endpoint *Controller* (EPC) library
  *
  * Copyright (C) 2017 Texas Instruments
diff --git a/drivers/pci/endpoint/pci-epc-mem.c b/drivers/pci/endpoint/pci-epc-mem.c
index 80c46f3a4590..a97b56a6d2db 100644
--- a/drivers/pci/endpoint/pci-epc-mem.c
+++ b/drivers/pci/endpoint/pci-epc-mem.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * PCI Endpoint *Controller* Address Space Management
  *
  * Copyright (C) 2017 Texas Instruments
diff --git a/drivers/pci/endpoint/pci-epf-core.c b/drivers/pci/endpoint/pci-epf-core.c
index 244e00f48c5c..c977cf9dce56 100644
--- a/drivers/pci/endpoint/pci-epf-core.c
+++ b/drivers/pci/endpoint/pci-epf-core.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * PCI Endpoint *Function* (EPF) library
  *
  * Copyright (C) 2017 Texas Instruments
@@ -71,6 +71,7 @@ EXPORT_SYMBOL_GPL(pci_epf_bind);
 
 /**
  * pci_epf_free_space() - free the allocated PCI EPF register space
+ * @epf: the EPF device from whom to free the memory
  * @addr: the virtual address of the PCI EPF register space
  * @bar: the BAR number corresponding to the register space
  *
@@ -96,6 +97,7 @@ EXPORT_SYMBOL_GPL(pci_epf_free_space);
 
 /**
  * pci_epf_alloc_space() - allocate memory for the PCI EPF register space
+ * @epf: the EPF device to whom allocate the memory
  * @size: the size of the memory that has to be allocated
  * @bar: the BAR number corresponding to the allocated register space
  * @align: alignment size for the allocation region
-- 
2.17.1

[PATCH v3 3/6] PCI: hotplug: Fix kerneldoc

[Krzysztof Kozlowski]

Fix W=1 compile warnings (invalid kerneldoc):

    drivers/pci/hotplug/acpi_pcihp.c:69: warning: Function parameter or member 'pdev' not described in 'acpi_get_hp_hw_control_from_firmware'
    drivers/pci/hotplug/acpi_pcihp.c:69: warning: Excess function parameter 'dev' description in 'acpi_get_hp_hw_control_from_firmware'
    drivers/pci/hotplug/acpi_pcihp.c:199: warning: Function parameter or member 'handle' not described in 'acpi_pci_detect_ejectable'
    drivers/pci/hotplug/pciehp_core.c:165: warning: Function parameter or member 'ctrl' not described in 'pciehp_check_presence'

Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
---
 drivers/pci/hotplug/acpi_pcihp.c  | 4 ++--
 drivers/pci/hotplug/pciehp_core.c | 1 +
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/drivers/pci/hotplug/acpi_pcihp.c b/drivers/pci/hotplug/acpi_pcihp.c
index 6b7c1ed58e7e..2750a64cecd3 100644
--- a/drivers/pci/hotplug/acpi_pcihp.c
+++ b/drivers/pci/hotplug/acpi_pcihp.c
@@ -61,7 +61,7 @@ static acpi_status acpi_run_oshp(acpi_handle handle)
 
 /**
  * acpi_get_hp_hw_control_from_firmware
- * @dev: the pci_dev of the bridge that has a hotplug controller
+ * @pdev: the pci_dev of the bridge that has a hotplug controller
  *
  * Attempt to take hotplug control from firmware.
  */
@@ -191,7 +191,7 @@ check_hotplug(acpi_handle handle, u32 lvl, void *context, void **rv)
 
 /**
  * acpi_pci_detect_ejectable - check if the PCI bus has ejectable slots
- * @handle - handle of the PCI bus to scan
+ * @handle: handle of the PCI bus to scan
  *
  * Returns 1 if the PCI bus has ACPI based ejectable slots, 0 otherwise.
  */
diff --git a/drivers/pci/hotplug/pciehp_core.c b/drivers/pci/hotplug/pciehp_core.c
index bf779f291f15..ad3393930ecb 100644
--- a/drivers/pci/hotplug/pciehp_core.c
+++ b/drivers/pci/hotplug/pciehp_core.c
@@ -153,6 +153,7 @@ static int get_adapter_status(struct hotplug_slot *hotplug_slot, u8 *value)
 
 /**
  * pciehp_check_presence() - synthesize event if presence has changed
+ * @ctrl: controller to check
  *
  * On probe and resume, an explicit presence check is necessary to bring up an
  * occupied slot or bring down an unoccupied slot.  This can't be triggered by
-- 
2.17.1

[PATCH v3 4/6] PCI: dwc: Fix kerneldoc

[Krzysztof Kozlowski]

Fix W=1 compile warnings (invalid kerneldoc):

    drivers/pci/controller/dwc/pcie-designware-ep.c:16: warning: Function parameter or member 'ep' not described in 'dw_pcie_ep_linkup'

Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
---
 drivers/pci/controller/dwc/pcie-designware-ep.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/pci/controller/dwc/pcie-designware-ep.c b/drivers/pci/controller/dwc/pcie-designware-ep.c
index 5e5b8821bed8..305bfec2424d 100644
--- a/drivers/pci/controller/dwc/pcie-designware-ep.c
+++ b/drivers/pci/controller/dwc/pcie-designware-ep.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * Synopsys DesignWare PCIe Endpoint controller driver
  *
  * Copyright (C) 2017 Texas Instruments
-- 
2.17.1

[PATCH v3 5/6] PCI: rockchip: Fix kerneldoc

[Krzysztof Kozlowski]

Fix W=1 compile warnings (invalid kerneldoc):

    drivers/pci/controller/pcie-rockchip-ep.c:50: warning: Function parameter or member 'epc' not described in 'rockchip_pcie_ep'

Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
---
 drivers/pci/controller/pcie-rockchip-ep.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/pci/controller/pcie-rockchip-ep.c b/drivers/pci/controller/pcie-rockchip-ep.c
index 5eaf36629a75..7631dc3961c1 100644
--- a/drivers/pci/controller/pcie-rockchip-ep.c
+++ b/drivers/pci/controller/pcie-rockchip-ep.c
@@ -22,6 +22,7 @@
 /**
  * struct rockchip_pcie_ep - private data for PCIe endpoint controller driver
  * @rockchip: Rockchip PCIe controller
+ * @epc: PCI EPC device
  * @max_regions: maximum number of regions supported by hardware
  * @ob_region_map: bitmask of mapped outbound regions
  * @ob_addr: base addresses in the AXI bus where the outbound regions start
-- 
2.17.1

[PATCH v3 6/6] PCI: xilinx: Fix kerneldoc

[Krzysztof Kozlowski]

Fix W=1 compile warnings (invalid kerneldoc):

    drivers/pci/controller/pcie-xilinx-cpm.c:122: warning: Function parameter or member 'cpm_domain' not described in 'xilinx_cpm_pcie_port'

Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
---
 drivers/pci/controller/pcie-xilinx-cpm.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/pci/controller/pcie-xilinx-cpm.c b/drivers/pci/controller/pcie-xilinx-cpm.c
index 66f554694e03..cd8c77457b5f 100644
--- a/drivers/pci/controller/pcie-xilinx-cpm.c
+++ b/drivers/pci/controller/pcie-xilinx-cpm.c
@@ -104,6 +104,7 @@
  * @cpm_base: CPM System Level Control and Status Register(SLCR) Base
  * @dev: Device pointer
  * @intx_domain: Legacy IRQ domain pointer
+ * @cpm_domain: CPM IRQ domain pointer
  * @cfg: Holds mappings of config space window
  * @intx_irq: legacy interrupt number
  * @irq: Error interrupt number
-- 
2.17.1

Re: [PATCH v3 0/6] PCI: Minor kerneldoc warning fixes

[Bjorn Helgaas]

On Wed, Jul 29, 2020 at 10:12:18PM +0200, Krzysztof Kozlowski wrote:
> Hi,
> 
> Changes since v2:
> 1. Fix almost all warnings, except:
>    drivers/pci/controller/pci-hyperv.c:2534: warning: Function parameter or member 'version' not described in 'hv_pci_protocol_negotiation'
>    drivers/pci/controller/pci-hyperv.c:2534: warning: Function parameter or member 'num_version' not described in 'hv_pci_protocol_negotiation'
>    Not sure what are these.
> 
> 2. New patches, split per driver or subdirectory
> 
> Best regards,
> Krzysztof
> 
> Krzysztof Kozlowski (6):
>   PCI: Fix kerneldoc
>   PCI: endpoint: Fix kerneldoc
>   PCI: hotplug: Fix kerneldoc
>   PCI: dwc: Fix kerneldoc
>   PCI: rockchip: Fix kerneldoc
>   PCI: xilinx: Fix kerneldoc
> 
>  drivers/pci/ats.c                               | 3 ++-
>  drivers/pci/controller/dwc/pcie-designware-ep.c | 2 +-
>  drivers/pci/controller/pcie-rockchip-ep.c       | 1 +
>  drivers/pci/controller/pcie-xilinx-cpm.c        | 1 +
>  drivers/pci/endpoint/functions/pci-epf-test.c   | 2 +-
>  drivers/pci/endpoint/pci-ep-cfs.c               | 2 +-
>  drivers/pci/endpoint/pci-epc-core.c             | 2 +-
>  drivers/pci/endpoint/pci-epc-mem.c              | 2 +-
>  drivers/pci/endpoint/pci-epf-core.c             | 4 +++-
>  drivers/pci/hotplug/acpi_pcihp.c                | 4 ++--
>  drivers/pci/hotplug/pciehp_core.c               | 1 +
>  drivers/pci/of.c                                | 2 ++
>  drivers/pci/pci-pf-stub.c                       | 2 +-
>  drivers/pci/setup-bus.c                         | 1 +
>  drivers/pci/vc.c                                | 1 -
>  15 files changed, 19 insertions(+), 11 deletions(-)

Thanks, I squashed these all together and applied them on pci/doc for
v5.9.

This was a tiny bit messy because pcie-xilinx-cpm.c is new this cycle
and ideally we would have squashed that fix into the original commit,
but we don't need to bother with that.