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
   9 ---------------------------------------------------------------------------
  10
  11 1. Overview
  12 2. How the PCI Subsystem Does Power Management
  13 3. PCI Utility Functions
  14 4. PCI Device Drivers
  15 5. Resources
  16
  17 1. Overview
  18 ~~~~~~~~~~~
  19
  20 The PCI Power Management Specification was introduced between the PCI 2.1 and
  21 PCI 2.2 Specifications. It a standard interface for controlling various
  22 power management operations.
  23
  24 Implementation of the PCI PM Spec is optional, as are several sub-components of
  25 it. If a device supports the PCI PM Spec, the device will have an 8 byte
  26 capability field in its PCI configuration space. This field is used to describe
  27 and control the standard PCI power management features.
  28
  29 The PCI PM spec defines 4 operating states for devices (D0 - D3) and for buses
  30 (B0 - B3). The higher the number, the less power the device consumes. However,
  31 the higher the number, the longer the latency is for the device to return to
  32 an operational state (D0).
  33
  34 Bus power management is not covered in this version of this document.
  35
  36 Note that all PCI devices support D0 and D3 by default, regardless of whether or
  37 not they implement any of the PCI PM spec.
  38
  39 The possible state transitions that a device can undergo are:
  40
  41 +---------------------------+
  42 | Current State | New State |
  43 +---------------------------+
  44 | D0            | D1, D2, D3|
  45 +---------------------------+
  46 | D1            | D2, D3    |
  47 +---------------------------+
  48 | D2            | D3        |
  49 +---------------------------+
  50 | D1, D2, D3    | D0        |
  51 +---------------------------+
  52
  53 Note that when the system is entering a global suspend state, all devices will be
  54 placed into D3 and when resuming, all devices will be placed into D0. However,
  55 when the system is running, other state transitions are possible.
  56
  57 2. How The PCI Subsystem Handles Power Management
  58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  59
  60 The PCI suspend/resume functionality is accessed indirectly via the Power Management
  61 subsystem. At boot, the PCI driver registers a power management callback with that layer.
  62 Upon entering a suspend state, the PM layer iterates through all of its registered
  63 callbacks. This currently takes place only during APM state transitions.
  64
  65 Upon going to sleep, the PCI subsystem walks its device tree twice. Both times, it does
  66 a depth first walk of the device tree. The first walk saves each of the device's state
  67 and checks for devices that will prevent the system from entering a global power state.
  68 The next walk then places the devices in a low power state.
  69
  70 The first walk allows a graceful recovery in the event of a failure, since none of the
  71 devices have actually been powered down.
  72
  73 In both walks, in particular the second, all children of a bridge are touched before the
  74 actual bridge itself. This allows the bridge to retain power while its children are being
  75 accessed.
  76
  77 Upon resuming from sleep, just the opposite must be true: all bridges must be powered on
  78 and restored before their children are powered on. This is easily accomplished with a
  79 breadth-first walk of the PCI device tree.
  80
  81
  82 3. PCI Utility Functions
  83 ~~~~~~~~~~~~~~~~~~~~~~~~
  84
  85 These are helper functions designed to be called by individual device drivers.
  86 Assuming that a device behaves as advertised, these should be applicable in most
  87 cases. However, results may vary.
  88
  89 Note that these functions are never implicitly called for the driver. The driver is always
  90 responsible for deciding when and if to call these.
  91
  92
  93 pci_save_state
  94 --------------
  95
  96 Usage:
  97         pci_save_state(dev, buffer);
  98
  99 Description:
 100         Save first 64 bytes of PCI config space. Buffer must be allocated by caller.
 101
 102
 103 pci_restore_state
 104 -----------------
 105
 106 Usage:
 107         pci_restore_state(dev, buffer);
 108
 109 Description:
 110         Restore previously saved config space. (First 64 bytes only);
 111
 112         If buffer is NULL, then restore what information we know about the device
 113         from bootup: BARs and interrupt line.
 114
 115
 116 pci_set_power_state
 117 -------------------
 118
 119 Usage:
 120         pci_set_power_state(dev, state);
 121
 122 Description:
 123         Transition device to low power state using PCI PM Capabilities registers.
 124
 125         Will fail under one of the following conditions:
 126         - If state is less than current state, but not D0 (illegal transition)
 127         - Device doesn't support PM Capabilities
 128         - Device does not support requested state
 129
 130
 131 pci_enable_wake
 132 ---------------
 133
 134 Usage:
 135         pci_enable_wake(dev, state, enable);
 136
 137 Description:
 138         Enable device to generate PME# during low power state using PCI PM
 139         Capabilities.
 140
 141         Checks whether if device supports generating PME# from requested state and fail
 142         if it does not, unless enable == 0 (request is to disable wake events, which
 143         is implicit if it doesn't even support it in the first place).
 144
 145         Note that the PMC Register in the device's PM Capabilties has a bitmask of
 146         the states it supports generating PME# from. D3hot is bit 3 and D3cold is bit
 147         4. So, while a value of 4 as the state may not seem semantically correct, it
 148         is.
 149
 150
 151 4. PCI Device Drivers
 152 ~~~~~~~~~~~~~~~~~~~~~
 153
 154 These functions are intended for use by individual drivers, and are defined in
 155 struct pci_driver:
 156
 157         int  (*save_state) (struct pci_dev *dev, u32 state);
 158         int  (*suspend) (struct pci_dev *dev, u32 state);
 159         int  (*resume) (struct pci_dev *dev);
 160         int  (*enable_wake) (struct pci_dev *dev, u32 state, int enable);
 161
 162
 163 save_state
 164 ----------
 165
 166 Usage:
 167
 168 if (dev->driver && dev->driver->save_state)
 169         dev->driver->save_state(dev,state);
 170
 171 The driver should use this callback to save device state. It should take into
 172 account the current state of the device and the requested state in order to avoid
 173 any unnecessary operations.
 174
 175 For example, a video card that supports all 4 states (D0-D3), all controller context
 176 is preserved when entering D1, but the screen is placed into a low power state
 177 (blanked).
 178
 179 The driver can also interpret this function as a notification that it may be entering
 180 a sleep state in the near future. If it knows that the device cannot enter the
 181 requested state, either because of lack of support for it, or because the device is
 182 middle of some critical operation, then it should fail.
 183
 184 This function should not be used to set any state in the device or the driver because
 185 the device may not actually enter the sleep state (e.g. another driver later causes
 186 causes a global state transition to fail).
 187
 188 Note that in intermediate low power states, a device's I/O and memory spaces may be
 189 disabled and may not be available in subsequent transitions to lower power states.
 190
 191
 192 suspend
 193 -------
 194
 195 Usage:
 196
 197 if (dev->driver && dev->driver->suspend)
 198         dev->driver->suspend(dev,state);
 199
 200 A driver uses this function to actually transition the device into a low power
 201 state. This may include disabling I/O, memory and bus-mastering, as well as physically
 202 transitioning the device to a lower power state.
 203
 204 Bus mastering may be disabled by doing:
 205
 206 pci_disable_device(dev);
 207
 208 For devices that support the PCI PM Spec, this may be used to set the device's power
 209 state:
 210
 211 pci_set_power_state(dev,state);
 212
 213 The driver is also responsible for disabling any other device-specific features
 214 (e.g blanking screen, turning off on-card memory, etc).
 215
 216 The driver should be sure to track the current state of the device, as it may obviate
 217 the need for some operations.
 218
 219 The driver should update the current_state field in its pci_dev structure in this
 220 function.
 221
 222 resume
 223 ------
 224
 225 Usage:
 226
 227 if (dev->driver && dev->driver->suspend)
 228         dev->driver->resume(dev)
 229
 230 The resume callback may be called from any power state, and is always meant to
 231 transition the device to the D0 state.
 232
 233 The driver is responsible for reenabling any features of the device that had
 234 been disabled during previous suspend calls and restoring all state that was saved
 235 in previous save_state calls.
 236
 237 If the device is currently in D3, it must be completely reinitialized, as it must be
 238 assumed that the device has lost all of its context (even that of its PCI config
 239 space). For almost all current drivers, this means that the initialization code that
 240 the driver does at boot must be separated out and called again from the resume
 241 callback. Note that some values for the device may not have to be probed for this
 242 time around if they are saved before entering the low power state.
 243
 244 If the device supports the PCI PM Spec, it can use this to physically transition the
 245 device to D0:
 246
 247 pci_set_power_state(dev,0);
 248
 249 Note that if the entire system is transitioning out of a global sleep state, all
 250 devices will be placed in the D0 state, so this is not necessary. However, in the
 251 event that the device is placed in the D3 state during normal operation, this call
 252 is necessary. It is impossible to determine which of the two events is taking place
 253 in the driver, so it is always a good idea to make that call.
 254
 255 The driver should take note of the state that it is resuming from in order to ensure
 256 correct (and speedy) operation.
 257
 258 The driver should update the current_state field in its pci_dev structure in this
 259 function.
 260
 261
 262 enable_wake
 263 -----------
 264
 265 Usage:
 266
 267 if (dev->driver && dev->driver->enable_wake)
 268         dev->driver->enable_wake(dev,state,enable);
 269
 270 This callback is generally only relevant for devices that support the PCI PM
 271 spec and have the ability to generate a PME# (Power Management Event Signal)
 272 to wake the system up. (However, it is possible that a device may support
 273 some non-standard way of generating a wake event on sleep.)
 274
 275 Bits 15:11 of the PMC (Power Mgmt Capabilities) Register in a device's
 276 PM Capabilties describe what power states the device supports generating a
 277 wake event from:
 278
 279 +------------------+
 280 |  Bit  |  State   |
 281 +------------------+
 282 |  15   |   D0     |
 283 |  14   |   D1     |
 284 |  13   |   D2     |
 285 |  12   |   D3hot  |
 286 |  11   |   D3cold |
 287 +------------------+
 288
 289 A device can use this to enable wake events:
 290
 291          pci_enable_wake(dev,state,enable);
 292
 293 Note that to enable PME# from D3cold, a value of 4 should be passed to
 294 pci_enable_wake (since it uses an index into a bitmask). If a driver gets
 295 a request to enable wake events from D3, two calls should be made to
 296 pci_enable_wake (one for both D3hot and D3cold).
 297
 298
 299 5. Resources
 300 ~~~~~~~~~~~~
 301
 302 PCI Local Bus Specification
 303 PCI Bus Power Management Interface Specification
 304
 305   http://pcisig.org
 306