[PATCH v6 00/16] Fix several bad kernel-doc markups

[PATCH v6 00/16] Fix several bad kernel-doc markups

[Mauro Carvalho Chehab]

Hi Jon,

This series have three parts:

1)  10 remaining fixup patches from the series I sent back on Dec, 1st:

   parport: fix a kernel-doc markup
   rapidio: fix kernel-doc a markup
   fs: fix kernel-doc markups
   pstore/zone: fix a kernel-doc markup
   firmware: stratix10-svc: fix kernel-doc markups
   connector: fix a kernel-doc markup
   lib/crc7: fix a kernel-doc markup
   memblock: fix kernel-doc markups
   w1: fix a kernel-doc markup
   selftests: kselftest_harness.h: partially fix kernel-doc markups

2) The patch adding the new check to ensure that the kernel-doc
   markup will be used for the right declaration;

3) 5 additional patches, produced against next-20210114 with new
   problems detected after the original series: 

 net: tip: fix a couple kernel-doc markups
 net: cfg80211: fix a kerneldoc markup
 reset: core: fix a kernel-doc markup
 drm: drm_crc: fix a kernel-doc markup
 platform/surface: aggregator: fix a kernel-doc markup

It probably makes sense to merge at least the first 11 patches
via the doc tree, as they should apply cleanly there, and
having the last 5 patches merged via each maintainer's tree.

-

Kernel-doc has always be limited to a probably bad documented
rule:

The kernel-doc markups should appear *imediatelly before* the
function or data structure that it documents.

On other words, if a C file would contain something like this:

	/**
	 * foo - function foo
	 * @args: foo args
	 */
	static inline void bar(int args);

	/**
	 * bar - function bar
	 * @args: foo args
	 */
	static inline void foo(void *args);


The output (in ReST format) will be:

	.. c:function:: void bar (int args)

	   function foo

	**Parameters**

	``int args``
	  foo args


	.. c:function:: void foo (void *args)

	   function bar

	**Parameters**

	``void *args``
	  foo args

Which is clearly a wrong result.  Before this changeset, 
not even a warning is produced on such cases.

As placing such markups just before the documented
data is a common practice, on most cases this is fine.

However, as patches touch things, identifiers may be
renamed, and people may forget to update the kernel-doc
markups to follow such changes.

This has been happening for quite a while, as there are
lots of files with kernel-doc problems.

This series address those issues and add a file at the
end that will enforce that the identifier will match the
kernel-doc markup, avoiding this problem from
keep happening as time goes by.

This series is based on current upstream tree.

@maintainers: feel free to pick the patches and
apply them directly on your trees, as all patches on 
this series are independent from the other ones.

--

v6:
  - rebased on the top of next-20210114 and added a few extra fixes

v5:
  - The completion.h patch was replaced by another one which drops
    an obsolete macro;
  - Some typos got fixed and review tags got added;
  - Dropped patches that were already merged at linux-next.

v4:

  - Patches got rebased and got some acks.

Mauro Carvalho Chehab (16):
  parport: fix a kernel-doc markup
  rapidio: fix kernel-doc a markup
  fs: fix kernel-doc markups
  pstore/zone: fix a kernel-doc markup
  firmware: stratix10-svc: fix kernel-doc markups
  connector: fix a kernel-doc markup
  lib/crc7: fix a kernel-doc markup
  memblock: fix kernel-doc markups
  w1: fix a kernel-doc markup
  selftests: kselftest_harness.h: partially fix kernel-doc markups
  scripts: kernel-doc: validate kernel-doc markup with the actual names
  net: tip: fix a couple kernel-doc markups
  net: cfg80211: fix a kerneldoc markup
  reset: core: fix a kernel-doc markup
  drm: drm_crc: fix a kernel-doc markup
  platform/surface: aggregator: fix a kernel-doc markup

 drivers/parport/share.c                       |  2 +-
 .../surface/aggregator/ssh_request_layer.c    |  2 +-
 drivers/rapidio/rio.c                         |  2 +-
 drivers/reset/core.c                          |  4 +-
 fs/dcache.c                                   | 73 ++++++++++---------
 fs/inode.c                                    |  4 +-
 fs/pstore/zone.c                              |  2 +-
 fs/seq_file.c                                 |  5 +-
 fs/super.c                                    | 12 +--
 include/drm/drm_crtc.h                        |  2 +-
 include/linux/connector.h                     |  2 +-
 .../firmware/intel/stratix10-svc-client.h     | 10 +--
 include/linux/memblock.h                      |  4 +-
 include/linux/parport.h                       | 31 ++++++++
 include/linux/w1.h                            |  2 +-
 include/net/cfg80211.h                        |  2 +-
 lib/crc7.c                                    |  2 +-
 net/tipc/link.c                               |  2 +-
 net/tipc/node.c                               |  2 +-
 scripts/kernel-doc                            | 62 ++++++++++++----
 tools/testing/selftests/kselftest_harness.h   | 26 ++++---
 21 files changed, 160 insertions(+), 93 deletions(-)

-- 
2.29.2

[PATCH v6 01/16] parport: fix a kernel-doc markup

[Mauro Carvalho Chehab]

The kernel-doc markup inside share.c is actually for
__parport_register_driver. The actual goal seems to be
to document parport_register_driver().

So, fix the existing markup and add a new one.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/parport/share.c |  2 +-
 include/linux/parport.h | 31 +++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/drivers/parport/share.c b/drivers/parport/share.c
index 7fec4fefe151..62f8407923d4 100644
--- a/drivers/parport/share.c
+++ b/drivers/parport/share.c
@@ -243,7 +243,7 @@ static int port_detect(struct device *dev, void *dev_drv)
 }
 
 /**
- *	parport_register_driver - register a parallel port device driver
+ *	__parport_register_driver - register a parallel port device driver
  *	@drv: structure describing the driver
  *	@owner: owner module of drv
  *	@mod_name: module name string
diff --git a/include/linux/parport.h b/include/linux/parport.h
index 1fb508c19e83..f981f794c850 100644
--- a/include/linux/parport.h
+++ b/include/linux/parport.h
@@ -297,6 +297,37 @@ int __must_check __parport_register_driver(struct parport_driver *,
  * parport_register_driver must be a macro so that KBUILD_MODNAME can
  * be expanded
  */
+
+/**
+ *	parport_register_driver - register a parallel port device driver
+ *	@driver: structure describing the driver
+ *
+ *	This can be called by a parallel port device driver in order
+ *	to receive notifications about ports being found in the
+ *	system, as well as ports no longer available.
+ *
+ *	If devmodel is true then the new device model is used
+ *	for registration.
+ *
+ *	The @driver structure is allocated by the caller and must not be
+ *	deallocated until after calling parport_unregister_driver().
+ *
+ *	If using the non device model:
+ *	The driver's attach() function may block.  The port that
+ *	attach() is given will be valid for the duration of the
+ *	callback, but if the driver wants to take a copy of the
+ *	pointer it must call parport_get_port() to do so.  Calling
+ *	parport_register_device() on that port will do this for you.
+ *
+ *	The driver's detach() function may block.  The port that
+ *	detach() is given will be valid for the duration of the
+ *	callback, but if the driver wants to take a copy of the
+ *	pointer it must call parport_get_port() to do so.
+ *
+ *
+ *	Returns 0 on success. The non device model will always succeeds.
+ *	but the new device model can fail and will return the error code.
+ **/
 #define parport_register_driver(driver)             \
 	__parport_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
 
-- 
2.29.2

[PATCH v6 02/16] rapidio: fix kernel-doc a markup

[Mauro Carvalho Chehab]

Probaly this was due to a cut and paste issue.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/rapidio/rio.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/rapidio/rio.c b/drivers/rapidio/rio.c
index c2b79736a92b..e74cf09eeff0 100644
--- a/drivers/rapidio/rio.c
+++ b/drivers/rapidio/rio.c
@@ -749,7 +749,7 @@ int rio_map_outb_region(struct rio_mport *mport, u16 destid, u64 rbase,
 EXPORT_SYMBOL_GPL(rio_map_outb_region);
 
 /**
- * rio_unmap_inb_region -- Unmap the inbound memory region
+ * rio_unmap_outb_region -- Unmap the inbound memory region
  * @mport: Master port
  * @destid: destination id mapping points to
  * @rstart: RIO base address window translates to
-- 
2.29.2

[PATCH v6 03/16] fs: fix kernel-doc markups

[Mauro Carvalho Chehab]

Two markups are at the wrong place. Kernel-doc only
support having the comment just before the identifier.

Also, some identifiers have different names between their
prototypes and the kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 fs/dcache.c   | 73 ++++++++++++++++++++++++++-------------------------
 fs/inode.c    |  4 +--
 fs/seq_file.c |  5 ++--
 fs/super.c    | 12 ++++-----
 4 files changed, 48 insertions(+), 46 deletions(-)

diff --git a/fs/dcache.c b/fs/dcache.c
index 737631c8ca7e..51e7081aacdd 100644
--- a/fs/dcache.c
+++ b/fs/dcache.c
@@ -456,23 +456,6 @@ static void d_lru_shrink_move(struct list_lru_one *lru, struct dentry *dentry,
 	list_lru_isolate_move(lru, &dentry->d_lru, list);
 }
 
-/**
- * d_drop - drop a dentry
- * @dentry: dentry to drop
- *
- * d_drop() unhashes the entry from the parent dentry hashes, so that it won't
- * be found through a VFS lookup any more. Note that this is different from
- * deleting the dentry - d_delete will try to mark the dentry negative if
- * possible, giving a successful _negative_ lookup, while d_drop will
- * just make the cache lookup fail.
- *
- * d_drop() is used mainly for stuff that wants to invalidate a dentry for some
- * reason (NFS timeouts or autofs deletes).
- *
- * __d_drop requires dentry->d_lock
- * ___d_drop doesn't mark dentry as "unhashed"
- *   (dentry->d_hash.pprev will be LIST_POISON2, not NULL).
- */
 static void ___d_drop(struct dentry *dentry)
 {
 	struct hlist_bl_head *b;
@@ -501,6 +484,24 @@ void __d_drop(struct dentry *dentry)
 }
 EXPORT_SYMBOL(__d_drop);
 
+/**
+ * d_drop - drop a dentry
+ * @dentry: dentry to drop
+ *
+ * d_drop() unhashes the entry from the parent dentry hashes, so that it won't
+ * be found through a VFS lookup any more. Note that this is different from
+ * deleting the dentry - d_delete will try to mark the dentry negative if
+ * possible, giving a successful _negative_ lookup, while d_drop will
+ * just make the cache lookup fail.
+ *
+ * d_drop() is used mainly for stuff that wants to invalidate a dentry for some
+ * reason (NFS timeouts or autofs deletes).
+ *
+ * __d_drop requires dentry->d_lock
+ *
+ * ___d_drop doesn't mark dentry as "unhashed"
+ * (dentry->d_hash.pprev will be LIST_POISON2, not NULL).
+ */
 void d_drop(struct dentry *dentry)
 {
 	spin_lock(&dentry->d_lock);
@@ -996,6 +997,25 @@ struct dentry *d_find_any_alias(struct inode *inode)
 }
 EXPORT_SYMBOL(d_find_any_alias);
 
+static struct dentry *__d_find_alias(struct inode *inode)
+{
+	struct dentry *alias;
+
+	if (S_ISDIR(inode->i_mode))
+		return __d_find_any_alias(inode);
+
+	hlist_for_each_entry(alias, &inode->i_dentry, d_u.d_alias) {
+		spin_lock(&alias->d_lock);
+ 		if (!d_unhashed(alias)) {
+			__dget_dlock(alias);
+			spin_unlock(&alias->d_lock);
+			return alias;
+		}
+		spin_unlock(&alias->d_lock);
+	}
+	return NULL;
+}
+
 /**
  * d_find_alias - grab a hashed alias of inode
  * @inode: inode in question
@@ -1010,25 +1030,6 @@ EXPORT_SYMBOL(d_find_any_alias);
  * If the inode has an IS_ROOT, DCACHE_DISCONNECTED alias, then prefer
  * any other hashed alias over that one.
  */
-static struct dentry *__d_find_alias(struct inode *inode)
-{
-	struct dentry *alias;
-
-	if (S_ISDIR(inode->i_mode))
-		return __d_find_any_alias(inode);
-
-	hlist_for_each_entry(alias, &inode->i_dentry, d_u.d_alias) {
-		spin_lock(&alias->d_lock);
- 		if (!d_unhashed(alias)) {
-			__dget_dlock(alias);
-			spin_unlock(&alias->d_lock);
-			return alias;
-		}
-		spin_unlock(&alias->d_lock);
-	}
-	return NULL;
-}
-
 struct dentry *d_find_alias(struct inode *inode)
 {
 	struct dentry *de = NULL;
diff --git a/fs/inode.c b/fs/inode.c
index dd52b6444fdf..af280ffb105d 100644
--- a/fs/inode.c
+++ b/fs/inode.c
@@ -1494,7 +1494,7 @@ struct inode *find_inode_rcu(struct super_block *sb, unsigned long hashval,
 EXPORT_SYMBOL(find_inode_rcu);
 
 /**
- * find_inode_by_rcu - Find an inode in the inode cache
+ * find_inode_by_ino_rcu - Find an inode in the inode cache
  * @sb:		Super block of file system to search
  * @ino:	The inode number to match
  *
@@ -1780,7 +1780,7 @@ static int update_time(struct inode *inode, struct timespec64 *time, int flags)
 }
 
 /**
- *	touch_atime	-	update the access time
+ *	atime_needs_update	-	update the access time
  *	@path: the &struct path to update
  *	@inode: inode to update
  *
diff --git a/fs/seq_file.c b/fs/seq_file.c
index 03a369ccd28c..cb11a34fb871 100644
--- a/fs/seq_file.c
+++ b/fs/seq_file.c
@@ -669,7 +669,8 @@ void seq_puts(struct seq_file *m, const char *s)
 EXPORT_SYMBOL(seq_puts);
 
 /**
- * A helper routine for putting decimal numbers without rich format of printf().
+ * seq_put_decimal_ull_width - A helper routine for putting decimal numbers
+ * 			       without rich format of printf().
  * only 'unsigned long long' is supported.
  * @m: seq_file identifying the buffer to which data should be written
  * @delimiter: a string which is printed before the number
@@ -1044,7 +1045,7 @@ struct hlist_node *seq_hlist_next_rcu(void *v,
 EXPORT_SYMBOL(seq_hlist_next_rcu);
 
 /**
- * seq_hlist_start_precpu - start an iteration of a percpu hlist array
+ * seq_hlist_start_percpu - start an iteration of a percpu hlist array
  * @head: pointer to percpu array of struct hlist_heads
  * @cpu:  pointer to cpu "cursor"
  * @pos:  start position of sequence
diff --git a/fs/super.c b/fs/super.c
index 2c6cdea2ab2d..18a3de0b93f5 100644
--- a/fs/super.c
+++ b/fs/super.c
@@ -1718,12 +1718,6 @@ int freeze_super(struct super_block *sb)
 }
 EXPORT_SYMBOL(freeze_super);
 
-/**
- * thaw_super -- unlock filesystem
- * @sb: the super to thaw
- *
- * Unlocks the filesystem and marks it writeable again after freeze_super().
- */
 static int thaw_super_locked(struct super_block *sb)
 {
 	int error;
@@ -1759,6 +1753,12 @@ static int thaw_super_locked(struct super_block *sb)
 	return 0;
 }
 
+/**
+ * thaw_super -- unlock filesystem
+ * @sb: the super to thaw
+ *
+ * Unlocks the filesystem and marks it writeable again after freeze_super().
+ */
 int thaw_super(struct super_block *sb)
 {
 	down_write(&sb->s_umount);
-- 
2.29.2

[PATCH v6 04/16] pstore/zone: fix a kernel-doc markup

[Mauro Carvalho Chehab]

The documented struct is psz_head and not psz_buffer.

Reviewed-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 fs/pstore/zone.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/fs/pstore/zone.c b/fs/pstore/zone.c
index 5266ccbec007..7c8f8feac6c3 100644
--- a/fs/pstore/zone.c
+++ b/fs/pstore/zone.c
@@ -23,7 +23,7 @@
 #include "internal.h"
 
 /**
- * struct psz_head - header of zone to flush to storage
+ * struct psz_buffer - header of zone to flush to storage
  *
  * @sig: signature to indicate header (PSZ_SIG xor PSZONE-type value)
  * @datalen: length of data in @data
-- 
2.29.2

[PATCH v6 05/16] firmware: stratix10-svc: fix kernel-doc markups

[Mauro Carvalho Chehab]

There are some common comments marked, instead, with kernel-doc
notation, which won't work.

While here, rename an identifier, in order to match the
function prototype below kernel-doc markup.

Acked-by: Richard Gong <richard.gong@linux.intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/firmware/intel/stratix10-svc-client.h | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/include/linux/firmware/intel/stratix10-svc-client.h b/include/linux/firmware/intel/stratix10-svc-client.h
index a93d85932eb9..ebc295647581 100644
--- a/include/linux/firmware/intel/stratix10-svc-client.h
+++ b/include/linux/firmware/intel/stratix10-svc-client.h
@@ -6,7 +6,7 @@
 #ifndef __STRATIX10_SVC_CLIENT_H
 #define __STRATIX10_SVC_CLIENT_H
 
-/**
+/*
  * Service layer driver supports client names
  *
  * fpga: for FPGA configuration
@@ -15,7 +15,7 @@
 #define SVC_CLIENT_FPGA			"fpga"
 #define SVC_CLIENT_RSU			"rsu"
 
-/**
+/*
  * Status of the sent command, in bit number
  *
  * SVC_STATUS_OK:
@@ -50,7 +50,7 @@
 #define SVC_STATUS_ERROR		5
 #define SVC_STATUS_NO_SUPPORT		6
 
-/**
+/*
  * Flag bit for COMMAND_RECONFIG
  *
  * COMMAND_RECONFIG_FLAG_PARTIAL:
@@ -58,7 +58,7 @@
  */
 #define COMMAND_RECONFIG_FLAG_PARTIAL	1
 
-/**
+/*
  * Timeout settings for service clients:
  * timeout value used in Stratix10 FPGA manager driver.
  * timeout value used in RSU driver
@@ -218,7 +218,7 @@ void stratix10_svc_free_memory(struct stratix10_svc_chan *chan, void *kaddr);
 int stratix10_svc_send(struct stratix10_svc_chan *chan, void *msg);
 
 /**
- * intel_svc_done() - complete service request
+ * stratix10_svc_done() - complete service request
  * @chan: service channel assigned to the client
  *
  * This function is used by service client to inform service layer that
-- 
2.29.2

[PATCH v6 06/16] connector: fix a kernel-doc markup

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/connector.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/connector.h b/include/linux/connector.h
index 8ea860efea37..487350bb19c3 100644
--- a/include/linux/connector.h
+++ b/include/linux/connector.h
@@ -99,7 +99,7 @@ void cn_del_callback(const struct cb_id *id);
 int cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 group, gfp_t gfp_mask);
 
 /**
- * cn_netlink_send_mult - Sends message to the specified groups.
+ * cn_netlink_send - Sends message to the specified groups.
  *
  * @msg:	message header(with attached data).
  * @portid:	destination port.
-- 
2.29.2

[PATCH v6 07/16] lib/crc7: fix a kernel-doc markup

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 lib/crc7.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/crc7.c b/lib/crc7.c
index 6a848d73e804..3848e313b722 100644
--- a/lib/crc7.c
+++ b/lib/crc7.c
@@ -51,7 +51,7 @@ const u8 crc7_be_syndrome_table[256] = {
 EXPORT_SYMBOL(crc7_be_syndrome_table);
 
 /**
- * crc7 - update the CRC7 for the data buffer
+ * crc7_be - update the CRC7 for the data buffer
  * @crc:     previous CRC7 value
  * @buffer:  data pointer
  * @len:     number of bytes in the buffer
-- 
2.29.2

[PATCH v6 08/16] memblock: fix kernel-doc markups

[Mauro Carvalho Chehab]

Some identifiers have different names between their prototypes
and the kernel-doc markup.

Acked-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/memblock.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/memblock.h b/include/linux/memblock.h
index b93c44b9121e..9cc6da7b513e 100644
--- a/include/linux/memblock.h
+++ b/include/linux/memblock.h
@@ -272,7 +272,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
 				  unsigned long *out_spfn,
 				  unsigned long *out_epfn);
 /**
- * for_each_free_mem_range_in_zone - iterate through zone specific free
+ * for_each_free_mem_pfn_range_in_zone - iterate through zone specific free
  * memblock areas
  * @i: u64 used as loop variable
  * @zone: zone in which all of the memory blocks reside
@@ -292,7 +292,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
 	     __next_mem_pfn_range_in_zone(&i, zone, p_start, p_end))
 
 /**
- * for_each_free_mem_range_in_zone_from - iterate through zone specific
+ * for_each_free_mem_pfn_range_in_zone_from - iterate through zone specific
  * free memblock areas from a given point
  * @i: u64 used as loop variable
  * @zone: zone in which all of the memory blocks reside
-- 
2.29.2

[PATCH v6 09/16] w1: fix a kernel-doc markup

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/w1.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/w1.h b/include/linux/w1.h
index 949d3b10e531..9a2a0ef39018 100644
--- a/include/linux/w1.h
+++ b/include/linux/w1.h
@@ -280,7 +280,7 @@ int w1_register_family(struct w1_family *family);
 void w1_unregister_family(struct w1_family *family);
 
 /**
- * module_w1_driver() - Helper macro for registering a 1-Wire families
+ * module_w1_family() - Helper macro for registering a 1-Wire families
  * @__w1_family: w1_family struct
  *
  * Helper macro for 1-Wire families which do not do anything special in module
-- 
2.29.2

[PATCH v6 10/16] selftests: kselftest_harness.h: partially fix kernel-doc markups

[Mauro Carvalho Chehab]

The kernel-doc markups on this file are weird: they don't
follow what's specified at:

	Documentation/doc-guide/kernel-doc.rst

In particular, markups should use this format:
        identifier - description

and not this:
	identifier(args)

The way the definitions are inside this file cause the
parser to completely miss the identifier name of each
function.

This prevents improving the script to do some needed validation
tests.

Address this part. Yet, furter changes are needed in order
for it to fully follow the specs.

Acked-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/testing/selftests/kselftest_harness.h | 26 ++++++++++++---------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h
index edce85420d19..ae0f0f33b2a6 100644
--- a/tools/testing/selftests/kselftest_harness.h
+++ b/tools/testing/selftests/kselftest_harness.h
@@ -79,7 +79,7 @@
 #endif
 
 /**
- * TH_LOG(fmt, ...)
+ * TH_LOG()
  *
  * @fmt: format string
  * @...: optional arguments
@@ -113,12 +113,16 @@
 			__FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
 
 /**
- * SKIP(statement, fmt, ...)
+ * SKIP()
  *
  * @statement: statement to run after reporting SKIP
  * @fmt: format string
  * @...: optional arguments
  *
+ * .. code-block:: c
+ *
+ *     SKIP(statement, fmt, ...);
+ *
  * This forces a "pass" after reporting why something is being skipped
  * and runs "statement", which is usually "return" or "goto skip".
  */
@@ -136,7 +140,7 @@
 } while (0)
 
 /**
- * TEST(test_name) - Defines the test function and creates the registration
+ * TEST() - Defines the test function and creates the registration
  * stub
  *
  * @test_name: test name
@@ -155,7 +159,7 @@
 #define TEST(test_name) __TEST_IMPL(test_name, -1)
 
 /**
- * TEST_SIGNAL(test_name, signal)
+ * TEST_SIGNAL()
  *
  * @test_name: test name
  * @signal: signal number
@@ -195,7 +199,7 @@
 		struct __test_metadata __attribute__((unused)) *_metadata)
 
 /**
- * FIXTURE_DATA(datatype_name) - Wraps the struct name so we have one less
+ * FIXTURE_DATA() - Wraps the struct name so we have one less
  * argument to pass around
  *
  * @datatype_name: datatype name
@@ -212,7 +216,7 @@
 #define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name
 
 /**
- * FIXTURE(fixture_name) - Called once per fixture to setup the data and
+ * FIXTURE() - Called once per fixture to setup the data and
  * register
  *
  * @fixture_name: fixture name
@@ -239,7 +243,7 @@
 	FIXTURE_DATA(fixture_name)
 
 /**
- * FIXTURE_SETUP(fixture_name) - Prepares the setup function for the fixture.
+ * FIXTURE_SETUP() - Prepares the setup function for the fixture.
  * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
  *
  * @fixture_name: fixture name
@@ -265,7 +269,7 @@
 			__attribute__((unused)) *variant)
 
 /**
- * FIXTURE_TEARDOWN(fixture_name)
+ * FIXTURE_TEARDOWN()
  * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
  *
  * @fixture_name: fixture name
@@ -286,7 +290,7 @@
 		FIXTURE_DATA(fixture_name) __attribute__((unused)) *self)
 
 /**
- * FIXTURE_VARIANT(fixture_name) - Optionally called once per fixture
+ * FIXTURE_VARIANT() - Optionally called once per fixture
  * to declare fixture variant
  *
  * @fixture_name: fixture name
@@ -305,7 +309,7 @@
 #define FIXTURE_VARIANT(fixture_name) struct _fixture_variant_##fixture_name
 
 /**
- * FIXTURE_VARIANT_ADD(fixture_name, variant_name) - Called once per fixture
+ * FIXTURE_VARIANT_ADD() - Called once per fixture
  * variant to setup and register the data
  *
  * @fixture_name: fixture name
@@ -339,7 +343,7 @@
 		_##fixture_name##_##variant_name##_variant =
 
 /**
- * TEST_F(fixture_name, test_name) - Emits test registration and helpers for
+ * TEST_F() - Emits test registration and helpers for
  * fixture-based test cases
  *
  * @fixture_name: fixture name
-- 
2.29.2

[PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names

[Mauro Carvalho Chehab]

Kernel-doc currently expects that the kernel-doc markup to come
just before the function/enum/struct/union/typedef 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 if the kernel-doc identifier matches the actual
name of the C function or data structure that will be documented.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 6325bec3f66f..a9a92e623dbc 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;
 
+# Name of the kernel-doc identifier for non-DOC markups
+my $identifier;
+
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
@@ -1203,6 +1206,11 @@ sub dump_struct($$) {
 	$declaration_name = $2;
 	my $members = $3;
 
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
+	    return;
+	}
+
 	# ignore members marked private:
 	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
 	$members =~ s/\/\*\s*private:.*//gosi;
@@ -1391,6 +1399,11 @@ sub dump_enum($$) {
     }
 
     if ($members) {
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
+	    return;
+	}
+
 	my %_members;
 
 	$members =~ s/\s+$//;
@@ -1451,6 +1464,11 @@ sub dump_typedef($$) {
 	my $args = $3;
 	$return_type =~ s/^\s+//;
 
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+	    return;
+	}
+
 	create_parameterlist($args, ',', $file, $declaration_name);
 
 	output_declaration($declaration_name,
@@ -1477,6 +1495,11 @@ sub dump_typedef($$) {
     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
 	$declaration_name = $1;
 
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+	    return;
+	}
+
 	output_declaration($declaration_name,
 			   'typedef',
 			   {'typedef' => $declaration_name,
@@ -1796,6 +1819,11 @@ sub dump_function($$) {
 	return;
     }
 
+    if ($identifier ne $declaration_name) {
+	print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
+	return;
+    }
+
     my $prms = join " ", @parameterlist;
     check_sections($file, $declaration_name, "function", $sectcheck, $prms);
 
@@ -1878,6 +1906,7 @@ sub tracepoint_munge($) {
 			     "$prototype\n";
 	} else {
 		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
+		$identifier = "trace_$identifier";
 	}
 }
 
@@ -2041,7 +2070,6 @@ sub process_normal() {
 #
 sub process_name($$) {
     my $file = shift;
-    my $identifier;
     my $descr;
 
     if (/$doc_block/o) {
@@ -2054,12 +2082,19 @@ sub process_name($$) {
 	} else {
 	    $section = $1;
 	}
-    }
-    elsif (/$doc_decl/o) {
+    } elsif (/$doc_decl/o) {
 	$identifier = $1;
-	if (/\s*([\w\s]+?)(\(\))?\s*-/) {
+	if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
 	    $identifier = $1;
 	}
+	if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
+	    $decl_type = $1;
+	    $identifier = $2;
+	} else {
+	    $decl_type = 'function';
+	    $identifier =~ s/^define\s+//;
+	}
+	$identifier =~ s/\s+$//;
 
 	$state = STATE_BODY;
 	# if there's no @param blocks need to set up default section
@@ -2067,7 +2102,7 @@ sub process_name($$) {
 	$contents = "";
 	$section = $section_default;
 	$new_start_line = $. + 1;
-	if (/-(.*)/) {
+	if (/[-:](.*)/) {
 	    # strip leading/trailing/multiple spaces
 	    $descr= $1;
 	    $descr =~ s/^\s*//;
@@ -2085,20 +2120,15 @@ sub process_name($$) {
 	    ++$warnings;
 	}
 
-	if ($identifier =~ m/^struct\b/) {
-	    $decl_type = 'struct';
-	} elsif ($identifier =~ m/^union\b/) {
-	    $decl_type = 'union';
-	} elsif ($identifier =~ m/^enum\b/) {
-	    $decl_type = 'enum';
-	} elsif ($identifier =~ m/^typedef\b/) {
-	    $decl_type = 'typedef';
-	} else {
-	    $decl_type = 'function';
+	if ($identifier eq "") {
+	    print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
+	    print STDERR $_;
+	    ++$warnings;
+	    $state = STATE_NORMAL;
 	}
 
 	if ($verbose) {
-	    print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
+	    print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
 	}
     } else {
 	print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
-- 
2.29.2

[PATCH v6 12/16] net: tip: fix a couple kernel-doc markups

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup:

	../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead
	../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 net/tipc/link.c | 2 +-
 net/tipc/node.c | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/net/tipc/link.c b/net/tipc/link.c
index a6a694b78927..115109259430 100644
--- a/net/tipc/link.c
+++ b/net/tipc/link.c
@@ -2544,7 +2544,7 @@ void tipc_link_set_queue_limits(struct tipc_link *l, u32 min_win, u32 max_win)
 }
 
 /**
- * link_reset_stats - reset link statistics
+ * tipc_link_reset_stats - reset link statistics
  * @l: pointer to link
  */
 void tipc_link_reset_stats(struct tipc_link *l)
diff --git a/net/tipc/node.c b/net/tipc/node.c
index 83d9eb830592..008670d1f43e 100644
--- a/net/tipc/node.c
+++ b/net/tipc/node.c
@@ -1665,7 +1665,7 @@ static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list)
 }
 
 /**
- * tipc_node_xmit() is the general link level function for message sending
+ * tipc_node_xmit() - general link level function for message sending
  * @net: the applicable net namespace
  * @list: chain of buffers containing message
  * @dnode: address of destination node
-- 
2.29.2

[PATCH v6 13/16] net: cfg80211: fix a kerneldoc markup

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup:
	../include/net/cfg80211.h:1766: warning: expecting prototype for struct cfg80211_sar_chan_ranges. Prototype was for struct cfg80211_sar_freq_ranges instead

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/net/cfg80211.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 1b3954afcda4..0d6f7ec86061 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -1756,7 +1756,7 @@ struct cfg80211_sar_specs {
 
 
 /**
- * struct cfg80211_sar_chan_ranges - sar frequency ranges
+ * struct cfg80211_sar_freq_ranges - sar frequency ranges
  * @start_freq:  start range edge frequency
  * @end_freq:    end range edge frequency
  */
-- 
2.29.2

[PATCH v6 14/16] reset: core: fix a kernel-doc markup

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup:

	../drivers/reset/core.c:888: warning: expecting prototype for device_reset(). Prototype was for __device_reset() instead

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/reset/core.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/reset/core.c b/drivers/reset/core.c
index 34e89aa0fb5e..dbf881b586d9 100644
--- a/drivers/reset/core.c
+++ b/drivers/reset/core.c
@@ -875,8 +875,8 @@ struct reset_control *__devm_reset_control_get(struct device *dev,
 EXPORT_SYMBOL_GPL(__devm_reset_control_get);
 
 /**
- * device_reset - find reset controller associated with the device
- *                and perform reset
+ * __device_reset - find reset controller associated with the device
+ *                  and perform reset
  * @dev: device to be reset by the controller
  * @optional: whether it is optional to reset the device
  *
-- 
2.29.2

[PATCH v6 15/16] drm: drm_crc: fix a kernel-doc markup

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup:

	../include/drm/drm_crtc.h:1257: warning: expecting prototype for drm_crtc_alloc_with_planes(). Prototype was for drmm_crtc_alloc_with_planes() instead

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/drm/drm_crtc.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index 540e2e43ec93..13eeba2a750a 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -1232,7 +1232,7 @@ void *__drmm_crtc_alloc_with_planes(struct drm_device *dev,
 				    const char *name, ...);
 
 /**
- * drm_crtc_alloc_with_planes - Allocate and initialize a new CRTC object with
+ * drmm_crtc_alloc_with_planes - Allocate and initialize a new CRTC object with
  *    specified primary and cursor planes.
  * @dev: DRM device
  * @type: the type of the struct which contains struct &drm_crtc
-- 
2.29.2

[PATCH v6 16/16] platform/surface: aggregator: fix a kernel-doc markup

[Mauro Carvalho Chehab]

A function has a different name between their prototype
and its kernel-doc markup:

	../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype for ssh_rtl_tx_start(). Prototype was for ssh_rtl_start() instead

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/platform/surface/aggregator/ssh_request_layer.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/platform/surface/aggregator/ssh_request_layer.c b/drivers/platform/surface/aggregator/ssh_request_layer.c
index bb1c862411a2..25db4d638cfa 100644
--- a/drivers/platform/surface/aggregator/ssh_request_layer.c
+++ b/drivers/platform/surface/aggregator/ssh_request_layer.c
@@ -1056,7 +1056,7 @@ void ssh_rtl_destroy(struct ssh_rtl *rtl)
 }
 
 /**
- * ssh_rtl_tx_start() - Start request transmitter and receiver.
+ * ssh_rtl_start() - Start request transmitter and receiver.
  * @rtl: The request transport layer.
  *
  * Return: Returns zero on success, a negative error code on failure.
-- 
2.29.2

Re: [PATCH v6 15/16] drm: drm_crc: fix a kernel-doc markup

[Simon Ser]

On Thursday, January 14th, 2021 at 9:04 AM, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> A function has a different name between their prototype
> and its kernel-doc markup:
>
> 	../include/drm/drm_crtc.h:1257: warning: expecting prototype for drm_crtc_alloc_with_planes(). Prototype was for drmm_crtc_alloc_with_planes() instead
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Simon Ser <contact@emersion.fr>

Re: [PATCH v6 14/16] reset: core: fix a kernel-doc markup

[Philipp Zabel]

Hi Mauro,

On Thu, 2021-01-14 at 09:04 +0100, Mauro Carvalho Chehab wrote:
> A function has a different name between their prototype
> and its kernel-doc markup:
> 
> 	../drivers/reset/core.c:888: warning: expecting prototype for device_reset(). Prototype was for __device_reset() instead
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/reset/core.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/reset/core.c b/drivers/reset/core.c
> index 34e89aa0fb5e..dbf881b586d9 100644
> --- a/drivers/reset/core.c
> +++ b/drivers/reset/core.c
> @@ -875,8 +875,8 @@ struct reset_control *__devm_reset_control_get(struct device *dev,
>  EXPORT_SYMBOL_GPL(__devm_reset_control_get);
>  
>  /**
> - * device_reset - find reset controller associated with the device
> - *                and perform reset
> + * __device_reset - find reset controller associated with the device
> + *                  and perform reset
>   * @dev: device to be reset by the controller
>   * @optional: whether it is optional to reset the device
>   *

Thank you, applied to reset/next.

regards
Philipp

Re: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names

[kernel test robot]

[-- Attachment #1: Type: text/plain, Size: 6531 bytes --]

Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on next-20210113]
[also build test WARNING on v5.11-rc3]
[cannot apply to lwn/docs-next kees/for-next/pstore mac80211-next/master mac80211/master pza/reset/next linus/master v5.11-rc3 v5.11-rc2 v5.11-rc1]
[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/Fix-several-bad-kernel-doc-markups/20210114-161010
base:    aa515cdce7a151dcc14b7600d33f1414c6fa32c9
config: arm64-alldefconfig (attached as .config)
compiler: aarch64-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/1e9159b3640012fc5fab8508b1c5635ac13a55e9
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010
        git checkout 1e9159b3640012fc5fab8508b1c5635ac13a55e9
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=arm64 

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 >>):

   kernel/seccomp.c:126: warning: Function parameter or member 'list' not described in 'seccomp_kaddfd'
   kernel/seccomp.c:390: warning: Function parameter or member 'ret' not described in 'ACTION_ONLY'
>> kernel/seccomp.c:390: warning: expecting prototype for seccomp_run_filters(). Prototype was for ACTION_ONLY() instead
   kernel/seccomp.c:553: warning: Function parameter or member 'tsk' not described in 'seccomp_filter_release'
   kernel/seccomp.c:573: warning: Function parameter or member 'flags' not described in 'seccomp_sync_threads'
--
   drivers/base/platform-msi.c:336: warning: Function parameter or member 'is_tree' not described in '__platform_msi_create_device_domain'
>> drivers/base/platform-msi.c:336: warning: expecting prototype for platform_msi_create_device_domain(). Prototype was for __platform_msi_create_device_domain() instead
--
>> drivers/iommu/iommu.c:956: warning: expecting prototype for iommu_group_for_each_dev(). Prototype was for __iommu_group_for_each_dev() instead
   drivers/iommu/iommu.c:2976: warning: Function parameter or member 'drvdata' not described in 'iommu_sva_bind_device'
--
>> kernel/irq/msi.c:534: warning: expecting prototype for __msi_domain_free_irqs(). Prototype was for msi_domain_free_irqs() instead
--
>> kernel/irq/ipi.c:264: warning: expecting prototype for ipi_send_mask(). Prototype was for __ipi_send_mask() instead


vim +390 kernel/seccomp.c

f9d480b6ffbeb336 YiFei Zhu          2020-10-11  380  
e2cfabdfd0756482 Will Drewry        2012-04-12  381  /**
285fdfc5d9959a21 Mickaël Salaün     2016-09-20  382   * seccomp_run_filters - evaluates all seccomp filters against @sd
285fdfc5d9959a21 Mickaël Salaün     2016-09-20  383   * @sd: optional seccomp data to be passed to filters
deb4de8b31bc5bf2 Kees Cook          2017-08-02  384   * @match: stores struct seccomp_filter that resulted in the return value,
deb4de8b31bc5bf2 Kees Cook          2017-08-02  385   *         unless filter returned SECCOMP_RET_ALLOW, in which case it will
deb4de8b31bc5bf2 Kees Cook          2017-08-02  386   *         be unchanged.
e2cfabdfd0756482 Will Drewry        2012-04-12  387   *
e2cfabdfd0756482 Will Drewry        2012-04-12  388   * Returns valid seccomp BPF response codes.
e2cfabdfd0756482 Will Drewry        2012-04-12  389   */
0466bdb99e8744bc Kees Cook          2017-08-11 @390  #define ACTION_ONLY(ret) ((s32)((ret) & (SECCOMP_RET_ACTION_FULL)))
deb4de8b31bc5bf2 Kees Cook          2017-08-02  391  static u32 seccomp_run_filters(const struct seccomp_data *sd,
deb4de8b31bc5bf2 Kees Cook          2017-08-02  392  			       struct seccomp_filter **match)
e2cfabdfd0756482 Will Drewry        2012-04-12  393  {
acf3b2c71ed20c53 Will Drewry        2012-04-12  394  	u32 ret = SECCOMP_RET_ALLOW;
8225d3853f34f6cf Pranith Kumar      2014-11-21  395  	/* Make sure cross-thread synced filter points somewhere sane. */
8225d3853f34f6cf Pranith Kumar      2014-11-21  396  	struct seccomp_filter *f =
506458efaf153c1e Will Deacon        2017-10-24  397  			READ_ONCE(current->seccomp.filter);
acf3b2c71ed20c53 Will Drewry        2012-04-12  398  
acf3b2c71ed20c53 Will Drewry        2012-04-12  399  	/* Ensure unexpected behavior doesn't result in failing open. */
0d42d73a37ff9102 Igor Stoppa        2018-09-05  400  	if (WARN_ON(f == NULL))
4d3b0b05aae9ee9c Kees Cook          2017-08-11  401  		return SECCOMP_RET_KILL_PROCESS;
acf3b2c71ed20c53 Will Drewry        2012-04-12  402  
f9d480b6ffbeb336 YiFei Zhu          2020-10-11  403  	if (seccomp_cache_check_allow(f, sd))
f9d480b6ffbeb336 YiFei Zhu          2020-10-11  404  		return SECCOMP_RET_ALLOW;
f9d480b6ffbeb336 YiFei Zhu          2020-10-11  405  
e2cfabdfd0756482 Will Drewry        2012-04-12  406  	/*
e2cfabdfd0756482 Will Drewry        2012-04-12  407  	 * All filters in the list are evaluated and the lowest BPF return
acf3b2c71ed20c53 Will Drewry        2012-04-12  408  	 * value always takes priority (ignoring the DATA).
e2cfabdfd0756482 Will Drewry        2012-04-12  409  	 */
3ba2530cc06eb4ae Kees Cook          2014-06-27  410  	for (; f; f = f->prev) {
3d9f773cf2876c01 David Miller       2020-02-24  411  		u32 cur_ret = bpf_prog_run_pin_on_cpu(f->prog, sd);
8f577cadf7181243 Alexei Starovoitov 2014-05-13  412  
0466bdb99e8744bc Kees Cook          2017-08-11  413  		if (ACTION_ONLY(cur_ret) < ACTION_ONLY(ret)) {
acf3b2c71ed20c53 Will Drewry        2012-04-12  414  			ret = cur_ret;
deb4de8b31bc5bf2 Kees Cook          2017-08-02  415  			*match = f;
deb4de8b31bc5bf2 Kees Cook          2017-08-02  416  		}
e2cfabdfd0756482 Will Drewry        2012-04-12  417  	}
e2cfabdfd0756482 Will Drewry        2012-04-12  418  	return ret;
e2cfabdfd0756482 Will Drewry        2012-04-12  419  }
1f41b450416e689b Kees Cook          2014-06-25  420  #endif /* CONFIG_SECCOMP_FILTER */
1f41b450416e689b Kees Cook          2014-06-25  421  

---
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: 10848 bytes --]

Re: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names

[kernel test robot]

[-- Attachment #1: Type: text/plain, Size: 4115 bytes --]

Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on next-20210113]
[also build test WARNING on v5.11-rc3]
[cannot apply to lwn/docs-next kees/for-next/pstore mac80211-next/master mac80211/master pza/reset/next linus/master v5.11-rc3 v5.11-rc2 v5.11-rc1]
[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/Fix-several-bad-kernel-doc-markups/20210114-161010
base:    aa515cdce7a151dcc14b7600d33f1414c6fa32c9
config: mips-nlm_xlp_defconfig (attached as .config)
compiler: mips64-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/1e9159b3640012fc5fab8508b1c5635ac13a55e9
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010
        git checkout 1e9159b3640012fc5fab8508b1c5635ac13a55e9
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=mips 

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 >>):

   arch/mips/kernel/module.c:289: warning: Function parameter or member 'reloc_handler' not described in 'int'
>> arch/mips/kernel/module.c:289: warning: expecting prototype for reloc_handler(). Prototype was for int() instead
--
   arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'p' not described in 'evaluate_branch_instruction'
   arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'regs' not described in 'evaluate_branch_instruction'
   arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'kcb' not described in 'evaluate_branch_instruction'
>> arch/mips/kernel/kprobes.c:196: warning: expecting prototype for evaluate_branch_instrucion(). Prototype was for evaluate_branch_instruction() instead


vim +289 arch/mips/kernel/module.c

5d3c792583b60406 Paul Burton 2016-02-04  272  
430d0b88943afffd Paul Burton 2017-03-30  273  /**
430d0b88943afffd Paul Burton 2017-03-30  274   * reloc_handler() - Apply a particular relocation to a module
430d0b88943afffd Paul Burton 2017-03-30  275   * @me: the module to apply the reloc to
430d0b88943afffd Paul Burton 2017-03-30  276   * @location: the address at which the reloc is to be applied
430d0b88943afffd Paul Burton 2017-03-30  277   * @base: the existing value at location for REL-style; 0 for RELA-style
430d0b88943afffd Paul Burton 2017-03-30  278   * @v: the value of the reloc, with addend for RELA-style
430d0b88943afffd Paul Burton 2017-03-30  279   *
430d0b88943afffd Paul Burton 2017-03-30  280   * Each implemented reloc_handler function applies a particular type of
430d0b88943afffd Paul Burton 2017-03-30  281   * relocation to the module @me. Relocs that may be found in either REL or RELA
430d0b88943afffd Paul Burton 2017-03-30  282   * variants can be handled by making use of the @base & @v parameters which are
430d0b88943afffd Paul Burton 2017-03-30  283   * set to values which abstract the difference away from the particular reloc
430d0b88943afffd Paul Burton 2017-03-30  284   * implementations.
430d0b88943afffd Paul Burton 2017-03-30  285   *
430d0b88943afffd Paul Burton 2017-03-30  286   * Return: 0 upon success, else -ERRNO
430d0b88943afffd Paul Burton 2017-03-30  287   */
430d0b88943afffd Paul Burton 2017-03-30  288  typedef int (*reloc_handler)(struct module *me, u32 *location,
430d0b88943afffd Paul Burton 2017-03-30 @289  			     u32 base, Elf_Addr v, bool rela);
430d0b88943afffd Paul Burton 2017-03-30  290  

---
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: 21744 bytes --]

Re: [PATCH v6 15/16] drm: drm_crc: fix a kernel-doc markup

[Simon Ser]

On Thursday, January 14th, 2021 at 9:06 AM, Simon Ser <contact@emersion.fr> wrote:

> On Thursday, January 14th, 2021 at 9:04 AM, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > A function has a different name between their prototype
> > and its kernel-doc markup:
> >
> > 	../include/drm/drm_crtc.h:1257: warning: expecting prototype for drm_crtc_alloc_with_planes(). Prototype was for drmm_crtc_alloc_with_planes() instead
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Acked-by: Simon Ser <contact@emersion.fr>

Pushed to drm-misc-next, thanks for the fix!

Re: [PATCH v6 16/16] platform/surface: aggregator: fix a kernel-doc markup

[Maximilian Luz]

On 1/14/21 9:04 AM, Mauro Carvalho Chehab wrote:
> A function has a different name between their prototype
> and its kernel-doc markup:
> 
> 	../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype for ssh_rtl_tx_start(). Prototype was for ssh_rtl_start() instead
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   drivers/platform/surface/aggregator/ssh_request_layer.c | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/platform/surface/aggregator/ssh_request_layer.c b/drivers/platform/surface/aggregator/ssh_request_layer.c
> index bb1c862411a2..25db4d638cfa 100644
> --- a/drivers/platform/surface/aggregator/ssh_request_layer.c
> +++ b/drivers/platform/surface/aggregator/ssh_request_layer.c
> @@ -1056,7 +1056,7 @@ void ssh_rtl_destroy(struct ssh_rtl *rtl)
>   }
>   
>   /**
> - * ssh_rtl_tx_start() - Start request transmitter and receiver.
> + * ssh_rtl_start() - Start request transmitter and receiver.
>    * @rtl: The request transport layer.
>    *
>    * Return: Returns zero on success, a negative error code on failure.
> 

Thanks! Looks good to me.

Reviewed-by: Maximilian Luz <luzmaximilian@gmail.com>

There seems to be another issue similar to this, specifically the
non-existing ssh_rtl_tx_start() and ssh_rtl_tx_start() are referenced.
Both should point to to ssh_rtl_start() instead. I'll start working on a
patch to fix that right away.

Regards,
Max

Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups

[Jon Maloy]

On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
> A function has a different name between their prototype
> and its kernel-doc markup:
>
> 	../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead
> 	../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   net/tipc/link.c | 2 +-
>   net/tipc/node.c | 2 +-
>   2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/net/tipc/link.c b/net/tipc/link.c
> index a6a694b78927..115109259430 100644
> --- a/net/tipc/link.c
> +++ b/net/tipc/link.c
> @@ -2544,7 +2544,7 @@ void tipc_link_set_queue_limits(struct tipc_link *l, u32 min_win, u32 max_win)
>   }
>   
>   /**
> - * link_reset_stats - reset link statistics
> + * tipc_link_reset_stats - reset link statistics
>    * @l: pointer to link
>    */
>   void tipc_link_reset_stats(struct tipc_link *l)
> diff --git a/net/tipc/node.c b/net/tipc/node.c
> index 83d9eb830592..008670d1f43e 100644
> --- a/net/tipc/node.c
> +++ b/net/tipc/node.c
> @@ -1665,7 +1665,7 @@ static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list)
>   }
>   
>   /**
> - * tipc_node_xmit() is the general link level function for message sending
> + * tipc_node_xmit() - general link level function for message sending
>    * @net: the applicable net namespace
>    * @list: chain of buffers containing message
>    * @dnode: address of destination node
Acked-by: Jon Maloy <jmaloy@redhat.com>

Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups

[Jakub Kicinski]

On Thu, 14 Jan 2021 10:59:08 -0500 Jon Maloy wrote:
> On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
> > A function has a different name between their prototype
> > and its kernel-doc markup:
> >
> > 	../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead
> > 	../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
> Acked-by: Jon Maloy <jmaloy@redhat.com>

Thanks! Applied this one to net, the cfg80211 one does not apply to
net, so I'll leave it to Johannes.

Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups

[Johannes Berg]

On Thu, 2021-01-14 at 10:34 -0800, Jakub Kicinski wrote:
> On Thu, 14 Jan 2021 10:59:08 -0500 Jon Maloy wrote:
> > On 1/14/21 3:04 AM, Mauro Carvalho Chehab wrote:
> > > A function has a different name between their prototype
> > > and its kernel-doc markup:
> > > 
> > > 	../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead
> > > 	../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > 
> > Acked-by: Jon Maloy <jmaloy@redhat.com>
> 
> Thanks! Applied this one to net, the cfg80211 one does not apply to
> net, so I'll leave it to Johannes.

Right, that was diffed against -next, and I've got a fix pending that I
didn't send yet.

I've applied this now, thanks.

johannes

Re: [PATCH v6 16/16] platform/surface: aggregator: fix a kernel-doc markup

[Hans de Goede]

Hi,

On 1/14/21 9:04 AM, Mauro Carvalho Chehab wrote:
> A function has a different name between their prototype
> and its kernel-doc markup:
> 
> 	../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype for ssh_rtl_tx_start(). Prototype was for ssh_rtl_start() instead
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Thank you for your patch, I've applied this patch to my review-hans 
branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans

Note it will show up in my review-hans branch once I've pushed my
local branch there, which might take a while.

Once I've run some tests on this branch the patches there will be
added to the platform-drivers-x86/for-next branch and eventually
will be included in the pdx86 pull-request to Linus for the next
merge-window.

Regards,

Hans


> ---
>  drivers/platform/surface/aggregator/ssh_request_layer.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/platform/surface/aggregator/ssh_request_layer.c b/drivers/platform/surface/aggregator/ssh_request_layer.c
> index bb1c862411a2..25db4d638cfa 100644
> --- a/drivers/platform/surface/aggregator/ssh_request_layer.c
> +++ b/drivers/platform/surface/aggregator/ssh_request_layer.c
> @@ -1056,7 +1056,7 @@ void ssh_rtl_destroy(struct ssh_rtl *rtl)
>  }
>  
>  /**
> - * ssh_rtl_tx_start() - Start request transmitter and receiver.
> + * ssh_rtl_start() - Start request transmitter and receiver.
>   * @rtl: The request transport layer.
>   *
>   * Return: Returns zero on success, a negative error code on failure.
> 

Re: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names

[Jonathan Corbet]

On Thu, 14 Jan 2021 09:04:47 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Kernel-doc currently expects that the kernel-doc markup to come
> just before the function/enum/struct/union/typedef 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 if the kernel-doc identifier matches the actual
> name of the C function or data structure that will be documented.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

I've applied this one; it seems useful to have even if it creates more
warnings that Stephen will duly email me about tomorrow...:)  I have parts
1-10 set aside and will apply any that don't get picked up directly by the
maintainers involved.

Thanks,

jon

Re: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names

[Mauro Carvalho Chehab]

Em Mon, 18 Jan 2021 13:35:45 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 14 Jan 2021 09:04:47 +0100
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 
> > Kernel-doc currently expects that the kernel-doc markup to come
> > just before the function/enum/struct/union/typedef 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 if the kernel-doc identifier matches the actual
> > name of the C function or data structure that will be documented.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> I've applied this one; 

Thanks!

> it seems useful to have even if it creates more
> warnings that Stephen will duly email me about tomorrow...:)  I have parts
> 1-10 set aside and will apply any that don't get picked up directly by the
> maintainers involved.

Yeah, new warnings are unavoidable, as new patches may be introducing
extra issues. Hopefully, the new warning will help people to detect
the issue earlier before submitting upstream.


Thanks,
Mauro

Re: [PATCH v6 00/16] Fix several bad kernel-doc markups

[Jonathan Corbet]

On Thu, 14 Jan 2021 09:04:36 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> 1)  10 remaining fixup patches from the series I sent back on Dec, 1st:
> 
>    parport: fix a kernel-doc markup
>    rapidio: fix kernel-doc a markup
>    fs: fix kernel-doc markups
>    pstore/zone: fix a kernel-doc markup
>    firmware: stratix10-svc: fix kernel-doc markups
>    connector: fix a kernel-doc markup
>    lib/crc7: fix a kernel-doc markup
>    memblock: fix kernel-doc markups
>    w1: fix a kernel-doc markup
>    selftests: kselftest_harness.h: partially fix kernel-doc markups

A week later none of these have shown up in linux-next, so I went ahead
and applied the set.

Thanks,

jon