+Those calls are issued in specific phases of the process by which the
+system enters a low power "suspend" state, or resumes from it.
+
+
+Calling Drivers to Enter System Sleep States
+============================================
+When the system enters a low power state, each device's driver is asked
+to suspend the device by putting it into state compatible with the target
+system state. That's usually some version of "off", but the details are
+system-specific. Also, wakeup-enabled devices will usually stay partly
+functional in order to wake the system.
+
+When the system leaves that low power state, the device's driver is asked
+to resume it. The suspend and resume operations always go together, and
+both are multi-phase operations.
+
+For simple drivers, suspend might quiesce the device using the class code
+and then turn its hardware as "off" as possible with late_suspend. The
+matching resume calls would then completely reinitialize the hardware
+before reactivating its class I/O queues.
+
+More power-aware drivers drivers will use more than one device low power
+state, either at runtime or during system sleep states, and might trigger
+system wakeup events.
+
+
+Call Sequence Guarantees
+------------------------
+To ensure that bridges and similar links needed to talk to a device are
+available when the device is suspended or resumed, the device tree is
+walked in a bottom-up order to suspend devices. A top-down order is
+used to resume those devices.
+
+The ordering of the device tree is defined by the order in which devices
+get registered: a child can never be registered, probed or resumed before
+its parent; and can't be removed or suspended after that parent.
+
+The policy is that the device tree should match hardware bus topology.
+(Or at least the control bus, for devices which use multiple busses.)
+
+
+Suspending Devices
+------------------
+Suspending a given device is done in several phases. Suspending the
+system always includes every phase, executing calls for every device
+before the next phase begins. Not all busses or classes support all
+these callbacks; and not all drivers use all the callbacks.
+
+The phases are seen by driver notifications issued in this order:
+
+ 1 class.suspend(dev, message) is called after tasks are frozen, for
+ devices associated with a class that has such a method. This
+ method may sleep.
+
+ Since I/O activity usually comes from such higher layers, this is
+ a good place to quiesce all drivers of a given type (and keep such
+ code out of those drivers).
+
+ 2 bus.suspend(dev, message) is called next. This method may sleep,
+ and is often morphed into a device driver call with bus-specific
+ parameters and/or rules.
+
+ This call should handle parts of device suspend logic that require
+ sleeping. It probably does work to quiesce the device which hasn't
+ been abstracted into class.suspend() or bus.suspend_late().
+
+ 3 bus.suspend_late(dev, message) is called with IRQs disabled, and
+ with only one CPU active. Until the bus.resume_early() phase
+ completes (see later), IRQs are not enabled again. This method
+ won't be exposed by all busses; for message based busses like USB,
+ I2C, or SPI, device interactions normally require IRQs. This bus
+ call may be morphed into a driver call with bus-specific parameters.
+
+ This call might save low level hardware state that might otherwise
+ be lost in the upcoming low power state, and actually put the
+ device into a low power state ... so that in some cases the device
+ may stay partly usable until this late. This "late" call may also
+ help when coping with hardware that behaves badly.
+
+The pm_message_t parameter is currently used to refine those semantics
+(described later).
+
+At the end of those phases, drivers should normally have stopped all I/O
+transactions (DMA, IRQs), saved enough state that they can re-initialize
+or restore previous state (as needed by the hardware), and placed the
+device into a low-power state. On many platforms they will also use
+clk_disable() to gate off one or more clock sources; sometimes they will
+also switch off power supplies, or reduce voltages. Drivers which have
+runtime PM support may already have performed some or all of the steps
+needed to prepare for the upcoming system sleep state.
+
+When any driver sees that its device_can_wakeup(dev), it should make sure
+to use the relevant hardware signals to trigger a system wakeup event.
+For example, enable_irq_wake() might identify GPIO signals hooked up to
+a switch or other external hardware, and pci_enable_wake() does something
+similar for PCI's PME# signal.
+
+If a driver (or bus, or class) fails it suspend method, the system won't
+enter the desired low power state; it will resume all the devices it's
+suspended so far.
+
+Note that drivers may need to perform different actions based on the target
+system lowpower/sleep state. At this writing, there are only platform
+specific APIs through which drivers could determine those target states.
+
+
+Device Low Power (suspend) States
+---------------------------------
+Device low-power states aren't very standard. One device might only handle
+"on" and "off, while another might support a dozen different versions of
+"on" (how many engines are active?), plus a state that gets back to "on"
+faster than from a full "off".
+
+Some busses define rules about what different suspend states mean. PCI
+gives one example: after the suspend sequence completes, a non-legacy
+PCI device may not perform DMA or issue IRQs, and any wakeup events it
+issues would be issued through the PME# bus signal. Plus, there are
+several PCI-standard device states, some of which are optional.
+
+In contrast, integrated system-on-chip processors often use irqs as the
+wakeup event sources (so drivers would call enable_irq_wake) and might
+be able to treat DMA completion as a wakeup event (sometimes DMA can stay
+active too, it'd only be the CPU and some peripherals that sleep).
+
+Some details here may be platform-specific. Systems may have devices that
+can be fully active in certain sleep states, such as an LCD display that's
+refreshed using DMA while most of the system is sleeping lightly ... and
+its frame buffer might even be updated by a DSP or other non-Linux CPU while
+the Linux control processor stays idle.
+
+Moreover, the specific actions taken may depend on the target system state.
+One target system state might allow a given device to be very operational;
+another might require a hard shut down with re-initialization on resume.
+And two different target systems might use the same device in different
+ways; the aforementioned LCD might be active in one product's "standby",
+but a different product using the same SOC might work differently.
+
+
+Meaning of pm_message_t.event
+-----------------------------
+Parameters to suspend calls include the device affected and a message of
+type pm_message_t, which has one field: the event. If driver does not
+recognize the event code, suspend calls may abort the request and return
+a negative errno. However, most drivers will be fine if they implement
+PM_EVENT_SUSPEND semantics for all messages.
+
+The event codes are used to refine the goal of suspending the device, and
+mostly matter when creating or resuming system memory image snapshots, as
+used with suspend-to-disk:
+
+ PM_EVENT_SUSPEND -- quiesce the driver and put hardware into a low-power
+ state. When used with system sleep states like "suspend-to-RAM" or
+ "standby", the upcoming resume() call will often be able to rely on
+ state kept in hardware, or issue system wakeup events. When used
+ instead with suspend-to-disk, few devices support this capability;
+ most are completely powered off.
+
+ PM_EVENT_FREEZE -- quiesce the driver, but don't necessarily change into
+ any low power mode. A system snapshot is about to be taken, often
+ followed by a call to the driver's resume() method. Neither wakeup
+ events nor DMA are allowed.
+
+ PM_EVENT_PRETHAW -- quiesce the driver, knowing that the upcoming resume()
+ will restore a suspend-to-disk snapshot from a different kernel image.
+ Drivers that are smart enough to look at their hardware state during
+ resume() processing need that state to be correct ... a PRETHAW could
+ be used to invalidate that state (by resetting the device), like a
+ shutdown() invocation would before a kexec() or system halt. Other
+ drivers might handle this the same way as PM_EVENT_FREEZE. Neither
+ wakeup events nor DMA are allowed.
+
+To enter "standby" (ACPI S1) or "Suspend to RAM" (STR, ACPI S3) states, or
+the similarly named APM states, only PM_EVENT_SUSPEND is used; for "Suspend
+to Disk" (STD, hibernate, ACPI S4), all of those event codes are used.
+
+There's also PM_EVENT_ON, a value which never appears as a suspend event
+but is sometimes used to record the "not suspended" device state.
+
+
+Resuming Devices
+----------------
+Resuming is done in multiple phases, much like suspending, with all
+devices processing each phase's calls before the next phase begins.
+
+The phases are seen by driver notifications issued in this order:
+
+ 1 bus.resume_early(dev) is called with IRQs disabled, and with
+ only one CPU active. As with bus.suspend_late(), this method
+ won't be supported on busses that require IRQs in order to
+ interact with devices.
+
+ This reverses the effects of bus.suspend_late().
+
+ 2 bus.resume(dev) is called next. This may be morphed into a device
+ driver call with bus-specific parameters; implementations may sleep.
+
+ This reverses the effects of bus.suspend().
+
+ 3 class.resume(dev) is called for devices associated with a class
+ that has such a method. Implementations may sleep.
+
+ This reverses the effects of class.suspend(), and would usually
+ reactivate the device's I/O queue.
+
+At the end of those phases, drivers should normally be as functional as
+they were before suspending: I/O can be performed using DMA and IRQs, and
+the relevant clocks are gated on. The device need not be "fully on"; it
+might be in a runtime lowpower/suspend state that acts as if it were.
+
+However, the details here may again be platform-specific. For example,
+some systems support multiple "run" states, and the mode in effect at
+the end of resume() might not be the one which preceded suspension.
+That means availability of certain clocks or power supplies changed,
+which could easily affect how a driver works.
+
+
+Drivers need to be able to handle hardware which has been reset since the
+suspend methods were called, for example by complete reinitialization.
+This may be the hardest part, and the one most protected by NDA'd documents
+and chip errata. It's simplest if the hardware state hasn't changed since
+the suspend() was called, but that can't always be guaranteed.
+
+Drivers must also be prepared to notice that the device has been removed
+while the system was powered off, whenever that's physically possible.
+PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses
+where common Linux platforms will see such removal. Details of how drivers
+will notice and handle such removals are currently bus-specific, and often
+involve a separate thread.