[PATCH 1/2] PM / Runtime: fix autosuspend documentation

[PATCH 1/2] PM / Runtime: fix autosuspend documentation

[Johan Hovold]

Update the autosuspend documentation which claimed that the autosuspend
delay is not taken into account when using the non-autosuspend helper
functions, something which is no longer true since commit d66e6db28df3
("PM / Runtime: Respect autosuspend when idle triggers suspend").

This specifically means that drivers must now disable autosuspend before
disabling runtime pm in probe error paths and remove callbacks if
pm_runtime_put_sync was being used to suspend the device before
returning. (If an idle callback can prevent suspend,
pm_runtime_put_sync_suspend must be used instead of pm_runtime_put_sync
as before.)

Also remove the claim that the autosuspend helpers behave "just like
the non-autosuspend counterparts", something which have never really
been true as some of the latter use idle notifications.

Signed-off-by: Johan Hovold <johan@kernel.org>
---
 Documentation/power/runtime_pm.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt
index 64546eb9a16a..56a13b865927 100644
--- a/Documentation/power/runtime_pm.txt
+++ b/Documentation/power/runtime_pm.txt
@@ -836,9 +836,8 @@ of the non-autosuspend counterparts:
 	Instead of: pm_runtime_put_sync   use: pm_runtime_put_sync_autosuspend.
 
 Drivers may also continue to use the non-autosuspend helper functions; they
-will behave normally, not taking the autosuspend delay into account.
-Similarly, if the power.use_autosuspend field isn't set then the autosuspend
-helper functions will behave just like the non-autosuspend counterparts.
+will behave normally, which means sometimes taking the autosuspend delay into
+account (see pm_runtime_idle).
 
 Under some circumstances a driver or subsystem may want to prevent a device
 from autosuspending immediately, even though the usage counter is zero and the
-- 
2.12.2

[PATCH 2/2] PM / Runtime: document autosuspend-helper side effects

[Johan Hovold]

Document the fact that the autosuspend delay and enable helpers may
change the power.usage_count and resume or suspend a device depending on
the values of power.autosuspend_delay and power.use_autosuspend.

Note that this means that a driver must disable autosuspend before
disabling runtime pm on probe errors and on driver unbind if the device
is to be suspended upon return (as a negative delay may otherwise keep
the device resumed).

Signed-off-by: Johan Hovold <johan@kernel.org>
---
 Documentation/power/runtime_pm.txt | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt
index 56a13b865927..ee69d7532172 100644
--- a/Documentation/power/runtime_pm.txt
+++ b/Documentation/power/runtime_pm.txt
@@ -478,15 +478,23 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
     - set the power.last_busy field to the current time
 
   void pm_runtime_use_autosuspend(struct device *dev);
-    - set the power.use_autosuspend flag, enabling autosuspend delays
+    - set the power.use_autosuspend flag, enabling autosuspend delays; call
+      pm_runtime_get_sync if the flag was previously cleared and
+      power.autosuspend_delay is negative
 
   void pm_runtime_dont_use_autosuspend(struct device *dev);
-    - clear the power.use_autosuspend flag, disabling autosuspend delays
+    - clear the power.use_autosuspend flag, disabling autosuspend delays;
+      decrement the device's usage counter if the flag was previously set and
+      power.autosuspend_delay is negative; call pm_runtime_idle
 
   void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);
     - set the power.autosuspend_delay value to 'delay' (expressed in
       milliseconds); if 'delay' is negative then runtime suspends are
-      prevented
+      prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be
+      called or the device's usage counter may be decremented and
+      pm_runtime_idle called depending on if power.autosuspend_delay is
+      changed to or from a negative value; if power.use_autosuspend is clear,
+      pm_runtime_idle is called
 
   unsigned long pm_runtime_autosuspend_expiration(struct device *dev);
     - calculate the time when the current autosuspend delay period will expire,
-- 
2.12.2

Re: [PATCH 1/2] PM / Runtime: fix autosuspend documentation

[Tony Lindgren]

* Johan Hovold <johan@kernel.org> [170410 04:41]:
> Update the autosuspend documentation which claimed that the autosuspend
> delay is not taken into account when using the non-autosuspend helper
> functions, something which is no longer true since commit d66e6db28df3
> ("PM / Runtime: Respect autosuspend when idle triggers suspend").
> 
> This specifically means that drivers must now disable autosuspend before
> disabling runtime pm in probe error paths and remove callbacks if
> pm_runtime_put_sync was being used to suspend the device before
> returning. (If an idle callback can prevent suspend,
> pm_runtime_put_sync_suspend must be used instead of pm_runtime_put_sync
> as before.)
> 
> Also remove the claim that the autosuspend helpers behave "just like
> the non-autosuspend counterparts", something which have never really
> been true as some of the latter use idle notifications.
> 
> Signed-off-by: Johan Hovold <johan@kernel.org>

Acked-by: Tony Lindgren <tony@atomide.com>

Re: [PATCH 2/2] PM / Runtime: document autosuspend-helper side effects

[Tony Lindgren]

* Johan Hovold <johan@kernel.org> [170410 04:41]:
> Document the fact that the autosuspend delay and enable helpers may
> change the power.usage_count and resume or suspend a device depending on
> the values of power.autosuspend_delay and power.use_autosuspend.
> 
> Note that this means that a driver must disable autosuspend before
> disabling runtime pm on probe errors and on driver unbind if the device
> is to be suspended upon return (as a negative delay may otherwise keep
> the device resumed).
> 
> Signed-off-by: Johan Hovold <johan@kernel.org>

Acked-by: Tony Lindgren <tony@atomide.com>