linux-kernel - Re: [PATCH 03/13] cpufreq: cpufreq_governor: Demote store_sampling

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20200715064539.GS1398296@dell>
Date:   Wed, 15 Jul 2020 07:45:39 +0100
From:   Lee Jones <lee.jones@...aro.org>
To:     Viresh Kumar <viresh.kumar@...aro.org>
Cc:     rjw@...ysocki.net, linux-arm-kernel@...ts.infradead.org,
        linux-kernel@...r.kernel.org, linux-pm@...r.kernel.org,
        Venkatesh Pallipadi <venkatesh.pallipadi@...el.com>,
        Jun Nakajima <jun.nakajima@...el.com>,
        Alexander Clouter <alex@...riz.org.uk>
Subject: Re: [PATCH 03/13] cpufreq: cpufreq_governor: Demote
 store_sampling_rate() header to standard comment block

On Wed, 15 Jul 2020, Viresh Kumar wrote:

> On 14-07-20, 15:50, Lee Jones wrote:
> > There is no need for this to be denoted as kerneldoc.
> > 
> > Fixes the following W=1 kernel build warning(s):
> > 
> >  drivers/cpufreq/cpufreq_governor.c:46: warning: Function parameter or member 'attr_set' not described in 'store_sampling_rate'
> >  drivers/cpufreq/cpufreq_governor.c:46: warning: Function parameter or member 'buf' not described in 'store_sampling_rate'
> >  drivers/cpufreq/cpufreq_governor.c:46: warning: Function parameter or member 'count' not described in 'store_sampling_rate'
> > 
> > Cc: Venkatesh Pallipadi <venkatesh.pallipadi@...el.com>
> > Cc: Jun Nakajima <jun.nakajima@...el.com>
> > Cc: Alexander Clouter <alex@...riz.org.uk>
> > Signed-off-by: Lee Jones <lee.jones@...aro.org>
> > ---
> >  drivers/cpufreq/cpufreq_governor.c | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/drivers/cpufreq/cpufreq_governor.c b/drivers/cpufreq/cpufreq_governor.c
> > index f99ae45efaea7..63f7c219062b9 100644
> > --- a/drivers/cpufreq/cpufreq_governor.c
> > +++ b/drivers/cpufreq/cpufreq_governor.c
> > @@ -26,7 +26,7 @@ static DEFINE_PER_CPU(struct cpu_dbs_info, cpu_dbs);
> >  static DEFINE_MUTEX(gov_dbs_data_mutex);
> >  
> >  /* Common sysfs tunables */
> > -/**
> > +/*
> 
> This is an important routine with good documentation details already
> there, though internal to governors and so I would rather keep it.

It maybe documented, but it isn't kerneldoc, for 2 reasons; a) it
doesn't meet the standards required qualify as kerneldoc i.e. it's
missing descriptions for each of the function parameters, which is why
the kerneldoc checker is complaining about it and b) it is not
referenced by any *.rst file:

 git grep kernel-doc::.*cpufreq_governor.c
 /* no results */

So what is the justification for keeping it as kerneldoc?

> >   * store_sampling_rate - update sampling rate effective immediately if needed.
> >   *
> >   * If new rate is smaller than the old, simply updating
> 

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog