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: Windows password security audit tool. GUI, reports in PDF.

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

Message-ID: <CAJZ5v0hRi3DZ69b1b=xes4qz2keq_aGDzX5kKQsR_rkwuFgk0w@mail.gmail.com>
Date:   Mon, 3 Aug 2020 13:36:52 +0200
From:   "Rafael J. Wysocki" <rafael@...nel.org>
To:     Sakari Ailus <sakari.ailus@...ux.intel.com>
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 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?

> 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!