[PATCH 1/1] media: Documentation: Use right function to test device power state

[PATCH 1/1] media: Documentation: Use right function to test device power state

[Sakari Ailus]

Tell driver authors to use pm_runtime_get_if_active() instead of
pm_runtime_get_if_in_use() to check the device's power state in the s_ctrl
callback. pm_runtime_get_if_active() is the right function to use here
since it returns non-zero if the device is powered on rather than its
PM runtime usage_count is non-zero.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 Documentation/driver-api/media/camera-sensor.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
index 94bd1dae82d5..c8552f70f496 100644
--- a/Documentation/driver-api/media/camera-sensor.rst
+++ b/Documentation/driver-api/media/camera-sensor.rst
@@ -114,7 +114,7 @@ of the device. This is because the power state of the device is only changed
 after the power state transition has taken place. The ``s_ctrl`` callback can be
 used to obtain device's power state after the power state transition:
 
-.. c:function:: int pm_runtime_get_if_in_use(struct device *dev);
+.. c:function:: int pm_runtime_get_if_active(struct device *dev);
 
 The function returns a non-zero value if it succeeded getting the power count or
 runtime PM was disabled, in either of which cases the driver may proceed to
-- 
2.47.3

Re: [PATCH 1/1] media: Documentation: Use right function to test device power state

[Laurent Pinchart]

Hi Sakari,

Thank you for the patch.

On Thu, Mar 26, 2026 at 12:46:11PM +0200, Sakari Ailus wrote:
> Tell driver authors to use pm_runtime_get_if_active() instead of
> pm_runtime_get_if_in_use() to check the device's power state in the s_ctrl
> callback. pm_runtime_get_if_active() is the right function to use here
> since it returns non-zero if the device is powered on rather than its
> PM runtime usage_count is non-zero.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
>  Documentation/driver-api/media/camera-sensor.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
> index 94bd1dae82d5..c8552f70f496 100644
> --- a/Documentation/driver-api/media/camera-sensor.rst
> +++ b/Documentation/driver-api/media/camera-sensor.rst
> @@ -114,7 +114,7 @@ of the device. This is because the power state of the device is only changed
>  after the power state transition has taken place. The ``s_ctrl`` callback can be
>  used to obtain device's power state after the power state transition:
>  
> -.. c:function:: int pm_runtime_get_if_in_use(struct device *dev);
> +.. c:function:: int pm_runtime_get_if_active(struct device *dev);

This looks fine, but I think we should also mass-convert drivers. There
are more drivers using pm_runtime_get_if_in_use() than
pm_runtime_get_if_active(), so we'll keep seeing new code using the
former due to cargo cult.

For this patch,

Reviewed-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>

Should I submit a series to mass-convert drivers, or will you do it ?

>  
>  The function returns a non-zero value if it succeeded getting the power count or
>  runtime PM was disabled, in either of which cases the driver may proceed to

-- 
Regards,

Laurent Pinchart

Re: [PATCH 1/1] media: Documentation: Use right function to test device power state

[Sakari Ailus]

Hi Laurent,

On Tue, May 05, 2026 at 04:02:58PM +0300, Laurent Pinchart wrote:
> Hi Sakari,
> 
> Thank you for the patch.
> 
> On Thu, Mar 26, 2026 at 12:46:11PM +0200, Sakari Ailus wrote:
> > Tell driver authors to use pm_runtime_get_if_active() instead of
> > pm_runtime_get_if_in_use() to check the device's power state in the s_ctrl
> > callback. pm_runtime_get_if_active() is the right function to use here
> > since it returns non-zero if the device is powered on rather than its
> > PM runtime usage_count is non-zero.
> > 
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> > ---
> >  Documentation/driver-api/media/camera-sensor.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
> > index 94bd1dae82d5..c8552f70f496 100644
> > --- a/Documentation/driver-api/media/camera-sensor.rst
> > +++ b/Documentation/driver-api/media/camera-sensor.rst
> > @@ -114,7 +114,7 @@ of the device. This is because the power state of the device is only changed
> >  after the power state transition has taken place. The ``s_ctrl`` callback can be
> >  used to obtain device's power state after the power state transition:
> >  
> > -.. c:function:: int pm_runtime_get_if_in_use(struct device *dev);
> > +.. c:function:: int pm_runtime_get_if_active(struct device *dev);
> 
> This looks fine, but I think we should also mass-convert drivers. There
> are more drivers using pm_runtime_get_if_in_use() than
> pm_runtime_get_if_active(), so we'll keep seeing new code using the
> former due to cargo cult.
> 
> For this patch,
> 
> Reviewed-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>

Thank you.

> 
> Should I submit a series to mass-convert drivers, or will you do it ?

I was planning to, yes.

It seems what happened was that the APIs and the usage of the APIs in
sensor drivers changed but we forgot to update the documentation. Oh well.

I'm a bit surprised there have been no complaints but I guess in practice
you'd need quite a bit of bad luck to hit this. Relatively few drivers use
autosuspend, too.

-- 
Regards,

Sakari Ailus