Re: [PATCH v3 1/6] PM / core: Add LEAVE_SUSPENDED driver flag

From: Rafael J. Wysocki <redacted>

Define and document a new driver flag, DPM_FLAG_LEAVE_SUSPENDED, to
instruct the PM core and middle-layer (bus type, PM domain, etc.)
code that it is desirable to leave the device in runtime suspend
after system-wide transitions to the working state (for example,
the device may be slow to resume and it may be better to avoid
resuming it right away).

Generally, the middle-layer code involved in the handling of the
device is expected to indicate to the PM core whether or not the
device may be left in suspend with the help of the device's
power.may_skip_resume status bit.  That has to happen in the "noirq"
phase of the preceding system suspend (or analogous) transition.
The middle layer is then responsible for handling the device as
appropriate in its "noirq" resume callback which is executed
regardless of whether or not the device may be left suspended, but
the other resume callbacks (except for ->complete) will be skipped
automatically by the core if the device really can be left in
suspend.

The additional power.must_resume status bit introduced for the
implementation of this mechanisn is used internally by the PM core
to track the requirement to resume the device (which may depend on
its children etc).

Signed-off-by: Rafael J. Wysocki <redacted>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
---

v2 -> v3: Take dev->power.usage_count when updating power.must_resume in
          __device_suspend_noirq().

---
 Documentation/driver-api/pm/devices.rst |   24 ++++++++++-
 drivers/base/power/main.c               |   66 +++++++++++++++++++++++++++++---
 drivers/base/power/runtime.c            |    9 ++--
 include/linux/pm.h                      |   14 +++++-
 include/linux/pm_runtime.h              |    9 ++--
 5 files changed, 104 insertions(+), 18 deletions(-)

Index: linux-pm/include/linux/pm.h
===================================================================

--- linux-pm.orig/include/linux/pm.h
+++ linux-pm/include/linux/pm.h

@@ -559,6 +559,7 @@ struct pm_subsys_data {
  * NEVER_SKIP: Do not skip system suspend/resume callbacks for the device.
  * SMART_PREPARE: Check the return value of the driver's ->prepare callback.
  * SMART_SUSPEND: No need to resume the device from runtime suspend.
+ * LEAVE_SUSPENDED: Avoid resuming the device during system resume if possible.
  *
  * Setting SMART_PREPARE instructs bus types and PM domains which may want
  * system suspend/resume callbacks to be skipped for the device to return 0 from

@@ -572,10 +573,14 @@ struct pm_subsys_data {
  * necessary from the driver's perspective.  It also may cause them to skip
  * invocations of the ->suspend_late and ->suspend_noirq callbacks provided by
  * the driver if they decide to leave the device in runtime suspend.
+ *
+ * Setting LEAVE_SUSPENDED informs the PM core and middle-layer code that the
+ * driver prefers the device to be left in runtime suspend after system resume.
  */

 /**
  * __device_suspend_noirq - Execute a "noirq suspend" callback for given device.
  * @dev: Device to handle.

@@ -1127,10 +1161,28 @@ static int __device_suspend_noirq(struct
        }

        error = dpm_run_callback(callback, dev, state, info);
-       if (!error)
-               dev->power.is_noirq_suspended = true;
-       else
+       if (error) {
                async_error = error;
+               goto Complete;
+       }
+
+       dev->power.is_noirq_suspended = true;
+
+       if (dev_pm_test_driver_flags(dev, DPM_FLAG_LEAVE_SUSPENDED)) {
+               /*
+                * The only safe strategy here is to require that if the device
+                * may not be left in suspend, resume callbacks must be invoked
+                * for it.
+                */
+               dev->power.must_resume = dev->power.must_resume ||
+                                       !dev->power.may_skip_resume ||
+                                       atomic_read(&dev->power.usage_count);

+       } else {
+               dev->power.must_resume = true;
+       }
+
+       if (dev->power.must_resume)
+               dpm_superior_set_must_resume(dev);

 Complete:
        complete_all(&dev->power.completion);

@@ -1487,6 +1539,9 @@ static int __device_suspend(struct devic
                dev->power.direct_complete = false;
        }

+       dev->power.may_skip_resume = false;
+       dev->power.must_resume = false;
+