[PATCH v4 0/1] cxl/core/regs: Refactor out functions to count regblocks of given type

[PATCH v4 0/1] cxl/core/regs: Refactor out functions to count regblocks of given type

[Huaisheng Ye]

In commit d717d7f3df18494baafd9595fb4bcb9c380d7389, cxl_count_regblock was
added for counting regblocks of a given RBI (Register Block Identifier).
It is workable, but the implementation can be improved.

1. In order to get the count of instances, cxl_count_regblock has to tentatively
repeat the call of cxl_find_regblock_instance by increasing index from 0. It
will not stop until an error value is returned. Actually, It needs to search for
Register Blocks in dvsec again every time by taking a start from the head. The
operations can be optimized.

2. cxl_count_regblock blocks the opportunity to get error codes from
cxl_find_regblock_instance. cxl_pci_probe has error code checking for almost
all function calls. This is a good behavior, but existing cxl_count_regblock
couldn't return error codes.

With this patch, only need to have minor modifications in
__cxl_find_regblock_instance, which can return the count of regblocks by given
RBI in just one call. It is more effective than before. Besides, the error code
could be obtained by the called function, here is cxl_pci_probe.

---

This patch is tested by ndctl cxl_test and physical CXL expander card
with v6.13-rc6.

1. Ndctl CXL test suite v80 could pass with this patch applied.
$ meson test -C build --suite cxl
ninja: Entering directory `/home/work/source/ndctl/build'
[1/48] Generating version.h with a custom command
 1/11 ndctl:cxl / cxl-topology.sh               OK               3.48s
 2/11 ndctl:cxl / cxl-region-sysfs.sh           OK               2.74s
 3/11 ndctl:cxl / cxl-labels.sh                 OK               1.75s
 4/11 ndctl:cxl / cxl-create-region.sh          OK               3.51s
 5/11 ndctl:cxl / cxl-xor-region.sh             OK               1.89s
 6/11 ndctl:cxl / cxl-events.sh                 OK               1.63s
 7/11 ndctl:cxl / cxl-sanitize.sh               OK               4.48s
 8/11 ndctl:cxl / cxl-destroy-region.sh         OK               1.90s
 9/11 ndctl:cxl / cxl-qos-class.sh              OK               2.65s
10/11 ndctl:cxl / cxl-poison.sh                 OK               2.86s
11/11 ndctl:cxl / cxl-security.sh               OK               0.91s

2. Test patch with Qemu x4 switch topology:

                       ACPI0017:00 [root0]
                           |
                         HB_0 [port1]
                        /             \
                     RP_0             RP_1
                      |                 |
                USP [port2]
            /    /    \    \
          DSP   DSP   DSP   DSP
           |     |     |     |
          mem1  mem0  mem2  mem3

Every card has 2 PMU RBs, here are the pmu_mem devices.

$ pwd
/sys/bus/cxl/devices
$ tree
[snip]
├── pmu_mem0.0 -> ../../../devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/0000:0e:01.0/0000:10:00.0/pmu_mem0.0
├── pmu_mem0.1 -> ../../../devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/0000:0e:01.0/0000:10:00.0/pmu_mem0.1
├── pmu_mem1.0 -> ../../../devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/0000:0e:00.0/0000:0f:00.0/pmu_mem1.0
├── pmu_mem1.1 -> ../../../devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/0000:0e:00.0/0000:0f:00.0/pmu_mem1.1
├── pmu_mem2.0 -> ../../../devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/0000:0e:02.0/0000:11:00.0/pmu_mem2.0
├── pmu_mem2.1 -> ../../../devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/0000:0e:02.0/0000:11:00.0/pmu_mem2.1
├── pmu_mem3.0 -> ../../../devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/0000:0e:03.0/0000:12:00.0/pmu_mem3.0
├── pmu_mem3.1 -> ../../../devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/0000:0e:03.0/0000:12:00.0/pmu_mem3.1

---

Changes
=======
v3 -> v4:
1. Simplify code comments of __cxl_find_regblock_instance() (Jonathan)
2. Move testing setup to cover letter (Jonathan)
3. Get Reviewed-by from Jonathan

 [v3] https://lore.kernel.org/all/20250113064345.6835-1-huaisheng.ye@intel.com/
=======
v2 -> v3:
1. Create static function __cxl_find_regblock_instance() for implementation of
   locating a register block or counting instances by type / index
   underneath. (Jonathan)
2. cxl_count_regblock() and cxl_find_regblock_instance() respectively call
   __cxl_find_regblock_instance for the purpose of counting instances and
   locating RB. (Jonathan)
3. Change parameter index's type to 'unsigned int' in cxl_find_regblock_instance (Jonathan)
4. Rebase patch to v6.13-rc6

=======
v1 -> v2:
1. Reserved cxl_count_regblock() for original function interface (Ming)
2. Reset 'map->resource' to 'CXL_RESOURCE_NONE' before returning the count of instances in
   cxl_find_regblock_instance() (Ming)
3. Append results of ndctl test suite and Qemu testing PMU devices to commit log (Ming)
4. Rebase patch to v6.13-rc5

Huaisheng Ye (1):
  cxl/core/regs: Refactor out functions to count regblocks of given type

 drivers/cxl/core/regs.c | 52 +++++++++++++++++++++++++----------------
 drivers/cxl/cxl.h       |  3 ++-
 drivers/cxl/pci.c       |  6 ++++-
 3 files changed, 39 insertions(+), 22 deletions(-)

-- 
2.39.3

[PATCH v4 1/1] cxl/core/regs: Refactor out functions to count regblocks of given type

[Huaisheng Ye]

In commit d717d7f3df18494baafd9595fb4bcb9c380d7389, cxl_count_regblock was
added for counting regblocks of a given RBI (Register Block Identifier).
It is workable, but the implementation can be improved.

1. In order to get the count of instances, cxl_count_regblock has to tentatively
repeat the call of cxl_find_regblock_instance by increasing index from 0. It
will not stop until an error value is returned. Actually, It needs to search for
Register Blocks in dvsec again every time by taking a start from the head. The
operations can be optimized.

For example, to determine if PMU1 exists, cxl_find_regblock_instance must check
all Register Blocks by the type and index from RB1 to RB4, starting from scratch,
even if PMU0 just has been searched. If there are more RBs of the same type in the
future, the situation will be even worse.

16 81 00 23             PCIe extended Capability Header
02 c0 1e 98             Header 1
00 00 00 08             Header 2
--------------------------------------
00 00 01 00             RB 1 - Offset Low       Component
00 00 00 00             RB 1 - Offset High
--------------------------------------
00 00 03 02             RB 2 - Offset Low       Device Register
00 00 00 00             RB 2 - Offset High
--------------------------------------
00 01 04 02             RB 3 - Offset Low       PMU0
00 00 00 00             RB 3 - Offset High
--------------------------------------
00 02 04 02             RB 4 - Offset Low       PMU1
00 00 00 00             RB 4 - Offset High

RB: Register Block

2. cxl_count_regblock blocks the opportunity to get error codes from
cxl_find_regblock_instance. cxl_pci_probe has error code checking for almost
all function calls. This is a good behavior, but existing cxl_count_regblock
couldn't return error codes.

With this patch, only need to have minor modifications in
__cxl_find_regblock_instance, which can return the count of regblocks by given
RBI in just one call. It is more effective than before. Besides, the error code
could be obtained by the called function, here is cxl_pci_probe.

Based on the above reasons, refactor out cxl_count_regblock and create
__cxl_find_regblock_instance for counting instances more efficiently.

Signed-off-by: Huaisheng Ye <huaisheng.ye@intel.com>
Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

---
Changes
=======
v3 -> v4:
1. Simplify code comments of __cxl_find_regblock_instance() (Jonathan)
2. Move testing setup to cover letter (Jonathan)
3. Get Reviewed-by from Jonathan

---
 drivers/cxl/core/regs.c | 52 +++++++++++++++++++++++++----------------
 drivers/cxl/cxl.h       |  3 ++-
 drivers/cxl/pci.c       |  6 ++++-
 3 files changed, 39 insertions(+), 22 deletions(-)

diff --git a/drivers/cxl/core/regs.c b/drivers/cxl/core/regs.c
index 59cb35b40c7e..dd1fe83db366 100644
--- a/drivers/cxl/core/regs.c
+++ b/drivers/cxl/core/regs.c
@@ -290,19 +290,15 @@ static bool cxl_decode_regblock(struct pci_dev *pdev, u32 reg_lo, u32 reg_hi,
 }
 
 /**
- * cxl_find_regblock_instance() - Locate a register block by type / index
- * @pdev: The CXL PCI device to enumerate.
- * @type: Register Block Indicator id
- * @map: Enumeration output, clobbered on error
- * @index: Index into which particular instance of a regblock wanted in the
- *	   order found in register locator DVSEC.
- *
- * Return: 0 if register block enumerated, negative error code otherwise
+ * __cxl_find_regblock_instance() - Locate a register block or count instances by type / index
+ * Use CXL_INSTANCES_COUNT for @index if counting instances.
  *
- * A CXL DVSEC may point to one or more register blocks, search for them
- * by @type and @index.
+ * __cxl_find_regblock_instance() may return:
+ * 0 - if register block enumerated.
+ * >= 0 - if counting instances.
+ * < 0 - error code otherwise.
  */
-int cxl_find_regblock_instance(struct pci_dev *pdev, enum cxl_regloc_type type,
+static int __cxl_find_regblock_instance(struct pci_dev *pdev, enum cxl_regloc_type type,
 			       struct cxl_register_map *map, int index)
 {
 	u32 regloc_size, regblocks;
@@ -342,8 +338,30 @@ int cxl_find_regblock_instance(struct pci_dev *pdev, enum cxl_regloc_type type,
 	}
 
 	map->resource = CXL_RESOURCE_NONE;
+	if (index == CXL_INSTANCES_COUNT)
+		return instance;
+
 	return -ENODEV;
 }
+
+/**
+ * cxl_find_regblock_instance() - Locate a register block by type / index
+ * @pdev: The CXL PCI device to enumerate.
+ * @type: Register Block Indicator id
+ * @map: Enumeration output, clobbered on error
+ * @index: Index into which particular instance of a regblock wanted in the
+ *	   order found in register locator DVSEC.
+ *
+ * Return: 0 if register block enumerated, negative error code otherwise
+ *
+ * A CXL DVSEC may point to one or more register blocks, search for them
+ * by @type and @index.
+ */
+int cxl_find_regblock_instance(struct pci_dev *pdev, enum cxl_regloc_type type,
+			struct cxl_register_map *map, unsigned int index)
+{
+	return __cxl_find_regblock_instance(pdev, type, map, index);
+}
 EXPORT_SYMBOL_NS_GPL(cxl_find_regblock_instance, "CXL");
 
 /**
@@ -360,7 +378,7 @@ EXPORT_SYMBOL_NS_GPL(cxl_find_regblock_instance, "CXL");
 int cxl_find_regblock(struct pci_dev *pdev, enum cxl_regloc_type type,
 		      struct cxl_register_map *map)
 {
-	return cxl_find_regblock_instance(pdev, type, map, 0);
+	return __cxl_find_regblock_instance(pdev, type, map, 0);
 }
 EXPORT_SYMBOL_NS_GPL(cxl_find_regblock, "CXL");
 
@@ -371,19 +389,13 @@ EXPORT_SYMBOL_NS_GPL(cxl_find_regblock, "CXL");
  *
  * Some regblocks may be repeated. Count how many instances.
  *
- * Return: count of matching regblocks.
+ * Return: non-negative count of matching regblocks, negative error code otherwise.
  */
 int cxl_count_regblock(struct pci_dev *pdev, enum cxl_regloc_type type)
 {
 	struct cxl_register_map map;
-	int rc, count = 0;
 
-	while (1) {
-		rc = cxl_find_regblock_instance(pdev, type, &map, count);
-		if (rc)
-			return count;
-		count++;
-	}
+	return __cxl_find_regblock_instance(pdev, type, &map, CXL_INSTANCES_COUNT);
 }
 EXPORT_SYMBOL_NS_GPL(cxl_count_regblock, "CXL");
 
diff --git a/drivers/cxl/cxl.h b/drivers/cxl/cxl.h
index f6015f24ad38..7fc456d5b917 100644
--- a/drivers/cxl/cxl.h
+++ b/drivers/cxl/cxl.h
@@ -302,10 +302,11 @@ int cxl_map_device_regs(const struct cxl_register_map *map,
 			struct cxl_device_regs *regs);
 int cxl_map_pmu_regs(struct cxl_register_map *map, struct cxl_pmu_regs *regs);
 
+#define CXL_INSTANCES_COUNT -1
 enum cxl_regloc_type;
 int cxl_count_regblock(struct pci_dev *pdev, enum cxl_regloc_type type);
 int cxl_find_regblock_instance(struct pci_dev *pdev, enum cxl_regloc_type type,
-			       struct cxl_register_map *map, int index);
+			       struct cxl_register_map *map, unsigned int index);
 int cxl_find_regblock(struct pci_dev *pdev, enum cxl_regloc_type type,
 		      struct cxl_register_map *map);
 int cxl_setup_regs(struct cxl_register_map *map);
diff --git a/drivers/cxl/pci.c b/drivers/cxl/pci.c
index 6d94ff4a4f1a..a96e54c6259e 100644
--- a/drivers/cxl/pci.c
+++ b/drivers/cxl/pci.c
@@ -907,7 +907,8 @@ static int cxl_pci_probe(struct pci_dev *pdev, const struct pci_device_id *id)
 	struct cxl_dev_state *cxlds;
 	struct cxl_register_map map;
 	struct cxl_memdev *cxlmd;
-	int i, rc, pmu_count;
+	int rc, pmu_count;
+	unsigned int i;
 	bool irq_avail;
 
 	/*
@@ -1009,6 +1010,9 @@ static int cxl_pci_probe(struct pci_dev *pdev, const struct pci_device_id *id)
 		return rc;
 
 	pmu_count = cxl_count_regblock(pdev, CXL_REGLOC_RBI_PMU);
+	if (pmu_count < 0)
+		return pmu_count;
+
 	for (i = 0; i < pmu_count; i++) {
 		struct cxl_pmu_regs pmu_regs;
 
-- 
2.39.3

Re: [PATCH v4 1/1] cxl/core/regs: Refactor out functions to count regblocks of given type

[kernel test robot]

Hi Huaisheng,

kernel test robot noticed the following build warnings:

[auto build test WARNING on cxl/next]
[also build test WARNING on linus/master v6.13-rc7 next-20250114]
[cannot apply to cxl/pending]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Huaisheng-Ye/cxl-core-regs-Refactor-out-functions-to-count-regblocks-of-given-type/20250114-212025
base:   https://git.kernel.org/pub/scm/linux/kernel/git/cxl/cxl.git next
patch link:    https://lore.kernel.org/r/20250114131041.17512-2-huaisheng.ye%40intel.com
patch subject: [PATCH v4 1/1] cxl/core/regs: Refactor out functions to count regblocks of given type
config: i386-buildonly-randconfig-001-20250114 (https://download.01.org/0day-ci/archive/20250114/202501142243.PmkW84KY-lkp@intel.com/config)
compiler: gcc-12 (Debian 12.2.0-14) 12.2.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20250114/202501142243.PmkW84KY-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202501142243.PmkW84KY-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> drivers/cxl/core/regs.c:303: warning: Function parameter or struct member 'pdev' not described in '__cxl_find_regblock_instance'
>> drivers/cxl/core/regs.c:303: warning: Function parameter or struct member 'type' not described in '__cxl_find_regblock_instance'
>> drivers/cxl/core/regs.c:303: warning: Function parameter or struct member 'map' not described in '__cxl_find_regblock_instance'
>> drivers/cxl/core/regs.c:303: warning: Function parameter or struct member 'index' not described in '__cxl_find_regblock_instance'


vim +303 drivers/cxl/core/regs.c

303ebc1b1741b6 Ben Widawsky     2022-01-23  291  
303ebc1b1741b6 Ben Widawsky     2022-01-23  292  /**
7167af677c5aa1 Huaisheng Ye     2025-01-14  293   * __cxl_find_regblock_instance() - Locate a register block or count instances by type / index
7167af677c5aa1 Huaisheng Ye     2025-01-14  294   * Use CXL_INSTANCES_COUNT for @index if counting instances.
303ebc1b1741b6 Ben Widawsky     2022-01-23  295   *
7167af677c5aa1 Huaisheng Ye     2025-01-14  296   * __cxl_find_regblock_instance() may return:
7167af677c5aa1 Huaisheng Ye     2025-01-14  297   * 0 - if register block enumerated.
7167af677c5aa1 Huaisheng Ye     2025-01-14  298   * >= 0 - if counting instances.
7167af677c5aa1 Huaisheng Ye     2025-01-14  299   * < 0 - error code otherwise.
303ebc1b1741b6 Ben Widawsky     2022-01-23  300   */
7167af677c5aa1 Huaisheng Ye     2025-01-14  301  static int __cxl_find_regblock_instance(struct pci_dev *pdev, enum cxl_regloc_type type,
d717d7f3df1849 Jonathan Cameron 2023-05-26  302  			       struct cxl_register_map *map, int index)
303ebc1b1741b6 Ben Widawsky     2022-01-23 @303  {
303ebc1b1741b6 Ben Widawsky     2022-01-23  304  	u32 regloc_size, regblocks;
d717d7f3df1849 Jonathan Cameron 2023-05-26  305  	int instance = 0;
303ebc1b1741b6 Ben Widawsky     2022-01-23  306  	int regloc, i;
303ebc1b1741b6 Ben Widawsky     2022-01-23  307  
573408049b7598 Robert Richter   2023-06-22  308  	*map = (struct cxl_register_map) {
dd22581f895371 Robert Richter   2023-10-18  309  		.host = &pdev->dev,
573408049b7598 Robert Richter   2023-06-22  310  		.resource = CXL_RESOURCE_NONE,
573408049b7598 Robert Richter   2023-06-22  311  	};
573408049b7598 Robert Richter   2023-06-22  312  
962f1e79e7acfb Dave Jiang       2024-05-02  313  	regloc = pci_find_dvsec_capability(pdev, PCI_VENDOR_ID_CXL,
303ebc1b1741b6 Ben Widawsky     2022-01-23  314  					   CXL_DVSEC_REG_LOCATOR);
303ebc1b1741b6 Ben Widawsky     2022-01-23  315  	if (!regloc)
303ebc1b1741b6 Ben Widawsky     2022-01-23  316  		return -ENXIO;
303ebc1b1741b6 Ben Widawsky     2022-01-23  317  
303ebc1b1741b6 Ben Widawsky     2022-01-23  318  	pci_read_config_dword(pdev, regloc + PCI_DVSEC_HEADER1, &regloc_size);
303ebc1b1741b6 Ben Widawsky     2022-01-23  319  	regloc_size = FIELD_GET(PCI_DVSEC_HEADER1_LENGTH_MASK, regloc_size);
303ebc1b1741b6 Ben Widawsky     2022-01-23  320  
303ebc1b1741b6 Ben Widawsky     2022-01-23  321  	regloc += CXL_DVSEC_REG_LOCATOR_BLOCK1_OFFSET;
303ebc1b1741b6 Ben Widawsky     2022-01-23  322  	regblocks = (regloc_size - CXL_DVSEC_REG_LOCATOR_BLOCK1_OFFSET) / 8;
303ebc1b1741b6 Ben Widawsky     2022-01-23  323  
303ebc1b1741b6 Ben Widawsky     2022-01-23  324  	for (i = 0; i < regblocks; i++, regloc += 8) {
303ebc1b1741b6 Ben Widawsky     2022-01-23  325  		u32 reg_lo, reg_hi;
303ebc1b1741b6 Ben Widawsky     2022-01-23  326  
303ebc1b1741b6 Ben Widawsky     2022-01-23  327  		pci_read_config_dword(pdev, regloc, &reg_lo);
303ebc1b1741b6 Ben Widawsky     2022-01-23  328  		pci_read_config_dword(pdev, regloc + 4, &reg_hi);
303ebc1b1741b6 Ben Widawsky     2022-01-23  329  
6c7f4f1e51c2a2 Dan Williams     2022-11-29  330  		if (!cxl_decode_regblock(pdev, reg_lo, reg_hi, map))
6c7f4f1e51c2a2 Dan Williams     2022-11-29  331  			continue;
303ebc1b1741b6 Ben Widawsky     2022-01-23  332  
d717d7f3df1849 Jonathan Cameron 2023-05-26  333  		if (map->reg_type == type) {
d717d7f3df1849 Jonathan Cameron 2023-05-26  334  			if (index == instance)
303ebc1b1741b6 Ben Widawsky     2022-01-23  335  				return 0;
d717d7f3df1849 Jonathan Cameron 2023-05-26  336  			instance++;
d717d7f3df1849 Jonathan Cameron 2023-05-26  337  		}
303ebc1b1741b6 Ben Widawsky     2022-01-23  338  	}
303ebc1b1741b6 Ben Widawsky     2022-01-23  339  
6c7f4f1e51c2a2 Dan Williams     2022-11-29  340  	map->resource = CXL_RESOURCE_NONE;
7167af677c5aa1 Huaisheng Ye     2025-01-14  341  	if (index == CXL_INSTANCES_COUNT)
7167af677c5aa1 Huaisheng Ye     2025-01-14  342  		return instance;
7167af677c5aa1 Huaisheng Ye     2025-01-14  343  
303ebc1b1741b6 Ben Widawsky     2022-01-23  344  	return -ENODEV;
303ebc1b1741b6 Ben Widawsky     2022-01-23  345  }
7167af677c5aa1 Huaisheng Ye     2025-01-14  346  

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH v4 1/1] cxl/core/regs: Refactor out functions to count regblocks of given type

[Jonathan Cameron]

On Tue, 14 Jan 2025 23:03:17 +0800
kernel test robot <lkp@intel.com> wrote:

> Hi Huaisheng,
> 
> kernel test robot noticed the following build warnings:
> 
> [auto build test WARNING on cxl/next]
> [also build test WARNING on linus/master v6.13-rc7 next-20250114]
> [cannot apply to cxl/pending]
> [If your patch is applied to the wrong git tree, kindly drop us a note.
> And when submitting patch, we suggest to use '--base' as documented in
> https://git-scm.com/docs/git-format-patch#_base_tree_information]
> 
> url:    https://github.com/intel-lab-lkp/linux/commits/Huaisheng-Ye/cxl-core-regs-Refactor-out-functions-to-count-regblocks-of-given-type/20250114-212025
> base:   https://git.kernel.org/pub/scm/linux/kernel/git/cxl/cxl.git next
> patch link:    https://lore.kernel.org/r/20250114131041.17512-2-huaisheng.ye%40intel.com
> patch subject: [PATCH v4 1/1] cxl/core/regs: Refactor out functions to count regblocks of given type
> config: i386-buildonly-randconfig-001-20250114 (https://download.01.org/0day-ci/archive/20250114/202501142243.PmkW84KY-lkp@intel.com/config)
> compiler: gcc-12 (Debian 12.2.0-14) 12.2.0
> reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20250114/202501142243.PmkW84KY-lkp@intel.com/reproduce)
> 
> If you fix the issue in a separate patch/commit (i.e. not just a new version of
> the same patch/commit), kindly add following tags
> | Reported-by: kernel test robot <lkp@intel.com>
> | Closes: https://lore.kernel.org/oe-kbuild-all/202501142243.PmkW84KY-lkp@intel.com/
> 
> All warnings (new ones prefixed by >>):
> 
> >> drivers/cxl/core/regs.c:303: warning: Function parameter or struct member 'pdev' not described in '__cxl_find_regblock_instance'
> >> drivers/cxl/core/regs.c:303: warning: Function parameter or struct member 'type' not described in '__cxl_find_regblock_instance'
> >> drivers/cxl/core/regs.c:303: warning: Function parameter or struct member 'map' not described in '__cxl_find_regblock_instance'
> >> drivers/cxl/core/regs.c:303: warning: Function parameter or struct member 'index' not described in '__cxl_find_regblock_instance'  
> 
As you've probably gathered from this, kernel-doc needs to be complete.
I'd just drop the extra *. This isn't stuff we need outside of someone
reading the actual code.

/*
 * __cxl_find_....

> 
> vim +303 drivers/cxl/core/regs.c
> 
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  291  
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  292  /**
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  293   * __cxl_find_regblock_instance() - Locate a register block or count instances by type / index
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  294   * Use CXL_INSTANCES_COUNT for @index if counting instances.
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  295   *
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  296   * __cxl_find_regblock_instance() may return:
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  297   * 0 - if register block enumerated.
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  298   * >= 0 - if counting instances.
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  299   * < 0 - error code otherwise.
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  300   */
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  301  static int __cxl_find_regblock_instance(struct pci_dev *pdev, enum cxl_regloc_type type,
> d717d7f3df1849 Jonathan Cameron 2023-05-26  302  			       struct cxl_register_map *map, int index)
> 303ebc1b1741b6 Ben Widawsky     2022-01-23 @303  {
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  304  	u32 regloc_size, regblocks;
> d717d7f3df1849 Jonathan Cameron 2023-05-26  305  	int instance = 0;
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  306  	int regloc, i;
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  307  
> 573408049b7598 Robert Richter   2023-06-22  308  	*map = (struct cxl_register_map) {
> dd22581f895371 Robert Richter   2023-10-18  309  		.host = &pdev->dev,
> 573408049b7598 Robert Richter   2023-06-22  310  		.resource = CXL_RESOURCE_NONE,
> 573408049b7598 Robert Richter   2023-06-22  311  	};
> 573408049b7598 Robert Richter   2023-06-22  312  
> 962f1e79e7acfb Dave Jiang       2024-05-02  313  	regloc = pci_find_dvsec_capability(pdev, PCI_VENDOR_ID_CXL,
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  314  					   CXL_DVSEC_REG_LOCATOR);
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  315  	if (!regloc)
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  316  		return -ENXIO;
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  317  
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  318  	pci_read_config_dword(pdev, regloc + PCI_DVSEC_HEADER1, &regloc_size);
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  319  	regloc_size = FIELD_GET(PCI_DVSEC_HEADER1_LENGTH_MASK, regloc_size);
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  320  
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  321  	regloc += CXL_DVSEC_REG_LOCATOR_BLOCK1_OFFSET;
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  322  	regblocks = (regloc_size - CXL_DVSEC_REG_LOCATOR_BLOCK1_OFFSET) / 8;
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  323  
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  324  	for (i = 0; i < regblocks; i++, regloc += 8) {
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  325  		u32 reg_lo, reg_hi;
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  326  
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  327  		pci_read_config_dword(pdev, regloc, &reg_lo);
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  328  		pci_read_config_dword(pdev, regloc + 4, &reg_hi);
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  329  
> 6c7f4f1e51c2a2 Dan Williams     2022-11-29  330  		if (!cxl_decode_regblock(pdev, reg_lo, reg_hi, map))
> 6c7f4f1e51c2a2 Dan Williams     2022-11-29  331  			continue;
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  332  
> d717d7f3df1849 Jonathan Cameron 2023-05-26  333  		if (map->reg_type == type) {
> d717d7f3df1849 Jonathan Cameron 2023-05-26  334  			if (index == instance)
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  335  				return 0;
> d717d7f3df1849 Jonathan Cameron 2023-05-26  336  			instance++;
> d717d7f3df1849 Jonathan Cameron 2023-05-26  337  		}
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  338  	}
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  339  
> 6c7f4f1e51c2a2 Dan Williams     2022-11-29  340  	map->resource = CXL_RESOURCE_NONE;
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  341  	if (index == CXL_INSTANCES_COUNT)
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  342  		return instance;
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  343  
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  344  	return -ENODEV;
> 303ebc1b1741b6 Ben Widawsky     2022-01-23  345  }
> 7167af677c5aa1 Huaisheng Ye     2025-01-14  346  
> 

RE: [PATCH v4 1/1] cxl/core/regs: Refactor out functions to count regblocks of given type

[Ye, Huaisheng]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Sent: Wednesday, January 15, 2025 9:35 PM
 
[snip]

> >
> > All warnings (new ones prefixed by >>):
> >
> > >> drivers/cxl/core/regs.c:303: warning: Function parameter or struct
> member 'pdev' not described in '__cxl_find_regblock_instance'
> > >> drivers/cxl/core/regs.c:303: warning: Function parameter or struct
> member 'type' not described in '__cxl_find_regblock_instance'
> > >> drivers/cxl/core/regs.c:303: warning: Function parameter or struct
> member 'map' not described in '__cxl_find_regblock_instance'
> > >> drivers/cxl/core/regs.c:303: warning: Function parameter or struct
> member 'index' not described in '__cxl_find_regblock_instance'
> >
> As you've probably gathered from this, kernel-doc needs to be complete.
> I'd just drop the extra *. This isn't stuff we need outside of someone
> reading the actual code.
> 
> /*
>  * __cxl_find_....
> 

oh, whoops, my mistake. Thank you for your patience and correction.
I should run scripts/kernel-doc firstly before 'git send-email'.

Best Regards,
Huaisheng Ye