patch-2.4.22 linux-2.4.22/Documentation/power/pci.txt

• Lines: 277
• Date: 2003-08-25 04:44:39.000000000 -0700
• Orig file: linux-2.4.21/Documentation/power/pci.txt
• Orig date: 2002-08-02 17:39:42.000000000 -0700

diff -urN linux-2.4.21/Documentation/power/pci.txt linux-2.4.22/Documentation/power/pci.txt
@@ -22,7 +22,7 @@
 power management operations.
 
 Implementation of the PCI PM Spec is optional, as are several sub-components of
-it. If a device supports the PCI PM Spec, the device will have an 8 byte 
+it. If a device supports the PCI PM Spec, the device will have an 8 byte
 capability field in its PCI configuration space. This field is used to describe
 and control the standard PCI power management features.
 
@@ -50,33 +50,35 @@
 | D1, D2, D3    | D0        |
 +---------------------------+
 
-Note that when the system is entering a global suspend state, all devices will be 
-placed into D3 and when resuming, all devices will be placed into D0. However, 
-when the system is running, other state transitions are possible.
+Note that when the system is entering a global suspend state, all devices will
+be placed into D3 and when resuming, all devices will be placed into D0.
+However, when the system is running, other state transitions are possible.
 
 2. How The PCI Subsystem Handles Power Management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The PCI suspend/resume functionality is accessed indirectly via the Power Management 
-subsystem. At boot, the PCI driver registers a power management callback with that layer.
-Upon entering a suspend state, the PM layer iterates through all of its registered 
-callbacks. This currently takes place only during APM state transitions.
-
-Upon going to sleep, the PCI subsystem walks its device tree twice. Both times, it does
-a depth first walk of the device tree. The first walk saves each of the device's state 
-and checks for devices that will prevent the system from entering a global power state. 
-The next walk then places the devices in a low power state.
-
-The first walk allows a graceful recovery in the event of a failure, since none of the 
-devices have actually been powered down.
-
-In both walks, in particular the second, all children of a bridge are touched before the
-actual bridge itself. This allows the bridge to retain power while its children are being
-accessed.
-
-Upon resuming from sleep, just the opposite must be true: all bridges must be powered on
-and restored before their children are powered on. This is easily accomplished with a
-breadth-first walk of the PCI device tree.
+The PCI suspend/resume functionality is accessed indirectly via the Power
+Management subsystem. At boot, the PCI driver registers a power management
+callback with that layer. Upon entering a suspend state, the PM layer iterates
+through all of its registered callbacks. This currently takes place only during
+APM state transitions.
+
+Upon going to sleep, the PCI subsystem walks its device tree twice. Both times,
+it does a depth first walk of the device tree. The first walk saves each of the
+device's state and checks for devices that will prevent the system from entering
+a global power state. The next walk then places the devices in a low power
+state.
+
+The first walk allows a graceful recovery in the event of a failure, since none
+of the devices have actually been powered down.
+
+In both walks, in particular the second, all children of a bridge are touched
+before the actual bridge itself. This allows the bridge to retain power while
+its children are being accessed.
+
+Upon resuming from sleep, just the opposite must be true: all bridges must be
+powered on and restored before their children are powered on. This is easily
+accomplished with a breadth-first walk of the PCI device tree.
 
 
 3. PCI Utility Functions
@@ -86,8 +88,8 @@
 Assuming that a device behaves as advertised, these should be applicable in most
 cases. However, results may vary.
 
-Note that these functions are never implicitly called for the driver. The driver is always
-responsible for deciding when and if to call these.
+Note that these functions are never implicitly called for the driver. The driver
+is always responsible for deciding when and if to call these.
 
 
 pci_save_state
@@ -97,7 +99,8 @@
 	pci_save_state(dev, buffer);
 
 Description:
-	Save first 64 bytes of PCI config space. Buffer must be allocated by caller.
+	Save first 64 bytes of PCI config space. Buffer must be allocated by
+	caller.
 
 
 pci_restore_state
@@ -109,8 +112,8 @@
 Description:
 	Restore previously saved config space. (First 64 bytes only);
 
-	If buffer is NULL, then restore what information we know about the device
-	from bootup: BARs and interrupt line.
+	If buffer is NULL, then restore what information we know about the
+	device from bootup: BARs and interrupt line.
 
 
 pci_set_power_state
@@ -120,7 +123,8 @@
 	pci_set_power_state(dev, state);
 
 Description:
-	Transition device to low power state using PCI PM Capabilities registers.
+	Transition device to low power state using PCI PM Capabilities
+	registers.
 
 	Will fail under one of the following conditions:
 	- If state is less than current state, but not D0 (illegal transition)
@@ -138,14 +142,15 @@
 	Enable device to generate PME# during low power state using PCI PM 
 	Capabilities.
 
-	Checks whether if device supports generating PME# from requested state and fail
-	if it does not, unless enable == 0 (request is to disable wake events, which
-	is implicit if it doesn't even support it in the first place).
-
-	Note that the PMC Register in the device's PM Capabilties has a bitmask of
-	the states it supports generating PME# from. D3hot is bit 3 and D3cold is bit
-	4. So, while a value of 4 as the state may not seem semantically correct, it
-	is. 
+	Checks whether if device supports generating PME# from requested state
+	and fail if it does not, unless enable == 0 (request is to disable wake
+	events, which is implicit if it doesn't even support it in the first
+	place).
+
+	Note that the PMC Register in the device's PM Capabilties has a bitmask
+	of the states it supports generating PME# from. D3hot is bit 3 and
+	D3cold is bit 4. So, while a value of 4 as the state may not seem
+	semantically correct, it is. 
 
 
 4. PCI Device Drivers
@@ -168,25 +173,26 @@
 if (dev->driver && dev->driver->save_state)
 	dev->driver->save_state(dev,state);
 
-The driver should use this callback to save device state. It should take into 
-account the current state of the device and the requested state in order to avoid
-any unnecessary operations.
-
-For example, a video card that supports all 4 states (D0-D3), all controller context
-is preserved when entering D1, but the screen is placed into a low power state
-(blanked). 
-
-The driver can also interpret this function as a notification that it may be entering
-a sleep state in the near future. If it knows that the device cannot enter the 
-requested state, either because of lack of support for it, or because the device is 
-middle of some critical operation, then it should fail.
-
-This function should not be used to set any state in the device or the driver because
-the device may not actually enter the sleep state (e.g. another driver later causes
-causes a global state transition to fail).
-
-Note that in intermediate low power states, a device's I/O and memory spaces may be
-disabled and may not be available in subsequent transitions to lower power states.
+The driver should use this callback to save device state. It should take into
+account the current state of the device and the requested state in order to
+avoid any unnecessary operations.
+
+For example, a video card that supports all 4 states (D0-D3), all controller
+context is preserved when entering D1, but the screen is placed into a low power
+state (blanked). 
+
+The driver can also interpret this function as a notification that it may be
+entering a sleep state in the near future. If it knows that the device cannot
+enter the requested state, either because of lack of support for it, or because
+the device is middle of some critical operation, then it should fail.
+
+This function should not be used to set any state in the device or the driver
+because the device may not actually enter the sleep state (e.g. another driver
+later causes causes a global state transition to fail).
+
+Note that in intermediate low power states, a device's I/O and memory spaces may
+be disabled and may not be available in subsequent transitions to lower power
+states.
 
 
 suspend
@@ -197,27 +203,27 @@
 if (dev->driver && dev->driver->suspend)
 	dev->driver->suspend(dev,state);
 
-A driver uses this function to actually transition the device into a low power 
-state. This may include disabling I/O, memory and bus-mastering, as well as physically
-transitioning the device to a lower power state.
+A driver uses this function to actually transition the device into a low power
+state. This may include disabling I/O, memory and bus-mastering, as well as
+physically transitioning the device to a lower power state.
 
 Bus mastering may be disabled by doing:
 
 pci_disable_device(dev);
 
-For devices that support the PCI PM Spec, this may be used to set the device's power 
-state:
+For devices that support the PCI PM Spec, this may be used to set the device's
+power state:
 
 pci_set_power_state(dev,state);
 
 The driver is also responsible for disabling any other device-specific features
 (e.g blanking screen, turning off on-card memory, etc).
 
-The driver should be sure to track the current state of the device, as it may obviate
-the need for some operations.
+The driver should be sure to track the current state of the device, as it may
+obviate the need for some operations.
 
-The driver should update the current_state field in its pci_dev structure in this 
-function.
+The driver should update the current_state field in its pci_dev structure in
+this function.
 
 resume
 ------
@@ -227,36 +233,37 @@
 if (dev->driver && dev->driver->suspend)
 	dev->driver->resume(dev)
 
-The resume callback may be called from any power state, and is always meant to 
+The resume callback may be called from any power state, and is always meant to
 transition the device to the D0 state. 
 
-The driver is responsible for reenabling any features of the device that had 
-been disabled during previous suspend calls and restoring all state that was saved
-in previous save_state calls.
-
-If the device is currently in D3, it must be completely reinitialized, as it must be
-assumed that the device has lost all of its context (even that of its PCI config 
-space). For almost all current drivers, this means that the initialization code that
-the driver does at boot must be separated out and called again from the resume
-callback. Note that some values for the device may not have to be probed for this
-time around if they are saved before entering the low power state.
+The driver is responsible for reenabling any features of the device that had
+been disabled during previous suspend calls and restoring all state that was
+saved in previous save_state calls.
+
+If the device is currently in D3, it must be completely reinitialized, as it
+must be assumed that the device has lost all of its context (even that of its
+PCI config space). For almost all current drivers, this means that the
+initialization code that the driver does at boot must be separated out and
+called again from the resume callback. Note that some values for the device may
+not have to be probed for this time around if they are saved before entering the
+low power state.
 
-If the device supports the PCI PM Spec, it can use this to physically transition the
-device to D0:
+If the device supports the PCI PM Spec, it can use this to physically transition
+the device to D0:
 
 pci_set_power_state(dev,0);
 
-Note that if the entire system is transitioning out of a global sleep state, all 
-devices will be placed in the D0 state, so this is not necessary. However, in the
-event that the device is placed in the D3 state during normal operation, this call
-is necessary. It is impossible to determine which of the two events is taking place
-in the driver, so it is always a good idea to make that call.
+Note that if the entire system is transitioning out of a global sleep state, all
+devices will be placed in the D0 state, so this is not necessary. However, in
+the event that the device is placed in the D3 state during normal operation,
+this call is necessary. It is impossible to determine which of the two events is
+taking place in the driver, so it is always a good idea to make that call.
 
-The driver should take note of the state that it is resuming from in order to ensure
-correct (and speedy) operation.
+The driver should take note of the state that it is resuming from in order to
+ensure correct (and speedy) operation.
 
-The driver should update the current_state field in its pci_dev structure in this 
-function.
+The driver should update the current_state field in its pci_dev structure in
+this function.
 
 
 enable_wake