linux-kernel - Re: [PATCH] PM: runtime: Add kerneldoc comments to multiple helpers

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 for Android: free password hash cracker in your pocket

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

Date:   Tue, 4 Aug 2020 02:05:36 +0300
From:   Sakari Ailus <sakari.ailus@...ux.intel.com>
To:     "Rafael J. Wysocki" <rafael@...nel.org>
Cc:     "Rafael J. Wysocki" <rjw@...ysocki.net>,
        Linux PM <linux-pm@...r.kernel.org>,
        LKML <linux-kernel@...r.kernel.org>,
        Alan Stern <stern@...land.harvard.edu>,
        Ulf Hansson <ulf.hansson@...aro.org>,
        Wolfram Sang <wsa@...nel.org>
Subject: Re: [PATCH] PM: runtime: Add kerneldoc comments to multiple helpers

Hi Rafael,

On Mon, Aug 03, 2020 at 01:36:52PM +0200, Rafael J. Wysocki wrote:
> Hi Sakari,
> 
> On Mon, Aug 3, 2020 at 10:53 AM Sakari Ailus
> <sakari.ailus@...ux.intel.com> wrote:
> >
> > Hi Rafael,
> >
> > Thanks for the patch.
> >
> > On Fri, Jul 31, 2020 at 07:03:26PM +0200, Rafael J. Wysocki wrote:
> > > From: Rafael J. Wysocki <rafael.j.wysocki@...el.com>
> > >
> > > Add kerneldoc comments to multiple PM-runtime helper functions
> > > defined as static inline wrappers around lower-level routines to
> > > provide quick reference decumentation of their behavior.
> >
> > > Some of them are similar to each other with subtle differences only
> > > and the behavior of some of them may appear as counter-intuitive, so
> > > clarify all that to avoid confusion.
> > >
> > > Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@...el.com>
> > > ---
> > >  include/linux/pm_runtime.h |  246 +++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 246 insertions(+)
> > >
> > > Index: linux-pm/include/linux/pm_runtime.h
> > > ===================================================================
> > > --- linux-pm.orig/include/linux/pm_runtime.h
> > > +++ linux-pm/include/linux/pm_runtime.h
> > > @@ -60,58 +60,151 @@ extern void pm_runtime_put_suppliers(str
> > >  extern void pm_runtime_new_link(struct device *dev);
> > >  extern void pm_runtime_drop_link(struct device *dev);
> > >
> > > +/**
> > > + * pm_runtime_get_if_in_use - Conditionally bump up runtime PM usage counter.
> > > + * @dev: Target device.
> > > + *
> > > + * Increment the runtime PM usage counter of @dev if its runtime PM status is
> > > + * %RPM_ACTIVE and its runtime PM usage counter is greater than 0.
> >
> > The implementation of the non-runtime PM variants (used when CONFIG_PM is
> > disabled) isn't here but I think it'd be nice if their behaviour was also
> > documented here. pm_runtime_get_if_in_use() returns -EINVAL if CONFIG_PM is
> > disabled, for instance.
> 
> These kerneldoc comments cover the CONFIG_PM case only.  The behavior
> for !CONFIG_PM needs to be figured out from the code, if it matters.
> 
> I'm not sure why it would matter for pm_runtime_get_if_in_use(), in particular?

Just as an example. It depends on the use case, but there have been bugs
related to these (e.g. commit 4d471563d87b2b83e73b8abffb9273950e6d2e36),
likely at least partly because it's extra manual work to figure out what a
given API function could return when it's not documented.

> 
> > pm_runtime_disable() is defined here but the documentation in corresponding
> > pm_runtime_enable() in drivers/base/power/runtime.c is rather terse. It'd
> > be nice to improve that now (or separately).
> 
> Yes, separately.

Thanks!

-- 
Regards,

Sakari Ailus