Fix kernel-doc formatting and add missing documentation for the members
"barno" and "flags" of the struct pci_epf_bar, "msix_interrupts" of the
struct pci_epf, "get_features" of the struct pci_epc_ops and
"core_init_notifier" of the struct pci_epc_features.
Thus, resolve build time warnings related to kernel-doc:
include/linux/pci-epf.h:4: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
include/linux/pci-epf.h:113: warning: Function parameter or member 'barno' not described in 'pci_epf_bar'
include/linux/pci-epf.h:113: warning: Function parameter or member 'flags' not described in 'pci_epf_bar'
include/linux/pci-epf.h:157: warning: Function parameter or member 'msix_interrupts' not described in 'pci_epf'
include/linux/pci-ep-cfs.h:4: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
include/linux/pci-epc.h:4: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
include/linux/pci-epc.h:91: warning: Function parameter or member 'get_features' not described in 'pci_epc_ops'
include/linux/pci-epc.h:170: warning: Function parameter or member 'core_init_notifier' not described in 'pci_epc_features'
No change to functionality intended.
Signed-off-by: Krzysztof Wilczyński <kw@xxxxxxxxx>
---
include/linux/pci-ep-cfs.h | 2 +-
include/linux/pci-epc.h | 62 +++++++++++++++++++++-----------------
include/linux/pci-epf.h | 56 ++++++++++++++++++++--------------
3 files changed, 68 insertions(+), 52 deletions(-)
diff --git a/include/linux/pci-ep-cfs.h b/include/linux/pci-ep-cfs.h
index 662881335c7e..3e2140d7e31d 100644
--- a/include/linux/pci-ep-cfs.h
+++ b/include/linux/pci-ep-cfs.h
@@ -1,5 +1,5 @@
/* SPDX-License-Identifier: GPL-2.0+ */
-/**
+/*
* PCI Endpoint ConfigFS header file
*
* Copyright (C) 2017 Texas Instruments
diff --git a/include/linux/pci-epc.h b/include/linux/pci-epc.h
index b82c9b100e97..912f8f542f3e 100644
--- a/include/linux/pci-epc.h
+++ b/include/linux/pci-epc.h
@@ -1,5 +1,5 @@
/* SPDX-License-Identifier: GPL-2.0 */
-/**
+/*
* PCI Endpoint *Controller* (EPC) header file
*
* Copyright (C) 2017 Texas Instruments
@@ -40,25 +40,27 @@ pci_epc_interface_string(enum pci_epc_interface_type type)
}
/**
- * struct pci_epc_ops - set of function pointers for performing EPC operations
- * @write_header: ops to populate configuration space header
- * @set_bar: ops to configure the BAR
- * @clear_bar: ops to reset the BAR
- * @map_addr: ops to map CPU address to PCI address
- * @unmap_addr: ops to unmap CPU address and PCI address
- * @set_msi: ops to set the requested number of MSI interrupts in the MSI
- * capability register
- * @get_msi: ops to get the number of MSI interrupts allocated by the RC from
- * the MSI capability register
- * @set_msix: ops to set the requested number of MSI-X interrupts in the
- * MSI-X capability register
- * @get_msix: ops to get the number of MSI-X interrupts allocated by the RC
- * from the MSI-X capability register
- * @raise_irq: ops to raise a legacy, MSI or MSI-X interrupt
- * @map_msi_irq: ops to map physical address to MSI address and return MSI data
- * @start: ops to start the PCI link
- * @stop: ops to stop the PCI link
- * @owner: the module owner containing the ops
+ * struct pci_epc_ops - Set of function pointers for performing EPC operations.
+ * @write_header: Ops to populate configuration space header.
+ * @set_bar: Ops to configure the BAR.
+ * @clear_bar: Ops to reset the BAR.
+ * @map_addr: Ops to map CPU address to PCI address.
+ * @unmap_addr: Ops to unmap CPU address and PCI address.
+ * @set_msi: Ops to set the requested number of MSI interrupts in the
+ * MSI capability register.
+ * @get_msi: Ops to get the number of MSI interrupts allocated by the
+ * RC from the MSI capability register.
+ * @set_msix: Ops to set the requested number of MSI-X interrupts in
+ * the MSI-X capability register.
+ * @get_msix: Ops to get the number of MSI-X interrupts allocated by.
+ * the RC from the MSI-X capability register.
+ * @raise_irq: Ops to raise a legacy, MSI or MSI-X interrupt.
+ * @map_msi_irq: Ops to map physical address to MSI address and return
+ * MSI data.
+ * @start: Ops to start the PCI link.
+ * @stop: Ops to stop the PCI link.
+ * @get_features: Ops to get the features supported by the EPC.
+ * @owner: The module owner containing the ops.
*/
struct pci_epc_ops {
int (*write_header)(struct pci_epc *epc, u8 func_no,
@@ -148,14 +150,18 @@ struct pci_epc {
};
/**
- * struct pci_epc_features - features supported by a EPC device per function
- * @linkup_notifier: indicate if the EPC device can notify EPF driver on link up
- * @msi_capable: indicate if the endpoint function has MSI capability
- * @msix_capable: indicate if the endpoint function has MSI-X capability
- * @reserved_bar: bitmap to indicate reserved BAR unavailable to function driver
- * @bar_fixed_64bit: bitmap to indicate fixed 64bit BARs
- * @bar_fixed_size: Array specifying the size supported by each BAR
- * @align: alignment size required for BAR buffer allocation
+ * struct pci_epc_features - Features supported by a EPC device per function.
+ * @linkup_notifier: Indicate if the EPC device can notify EPF driver on link
+ * up.
+ * @core_init_notifier: Indicate cores that can notify about their availability
+ * for initialization.
+ * @msi_capable: Indicate if the endpoint function has MSI capability.
+ * @msix_capable: Indicate if the endpoint function has MSI-X capability.
+ * @reserved_bar: Bitmap to indicate reserved BAR unavailable to function
+ * driver.
+ * @bar_fixed_64bit: Bitmap to indicate fixed 64bit BARs.
+ * @bar_fixed_size: Array specifying the size supported by each BAR.
+ * @align: Alignment size required for BAR buffer allocation.
*/
struct pci_epc_features {
unsigned int linkup_notifier : 1;
diff --git a/include/linux/pci-epf.h b/include/linux/pci-epf.h
index 6833e2160ef1..91d8b800e6dc 100644
--- a/include/linux/pci-epf.h
+++ b/include/linux/pci-epf.h
@@ -1,5 +1,5 @@
/* SPDX-License-Identifier: GPL-2.0 */
-/**
+/*
* PCI Endpoint *Function* (EPF) header file
*
* Copyright (C) 2017 Texas Instruments
@@ -98,10 +98,13 @@ struct pci_epf_driver {
driver))
/**
- * struct pci_epf_bar - represents the BAR of EPF device
- * @phys_addr: physical address that should be mapped to the BAR
- * @addr: virtual address corresponding to the @phys_addr
- * @size: the size of the address space present in BAR
+ * struct pci_epf_bar - Represents the BAR of EPF device.
+ * @phys_addr: Physical address that should be mapped to the BAR.
+ * @addr: Virtual address corresponding to the @phys_addr.
+ * @size: The size of the address space present in BAR.
+ * @barno: The BAR number.
+ * @flags: Flags that are set for the BAR. This is need so that specific
+ * epc->ops->set_bar() implementations can modify BAR flags.
*/
struct pci_epf_bar {
dma_addr_t phys_addr;
@@ -112,24 +115,31 @@ struct pci_epf_bar {
};
/**
- * struct pci_epf - represents the PCI EPF device
- * @dev: the PCI EPF device
- * @name: the name of the PCI EPF device
- * @header: represents standard configuration header
- * @bar: represents the BAR of EPF device
- * @msi_interrupts: number of MSI interrupts required by this function
- * @func_no: unique function number within this endpoint device
- * @epc: the EPC device to which this EPF device is bound
- * @driver: the EPF driver to which this EPF device is bound
- * @list: to add pci_epf as a list of PCI endpoint functions to pci_epc
- * @nb: notifier block to notify EPF of any EPC events (like linkup)
- * @lock: mutex to protect pci_epf_ops
- * @sec_epc: the secondary EPC device to which this EPF device is bound
- * @sec_epc_list: to add pci_epf as list of PCI endpoint functions to secondary
- * EPC device
- * @sec_epc_bar: represents the BAR of EPF device associated with secondary EPC
- * @sec_epc_func_no: unique (physical) function number within the secondary EPC
- * @group: configfs group associated with the EPF device
+ * struct pci_epf - Represents the PCI EPF device.
+ * @dev: The PCI EPF device.
+ * @name: The name of the PCI EPF device.
+ * @header: Represents standard configuration header.
+ * @bar: Represents the BAR of EPF device.
+ * @msi_interrupts: Number of MSI interrupts required by this function.
+ * @msix_interrupts: Maximum number of MSI-X interrupts required by this
+ * function.
+ * @func_no: Unique function number within this endpoint device.
+ * @epc: The EPC device to which this EPF device is bound.
+ * @driver: The EPF driver to which this EPF device is bound.
+ * @list: To add pci_epf as a list of PCI endpoint functions to
+ * pci_epc.
+ * @nb: Notifier block to notify EPF of any EPC events (like
+ * linkup).
+ * @lock: Mutex to protect pci_epf_ops.
+ * @sec_epc: The secondary EPC device to which this EPF device is
+ * bound.
+ * @sec_epc_list: To add pci_epf as list of PCI endpoint functions to
+ * secondary EPC device.
+ * @sec_epc_bar: Represents the BAR of EPF device associated with
+ * secondary EPC.
+ * @sec_epc_func_no: Unique (physical) function number within the secondary
+ * EPC.
+ * @group: Configfs group associated with the EPF device.
*/
struct pci_epf {
struct device dev;
--
2.32.0
