Seth/kernel_amazon_mt8127-common
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6fa3eb70c07b7ce2061fd6602159ac2d45a7dc3d
kernel_amazon_mt8127-common/Documentation/power/tuxonice.txt
T
Stricted 6fa3eb70c0 import PULS_20160108
2018-03-13 20:29:02 +01:00

949 lines
43 KiB
Plaintext
Raw Blame History

--- TuxOnIce, version 3.0 ---
1. What is it?
2. Why would you want it?
3. What do you need to use it?
4. Why not just use the version already in the kernel?
5. How do you use it?
6. What do all those entries in /sys/power/tuxonice do?
7. How do you get support?
8. I think I've found a bug. What should I do?
9. When will XXX be supported?
10 How does it work?
11. Who wrote TuxOnIce?
1. What is it?
Imagine you're sitting at your computer, working away. For some reason, you
need to turn off your computer for a while - perhaps it's time to go home
for the day. When you come back to your computer next, you're going to want
to carry on where you left off. Now imagine that you could push a button and
have your computer store the contents of its memory to disk and power down.
Then, when you next start up your computer, it loads that image back into
memory and you can carry on from where you were, just as if you'd never
turned the computer off. You have far less time to start up, no reopening of
applications or finding what directory you put that file in yesterday.
That's what TuxOnIce does.
TuxOnIce has a long heritage. It began life as work by Gabor Kuti, who,
with some help from Pavel Machek, got an early version going in 1999. The
project was then taken over by Florent Chabaud while still in alpha version
numbers. Nigel Cunningham came on the scene when Florent was unable to
continue, moving the project into betas, then 1.0, 2.0 and so on up to
the present series. During the 2.0 series, the name was contracted to
Suspend2 and the website suspend2.net created. Beginning around July 2007,
a transition to calling the software TuxOnIce was made, to seek to help
make it clear that TuxOnIce is more concerned with hibernation than suspend
to ram.
Pavel Machek's swsusp code, which was merged around 2.5.17 retains the
original name, and was essentially a fork of the beta code until Rafael
Wysocki came on the scene in 2005 and began to improve it further.
2. Why would you want it?
Why wouldn't you want it?
Being able to save the state of your system and quickly restore it improves
your productivity - you get a useful system in far less time than through
the normal boot process. You also get to be completely 'green', using zero
power, or as close to that as possible (the computer may still provide
minimal power to some devices, so they can initiate a power on, but that
will be the same amount of power as would be used if you told the computer
to shutdown.
3. What do you need to use it?
a. Kernel Support.
i) The TuxOnIce patch.
TuxOnIce is part of the Linux Kernel. This version is not part of Linus's
2.6 tree at the moment, so you will need to download the kernel source and
apply the latest patch. Having done that, enable the appropriate options in
make [menu|x]config (under Power Management Options - look for "Enhanced
Hibernation"), compile and install your kernel. TuxOnIce works with SMP,
Highmem, preemption, fuse filesystems, x86-32, PPC and x86_64.
TuxOnIce patches are available from http://tuxonice.net.
ii) Compression support.
Compression support is implemented via the cryptoapi. You will therefore want
to select any Cryptoapi transforms that you want to use on your image from
the Cryptoapi menu while configuring your kernel. We recommend the use of the
LZO compression method - it is very fast and still achieves good compression.
You can also tell TuxOnIce to write its image to an encrypted and/or
compressed filesystem/swap partition. In that case, you don't need to do
anything special for TuxOnIce when it comes to kernel configuration.
iii) Configuring other options.
While you're configuring your kernel, try to configure as much as possible
to build as modules. We recommend this because there are a number of drivers
that are still in the process of implementing proper power management
support. In those cases, the best way to work around their current lack is
to build them as modules and remove the modules while hibernating. You might
also bug the driver authors to get their support up to speed, or even help!
b. Storage.
i) Swap.
TuxOnIce can store the hibernation image in your swap partition, a swap file or
a combination thereof. Whichever combination you choose, you will probably
want to create enough swap space to store the largest image you could have,
plus the space you'd normally use for swap. A good rule of thumb would be
to calculate the amount of swap you'd want without using TuxOnIce, and then
add the amount of memory you have. This swapspace can be arranged in any way
you'd like. It can be in one partition or file, or spread over a number. The
only requirement is that they be active when you start a hibernation cycle.
There is one exception to this requirement. TuxOnIce has the ability to turn
on one swap file or partition at the start of hibernating and turn it back off
at the end. If you want to ensure you have enough memory to store a image
when your memory is fully used, you might want to make one swap partition or
file for 'normal' use, and another for TuxOnIce to activate & deactivate
automatically. (Further details below).
ii) Normal files.
TuxOnIce includes a 'file allocator'. The file allocator can store your
image in a simple file. Since Linux has the concept of everything being a
file, this is more powerful than it initially sounds. If, for example, you
were to set up a network block device file, you could hibernate to a network
server. This has been tested and works to a point, but nbd itself isn't
stateless enough for our purposes.
Take extra care when setting up the file allocator. If you just type
commands without thinking and then try to hibernate, you could cause
irreversible corruption on your filesystems! Make sure you have backups.
Most people will only want to hibernate to a local file. To achieve that, do
something along the lines of:
echo "TuxOnIce" > /hibernation-file
dd if=/dev/zero bs=1M count=512 >> /hibernation-file
This will create a 512MB file called /hibernation-file. To get TuxOnIce to use
it:
echo /hibernation-file > /sys/power/tuxonice/file/target
Then
cat /sys/power/tuxonice/resume
Put the results of this into your bootloader's configuration (see also step
C, below):
---EXAMPLE-ONLY-DON'T-COPY-AND-PASTE---
# cat /sys/power/tuxonice/resume
file:/dev/hda2:0x1e001
In this example, we would edit the append= line of our lilo.conf|menu.lst
so that it included:
resume=file:/dev/hda2:0x1e001
---EXAMPLE-ONLY-DON'T-COPY-AND-PASTE---
For those who are thinking 'Could I make the file sparse?', the answer is
'No!'. At the moment, there is no way for TuxOnIce to fill in the holes in
a sparse file while hibernating. In the longer term (post merge!), I'd like
to change things so that the file could be dynamically resized and have
holes filled as needed. Right now, however, that's not possible and not a
priority.
c. Bootloader configuration.
Using TuxOnIce also requires that you add an extra parameter to
your lilo.conf or equivalent. Here's an example for a swap partition:
append="resume=swap:/dev/hda1"
This would tell TuxOnIce that /dev/hda1 is a swap partition you
have. TuxOnIce will use the swap signature of this partition as a
pointer to your data when you hibernate. This means that (in this example)
/dev/hda1 doesn't need to be _the_ swap partition where all of your data
is actually stored. It just needs to be a swap partition that has a
valid signature.
You don't need to have a swap partition for this purpose. TuxOnIce
can also use a swap file, but usage is a little more complex. Having made
your swap file, turn it on and do
cat /sys/power/tuxonice/swap/headerlocations
(this assumes you've already compiled your kernel with TuxOnIce
support and booted it). The results of the cat command will tell you
what you need to put in lilo.conf:
For swap partitions like /dev/hda1, simply use resume=/dev/hda1.
For swapfile `swapfile`, use resume=swap:/dev/hda2:0x242d.
If the swapfile changes for any reason (it is moved to a different
location, it is deleted and recreated, or the filesystem is
defragmented) then you will have to check
/sys/power/tuxonice/swap/headerlocations for a new resume_block value.
Once you've compiled and installed the kernel and adjusted your bootloader
configuration, you should only need to reboot for the most basic part
of TuxOnIce to be ready.
If you only compile in the swap allocator, or only compile in the file
allocator, you don't need to add the "swap:" part of the resume=
parameters above. resume=/dev/hda2:0x242d will work just as well. If you
have compiled both and your storage is on swap, you can also use this
format (the swap allocator is the default allocator).
When compiling your kernel, one of the options in the 'Power Management
Support' menu, just above the 'Enhanced Hibernation (TuxOnIce)' entry is
called 'Default resume partition'. This can be used to set a default value
for the resume= parameter.
d. The hibernate script.
Since the driver model in 2.6 kernels is still being developed, you may need
to do more than just configure TuxOnIce. Users of TuxOnIce usually start the
process via a script which prepares for the hibernation cycle, tells the
kernel to do its stuff and then restore things afterwards. This script might
involve:
- Switching to a text console and back if X doesn't like the video card
status on resume.
- Un/reloading drivers that don't play well with hibernation.
Note that you might not be able to unload some drivers if there are
processes using them. You might have to kill off processes that hold
devices open. Hint: if your X server accesses an USB mouse, doing a
'chvt' to a text console releases the device and you can unload the
module.
Check out the latest script (available on tuxonice.net).
e. The userspace user interface.
TuxOnIce has very limited support for displaying status if you only apply
the kernel patch - it can printk messages, but that is all. In addition,
some of the functions mentioned in this document (such as cancelling a cycle
or performing interactive debugging) are unavailable. To utilise these
functions, or simply get a nice display, you need the 'userui' component.
Userui comes in three flavours, usplash, fbsplash and text. Text should
work on any console. Usplash and fbsplash require the appropriate
(distro specific?) support.
To utilise a userui, TuxOnIce just needs to be told where to find the
userspace binary:
echo "/usr/local/sbin/tuxoniceui_fbsplash" > /sys/power/tuxonice/user_interface/program
The hibernate script can do this for you, and a default value for this
setting can be configured when compiling the kernel. This path is also
stored in the image header, so if you have an initrd or initramfs, you can
use the userui during the first part of resuming (prior to the atomic
restore) by putting the binary in the same path in your initrd/ramfs.
Alternatively, you can put it in a different location and do an echo
similar to the above prior to the echo > do_resume. The value saved in the
image header will then be ignored.
4. Why not just use the version already in the kernel?
The version in the vanilla kernel has a number of drawbacks. The most
serious of these are:
- it has a maximum image size of 1/2 total memory;
- it doesn't allocate storage until after it has snapshotted memory.
This means that you can't be sure hibernating will work until you
see it start to write the image;
- it does not allow you to press escape to cancel a cycle;
- it does not allow you to press escape to cancel resuming;
- it does not allow you to automatically swapon a file when
starting a cycle;
- it does not allow you to use multiple swap partitions or files;
- it does not allow you to use ordinary files;
- it just invalidates an image and continues to boot if you
accidentally boot the wrong kernel after hibernating;
- it doesn't support any sort of nice display while hibernating;
- it is moving toward requiring that you have an initrd/initramfs
to ever have a hope of resuming (uswsusp). While uswsusp will
address some of the concerns above, it won't address all of them,
and will be more complicated to get set up;
- it doesn't have support for suspend-to-both (write a hibernation
image, then suspend to ram; I think this is known as ReadySafe
under M$).
5. How do you use it?
A hibernation cycle can be started directly by doing:
echo > /sys/power/tuxonice/do_hibernate
In practice, though, you'll probably want to use the hibernate script
to unload modules, configure the kernel the way you like it and so on.
In that case, you'd do (as root):
hibernate
See the hibernate script's man page for more details on the options it
takes.
If you're using the text or splash user interface modules, one feature of
TuxOnIce that you might find useful is that you can press Escape at any time
during hibernating, and the process will be aborted.
Due to the way hibernation works, this means you'll have your system back and
perfectly usable almost instantly. The only exception is when it's at the
very end of writing the image. Then it will need to reload a small (usually
4-50MBs, depending upon the image characteristics) portion first.
Likewise, when resuming, you can press escape and resuming will be aborted.
The computer will then powerdown again according to settings at that time for
the powerdown method or rebooting.
You can change the settings for powering down while the image is being
written by pressing 'R' to toggle rebooting and 'O' to toggle between
suspending to ram and powering down completely).
If you run into problems with resuming, adding the "noresume" option to
the kernel command line will let you skip the resume step and recover your
system. This option shouldn't normally be needed, because TuxOnIce modifies
the image header prior to the atomic restore, and will thus prompt you
if it detects that you've tried to resume an image before (this flag is
removed if you press Escape to cancel a resume, so you won't be prompted
then).
Recent kernels (2.6.24 onwards) add support for resuming from a different
kernel to the one that was hibernated (thanks to Rafael for his work on
this - I've just embraced and enhanced the support for TuxOnIce). This
should further reduce the need for you to use the noresume option.
6. What do all those entries in /sys/power/tuxonice do?
/sys/power/tuxonice is the directory which contains files you can use to
tune and configure TuxOnIce to your liking. The exact contents of
the directory will depend upon the version of TuxOnIce you're
running and the options you selected at compile time. In the following
descriptions, names in brackets refer to compile time options.
(Note that they're all dependant upon you having selected CONFIG_TUXONICE
in the first place!).
Since the values of these settings can open potential security risks, the
writeable ones are accessible only to the root user. You may want to
configure sudo to allow you to invoke your hibernate script as an ordinary
user.
- alloc/failure_test
This debugging option provides a way of testing TuxOnIce's handling of
memory allocation failures. Each allocation type that TuxOnIce makes has
been given a unique number (see the source code). Echo the appropriate
number into this entry, and when TuxOnIce attempts to do that allocation,
it will pretend there was a failure and act accordingly.
- alloc/find_max_mem_allocated
This debugging option will cause TuxOnIce to find the maximum amount of
memory it used during a cycle, and report that information in debugging
information at the end of the cycle.
- alt_resume_param
Instead of powering down after writing a hibernation image, TuxOnIce
supports resuming from a different image. This entry lets you set the
location of the signature for that image (the resume= value you'd use
for it). Using an alternate image and keep_image mode, you can do things
like using an alternate image to power down an uninterruptible power
supply.
- block_io/target_outstanding_io
This value controls the amount of memory that the block I/O code says it
needs when the core code is calculating how much memory is needed for
hibernating and for resuming. It doesn't directly control the amount of
I/O that is submitted at any one time - that depends on the amount of
available memory (we may have more available than we asked for), the
throughput that is being achieved and the ability of the CPU to keep up
with disk throughput (particularly where we're compressing pages).
- checksum/enabled
Use cryptoapi hashing routines to verify that Pageset2 pages don't change
while we're saving the first part of the image, and to get any pages that
do change resaved in the atomic copy. This should normally not be needed,
but if you're seeing issues, please enable this. If your issues stop you
being able to resume, enable this option, hibernate and cancel the cycle
after the atomic copy is done. If the debugging info shows a non-zero
number of pages resaved, please report this to Nigel.
- compression/algorithm
Set the cryptoapi algorithm used for compressing the image.
- compression/expected_compression
These values allow you to set an expected compression ratio, which TuxOnice
will use in calculating whether it meets constraints on the image size. If
this expected compression ratio is not attained, the hibernation cycle will
abort, so it is wise to allow some spare. You can see what compression
ratio is achieved in the logs after hibernating.
- debug_info:
This file returns information about your configuration that may be helpful
in diagnosing problems with hibernating.
- did_suspend_to_both:
This file can be used when you hibernate with powerdown method 3 (ie suspend
to ram after writing the image). There can be two outcomes in this case. We
can resume from the suspend-to-ram before the battery runs out, or we can run
out of juice and and up resuming like normal. This entry lets you find out,
post resume, which way we went. If the value is 1, we resumed from suspend
to ram. This can be useful when actions need to be run post suspend-to-ram
that don't need to be run if we did the normal resume from power off.
- do_hibernate:
When anything is written to this file, the kernel side of TuxOnIce will
begin to attempt to write an image to disk and power down. You'll normally
want to run the hibernate script instead, to get modules unloaded first.
- do_resume:
When anything is written to this file TuxOnIce will attempt to read and
restore an image. If there is no image, it will return almost immediately.
If an image exists, the echo > will never return. Instead, the original
kernel context will be restored and the original echo > do_hibernate will
return.
- */enabled
These option can be used to temporarily disable various parts of TuxOnIce.
- extra_pages_allowance
When TuxOnIce does its atomic copy, it calls the driver model suspend
and resume methods. If you have DRI enabled with a driver such as fglrx,
this can result in the driver allocating a substantial amount of memory
for storing its state. Extra_pages_allowance tells TuxOnIce how much
extra memory it should ensure is available for those allocations. If
your attempts at hibernating end with a message in dmesg indicating that
insufficient extra pages were allowed, you need to increase this value.
- file/target:
Read this value to get the current setting. Write to it to point TuxOnice
at a new storage location for the file allocator. See section 3.b.ii above
for details of how to set up the file allocator.
- freezer_test
This entry can be used to get TuxOnIce to just test the freezer and prepare
an image without actually doing a hibernation cycle. It is useful for
diagnosing freezing and image preparation issues.
- full_pageset2
TuxOnIce divides the pages that are stored in an image into two sets. The
difference between the two sets is that pages in pageset 1 are atomically
copied, and pages in pageset 2 are written to disk without being copied
first. A page CAN be written to disk without being copied first if and only
if its contents will not be modified or used at any time after userspace
processes are frozen. A page MUST be in pageset 1 if its contents are
modified or used at any time after userspace processes have been frozen.
Normally (ie if this option is enabled), TuxOnIce will put all pages on the
per-zone LRUs in pageset2, then remove those pages used by any userspace
user interface helper and TuxOnIce storage manager that are running,
together with pages used by the GEM memory manager introduced around 2.6.28
kernels.
If this option is disabled, a much more conservative approach will be taken.
The only pages in pageset2 will be those belonging to userspace processes,
with the exclusion of those belonging to the TuxOnIce userspace helpers
mentioned above. This will result in a much smaller pageset2, and will
therefore result in smaller images than are possible with this option
enabled.
- ignore_rootfs
TuxOnIce records which device is mounted as the root filesystem when
writing the hibernation image. It will normally check at resume time that
this device isn't already mounted - that would be a cause of filesystem
corruption. In some particular cases (RAM based root filesystems), you
might want to disable this check. This option allows you to do that.
- image_exists:
Can be used in a script to determine whether a valid image exists at the
location currently pointed to by resume=. Returns up to three lines.
The first is whether an image exists (-1 for unsure, otherwise 0 or 1).
If an image eixsts, additional lines will return the machine and version.
Echoing anything to this entry removes any current image.
- image_size_limit:
The maximum size of hibernation image written to disk, measured in megabytes
(1024*1024).
- last_result:
The result of the last hibernation cycle, as defined in
include/linux/suspend-debug.h with the values SUSPEND_ABORTED to
SUSPEND_KEPT_IMAGE. This is a bitmask.
- late_cpu_hotplug:
This sysfs entry controls whether cpu hotplugging is done - as normal - just
before (unplug) and after (replug) the atomic copy/restore (so that all
CPUs/cores are available for multithreaded I/O). The alternative is to
unplug all secondary CPUs/cores at the start of hibernating/resuming, and
replug them at the end of resuming. No multithreaded I/O will be possible in
this configuration, but the odd machine has been reported to require it.
- lid_file:
This determines which ACPI button file we look in to determine whether the
lid is open or closed after resuming from suspend to disk or power off.
If the entry is set to "lid/LID", we'll open /proc/acpi/button/lid/LID/state
and check its contents at the appropriate moment. See post_wake_state below
for more details on how this entry is used.
- log_everything (CONFIG_PM_DEBUG):
Setting this option results in all messages printed being logged. Normally,
only a subset are logged, so as to not slow the process and not clutter the
logs. Useful for debugging. It can be toggled during a cycle by pressing
'L'.
- no_load_direct:
This is a debugging option. If, when loading the atomically copied pages of
an image, TuxOnIce finds that the destination address for a page is free,
it will normally allocate the image, load the data directly into that
address and skip it in the atomic restore. If this option is disabled, the
page will be loaded somewhere else and atomically restored like other pages.
- no_flusher_thread:
When doing multithreaded I/O (see below), the first online CPU can be used
to _just_ submit compressed pages when writing the image, rather than
compressing and submitting data. This option is normally disabled, but has
been included because Nigel would like to see whether it will be more useful
as the number of cores/cpus in computers increases.
- no_multithreaded_io:
TuxOnIce will normally create one thread per cpu/core on your computer,
each of which will then perform I/O. This will generally result in
throughput that's the maximum the storage medium can handle. There
shouldn't be any reason to disable multithreaded I/O now, but this option
has been retained for debugging purposes.
- no_pageset2
See the entry for full_pageset2 above for an explanation of pagesets.
Enabling this option causes TuxOnIce to do an atomic copy of all pages,
thereby limiting the maximum image size to 1/2 of memory, as swsusp does.
- no_pageset2_if_unneeded
See the entry for full_pageset2 above for an explanation of pagesets.
Enabling this option causes TuxOnIce to act like no_pageset2 was enabled
if and only it isn't needed anyway. This option may still make TuxOnIce
less reliable because pageset2 pages are normally used to store the
atomic copy - drivers that want to do allocations of larger amounts of
memory in one shot will be more likely to find that those amounts aren't
available if this option is enabled.
- pause_between_steps (CONFIG_PM_DEBUG):
This option is used during debugging, to make TuxOnIce pause between
each step of the process. It is ignored when the nice display is on.
- post_wake_state:
TuxOnIce provides support for automatically waking after a user-selected
delay, and using a different powerdown method if the lid is still closed.
(Yes, we're assuming a laptop). This entry lets you choose what state
should be entered next. The values are those described under
powerdown_method, below. It can be used to suspend to RAM after hibernating,
then powerdown properly (say) 20 minutes. It can also be used to power down
properly, then wake at (say) 6.30am and suspend to RAM until you're ready
to use the machine.
- powerdown_method:
Used to select a method by which TuxOnIce should powerdown after writing the
image. Currently:
0: Don't use ACPI to power off.
3: Attempt to enter Suspend-to-ram.
4: Attempt to enter ACPI S4 mode.
5: Attempt to power down via ACPI S5 mode.
Note that these options are highly dependant upon your hardware & software:
3: When succesful, your machine suspends to ram instead of powering off.
The advantage of using this mode is that it doesn't matter whether your
battery has enough charge to make it through to your next resume. If it
lasts, you will simply resume from suspend to ram (and the image on disk
will be discarded). If the battery runs out, you will resume from disk
instead. The disadvantage is that it takes longer than a normal
suspend-to-ram to enter the state, since the suspend-to-disk image needs
to be written first.
4/5: When successful, your machine will be off and comsume (almost) no power.
But it might still react to some external events like opening the lid or
trafic on a network or usb device. For the bios, resume is then the same
as warm boot, similar to a situation where you used the command `reboot'
to reboot your machine. If your machine has problems on warm boot or if
you want to protect your machine with the bios password, this is probably
not the right choice. Mode 4 may be necessary on some machines where ACPI
wake up methods need to be run to properly reinitialise hardware after a
hibernation cycle.
0: Switch the machine completely off. The only possible wakeup is the power
button. For the bios, resume is then the same as a cold boot, in
particular you would have to provide your bios boot password if your
machine uses that feature for booting.
- progressbar_granularity_limit:
This option can be used to limit the granularity of the progress bar
displayed with a bootsplash screen. The value is the maximum number of
steps. That is, 10 will make the progress bar jump in 10% increments.
- reboot:
This option causes TuxOnIce to reboot rather than powering down
at the end of saving an image. It can be toggled during a cycle by pressing
'R'.
- resume:
This sysfs entry can be used to read and set the location in which TuxOnIce
will look for the signature of an image - the value set using resume= at
boot time or CONFIG_PM_STD_PARTITION ("Default resume partition"). By
writing to this file as well as modifying your bootloader's configuration
file (eg menu.lst), you can set or reset the location of your image or the
method of storing the image without rebooting.
- replace_swsusp (CONFIG_TOI_REPLACE_SWSUSP):
This option makes
echo disk > /sys/power/state
activate TuxOnIce instead of swsusp. Regardless of whether this option is
enabled, any invocation of swsusp's resume time trigger will cause TuxOnIce
to check for an image too. This is due to the fact that at resume time, we
can't know whether this option was enabled until we see if an image is there
for us to resume from. (And when an image exists, we don't care whether we
did replace swsusp anyway - we just want to resume).
- resume_commandline:
This entry can be read after resuming to see the commandline that was used
when resuming began. You might use this to set up two bootloader entries
that are the same apart from the fact that one includes a extra append=
argument "at_work=1". You could then grep resume_commandline in your
post-resume scripts and configure networking (for example) differently
depending upon whether you're at home or work. resume_commandline can be
set to arbitrary text if you wish to remove sensitive contents.
- swap/swapfilename:
This entry is used to specify the swapfile or partition that
TuxOnIce will attempt to swapon/swapoff automatically. Thus, if
I normally use /dev/hda1 for swap, and want to use /dev/hda2 for specifically
for my hibernation image, I would
echo /dev/hda2 > /sys/power/tuxonice/swap/swapfile
/dev/hda2 would then be automatically swapon'd and swapoff'd. Note that the
swapon and swapoff occur while other processes are frozen (including kswapd)
so this swap file will not be used up when attempting to free memory. The
parition/file is also given the highest priority, so other swapfiles/partitions
will only be used to save the image when this one is filled.
The value of this file is used by headerlocations along with any currently
activated swapfiles/partitions.
- swap/headerlocations:
This option tells you the resume= options to use for swap devices you
currently have activated. It is particularly useful when you only want to
use a swap file to store your image. See above for further details.
- test_bio
This is a debugging option. When enabled, TuxOnIce will not hibernate.
Instead, when asked to write an image, it will skip the atomic copy,
just doing the writing of the image and then returning control to the
user at the point where it would have powered off. This is useful for
testing throughput in different configurations.
- test_filter_speed
This is a debugging option. When enabled, TuxOnIce will not hibernate.
Instead, when asked to write an image, it will not write anything or do
an atomic copy, but will only run any enabled compression algorithm on the
data that would have been written (the source pages of the atomic copy in
the case of pageset 1). This is useful for comparing the performance of
compression algorithms and for determining the extent to which an upgrade
to your storage method would improve hibernation speed.
- user_interface/debug_sections (CONFIG_PM_DEBUG):
This value, together with the console log level, controls what debugging
information is displayed. The console log level determines the level of
detail, and this value determines what detail is displayed. This value is
a bit vector, and the meaning of the bits can be found in the kernel tree
in include/linux/tuxonice.h. It can be overridden using the kernel's
command line option suspend_dbg.
- user_interface/default_console_level (CONFIG_PM_DEBUG):
This determines the value of the console log level at the start of a
hibernation cycle. If debugging is compiled in, the console log level can be
changed during a cycle by pressing the digit keys. Meanings are:
0: Nice display.
1: Nice display plus numerical progress.
2: Errors only.
3: Low level debugging info.
4: Medium level debugging info.
5: High level debugging info.
6: Verbose debugging info.
- user_interface/enable_escape:
Setting this to "1" will enable you abort a hibernation cycle or resuming by
pressing escape, "0" (default) disables this feature. Note that enabling
this option means that you cannot initiate a hibernation cycle and then walk
away from your computer, expecting it to be secure. With feature disabled,
you can validly have this expectation once TuxOnice begins to write the
image to disk. (Prior to this point, it is possible that TuxOnice might
about because of failure to freeze all processes or because constraints
on its ability to save the image are not met).
- user_interface/program
This entry is used to tell TuxOnice what userspace program to use for
providing a user interface while hibernating. The program uses a netlink
socket to pass messages back and forward to the kernel, allowing all of the
functions formerly implemented in the kernel user interface components.
- version:
The version of TuxOnIce you have compiled into the currently running kernel.
- wake_alarm_dir:
As mentioned above (post_wake_state), TuxOnIce supports automatically waking
after some delay. This entry allows you to select which wake alarm to use.
It should contain the value "rtc0" if you're wanting to use
/sys/class/rtc/rtc0.
- wake_delay:
This value determines the delay from the end of writing the image until the
wake alarm is triggered. You can set an absolute time by writing the desired
time into /sys/class/rtc/<wake_alarm_dir>/wakealarm and leaving these values
empty.
Note that for the wakeup to actually occur, you may need to modify entries
in /proc/acpi/wakeup. This is done by echoing the name of the button in the
first column (eg PBTN) into the file.
7. How do you get support?
Glad you asked. TuxOnIce is being actively maintained and supported
by Nigel (the guy doing most of the kernel coding at the moment), Bernard
(who maintains the hibernate script and userspace user interface components)
and its users.
Resources availble include HowTos, FAQs and a Wiki, all available via
tuxonice.net. You can find the mailing lists there.
8. I think I've found a bug. What should I do?
By far and a way, the most common problems people have with TuxOnIce
related to drivers not having adequate power management support. In this
case, it is not a bug with TuxOnIce, but we can still help you. As we
mentioned above, such issues can usually be worked around by building the
functionality as modules and unloading them while hibernating. Please visit
the Wiki for up-to-date lists of known issues and work arounds.
If this information doesn't help, try running:
hibernate --bug-report
..and sending the output to the users mailing list.
Good information on how to provide us with useful information from an
oops is found in the file REPORTING-BUGS, in the top level directory
of the kernel tree. If you get an oops, please especially note the
information about running what is printed on the screen through ksymoops.
The raw information is useless.
9. When will XXX be supported?
If there's a feature missing from TuxOnIce that you'd like, feel free to
ask. We try to be obliging, within reason.
Patches are welcome. Please send to the list.
10. How does it work?
TuxOnIce does its work in a number of steps.
a. Freezing system activity.
The first main stage in hibernating is to stop all other activity. This is
achieved in stages. Processes are considered in fours groups, which we will
describe in reverse order for clarity's sake: Threads with the PF_NOFREEZE
flag, kernel threads without this flag, userspace processes with the
PF_SYNCTHREAD flag and all other processes. The first set (PF_NOFREEZE) are
untouched by the refrigerator code. They are allowed to run during hibernating
and resuming, and are used to support user interaction, storage access or the
like. Other kernel threads (those unneeded while hibernating) are frozen last.
This leaves us with userspace processes that need to be frozen. When a
process enters one of the *_sync system calls, we set a PF_SYNCTHREAD flag on
that process for the duration of that call. Processes that have this flag are
frozen after processes without it, so that we can seek to ensure that dirty
data is synced to disk as quickly as possible in a situation where other
processes may be submitting writes at the same time. Freezing the processes
that are submitting data stops new I/O from being submitted. Syncthreads can
then cleanly finish their work. So the order is:
- Userspace processes without PF_SYNCTHREAD or PF_NOFREEZE;
- Userspace processes with PF_SYNCTHREAD (they won't have NOFREEZE);
- Kernel processes without PF_NOFREEZE.
b. Eating memory.
For a successful hibernation cycle, you need to have enough disk space to store the
image and enough memory for the various limitations of TuxOnIce's
algorithm. You can also specify a maximum image size. In order to attain
to those constraints, TuxOnIce may 'eat' memory. If, after freezing
processes, the constraints aren't met, TuxOnIce will thaw all the
other processes and begin to eat memory until its calculations indicate
the constraints are met. It will then freeze processes again and recheck
its calculations.
c. Allocation of storage.
Next, TuxOnIce allocates the storage that will be used to save
the image.
The core of TuxOnIce knows nothing about how or where pages are stored. We
therefore request the active allocator (remember you might have compiled in
more than one!) to allocate enough storage for our expect image size. If
this request cannot be fulfilled, we eat more memory and try again. If it
is fulfiled, we seek to allocate additional storage, just in case our
expected compression ratio (if any) isn't achieved. This time, however, we
just continue if we can't allocate enough storage.
If these calls to our allocator change the characteristics of the image
such that we haven't allocated enough memory, we also loop. (The allocator
may well need to allocate space for its storage information).
d. Write the first part of the image.
TuxOnIce stores the image in two sets of pages called 'pagesets'.
Pageset 2 contains pages on the active and inactive lists; essentially
the page cache. Pageset 1 contains all other pages, including the kernel.
We use two pagesets for one important reason: We need to make an atomic copy
of the kernel to ensure consistency of the image. Without a second pageset,
that would limit us to an image that was at most half the amount of memory
available. Using two pagesets allows us to store a full image. Since pageset
2 pages won't be needed in saving pageset 1, we first save pageset 2 pages.
We can then make our atomic copy of the remaining pages using both pageset 2
pages and any other pages that are free. While saving both pagesets, we are
careful not to corrupt the image. Among other things, we use lowlevel block
I/O routines that don't change the pagecache contents.
The next step, then, is writing pageset 2.
e. Suspending drivers and storing processor context.
Having written pageset2, TuxOnIce calls the power management functions to
notify drivers of the hibernation, and saves the processor state in preparation
for the atomic copy of memory we are about to make.
f. Atomic copy.
At this stage, everything else but the TuxOnIce code is halted. Processes
are frozen or idling, drivers are quiesced and have stored (ideally and where
necessary) their configuration in memory we are about to atomically copy.
In our lowlevel architecture specific code, we have saved the CPU state.
We can therefore now do our atomic copy before resuming drivers etc.
g. Save the atomic copy (pageset 1).
TuxOnice can then write the atomic copy of the remaining pages. Since we
have copied the pages into other locations, we can continue to use the
normal block I/O routines without fear of corruption our image.
f. Save the image header.
Nearly there! We save our settings and other parameters needed for
reloading pageset 1 in an 'image header'. We also tell our allocator to
serialise its data at this stage, so that it can reread the image at resume
time.
g. Set the image header.
Finally, we edit the header at our resume= location. The signature is
changed by the allocator to reflect the fact that an image exists, and to
point to the start of that data if necessary (swap allocator).
h. Power down.
Or reboot if we're debugging and the appropriate option is selected.
Whew!
Reloading the image.
--------------------
Reloading the image is essentially the reverse of all the above. We load
our copy of pageset 1, being careful to choose locations that aren't going
to be overwritten as we copy it back (We start very early in the boot
process, so there are no other processes to quiesce here). We then copy
pageset 1 back to its original location in memory and restore the process
context. We are now running with the original kernel. Next, we reload the
pageset 2 pages, free the memory and swap used by TuxOnIce, restore
the pageset header and restart processes. Sounds easy in comparison to
hibernating, doesn't it!
There is of course more to TuxOnIce than this, but this explanation
should be a good start. If there's interest, I'll write further
documentation on range pages and the low level I/O.
11. Who wrote TuxOnIce?
(Answer based on the writings of Florent Chabaud, credits in files and
Nigel's limited knowledge; apologies to anyone missed out!)
The main developers of TuxOnIce have been...
Gabor Kuti
Pavel Machek
Florent Chabaud
Bernard Blackham
Nigel Cunningham
Significant portions of swsusp, the code in the vanilla kernel which
TuxOnIce enhances, have been worked on by Rafael Wysocki. Thanks should
also be expressed to him.
The above mentioned developers have been aided in their efforts by a host
of hundreds, if not thousands of testers and people who have submitted bug
fixes & suggestions. Of special note are the efforts of Michael Frank, who
had his computers repetitively hibernate and resume for literally tens of
thousands of cycles and developed scripts to stress the system and test
TuxOnIce far beyond the point most of us (Nigel included!) would consider
testing. His efforts have contributed as much to TuxOnIce as any of the
names above.
Reference in New Issue View Git Blame Copy Permalink