Just the basics, more to come.
--- /dev/null
+
+Device Power Management
+
+
+Device power management encompasses two areas - the ability to save
+state and transition a device to a low-power state when the system is
+entering a low-power state; and the ability to transition a device to
+a low-power state while the system is running (and independently of
+any other power management activity).
+
+
+Methods
+
+The methods to suspend and resume devices reside in struct bus_type:
+
+struct bus_type {
+ ...
+ int (*suspend)(struct device * dev, u32 state);
+ int (*resume)(struct device * dev);
+};
+
+Each bus driver is responsible implementing these methods, translating
+the call into a bus-specific request and forwarding the call to the
+bus-specific drivers. For example, PCI drivers implement suspend() and
+resume() methods in struct pci_driver. The PCI core is simply
+responsible for translating the pointers to PCI-specific ones and
+calling the low-level driver.
+
+This is done to a) ease transition to the new power management methods
+and leverage the existing PM code in various bus drivers; b) allow
+buses to implement generic and default PM routines for devices, and c)
+make the flow of execution obvious to the reader.
+
+
+System Power Management
+
+When the system enters a low-power state, the device tree is walked in
+a depth-first fashion to transition each device into a low-power
+state. The ordering of the device tree is guaranteed by the order in
+which devices get registered - children are never registered before
+their ancestors, and devices are placed at the back of the list when
+registered. By walking the list in reverse order, we are guaranteed to
+suspend devices in the proper order.
+
+Devices are suspended once with interrupts enabled. Drivers are
+expected to stop I/O transactions, save device state, and place the
+device into a low-power state. Drivers may sleep, allocate memory,
+etc. at will.
+
+Some devices are broken and will inevitably have problems powering
+down or disabling themselves with interrupts enabled. For these
+special cases, they may return -EAGAIN. This will put the device on a
+list to be taken care of later. When interrupts are disabled, before
+we enter the low-power state, their drivers are called again to put
+their device to sleep.
+
+On resume, the devices that returned -EAGAIN will be called to power
+themselves back on with interrupts disabled. Once interrupts have been
+re-enabled, the rest of the drivers will be called to resume their
+devices. On resume, a driver is responsible for powering back on each
+device, restoring state, and re-enabling I/O transactions for that
+device.
+
+System devices follow a slightly different API, which can be found in
+
+ include/linux/sysdev.h
+ drivers/base/sys.c
+
+System devices will only be suspended with interrupts disabled, and
+after all other devices have been suspended. On resume, they will be
+resumed before any other devices, and also with interrupts disabled.
+
--- /dev/null
+Power Management Interface
+
+
+The power management subsystem provides a unified sysfs interface to
+userspace, regardless of what architecture or platform one is
+running. The interface exists in /sys/power/ directory (assuming sysfs
+is mounted at /sys).
+
+/sys/power/state controls system power state. Reading from this file
+returns what states are supported, which is hard-coded to 'standby'
+(Power-On Suspend), 'mem' (Suspend-to-RAM), and 'disk'
+(Suspend-to-Disk).
+
+Writing to this file one of those strings causes the system to
+transition into that state. Please see the file
+Documentation/power/states.txt for a description of each of those
+states.
+
+
+/sys/power/disk controls the operating mode of the suspend-to-disk
+mechanism. Suspend-to-disk can be handled in several ways. The
+greatest distinction is who writes memory to disk - the firmware or
+the kernel. If the firmware does it, we assume that it also handles
+suspending the system.
+
+If the kernel does it, then we have three options for putting the system
+to sleep - using the platform driver (e.g. ACPI or other PM
+registers), powering off the system or rebooting the system (for
+testing). The system will support either 'firmware' or 'platform', and
+that is known a priori. But, the user may choose 'shutdown' or
+'reboot' as alternatives.
+
+Reading from this file will display what the mode is currently set
+to. Writing to this file will accept one of
+
+ 'firmware'
+ 'platform'
+ 'shutdown'
+ 'reboot'
+
+It will only change to 'firmware' or 'platform' if the system supports
+it.
+
--- /dev/null
+
+System Power Management States
+
+
+The kernel supports three power management states generically, though
+each is dependent on platform support code to implement the low-level
+details for each state. This file describes each state, what they are
+commonly called, what ACPI state they map to, and what string to write
+to /sys/power/state to enter that state
+
+
+State: Standby / Power-On Suspend
+ACPI State: S1
+String: "standby"
+
+This state offers minimal, though real, power savings, while providing
+a very low-latency transition back to a working system. No operating
+state is lost (the CPU retains power), so the system easily starts up
+again where it left off.
+
+We try to put devices in a low-power state equivalent to D1, which
+also offers low power savings, but low resume latency. Not all devices
+support D1, and those that don't are left on.
+
+A transition from Standby to the On state should take about 1-2
+seconds.
+
+
+State: Suspend-to-RAM
+ACPI State: S3
+String: "mem"
+
+This state offers significant power savings as everything in the
+system is put into a low-power state, except for memory, which is
+placed in self-refresh mode to retain its contents.
+
+System and device state is saved and kept in memory. All devices are
+suspended and put into D3. In many cases, all peripheral buses lose
+power when entering STR, so devices must be able to handle the
+transition back to the On state.
+
+For at least ACPI, STR requires some minimal boot-strapping code to
+resume the system from STR. This may be true on other platforms.
+
+A transition from Suspend-to-RAM to the On state should take about
+3-5 seconds.
+
+
+State: Suspend-to-disk
+ACPI State: S4
+String: "disk"
+
+This state offers the greatest power savings, and can be used even in
+the absence of low-level platform support for power management. This
+state operates similarly to Suspend-to-RAM, but includes a final step
+of writing memory contents to disk. On resume, this is read and memory
+is restored to its pre-suspend state.
+
+STD can be handled by the firmware or the kernel. If it is handled by
+the firmware, it usually requires a dedicated partition that must be
+setup via another operating system for it to use. Despite the
+inconvenience, this method requires minimal work by the kernel, since
+the firmware will also handle restoring memory contents on resume.
+
+If the kernel is responsible for persistantly saving state, a mechanism
+called 'swsusp' (Swap Suspend) is used to write memory contents to
+free swap space. swsusp has some restrictive requirements, but should
+work in most cases. Some, albeit outdated, documentation can be found
+in Documentation/power/swsusp.txt.
+
+Once memory state is written to disk, the system may either enter a
+low-power state (like ACPI S4), or it may simply power down. Powering
+down offers greater savings, and allows this mechanism to work on any
+system. However, entering a real low-power state allows the user to
+trigger wake up events (e.g. pressing a key or opening a laptop lid).
+
+A transition from Suspend-to-Disk to the On state should take about 30
+seconds, though it's typically a bit more with the current
+implementation.
--- /dev/null
+From kernel/suspend.c:
+
+ * BIG FAT WARNING *********************************************************
+ *
+ * If you have unsupported (*) devices using DMA...
+ * ...say goodbye to your data.
+ *
+ * If you touch anything on disk between suspend and resume...
+ * ...kiss your data goodbye.
+ *
+ * If your disk driver does not support suspend... (IDE does)
+ * ...you'd better find out how to get along
+ * without your data.
+ *
+ * (*) pm interface support is needed to make it safe.
+
+You need to append resume=/dev/your_swap_partition to kernel command
+line. Then you suspend by echo 4 > /proc/acpi/sleep.
+
+[Notice. Rest docs is pretty outdated (see date!) It should be safe to
+use swsusp on ext3/reiserfs these days.]
+
+
+Article about goals and implementation of Software Suspend for Linux
+Author: G\82ábor Kuti
+Last revised: 2002-04-08
+
+Idea and goals to achieve
+
+Nowadays it is common in several laptops that they have a suspend button. It
+saves the state of the machine to a filesystem or to a partition and switches
+to standby mode. Later resuming the machine the saved state is loaded back to
+ram and the machine can continue its work. It has two real benefits. First we
+save ourselves the time machine goes down and later boots up, energy costs
+real high when running from batteries. The other gain is that we don't have to
+interrupt our programs so processes that are calculating something for a long
+time shouldn't need to be written interruptible.
+
+On desk machines the power saving function isn't as important as it is in
+laptops but we really may benefit from the second one. Nowadays the number of
+desk machines supporting suspend function in their APM is going up but there
+are (and there will still be for a long time) machines that don't even support
+APM of any kind. On the other hand it is reported that using APM's suspend
+some irqs (e.g. ATA disk irq) is lost and it is annoying for the user until
+the Linux kernel resets the device.
+
+So I started thinking about implementing Software Suspend which doesn't need
+any APM support and - since it uses pretty near only high-level routines - is
+supposed to be architecture independent code.
+
+Using the code
+
+The code is experimental right now - testers, extra eyes are welcome. To
+compile this support into the kernel, you need CONFIG_EXPERIMENTAL,
+and then CONFIG_SOFTWARE_SUSPEND in menu General Setup to be enabled. It
+cannot be used as a module and I don't think it will ever be needed.
+
+You have two ways to use this code. The first one is if you've compiled in
+sysrq support then you may press Sysrq-D to request suspend. The other way
+is with a patched SysVinit (my patch is against 2.76 and available at my
+home page). You might call 'swsusp' or 'shutdown -z <time>'. Next way is to
+echo 4 > /proc/acpi/sleep.
+
+Either way it saves the state of the machine into active swaps and then
+reboots. You must explicitly specify the swap partition to resume from with
+``resume='' kernel option. If signature is found it loads and restores saved
+state. If the option ``noresume'' is specified as a boot parameter, it skips
+the resuming. Warning! Look at section ``Things to implement'' to see what
+isn't yet implemented. Also I strongly suggest you to list all active swaps
+in /etc/fstab. Firstly because you don't have to specify anything to resume
+and secondly if you have more than one swap area you can't decide which one
+has the 'root' signature.
+
+In the meantime while the system is suspended you should not touch any of the
+hardware!
+
+About the code
+Goals reached
+
+The code can be downloaded from
+http://falcon.sch.bme.hu/~seasons/linux/. It mainly works but there are still
+some of XXXs, TODOs, FIXMEs in the code which seem not to be too important. It
+should work all right except for the problems listed in ``Things to
+implement''. Notes about the code are really welcome.
+
+How the code works
+
+When suspending is triggered it immediately wakes up process bdflush. Bdflush
+checks whether we have anything in our run queue tq_bdflush. Since we queued up
+function do_software_suspend, it is called. Here we shrink everything including
+dcache, inodes, buffers and memory (here mainly processes are swapped out). We
+count how many pages we need to duplicate (we have to be atomical!) then we
+create an appropriate sized page directory. It will point to the original and
+the new (copied) address of the page. We get the free pages by
+__get_free_pages() but since it changes state we have to be able to track it
+later so it also flips in a bit in page's flags (a new Nosave flag). We
+duplicate pages and then mark them as used (so atomicity is ensured). After
+this we write out the image to swaps, do another sync and the machine may
+reboot. We also save registers to stack.
+
+By resuming an ``inverse'' method is executed. The image if exists is loaded,
+loadling is either triggered by ``resume='' kernel option. We
+change our task to bdflush (it is needed because if we don't do this init does
+an oops when it is waken up later) and then pages are copied back to their
+original location. We restore registers, free previously allocated memory,
+activate memory context and task information. Here we should restore hardware
+state but even without this the machine is restored and processes are continued
+to work. I think hardware state should be restored by some list (using
+notify_chain) and probably by some userland program (run-parts?) for users'
+pleasure. Check out my patch at the same location for the sysvinit patch.
+
+WARNINGS!
+- It does not like pcmcia cards. And this is logical: pcmcia cards need
+ cardmgr to be initialized. they are not initialized during singleuser boot,
+ but "resumed" kernel does expect them to be initialized. That leads to
+ armagedon. You should eject any pcmcia cards before suspending.
+
+Things to implement
+- SMP support. I've done an SMP support but since I don't have access to a kind
+ of this one I cannot test it. Please SMP people test it. .. Tested it,
+ doesn't work. Had no time to figure out why. There is some mess with
+ interrupts AFAIK..
+- We should only make a copy of data related to kernel segment, since any
+ process data won't be changed.
+- Hardware state restoring. Now there's support for notifying via the notify
+ chain, event handlers are welcome. Some devices may have microcodes loaded
+ into them. We should have event handlers for them as well.
+- We should support other architectures (There are really only some arch
+ related functions..)
+- We should also restore original state of swaps if the ``noresume'' kernel
+ option is specified.. Or do we need such a feature to save state for some
+ other time? Do we need some kind of ``several saved states''? (Linux-HA
+ people?). There's been some discussion about checkpointing on linux-future.
+- Should make more sanity checks. Or are these enough?
+
+Not so important ideas for implementing
+
+- If a real time process is running then don't suspend the machine.
+- Support for power.conf file as in Solaris, autoshutdown, special
+ devicetypes support, maybe in sysctl.
+- Introduce timeout for SMP locking. But first locking ought to work :O
+- Pre-detect if we don't have enough swap space or free it instead of
+ calling panic.
+- Support for adding/removing hardware while suspended?
+- We should not free pages at the beginning so aggressively, most of them
+ go there anyway..
+- If X is active while suspending then by resuming calling svgatextmode
+ corrupts the virtual console of X.. (Maybe this has been fixed AFAIK).
+
+Drivers we support
+- IDE disks are okay
+- vesafb
+
+Drivers that need support
+- pc_keyb -- perhaps we can wait for vojtech's input patches
+- do IDE cdroms need some kind of support?
+- IDE CD-RW -- how to deal with that?
+
+Sleep states summary (thanx, Ducrot)
+====================================
+
+In a really perfect world:
+echo 1 > /proc/acpi/sleep # for standby
+echo 2 > /proc/acpi/sleep # for suspend to ram
+echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative
+echo 4 > /proc/acpi/sleep # for suspend to disk
+echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system
+
+and perhaps
+echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios
+
+
+FAQ:
+
+Q: well, suspending a server is IMHO a really stupid thing,
+but... (Diego Zuccato):
+
+A: You bought new UPS for your server. How do you install it without
+bringing machine down? Suspend to disk, rearrange power cables,
+resume.
+
+You have your server on UPS. Power died, and UPS is indicating 30
+seconds to failure. What do you do? Suspend to disk.
+
+Ethernet card in your server died. You want to replace it. Your
+server is not hotplug capable. What do you do? Suspend to disk,
+replace ethernet card, resume. If you are fast your users will not
+even see broken connections.
+
+Any other idea you might have tell me!
+
+Contacting the author
+If you have any question or any patch that solves the above or detected
+problems please contact me at seasons@falcon.sch.bme.hu. I might delay
+answering, sorry about that.
+
+++ /dev/null
-From kernel/suspend.c:
-
- * BIG FAT WARNING *********************************************************
- *
- * If you have unsupported (*) devices using DMA...
- * ...say goodbye to your data.
- *
- * If you touch anything on disk between suspend and resume...
- * ...kiss your data goodbye.
- *
- * If your disk driver does not support suspend... (IDE does)
- * ...you'd better find out how to get along
- * without your data.
- *
- * (*) pm interface support is needed to make it safe.
-
-You need to append resume=/dev/your_swap_partition to kernel command
-line. Then you suspend by echo 4 > /proc/acpi/sleep.
-
-[Notice. Rest docs is pretty outdated (see date!) It should be safe to
-use swsusp on ext3/reiserfs these days.]
-
-
-Article about goals and implementation of Software Suspend for Linux
-Author: G\82ábor Kuti
-Last revised: 2002-04-08
-
-Idea and goals to achieve
-
-Nowadays it is common in several laptops that they have a suspend button. It
-saves the state of the machine to a filesystem or to a partition and switches
-to standby mode. Later resuming the machine the saved state is loaded back to
-ram and the machine can continue its work. It has two real benefits. First we
-save ourselves the time machine goes down and later boots up, energy costs
-real high when running from batteries. The other gain is that we don't have to
-interrupt our programs so processes that are calculating something for a long
-time shouldn't need to be written interruptible.
-
-On desk machines the power saving function isn't as important as it is in
-laptops but we really may benefit from the second one. Nowadays the number of
-desk machines supporting suspend function in their APM is going up but there
-are (and there will still be for a long time) machines that don't even support
-APM of any kind. On the other hand it is reported that using APM's suspend
-some irqs (e.g. ATA disk irq) is lost and it is annoying for the user until
-the Linux kernel resets the device.
-
-So I started thinking about implementing Software Suspend which doesn't need
-any APM support and - since it uses pretty near only high-level routines - is
-supposed to be architecture independent code.
-
-Using the code
-
-The code is experimental right now - testers, extra eyes are welcome. To
-compile this support into the kernel, you need CONFIG_EXPERIMENTAL,
-and then CONFIG_SOFTWARE_SUSPEND in menu General Setup to be enabled. It
-cannot be used as a module and I don't think it will ever be needed.
-
-You have two ways to use this code. The first one is if you've compiled in
-sysrq support then you may press Sysrq-D to request suspend. The other way
-is with a patched SysVinit (my patch is against 2.76 and available at my
-home page). You might call 'swsusp' or 'shutdown -z <time>'. Next way is to
-echo 4 > /proc/acpi/sleep.
-
-Either way it saves the state of the machine into active swaps and then
-reboots. You must explicitly specify the swap partition to resume from with
-``resume='' kernel option. If signature is found it loads and restores saved
-state. If the option ``noresume'' is specified as a boot parameter, it skips
-the resuming. Warning! Look at section ``Things to implement'' to see what
-isn't yet implemented. Also I strongly suggest you to list all active swaps
-in /etc/fstab. Firstly because you don't have to specify anything to resume
-and secondly if you have more than one swap area you can't decide which one
-has the 'root' signature.
-
-In the meantime while the system is suspended you should not touch any of the
-hardware!
-
-About the code
-Goals reached
-
-The code can be downloaded from
-http://falcon.sch.bme.hu/~seasons/linux/. It mainly works but there are still
-some of XXXs, TODOs, FIXMEs in the code which seem not to be too important. It
-should work all right except for the problems listed in ``Things to
-implement''. Notes about the code are really welcome.
-
-How the code works
-
-When suspending is triggered it immediately wakes up process bdflush. Bdflush
-checks whether we have anything in our run queue tq_bdflush. Since we queued up
-function do_software_suspend, it is called. Here we shrink everything including
-dcache, inodes, buffers and memory (here mainly processes are swapped out). We
-count how many pages we need to duplicate (we have to be atomical!) then we
-create an appropriate sized page directory. It will point to the original and
-the new (copied) address of the page. We get the free pages by
-__get_free_pages() but since it changes state we have to be able to track it
-later so it also flips in a bit in page's flags (a new Nosave flag). We
-duplicate pages and then mark them as used (so atomicity is ensured). After
-this we write out the image to swaps, do another sync and the machine may
-reboot. We also save registers to stack.
-
-By resuming an ``inverse'' method is executed. The image if exists is loaded,
-loadling is either triggered by ``resume='' kernel option. We
-change our task to bdflush (it is needed because if we don't do this init does
-an oops when it is waken up later) and then pages are copied back to their
-original location. We restore registers, free previously allocated memory,
-activate memory context and task information. Here we should restore hardware
-state but even without this the machine is restored and processes are continued
-to work. I think hardware state should be restored by some list (using
-notify_chain) and probably by some userland program (run-parts?) for users'
-pleasure. Check out my patch at the same location for the sysvinit patch.
-
-WARNINGS!
-- It does not like pcmcia cards. And this is logical: pcmcia cards need
- cardmgr to be initialized. they are not initialized during singleuser boot,
- but "resumed" kernel does expect them to be initialized. That leads to
- armagedon. You should eject any pcmcia cards before suspending.
-
-Things to implement
-- SMP support. I've done an SMP support but since I don't have access to a kind
- of this one I cannot test it. Please SMP people test it. .. Tested it,
- doesn't work. Had no time to figure out why. There is some mess with
- interrupts AFAIK..
-- We should only make a copy of data related to kernel segment, since any
- process data won't be changed.
-- Hardware state restoring. Now there's support for notifying via the notify
- chain, event handlers are welcome. Some devices may have microcodes loaded
- into them. We should have event handlers for them as well.
-- We should support other architectures (There are really only some arch
- related functions..)
-- We should also restore original state of swaps if the ``noresume'' kernel
- option is specified.. Or do we need such a feature to save state for some
- other time? Do we need some kind of ``several saved states''? (Linux-HA
- people?). There's been some discussion about checkpointing on linux-future.
-- Should make more sanity checks. Or are these enough?
-
-Not so important ideas for implementing
-
-- If a real time process is running then don't suspend the machine.
-- Support for power.conf file as in Solaris, autoshutdown, special
- devicetypes support, maybe in sysctl.
-- Introduce timeout for SMP locking. But first locking ought to work :O
-- Pre-detect if we don't have enough swap space or free it instead of
- calling panic.
-- Support for adding/removing hardware while suspended?
-- We should not free pages at the beginning so aggressively, most of them
- go there anyway..
-- If X is active while suspending then by resuming calling svgatextmode
- corrupts the virtual console of X.. (Maybe this has been fixed AFAIK).
-
-Drivers we support
-- IDE disks are okay
-- vesafb
-
-Drivers that need support
-- pc_keyb -- perhaps we can wait for vojtech's input patches
-- do IDE cdroms need some kind of support?
-- IDE CD-RW -- how to deal with that?
-
-Sleep states summary (thanx, Ducrot)
-====================================
-
-In a really perfect world:
-echo 1 > /proc/acpi/sleep # for standby
-echo 2 > /proc/acpi/sleep # for suspend to ram
-echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative
-echo 4 > /proc/acpi/sleep # for suspend to disk
-echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system
-
-and perhaps
-echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios
-
-
-FAQ:
-
-Q: well, suspending a server is IMHO a really stupid thing,
-but... (Diego Zuccato):
-
-A: You bought new UPS for your server. How do you install it without
-bringing machine down? Suspend to disk, rearrange power cables,
-resume.
-
-You have your server on UPS. Power died, and UPS is indicating 30
-seconds to failure. What do you do? Suspend to disk.
-
-Ethernet card in your server died. You want to replace it. Your
-server is not hotplug capable. What do you do? Suspend to disk,
-replace ethernet card, resume. If you are fast your users will not
-even see broken connections.
-
-Any other idea you might have tell me!
-
-Contacting the author
-If you have any question or any patch that solves the above or detected
-problems please contact me at seasons@falcon.sch.bme.hu. I might delay
-answering, sorry about that.
-
projects / linux / commitdiff