Documentation/power/pci.txt

   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
 168         int  (*save_state) (struct pci_dev *dev, u32 state);
 169         int  (*suspend) (struct pci_dev *dev, u32 state);
 170         int  (*resume) (struct pci_dev *dev);
 171         int  (*enable_wake) (struct pci_dev *dev, u32 state, int enable);
 172
 173
 174 save_state
 175 ----------
 176
 177 Usage:
 178
 179 if (dev->driver && dev->driver->save_state)
 180         dev->driver->save_state(dev,state);
 181
 182 The driver should use this callback to save device state. It should take into
 183 account the current state of the device and the requested state in order to
 184 avoid any unnecessary operations.
 185
 186 For example, a video card that supports all 4 states (D0-D3), all controller
 187 context is preserved when entering D1, but the screen is placed into a low power
 188 state (blanked).
 189
 190 The driver can also interpret this function as a notification that it may be
 191 entering a sleep state in the near future. If it knows that the device cannot
 192 enter the requested state, either because of lack of support for it, or because
 193 the device is middle of some critical operation, then it should fail.
 194
 195 This function should not be used to set any state in the device or the driver
 196 because the device may not actually enter the sleep state (e.g. another driver
 197 later causes causes a global state transition to fail).
 198
 199 Note that in intermediate low power states, a device's I/O and memory spaces may
 200 be disabled and may not be available in subsequent transitions to lower power
 201 states.
 202
 203
 204 suspend
 205 -------
 206
 207 Usage:
 208
 209 if (dev->driver && dev->driver->suspend)
 210         dev->driver->suspend(dev,state);
 211
 212 A driver uses this function to actually transition the device into a low power
 213 state. This should include disabling I/O, IRQs, and bus-mastering, as well as
 214 physically transitioning the device to a lower power state; it may also include
 215 calls to pci_enable_wake().
 216
 217 Bus mastering may be disabled by doing:
 218
 219 pci_disable_device(dev);
 220
 221 For devices that support the PCI PM Spec, this may be used to set the device's
 222 power state to match the suspend() parameter:
 223
 224 pci_set_power_state(dev,state);
 225
 226 The driver is also responsible for disabling any other device-specific features
 227 (e.g blanking screen, turning off on-card memory, etc).
 228
 229 The driver should be sure to track the current state of the device, as it may
 230 obviate the need for some operations.
 231
 232 The driver should update the current_state field in its pci_dev structure in
 233 this function, except for PM-capable devices when pci_set_power_state is used.
 234
 235 resume
 236 ------
 237
 238 Usage:
 239
 240 if (dev->driver && dev->driver->suspend)
 241         dev->driver->resume(dev)
 242
 243 The resume callback may be called from any power state, and is always meant to
 244 transition the device to the D0 state.
 245
 246 The driver is responsible for reenabling any features of the device that had
 247 been disabled during previous suspend calls, such as IRQs and bus mastering,
 248 as well as calling pci_restore_state().
 249
 250 If the device is currently in D3, it may need to be reinitialized in resume().
 251
 252   * Some types of devices, like bus controllers, will preserve context in D3hot
 253     (using Vcc power).  Their drivers will often want to avoid re-initializing
 254     them after re-entering D0 (perhaps to avoid resetting downstream devices).
 255
 256   * Other kinds of devices in D3hot will discard device context as part of a
 257     soft reset when re-entering the D0 state.
 258
 259   * Devices resuming from D3cold always go through a power-on reset.  Some
 260     device context can also be preserved using Vaux power.
 261
 262   * Some systems hide D3cold resume paths from drivers.  For example, on PCs
 263     the resume path for suspend-to-disk often runs BIOS powerup code, which
 264     will sometimes re-initialize the device.
 265
 266 To handle resets during D3 to D0 transitions, it may be convenient to share
 267 device initialization code between probe() and resume().  Device parameters
 268 can also be saved before the driver suspends into D3, avoiding re-probe.
 269
 270 If the device supports the PCI PM Spec, it can use this to physically transition
 271 the device to D0:
 272
 273 pci_set_power_state(dev,0);
 274
 275 Note that if the entire system is transitioning out of a global sleep state, all
 276 devices will be placed in the D0 state, so this is not necessary. However, in
 277 the event that the device is placed in the D3 state during normal operation,
 278 this call is necessary. It is impossible to determine which of the two events is
 279 taking place in the driver, so it is always a good idea to make that call.
 280
 281 The driver should take note of the state that it is resuming from in order to
 282 ensure correct (and speedy) operation.
 283
 284 The driver should update the current_state field in its pci_dev structure in
 285 this function, except for PM-capable devices when pci_set_power_state is used.
 286
 287
 288 enable_wake
 289 -----------
 290
 291 Usage:
 292
 293 if (dev->driver && dev->driver->enable_wake)
 294         dev->driver->enable_wake(dev,state,enable);
 295
 296 This callback is generally only relevant for devices that support the PCI PM
 297 spec and have the ability to generate a PME# (Power Management Event Signal)
 298 to wake the system up. (However, it is possible that a device may support
 299 some non-standard way of generating a wake event on sleep.)
 300
 301 Bits 15:11 of the PMC (Power Mgmt Capabilities) Register in a device's
 302 PM Capabilties describe what power states the device supports generating a
 303 wake event from:
 304
 305 +------------------+
 306 |  Bit  |  State   |
 307 +------------------+
 308 |  11   |   D0     |
 309 |  12   |   D1     |
 310 |  13   |   D2     |
 311 |  14   |   D3hot  |
 312 |  15   |   D3cold |
 313 +------------------+
 314
 315 A device can use this to enable wake events:
 316
 317          pci_enable_wake(dev,state,enable);
 318
 319 Note that to enable PME# from D3cold, a value of 4 should be passed to
 320 pci_enable_wake (since it uses an index into a bitmask). If a driver gets
 321 a request to enable wake events from D3, two calls should be made to
 322 pci_enable_wake (one for both D3hot and D3cold).
 323
 324
 325 5. Resources
 326 ~~~~~~~~~~~~
 327
 328 PCI Local Bus Specification
 329 PCI Bus Power Management Interface Specification
 330
 331   http://pcisig.org
 332