blob: 73fc87e5dc382013207ccbf5c2989eb0e1240abf [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
2PCI Power Management
3~~~~~~~~~~~~~~~~~~~~
4
5An overview of the concepts and the related functions in the Linux kernel
6
7Patrick Mochel <mochel@transmeta.com>
8(and others)
9
10---------------------------------------------------------------------------
11
121. Overview
132. How the PCI Subsystem Does Power Management
143. PCI Utility Functions
154. PCI Device Drivers
165. Resources
17
181. Overview
19~~~~~~~~~~~
20
21The PCI Power Management Specification was introduced between the PCI 2.1 and
22PCI 2.2 Specifications. It a standard interface for controlling various
23power management operations.
24
25Implementation of the PCI PM Spec is optional, as are several sub-components of
26it. If a device supports the PCI PM Spec, the device will have an 8 byte
27capability field in its PCI configuration space. This field is used to describe
28and control the standard PCI power management features.
29
30The PCI PM spec defines 4 operating states for devices (D0 - D3) and for buses
31(B0 - B3). The higher the number, the less power the device consumes. However,
32the higher the number, the longer the latency is for the device to return to
33an operational state (D0).
34
35There are actually two D3 states. When someone talks about D3, they usually
36mean D3hot, which corresponds to an ACPI D2 state (power is reduced, the
37device may lose some context). But they may also mean D3cold, which is an
38ACPI D3 state (power is fully off, all state was discarded); or both.
39
40Bus power management is not covered in this version of this document.
41
42Note that all PCI devices support D0 and D3cold by default, regardless of
43whether or not they implement any of the PCI PM spec.
44
45The possible state transitions that a device can undergo are:
46
47+---------------------------+
48| Current State | New State |
49+---------------------------+
50| D0 | D1, D2, D3|
51+---------------------------+
52| D1 | D2, D3 |
53+---------------------------+
54| D2 | D3 |
55+---------------------------+
56| D1, D2, D3 | D0 |
57+---------------------------+
58
59Note that when the system is entering a global suspend state, all devices will
60be placed into D3 and when resuming, all devices will be placed into D0.
61However, when the system is running, other state transitions are possible.
62
632. How The PCI Subsystem Handles Power Management
64~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
65
66The PCI suspend/resume functionality is accessed indirectly via the Power
67Management subsystem. At boot, the PCI driver registers a power management
68callback with that layer. Upon entering a suspend state, the PM layer iterates
69through all of its registered callbacks. This currently takes place only during
70APM state transitions.
71
72Upon going to sleep, the PCI subsystem walks its device tree twice. Both times,
73it does a depth first walk of the device tree. The first walk saves each of the
74device's state and checks for devices that will prevent the system from entering
75a global power state. The next walk then places the devices in a low power
76state.
77
78The first walk allows a graceful recovery in the event of a failure, since none
79of the devices have actually been powered down.
80
81In both walks, in particular the second, all children of a bridge are touched
82before the actual bridge itself. This allows the bridge to retain power while
83its children are being accessed.
84
85Upon resuming from sleep, just the opposite must be true: all bridges must be
86powered on and restored before their children are powered on. This is easily
87accomplished with a breadth-first walk of the PCI device tree.
88
89
903. PCI Utility Functions
91~~~~~~~~~~~~~~~~~~~~~~~~
92
93These are helper functions designed to be called by individual device drivers.
94Assuming that a device behaves as advertised, these should be applicable in most
95cases. However, results may vary.
96
97Note that these functions are never implicitly called for the driver. The driver
98is always responsible for deciding when and if to call these.
99
100
101pci_save_state
102--------------
103
104Usage:
105 pci_save_state(dev, buffer);
106
107Description:
108 Save first 64 bytes of PCI config space. Buffer must be allocated by
109 caller.
110
111
112pci_restore_state
113-----------------
114
115Usage:
116 pci_restore_state(dev, buffer);
117
118Description:
119 Restore previously saved config space. (First 64 bytes only);
120
121 If buffer is NULL, then restore what information we know about the
122 device from bootup: BARs and interrupt line.
123
124
125pci_set_power_state
126-------------------
127
128Usage:
129 pci_set_power_state(dev, state);
130
131Description:
132 Transition device to low power state using PCI PM Capabilities
133 registers.
134
135 Will fail under one of the following conditions:
136 - If state is less than current state, but not D0 (illegal transition)
137 - Device doesn't support PM Capabilities
138 - Device does not support requested state
139
140
141pci_enable_wake
142---------------
143
144Usage:
145 pci_enable_wake(dev, state, enable);
146
147Description:
148 Enable device to generate PME# during low power state using PCI PM
149 Capabilities.
150
151 Checks whether if device supports generating PME# from requested state
152 and fail if it does not, unless enable == 0 (request is to disable wake
153 events, which is implicit if it doesn't even support it in the first
154 place).
155
156 Note that the PMC Register in the device's PM Capabilties has a bitmask
157 of the states it supports generating PME# from. D3hot is bit 3 and
158 D3cold is bit 4. So, while a value of 4 as the state may not seem
159 semantically correct, it is.
160
161
1624. PCI Device Drivers
163~~~~~~~~~~~~~~~~~~~~~
164
165These functions are intended for use by individual drivers, and are defined in
166struct pci_driver:
167
Pavel Machek92df5162005-04-05 23:49:49 +0200168 int (*suspend) (struct pci_dev *dev, pm_message_t state);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700169 int (*resume) (struct pci_dev *dev);
Pavel Machek92df5162005-04-05 23:49:49 +0200170 int (*enable_wake) (struct pci_dev *dev, pci_power_t state, int enable);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700171
172
173suspend
174-------
175
176Usage:
177
178if (dev->driver && dev->driver->suspend)
179 dev->driver->suspend(dev,state);
180
181A driver uses this function to actually transition the device into a low power
182state. This should include disabling I/O, IRQs, and bus-mastering, as well as
183physically transitioning the device to a lower power state; it may also include
184calls to pci_enable_wake().
185
186Bus mastering may be disabled by doing:
187
188pci_disable_device(dev);
189
190For devices that support the PCI PM Spec, this may be used to set the device's
191power state to match the suspend() parameter:
192
193pci_set_power_state(dev,state);
194
195The driver is also responsible for disabling any other device-specific features
196(e.g blanking screen, turning off on-card memory, etc).
197
198The driver should be sure to track the current state of the device, as it may
199obviate the need for some operations.
200
201The driver should update the current_state field in its pci_dev structure in
202this function, except for PM-capable devices when pci_set_power_state is used.
203
204resume
205------
206
207Usage:
208
209if (dev->driver && dev->driver->suspend)
210 dev->driver->resume(dev)
211
212The resume callback may be called from any power state, and is always meant to
213transition the device to the D0 state.
214
215The driver is responsible for reenabling any features of the device that had
216been disabled during previous suspend calls, such as IRQs and bus mastering,
217as well as calling pci_restore_state().
218
219If the device is currently in D3, it may need to be reinitialized in resume().
220
221 * Some types of devices, like bus controllers, will preserve context in D3hot
222 (using Vcc power). Their drivers will often want to avoid re-initializing
223 them after re-entering D0 (perhaps to avoid resetting downstream devices).
224
225 * Other kinds of devices in D3hot will discard device context as part of a
226 soft reset when re-entering the D0 state.
227
228 * Devices resuming from D3cold always go through a power-on reset. Some
229 device context can also be preserved using Vaux power.
230
231 * Some systems hide D3cold resume paths from drivers. For example, on PCs
232 the resume path for suspend-to-disk often runs BIOS powerup code, which
233 will sometimes re-initialize the device.
234
235To handle resets during D3 to D0 transitions, it may be convenient to share
236device initialization code between probe() and resume(). Device parameters
237can also be saved before the driver suspends into D3, avoiding re-probe.
238
239If the device supports the PCI PM Spec, it can use this to physically transition
240the device to D0:
241
242pci_set_power_state(dev,0);
243
244Note that if the entire system is transitioning out of a global sleep state, all
245devices will be placed in the D0 state, so this is not necessary. However, in
246the event that the device is placed in the D3 state during normal operation,
247this call is necessary. It is impossible to determine which of the two events is
248taking place in the driver, so it is always a good idea to make that call.
249
250The driver should take note of the state that it is resuming from in order to
251ensure correct (and speedy) operation.
252
253The driver should update the current_state field in its pci_dev structure in
254this function, except for PM-capable devices when pci_set_power_state is used.
255
256
257enable_wake
258-----------
259
260Usage:
261
262if (dev->driver && dev->driver->enable_wake)
263 dev->driver->enable_wake(dev,state,enable);
264
265This callback is generally only relevant for devices that support the PCI PM
266spec and have the ability to generate a PME# (Power Management Event Signal)
267to wake the system up. (However, it is possible that a device may support
268some non-standard way of generating a wake event on sleep.)
269
270Bits 15:11 of the PMC (Power Mgmt Capabilities) Register in a device's
271PM Capabilties describe what power states the device supports generating a
272wake event from:
273
274+------------------+
275| Bit | State |
276+------------------+
277| 11 | D0 |
278| 12 | D1 |
279| 13 | D2 |
280| 14 | D3hot |
281| 15 | D3cold |
282+------------------+
283
284A device can use this to enable wake events:
285
286 pci_enable_wake(dev,state,enable);
287
288Note that to enable PME# from D3cold, a value of 4 should be passed to
289pci_enable_wake (since it uses an index into a bitmask). If a driver gets
290a request to enable wake events from D3, two calls should be made to
291pci_enable_wake (one for both D3hot and D3cold).
292
293
pavel@ucw.cz21d6b7e2005-06-25 14:55:16 -0700294A reference implementation
295-------------------------
296.suspend()
297{
298 /* driver specific operations */
299
300 /* Disable IRQ */
301 free_irq();
302 /* If using MSI */
303 pci_disable_msi();
304
305 pci_save_state();
306 pci_enable_wake();
307 /* Disable IO/bus master/irq router */
308 pci_disable_device();
309 pci_set_power_state(pci_choose_state());
310}
311
312.resume()
313{
314 pci_set_power_state(PCI_D0);
315 pci_restore_state();
316 /* device's irq possibly is changed, driver should take care */
317 pci_enable_device();
318 pci_set_master();
319
320 /* if using MSI, device's vector possibly is changed */
321 pci_enable_msi();
322
323 request_irq();
324 /* driver specific operations; */
325}
326
327This is a typical implementation. Drivers can slightly change the order
328of the operations in the implementation, ignore some operations or add
329more deriver specific operations in it, but drivers should do something like
330this on the whole.
331
Linus Torvalds1da177e2005-04-16 15:20:36 -07003325. Resources
333~~~~~~~~~~~~
334
335PCI Local Bus Specification
336PCI Bus Power Management Interface Specification
337
Randy Dunlap98766fb2005-11-21 21:32:31 -0800338 http://www.pcisig.com
Linus Torvalds1da177e2005-04-16 15:20:36 -0700339