* [PATCH] kernel-doc: validate function prototype names
@ 2020-10-23 7:34 Mauro Carvalho Chehab
2020-10-23 10:18 ` kernel test robot
2020-10-23 10:18 ` kernel test robot
0 siblings, 2 replies; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-23 7:34 UTC (permalink / raw)
To: Jonathan Corbet, Linux Media Mailing List
Cc: linuxarm, mauro.chehab, Mauro Carvalho Chehab, linux-doc, linux-kernel
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(-)
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) {
--
2.26.2
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] kernel-doc: validate function prototype names
2020-10-23 7:34 [PATCH] kernel-doc: validate function prototype names Mauro Carvalho Chehab
@ 2020-10-23 10:18 ` kernel test robot
2020-10-23 10:18 ` kernel test robot
1 sibling, 0 replies; 3+ messages in thread
From: kernel test robot @ 2020-10-23 10:18 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Jonathan Corbet, Linux Media Mailing List
Cc: kbuild-all, linux-media, linuxarm, mauro.chehab,
Mauro Carvalho Chehab, linux-doc, linux-kernel
[-- Attachment #1: Type: text/plain, Size: 4283 bytes --]
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
[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 31740 bytes --]
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] kernel-doc: validate function prototype names
2020-10-23 7:34 [PATCH] kernel-doc: validate function prototype names Mauro Carvalho Chehab
2020-10-23 10:18 ` kernel test robot
@ 2020-10-23 10:18 ` kernel test robot
1 sibling, 0 replies; 3+ messages in thread
From: kernel test robot @ 2020-10-23 10:18 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Jonathan Corbet, Linux Media Mailing List
Cc: kbuild-all, linux-media, linuxarm, mauro.chehab,
Mauro Carvalho Chehab, linux-doc, linux-kernel
[-- Attachment #1: Type: text/plain, Size: 5819 bytes --]
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, ®);
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, ®);
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
[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 29635 bytes --]
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-10-23 10:19 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-23 7:34 [PATCH] kernel-doc: validate function prototype names Mauro Carvalho Chehab
2020-10-23 10:18 ` kernel test robot
2020-10-23 10:18 ` kernel test robot
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).