Merge branch 'pm-sleep'
authorRafael J. Wysocki <rafael.j.wysocki@intel.com>
Mon, 13 Nov 2017 00:41:20 +0000 (01:41 +0100)
committerRafael J. Wysocki <rafael.j.wysocki@intel.com>
Mon, 13 Nov 2017 00:41:20 +0000 (01:41 +0100)
* pm-sleep:
  freezer: Fix typo in freezable_schedule_timeout() comment
  PM / s2idle: Clear the events_check_enabled flag
  PM / sleep: Remove pm_complete_with_resume_check()
  PM: ARM: locomo: Drop suspend and resume bus type callbacks
  PM: Use a more common logging style
  PM: Document rules on using pm_runtime_resume() in system suspend callbacks

1  2 
Documentation/driver-api/pm/devices.rst
include/linux/freezer.h

index b8f1e3bdb743068d09da62fe04f787bff6804685,4a18ef9997c0d00ca5ef96ac70a2e66be4acf360..b5d7d4948e933b0be10ad6e66bd68b6d6f023dc7
@@@ -274,7 -274,7 +274,7 @@@ sleep states and the hibernation state 
  executing callbacks for every device before the next phase begins.  Not all
  buses or classes support all these callbacks and not all drivers use all the
  callbacks.  The various phases always run after tasks have been frozen and
 -before they are unfrozen.  Furthermore, the ``*_noirq phases`` run at a time
 +before they are unfrozen.  Furthermore, the ``*_noirq`` phases run at a time
  when IRQ handlers have been disabled (except for those marked with the
  IRQF_NO_SUSPEND flag).
  
@@@ -328,7 -328,10 +328,10 @@@ the phases are: ``prepare``, ``suspend`
        After the ``->prepare`` callback method returns, no new children may be
        registered below the device.  The method may also prepare the device or
        driver in some way for the upcoming system power transition, but it
-       should not put the device into a low-power state.
+       should not put the device into a low-power state.  Moreover, if the
+       device supports runtime power management, the ``->prepare`` callback
+       method must not update its state in case it is necessary to resume it
+       from runtime suspend later on.
  
        For devices supporting runtime power management, the return value of the
        prepare callback can be used to indicate to the PM core that it may
        the appropriate low-power state, depending on the bus type the device is
        on, and they may enable wakeup events.
  
+       However, for devices supporting runtime power management, the
+       ``->suspend`` methods provided by subsystems (bus types and PM domains
+       in particular) must follow an additional rule regarding what can be done
+       to the devices before their drivers' ``->suspend`` methods are called.
+       Namely, they can only resume the devices from runtime suspend by
+       calling :c:func:`pm_runtime_resume` for them, if that is necessary, and
+       they must not update the state of the devices in any other way at that
+       time (in case the drivers need to resume the devices from runtime
+       suspend in their ``->suspend`` methods).
      3.        For a number of devices it is convenient to split suspend into the
        "quiesce device" and "save device state" phases, in which cases
        ``suspend_late`` is meant to do the latter.  It is always executed after
@@@ -729,6 -742,16 +742,16 @@@ state temporarily, for example so that 
  disabled.  This all depends on the hardware and the design of the subsystem and
  device driver in question.
  
+ If it is necessary to resume a device from runtime suspend during a system-wide
+ transition into a sleep state, that can be done by calling
+ :c:func:`pm_runtime_resume` for it from the ``->suspend`` callback (or its
+ couterpart for transitions related to hibernation) of either the device's driver
+ or a subsystem responsible for it (for example, a bus type or a PM domain).
+ That is guaranteed to work by the requirement that subsystems must not change
+ the state of devices (possibly except for resuming them from runtime suspend)
+ from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before*
+ invoking device drivers' ``->suspend`` callbacks (or equivalent).
  During system-wide resume from a sleep state it's easiest to put devices into
  the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`.
  Refer to that document for more information regarding this particular issue as
diff --combined include/linux/freezer.h
index 3995df1d068f66b6c1574312b8740d35e2ad0de5,5b2cf48b2a7c5b6c84f0f596dd04fafa14c8ca48..21f5aa0b217f3c0ce3c04a7d459f7a2e44e93076
@@@ -1,4 -1,3 +1,4 @@@
 +/* SPDX-License-Identifier: GPL-2.0 */
  /* Freezer declarations */
  
  #ifndef FREEZER_H_INCLUDED
@@@ -182,7 -181,7 +182,7 @@@ static inline void freezable_schedule_u
  }
  
  /*
-  * Like freezable_schedule_timeout(), but should not block the freezer.  Do not
+  * Like schedule_timeout(), but should not block the freezer.  Do not
   * call this with locks held.
   */
  static inline long freezable_schedule_timeout(long timeout)