Skip to contentSkip to conversation

PM / suspend: fix kernel-doc markup

PATCH Applied Alex Shi 5 participants 13 messages Nov 13, 2020 – Jan 28, 2021

Subsystems (9)
x86 PCI Crypto API Suspend to RAM +5 more subsystems
lore
Share & tools
lore

Alex Shi

author
#0 lore raw

PATCH 1/1 PM / suspend: fix kernel-doc markup

Add parameter explanation to fix kernel-doc marks:

kernel/power/suspend.c:233: warning: Function parameter or member 'state' not described in 'suspend_valid_only_mem' kernel/power/suspend.c:344: warning: Function parameter or member 'state' not described in 'suspend_prepare'

---
 kernel/power/suspend.c | 2 ++
 1 file changed, 2 insertions(+)
kernel/power/suspend.c +2 -0
index 32391acc806b..502d86ed99c7 100644
@@ -224,6 +224,7 @@ EXPORT_SYMBOL_GPL(suspend_set_ops);
 
 /**
  * suspend_valid_only_mem - Generic memory-only valid callback.
+ * @state: Suspend state to be set
  *
  * Platform drivers that implement mem suspend only and only need to check for
  * that in their .valid() callback can use this instead of rolling their own
@@ -335,6 +336,7 @@ static int suspend_test(int level)
 
 /**
  * suspend_prepare - Prepare for entering system sleep state.
+ * @state: suspend state which sleep from
  *
  * Common code run for every system sleep state that can be entered (except for
  * hibernation).  Run suspend notifiers, allocate the "suspend" console and
Signature · 1 line
2.29.GIT
author
#1 lore raw

PATCH 1/1 locking/rtmutex: add missed kernel-doc markup

To fix the following issues:
kernel/locking/rtmutex.c:1612: warning: Function parameter or member 'lock' not described in '__rt_mutex_futex_unlock' kernel/locking/rtmutex.c:1612: warning: Function parameter or member 'wake_q' not described in '__rt_mutex_futex_unlock' kernel/locking/rtmutex.c:1675: warning: Function parameter or member 'name' not described in '__rt_mutex_init' kernel/locking/rtmutex.c:1675: warning: Function parameter or member 'key' not described in '__rt_mutex_init'

Cc Peter Zijlstra <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Will Deacon <[email protected]>
---
 kernel/locking/rtmutex.c | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
kernel/locking/rtmutex.c +7 -2
index cfdd5b93264d..50fa521fe767 100644
@@ -1604,8 +1604,11 @@ void __sched rt_mutex_unlock(struct rt_mutex *lock)
 EXPORT_SYMBOL_GPL(rt_mutex_unlock);
 
 /**
- * Futex variant, that since futex variants do not use the fast-path, can be
- * simple and will not need to retry.
+ * __rt_mutex_futex_unlock - Futex variant, that since futex variants
+ * do not use the fast-path, can be simple and will not need to retry.
+ *
+ * @lock: the rt_mutex to be unlocked
+ * @wake_q: wake queue head from which get the next lock waiter
  */
 bool __sched __rt_mutex_futex_unlock(struct rt_mutex *lock,
 				    struct wake_q_head *wake_q)
@@ -1665,6 +1668,8 @@ EXPORT_SYMBOL_GPL(rt_mutex_destroy);
  * __rt_mutex_init - initialize the rt lock
  *
  * @lock: the rt lock to be initialized
+ * @name: the lock name used for debug
+ * @key: the lock class key used for debug
  *
  * Initialize the rt lock to unlocked state.
  *
Signature · 1 line
2.29.GIT
maintainer Acked-by on v1 1/1
#2 lore raw

Re: [PATCH] locking/rtmutex: add missed kernel-doc markup

Quoted 24 lines · Alex Shi

To fix the following issues:
kernel/locking/rtmutex.c:1612: warning: Function parameter or member 'lock' not described in '__rt_mutex_futex_unlock' kernel/locking/rtmutex.c:1612: warning: Function parameter or member 'wake_q' not described in '__rt_mutex_futex_unlock' kernel/locking/rtmutex.c:1675: warning: Function parameter or member 'name' not described in '__rt_mutex_init' kernel/locking/rtmutex.c:1675: warning: Function parameter or member 'key' not described in '__rt_mutex_init'

Cc Peter Zijlstra <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Will Deacon <[email protected]>
---
 kernel/locking/rtmutex.c | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
kernel/locking/rtmutex.c +0 -0
index cfdd5b93264d..50fa521fe767 100644

kernel/locking/rtmutex.c void __sched rt_mutex_unlock(struct rt_mutex *lock) · line 1611

Quoted 10 lines
kernel/locking/rtmutex.c +5 -2
@@ -1604,8 +1604,11 @@ void __sched rt_mutex_unlock(struct rt_mutex *lock)
 EXPORT_SYMBOL_GPL(rt_mutex_unlock);
 
 /**
- * Futex variant, that since futex variants do not use the fast-path, can be
- * simple and will not need to retry.
+ * __rt_mutex_futex_unlock - Futex variant, that since futex variants
+ * do not use the fast-path, can be simple and will not need to retry.
+ *
+ * @lock: the rt_mutex to be unlocked
+ * @wake_q: wake queue head from which get the next lock waiter

missing word: from which *to* get

With that fixed,

Will

merge bot Applied
#3 lore raw

[tip: locking/core] locking/rtmutex: Add missing kernel-doc markup

In reply to Alex Shi
The following commit has been merged into the locking/core branch of tip:

The following commit has been merged into the locking/core branch of tip:

Commit-ID:     59ea5f1508e15cecddd8e2ca828f7962ea37adab
Gitweb:        https://git.kernel.org/tip/59ea5f1508e15cecddd8e2ca828f7962ea37adab
Author:        Alex Shi <[email protected]>
AuthorDate:    Fri, 13 Nov 2020 16:58:11 +08:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 27 Jan 2021 12:44:52 +01:00

locking/rtmutex: Add missing kernel-doc markup

To fix the following issues:
kernel/locking/rtmutex.c:1612: warning: Function parameter or member 'lock' not described in '__rt_mutex_futex_unlock' kernel/locking/rtmutex.c:1612: warning: Function parameter or member 'wake_q' not described in '__rt_mutex_futex_unlock' kernel/locking/rtmutex.c:1675: warning: Function parameter or member 'name' not described in '__rt_mutex_init' kernel/locking/rtmutex.c:1675: warning: Function parameter or member 'key' not described in '__rt_mutex_init'

[ tglx: Change rt lock to rt_mutex for consistency sake ]

---
 kernel/locking/rtmutex.c | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)
kernel/locking/rtmutex.c +11 -6
index cfdd5b9..a201e5e 100644
@@ -1604,8 +1604,11 @@ void __sched rt_mutex_unlock(struct rt_mutex *lock)
 EXPORT_SYMBOL_GPL(rt_mutex_unlock);
 
 /**
- * Futex variant, that since futex variants do not use the fast-path, can be
- * simple and will not need to retry.
+ * __rt_mutex_futex_unlock - Futex variant, that since futex variants
+ * do not use the fast-path, can be simple and will not need to retry.
+ *
+ * @lock:	The rt_mutex to be unlocked
+ * @wake_q:	The wake queue head from which to get the next lock waiter
  */
 bool __sched __rt_mutex_futex_unlock(struct rt_mutex *lock,
 				    struct wake_q_head *wake_q)
@@ -1662,13 +1665,15 @@ void rt_mutex_destroy(struct rt_mutex *lock)
 EXPORT_SYMBOL_GPL(rt_mutex_destroy);
 
 /**
- * __rt_mutex_init - initialize the rt lock
+ * __rt_mutex_init - initialize the rt_mutex
  *
- * @lock: the rt lock to be initialized
+ * @lock:	The rt_mutex to be initialized
+ * @name:	The lock name used for debugging
+ * @key:	The lock class key used for debugging
  *
- * Initialize the rt lock to unlocked state.
+ * Initialize the rt_mutex to unlocked state.
  *
- * Initializing of a locked rt lock is not allowed
+ * Initializing of a locked rt_mutex is not allowed
  */
 void __rt_mutex_init(struct rt_mutex *lock, const char *name,
 		     struct lock_class_key *key)
merge bot Applied
#4 lore raw

[tip: locking/core] locking/rtmutex: Add missing kernel-doc markup

In reply to Alex Shi
The following commit has been merged into the locking/core branch of tip:

The following commit has been merged into the locking/core branch of tip:

Commit-ID:     bf594bf400016a1ac58c753bcc0393a39c36f669
Gitweb:        https://git.kernel.org/tip/bf594bf400016a1ac58c753bcc0393a39c36f669
Author:        Alex Shi <[email protected]>
AuthorDate:    Fri, 13 Nov 2020 16:58:11 +08:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Thu, 28 Jan 2021 13:20:18 +01:00

locking/rtmutex: Add missing kernel-doc markup

To fix the following issues:
kernel/locking/rtmutex.c:1612: warning: Function parameter or member 'lock' not described in '__rt_mutex_futex_unlock' kernel/locking/rtmutex.c:1612: warning: Function parameter or member 'wake_q' not described in '__rt_mutex_futex_unlock' kernel/locking/rtmutex.c:1675: warning: Function parameter or member 'name' not described in '__rt_mutex_init' kernel/locking/rtmutex.c:1675: warning: Function parameter or member 'key' not described in '__rt_mutex_init'

[ tglx: Change rt lock to rt_mutex for consistency sake ]

---
 kernel/locking/rtmutex.c | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)
kernel/locking/rtmutex.c +11 -6
index cfdd5b9..a201e5e 100644
@@ -1604,8 +1604,11 @@ void __sched rt_mutex_unlock(struct rt_mutex *lock)
 EXPORT_SYMBOL_GPL(rt_mutex_unlock);
 
 /**
- * Futex variant, that since futex variants do not use the fast-path, can be
- * simple and will not need to retry.
+ * __rt_mutex_futex_unlock - Futex variant, that since futex variants
+ * do not use the fast-path, can be simple and will not need to retry.
+ *
+ * @lock:	The rt_mutex to be unlocked
+ * @wake_q:	The wake queue head from which to get the next lock waiter
  */
 bool __sched __rt_mutex_futex_unlock(struct rt_mutex *lock,
 				    struct wake_q_head *wake_q)
@@ -1662,13 +1665,15 @@ void rt_mutex_destroy(struct rt_mutex *lock)
 EXPORT_SYMBOL_GPL(rt_mutex_destroy);
 
 /**
- * __rt_mutex_init - initialize the rt lock
+ * __rt_mutex_init - initialize the rt_mutex
  *
- * @lock: the rt lock to be initialized
+ * @lock:	The rt_mutex to be initialized
+ * @name:	The lock name used for debugging
+ * @key:	The lock class key used for debugging
  *
- * Initialize the rt lock to unlocked state.
+ * Initialize the rt_mutex to unlocked state.
  *
- * Initializing of a locked rt lock is not allowed
+ * Initializing of a locked rt_mutex is not allowed
  */
 void __rt_mutex_init(struct rt_mutex *lock, const char *name,
 		     struct lock_class_key *key)
author
#5 lore raw

PATCH 1/1 locking/rtmutex: remove useless parameter for rt_mutex_proxy_unlock

In reply to Alex Shi

The parameter 'proxy_owner' isn't used, so could be removed.

Cc Thomas Gleixner <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Peter Zijlstra <[email protected]>
Cc Darren Hart <[email protected]>
Cc Will Deacon <[email protected]>
---
 kernel/futex.c                  | 2 +-
 kernel/locking/rtmutex.c        | 3 +--
 kernel/locking/rtmutex_common.h | 3 +--
 3 files changed, 3 insertions(+), 5 deletions(-)
kernel/futex.c +1 -1
index f8614ef4ff31..347deedcfd0e 100644
@@ -796,7 +796,7 @@ static void put_pi_state(struct futex_pi_state *pi_state)
 			list_del_init(&pi_state->list);
 			raw_spin_unlock(&owner->pi_lock);
 		}
-		rt_mutex_proxy_unlock(&pi_state->pi_mutex, owner);
+		rt_mutex_proxy_unlock(&pi_state->pi_mutex);
 		raw_spin_unlock_irq(&pi_state->pi_mutex.wait_lock);
 	}
 
kernel/locking/rtmutex.c +1 -2
index 50fa521fe767..f196045f2857 100644
@@ -1721,8 +1721,7 @@ void rt_mutex_init_proxy_locked(struct rt_mutex *lock,
  * possible because it belongs to the pi_state which is about to be freed
  * and it is not longer visible to other tasks.
  */
-void rt_mutex_proxy_unlock(struct rt_mutex *lock,
-			   struct task_struct *proxy_owner)
+void rt_mutex_proxy_unlock(struct rt_mutex *lock)
 {
 	debug_rt_mutex_proxy_unlock(lock);
 	rt_mutex_set_owner(lock, NULL);
kernel/locking/rtmutex_common.h +1 -2
index d1d62f942be2..ca6fb489007b 100644
@@ -133,8 +133,7 @@ enum rtmutex_chainwalk {
 extern struct task_struct *rt_mutex_next_owner(struct rt_mutex *lock);
 extern void rt_mutex_init_proxy_locked(struct rt_mutex *lock,
 				       struct task_struct *proxy_owner);
-extern void rt_mutex_proxy_unlock(struct rt_mutex *lock,
-				  struct task_struct *proxy_owner);
+extern void rt_mutex_proxy_unlock(struct rt_mutex *lock);
 extern void rt_mutex_init_waiter(struct rt_mutex_waiter *waiter);
 extern int __rt_mutex_start_proxy_lock(struct rt_mutex *lock,
 				     struct rt_mutex_waiter *waiter,
Signature · 1 line
2.29.GIT
maintainer Acked-by on v1 1/1
#6 lore raw

Re: [PATCH] locking/rtmutex: remove useless parameter for rt_mutex_proxy_unlock

Quoted 1 line · Alex Shi

The parameter 'proxy_owner' isn't used, so could be removed.

Looks like the last user of this was removed in fffa954fb528 ("futex: Remove rt_mutex_deadlock_account_*()").

Quoted 7 lines
Cc Thomas Gleixner <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Peter Zijlstra <[email protected]>
Cc Darren Hart <[email protected]>
Cc Will Deacon <[email protected]>
Quoted 5 lines
---
 kernel/futex.c                  | 2 +-
 kernel/locking/rtmutex.c        | 3 +--
 kernel/locking/rtmutex_common.h | 3 +--
 3 files changed, 3 insertions(+), 5 deletions(-)

Will

author
#7 lore raw

PATCH 1/1 configfs: fix kernel-doc markup issue

In reply to Alex Shi

Add explanation for 'frag' parameter to avoid kernel-doc issue:
fs/configfs/dir.c:277: warning: Function parameter or member 'frag' not described in 'configfs_create_dir'

Cc Joel Becker <[email protected]>
Cc Christoph Hellwig <[email protected]>
---
 fs/configfs/dir.c | 1 +
 1 file changed, 1 insertion(+)
fs/configfs/dir.c +1 -0
index b0983e2a4e2c..b839dd1b459f 100644
@@ -267,6 +267,7 @@ static void configfs_remove_dirent(struct dentry *dentry)
  *	configfs_create_dir - create a directory for an config_item.
  *	@item:		config_itemwe're creating directory for.
  *	@dentry:	config_item's dentry.
+ *	@frag:		config_item's fragment.
  *
  *	Note: user-created entries won't be allowed under this new directory
  *	until it is validated by configfs_dir_set_ready()
Signature · 1 line
2.29.GIT
author
#9 lore raw

PATCH 1/1 PKCS#7: drop function from kernel-doc pkcs7_validate_trust_one

In reply to Alex Shi

The function is a static function, so no needs add into kernel-doc. and we could avoid warning:
crypto/asymmetric_keys/pkcs7_trust.c:25: warning: Function parameter or member 'pkcs7' not described in 'pkcs7_validate_trust_one' crypto/asymmetric_keys/pkcs7_trust.c:25: warning: Function parameter or member 'sinfo' not described in 'pkcs7_validate_trust_one' crypto/asymmetric_keys/pkcs7_trust.c:25: warning: Function parameter or member 'trust_keyring' not described in 'pkcs7_validate_trust_one'

---
 crypto/asymmetric_keys/pkcs7_trust.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
crypto/asymmetric_keys/pkcs7_trust.c +1 -1
index 61af3c4d82cc..b531df2013c4 100644
@@ -16,7 +16,7 @@
 #include <crypto/public_key.h>
 #include "pkcs7_parser.h"
 
-/**
+/*
  * Check the trust on one PKCS#7 SignedInfo block.
  */
 static int pkcs7_validate_trust_one(struct pkcs7_message *pkcs7,
Signature · 1 line
2.29.GIT
author
#10 lore raw

PATCH 1/1 x86/PCI: fix a comments issue

In reply to Alex Shi

The comments is using kernel-doc markup, while it isn't, so remove it from kernel-doc type to avoid warning:
arch/x86/pci/i386.c:373: warning: Function parameter or member 'pcibios_assign_resources' not described in 'fs_initcall'

Cc Bjorn Helgaas <[email protected]>
Cc Thomas Gleixner <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Borislav Petkov <[email protected]>
Cc "H. Peter Anvin" <[email protected]>
---
 arch/x86/pci/i386.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
arch/x86/pci/i386.c +1 -1
index fa855bbaebaf..77fda6d432c6 100644
@@ -366,7 +366,7 @@ static int __init pcibios_assign_resources(void)
 	return 0;
 }
 
-/**
+/*
  * called in fs_initcall (one below subsys_initcall),
  * give a chance for motherboard reserve resources
  */
Signature · 1 line
2.29.GIT
merge bot Applied
#11 lore raw

[tip: x86/cleanups] x86/PCI: Make a kernel-doc comment a normal one

The following commit has been merged into the x86/cleanups branch of tip:

The following commit has been merged into the x86/cleanups branch of tip:

Commit-ID:     638920a66a17c8e1f4415cbab0d49dc4a344c2a7
Gitweb:        https://git.kernel.org/tip/638920a66a17c8e1f4415cbab0d49dc4a344c2a7
Author:        Alex Shi <[email protected]>
AuthorDate:    Fri, 13 Nov 2020 16:58:14 +08:00
Committer:     Borislav Petkov <[email protected]>
CommitterDate: Fri, 27 Nov 2020 13:43:09 +01:00

x86/PCI: Make a kernel-doc comment a normal one

The comment is using kernel-doc markup but that comment isn't a kernel-doc comment so make it a normal one to avoid:

arch/x86/pci/i386.c:373: warning: Function parameter or member \
'pcibios_assign_resources' not described in 'fs_initcall'

[ bp: Massage and fixup comment while at it. ]

---
 arch/x86/pci/i386.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
arch/x86/pci/i386.c +3 -3
index fa855bb..f2f4a5d 100644
@@ -366,9 +366,9 @@ static int __init pcibios_assign_resources(void)
 	return 0;
 }
 
-/**
- * called in fs_initcall (one below subsys_initcall),
- * give a chance for motherboard reserve resources
+/*
+ * This is an fs_initcall (one below subsys_initcall) in order to reserve
+ * resources properly.
  */
 fs_initcall(pcibios_assign_resources);
 
maintainer Applied
#12 lore raw
In reply to Alex Shi
Quoted 31 lines · Alex Shi

Add parameter explanation to fix kernel-doc marks:

kernel/power/suspend.c:233: warning: Function parameter or member 'state' not described in 'suspend_valid_only_mem' kernel/power/suspend.c:344: warning: Function parameter or member 'state' not described in 'suspend_prepare'

---
 kernel/power/suspend.c | 2 ++
 1 file changed, 2 insertions(+)
kernel/power/suspend.c +1 -0
index 32391acc806b..502d86ed99c7 100644
@@ -224,6 +224,7 @@ EXPORT_SYMBOL_GPL(suspend_set_ops);
 
 /**
  * suspend_valid_only_mem - Generic memory-only valid callback.
+ * @state: Suspend state to be set
  *
  * Platform drivers that implement mem suspend only and only need to check for
  * that in their .valid() callback can use this instead of rolling their own

kernel/power/suspend.c static int suspend_test(int level)

Quoted 8 lines
kernel/power/suspend.c +1 -1
@@ -335,6 +336,7 @@ static int suspend_test(int level)
 
 /**
  * suspend_prepare - Prepare for entering system sleep state.
+ * @state: suspend state which sleep from
  *
  * Common code run for every system sleep state that can be entered (except for
  * hibernation).  Run suspend notifiers, allocate the "suspend" console and
--

Applied as 5.11 material, but I've changed the originally proposed parameter descriptions into "Target system sleep state" in both cases.

Thanks!