forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2024-01-31 f70575805708cabdedea7498aaa3f710fde4d920 
 kernel/Documentation/driver-api/pm/devices.rst
....@@ -1,20 +1,18 @@
1
-.. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>`
2
-.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
3
-.. |struct bus_type| replace:: :c:type:`struct bus_type <bus_type>`
4
-.. |struct device_type| replace:: :c:type:`struct device_type <device_type>`
5
-.. |struct class| replace:: :c:type:`struct class <class>`
6
-.. |struct wakeup_source| replace:: :c:type:`struct wakeup_source <wakeup_source>`
7
-.. |struct device| replace:: :c:type:`struct device <device>`
1
+.. SPDX-License-Identifier: GPL-2.0
2
+.. include:: <isonum.txt>
3
+
4
+.. _driverapi_pm_devices:
85 
96 ==============================
107 Device Power Management Basics
118 ==============================
129 
13
-::
10
+:Copyright: |copy| 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
11
+:Copyright: |copy| 2010 Alan Stern <stern@rowland.harvard.edu>
12
+:Copyright: |copy| 2016 Intel Corporation
1413 
15
- Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
16
- Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu>
17
- Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
14
+:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
15
+
1816 
1917 Most of the code in Linux is device drivers, so most of the Linux power
2018 management (PM) code is also driver-specific.  Most drivers will do very
....@@ -101,7 +99,7 @@
10199 
102100 Device power management operations, at the subsystem level as well as at the
103101 device driver level, are implemented by defining and populating objects of type
104
-|struct dev_pm_ops| defined in :file:`include/linux/pm.h`.  The roles of the
102
+struct dev_pm_ops defined in :file:`include/linux/pm.h`.  The roles of the
105103 methods included in it will be explained in what follows.  For now, it should be
106104 sufficient to remember that the last three methods are specific to runtime power
107105 management while the remaining ones are used during system-wide power
....@@ -109,7 +107,7 @@
109107 
110108 There also is a deprecated "old" or "legacy" interface for power management
111109 operations available at least for some subsystems.  This approach does not use
112
-|struct dev_pm_ops| objects and it is suitable only for implementing system
110
+struct dev_pm_ops objects and it is suitable only for implementing system
113111 sleep power management methods in a limited way.  Therefore it is not described
114112 in this document, so please refer directly to the source code for more
115113 information about it.
....@@ -119,9 +117,9 @@
119117 -----------------------
120118 
121119 The core methods to suspend and resume devices reside in
122
-|struct dev_pm_ops| pointed to by the :c:member:`ops` member of
123
-|struct dev_pm_domain|, or by the :c:member:`pm` member of |struct bus_type|,
124
-|struct device_type| and |struct class|.  They are mostly of interest to the
120
+struct dev_pm_ops pointed to by the :c:member:`ops` member of
121
+struct dev_pm_domain, or by the :c:member:`pm` member of struct bus_type,
122
+struct device_type and struct class.  They are mostly of interest to the
125123 people writing infrastructure for platforms and buses, like PCI or USB, or
126124 device type and device class drivers.  They also are relevant to the writers of
127125 device drivers whose subsystems (PM domains, device types, device classes and
....@@ -150,7 +148,7 @@
150148 driver) can physically support wakeup events.  The
151149 :c:func:`device_set_wakeup_capable()` routine affects this flag.  The
152150 :c:member:`power.wakeup` field is a pointer to an object of type
153
-|struct wakeup_source| used for controlling whether or not the device should use
151
+struct wakeup_source used for controlling whether or not the device should use
154152 its system wakeup mechanism and for notifying the PM core of system wakeup
155153 events signaled by the device.  This object is only present for wakeup-capable
156154 devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created
....@@ -219,7 +217,7 @@
219217 flag is clear.
220218 
221219 For more information about the runtime power management framework, refer to
222
-:file:`Documentation/power/runtime_pm.txt`.
220
+:file:`Documentation/power/runtime_pm.rst`.
223221 
224222 
225223 Calling Drivers to Enter and Leave System Sleep States
....@@ -343,7 +341,7 @@
343341 	PM core will skip the ``suspend``, ``suspend_late`` and
344342 	``suspend_noirq`` phases as well as all of the corresponding phases of
345343 	the subsequent device resume for all of these devices.	In that case,
346
-	the ``->complete`` callback will be invoked directly after the
344
+	the ``->complete`` callback will be the next one invoked after the
347345 	``->prepare`` callback and is entirely responsible for putting the
348346 	device into a consistent state as appropriate.
349347 
....@@ -355,9 +353,9 @@
355353 	runtime PM disabled.
356354 
357355 	This feature also can be controlled by device drivers by using the
358
-	``DPM_FLAG_NEVER_SKIP`` and ``DPM_FLAG_SMART_PREPARE`` driver power
359
-	management flags.  [Typically, they are set at the time the driver is
360
-	probed against the device in question by passing them to the
356
+	``DPM_FLAG_NO_DIRECT_COMPLETE`` and ``DPM_FLAG_SMART_PREPARE`` driver
357
+	power management flags.  [Typically, they are set at the time the driver
358
+	is probed against the device in question by passing them to the
361359 	:c:func:`dev_pm_set_driver_flags` helper function.]  If the first of
362360 	these flags is set, the PM core will not apply the direct-complete
363361 	procedure described above to the given device and, consequenty, to any
....@@ -377,11 +375,15 @@
377375 	``->suspend`` methods provided by subsystems (bus types and PM domains
378376 	in particular) must follow an additional rule regarding what can be done
379377 	to the devices before their drivers' ``->suspend`` methods are called.
380
-	Namely, they can only resume the devices from runtime suspend by
381
-	calling :c:func:`pm_runtime_resume` for them, if that is necessary, and
378
+	Namely, they may resume the devices from runtime suspend by
379
+	calling :c:func:`pm_runtime_resume` for them, if that is necessary, but
382380 	they must not update the state of the devices in any other way at that
383381 	time (in case the drivers need to resume the devices from runtime
384
-	suspend in their ``->suspend`` methods).
382
+	suspend in their ``->suspend`` methods).  In fact, the PM core prevents
383
+	subsystems or drivers from putting devices into runtime suspend at
384
+	these times by calling :c:func:`pm_runtime_get_noresume` before issuing
385
+	the ``->prepare`` callback (and calling :c:func:`pm_runtime_put` after
386
+	issuing the ``->complete`` callback).
385387 
386388     3.	For a number of devices it is convenient to split suspend into the
387389 	"quiesce device" and "save device state" phases, in which cases
....@@ -408,7 +410,7 @@
408410 will also switch off power supplies or reduce voltages.  [Drivers supporting
409411 runtime PM may already have performed some or all of these steps.]
410412 
411
-If :c:func:`device_may_wakeup(dev)` returns ``true``, the device should be
413
+If :c:func:`device_may_wakeup()` returns ``true``, the device should be
412414 prepared for generating hardware wakeup signals to trigger a system wakeup event
413415 when the system is in the sleep state.  For example, :c:func:`enable_irq_wake()`
414416 might identify GPIO signals hooked up to a switch or other external hardware,
....@@ -453,22 +455,22 @@
453455 
454456 	Note, however, that new children may be registered below the device as
455457 	soon as the ``->resume`` callbacks occur; it's not necessary to wait
456
-	until the ``complete`` phase with that.
458
+	until the ``complete`` phase runs.
457459 
458460 	Moreover, if the preceding ``->prepare`` callback returned a positive
459461 	number, the device may have been left in runtime suspend throughout the
460
-	whole system suspend and resume (the ``suspend``, ``suspend_late``,
461
-	``suspend_noirq`` phases of system suspend and the ``resume_noirq``,
462
-	``resume_early``, ``resume`` phases of system resume may have been
463
-	skipped for it).  In that case, the ``->complete`` callback is entirely
462
+	whole system suspend and resume (its ``->suspend``, ``->suspend_late``,
463
+	``->suspend_noirq``, ``->resume_noirq``,
464
+	``->resume_early``, and ``->resume`` callbacks may have been
465
+	skipped).  In that case, the ``->complete`` callback is entirely
464466 	responsible for putting the device into a consistent state after system
465467 	suspend if necessary.  [For example, it may need to queue up a runtime
466468 	resume request for the device for this purpose.]  To check if that is
467469 	the case, the ``->complete`` callback can consult the device's
468
-	``power.direct_complete`` flag.  Namely, if that flag is set when the
469
-	``->complete`` callback is being run, it has been called directly after
470
-	the preceding ``->prepare`` and special actions may be required
471
-	to make the device work correctly afterward.
470
+	``power.direct_complete`` flag.  If that flag is set when the
471
+	``->complete`` callback is being run then the direct-complete mechanism
472
+	was used, and special actions may be required to make the device work
473
+	correctly afterward.
472474 
473475 At the end of these phases, drivers should be as functional as they were before
474476 suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are
....@@ -569,10 +571,12 @@
569571 
570572 The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks
571573 should do essentially the same things as the ``->suspend``, ``->suspend_late``
572
-and ``->suspend_noirq`` callbacks, respectively.  The only notable difference is
574
+and ``->suspend_noirq`` callbacks, respectively.  A notable difference is
573575 that they need not store the device register values, because the registers
574576 should already have been stored during the ``freeze``, ``freeze_late`` or
575
-``freeze_noirq`` phases.
577
+``freeze_noirq`` phases.  Also, on many machines the firmware will power-down
578
+the entire system, so it is not necessary for the callback to put the device in
579
+a low-power state.
576580 
577581 
578582 Leaving Hibernation
....@@ -701,8 +705,8 @@
701705 sub-domain of the parent domain.
702706 
703707 Support for power domains is provided through the :c:member:`pm_domain` field of
704
-|struct device|.  This field is a pointer to an object of type
705
-|struct dev_pm_domain|, defined in :file:`include/linux/pm.h`, providing a set
708
+struct device.  This field is a pointer to an object of type
709
+struct dev_pm_domain, defined in :file:`include/linux/pm.h`, providing a set
706710 of power management callbacks analogous to the subsystem-level and device driver
707711 callbacks that are executed for the given device during all power transitions,
708712 instead of the respective subsystem-level callbacks.  Specifically, if a
....@@ -722,7 +726,7 @@
722726 
723727 Devices may be defined as IRQ-safe which indicates to the PM core that their
724728 runtime PM callbacks may be invoked with disabled interrupts (see
725
-:file:`Documentation/power/runtime_pm.txt` for more information).  If an
729
+:file:`Documentation/power/runtime_pm.rst` for more information).  If an
726730 IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
727731 disallowed, unless the domain itself is defined as IRQ-safe. However, it
728732 makes sense to define a PM domain as IRQ-safe only if all the devices in it
....@@ -758,70 +762,119 @@
758762 
759763 If it is necessary to resume a device from runtime suspend during a system-wide
760764 transition into a sleep state, that can be done by calling
761
-:c:func:`pm_runtime_resume` for it from the ``->suspend`` callback (or its
762
-couterpart for transitions related to hibernation) of either the device's driver
763
-or a subsystem responsible for it (for example, a bus type or a PM domain).
764
-That is guaranteed to work by the requirement that subsystems must not change
765
-the state of devices (possibly except for resuming them from runtime suspend)
765
+:c:func:`pm_runtime_resume` from the ``->suspend`` callback (or the ``->freeze``
766
+or ``->poweroff`` callback for transitions related to hibernation) of either the
767
+device's driver or its subsystem (for example, a bus type or a PM domain).
768
+However, subsystems must not otherwise change the runtime status of devices
766769 from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before*
767770 invoking device drivers' ``->suspend`` callbacks (or equivalent).
768771 
772
+.. _smart_suspend_flag:
773
+
774
+The ``DPM_FLAG_SMART_SUSPEND`` Driver Flag
775
+------------------------------------------
776
+
769777 Some bus types and PM domains have a policy to resume all devices from runtime
770778 suspend upfront in their ``->suspend`` callbacks, but that may not be really
771
-necessary if the driver of the device can cope with runtime-suspended devices.
772
-The driver can indicate that by setting ``DPM_FLAG_SMART_SUSPEND`` in
773
-:c:member:`power.driver_flags` at the probe time, by passing it to the
774
-:c:func:`dev_pm_set_driver_flags` helper.  That also may cause middle-layer code
779
+necessary if the device's driver can cope with runtime-suspended devices.
780
+The driver can indicate this by setting ``DPM_FLAG_SMART_SUSPEND`` in
781
+:c:member:`power.driver_flags` at probe time, with the assistance of the
782
+:c:func:`dev_pm_set_driver_flags` helper routine.
783
+
784
+Setting that flag causes the PM core and middle-layer code
775785 (bus types, PM domains etc.) to skip the ``->suspend_late`` and
776786 ``->suspend_noirq`` callbacks provided by the driver if the device remains in
777
-runtime suspend at the beginning of the ``suspend_late`` phase of system-wide
778
-suspend (or in the ``poweroff_late`` phase of hibernation), when runtime PM
779
-has been disabled for it, under the assumption that its state should not change
780
-after that point until the system-wide transition is over (the PM core itself
781
-does that for devices whose "noirq", "late" and "early" system-wide PM callbacks
782
-are executed directly by it).  If that happens, the driver's system-wide resume
783
-callbacks, if present, may still be invoked during the subsequent system-wide
784
-resume transition and the device's runtime power management status may be set
785
-to "active" before enabling runtime PM for it, so the driver must be prepared to
786
-cope with the invocation of its system-wide resume callbacks back-to-back with
787
-its ``->runtime_suspend`` one (without the intervening ``->runtime_resume`` and
788
-so on) and the final state of the device must reflect the "active" runtime PM
789
-status in that case.
787
+runtime suspend throughout those phases of the system-wide suspend (and
788
+similarly for the "freeze" and "poweroff" parts of system hibernation).
789
+[Otherwise the same driver
790
+callback might be executed twice in a row for the same device, which would not
791
+be valid in general.]  If the middle-layer system-wide PM callbacks are present
792
+for the device then they are responsible for skipping these driver callbacks;
793
+if not then the PM core skips them.  The subsystem callback routines can
794
+determine whether they need to skip the driver callbacks by testing the return
795
+value from the :c:func:`dev_pm_skip_suspend` helper function.
796
+
797
+In addition, with ``DPM_FLAG_SMART_SUSPEND`` set, the driver's ``->thaw_noirq``
798
+and ``->thaw_early`` callbacks are skipped in hibernation if the device remained
799
+in runtime suspend throughout the preceding "freeze" transition.  Again, if the
800
+middle-layer callbacks are present for the device, they are responsible for
801
+doing this, otherwise the PM core takes care of it.
802
+
803
+
804
+The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag
805
+--------------------------------------------
790806 
791807 During system-wide resume from a sleep state it's easiest to put devices into
792
-the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`.
808
+the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`.
793809 [Refer to that document for more information regarding this particular issue as
794810 well as for information on the device runtime power management framework in
795
-general.]
796
-
797
-However, it often is desirable to leave devices in suspend after system
798
-transitions to the working state, especially if those devices had been in
811
+general.]  However, it often is desirable to leave devices in suspend after
812
+system transitions to the working state, especially if those devices had been in
799813 runtime suspend before the preceding system-wide suspend (or analogous)
800
-transition.  Device drivers can use the ``DPM_FLAG_LEAVE_SUSPENDED`` flag to
801
-indicate to the PM core (and middle-layer code) that they prefer the specific
802
-devices handled by them to be left suspended and they have no problems with
803
-skipping their system-wide resume callbacks for this reason.  Whether or not the
804
-devices will actually be left in suspend may depend on their state before the
805
-given system suspend-resume cycle and on the type of the system transition under
806
-way.  In particular, devices are not left suspended if that transition is a
807
-restore from hibernation, as device states are not guaranteed to be reflected
808
-by the information stored in the hibernation image in that case.
814
+transition.
809815 
810
-The middle-layer code involved in the handling of the device is expected to
811
-indicate to the PM core if the device may be left in suspend by setting its
812
-:c:member:`power.may_skip_resume` status bit which is checked by the PM core
813
-during the "noirq" phase of the preceding system-wide suspend (or analogous)
814
-transition.  The middle layer is then responsible for handling the device as
815
-appropriate in its "noirq" resume callback, which is executed regardless of
816
-whether or not the device is left suspended, but the other resume callbacks
817
-(except for ``->complete``) will be skipped automatically by the PM core if the
818
-device really can be left in suspend.
816
+To that end, device drivers can use the ``DPM_FLAG_MAY_SKIP_RESUME`` flag to
817
+indicate to the PM core and middle-layer code that they allow their "noirq" and
818
+"early" resume callbacks to be skipped if the device can be left in suspend
819
+after system-wide PM transitions to the working state.  Whether or not that is
820
+the case generally depends on the state of the device before the given system
821
+suspend-resume cycle and on the type of the system transition under way.
822
+In particular, the "thaw" and "restore" transitions related to hibernation are
823
+not affected by ``DPM_FLAG_MAY_SKIP_RESUME`` at all.  [All callbacks are
824
+issued during the "restore" transition regardless of the flag settings,
825
+and whether or not any driver callbacks
826
+are skipped during the "thaw" transition depends whether or not the
827
+``DPM_FLAG_SMART_SUSPEND`` flag is set (see `above <smart_suspend_flag_>`_).
828
+In addition, a device is not allowed to remain in runtime suspend if any of its
829
+children will be returned to full power.]
819830 
820
-For devices whose "noirq", "late" and "early" driver callbacks are invoked
821
-directly by the PM core, all of the system-wide resume callbacks are skipped if
822
-``DPM_FLAG_LEAVE_SUSPENDED`` is set and the device is in runtime suspend during
823
-the ``suspend_noirq`` (or analogous) phase or the transition under way is a
824
-proper system suspend (rather than anything related to hibernation) and the
825
-device's wakeup settings are suitable for runtime PM (that is, it cannot
826
-generate wakeup signals at all or it is allowed to wake up the system from
827
-sleep).
831
+The ``DPM_FLAG_MAY_SKIP_RESUME`` flag is taken into account in combination with
832
+the :c:member:`power.may_skip_resume` status bit set by the PM core during the
833
+"suspend" phase of suspend-type transitions.  If the driver or the middle layer
834
+has a reason to prevent the driver's "noirq" and "early" resume callbacks from
835
+being skipped during the subsequent system resume transition, it should
836
+clear :c:member:`power.may_skip_resume` in its ``->suspend``, ``->suspend_late``
837
+or ``->suspend_noirq`` callback.  [Note that the drivers setting
838
+``DPM_FLAG_SMART_SUSPEND`` need to clear :c:member:`power.may_skip_resume` in
839
+their ``->suspend`` callback in case the other two are skipped.]
840
+
841
+Setting the :c:member:`power.may_skip_resume` status bit along with the
842
+``DPM_FLAG_MAY_SKIP_RESUME`` flag is necessary, but generally not sufficient,
843
+for the driver's "noirq" and "early" resume callbacks to be skipped.  Whether or
844
+not they should be skipped can be determined by evaluating the
845
+:c:func:`dev_pm_skip_resume` helper function.
846
+
847
+If that function returns ``true``, the driver's "noirq" and "early" resume
848
+callbacks should be skipped and the device's runtime PM status will be set to
849
+"suspended" by the PM core.  Otherwise, if the device was runtime-suspended
850
+during the preceding system-wide suspend transition and its
851
+``DPM_FLAG_SMART_SUSPEND`` is set, its runtime PM status will be set to
852
+"active" by the PM core.  [Hence, the drivers that do not set
853
+``DPM_FLAG_SMART_SUSPEND`` should not expect the runtime PM status of their
854
+devices to be changed from "suspended" to "active" by the PM core during
855
+system-wide resume-type transitions.]
856
+
857
+If the ``DPM_FLAG_MAY_SKIP_RESUME`` flag is not set for a device, but
858
+``DPM_FLAG_SMART_SUSPEND`` is set and the driver's "late" and "noirq" suspend
859
+callbacks are skipped, its system-wide "noirq" and "early" resume callbacks, if
860
+present, are invoked as usual and the device's runtime PM status is set to
861
+"active" by the PM core before enabling runtime PM for it.  In that case, the
862
+driver must be prepared to cope with the invocation of its system-wide resume
863
+callbacks back-to-back with its ``->runtime_suspend`` one (without the
864
+intervening ``->runtime_resume`` and system-wide suspend callbacks) and the
865
+final state of the device must reflect the "active" runtime PM status in that
866
+case.  [Note that this is not a problem at all if the driver's
867
+``->suspend_late`` callback pointer points to the same function as its
868
+``->runtime_suspend`` one and its ``->resume_early`` callback pointer points to
869
+the same function as the ``->runtime_resume`` one, while none of the other
870
+system-wide suspend-resume callbacks of the driver are present, for example.]
871
+
872
+Likewise, if ``DPM_FLAG_MAY_SKIP_RESUME`` is set for a device, its driver's
873
+system-wide "noirq" and "early" resume callbacks may be skipped while its "late"
874
+and "noirq" suspend callbacks may have been executed (in principle, regardless
875
+of whether or not ``DPM_FLAG_SMART_SUSPEND`` is set).  In that case, the driver
876
+needs to be able to cope with the invocation of its ``->runtime_resume``
877
+callback back-to-back with its "late" and "noirq" suspend ones.  [For instance,
878
+that is not a concern if the driver sets both ``DPM_FLAG_SMART_SUSPEND`` and
879
+``DPM_FLAG_MAY_SKIP_RESUME`` and uses the same pair of suspend/resume callback
880
+functions for runtime PM and system-wide suspend/resume.]