diff mbox

[2/2] ARM: cpuidle: Document the code

Message ID 1427190842-30675-2-git-send-email-daniel.lezcano@linaro.org (mailing list archive)
State Not Applicable, archived
Headers show

Commit Message

Daniel Lezcano March 24, 2015, 9:54 a.m. UTC
Add kernel-doc format documentation in the code.

Signed-off-by: Daniel Lezcano <daniel.lezcano@linaro.org>
---
 arch/arm/kernel/cpuidle.c | 58 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

Comments

Lorenzo Pieralisi March 24, 2015, 6:51 p.m. UTC | #1
On Tue, Mar 24, 2015 at 09:54:02AM +0000, Daniel Lezcano wrote:
> Add kernel-doc format documentation in the code.
> 
> Signed-off-by: Daniel Lezcano <daniel.lezcano@linaro.org>
> ---
>  arch/arm/kernel/cpuidle.c | 58 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 58 insertions(+)
> 
> diff --git a/arch/arm/kernel/cpuidle.c b/arch/arm/kernel/cpuidle.c
> index 2b0dae3..9219613 100644
> --- a/arch/arm/kernel/cpuidle.c
> +++ b/arch/arm/kernel/cpuidle.c
> @@ -21,6 +21,17 @@ static const struct of_cpuidle_method __cpuidle_method_of_table_sentinel
>  
>  static struct cpuidle_ops cpuidle_ops[NR_CPUS];
>  
> +/*

You miss a star here to comply with kernel-doc (comment valid throughout
the patch for all functions).

> + * arm_cpuidle_simple_enter() - a wrapper to cpu_do_idle()
> + * @dev: not used
> + * @drv: not used
> + * @index: not used
> + *
> + * A trivial wrapper to allow the cpu_do_idle function to be assigned as a
> + * cpuidle callback by matching the function signature.
> + *
> + * Returns the index passed as parameter
> + */
>  int arm_cpuidle_simple_enter(struct cpuidle_device *dev,
>  		struct cpuidle_driver *drv, int index)
>  {
> @@ -29,6 +40,16 @@ int arm_cpuidle_simple_enter(struct cpuidle_device *dev,
>  	return index;
>  }
>  
> +/*
> + * arm_cpuidle_suspend() - function to enter low power idle states
> + * @index: an integer used as an identifier for the low level PM callbacks
> + *
> + * This function calls the underlying arch specific low level PM code as
> + * registered at the init time.
> + *
> + * Returns -EOPNOTSUPP if no suspend callback is defined, the result of the
> + * callback otherwise.
> + */
>  int arm_cpuidle_suspend(int index)
>  {
>  	int ret = -EOPNOTSUPP;
> @@ -40,6 +61,15 @@ int arm_cpuidle_suspend(int index)
>  	return ret;
>  }
>  
> +/*
> + * arm_cpuidle_get_ops() - find a registered cpuidle_ops by name
> + * @method: the method name
> + *
> + * Search in the __cpuidle_method_of_table array the cpuidle ops matching the
> + * method name.
> + *
> + * Returns a struct cpuidle_ops pointer, NULL if not found.
> + */
>  static struct cpuidle_ops *__init arm_cpuidle_get_ops(const char *method)
>  {
>  	struct of_cpuidle_method *m = __cpuidle_method_of_table;
> @@ -51,6 +81,19 @@ static struct cpuidle_ops *__init arm_cpuidle_get_ops(const char *method)
>  	return NULL;
>  }
>  
> +/*
> + * arm_cpuidle_read_ops() - Initialize the cpuidle ops with the device tree
> + * @dn: a struct device node corresponding to a cpu node

It is a pointer, not a struct.

> + * @cpu: the cpu identifier
> + *
> + * Get the method name defined in the 'enabled-method' property, retrieve the
> + * associated cpuidle_ops and do a struct copy. This copy is needed because all
> + * cpuidle_ops are tagged __initdata and will be unloaded after the init
> + * process.
> + *
> + * Return 0 on sucess, -ENOENT if no enabled-method is defined, -EOPNOTSUPP if
> + * no cpuidle_ops is registered for the enabled-method.
> + */
>  static int __init arm_cpuidle_read_ops(struct device_node *dn, int cpu)
>  {
>  	const char *enable_method;
> @@ -75,6 +118,21 @@ static int __init arm_cpuidle_read_ops(struct device_node *dn, int cpu)
>  	return 0;
>  }
>  
> +/*
> + * arm_cpuidle_init() - Initialize cpuidle_ops for a specific cpu
> + * @cpu: the cpu to be initialized
> + *
> + * Initialize the cpuidle ops with the device for the cpu and then call
> + * the cpu's idle initialization callback. This may fail if the underlying HW
> + * is not operational.
> + *
> + * Returns:
> + *  0 on success,
> + *  -ENODEV if it fails to find the cpu node in the device tree,
> + *  -EOPNOTSUPP if it does not find a registered cpuidle_ops for this cpu,
> + *  -ENOENT if it fails to find a enabled-method property,

Ultra-nit: "an enabled-method"

> + *  -ENXIO if the HW reports a failure or a misconfiguration

-ENOMEM is missing.

Apart from these ultraminor changes (and thanks for putting it
together):

Acked-by: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>

> + */
>  int __init arm_cpuidle_init(int cpu)
>  {
>  	struct device_node *cpu_node = of_cpu_device_node_get(cpu);
> -- 
> 1.9.1
> 
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-pm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lorenzo Pieralisi March 24, 2015, 7:04 p.m. UTC | #2
On Tue, Mar 24, 2015 at 06:51:44PM +0000, Lorenzo Pieralisi wrote:
> On Tue, Mar 24, 2015 at 09:54:02AM +0000, Daniel Lezcano wrote:

[...]

> > +/*
> > + * arm_cpuidle_init() - Initialize cpuidle_ops for a specific cpu
> > + * @cpu: the cpu to be initialized
> > + *
> > + * Initialize the cpuidle ops with the device for the cpu and then call
> > + * the cpu's idle initialization callback. This may fail if the underlying HW
> > + * is not operational.
> > + *
> > + * Returns:
> > + *  0 on success,
> > + *  -ENODEV if it fails to find the cpu node in the device tree,
> > + *  -EOPNOTSUPP if it does not find a registered cpuidle_ops for this cpu,
> > + *  -ENOENT if it fails to find a enabled-method property,
> 
> Ultra-nit: "an enabled-method"

Bah, I cannot see the wood for the trees anymore. "an enable-method".

Lorenzo
--
To unsubscribe from this list: send the line "unsubscribe linux-pm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Daniel Lezcano March 25, 2015, 7:03 a.m. UTC | #3
On 03/24/2015 07:51 PM, Lorenzo Pieralisi wrote:
> On Tue, Mar 24, 2015 at 09:54:02AM +0000, Daniel Lezcano wrote:
>> Add kernel-doc format documentation in the code.
>>
>> Signed-off-by: Daniel Lezcano <daniel.lezcano@linaro.org>
>> ---

[ ... ]

>> + * Returns:
>> + *  0 on success,
>> + *  -ENODEV if it fails to find the cpu node in the device tree,
>> + *  -EOPNOTSUPP if it does not find a registered cpuidle_ops for this cpu,
>> + *  -ENOENT if it fails to find a enabled-method property,
>
> Ultra-nit: "an enabled-method"
>
>> + *  -ENXIO if the HW reports a failure or a misconfiguration
>
> -ENOMEM is missing.
>
> Apart from these ultraminor changes (and thanks for putting it
> together):
>
> Acked-by: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
>

Thanks for review Lorenzo. I fixed the comment and pushed in my tree for 
4.1.

  -- Daniel
diff mbox

Patch

diff --git a/arch/arm/kernel/cpuidle.c b/arch/arm/kernel/cpuidle.c
index 2b0dae3..9219613 100644
--- a/arch/arm/kernel/cpuidle.c
+++ b/arch/arm/kernel/cpuidle.c
@@ -21,6 +21,17 @@  static const struct of_cpuidle_method __cpuidle_method_of_table_sentinel
 
 static struct cpuidle_ops cpuidle_ops[NR_CPUS];
 
+/*
+ * arm_cpuidle_simple_enter() - a wrapper to cpu_do_idle()
+ * @dev: not used
+ * @drv: not used
+ * @index: not used
+ *
+ * A trivial wrapper to allow the cpu_do_idle function to be assigned as a
+ * cpuidle callback by matching the function signature.
+ *
+ * Returns the index passed as parameter
+ */
 int arm_cpuidle_simple_enter(struct cpuidle_device *dev,
 		struct cpuidle_driver *drv, int index)
 {
@@ -29,6 +40,16 @@  int arm_cpuidle_simple_enter(struct cpuidle_device *dev,
 	return index;
 }
 
+/*
+ * arm_cpuidle_suspend() - function to enter low power idle states
+ * @index: an integer used as an identifier for the low level PM callbacks
+ *
+ * This function calls the underlying arch specific low level PM code as
+ * registered at the init time.
+ *
+ * Returns -EOPNOTSUPP if no suspend callback is defined, the result of the
+ * callback otherwise.
+ */
 int arm_cpuidle_suspend(int index)
 {
 	int ret = -EOPNOTSUPP;
@@ -40,6 +61,15 @@  int arm_cpuidle_suspend(int index)
 	return ret;
 }
 
+/*
+ * arm_cpuidle_get_ops() - find a registered cpuidle_ops by name
+ * @method: the method name
+ *
+ * Search in the __cpuidle_method_of_table array the cpuidle ops matching the
+ * method name.
+ *
+ * Returns a struct cpuidle_ops pointer, NULL if not found.
+ */
 static struct cpuidle_ops *__init arm_cpuidle_get_ops(const char *method)
 {
 	struct of_cpuidle_method *m = __cpuidle_method_of_table;
@@ -51,6 +81,19 @@  static struct cpuidle_ops *__init arm_cpuidle_get_ops(const char *method)
 	return NULL;
 }
 
+/*
+ * arm_cpuidle_read_ops() - Initialize the cpuidle ops with the device tree
+ * @dn: a struct device node corresponding to a cpu node
+ * @cpu: the cpu identifier
+ *
+ * Get the method name defined in the 'enabled-method' property, retrieve the
+ * associated cpuidle_ops and do a struct copy. This copy is needed because all
+ * cpuidle_ops are tagged __initdata and will be unloaded after the init
+ * process.
+ *
+ * Return 0 on sucess, -ENOENT if no enabled-method is defined, -EOPNOTSUPP if
+ * no cpuidle_ops is registered for the enabled-method.
+ */
 static int __init arm_cpuidle_read_ops(struct device_node *dn, int cpu)
 {
 	const char *enable_method;
@@ -75,6 +118,21 @@  static int __init arm_cpuidle_read_ops(struct device_node *dn, int cpu)
 	return 0;
 }
 
+/*
+ * arm_cpuidle_init() - Initialize cpuidle_ops for a specific cpu
+ * @cpu: the cpu to be initialized
+ *
+ * Initialize the cpuidle ops with the device for the cpu and then call
+ * the cpu's idle initialization callback. This may fail if the underlying HW
+ * is not operational.
+ *
+ * Returns:
+ *  0 on success,
+ *  -ENODEV if it fails to find the cpu node in the device tree,
+ *  -EOPNOTSUPP if it does not find a registered cpuidle_ops for this cpu,
+ *  -ENOENT if it fails to find a enabled-method property,
+ *  -ENXIO if the HW reports a failure or a misconfiguration
+ */
 int __init arm_cpuidle_init(int cpu)
 {
 	struct device_node *cpu_node = of_cpu_device_node_get(cpu);