* [PATCH] cpufreq: Improve kerneldoc comments for cpufreq_cpu_get/put()
@ 2019-03-05 10:44 Rafael J. Wysocki
2019-03-06 3:17 ` Viresh Kumar
0 siblings, 1 reply; 2+ messages in thread
From: Rafael J. Wysocki @ 2019-03-05 10:44 UTC (permalink / raw)
To: Linux PM; +Cc: LKML, Viresh Kumar
From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Fix the formatting of the cpufreq_cpu_get() and cpufreq_cpu_put()
kerneldoc comments and rework them to be somewhat easier to follow.
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
---
drivers/cpufreq/cpufreq.c | 24 +++++++++---------------
1 file changed, 9 insertions(+), 15 deletions(-)
Index: linux-pm/drivers/cpufreq/cpufreq.c
===================================================================
--- linux-pm.orig/drivers/cpufreq/cpufreq.c
+++ linux-pm/drivers/cpufreq/cpufreq.c
@@ -201,17 +201,15 @@ unsigned int cpufreq_generic_get(unsigne
EXPORT_SYMBOL_GPL(cpufreq_generic_get);
/**
- * cpufreq_cpu_get: returns policy for a cpu and marks it busy.
+ * cpufreq_cpu_get - Return policy for a CPU and mark it as busy.
+ * @cpu: CPU to find the policy for.
*
- * @cpu: cpu to find policy for.
+ * Call cpufreq_cpu_get_raw() to obtain a cpufreq policy for @cpu and increment
+ * the kobject reference counter of that policy. Return a valid policy on
+ * success or NULL on failure.
*
- * This returns policy for 'cpu', returns NULL if it doesn't exist.
- * It also increments the kobject reference count to mark it busy and so would
- * require a corresponding call to cpufreq_cpu_put() to decrement it back.
- * If corresponding call cpufreq_cpu_put() isn't made, the policy wouldn't be
- * freed as that depends on the kobj count.
- *
- * Return: A valid policy on success, otherwise NULL on failure.
+ * The policy returned by this function has to be released with the help of
+ * cpufreq_cpu_put() to balance its kobject reference counter properly.
*/
struct cpufreq_policy *cpufreq_cpu_get(unsigned int cpu)
{
@@ -238,12 +236,8 @@ struct cpufreq_policy *cpufreq_cpu_get(u
EXPORT_SYMBOL_GPL(cpufreq_cpu_get);
/**
- * cpufreq_cpu_put: Decrements the usage count of a policy
- *
- * @policy: policy earlier returned by cpufreq_cpu_get().
- *
- * This decrements the kobject reference count incremented earlier by calling
- * cpufreq_cpu_get().
+ * cpufreq_cpu_put - Decrement kobject usage counter for cpufreq policy.
+ * @policy: cpufreq policy returned by cpufreq_cpu_get().
*/
void cpufreq_cpu_put(struct cpufreq_policy *policy)
{
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: [PATCH] cpufreq: Improve kerneldoc comments for cpufreq_cpu_get/put()
2019-03-05 10:44 [PATCH] cpufreq: Improve kerneldoc comments for cpufreq_cpu_get/put() Rafael J. Wysocki
@ 2019-03-06 3:17 ` Viresh Kumar
0 siblings, 0 replies; 2+ messages in thread
From: Viresh Kumar @ 2019-03-06 3:17 UTC (permalink / raw)
To: Rafael J. Wysocki; +Cc: Linux PM, LKML
On 05-03-19, 11:44, Rafael J. Wysocki wrote:
> From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
>
> Fix the formatting of the cpufreq_cpu_get() and cpufreq_cpu_put()
> kerneldoc comments and rework them to be somewhat easier to follow.
>
> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> ---
> drivers/cpufreq/cpufreq.c | 24 +++++++++---------------
> 1 file changed, 9 insertions(+), 15 deletions(-)
>
> Index: linux-pm/drivers/cpufreq/cpufreq.c
> ===================================================================
> --- linux-pm.orig/drivers/cpufreq/cpufreq.c
> +++ linux-pm/drivers/cpufreq/cpufreq.c
> @@ -201,17 +201,15 @@ unsigned int cpufreq_generic_get(unsigne
> EXPORT_SYMBOL_GPL(cpufreq_generic_get);
>
> /**
> - * cpufreq_cpu_get: returns policy for a cpu and marks it busy.
> + * cpufreq_cpu_get - Return policy for a CPU and mark it as busy.
> + * @cpu: CPU to find the policy for.
> *
> - * @cpu: cpu to find policy for.
> + * Call cpufreq_cpu_get_raw() to obtain a cpufreq policy for @cpu and increment
> + * the kobject reference counter of that policy. Return a valid policy on
> + * success or NULL on failure.
> *
> - * This returns policy for 'cpu', returns NULL if it doesn't exist.
> - * It also increments the kobject reference count to mark it busy and so would
> - * require a corresponding call to cpufreq_cpu_put() to decrement it back.
> - * If corresponding call cpufreq_cpu_put() isn't made, the policy wouldn't be
> - * freed as that depends on the kobj count.
> - *
> - * Return: A valid policy on success, otherwise NULL on failure.
> + * The policy returned by this function has to be released with the help of
> + * cpufreq_cpu_put() to balance its kobject reference counter properly.
> */
> struct cpufreq_policy *cpufreq_cpu_get(unsigned int cpu)
> {
> @@ -238,12 +236,8 @@ struct cpufreq_policy *cpufreq_cpu_get(u
> EXPORT_SYMBOL_GPL(cpufreq_cpu_get);
>
> /**
> - * cpufreq_cpu_put: Decrements the usage count of a policy
> - *
> - * @policy: policy earlier returned by cpufreq_cpu_get().
> - *
> - * This decrements the kobject reference count incremented earlier by calling
> - * cpufreq_cpu_get().
Shouldn't we always try to keep some description?
> + * cpufreq_cpu_put - Decrement kobject usage counter for cpufreq policy.
> + * @policy: cpufreq policy returned by cpufreq_cpu_get().
> */
> void cpufreq_cpu_put(struct cpufreq_policy *policy)
> {
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
--
viresh
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2019-03-06 3:17 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-03-05 10:44 [PATCH] cpufreq: Improve kerneldoc comments for cpufreq_cpu_get/put() Rafael J. Wysocki
2019-03-06 3:17 ` Viresh Kumar
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).