]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | PCI Power Management | |
3 | ~~~~~~~~~~~~~~~~~~~~ | |
4 | ||
5 | An overview of the concepts and the related functions in the Linux kernel | |
6 | ||
7 | Patrick Mochel <mochel@transmeta.com> | |
8 | (and others) | |
9 | ||
10 | --------------------------------------------------------------------------- | |
11 | ||
12 | 1. Overview | |
13 | 2. How the PCI Subsystem Does Power Management | |
14 | 3. PCI Utility Functions | |
15 | 4. PCI Device Drivers | |
16 | 5. Resources | |
17 | ||
18 | 1. Overview | |
19 | ~~~~~~~~~~~ | |
20 | ||
21 | The PCI Power Management Specification was introduced between the PCI 2.1 and | |
22 | PCI 2.2 Specifications. It a standard interface for controlling various | |
23 | power management operations. | |
24 | ||
25 | Implementation of the PCI PM Spec is optional, as are several sub-components of | |
26 | it. If a device supports the PCI PM Spec, the device will have an 8 byte | |
27 | capability field in its PCI configuration space. This field is used to describe | |
28 | and control the standard PCI power management features. | |
29 | ||
30 | The 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, | |
32 | the higher the number, the longer the latency is for the device to return to | |
33 | an operational state (D0). | |
34 | ||
35 | There are actually two D3 states. When someone talks about D3, they usually | |
36 | mean D3hot, which corresponds to an ACPI D2 state (power is reduced, the | |
37 | device may lose some context). But they may also mean D3cold, which is an | |
38 | ACPI D3 state (power is fully off, all state was discarded); or both. | |
39 | ||
40 | Bus power management is not covered in this version of this document. | |
41 | ||
42 | Note that all PCI devices support D0 and D3cold by default, regardless of | |
43 | whether or not they implement any of the PCI PM spec. | |
44 | ||
45 | The 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 | ||
59 | Note that when the system is entering a global suspend state, all devices will | |
60 | be placed into D3 and when resuming, all devices will be placed into D0. | |
61 | However, when the system is running, other state transitions are possible. | |
62 | ||
63 | 2. How The PCI Subsystem Handles Power Management | |
64 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
65 | ||
66 | The PCI suspend/resume functionality is accessed indirectly via the Power | |
67 | Management subsystem. At boot, the PCI driver registers a power management | |
68 | callback with that layer. Upon entering a suspend state, the PM layer iterates | |
69 | through all of its registered callbacks. This currently takes place only during | |
70 | APM state transitions. | |
71 | ||
72 | Upon going to sleep, the PCI subsystem walks its device tree twice. Both times, | |
73 | it does a depth first walk of the device tree. The first walk saves each of the | |
74 | device's state and checks for devices that will prevent the system from entering | |
75 | a global power state. The next walk then places the devices in a low power | |
76 | state. | |
77 | ||
78 | The first walk allows a graceful recovery in the event of a failure, since none | |
79 | of the devices have actually been powered down. | |
80 | ||
81 | In both walks, in particular the second, all children of a bridge are touched | |
82 | before the actual bridge itself. This allows the bridge to retain power while | |
83 | its children are being accessed. | |
84 | ||
85 | Upon resuming from sleep, just the opposite must be true: all bridges must be | |
86 | powered on and restored before their children are powered on. This is easily | |
87 | accomplished with a breadth-first walk of the PCI device tree. | |
88 | ||
89 | ||
90 | 3. PCI Utility Functions | |
91 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
92 | ||
93 | These are helper functions designed to be called by individual device drivers. | |
94 | Assuming that a device behaves as advertised, these should be applicable in most | |
95 | cases. However, results may vary. | |
96 | ||
97 | Note that these functions are never implicitly called for the driver. The driver | |
98 | is always responsible for deciding when and if to call these. | |
99 | ||
100 | ||
101 | pci_save_state | |
102 | -------------- | |
103 | ||
104 | Usage: | |
105 | pci_save_state(dev, buffer); | |
106 | ||
107 | Description: | |
108 | Save first 64 bytes of PCI config space. Buffer must be allocated by | |
109 | caller. | |
110 | ||
111 | ||
112 | pci_restore_state | |
113 | ----------------- | |
114 | ||
115 | Usage: | |
116 | pci_restore_state(dev, buffer); | |
117 | ||
118 | Description: | |
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 | ||
125 | pci_set_power_state | |
126 | ------------------- | |
127 | ||
128 | Usage: | |
129 | pci_set_power_state(dev, state); | |
130 | ||
131 | Description: | |
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 | ||
141 | pci_enable_wake | |
142 | --------------- | |
143 | ||
144 | Usage: | |
145 | pci_enable_wake(dev, state, enable); | |
146 | ||
147 | Description: | |
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 | ||
162 | 4. PCI Device Drivers | |
163 | ~~~~~~~~~~~~~~~~~~~~~ | |
164 | ||
165 | These functions are intended for use by individual drivers, and are defined in | |
166 | struct pci_driver: | |
167 | ||
92df516e | 168 | int (*suspend) (struct pci_dev *dev, pm_message_t state); |
1da177e4 | 169 | int (*resume) (struct pci_dev *dev); |
92df516e | 170 | int (*enable_wake) (struct pci_dev *dev, pci_power_t state, int enable); |
1da177e4 LT |
171 | |
172 | ||
173 | suspend | |
174 | ------- | |
175 | ||
176 | Usage: | |
177 | ||
178 | if (dev->driver && dev->driver->suspend) | |
179 | dev->driver->suspend(dev,state); | |
180 | ||
181 | A driver uses this function to actually transition the device into a low power | |
182 | state. This should include disabling I/O, IRQs, and bus-mastering, as well as | |
183 | physically transitioning the device to a lower power state; it may also include | |
184 | calls to pci_enable_wake(). | |
185 | ||
186 | Bus mastering may be disabled by doing: | |
187 | ||
188 | pci_disable_device(dev); | |
189 | ||
190 | For devices that support the PCI PM Spec, this may be used to set the device's | |
191 | power state to match the suspend() parameter: | |
192 | ||
193 | pci_set_power_state(dev,state); | |
194 | ||
195 | The driver is also responsible for disabling any other device-specific features | |
196 | (e.g blanking screen, turning off on-card memory, etc). | |
197 | ||
198 | The driver should be sure to track the current state of the device, as it may | |
199 | obviate the need for some operations. | |
200 | ||
201 | The driver should update the current_state field in its pci_dev structure in | |
202 | this function, except for PM-capable devices when pci_set_power_state is used. | |
203 | ||
204 | resume | |
205 | ------ | |
206 | ||
207 | Usage: | |
208 | ||
209 | if (dev->driver && dev->driver->suspend) | |
210 | dev->driver->resume(dev) | |
211 | ||
212 | The resume callback may be called from any power state, and is always meant to | |
213 | transition the device to the D0 state. | |
214 | ||
215 | The driver is responsible for reenabling any features of the device that had | |
216 | been disabled during previous suspend calls, such as IRQs and bus mastering, | |
217 | as well as calling pci_restore_state(). | |
218 | ||
219 | If 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 | ||
235 | To handle resets during D3 to D0 transitions, it may be convenient to share | |
236 | device initialization code between probe() and resume(). Device parameters | |
237 | can also be saved before the driver suspends into D3, avoiding re-probe. | |
238 | ||
239 | If the device supports the PCI PM Spec, it can use this to physically transition | |
240 | the device to D0: | |
241 | ||
242 | pci_set_power_state(dev,0); | |
243 | ||
244 | Note that if the entire system is transitioning out of a global sleep state, all | |
245 | devices will be placed in the D0 state, so this is not necessary. However, in | |
246 | the event that the device is placed in the D3 state during normal operation, | |
247 | this call is necessary. It is impossible to determine which of the two events is | |
248 | taking place in the driver, so it is always a good idea to make that call. | |
249 | ||
250 | The driver should take note of the state that it is resuming from in order to | |
251 | ensure correct (and speedy) operation. | |
252 | ||
253 | The driver should update the current_state field in its pci_dev structure in | |
254 | this function, except for PM-capable devices when pci_set_power_state is used. | |
255 | ||
256 | ||
257 | enable_wake | |
258 | ----------- | |
259 | ||
260 | Usage: | |
261 | ||
262 | if (dev->driver && dev->driver->enable_wake) | |
263 | dev->driver->enable_wake(dev,state,enable); | |
264 | ||
265 | This callback is generally only relevant for devices that support the PCI PM | |
266 | spec and have the ability to generate a PME# (Power Management Event Signal) | |
267 | to wake the system up. (However, it is possible that a device may support | |
268 | some non-standard way of generating a wake event on sleep.) | |
269 | ||
270 | Bits 15:11 of the PMC (Power Mgmt Capabilities) Register in a device's | |
271 | PM Capabilties describe what power states the device supports generating a | |
272 | wake 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 | ||
284 | A device can use this to enable wake events: | |
285 | ||
286 | pci_enable_wake(dev,state,enable); | |
287 | ||
288 | Note that to enable PME# from D3cold, a value of 4 should be passed to | |
289 | pci_enable_wake (since it uses an index into a bitmask). If a driver gets | |
290 | a request to enable wake events from D3, two calls should be made to | |
291 | pci_enable_wake (one for both D3hot and D3cold). | |
292 | ||
293 | ||
21d6b7e1 | 294 | A 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 | ||
327 | This is a typical implementation. Drivers can slightly change the order | |
328 | of the operations in the implementation, ignore some operations or add | |
329 | more deriver specific operations in it, but drivers should do something like | |
330 | this on the whole. | |
331 | ||
1da177e4 LT |
332 | 5. Resources |
333 | ~~~~~~~~~~~~ | |
334 | ||
335 | PCI Local Bus Specification | |
336 | PCI Bus Power Management Interface Specification | |
337 | ||
98766fbe | 338 | http://www.pcisig.com |
1da177e4 | 339 |