1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt>
3
4 .. _driverapi_pm_devices:
5
6 ==============================
7 Device Power Management Basics
8 ==============================
9
10 :Copyright: |copy| 2010-2011 Rafael J. Wysocki<
11 :Copyright: |copy| 2010 Alan Stern <stern@rowla
12 :Copyright: |copy| 2016 Intel Corporation
13
14 :Author: Rafael J. Wysocki <rafael.j.wysocki@in
15
16
17 Most of the code in Linux is device drivers, s
18 management (PM) code is also driver-specific.
19 little; others, especially for platforms with
20 phones), will do a lot.
21
22 This writeup gives an overview of how drivers
23 power management goals, emphasizing the models
24 shared by everything that hooks up to the driv
25 background for the domain-specific work you'd
26
27
28 Two Models for Device Power Management
29 ======================================
30
31 Drivers will use one or both of these models t
32 states:
33
34 System Sleep model:
35
36 Drivers can enter low-power states as
37 low-power states like "suspend" (also
38 (mostly for systems with disks) "hiber
39 "suspend-to-disk").
40
41 This is something that device, bus, an
42 by implementing various role-specific
43 cleanly power down hardware and softwa
44 them without loss of data.
45
46 Some drivers can manage hardware wakeu
47 leave the low-power state. This featu
48 using the relevant :file:`/sys/devices
49 Ethernet drivers the ioctl interface u
50 for this purpose); enabling it may cos
51 whole system enter low-power states mo
52
53 Runtime Power Management model:
54
55 Devices may also be put into low-power
56 running, independently of other power
57 However, devices are not generally ind
58 example, a parent device cannot be sus
59 devices have been suspended). Moreove
60 device is on, it may be necessary to c
61 operations on the device for this purp
62 states at run time may require special
63 transitions (suspend or hibernation).
64
65 For these reasons not only the device
66 appropriate subsystem (bus type, devic
67 the PM core are involved in runtime po
68 sleep power management case, they need
69 various role-specific suspend and resu
70 is cleanly powered down and reactivate
71
72 There's not a lot to be said about those low-p
73 very system-specific, and often device-specifi
74 have been put into low-power states (at runtim
75 to entering some system-wide low-power state (
76 synergies exist, so that several drivers using
77 into a state where even deeper power saving op
78
79 Most suspended devices will have quiesced all
80 for wakeup events), no more data read or writt
81 drivers are no longer accepted. A given bus o
82 requirements though.
83
84 Examples of hardware wakeup events include an
85 network wake-on-LAN packets, keyboard or mouse
86 or removal (for PCMCIA, MMC/SD, USB, and so on
87
88 Interfaces for Entering System Sleep States
89 ===========================================
90
91 There are programming interfaces provided for
92 device class) and device drivers to allow them
93 management of devices they are concerned with.
94 system sleep and runtime power management.
95
96
97 Device Power Management Operations
98 ----------------------------------
99
100 Device power management operations, at the sub
101 device driver level, are implemented by defini
102 struct dev_pm_ops defined in :file:`include/li
103 methods included in it will be explained in wh
104 sufficient to remember that the last three met
105 management while the remaining ones are used d
106 transitions.
107
108 There also is a deprecated "old" or "legacy" i
109 operations available at least for some subsyst
110 struct dev_pm_ops objects and it is suitable o
111 sleep power management methods in a limited wa
112 in this document, so please refer directly to
113 information about it.
114
115
116 Subsystem-Level Methods
117 -----------------------
118
119 The core methods to suspend and resume devices
120 struct dev_pm_ops pointed to by the :c:member:
121 struct dev_pm_domain, or by the :c:member:`pm`
122 struct device_type and struct class. They are
123 people writing infrastructure for platforms an
124 device type and device class drivers. They al
125 device drivers whose subsystems (PM domains, d
126 bus types) don't provide all power management
127
128 Bus drivers implement these methods as appropr
129 drivers using it; PCI works differently from U
130 write subsystem-level drivers; most driver cod
131 on top of bus-specific framework code.
132
133 For more information on these driver calls, se
134 they are called in phases for every device, re
135 sequencing in the driver model tree.
136
137
138 :file:`/sys/devices/.../power/wakeup` files
139 -------------------------------------------
140
141 All device objects in the driver model contain
142 of system wakeup events (hardware signals that
143 sleep state). These fields are initialized by
144 :c:func:`device_set_wakeup_capable()` and :c:f
145 defined in :file:`include/linux/pm_wakeup.h`.
146
147 The :c:member:`power.can_wakeup` flag just rec
148 driver) can physically support wakeup events.
149 :c:func:`device_set_wakeup_capable()` routine
150 :c:member:`power.wakeup` field is a pointer to
151 struct wakeup_source used for controlling whet
152 its system wakeup mechanism and for notifying
153 events signaled by the device. This object is
154 devices (i.e. devices whose :c:member:`can_wak
155 (or removed) by :c:func:`device_set_wakeup_cap
156
157 Whether or not a device is capable of issuing
158 matter, and the kernel is responsible for keep
159 whether or not a wakeup-capable device should
160 decision, and it is managed by user space thro
161 :file:`power/wakeup` file. User space can wri
162 strings to it to indicate whether or not, resp
163 to signal system wakeup. This file is only pr
164 :c:member:`power.wakeup` object exists for the
165 removed) along with that object, by :c:func:`d
166 Reads from the file will return the correspond
167
168 The initial value in the :file:`power/wakeup`
169 majority of devices; the major exceptions are
170 Ethernet adapters whose WoL (wake-on-LAN) feat
171 It should also default to "enabled" for device
172 requests on their own but merely forward wakeu
173 (like PCI Express ports).
174
175 The :c:func:`device_may_wakeup()` routine retu
176 :c:member:`power.wakeup` object exists and the
177 file contains the "enabled" string. This info
178 like the PCI bus type code, to see whether or
179 mechanisms. If device wakeup mechanisms are e
180 drivers, they also should use :c:func:`device_
181 during a system sleep transition. Device driv
182 call :c:func:`device_set_wakeup_enable()` dire
183
184 It ought to be noted that system wakeup is con
185 wakeup" used by runtime power management, alth
186 same physical mechanism. Remote wakeup is a f
187 low-power states to trigger specific interrupt
188 they should be put into the full-power state.
189 be used to signal system wakeup events, depend
190 some systems it is impossible to trigger them
191 case, remote wakeup should always be enabled f
192 all devices and drivers that support it.
193
194
195 :file:`/sys/devices/.../power/control` files
196 --------------------------------------------
197
198 Each device in the driver model has a flag to
199 runtime power management. This flag, :c:membe
200 by the bus type (or generally subsystem) code
201 or :c:func:`pm_runtime_forbid()`; the default
202 management.
203
204 The setting can be adjusted by user space by w
205 the device's :file:`power/control` sysfs file.
206 :c:func:`pm_runtime_allow()`, setting the flag
207 runtime power-managed by its driver. Writing
208 :c:func:`pm_runtime_forbid()`, clearing the fl
209 power if it was in a low-power state, and prev
210 device from being runtime power-managed. User
211 of the :c:member:`runtime_auto` flag by readin
212
213 The device's :c:member:`runtime_auto` flag has
214 system-wide power transitions. In particular,
215 majority of cases should and will) be put into
216 system-wide transition to a sleep state even t
217 flag is clear.
218
219 For more information about the runtime power m
220 Documentation/power/runtime_pm.rst.
221
222
223 Calling Drivers to Enter and Leave System Slee
224 ==============================================
225
226 When the system goes into a sleep state, each
227 suspend the device by putting it into a state
228 system state. That's usually some version of
229 system-specific. Also, wakeup-enabled devices
230 functional in order to wake the system.
231
232 When the system leaves that low-power state, t
233 resume it by returning it to full power. The
234 always go together, and both are multi-phase o
235
236 For simple drivers, suspend might quiesce the
237 and then turn its hardware as "off" as possibl
238 matching resume calls would then completely re
239 before reactivating its class I/O queues.
240
241 More power-aware drivers might prepare the dev
242 events.
243
244
245 Call Sequence Guarantees
246 ------------------------
247
248 To ensure that bridges and similar links needi
249 available when the device is suspended or resu
250 walked in a bottom-up order to suspend devices
251 used to resume those devices.
252
253 The ordering of the device hierarchy is define
254 get registered: a child can never be register
255 its parent; and can't be removed or suspended
256
257 The policy is that the device hierarchy should
258 [Or at least the control bus, for devices whic
259 In particular, this means that a device regist
260 the device is suspending (i.e. has been chosen
261 device to suspend) or has already suspended, a
262 devices have been suspended. Device drivers m
263 situations.
264
265
266 System Power Management Phases
267 ------------------------------
268
269 Suspending or resuming the system is done in s
270 are used for suspend-to-idle, shallow (standby
271 sleep states and the hibernation state ("suspe
272 executing callbacks for every device before th
273 buses or classes support all these callbacks a
274 callbacks. The various phases always run afte
275 before they are unfrozen. Furthermore, the ``
276 when IRQ handlers have been disabled (except f
277 IRQF_NO_SUSPEND flag).
278
279 All phases use PM domain, bus, type, class or
280 defined in ``dev->pm_domain->ops``, ``dev->bus
281 ``dev->class->pm`` or ``dev->driver->pm``). T
282 PM core as mutually exclusive. Moreover, PM d
283 precedence over all of the other callbacks and
284 precedence over bus, class and driver callback
285 rules are used to determine which callback to
286
287 1. If ``dev->pm_domain`` is present, the
288 provided by ``dev->pm_domain->ops`` fo
289
290 2. Otherwise, if both ``dev->type`` and `
291 callback provided by ``dev->type->pm``
292
293 3. Otherwise, if both ``dev->class`` and
294 the callback provided by ``dev->class-
295 execution.
296
297 4. Otherwise, if both ``dev->bus`` and ``
298 callback provided by ``dev->bus->pm``
299
300 This allows PM domains and device types to ove
301 types or device classes if necessary.
302
303 The PM domain, type, class and bus callbacks m
304 driver-specific methods stored in ``dev->drive
305 that.
306
307 If the subsystem callback chosen for execution
308 execute the corresponding method from the ``de
309 there is one.
310
311
312 Entering System Suspend
313 -----------------------
314
315 When the system goes into the freeze, standby
316 the phases are: ``prepare``, ``suspend``, ``su
317
318 1. The ``prepare`` phase is meant to prev
319 devices from being registered; the PM
320 children of a device had been suspende
321 registered at will. [By contrast, fro
322 devices may be unregistered at any tim
323 suspend-related phases, during the ``p
324 hierarchy is traversed top-down.
325
326 After the ``->prepare`` callback metho
327 registered below the device. The meth
328 driver in some way for the upcoming sy
329 should not put the device into a low-p
330 device supports runtime power manageme
331 method must not update its state in ca
332 from runtime suspend later on.
333
334 For devices supporting runtime power m
335 prepare callback can be used to indica
336 safely leave the device in runtime sus
337 already), provided that all of the dev
338 runtime suspend. Namely, if the prepa
339 number and that happens for all of the
340 and all of them (including the device
341 PM core will skip the ``suspend``, ``s
342 ``suspend_noirq`` phases as well as al
343 the subsequent device resume for all o
344 the ``->complete`` callback will be th
345 ``->prepare`` callback and is entirely
346 device into a consistent state as appr
347
348 Note that this direct-complete procedu
349 disabled for runtime PM; only the runt
350 that if a device has system-sleep call
351 PM, then its prepare callback must nev
352 is because all such devices are initia
353 runtime PM disabled.
354
355 This feature also can be controlled by
356 ``DPM_FLAG_NO_DIRECT_COMPLETE`` and ``
357 power management flags. [Typically, t
358 is probed against the device in questi
359 :c:func:`dev_pm_set_driver_flags` help
360 these flags is set, the PM core will n
361 procedure described above to the given
362 of its ancestors. The second flag, wh
363 code (bus types, device types, PM doma
364 the return value of the ``->prepare``
365 into account and it may only return a
366 ``->prepare`` callback if the driver's
367 value.
368
369 2. The ``->suspend`` methods should quies
370 performing I/O. They also may save th
371 the appropriate low-power state, depen
372 on, and they may enable wakeup events.
373
374 However, for devices supporting runtim
375 ``->suspend`` methods provided by subs
376 in particular) must follow an addition
377 to the devices before their drivers' `
378 Namely, they may resume the devices fr
379 calling :c:func:`pm_runtime_resume` fo
380 they must not update the state of the
381 time (in case the drivers need to resu
382 suspend in their ``->suspend`` methods
383 subsystems or drivers from putting dev
384 these times by calling :c:func:`pm_run
385 the ``->prepare`` callback (and callin
386 issuing the ``->complete`` callback).
387
388 3. For a number of devices it is convenie
389 "quiesce device" and "save device stat
390 ``suspend_late`` is meant to do the la
391 runtime power management has been disa
392
393 4. The ``suspend_noirq`` phase occurs aft
394 which means that the driver's interrup
395 the callback method is running. The `
396 save the values of the device's regist
397 and finally put the device into the ap
398
399 The majority of subsystems and device
400 callback. However, bus types allowing
401 vectors, like PCI, generally need it;
402 an error during the suspend phase by f
403 generated by some other device after i
404 power.
405
406 At the end of these phases, drivers should hav
407 (DMA, IRQs), saved enough state that they can
408 state (as needed by the hardware), and placed
409 On many platforms they will gate off one or mo
410 will also switch off power supplies or reduce
411 runtime PM may already have performed some or
412
413 If :c:func:`device_may_wakeup()` returns ``tru
414 prepared for generating hardware wakeup signal
415 when the system is in the sleep state. For ex
416 might identify GPIO signals hooked up to a swi
417 and :c:func:`pci_enable_wake()` does something
418
419 If any of these callbacks returns an error, th
420 low-power state. Instead, the PM core will un
421 the devices that were suspended.
422
423
424 Leaving System Suspend
425 ----------------------
426
427 When resuming from freeze, standby or memory s
428 ``resume_noirq``, ``resume_early``, ``resume``
429
430 1. The ``->resume_noirq`` callback method
431 needed before the driver's interrupt h
432 generally means undoing the actions of
433 the bus type permits devices to share
434 method should bring the device and its
435 driver can recognize if the device is
436 if any, and handle them correctly.
437
438 For example, the PCI bus type's ``->pm
439 into the full-power state (D0 in the P
440 standard configuration registers of th
441 device driver's ``->pm.resume_noirq()`
442 actions.
443
444 2. The ``->resume_early`` methods should
445 of the resume methods. This generally
446 the preceding ``suspend_late`` phase.
447
448 3. The ``->resume`` methods should bring
449 state, so that it can perform normal I
450 undoing the actions of the ``suspend``
451
452 4. The ``complete`` phase should undo the
453 For this reason, unlike the other resu
454 ``complete`` phase the device hierarch
455
456 Note, however, that new children may b
457 soon as the ``->resume`` callbacks occ
458 until the ``complete`` phase runs.
459
460 Moreover, if the preceding ``->prepare
461 number, the device may have been left
462 whole system suspend and resume (its `
463 ``->suspend_noirq``, ``->resume_noirq`
464 ``->resume_early``, and ``->resume`` c
465 skipped). In that case, the ``->compl
466 responsible for putting the device int
467 suspend if necessary. [For example, i
468 resume request for the device for this
469 the case, the ``->complete`` callback
470 ``power.direct_complete`` flag. If th
471 ``->complete`` callback is being run t
472 was used, and special actions may be r
473 correctly afterward.
474
475 At the end of these phases, drivers should be
476 suspending: I/O can be performed using DMA and
477 gated on.
478
479 However, the details here may again be platfor
480 some systems support multiple "run" states, an
481 the end of resume might not be the one which p
482 That means availability of certain clocks or p
483 which could easily affect how a driver works.
484
485 Drivers need to be able to handle hardware whi
486 suspend methods were called, for example by co
487 This may be the hardest part, and the one most
488 and chip errata. It's simplest if the hardwar
489 the suspend was carried out, but that can only
490 system sleep entered was suspend-to-idle. For
491 that may not be the case (and usually isn't fo
492 states, like S3).
493
494 Drivers must also be prepared to notice that t
495 while the system was powered down, whenever th
496 PCMCIA, MMC, USB, Firewire, SCSI, and even IDE
497 where common Linux platforms will see such rem
498 will notice and handle such removals are curre
499 involve a separate thread.
500
501 These callbacks may return an error value, but
502 errors since there's nothing it can do about t
503 the system log.
504
505
506 Entering Hibernation
507 --------------------
508
509 Hibernating the system is more complicated tha
510 because it involves creating and saving a syst
511 more phases for hibernation, with a different
512 always run after tasks have been frozen and en
513
514 The general procedure for hibernation is to qu
515 create an image of the system memory while eve
516 devices ("thaw"), write the image to permanent
517 the system ("power off"). The phases used to
518 ``freeze``, ``freeze_late``, ``freeze_noirq``,
519 ``thaw``, ``complete``, ``prepare``, ``powerof
520 ``poweroff_noirq``.
521
522 1. The ``prepare`` phase is discussed in
523 section above.
524
525 2. The ``->freeze`` methods should quiesc
526 generate IRQs or DMA, and they may nee
527 registers. However the device does no
528 state, and to save time it's best not
529 not be prepared to generate wakeup eve
530
531 3. The ``freeze_late`` phase is analogous
532 described earlier, except that the dev
533 low-power state and should not be allo
534
535 4. The ``freeze_noirq`` phase is analogou
536 discussed earlier, except again that t
537 a low-power state and should not be al
538
539 At this point the system image is created. Al
540 the contents of memory should remain undisturb
541 image forms an atomic snapshot of the system s
542
543 5. The ``thaw_noirq`` phase is analogous
544 discussed earlier. The main differenc
545 the device is in the same state as at
546 phase.
547
548 6. The ``thaw_early`` phase is analogous
549 described above. Its methods should u
550 ``freeze_late``, if necessary.
551
552 7. The ``thaw`` phase is analogous to the
553 earlier. Its methods should bring the
554 state, so that it can be used for savi
555
556 8. The ``complete`` phase is discussed in
557 section above.
558
559 At this point the system image is saved, and t
560 prepared for the upcoming system shutdown. Th
561 before putting the system into the suspend-to-
562 and the phases are similar.
563
564 9. The ``prepare`` phase is discussed abo
565
566 10. The ``poweroff`` phase is analogous to
567
568 11. The ``poweroff_late`` phase is analogo
569
570 12. The ``poweroff_noirq`` phase is analog
571
572 The ``->poweroff``, ``->poweroff_late`` and ``
573 should do essentially the same things as the `
574 and ``->suspend_noirq`` callbacks, respectivel
575 that they need not store the device register v
576 should already have been stored during the ``f
577 ``freeze_noirq`` phases. Also, on many machin
578 the entire system, so it is not necessary for
579 a low-power state.
580
581
582 Leaving Hibernation
583 -------------------
584
585 Resuming from hibernation is, again, more comp
586 state in which the contents of main memory are
587 a system image to be loaded into memory and th
588 to be restored before control can be passed ba
589
590 Although in principle the image might be loade
591 pre-hibernation memory contents restored by th
592 can't be done because boot loaders aren't smar
593 established protocol for passing the necessary
594 boot loader loads a fresh instance of the kern
595 into memory and passes control to it in the us
596 reads the system image, restores the pre-hiber
597 control to the image kernel. Thus two differe
598 in resuming from hibernation. In fact, the re
599 different from the image kernel: a different c
600 version. This has important consequences for
601 subsystems.
602
603 To be able to load the system image into memor
604 include at least a subset of device drivers al
605 medium containing the image, although it doesn
606 drivers present in the image kernel. After th
607 devices managed by the boot kernel need to be
608 to the image kernel. This is very similar to
609 creating a system image, and it is accomplishe
610 ``prepare``, ``freeze``, and ``freeze_noirq``
611 affected by these phases are only those having
612 other devices will still be in whatever state
613
614 Should the restoration of the pre-hibernation
615 kernel would go through the "thawing" procedur
616 ``thaw_noirq``, ``thaw_early``, ``thaw``, and
617 continue running normally. This happens only
618 pre-hibernation memory contents are restored s
619 to the image kernel, which then becomes respon
620 to the working state.
621
622 To achieve this, the image kernel must restore
623 functionality. The operation is much like wak
624 the memory contents preserved), although it in
625 ``restore_noirq``, ``restore_early``, ``restor
626
627 1. The ``restore_noirq`` phase is analogo
628
629 2. The ``restore_early`` phase is analogo
630
631 3. The ``restore`` phase is analogous to
632
633 4. The ``complete`` phase is discussed ab
634
635 The main difference from ``resume[_early|_noir
636 ``restore[_early|_noirq]`` must assume the dev
637 reconfigured by the boot loader or the restore
638 of the device may be different from the state
639 ``freeze_late`` and ``freeze_noirq`` phases.
640 reset and completely re-initialized. In many
641 matter, so the ``->resume[_early|_noirq]`` and
642 method pointers can be set to the same routine
643 callback pointers are used in case there is a
644 matter.
645
646
647 Power Management Notifiers
648 ==========================
649
650 There are some operations that cannot be carri
651 callbacks discussed above, because the callbac
652 To handle these cases, subsystems and device d
653 management notifiers that are called before ta
654 been thawed. Generally speaking, the PM notif
655 actions that either require user space to be a
656 interfere with user space.
657
658 For details refer to Documentation/driver-api/
659
660
661 Device Low-Power (suspend) States
662 =================================
663
664 Device low-power states aren't standard. One
665 "on" and "off", while another might support a
666 "on" (how many engines are active?), plus a st
667 faster than from a full "off".
668
669 Some buses define rules about what different s
670 gives one example: after the suspend sequence
671 PCI device may not perform DMA or issue IRQs,
672 issues would be issued through the PME# bus si
673 several PCI-standard device states, some of wh
674
675 In contrast, integrated system-on-chip process
676 wakeup event sources (so drivers would call :c
677 might be able to treat DMA completion as a wak
678 active too, it'd only be the CPU and some peri
679
680 Some details here may be platform-specific. S
681 can be fully active in certain sleep states, s
682 refreshed using DMA while most of the system i
683 its frame buffer might even be updated by a DS
684 the Linux control processor stays idle.
685
686 Moreover, the specific actions taken may depen
687 One target system state might allow a given de
688 another might require a hard shut down with re
689 And two different target systems might use the
690 ways; the aforementioned LCD might be active i
691 but a different product using the same SOC mig
692
693
694 Device Power Management Domains
695 ===============================
696
697 Sometimes devices share reference clocks or ot
698 cases it generally is not possible to put devi
699 individually. Instead, a set of devices shari
700 into a low-power state together at the same ti
701 power resource. Of course, they also need to
702 together, by turning the shared power resource
703 property is often referred to as a power domai
704 nested inside another power domain. The nested
705 sub-domain of the parent domain.
706
707 Support for power domains is provided through
708 struct device. This field is a pointer to an
709 struct dev_pm_domain, defined in :file:`includ
710 of power management callbacks analogous to the
711 callbacks that are executed for the given devi
712 instead of the respective subsystem-level call
713 device's :c:member:`pm_domain` pointer is not
714 from the object pointed to by it will be execu
715 (e.g. bus type's) ``->suspend()`` callback and
716 remaining callbacks. In other words, power ma
717 defined for the given device, always take prec
718 by the device's subsystem (e.g. bus type).
719
720 The support for device power management domain
721 needing to use the same device driver power ma
722 different power domain configurations and want
723 support for power domains into subsystem-level
724 modifying the platform bus type. Other platfo
725 it into account in any way.
726
727 Devices may be defined as IRQ-safe which indic
728 runtime PM callbacks may be invoked with disab
729 Documentation/power/runtime_pm.rst for more in
730 IRQ-safe device belongs to a PM domain, the ru
731 disallowed, unless the domain itself is define
732 makes sense to define a PM domain as IRQ-safe
733 are IRQ-safe. Moreover, if an IRQ-safe domain
734 PM of the parent is only allowed if the parent
735 additional restriction that all child domains
736 be IRQ-safe.
737
738
739 Runtime Power Management
740 ========================
741
742 Many devices are able to dynamically power dow
743 running. This feature is useful for devices th
744 can offer significant power savings on a runni
745 often support a range of runtime power states,
746 as "off", "sleep", "idle", "active", and so on
747 cases (like PCI) be partially constrained by t
748 usually include hardware states that are also
749
750 A system-wide power transition can be started
751 power states due to runtime power management.
752 should recognize such situations and react to
753 necessary actions are subsystem-specific.
754
755 In some cases the decision may be made at the
756 cases the device driver may be left to decide.
757 desirable to leave a suspended device in that
758 transition, but in other cases the device must
759 state temporarily, for example so that its sys
760 disabled. This all depends on the hardware an
761 device driver in question.
762
763 If it is necessary to resume a device from run
764 transition into a sleep state, that can be don
765 :c:func:`pm_runtime_resume` from the ``->suspe
766 or ``->poweroff`` callback for transitions rel
767 device's driver or its subsystem (for example,
768 However, subsystems must not otherwise change
769 from their ``->prepare`` and ``->suspend`` cal
770 invoking device drivers' ``->suspend`` callbac
771
772 .. _smart_suspend_flag:
773
774 The ``DPM_FLAG_SMART_SUSPEND`` Driver Flag
775 ------------------------------------------
776
777 Some bus types and PM domains have a policy to
778 suspend upfront in their ``->suspend`` callbac
779 necessary if the device's driver can cope with
780 The driver can indicate this by setting ``DPM_
781 :c:member:`power.driver_flags` at probe time,
782 :c:func:`dev_pm_set_driver_flags` helper routi
783
784 Setting that flag causes the PM core and middl
785 (bus types, PM domains etc.) to skip the ``->s
786 ``->suspend_noirq`` callbacks provided by the
787 runtime suspend throughout those phases of the
788 similarly for the "freeze" and "poweroff" part
789 [Otherwise the same driver
790 callback might be executed twice in a row for
791 be valid in general.] If the middle-layer sys
792 for the device then they are responsible for s
793 if not then the PM core skips them. The subsy
794 determine whether they need to skip the driver
795 value from the :c:func:`dev_pm_skip_suspend` h
796
797 In addition, with ``DPM_FLAG_SMART_SUSPEND`` s
798 and ``->thaw_early`` callbacks are skipped in
799 in runtime suspend throughout the preceding "f
800 middle-layer callbacks are present for the dev
801 doing this, otherwise the PM core takes care o
802
803
804 The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag
805 --------------------------------------------
806
807 During system-wide resume from a sleep state i
808 the full-power state, as explained in Document
809 [Refer to that document for more information r
810 well as for information on the device runtime
811 general.] However, it often is desirable to l
812 system transitions to the working state, espec
813 runtime suspend before the preceding system-wi
814 transition.
815
816 To that end, device drivers can use the ``DPM_
817 indicate to the PM core and middle-layer code
818 "early" resume callbacks to be skipped if the
819 after system-wide PM transitions to the workin
820 the case generally depends on the state of the
821 suspend-resume cycle and on the type of the sy
822 In particular, the "thaw" and "restore" transi
823 not affected by ``DPM_FLAG_MAY_SKIP_RESUME`` a
824 issued during the "restore" transition regardl
825 and whether or not any driver callbacks
826 are skipped during the "thaw" transition depen
827 ``DPM_FLAG_SMART_SUSPEND`` flag is set (see `a
828 In addition, a device is not allowed to remain
829 children will be returned to full power.]
830
831 The ``DPM_FLAG_MAY_SKIP_RESUME`` flag is taken
832 the :c:member:`power.may_skip_resume` status b
833 "suspend" phase of suspend-type transitions.
834 has a reason to prevent the driver's "noirq" a
835 being skipped during the subsequent system res
836 clear :c:member:`power.may_skip_resume` in its
837 or ``->suspend_noirq`` callback. [Note that t
838 ``DPM_FLAG_SMART_SUSPEND`` need to clear :c:me
839 their ``->suspend`` callback in case the other
840
841 Setting the :c:member:`power.may_skip_resume`
842 ``DPM_FLAG_MAY_SKIP_RESUME`` flag is necessary
843 for the driver's "noirq" and "early" resume ca
844 not they should be skipped can be determined b
845 :c:func:`dev_pm_skip_resume` helper function.
846
847 If that function returns ``true``, the driver'
848 callbacks should be skipped and the device's r
849 "suspended" by the PM core. Otherwise, if the
850 during the preceding system-wide suspend trans
851 ``DPM_FLAG_SMART_SUSPEND`` is set, its runtime
852 "active" by the PM core. [Hence, the drivers
853 ``DPM_FLAG_SMART_SUSPEND`` should not expect t
854 devices to be changed from "suspended" to "act
855 system-wide resume-type transitions.]
856
857 If the ``DPM_FLAG_MAY_SKIP_RESUME`` flag is no
858 ``DPM_FLAG_SMART_SUSPEND`` is set and the driv
859 callbacks are skipped, its system-wide "noirq"
860 present, are invoked as usual and the device's
861 "active" by the PM core before enabling runtim
862 driver must be prepared to cope with the invoc
863 callbacks back-to-back with its ``->runtime_su
864 intervening ``->runtime_resume`` and system-wi
865 final state of the device must reflect the "ac
866 case. [Note that this is not a problem at all
867 ``->suspend_late`` callback pointer points to
868 ``->runtime_suspend`` one and its ``->resume_e
869 the same function as the ``->runtime_resume``
870 system-wide suspend-resume callbacks of the dr
871
872 Likewise, if ``DPM_FLAG_MAY_SKIP_RESUME`` is s
873 system-wide "noirq" and "early" resume callbac
874 and "noirq" suspend callbacks may have been ex
875 of whether or not ``DPM_FLAG_SMART_SUSPEND`` i
876 needs to be able to cope with the invocation o
877 callback back-to-back with its "late" and "noi
878 that is not a concern if the driver sets both
879 ``DPM_FLAG_MAY_SKIP_RESUME`` and uses the same
880 functions for runtime PM and system-wide suspe
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.