All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH v3] moduleparam: fix kerneldoc
@ 2019-12-02  9:01 Fabien Dessenne
  2019-12-02 22:04 ` Randy Dunlap
  2019-12-04 19:31 ` Jessica Yu
  0 siblings, 2 replies; 3+ messages in thread
From: Fabien Dessenne @ 2019-12-02  9:01 UTC (permalink / raw)
  To: Jessica Yu, Alexey Gladkov, Zhenzhong Duan,
	Gleb Fotengauer-Malinovskiy, Randy Dunlap, linux-kernel
  Cc: Fabien Dessenne

Document missing @arg in xxx_param_cb().
Describe all parameters of module_param_[named_]unsafe() and all
*_param_cb() to make ./scripts/kernel-doc happy.

Signed-off-by: Fabien Dessenne <fabien.dessenne@st.com>
---
Changes since v2: @arg not @args + fix other kernel-doc warnings
Changes since v1: do not replace 'lvalue' with 'value'
---
 include/linux/moduleparam.h | 82 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 77 insertions(+), 5 deletions(-)

diff --git a/include/linux/moduleparam.h b/include/linux/moduleparam.h
index e5c3e23..3ef917f 100644
--- a/include/linux/moduleparam.h
+++ b/include/linux/moduleparam.h
@@ -128,6 +128,9 @@ struct kparam_array
 
 /**
  * module_param_unsafe - same as module_param but taints kernel
+ * @name: the variable to alter, and exposed parameter name.
+ * @type: the type of the parameter
+ * @perm: visibility in sysfs.
  */
 #define module_param_unsafe(name, type, perm)			\
 	module_param_named_unsafe(name, name, type, perm)
@@ -150,6 +153,10 @@ struct kparam_array
 
 /**
  * module_param_named_unsafe - same as module_param_named but taints kernel
+ * @name: a valid C identifier which is the parameter name.
+ * @value: the actual lvalue to alter.
+ * @type: the type of the parameter
+ * @perm: visibility in sysfs.
  */
 #define module_param_named_unsafe(name, value, type, perm)		\
 	param_check_##type(name, &(value));				\
@@ -160,6 +167,7 @@ struct kparam_array
  * module_param_cb - general callback for a module/cmdline parameter
  * @name: a valid C identifier which is the parameter name.
  * @ops: the set & get operations for this parameter.
+ * @arg: args for @ops
  * @perm: visibility in sysfs.
  *
  * The ops can have NULL set or get functions.
@@ -171,36 +179,96 @@ struct kparam_array
 	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, -1,    \
 			    KERNEL_PARAM_FL_UNSAFE)
 
+#define __level_param_cb(name, ops, arg, perm, level)			\
+	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, level, 0)
 /**
- * <level>_param_cb - general callback for a module/cmdline parameter
- *                    to be evaluated before certain initcall level
+ * core_param_cb - general callback for a module/cmdline parameter
+ *                 to be evaluated before core initcall level
  * @name: a valid C identifier which is the parameter name.
  * @ops: the set & get operations for this parameter.
+ * @arg: args for @ops
  * @perm: visibility in sysfs.
  *
  * The ops can have NULL set or get functions.
  */
-#define __level_param_cb(name, ops, arg, perm, level)			\
-	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, level, 0)
-
 #define core_param_cb(name, ops, arg, perm)		\
 	__level_param_cb(name, ops, arg, perm, 1)
 
+/**
+ * postcore_param_cb - general callback for a module/cmdline parameter
+ *                     to be evaluated before postcore initcall level
+ * @name: a valid C identifier which is the parameter name.
+ * @ops: the set & get operations for this parameter.
+ * @arg: args for @ops
+ * @perm: visibility in sysfs.
+ *
+ * The ops can have NULL set or get functions.
+ */
 #define postcore_param_cb(name, ops, arg, perm)		\
 	__level_param_cb(name, ops, arg, perm, 2)
 
+/**
+ * arch_param_cb - general callback for a module/cmdline parameter
+ *                 to be evaluated before arch initcall level
+ * @name: a valid C identifier which is the parameter name.
+ * @ops: the set & get operations for this parameter.
+ * @arg: args for @ops
+ * @perm: visibility in sysfs.
+ *
+ * The ops can have NULL set or get functions.
+ */
 #define arch_param_cb(name, ops, arg, perm)		\
 	__level_param_cb(name, ops, arg, perm, 3)
 
+/**
+ * subsys_param_cb - general callback for a module/cmdline parameter
+ *                   to be evaluated before subsys initcall level
+ * @name: a valid C identifier which is the parameter name.
+ * @ops: the set & get operations for this parameter.
+ * @arg: args for @ops
+ * @perm: visibility in sysfs.
+ *
+ * The ops can have NULL set or get functions.
+ */
 #define subsys_param_cb(name, ops, arg, perm)		\
 	__level_param_cb(name, ops, arg, perm, 4)
 
+/**
+ * fs_param_cb - general callback for a module/cmdline parameter
+ *               to be evaluated before fs initcall level
+ * @name: a valid C identifier which is the parameter name.
+ * @ops: the set & get operations for this parameter.
+ * @arg: args for @ops
+ * @perm: visibility in sysfs.
+ *
+ * The ops can have NULL set or get functions.
+ */
 #define fs_param_cb(name, ops, arg, perm)		\
 	__level_param_cb(name, ops, arg, perm, 5)
 
+/**
+ * device_param_cb - general callback for a module/cmdline parameter
+ *                   to be evaluated before device initcall level
+ * @name: a valid C identifier which is the parameter name.
+ * @ops: the set & get operations for this parameter.
+ * @arg: args for @ops
+ * @perm: visibility in sysfs.
+ *
+ * The ops can have NULL set or get functions.
+ */
 #define device_param_cb(name, ops, arg, perm)		\
 	__level_param_cb(name, ops, arg, perm, 6)
 
+/**
+ * late_param_cb - general callback for a module/cmdline parameter
+ *                 to be evaluated before late initcall level
+ * @name: a valid C identifier which is the parameter name.
+ * @ops: the set & get operations for this parameter.
+ * @arg: args for @ops
+ * @perm: visibility in sysfs.
+ *
+ * The ops can have NULL set or get functions.
+ */
 #define late_param_cb(name, ops, arg, perm)		\
 	__level_param_cb(name, ops, arg, perm, 7)
 
@@ -263,6 +331,10 @@ static inline void kernel_param_unlock(struct module *mod)
 
 /**
  * core_param_unsafe - same as core_param but taints kernel
+ * @name: the name of the cmdline and sysfs parameter (often the same as var)
+ * @var: the variable
+ * @type: the type of the parameter
+ * @perm: visibility in sysfs
  */
 #define core_param_unsafe(name, var, type, perm)		\
 	param_check_##type(name, &(var));				\
-- 
2.7.4


^ permalink raw reply related	[flat|nested] 3+ messages in thread

* Re: [PATCH v3] moduleparam: fix kerneldoc
  2019-12-02  9:01 [PATCH v3] moduleparam: fix kerneldoc Fabien Dessenne
@ 2019-12-02 22:04 ` Randy Dunlap
  2019-12-04 19:31 ` Jessica Yu
  1 sibling, 0 replies; 3+ messages in thread
From: Randy Dunlap @ 2019-12-02 22:04 UTC (permalink / raw)
  To: Fabien Dessenne, Jessica Yu, Alexey Gladkov, Zhenzhong Duan,
	Gleb Fotengauer-Malinovskiy, linux-kernel

On 12/2/19 1:01 AM, Fabien Dessenne wrote:
> Document missing @arg in xxx_param_cb().
> Describe all parameters of module_param_[named_]unsafe() and all
> *_param_cb() to make ./scripts/kernel-doc happy.
> 
> Signed-off-by: Fabien Dessenne <fabien.dessenne@st.com>

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
> Changes since v2: @arg not @args + fix other kernel-doc warnings
> Changes since v1: do not replace 'lvalue' with 'value'
> ---
>  include/linux/moduleparam.h | 82 ++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 77 insertions(+), 5 deletions(-)
> 
> diff --git a/include/linux/moduleparam.h b/include/linux/moduleparam.h
> index e5c3e23..3ef917f 100644
> --- a/include/linux/moduleparam.h
> +++ b/include/linux/moduleparam.h
> @@ -128,6 +128,9 @@ struct kparam_array
>  
>  /**
>   * module_param_unsafe - same as module_param but taints kernel
> + * @name: the variable to alter, and exposed parameter name.
> + * @type: the type of the parameter
> + * @perm: visibility in sysfs.
>   */
>  #define module_param_unsafe(name, type, perm)			\
>  	module_param_named_unsafe(name, name, type, perm)
> @@ -150,6 +153,10 @@ struct kparam_array
>  
>  /**
>   * module_param_named_unsafe - same as module_param_named but taints kernel
> + * @name: a valid C identifier which is the parameter name.
> + * @value: the actual lvalue to alter.
> + * @type: the type of the parameter
> + * @perm: visibility in sysfs.
>   */
>  #define module_param_named_unsafe(name, value, type, perm)		\
>  	param_check_##type(name, &(value));				\
> @@ -160,6 +167,7 @@ struct kparam_array
>   * module_param_cb - general callback for a module/cmdline parameter
>   * @name: a valid C identifier which is the parameter name.
>   * @ops: the set & get operations for this parameter.
> + * @arg: args for @ops
>   * @perm: visibility in sysfs.
>   *
>   * The ops can have NULL set or get functions.
> @@ -171,36 +179,96 @@ struct kparam_array
>  	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, -1,    \
>  			    KERNEL_PARAM_FL_UNSAFE)
>  
> +#define __level_param_cb(name, ops, arg, perm, level)			\
> +	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, level, 0)
>  /**
> - * <level>_param_cb - general callback for a module/cmdline parameter
> - *                    to be evaluated before certain initcall level
> + * core_param_cb - general callback for a module/cmdline parameter
> + *                 to be evaluated before core initcall level
>   * @name: a valid C identifier which is the parameter name.
>   * @ops: the set & get operations for this parameter.
> + * @arg: args for @ops
>   * @perm: visibility in sysfs.
>   *
>   * The ops can have NULL set or get functions.
>   */
> -#define __level_param_cb(name, ops, arg, perm, level)			\
> -	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, level, 0)
> -
>  #define core_param_cb(name, ops, arg, perm)		\
>  	__level_param_cb(name, ops, arg, perm, 1)
>  
> +/**
> + * postcore_param_cb - general callback for a module/cmdline parameter
> + *                     to be evaluated before postcore initcall level
> + * @name: a valid C identifier which is the parameter name.
> + * @ops: the set & get operations for this parameter.
> + * @arg: args for @ops
> + * @perm: visibility in sysfs.
> + *
> + * The ops can have NULL set or get functions.
> + */
>  #define postcore_param_cb(name, ops, arg, perm)		\
>  	__level_param_cb(name, ops, arg, perm, 2)
>  
> +/**
> + * arch_param_cb - general callback for a module/cmdline parameter
> + *                 to be evaluated before arch initcall level
> + * @name: a valid C identifier which is the parameter name.
> + * @ops: the set & get operations for this parameter.
> + * @arg: args for @ops
> + * @perm: visibility in sysfs.
> + *
> + * The ops can have NULL set or get functions.
> + */
>  #define arch_param_cb(name, ops, arg, perm)		\
>  	__level_param_cb(name, ops, arg, perm, 3)
>  
> +/**
> + * subsys_param_cb - general callback for a module/cmdline parameter
> + *                   to be evaluated before subsys initcall level
> + * @name: a valid C identifier which is the parameter name.
> + * @ops: the set & get operations for this parameter.
> + * @arg: args for @ops
> + * @perm: visibility in sysfs.
> + *
> + * The ops can have NULL set or get functions.
> + */
>  #define subsys_param_cb(name, ops, arg, perm)		\
>  	__level_param_cb(name, ops, arg, perm, 4)
>  
> +/**
> + * fs_param_cb - general callback for a module/cmdline parameter
> + *               to be evaluated before fs initcall level
> + * @name: a valid C identifier which is the parameter name.
> + * @ops: the set & get operations for this parameter.
> + * @arg: args for @ops
> + * @perm: visibility in sysfs.
> + *
> + * The ops can have NULL set or get functions.
> + */
>  #define fs_param_cb(name, ops, arg, perm)		\
>  	__level_param_cb(name, ops, arg, perm, 5)
>  
> +/**
> + * device_param_cb - general callback for a module/cmdline parameter
> + *                   to be evaluated before device initcall level
> + * @name: a valid C identifier which is the parameter name.
> + * @ops: the set & get operations for this parameter.
> + * @arg: args for @ops
> + * @perm: visibility in sysfs.
> + *
> + * The ops can have NULL set or get functions.
> + */
>  #define device_param_cb(name, ops, arg, perm)		\
>  	__level_param_cb(name, ops, arg, perm, 6)
>  
> +/**
> + * late_param_cb - general callback for a module/cmdline parameter
> + *                 to be evaluated before late initcall level
> + * @name: a valid C identifier which is the parameter name.
> + * @ops: the set & get operations for this parameter.
> + * @arg: args for @ops
> + * @perm: visibility in sysfs.
> + *
> + * The ops can have NULL set or get functions.
> + */
>  #define late_param_cb(name, ops, arg, perm)		\
>  	__level_param_cb(name, ops, arg, perm, 7)
>  
> @@ -263,6 +331,10 @@ static inline void kernel_param_unlock(struct module *mod)
>  
>  /**
>   * core_param_unsafe - same as core_param but taints kernel
> + * @name: the name of the cmdline and sysfs parameter (often the same as var)
> + * @var: the variable
> + * @type: the type of the parameter
> + * @perm: visibility in sysfs
>   */
>  #define core_param_unsafe(name, var, type, perm)		\
>  	param_check_##type(name, &(var));				\
> 


-- 
~Randy


^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH v3] moduleparam: fix kerneldoc
  2019-12-02  9:01 [PATCH v3] moduleparam: fix kerneldoc Fabien Dessenne
  2019-12-02 22:04 ` Randy Dunlap
@ 2019-12-04 19:31 ` Jessica Yu
  1 sibling, 0 replies; 3+ messages in thread
From: Jessica Yu @ 2019-12-04 19:31 UTC (permalink / raw)
  To: Fabien Dessenne
  Cc: Alexey Gladkov, Zhenzhong Duan, Gleb Fotengauer-Malinovskiy,
	Randy Dunlap, linux-kernel

+++ Fabien Dessenne [02/12/19 10:01 +0100]:
>Document missing @arg in xxx_param_cb().
>Describe all parameters of module_param_[named_]unsafe() and all
>*_param_cb() to make ./scripts/kernel-doc happy.
>
>Signed-off-by: Fabien Dessenne <fabien.dessenne@st.com>

Looks good, I'll apply this to modules-next after the merge window ends.

Thanks!

Jessica

>---
>Changes since v2: @arg not @args + fix other kernel-doc warnings
>Changes since v1: do not replace 'lvalue' with 'value'
>---
> include/linux/moduleparam.h | 82 ++++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 77 insertions(+), 5 deletions(-)
>
>diff --git a/include/linux/moduleparam.h b/include/linux/moduleparam.h
>index e5c3e23..3ef917f 100644
>--- a/include/linux/moduleparam.h
>+++ b/include/linux/moduleparam.h
>@@ -128,6 +128,9 @@ struct kparam_array
>
> /**
>  * module_param_unsafe - same as module_param but taints kernel
>+ * @name: the variable to alter, and exposed parameter name.
>+ * @type: the type of the parameter
>+ * @perm: visibility in sysfs.
>  */
> #define module_param_unsafe(name, type, perm)			\
> 	module_param_named_unsafe(name, name, type, perm)
>@@ -150,6 +153,10 @@ struct kparam_array
>
> /**
>  * module_param_named_unsafe - same as module_param_named but taints kernel
>+ * @name: a valid C identifier which is the parameter name.
>+ * @value: the actual lvalue to alter.
>+ * @type: the type of the parameter
>+ * @perm: visibility in sysfs.
>  */
> #define module_param_named_unsafe(name, value, type, perm)		\
> 	param_check_##type(name, &(value));				\
>@@ -160,6 +167,7 @@ struct kparam_array
>  * module_param_cb - general callback for a module/cmdline parameter
>  * @name: a valid C identifier which is the parameter name.
>  * @ops: the set & get operations for this parameter.
>+ * @arg: args for @ops
>  * @perm: visibility in sysfs.
>  *
>  * The ops can have NULL set or get functions.
>@@ -171,36 +179,96 @@ struct kparam_array
> 	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, -1,    \
> 			    KERNEL_PARAM_FL_UNSAFE)
>
>+#define __level_param_cb(name, ops, arg, perm, level)			\
>+	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, level, 0)
> /**
>- * <level>_param_cb - general callback for a module/cmdline parameter
>- *                    to be evaluated before certain initcall level
>+ * core_param_cb - general callback for a module/cmdline parameter
>+ *                 to be evaluated before core initcall level
>  * @name: a valid C identifier which is the parameter name.
>  * @ops: the set & get operations for this parameter.
>+ * @arg: args for @ops
>  * @perm: visibility in sysfs.
>  *
>  * The ops can have NULL set or get functions.
>  */
>-#define __level_param_cb(name, ops, arg, perm, level)			\
>-	__module_param_call(MODULE_PARAM_PREFIX, name, ops, arg, perm, level, 0)
>-
> #define core_param_cb(name, ops, arg, perm)		\
> 	__level_param_cb(name, ops, arg, perm, 1)
>
>+/**
>+ * postcore_param_cb - general callback for a module/cmdline parameter
>+ *                     to be evaluated before postcore initcall level
>+ * @name: a valid C identifier which is the parameter name.
>+ * @ops: the set & get operations for this parameter.
>+ * @arg: args for @ops
>+ * @perm: visibility in sysfs.
>+ *
>+ * The ops can have NULL set or get functions.
>+ */
> #define postcore_param_cb(name, ops, arg, perm)		\
> 	__level_param_cb(name, ops, arg, perm, 2)
>
>+/**
>+ * arch_param_cb - general callback for a module/cmdline parameter
>+ *                 to be evaluated before arch initcall level
>+ * @name: a valid C identifier which is the parameter name.
>+ * @ops: the set & get operations for this parameter.
>+ * @arg: args for @ops
>+ * @perm: visibility in sysfs.
>+ *
>+ * The ops can have NULL set or get functions.
>+ */
> #define arch_param_cb(name, ops, arg, perm)		\
> 	__level_param_cb(name, ops, arg, perm, 3)
>
>+/**
>+ * subsys_param_cb - general callback for a module/cmdline parameter
>+ *                   to be evaluated before subsys initcall level
>+ * @name: a valid C identifier which is the parameter name.
>+ * @ops: the set & get operations for this parameter.
>+ * @arg: args for @ops
>+ * @perm: visibility in sysfs.
>+ *
>+ * The ops can have NULL set or get functions.
>+ */
> #define subsys_param_cb(name, ops, arg, perm)		\
> 	__level_param_cb(name, ops, arg, perm, 4)
>
>+/**
>+ * fs_param_cb - general callback for a module/cmdline parameter
>+ *               to be evaluated before fs initcall level
>+ * @name: a valid C identifier which is the parameter name.
>+ * @ops: the set & get operations for this parameter.
>+ * @arg: args for @ops
>+ * @perm: visibility in sysfs.
>+ *
>+ * The ops can have NULL set or get functions.
>+ */
> #define fs_param_cb(name, ops, arg, perm)		\
> 	__level_param_cb(name, ops, arg, perm, 5)
>
>+/**
>+ * device_param_cb - general callback for a module/cmdline parameter
>+ *                   to be evaluated before device initcall level
>+ * @name: a valid C identifier which is the parameter name.
>+ * @ops: the set & get operations for this parameter.
>+ * @arg: args for @ops
>+ * @perm: visibility in sysfs.
>+ *
>+ * The ops can have NULL set or get functions.
>+ */
> #define device_param_cb(name, ops, arg, perm)		\
> 	__level_param_cb(name, ops, arg, perm, 6)
>
>+/**
>+ * late_param_cb - general callback for a module/cmdline parameter
>+ *                 to be evaluated before late initcall level
>+ * @name: a valid C identifier which is the parameter name.
>+ * @ops: the set & get operations for this parameter.
>+ * @arg: args for @ops
>+ * @perm: visibility in sysfs.
>+ *
>+ * The ops can have NULL set or get functions.
>+ */
> #define late_param_cb(name, ops, arg, perm)		\
> 	__level_param_cb(name, ops, arg, perm, 7)
>
>@@ -263,6 +331,10 @@ static inline void kernel_param_unlock(struct module *mod)
>
> /**
>  * core_param_unsafe - same as core_param but taints kernel
>+ * @name: the name of the cmdline and sysfs parameter (often the same as var)
>+ * @var: the variable
>+ * @type: the type of the parameter
>+ * @perm: visibility in sysfs
>  */
> #define core_param_unsafe(name, var, type, perm)		\
> 	param_check_##type(name, &(var));				\
>-- 
>2.7.4
>

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2019-12-04 19:31 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-12-02  9:01 [PATCH v3] moduleparam: fix kerneldoc Fabien Dessenne
2019-12-02 22:04 ` Randy Dunlap
2019-12-04 19:31 ` Jessica Yu

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.