linux-pci.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation
@ 2021-03-11  0:17 Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 2/8] PCI/AER: Update functions names in the kernel-doc Krzysztof Wilczyński
                   ` (7 more replies)
  0 siblings, 8 replies; 9+ messages in thread
From: Krzysztof Wilczyński @ 2021-03-11  0:17 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Lorenzo Pieralisi, Kishon Vijay Abraham I, Tom Joseph,
	Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

Add missing documentation for the parameters "ntb_epc", "type", "dev",
and "group" of the following functions:

  - epf_ntb_add_cfs()
  - epf_ntb_alloc_peer_mem()
  - epf_ntb_config_sspad_bar_clear(),
  - epf_ntb_config_sspad_bar_set()
  - epf_ntb_peer_spad_bar_clear()
  - epf_ntb_peer_spad_bar_set()
  - pci_epc_remove_epf()

Remove surplus parameter from the epf_ntb_init_epc_bar() function.

Additionally, fix a non-compliant kernel-doc at the top of the files
pci-epf-ntb.c and pci-epf-test.c, and resolve number of build time
warnings related to kernel-doc:

 drivers/pci/endpoint/functions/pci-epf-ntb.c:1363: warning: Function
 parameter or member 'dev' not described in 'epf_ntb_alloc_peer_mem'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:2046: warning: Function
 parameter or member 'group' not described in 'epf_ntb_add_cfs'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:1670: warning: Excess
 function parameter 'type' description in 'epf_ntb_init_epc_bar'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:45: warning: cannot
 understand function prototype: 'struct workqueue_struct
 *kpcintb_workqueue; '

 drivers/pci/endpoint/functions/pci-epf-ntb.c:727: warning: Excess
 function parameter 'ntb' description in 'epf_ntb_peer_spad_bar_clear'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:727: warning: Function
 parameter or member 'ntb_epc' not described in
 'epf_ntb_peer_spad_bar_clear'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:771: warning: Function
 parameter or member 'type' not described in 'epf_ntb_peer_spad_bar_set'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:839: warning: Excess
 function parameter 'ntb' description in
 'epf_ntb_config_sspad_bar_clear'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:839: warning: Function
 parameter or member 'ntb_epc' not described in
 'epf_ntb_config_sspad_bar_clear'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:882: warning: Excess
 function parameter 'ntb' description in 'epf_ntb_config_sspad_bar_set'

 drivers/pci/endpoint/functions/pci-epf-ntb.c:882: warning: Function
 parameter or member 'ntb_epc' not described in
 'epf_ntb_config_sspad_bar_set'

 drivers/pci/endpoint/functions/pci-epf-test.c:22: warning: expecting
 prototype for Test driver to test endpoint functionality(). Prototype
 was for IRQ_TYPE_LEGACY() instead

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/endpoint/functions/pci-epf-ntb.c  | 16 +++++++++++-----
 drivers/pci/endpoint/functions/pci-epf-test.c |  2 +-
 drivers/pci/endpoint/pci-epc-core.c           |  2 ++
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/drivers/pci/endpoint/functions/pci-epf-ntb.c b/drivers/pci/endpoint/functions/pci-epf-ntb.c
index 338148cf56f5..bce274d02dcf 100644
--- a/drivers/pci/endpoint/functions/pci-epf-ntb.c
+++ b/drivers/pci/endpoint/functions/pci-epf-ntb.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * Endpoint Function Driver to implement Non-Transparent Bridge functionality
  *
  * Copyright (C) 2020 Texas Instruments
@@ -696,7 +696,8 @@ static void epf_ntb_cmd_handler(struct work_struct *work)
 
 /**
  * epf_ntb_peer_spad_bar_clear() - Clear Peer Scratchpad BAR
- * @ntb: NTB device that facilitates communication between HOST1 and HOST2
+ * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
+ *	     address.
  *
  *+-----------------+------->+------------------+        +-----------------+
  *|       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
@@ -740,6 +741,7 @@ static void epf_ntb_peer_spad_bar_clear(struct epf_ntb_epc *ntb_epc)
 /**
  * epf_ntb_peer_spad_bar_set() - Set peer scratchpad BAR
  * @ntb: NTB device that facilitates communication between HOST1 and HOST2
+ * @type: PRIMARY interface or SECONDARY interface
  *
  *+-----------------+------->+------------------+        +-----------------+
  *|       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
@@ -808,7 +810,8 @@ static int epf_ntb_peer_spad_bar_set(struct epf_ntb *ntb,
 
 /**
  * epf_ntb_config_sspad_bar_clear() - Clear Config + Self scratchpad BAR
- * @ntb: NTB device that facilitates communication between HOST1 and HOST2
+ * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
+ *	     address.
  *
  * +-----------------+------->+------------------+        +-----------------+
  * |       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
@@ -851,7 +854,8 @@ static void epf_ntb_config_sspad_bar_clear(struct epf_ntb_epc *ntb_epc)
 
 /**
  * epf_ntb_config_sspad_bar_set() - Set Config + Self scratchpad BAR
- * @ntb: NTB device that facilitates communication between HOST1 and HOST2
+ * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
+ *	     address.
  *
  * +-----------------+------->+------------------+        +-----------------+
  * |       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
@@ -1312,6 +1316,7 @@ static int epf_ntb_configure_interrupt(struct epf_ntb *ntb,
 
 /**
  * epf_ntb_alloc_peer_mem() - Allocate memory in peer's outbound address space
+ * @dev: The PCI device.
  * @ntb_epc: EPC associated with one of the HOST whose BAR holds peer's outbound
  *   address
  * @bar: BAR of @ntb_epc in for which memory has to be allocated (could be
@@ -1660,7 +1665,6 @@ static int epf_ntb_init_epc_bar_interface(struct epf_ntb *ntb,
  * epf_ntb_init_epc_bar() - Identify BARs to be used for each of the NTB
  * constructs (scratchpad region, doorbell, memorywindow)
  * @ntb: NTB device that facilitates communication between HOST1 and HOST2
- * @type: PRIMARY interface or SECONDARY interface
  *
  * Wrapper to epf_ntb_init_epc_bar_interface() to identify the free BARs
  * to be used for each of BAR_CONFIG, BAR_PEER_SPAD, BAR_DB_MW1, BAR_MW2,
@@ -2037,6 +2041,8 @@ static const struct config_item_type ntb_group_type = {
 /**
  * epf_ntb_add_cfs() - Add configfs directory specific to NTB
  * @epf: NTB endpoint function device
+ * @group: A pointer to the config_group structure referencing a group of
+ *	   config_items of a specific type that belong to a specific sub-system.
  *
  * Add configfs directory specific to NTB. This directory will hold
  * NTB specific properties like db_count, spad_count, num_mws etc.,
diff --git a/drivers/pci/endpoint/functions/pci-epf-test.c b/drivers/pci/endpoint/functions/pci-epf-test.c
index c0ac4e9cbe72..63d5f5c6e3e0 100644
--- a/drivers/pci/endpoint/functions/pci-epf-test.c
+++ b/drivers/pci/endpoint/functions/pci-epf-test.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * Test driver to test endpoint functionality
  *
  * Copyright (C) 2017 Texas Instruments
diff --git a/drivers/pci/endpoint/pci-epc-core.c b/drivers/pci/endpoint/pci-epc-core.c
index cc8f9eb2b177..adec9bee72cf 100644
--- a/drivers/pci/endpoint/pci-epc-core.c
+++ b/drivers/pci/endpoint/pci-epc-core.c
@@ -594,6 +594,8 @@ EXPORT_SYMBOL_GPL(pci_epc_add_epf);
  * pci_epc_remove_epf() - remove PCI endpoint function from endpoint controller
  * @epc: the EPC device from which the endpoint function should be removed
  * @epf: the endpoint function to be removed
+ * @type: identifies if the EPC is connected to the primary or secondary
+ *        interface of EPF
  *
  * Invoke to remove PCI endpoint function from the endpoint controller.
  */
-- 
2.30.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 2/8] PCI/AER: Update functions names in the kernel-doc
  2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
@ 2021-03-11  0:17 ` Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 3/8] PCI/PME: Update function name " Krzysztof Wilczyński
                   ` (6 subsequent siblings)
  7 siblings, 0 replies; 9+ messages in thread
From: Krzysztof Wilczyński @ 2021-03-11  0:17 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Lorenzo Pieralisi, Kishon Vijay Abraham I, Tom Joseph,
	Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

Update function names in the kernel-doc to match function prototypes
for functions enable_ecrc_checking(), disable_ecrc_checking() and
pcie_aer_init(), and resolve build time warnings related to kernel-doc:

 drivers/pci/pcie/aer.c:138: warning: expecting prototype for
 enable_ercr_checking(). Prototype was for enable_ecrc_checking()
 instead

 drivers/pci/pcie/aer.c:1450: warning: expecting prototype for
 aer_service_init(). Prototype was for pcie_aer_init() instead

 drivers/pci/pcie/aer.c:162: warning: expecting prototype for
 disable_ercr_checking(). Prototype was for disable_ecrc_checking()
 instead

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/pcie/aer.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/pci/pcie/aer.c b/drivers/pci/pcie/aer.c
index ba22388342d1..ec943cee5ecc 100644
--- a/drivers/pci/pcie/aer.c
+++ b/drivers/pci/pcie/aer.c
@@ -129,7 +129,7 @@ static const char * const ecrc_policy_str[] = {
 };
 
 /**
- * enable_ercr_checking - enable PCIe ECRC checking for a device
+ * enable_ecrc_checking - enable PCIe ECRC checking for a device
  * @dev: the PCI device
  *
  * Returns 0 on success, or negative on failure.
@@ -153,7 +153,7 @@ static int enable_ecrc_checking(struct pci_dev *dev)
 }
 
 /**
- * disable_ercr_checking - disables PCIe ECRC checking for a device
+ * disable_ecrc_checking - disables PCIe ECRC checking for a device
  * @dev: the PCI device
  *
  * Returns 0 on success, or negative on failure.
@@ -1442,7 +1442,7 @@ static struct pcie_port_service_driver aerdriver = {
 };
 
 /**
- * aer_service_init - register AER root service driver
+ * pcie_aer_init - register AER root service driver
  *
  * Invoked when AER root service driver is loaded.
  */
-- 
2.30.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 3/8] PCI/PME: Update function name in the kernel-doc
  2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 2/8] PCI/AER: Update functions names in the kernel-doc Krzysztof Wilczyński
@ 2021-03-11  0:17 ` Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 4/8] PCI/ATS: " Krzysztof Wilczyński
                   ` (5 subsequent siblings)
  7 siblings, 0 replies; 9+ messages in thread
From: Krzysztof Wilczyński @ 2021-03-11  0:17 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Lorenzo Pieralisi, Kishon Vijay Abraham I, Tom Joseph,
	Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

Update function name in the kernel-doc to match function prototype for
function pcie_pme_init(), and resolve build time warning related to
kernel-doc:

  drivers/pci/pcie/pme.c:469: warning: expecting prototype for
  pcie_pme_service_init(). Prototype was for pcie_pme_init() instead

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/pcie/pme.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/pci/pcie/pme.c b/drivers/pci/pcie/pme.c
index 3fc08488d65f..1d0dd77fed3a 100644
--- a/drivers/pci/pcie/pme.c
+++ b/drivers/pci/pcie/pme.c
@@ -463,7 +463,7 @@ static struct pcie_port_service_driver pcie_pme_driver = {
 };
 
 /**
- * pcie_pme_service_init - Register the PCIe PME service driver.
+ * pcie_pme_init - Register the PCIe PME service driver.
  */
 int __init pcie_pme_init(void)
 {
-- 
2.30.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 4/8] PCI/ATS: Update function name in the kernel-doc
  2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 2/8] PCI/AER: Update functions names in the kernel-doc Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 3/8] PCI/PME: Update function name " Krzysztof Wilczyński
@ 2021-03-11  0:17 ` Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 5/8] PCI: " Krzysztof Wilczyński
                   ` (4 subsequent siblings)
  7 siblings, 0 replies; 9+ messages in thread
From: Krzysztof Wilczyński @ 2021-03-11  0:17 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Lorenzo Pieralisi, Kishon Vijay Abraham I, Tom Joseph,
	Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

Update function name in the kernel-doc to match function prototype for
function pci_max_pasids(), and resolve build time warning related to
kernel-doc:

  drivers/pci/ats.c:490: warning: expecting prototype for
  pci_max_pasid(). Prototype was for pci_max_pasids() instead

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/ats.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/pci/ats.c b/drivers/pci/ats.c
index 0d3719407b8b..6d7d64939f82 100644
--- a/drivers/pci/ats.c
+++ b/drivers/pci/ats.c
@@ -480,7 +480,7 @@ EXPORT_SYMBOL_GPL(pci_pasid_features);
 #define PASID_NUMBER_SHIFT	8
 #define PASID_NUMBER_MASK	(0x1f << PASID_NUMBER_SHIFT)
 /**
- * pci_max_pasid - Get maximum number of PASIDs supported by device
+ * pci_max_pasids - Get maximum number of PASIDs supported by device
  * @pdev: PCI device structure
  *
  * Returns negative value when PASID capability is not present.
-- 
2.30.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 5/8] PCI: Update function name in the kernel-doc
  2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
                   ` (2 preceding siblings ...)
  2021-03-11  0:17 ` [PATCH 4/8] PCI/ATS: " Krzysztof Wilczyński
@ 2021-03-11  0:17 ` Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 6/8] PCI: j721e: Fix a non-compliant kernel-doc Krzysztof Wilczyński
                   ` (3 subsequent siblings)
  7 siblings, 0 replies; 9+ messages in thread
From: Krzysztof Wilczyński @ 2021-03-11  0:17 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Lorenzo Pieralisi, Kishon Vijay Abraham I, Tom Joseph,
	Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

Update function name in the kernel-doc to match function prototype for
function acpi_pci_check_ejectable(), and resolve build time warning
related to kernel-doc:

  drivers/pci/hotplug/acpi_pcihp.c:167: warning: expecting prototype for
  acpi_pcihp_check_ejectable(). Prototype was for acpi_pci_check_ejectable()
  instead

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/hotplug/acpi_pcihp.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/pci/hotplug/acpi_pcihp.c b/drivers/pci/hotplug/acpi_pcihp.c
index 2750a64cecd3..4fedebf2f8c1 100644
--- a/drivers/pci/hotplug/acpi_pcihp.c
+++ b/drivers/pci/hotplug/acpi_pcihp.c
@@ -157,7 +157,7 @@ static int pcihp_is_ejectable(acpi_handle handle)
 }
 
 /**
- * acpi_pcihp_check_ejectable - check if handle is ejectable ACPI PCI slot
+ * acpi_pci_check_ejectable - check if handle is ejectable ACPI PCI slot
  * @pbus: the PCI bus of the PCI slot corresponding to 'handle'
  * @handle: ACPI handle to check
  *
-- 
2.30.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 6/8] PCI: j721e: Fix a non-compliant kernel-doc
  2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
                   ` (3 preceding siblings ...)
  2021-03-11  0:17 ` [PATCH 5/8] PCI: " Krzysztof Wilczyński
@ 2021-03-11  0:17 ` Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 7/8] PCI: dwc: Remove surplus and document missing function parameters Krzysztof Wilczyński
                   ` (2 subsequent siblings)
  7 siblings, 0 replies; 9+ messages in thread
From: Krzysztof Wilczyński @ 2021-03-11  0:17 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Lorenzo Pieralisi, Kishon Vijay Abraham I, Tom Joseph,
	Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

Correct a non-compliant kernel-doc at the top of the pci-j721e.c file,
and resolve build time warning related to kernel-doc:

  drivers/pci/controller/cadence/pci-j721e.c:25: warning: expecting
  prototype for pci(). Prototype was for ENABLE_REG_SYS_2() instead

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/controller/cadence/pci-j721e.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/pci/controller/cadence/pci-j721e.c b/drivers/pci/controller/cadence/pci-j721e.c
index 849f1e416ea5..f1eef67e9526 100644
--- a/drivers/pci/controller/cadence/pci-j721e.c
+++ b/drivers/pci/controller/cadence/pci-j721e.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * pci-j721e - PCIe controller driver for TI's J721E SoCs
  *
  * Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com
-- 
2.30.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 7/8] PCI: dwc: Remove surplus and document missing function parameters
  2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
                   ` (4 preceding siblings ...)
  2021-03-11  0:17 ` [PATCH 6/8] PCI: j721e: Fix a non-compliant kernel-doc Krzysztof Wilczyński
@ 2021-03-11  0:17 ` Krzysztof Wilczyński
  2021-03-11  0:17 ` [PATCH 8/8] PCI: of: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
  2021-03-11 23:38 ` [PATCH 1/8] PCI: endpoint: " Bjorn Helgaas
  7 siblings, 0 replies; 9+ messages in thread
From: Krzysztof Wilczyński @ 2021-03-11  0:17 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Lorenzo Pieralisi, Kishon Vijay Abraham I, Tom Joseph,
	Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

Add missing documentation for the parameters "ks_pcie", "bus"
and "pci" of the ks_pcie_set_dbi_mode(), ks_pcie_clear_dbi_mode(),
ks_pcie_v3_65_add_bus() and ks_pcie_link_up() functions and resolve
build time warnings related to kernel-doc:

  drivers/pci/controller/dwc/pci-keystone.c:356: warning: Function
  parameter or member 'ks_pcie' not described in 'ks_pcie_set_dbi_mode'

  drivers/pci/controller/dwc/pci-keystone.c:375: warning: Function
  parameter or member 'ks_pcie' not described in
  'ks_pcie_clear_dbi_mode'

  drivers/pci/controller/dwc/pci-keystone.c:456: warning: Function
  parameter or member 'bus' not described in 'ks_pcie_v3_65_add_bus'

  drivers/pci/controller/dwc/pci-keystone.c:493: warning: Function
  parameter or member 'pci' not described in 'ks_pcie_link_up'

  drivers/pci/controller/dwc/pci-keystone.c:615: warning: Excess
  function parameter 'irq' description in 'ks_pcie_legacy_irq_handler'

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/controller/dwc/pci-keystone.c | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/drivers/pci/controller/dwc/pci-keystone.c b/drivers/pci/controller/dwc/pci-keystone.c
index 53aa35cb3a49..6745e69b7020 100644
--- a/drivers/pci/controller/dwc/pci-keystone.c
+++ b/drivers/pci/controller/dwc/pci-keystone.c
@@ -346,8 +346,9 @@ static const struct irq_domain_ops ks_pcie_legacy_irq_domain_ops = {
 };
 
 /**
- * ks_pcie_set_dbi_mode() - Set DBI mode to access overlaid BAR mask
- * registers
+ * ks_pcie_set_dbi_mode() - Set DBI mode to access overlaid BAR mask registers
+ * @ks_pcie: A pointer to the keystone_pcie structure which holds the KeyStone
+ *	     PCIe host controller driver information.
  *
  * Since modification of dbi_cs2 involves different clock domain, read the
  * status back to ensure the transition is complete.
@@ -367,6 +368,8 @@ static void ks_pcie_set_dbi_mode(struct keystone_pcie *ks_pcie)
 
 /**
  * ks_pcie_clear_dbi_mode() - Disable DBI mode
+ * @ks_pcie: A pointer to the keystone_pcie structure which holds the KeyStone
+ *	     PCIe host controller driver information.
  *
  * Since modification of dbi_cs2 involves different clock domain, read the
  * status back to ensure the transition is complete.
@@ -449,6 +452,7 @@ static struct pci_ops ks_child_pcie_ops = {
 
 /**
  * ks_pcie_v3_65_add_bus() - keystone add_bus post initialization
+ * @bus: A pointer to the PCI bus structure.
  *
  * This sets BAR0 to enable inbound access for MSI_IRQ register
  */
@@ -488,6 +492,8 @@ static struct pci_ops ks_pcie_ops = {
 
 /**
  * ks_pcie_link_up() - Check if link up
+ * @pci: A pointer to the dw_pcie structure which holds the DesignWare PCIe host
+ *	 controller driver information.
  */
 static int ks_pcie_link_up(struct dw_pcie *pci)
 {
@@ -605,7 +611,6 @@ static void ks_pcie_msi_irq_handler(struct irq_desc *desc)
 
 /**
  * ks_pcie_legacy_irq_handler() - Handle legacy interrupt
- * @irq: IRQ line for legacy interrupts
  * @desc: Pointer to irq descriptor
  *
  * Traverse through pending legacy interrupts and invoke handler for each. Also
-- 
2.30.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 8/8] PCI: of: Fix kernel-doc formatting and add missing documentation
  2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
                   ` (5 preceding siblings ...)
  2021-03-11  0:17 ` [PATCH 7/8] PCI: dwc: Remove surplus and document missing function parameters Krzysztof Wilczyński
@ 2021-03-11  0:17 ` Krzysztof Wilczyński
  2021-03-11 23:38 ` [PATCH 1/8] PCI: endpoint: " Bjorn Helgaas
  7 siblings, 0 replies; 9+ messages in thread
From: Krzysztof Wilczyński @ 2021-03-11  0:17 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Lorenzo Pieralisi, Kishon Vijay Abraham I, Tom Joseph,
	Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

Fix kernel-doc formatting and add missing documentation for the "node"
parameter of the of_get_pci_domain_nr() and of_pci_get_max_link_speed()
functions, and resolve build time warnings related to kernel-doc:

  drivers/pci/of.c:202: warning: expecting prototype for This function
  will try to obtain the host bridge domain number by(). Prototype was
  for of_get_pci_domain_nr() instead

  drivers/pci/of.c:597: warning: expecting prototype for This function
  will try to find the limitation of link speed by finding(). Prototype
  was for of_pci_get_max_link_speed() instead

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/of.c | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/drivers/pci/of.c b/drivers/pci/of.c
index 5ea472ae22ac..da5b414d585a 100644
--- a/drivers/pci/of.c
+++ b/drivers/pci/of.c
@@ -190,10 +190,18 @@ int of_pci_parse_bus_range(struct device_node *node, struct resource *res)
 EXPORT_SYMBOL_GPL(of_pci_parse_bus_range);
 
 /**
- * This function will try to obtain the host bridge domain number by
- * finding a property called "linux,pci-domain" of the given device node.
+ * of_get_pci_domain_nr - Find the host bridge domain number
+ *			  of the given device node.
+ * @node: Device tree node with the domain information.
  *
- * @node: device tree node with the domain information
+ * This function will try to obtain the host bridge domain number by finding
+ * a property called "linux,pci-domain" of the given device node.
+ *
+ * Return:
+ * * > 0	- On success, an associated domain number.
+ * * -EINVAL	- The property "linux,pci-domain" does not exist.
+ * * -ENODATA	- The linux,pci-domain" property does not have value.
+ * * -EOVERFLOW	- Invalid "linux,pci-domain" property value.
  *
  * Returns the associated domain number from DT in the range [0-0xffff], or
  * a negative value if the required property is not found.
@@ -585,10 +593,16 @@ int devm_of_pci_bridge_init(struct device *dev, struct pci_host_bridge *bridge)
 #endif /* CONFIG_PCI */
 
 /**
+ * of_pci_get_max_link_speed - Find the maximum link speed of the given device node.
+ * @node: Device tree node with the maximum link speed information.
+ *
  * This function will try to find the limitation of link speed by finding
  * a property called "max-link-speed" of the given device node.
  *
- * @node: device tree node with the max link speed information
+ * Return:
+ * * > 0	- On success, a maximum link speed.
+ * * -EINVAL	- Invalid "max-link-speed" property value, or failure to access
+ *		  the property of the device tree node.
  *
  * Returns the associated max link speed from DT, or a negative value if the
  * required property is not found or is invalid.
-- 
2.30.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation
  2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
                   ` (6 preceding siblings ...)
  2021-03-11  0:17 ` [PATCH 8/8] PCI: of: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
@ 2021-03-11 23:38 ` Bjorn Helgaas
  7 siblings, 0 replies; 9+ messages in thread
From: Bjorn Helgaas @ 2021-03-11 23:38 UTC (permalink / raw)
  To: Krzysztof Wilczyński
  Cc: Bjorn Helgaas, Lorenzo Pieralisi, Kishon Vijay Abraham I,
	Tom Joseph, Murali Karicheri, Rob Herring, Russell Currey,
	Oliver O'Halloran, Geert Uytterhoeven, Arnd Bergmann,
	Krzysztof Kozlowski, Kunihiko Hayashi, Sean V Kelley, Qiuxu Zhuo,
	Jay Fang, linux-pci

On Thu, Mar 11, 2021 at 12:17:17AM +0000, Krzysztof Wilczyński wrote:
> Add missing documentation for the parameters "ntb_epc", "type", "dev",
> and "group" of the following functions:
> 
>   - epf_ntb_add_cfs()
>   - epf_ntb_alloc_peer_mem()
>   - epf_ntb_config_sspad_bar_clear(),
>   - epf_ntb_config_sspad_bar_set()
>   - epf_ntb_peer_spad_bar_clear()
>   - epf_ntb_peer_spad_bar_set()
>   - pci_epc_remove_epf()
> 
> Remove surplus parameter from the epf_ntb_init_epc_bar() function.
> 
> Additionally, fix a non-compliant kernel-doc at the top of the files
> pci-epf-ntb.c and pci-epf-test.c, and resolve number of build time
> warnings related to kernel-doc:
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:1363: warning: Function
>  parameter or member 'dev' not described in 'epf_ntb_alloc_peer_mem'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:2046: warning: Function
>  parameter or member 'group' not described in 'epf_ntb_add_cfs'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:1670: warning: Excess
>  function parameter 'type' description in 'epf_ntb_init_epc_bar'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:45: warning: cannot
>  understand function prototype: 'struct workqueue_struct
>  *kpcintb_workqueue; '
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:727: warning: Excess
>  function parameter 'ntb' description in 'epf_ntb_peer_spad_bar_clear'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:727: warning: Function
>  parameter or member 'ntb_epc' not described in
>  'epf_ntb_peer_spad_bar_clear'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:771: warning: Function
>  parameter or member 'type' not described in 'epf_ntb_peer_spad_bar_set'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:839: warning: Excess
>  function parameter 'ntb' description in
>  'epf_ntb_config_sspad_bar_clear'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:839: warning: Function
>  parameter or member 'ntb_epc' not described in
>  'epf_ntb_config_sspad_bar_clear'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:882: warning: Excess
>  function parameter 'ntb' description in 'epf_ntb_config_sspad_bar_set'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:882: warning: Function
>  parameter or member 'ntb_epc' not described in
>  'epf_ntb_config_sspad_bar_set'
> 
>  drivers/pci/endpoint/functions/pci-epf-test.c:22: warning: expecting
>  prototype for Test driver to test endpoint functionality(). Prototype
>  was for IRQ_TYPE_LEGACY() instead
> 
> No change to functionality intended.
> 
> Signed-off-by: Krzysztof Wilczyński <kw@linux.com>

Applied all to pci/kernel-doc, thanks!  I squashed them into one patch
since these only change comments.

> ---
>  drivers/pci/endpoint/functions/pci-epf-ntb.c  | 16 +++++++++++-----
>  drivers/pci/endpoint/functions/pci-epf-test.c |  2 +-
>  drivers/pci/endpoint/pci-epc-core.c           |  2 ++
>  3 files changed, 14 insertions(+), 6 deletions(-)
> 
> diff --git a/drivers/pci/endpoint/functions/pci-epf-ntb.c b/drivers/pci/endpoint/functions/pci-epf-ntb.c
> index 338148cf56f5..bce274d02dcf 100644
> --- a/drivers/pci/endpoint/functions/pci-epf-ntb.c
> +++ b/drivers/pci/endpoint/functions/pci-epf-ntb.c
> @@ -1,5 +1,5 @@
>  // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>   * Endpoint Function Driver to implement Non-Transparent Bridge functionality
>   *
>   * Copyright (C) 2020 Texas Instruments
> @@ -696,7 +696,8 @@ static void epf_ntb_cmd_handler(struct work_struct *work)
>  
>  /**
>   * epf_ntb_peer_spad_bar_clear() - Clear Peer Scratchpad BAR
> - * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> + * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
> + *	     address.
>   *
>   *+-----------------+------->+------------------+        +-----------------+
>   *|       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
> @@ -740,6 +741,7 @@ static void epf_ntb_peer_spad_bar_clear(struct epf_ntb_epc *ntb_epc)
>  /**
>   * epf_ntb_peer_spad_bar_set() - Set peer scratchpad BAR
>   * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> + * @type: PRIMARY interface or SECONDARY interface
>   *
>   *+-----------------+------->+------------------+        +-----------------+
>   *|       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
> @@ -808,7 +810,8 @@ static int epf_ntb_peer_spad_bar_set(struct epf_ntb *ntb,
>  
>  /**
>   * epf_ntb_config_sspad_bar_clear() - Clear Config + Self scratchpad BAR
> - * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> + * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
> + *	     address.
>   *
>   * +-----------------+------->+------------------+        +-----------------+
>   * |       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
> @@ -851,7 +854,8 @@ static void epf_ntb_config_sspad_bar_clear(struct epf_ntb_epc *ntb_epc)
>  
>  /**
>   * epf_ntb_config_sspad_bar_set() - Set Config + Self scratchpad BAR
> - * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> + * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
> + *	     address.
>   *
>   * +-----------------+------->+------------------+        +-----------------+
>   * |       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
> @@ -1312,6 +1316,7 @@ static int epf_ntb_configure_interrupt(struct epf_ntb *ntb,
>  
>  /**
>   * epf_ntb_alloc_peer_mem() - Allocate memory in peer's outbound address space
> + * @dev: The PCI device.
>   * @ntb_epc: EPC associated with one of the HOST whose BAR holds peer's outbound
>   *   address
>   * @bar: BAR of @ntb_epc in for which memory has to be allocated (could be
> @@ -1660,7 +1665,6 @@ static int epf_ntb_init_epc_bar_interface(struct epf_ntb *ntb,
>   * epf_ntb_init_epc_bar() - Identify BARs to be used for each of the NTB
>   * constructs (scratchpad region, doorbell, memorywindow)
>   * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> - * @type: PRIMARY interface or SECONDARY interface
>   *
>   * Wrapper to epf_ntb_init_epc_bar_interface() to identify the free BARs
>   * to be used for each of BAR_CONFIG, BAR_PEER_SPAD, BAR_DB_MW1, BAR_MW2,
> @@ -2037,6 +2041,8 @@ static const struct config_item_type ntb_group_type = {
>  /**
>   * epf_ntb_add_cfs() - Add configfs directory specific to NTB
>   * @epf: NTB endpoint function device
> + * @group: A pointer to the config_group structure referencing a group of
> + *	   config_items of a specific type that belong to a specific sub-system.
>   *
>   * Add configfs directory specific to NTB. This directory will hold
>   * NTB specific properties like db_count, spad_count, num_mws etc.,
> diff --git a/drivers/pci/endpoint/functions/pci-epf-test.c b/drivers/pci/endpoint/functions/pci-epf-test.c
> index c0ac4e9cbe72..63d5f5c6e3e0 100644
> --- a/drivers/pci/endpoint/functions/pci-epf-test.c
> +++ b/drivers/pci/endpoint/functions/pci-epf-test.c
> @@ -1,5 +1,5 @@
>  // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>   * Test driver to test endpoint functionality
>   *
>   * Copyright (C) 2017 Texas Instruments
> diff --git a/drivers/pci/endpoint/pci-epc-core.c b/drivers/pci/endpoint/pci-epc-core.c
> index cc8f9eb2b177..adec9bee72cf 100644
> --- a/drivers/pci/endpoint/pci-epc-core.c
> +++ b/drivers/pci/endpoint/pci-epc-core.c
> @@ -594,6 +594,8 @@ EXPORT_SYMBOL_GPL(pci_epc_add_epf);
>   * pci_epc_remove_epf() - remove PCI endpoint function from endpoint controller
>   * @epc: the EPC device from which the endpoint function should be removed
>   * @epf: the endpoint function to be removed
> + * @type: identifies if the EPC is connected to the primary or secondary
> + *        interface of EPF
>   *
>   * Invoke to remove PCI endpoint function from the endpoint controller.
>   */
> -- 
> 2.30.1
> 

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-03-11 23:39 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 2/8] PCI/AER: Update functions names in the kernel-doc Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 3/8] PCI/PME: Update function name " Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 4/8] PCI/ATS: " Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 5/8] PCI: " Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 6/8] PCI: j721e: Fix a non-compliant kernel-doc Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 7/8] PCI: dwc: Remove surplus and document missing function parameters Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 8/8] PCI: of: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
2021-03-11 23:38 ` [PATCH 1/8] PCI: endpoint: " Bjorn Helgaas

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).