About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / power / devices.txt




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:04 EST.

1	Device Power Management
2	
3	Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
4	Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu>
5	
6	
7	Most of the code in Linux is device drivers, so most of the Linux power
8	management (PM) code is also driver-specific.  Most drivers will do very
9	little; others, especially for platforms with small batteries (like cell
10	phones), will do a lot.
11	
12	This writeup gives an overview of how drivers interact with system-wide
13	power management goals, emphasizing the models and interfaces that are
14	shared by everything that hooks up to the driver model core.  Read it as
15	background for the domain-specific work you'd do with any specific driver.
16	
17	
18	Two Models for Device Power Management
19	======================================
20	Drivers will use one or both of these models to put devices into low-power
21	states:
22	
23	    System Sleep model:
24		Drivers can enter low-power states as part of entering system-wide
25		low-power states like "suspend" (also known as "suspend-to-RAM"), or
26		(mostly for systems with disks) "hibernation" (also known as
27		"suspend-to-disk").
28	
29		This is something that device, bus, and class drivers collaborate on
30		by implementing various role-specific suspend and resume methods to
31		cleanly power down hardware and software subsystems, then reactivate
32		them without loss of data.
33	
34		Some drivers can manage hardware wakeup events, which make the system
35		leave the low-power state.  This feature may be enabled or disabled
36		using the relevant /sys/devices/.../power/wakeup file (for Ethernet
37		drivers the ioctl interface used by ethtool may also be used for this
38		purpose); enabling it may cost some power usage, but let the whole
39		system enter low-power states more often.
40	
41	    Runtime Power Management model:
42		Devices may also be put into low-power states while the system is
43		running, independently of other power management activity in principle.
44		However, devices are not generally independent of each other (for
45		example, a parent device cannot be suspended unless all of its child
46		devices have been suspended).  Moreover, depending on the bus type the
47		device is on, it may be necessary to carry out some bus-specific
48		operations on the device for this purpose.  Devices put into low power
49		states at run time may require special handling during system-wide power
50		transitions (suspend or hibernation).
51	
52		For these reasons not only the device driver itself, but also the
53		appropriate subsystem (bus type, device type or device class) driver and
54		the PM core are involved in runtime power management.  As in the system
55		sleep power management case, they need to collaborate by implementing
56		various role-specific suspend and resume methods, so that the hardware
57		is cleanly powered down and reactivated without data or service loss.
58	
59	There's not a lot to be said about those low-power states except that they are
60	very system-specific, and often device-specific.  Also, that if enough devices
61	have been put into low-power states (at runtime), the effect may be very similar
62	to entering some system-wide low-power state (system sleep) ... and that
63	synergies exist, so that several drivers using runtime PM might put the system
64	into a state where even deeper power saving options are available.
65	
66	Most suspended devices will have quiesced all I/O: no more DMA or IRQs (except
67	for wakeup events), no more data read or written, and requests from upstream
68	drivers are no longer accepted.  A given bus or platform may have different
69	requirements though.
70	
71	Examples of hardware wakeup events include an alarm from a real time clock,
72	network wake-on-LAN packets, keyboard or mouse activity, and media insertion
73	or removal (for PCMCIA, MMC/SD, USB, and so on).
74	
75	
76	Interfaces for Entering System Sleep States
77	===========================================
78	There are programming interfaces provided for subsystems (bus type, device type,
79	device class) and device drivers to allow them to participate in the power
80	management of devices they are concerned with.  These interfaces cover both
81	system sleep and runtime power management.
82	
83	
84	Device Power Management Operations
85	----------------------------------
86	Device power management operations, at the subsystem level as well as at the
87	device driver level, are implemented by defining and populating objects of type
88	struct dev_pm_ops:
89	
90	struct dev_pm_ops {
91		int (*prepare)(struct device *dev);
92		void (*complete)(struct device *dev);
93		int (*suspend)(struct device *dev);
94		int (*resume)(struct device *dev);
95		int (*freeze)(struct device *dev);
96		int (*thaw)(struct device *dev);
97		int (*poweroff)(struct device *dev);
98		int (*restore)(struct device *dev);
99		int (*suspend_late)(struct device *dev);
100		int (*resume_early)(struct device *dev);
101		int (*freeze_late)(struct device *dev);
102		int (*thaw_early)(struct device *dev);
103		int (*poweroff_late)(struct device *dev);
104		int (*restore_early)(struct device *dev);
105		int (*suspend_noirq)(struct device *dev);
106		int (*resume_noirq)(struct device *dev);
107		int (*freeze_noirq)(struct device *dev);
108		int (*thaw_noirq)(struct device *dev);
109		int (*poweroff_noirq)(struct device *dev);
110		int (*restore_noirq)(struct device *dev);
111		int (*runtime_suspend)(struct device *dev);
112		int (*runtime_resume)(struct device *dev);
113		int (*runtime_idle)(struct device *dev);
114	};
115	
116	This structure is defined in include/linux/pm.h and the methods included in it
117	are also described in that file.  Their roles will be explained in what follows.
118	For now, it should be sufficient to remember that the last three methods are
119	specific to runtime power management while the remaining ones are used during
120	system-wide power transitions.
121	
122	There also is a deprecated "old" or "legacy" interface for power management
123	operations available at least for some subsystems.  This approach does not use
124	struct dev_pm_ops objects and it is suitable only for implementing system sleep
125	power management methods.  Therefore it is not described in this document, so
126	please refer directly to the source code for more information about it.
127	
128	
129	Subsystem-Level Methods
130	-----------------------
131	The core methods to suspend and resume devices reside in struct dev_pm_ops
132	pointed to by the ops member of struct dev_pm_domain, or by the pm member of
133	struct bus_type, struct device_type and struct class.  They are mostly of
134	interest to the people writing infrastructure for platforms and buses, like PCI
135	or USB, or device type and device class drivers.  They also are relevant to the
136	writers of device drivers whose subsystems (PM domains, device types, device
137	classes and bus types) don't provide all power management methods.
138	
139	Bus drivers implement these methods as appropriate for the hardware and the
140	drivers using it; PCI works differently from USB, and so on.  Not many people
141	write subsystem-level drivers; most driver code is a "device driver" that builds
142	on top of bus-specific framework code.
143	
144	For more information on these driver calls, see the description later;
145	they are called in phases for every device, respecting the parent-child
146	sequencing in the driver model tree.
147	
148	
149	/sys/devices/.../power/wakeup files
150	-----------------------------------
151	All device objects in the driver model contain fields that control the handling
152	of system wakeup events (hardware signals that can force the system out of a
153	sleep state).  These fields are initialized by bus or device driver code using
154	device_set_wakeup_capable() and device_set_wakeup_enable(), defined in
155	include/linux/pm_wakeup.h.
156	
157	The "power.can_wakeup" flag just records whether the device (and its driver) can
158	physically support wakeup events.  The device_set_wakeup_capable() routine
159	affects this flag.  The "power.wakeup" field is a pointer to an object of type
160	struct wakeup_source used for controlling whether or not the device should use
161	its system wakeup mechanism and for notifying the PM core of system wakeup
162	events signaled by the device.  This object is only present for wakeup-capable
163	devices (i.e. devices whose "can_wakeup" flags are set) and is created (or
164	removed) by device_set_wakeup_capable().
165	
166	Whether or not a device is capable of issuing wakeup events is a hardware
167	matter, and the kernel is responsible for keeping track of it.  By contrast,
168	whether or not a wakeup-capable device should issue wakeup events is a policy
169	decision, and it is managed by user space through a sysfs attribute: the
170	"power/wakeup" file.  User space can write the strings "enabled" or "disabled"
171	to it to indicate whether or not, respectively, the device is supposed to signal
172	system wakeup.  This file is only present if the "power.wakeup" object exists
173	for the given device and is created (or removed) along with that object, by
174	device_set_wakeup_capable().  Reads from the file will return the corresponding
175	string.
176	
177	The "power/wakeup" file is supposed to contain the "disabled" string initially
178	for the majority of devices; the major exceptions are power buttons, keyboards,
179	and Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with
180	ethtool.  It should also default to "enabled" for devices that don't generate
181	wakeup requests on their own but merely forward wakeup requests from one bus to
182	another (like PCI Express ports).
183	
184	The device_may_wakeup() routine returns true only if the "power.wakeup" object
185	exists and the corresponding "power/wakeup" file contains the string "enabled".
186	This information is used by subsystems, like the PCI bus type code, to see
187	whether or not to enable the devices' wakeup mechanisms.  If device wakeup
188	mechanisms are enabled or disabled directly by drivers, they also should use
189	device_may_wakeup() to decide what to do during a system sleep transition.
190	Device drivers, however, are not supposed to call device_set_wakeup_enable()
191	directly in any case.
192	
193	It ought to be noted that system wakeup is conceptually different from "remote
194	wakeup" used by runtime power management, although it may be supported by the
195	same physical mechanism.  Remote wakeup is a feature allowing devices in
196	low-power states to trigger specific interrupts to signal conditions in which
197	they should be put into the full-power state.  Those interrupts may or may not
198	be used to signal system wakeup events, depending on the hardware design.  On
199	some systems it is impossible to trigger them from system sleep states.  In any
200	case, remote wakeup should always be enabled for runtime power management for
201	all devices and drivers that support it.
202	
203	/sys/devices/.../power/control files
204	------------------------------------
205	Each device in the driver model has a flag to control whether it is subject to
206	runtime power management.  This flag, called runtime_auto, is initialized by the
207	bus type (or generally subsystem) code using pm_runtime_allow() or
208	pm_runtime_forbid(); the default is to allow runtime power management.
209	
210	The setting can be adjusted by user space by writing either "on" or "auto" to
211	the device's power/control sysfs file.  Writing "auto" calls pm_runtime_allow(),
212	setting the flag and allowing the device to be runtime power-managed by its
213	driver.  Writing "on" calls pm_runtime_forbid(), clearing the flag, returning
214	the device to full power if it was in a low-power state, and preventing the
215	device from being runtime power-managed.  User space can check the current value
216	of the runtime_auto flag by reading the file.
217	
218	The device's runtime_auto flag has no effect on the handling of system-wide
219	power transitions.  In particular, the device can (and in the majority of cases
220	should and will) be put into a low-power state during a system-wide transition
221	to a sleep state even though its runtime_auto flag is clear.
222	
223	For more information about the runtime power management framework, refer to
224	Documentation/power/runtime_pm.txt.
225	
226	
227	Calling Drivers to Enter and Leave System Sleep States
228	======================================================
229	When the system goes into a sleep state, each device's driver is asked to
230	suspend the device by putting it into a state compatible with the target
231	system state.  That's usually some version of "off", but the details are
232	system-specific.  Also, wakeup-enabled devices will usually stay partly
233	functional in order to wake the system.
234	
235	When the system leaves that low-power state, the device's driver is asked to
236	resume it by returning it to full power.  The suspend and resume operations
237	always go together, and both are multi-phase operations.
238	
239	For simple drivers, suspend might quiesce the device using class code
240	and then turn its hardware as "off" as possible during suspend_noirq.  The
241	matching resume calls would then completely reinitialize the hardware
242	before reactivating its class I/O queues.
243	
244	More power-aware drivers might prepare the devices for triggering system wakeup
245	events.
246	
247	
248	Call Sequence Guarantees
249	------------------------
250	To ensure that bridges and similar links needing to talk to a device are
251	available when the device is suspended or resumed, the device tree is
252	walked in a bottom-up order to suspend devices.  A top-down order is
253	used to resume those devices.
254	
255	The ordering of the device tree is defined by the order in which devices
256	get registered:  a child can never be registered, probed or resumed before
257	its parent; and can't be removed or suspended after that parent.
258	
259	The policy is that the device tree should match hardware bus topology.
260	(Or at least the control bus, for devices which use multiple busses.)
261	In particular, this means that a device registration may fail if the parent of
262	the device is suspending (i.e. has been chosen by the PM core as the next
263	device to suspend) or has already suspended, as well as after all of the other
264	devices have been suspended.  Device drivers must be prepared to cope with such
265	situations.
266	
267	
268	System Power Management Phases
269	------------------------------
270	Suspending or resuming the system is done in several phases.  Different phases
271	are used for freeze, standby, and memory sleep states ("suspend-to-RAM") and the
272	hibernation state ("suspend-to-disk").  Each phase involves executing callbacks
273	for every device before the next phase begins.  Not all busses or classes
274	support all these callbacks and not all drivers use all the callbacks.  The
275	various phases always run after tasks have been frozen and before they are
276	unfrozen.  Furthermore, the *_noirq phases run at a time when IRQ handlers have
277	been disabled (except for those marked with the IRQF_NO_SUSPEND flag).
278	
279	All phases use PM domain, bus, type, class or driver callbacks (that is, methods
280	defined in dev->pm_domain->ops, dev->bus->pm, dev->type->pm, dev->class->pm or
281	dev->driver->pm).  These callbacks are regarded by the PM core as mutually
282	exclusive.  Moreover, PM domain callbacks always take precedence over all of the
283	other callbacks and, for example, type callbacks take precedence over bus, class
284	and driver callbacks.  To be precise, the following rules are used to determine
285	which callback to execute in the given phase:
286	
287	    1.	If dev->pm_domain is present, the PM core will choose the callback
288		included in dev->pm_domain->ops for execution
289	
290	    2.	Otherwise, if both dev->type and dev->type->pm are present, the callback
291		included in dev->type->pm will be chosen for execution.
292	
293	    3.	Otherwise, if both dev->class and dev->class->pm are present, the
294		callback included in dev->class->pm will be chosen for execution.
295	
296	    4.	Otherwise, if both dev->bus and dev->bus->pm are present, the callback
297		included in dev->bus->pm will be chosen for execution.
298	
299	This allows PM domains and device types to override callbacks provided by bus
300	types or device classes if necessary.
301	
302	The PM domain, type, class and bus callbacks may in turn invoke device- or
303	driver-specific methods stored in dev->driver->pm, but they don't have to do
304	that.
305	
306	If the subsystem callback chosen for execution is not present, the PM core will
307	execute the corresponding method from dev->driver->pm instead if there is one.
308	
309	
310	Entering System Suspend
311	-----------------------
312	When the system goes into the freeze, standby or memory sleep state,
313	the phases are:
314	
315			prepare, suspend, suspend_late, suspend_noirq.
316	
317	    1.	The prepare phase is meant to prevent races by preventing new devices
318		from being registered; the PM core would never know that all the
319		children of a device had been suspended if new children could be
320		registered at will.  (By contrast, devices may be unregistered at any
321		time.)  Unlike the other suspend-related phases, during the prepare
322		phase the device tree is traversed top-down.
323	
324		After the prepare callback method returns, no new children may be
325		registered below the device.  The method may also prepare the device or
326		driver in some way for the upcoming system power transition, but it
327		should not put the device into a low-power state.
328	
329	    2.	The suspend methods should quiesce the device to stop it from performing
330		I/O.  They also may save the device registers and put it into the
331		appropriate low-power state, depending on the bus type the device is on,
332		and they may enable wakeup events.
333	
334	    3	For a number of devices it is convenient to split suspend into the
335		"quiesce device" and "save device state" phases, in which cases
336		suspend_late is meant to do the latter.  It is always executed after
337		runtime power management has been disabled for all devices.
338	
339	    4.	The suspend_noirq phase occurs after IRQ handlers have been disabled,
340		which means that the driver's interrupt handler will not be called while
341		the callback method is running.  The methods should save the values of
342		the device's registers that weren't saved previously and finally put the
343		device into the appropriate low-power state.
344	
345		The majority of subsystems and device drivers need not implement this
346		callback.  However, bus types allowing devices to share interrupt
347		vectors, like PCI, generally need it; otherwise a driver might encounter
348		an error during the suspend phase by fielding a shared interrupt
349		generated by some other device after its own device had been set to low
350		power.
351	
352	At the end of these phases, drivers should have stopped all I/O transactions
353	(DMA, IRQs), saved enough state that they can re-initialize or restore previous
354	state (as needed by the hardware), and placed the device into a low-power state.
355	On many platforms they will gate off one or more clock sources; sometimes they
356	will also switch off power supplies or reduce voltages.  (Drivers supporting
357	runtime PM may already have performed some or all of these steps.)
358	
359	If device_may_wakeup(dev) returns true, the device should be prepared for
360	generating hardware wakeup signals to trigger a system wakeup event when the
361	system is in the sleep state.  For example, enable_irq_wake() might identify
362	GPIO signals hooked up to a switch or other external hardware, and
363	pci_enable_wake() does something similar for the PCI PME signal.
364	
365	If any of these callbacks returns an error, the system won't enter the desired
366	low-power state.  Instead the PM core will unwind its actions by resuming all
367	the devices that were suspended.
368	
369	
370	Leaving System Suspend
371	----------------------
372	When resuming from freeze, standby or memory sleep, the phases are:
373	
374			resume_noirq, resume_early, resume, complete.
375	
376	    1.	The resume_noirq callback methods should perform any actions needed
377		before the driver's interrupt handlers are invoked.  This generally
378		means undoing the actions of the suspend_noirq phase.  If the bus type
379		permits devices to share interrupt vectors, like PCI, the method should
380		bring the device and its driver into a state in which the driver can
381		recognize if the device is the source of incoming interrupts, if any,
382		and handle them correctly.
383	
384		For example, the PCI bus type's ->pm.resume_noirq() puts the device into
385		the full-power state (D0 in the PCI terminology) and restores the
386		standard configuration registers of the device.  Then it calls the
387		device driver's ->pm.resume_noirq() method to perform device-specific
388		actions.
389	
390	    2.	The resume_early methods should prepare devices for the execution of
391		the resume methods.  This generally involves undoing the actions of the
392		preceding suspend_late phase.
393	
394	    3	The resume methods should bring the the device back to its operating
395		state, so that it can perform normal I/O.  This generally involves
396		undoing the actions of the suspend phase.
397	
398	    4.	The complete phase should undo the actions of the prepare phase.  Note,
399		however, that new children may be registered below the device as soon as
400		the resume callbacks occur; it's not necessary to wait until the
401		complete phase.
402	
403	At the end of these phases, drivers should be as functional as they were before
404	suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are
405	gated on.  Even if the device was in a low-power state before the system sleep
406	because of runtime power management, afterwards it should be back in its
407	full-power state.  There are multiple reasons why it's best to do this; they are
408	discussed in more detail in Documentation/power/runtime_pm.txt.
409	
410	However, the details here may again be platform-specific.  For example,
411	some systems support multiple "run" states, and the mode in effect at
412	the end of resume might not be the one which preceded suspension.
413	That means availability of certain clocks or power supplies changed,
414	which could easily affect how a driver works.
415	
416	Drivers need to be able to handle hardware which has been reset since the
417	suspend methods were called, for example by complete reinitialization.
418	This may be the hardest part, and the one most protected by NDA'd documents
419	and chip errata.  It's simplest if the hardware state hasn't changed since
420	the suspend was carried out, but that can't be guaranteed (in fact, it usually
421	is not the case).
422	
423	Drivers must also be prepared to notice that the device has been removed
424	while the system was powered down, whenever that's physically possible.
425	PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses
426	where common Linux platforms will see such removal.  Details of how drivers
427	will notice and handle such removals are currently bus-specific, and often
428	involve a separate thread.
429	
430	These callbacks may return an error value, but the PM core will ignore such
431	errors since there's nothing it can do about them other than printing them in
432	the system log.
433	
434	
435	Entering Hibernation
436	--------------------
437	Hibernating the system is more complicated than putting it into the other
438	sleep states, because it involves creating and saving a system image.
439	Therefore there are more phases for hibernation, with a different set of
440	callbacks.  These phases always run after tasks have been frozen and memory has
441	been freed.
442	
443	The general procedure for hibernation is to quiesce all devices (freeze), create
444	an image of the system memory while everything is stable, reactivate all
445	devices (thaw), write the image to permanent storage, and finally shut down the
446	system (poweroff).  The phases used to accomplish this are:
447	
448		prepare, freeze, freeze_late, freeze_noirq, thaw_noirq, thaw_early,
449		thaw, complete, prepare, poweroff, poweroff_late, poweroff_noirq
450	
451	    1.	The prepare phase is discussed in the "Entering System Suspend" section
452		above.
453	
454	    2.	The freeze methods should quiesce the device so that it doesn't generate
455		IRQs or DMA, and they may need to save the values of device registers.
456		However the device does not have to be put in a low-power state, and to
457		save time it's best not to do so.  Also, the device should not be
458		prepared to generate wakeup events.
459	
460	    3.	The freeze_late phase is analogous to the suspend_late phase described
461		above, except that the device should not be put in a low-power state and
462		should not be allowed to generate wakeup events by it.
463	
464	    4.	The freeze_noirq phase is analogous to the suspend_noirq phase discussed
465		above, except again that the device should not be put in a low-power
466		state and should not be allowed to generate wakeup events.
467	
468	At this point the system image is created.  All devices should be inactive and
469	the contents of memory should remain undisturbed while this happens, so that the
470	image forms an atomic snapshot of the system state.
471	
472	    5.	The thaw_noirq phase is analogous to the resume_noirq phase discussed
473		above.  The main difference is that its methods can assume the device is
474		in the same state as at the end of the freeze_noirq phase.
475	
476	    6.	The thaw_early phase is analogous to the resume_early phase described
477		above.  Its methods should undo the actions of the preceding
478		freeze_late, if necessary.
479	
480	    7.	The thaw phase is analogous to the resume phase discussed above.  Its
481		methods should bring the device back to an operating state, so that it
482		can be used for saving the image if necessary.
483	
484	    8.	The complete phase is discussed in the "Leaving System Suspend" section
485		above.
486	
487	At this point the system image is saved, and the devices then need to be
488	prepared for the upcoming system shutdown.  This is much like suspending them
489	before putting the system into the freeze, standby or memory sleep state,
490	and the phases are similar.
491	
492	    9.	The prepare phase is discussed above.
493	
494	    10.	The poweroff phase is analogous to the suspend phase.
495	
496	    11.	The poweroff_late phase is analogous to the suspend_late phase.
497	
498	    12.	The poweroff_noirq phase is analogous to the suspend_noirq phase.
499	
500	The poweroff, poweroff_late and poweroff_noirq callbacks should do essentially
501	the same things as the suspend, suspend_late and suspend_noirq callbacks,
502	respectively.  The only notable difference is that they need not store the
503	device register values, because the registers should already have been stored
504	during the freeze, freeze_late or freeze_noirq phases.
505	
506	
507	Leaving Hibernation
508	-------------------
509	Resuming from hibernation is, again, more complicated than resuming from a sleep
510	state in which the contents of main memory are preserved, because it requires
511	a system image to be loaded into memory and the pre-hibernation memory contents
512	to be restored before control can be passed back to the image kernel.
513	
514	Although in principle, the image might be loaded into memory and the
515	pre-hibernation memory contents restored by the boot loader, in practice this
516	can't be done because boot loaders aren't smart enough and there is no
517	established protocol for passing the necessary information.  So instead, the
518	boot loader loads a fresh instance of the kernel, called the boot kernel, into
519	memory and passes control to it in the usual way.  Then the boot kernel reads
520	the system image, restores the pre-hibernation memory contents, and passes
521	control to the image kernel.  Thus two different kernels are involved in
522	resuming from hibernation.  In fact, the boot kernel may be completely different
523	from the image kernel: a different configuration and even a different version.
524	This has important consequences for device drivers and their subsystems.
525	
526	To be able to load the system image into memory, the boot kernel needs to
527	include at least a subset of device drivers allowing it to access the storage
528	medium containing the image, although it doesn't need to include all of the
529	drivers present in the image kernel.  After the image has been loaded, the
530	devices managed by the boot kernel need to be prepared for passing control back
531	to the image kernel.  This is very similar to the initial steps involved in
532	creating a system image, and it is accomplished in the same way, using prepare,
533	freeze, and freeze_noirq phases.  However the devices affected by these phases
534	are only those having drivers in the boot kernel; other devices will still be in
535	whatever state the boot loader left them.
536	
537	Should the restoration of the pre-hibernation memory contents fail, the boot
538	kernel would go through the "thawing" procedure described above, using the
539	thaw_noirq, thaw, and complete phases, and then continue running normally.  This
540	happens only rarely.  Most often the pre-hibernation memory contents are
541	restored successfully and control is passed to the image kernel, which then
542	becomes responsible for bringing the system back to the working state.
543	
544	To achieve this, the image kernel must restore the devices' pre-hibernation
545	functionality.  The operation is much like waking up from the memory sleep
546	state, although it involves different phases:
547	
548		restore_noirq, restore_early, restore, complete
549	
550	    1.	The restore_noirq phase is analogous to the resume_noirq phase.
551	
552	    2.	The restore_early phase is analogous to the resume_early phase.
553	
554	    3.	The restore phase is analogous to the resume phase.
555	
556	    4.	The complete phase is discussed above.
557	
558	The main difference from resume[_early|_noirq] is that restore[_early|_noirq]
559	must assume the device has been accessed and reconfigured by the boot loader or
560	the boot kernel.  Consequently the state of the device may be different from the
561	state remembered from the freeze, freeze_late and freeze_noirq phases.  The
562	device may even need to be reset and completely re-initialized.  In many cases
563	this difference doesn't matter, so the resume[_early|_noirq] and
564	restore[_early|_norq] method pointers can be set to the same routines.
565	Nevertheless, different callback pointers are used in case there is a situation
566	where it actually does matter.
567	
568	
569	Device Power Management Domains
570	-------------------------------
571	Sometimes devices share reference clocks or other power resources.  In those
572	cases it generally is not possible to put devices into low-power states
573	individually.  Instead, a set of devices sharing a power resource can be put
574	into a low-power state together at the same time by turning off the shared
575	power resource.  Of course, they also need to be put into the full-power state
576	together, by turning the shared power resource on.  A set of devices with this
577	property is often referred to as a power domain.
578	
579	Support for power domains is provided through the pm_domain field of struct
580	device.  This field is a pointer to an object of type struct dev_pm_domain,
581	defined in include/linux/pm.h, providing a set of power management callbacks
582	analogous to the subsystem-level and device driver callbacks that are executed
583	for the given device during all power transitions, instead of the respective
584	subsystem-level callbacks.  Specifically, if a device's pm_domain pointer is
585	not NULL, the ->suspend() callback from the object pointed to by it will be
586	executed instead of its subsystem's (e.g. bus type's) ->suspend() callback and
587	analogously for all of the remaining callbacks.  In other words, power
588	management domain callbacks, if defined for the given device, always take
589	precedence over the callbacks provided by the device's subsystem (e.g. bus
590	type).
591	
592	The support for device power management domains is only relevant to platforms
593	needing to use the same device driver power management callbacks in many
594	different power domain configurations and wanting to avoid incorporating the
595	support for power domains into subsystem-level callbacks, for example by
596	modifying the platform bus type.  Other platforms need not implement it or take
597	it into account in any way.
598	
599	
600	Device Low Power (suspend) States
601	---------------------------------
602	Device low-power states aren't standard.  One device might only handle
603	"on" and "off", while another might support a dozen different versions of
604	"on" (how many engines are active?), plus a state that gets back to "on"
605	faster than from a full "off".
606	
607	Some busses define rules about what different suspend states mean.  PCI
608	gives one example:  after the suspend sequence completes, a non-legacy
609	PCI device may not perform DMA or issue IRQs, and any wakeup events it
610	issues would be issued through the PME# bus signal.  Plus, there are
611	several PCI-standard device states, some of which are optional.
612	
613	In contrast, integrated system-on-chip processors often use IRQs as the
614	wakeup event sources (so drivers would call enable_irq_wake) and might
615	be able to treat DMA completion as a wakeup event (sometimes DMA can stay
616	active too, it'd only be the CPU and some peripherals that sleep).
617	
618	Some details here may be platform-specific.  Systems may have devices that
619	can be fully active in certain sleep states, such as an LCD display that's
620	refreshed using DMA while most of the system is sleeping lightly ... and
621	its frame buffer might even be updated by a DSP or other non-Linux CPU while
622	the Linux control processor stays idle.
623	
624	Moreover, the specific actions taken may depend on the target system state.
625	One target system state might allow a given device to be very operational;
626	another might require a hard shut down with re-initialization on resume.
627	And two different target systems might use the same device in different
628	ways; the aforementioned LCD might be active in one product's "standby",
629	but a different product using the same SOC might work differently.
630	
631	
632	Power Management Notifiers
633	--------------------------
634	There are some operations that cannot be carried out by the power management
635	callbacks discussed above, because the callbacks occur too late or too early.
636	To handle these cases, subsystems and device drivers may register power
637	management notifiers that are called before tasks are frozen and after they have
638	been thawed.  Generally speaking, the PM notifiers are suitable for performing
639	actions that either require user space to be available, or at least won't
640	interfere with user space.
641	
642	For details refer to Documentation/power/notifiers.txt.
643	
644	
645	Runtime Power Management
646	========================
647	Many devices are able to dynamically power down while the system is still
648	running. This feature is useful for devices that are not being used, and
649	can offer significant power savings on a running system.  These devices
650	often support a range of runtime power states, which might use names such
651	as "off", "sleep", "idle", "active", and so on.  Those states will in some
652	cases (like PCI) be partially constrained by the bus the device uses, and will
653	usually include hardware states that are also used in system sleep states.
654	
655	A system-wide power transition can be started while some devices are in low
656	power states due to runtime power management.  The system sleep PM callbacks
657	should recognize such situations and react to them appropriately, but the
658	necessary actions are subsystem-specific.
659	
660	In some cases the decision may be made at the subsystem level while in other
661	cases the device driver may be left to decide.  In some cases it may be
662	desirable to leave a suspended device in that state during a system-wide power
663	transition, but in other cases the device must be put back into the full-power
664	state temporarily, for example so that its system wakeup capability can be
665	disabled.  This all depends on the hardware and the design of the subsystem and
666	device driver in question.
667	
668	During system-wide resume from a sleep state it's easiest to put devices into
669	the full-power state, as explained in Documentation/power/runtime_pm.txt.  Refer
670	to that document for more information regarding this particular issue as well as
671	for information on the device runtime power management framework in general.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.