diff mbox series

kernel-doc: validate function prototype names

Message ID b5c62d6251516d9d87e1fb0746447612501b7fe3.1603438441.git.mchehab+huawei@kernel.org
State New
Headers show
Series kernel-doc: validate function prototype names | expand

Commit Message

Mauro Carvalho Chehab Oct. 23, 2020, 7:34 a.m. UTC 
Kernel-doc currently expects that the kernel-doc markup to come
just before the function prototype. Yet, if it find things like:

	/**
	 * refcount_add - add a value to a refcount
	 * @i: the value to add to the refcount
	 * @r: the refcount
	 */
	static inline void __refcount_add(int i, refcount_t *r, int *oldp);
	static inline void refcount_add(int i, refcount_t *r);

Kernel-doc will do the wrong thing:

	foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
	.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)

	   add a value to a refcount

	**Parameters**

	``int i``
	  the value to add to the refcount

	``refcount_t *r``
	  the refcount

	``int *oldp``
	  *undescribed*

Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.

If both functions have the same arguments, this won't even
produce any warning!

Add a logic to check function identifiers, warning about
wrong identifiers and not documenting them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

Comments

kernel test robot Oct. 23, 2020, 10:18 a.m. UTC | #1 
Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v5.9 next-20201023]
[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]

url:    https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/kernel-doc-validate-function-prototype-names/20201023-153539
base:   git://git.lwn.net/linux-2.6 docs-next
config: i386-randconfig-a005-20201023 (attached as .config)
compiler: gcc-9 (Debian 9.3.0-15) 9.3.0
reproduce (this is a W=1 build):
        # https://github.com/0day-ci/linux/commit/5193d879fdb280898c28b196d3177b61d48fd2db
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/kernel-doc-validate-function-prototype-names/20201023-153539
        git checkout 5193d879fdb280898c28b196d3177b61d48fd2db
        # save the attached .config to linux build tree
        make W=1 ARCH=i386 

If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

>> drivers/misc/mei/hw-me.c:1394: warning: expecting prototype for function mei_me_fw_sku_sps_4. Prototype was for function mei_me_fw_type_sps_4 instead

>> drivers/misc/mei/hw-me.c:1418: warning: expecting prototype for function mei_me_fw_sku_sps. Prototype was for function mei_me_fw_type_sps instead


vim +1394 drivers/misc/mei/hw-me.c

c919951d940f28b Tomas Winkler 2014-05-13  1378  
c919951d940f28b Tomas Winkler 2014-05-13  1379  #define MEI_CFG_FW_NM                           \
c919951d940f28b Tomas Winkler 2014-05-13  1380  	.quirk_probe = mei_me_fw_type_nm
c919951d940f28b Tomas Winkler 2014-05-13  1381  
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1382  /**
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1383   * mei_me_fw_sku_sps_4() - check for sps 4.0 sku
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1384   *
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1385   * Read ME FW Status register to check for SPS Firmware.
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1386   * The SPS FW is only signaled in the PCI function 0.
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1387   * __Note__: Deprecated by SPS 5.0 and newer.
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1388   *
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1389   * @pdev: pci device
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1390   *
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1391   * Return: true in case of SPS firmware
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1392   */
45a2c76283ace79 Tomas Winkler 2020-06-19  1393  static bool mei_me_fw_type_sps_4(const struct pci_dev *pdev)
c919951d940f28b Tomas Winkler 2014-05-13 @1394  {
c919951d940f28b Tomas Winkler 2014-05-13  1395  	u32 reg;
8c57cac1457f312 Tomas Winkler 2016-07-20  1396  	unsigned int devfn;
8c57cac1457f312 Tomas Winkler 2016-07-20  1397  
8c57cac1457f312 Tomas Winkler 2016-07-20  1398  	devfn = PCI_DEVFN(PCI_SLOT(pdev->devfn), 0);
8c57cac1457f312 Tomas Winkler 2016-07-20  1399  	pci_bus_read_config_dword(pdev->bus, devfn, PCI_CFG_HFS_1, &reg);
a96c548291719ae Tomas Winkler 2016-02-07  1400  	trace_mei_pci_cfg_read(&pdev->dev, "PCI_CFG_HFS_1", PCI_CFG_HFS_1, reg);
4d3c6c8eb9816a0 Tomas Winkler 2020-06-19  1401  	return (reg & PCI_CFG_HFS_1_OPMODE_MSK) == PCI_CFG_HFS_1_OPMODE_SPS;
c919951d940f28b Tomas Winkler 2014-05-13  1402  }
c919951d940f28b Tomas Winkler 2014-05-13  1403  
f76d77f50b343bc Tomas Winkler 2020-06-19  1404  #define MEI_CFG_FW_SPS_4                          \
f76d77f50b343bc Tomas Winkler 2020-06-19  1405  	.quirk_probe = mei_me_fw_type_sps_4
f76d77f50b343bc Tomas Winkler 2020-06-19  1406  
f76d77f50b343bc Tomas Winkler 2020-06-19  1407  /**
f76d77f50b343bc Tomas Winkler 2020-06-19  1408   * mei_me_fw_sku_sps() - check for sps sku
f76d77f50b343bc Tomas Winkler 2020-06-19  1409   *
f76d77f50b343bc Tomas Winkler 2020-06-19  1410   * Read ME FW Status register to check for SPS Firmware.
f76d77f50b343bc Tomas Winkler 2020-06-19  1411   * The SPS FW is only signaled in pci function 0
f76d77f50b343bc Tomas Winkler 2020-06-19  1412   *
f76d77f50b343bc Tomas Winkler 2020-06-19  1413   * @pdev: pci device
f76d77f50b343bc Tomas Winkler 2020-06-19  1414   *
f76d77f50b343bc Tomas Winkler 2020-06-19  1415   * Return: true in case of SPS firmware
f76d77f50b343bc Tomas Winkler 2020-06-19  1416   */
45a2c76283ace79 Tomas Winkler 2020-06-19  1417  static bool mei_me_fw_type_sps(const struct pci_dev *pdev)
f76d77f50b343bc Tomas Winkler 2020-06-19 @1418  {
f76d77f50b343bc Tomas Winkler 2020-06-19  1419  	u32 reg;
f76d77f50b343bc Tomas Winkler 2020-06-19  1420  	u32 fw_type;
f76d77f50b343bc Tomas Winkler 2020-06-19  1421  	unsigned int devfn;
f76d77f50b343bc Tomas Winkler 2020-06-19  1422  
f76d77f50b343bc Tomas Winkler 2020-06-19  1423  	devfn = PCI_DEVFN(PCI_SLOT(pdev->devfn), 0);
f76d77f50b343bc Tomas Winkler 2020-06-19  1424  	pci_bus_read_config_dword(pdev->bus, devfn, PCI_CFG_HFS_3, &reg);
f76d77f50b343bc Tomas Winkler 2020-06-19  1425  	trace_mei_pci_cfg_read(&pdev->dev, "PCI_CFG_HFS_3", PCI_CFG_HFS_3, reg);
f76d77f50b343bc Tomas Winkler 2020-06-19  1426  	fw_type = (reg & PCI_CFG_HFS_3_FW_SKU_MSK);
f76d77f50b343bc Tomas Winkler 2020-06-19  1427  
f76d77f50b343bc Tomas Winkler 2020-06-19  1428  	dev_dbg(&pdev->dev, "fw type is %d\n", fw_type);
f76d77f50b343bc Tomas Winkler 2020-06-19  1429  
f76d77f50b343bc Tomas Winkler 2020-06-19  1430  	return fw_type == PCI_CFG_HFS_3_FW_SKU_SPS;
f76d77f50b343bc Tomas Winkler 2020-06-19  1431  }
f76d77f50b343bc Tomas Winkler 2020-06-19  1432  

---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all@lists.01.org
kernel test robot Oct. 23, 2020, 10:18 a.m. UTC | #2 
Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v5.9 next-20201023]
[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]

url:    https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/kernel-doc-validate-function-prototype-names/20201023-153539
base:   git://git.lwn.net/linux-2.6 docs-next
config: microblaze-randconfig-r004-20201023 (attached as .config)
compiler: microblaze-linux-gcc (GCC) 9.3.0
reproduce (this is a W=1 build):
        wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
        chmod +x ~/bin/make.cross
        # https://github.com/0day-ci/linux/commit/5193d879fdb280898c28b196d3177b61d48fd2db
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/kernel-doc-validate-function-prototype-names/20201023-153539
        git checkout 5193d879fdb280898c28b196d3177b61d48fd2db
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=microblaze 

If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

>> drivers/dma/xilinx/xilinx_dma.c:800: warning: expecting prototype for function xilinx_dma_tx_descriptor. Prototype was for function xilinx_dma_alloc_tx_descriptor instead
>> drivers/dma/xilinx/xilinx_dma.c:2452: warning: expecting prototype for function xilinx_dma_channel_set_config. Prototype was for function xilinx_vdma_channel_set_config instead

vim +800 drivers/dma/xilinx/xilinx_dma.c

9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  791  
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  792  /**
42c1a2ede4f6a32 drivers/dma/xilinx/xilinx_vdma.c Kedareswara rao Appana 2016-04-07  793   * xilinx_dma_tx_descriptor - Allocate transaction descriptor
42c1a2ede4f6a32 drivers/dma/xilinx/xilinx_vdma.c Kedareswara rao Appana 2016-04-07  794   * @chan: Driver specific DMA channel
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  795   *
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  796   * Return: The allocated descriptor on success and NULL on failure.
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  797   */
42c1a2ede4f6a32 drivers/dma/xilinx/xilinx_vdma.c Kedareswara rao Appana 2016-04-07  798  static struct xilinx_dma_tx_descriptor *
42c1a2ede4f6a32 drivers/dma/xilinx/xilinx_vdma.c Kedareswara rao Appana 2016-04-07  799  xilinx_dma_alloc_tx_descriptor(struct xilinx_dma_chan *chan)
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23 @800  {
42c1a2ede4f6a32 drivers/dma/xilinx/xilinx_vdma.c Kedareswara rao Appana 2016-04-07  801  	struct xilinx_dma_tx_descriptor *desc;
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  802  
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  803  	desc = kzalloc(sizeof(*desc), GFP_KERNEL);
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  804  	if (!desc)
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  805  		return NULL;
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  806  
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  807  	INIT_LIST_HEAD(&desc->segments);
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  808  
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  809  	return desc;
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  810  }
9cd4360de6090a6 drivers/dma/xilinx/xilinx_vdma.c Srikanth Thokala       2014-04-23  811  

---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all@lists.01.org
diff mbox series

Patch

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..c879e69262dd 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -382,6 +382,9 @@  my $inline_doc_state;
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
 
+# On functions, this should match the name of the function
+my $identifier;
+
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
@@ -1785,6 +1788,11 @@  sub dump_function($$) {
 	$declaration_name = $2;
 	my $args = $3;
 
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for function $identifier. Prototype was for function $declaration_name instead\n";
+	    return;
+	}
+
 	create_parameterlist($args, ',', $file, $declaration_name);
     } else {
 	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
@@ -2036,7 +2044,6 @@  sub process_normal() {
 #
 sub process_name($$) {
     my $file = shift;
-    my $identifier;
     my $descr;
 
     if (/$doc_block/o) {