aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/power/freezing-of-tasks.txt')
-rw-r--r--Documentation/power/freezing-of-tasks.txt47
1 files changed, 36 insertions, 11 deletions
diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.txt
index 38b57248fd61..6ccb68f68da6 100644
--- a/Documentation/power/freezing-of-tasks.txt
+++ b/Documentation/power/freezing-of-tasks.txt
@@ -21,18 +21,18 @@ freeze_processes() (defined in kernel/power/process.c) is called. It executes
21try_to_freeze_tasks() that sets TIF_FREEZE for all of the freezable tasks and 21try_to_freeze_tasks() that sets TIF_FREEZE for all of the freezable tasks and
22either wakes them up, if they are kernel threads, or sends fake signals to them, 22either wakes them up, if they are kernel threads, or sends fake signals to them,
23if they are user space processes. A task that has TIF_FREEZE set, should react 23if they are user space processes. A task that has TIF_FREEZE set, should react
24to it by calling the function called refrigerator() (defined in 24to it by calling the function called __refrigerator() (defined in
25kernel/power/process.c), which sets the task's PF_FROZEN flag, changes its state 25kernel/freezer.c), which sets the task's PF_FROZEN flag, changes its state
26to TASK_UNINTERRUPTIBLE and makes it loop until PF_FROZEN is cleared for it. 26to TASK_UNINTERRUPTIBLE and makes it loop until PF_FROZEN is cleared for it.
27Then, we say that the task is 'frozen' and therefore the set of functions 27Then, we say that the task is 'frozen' and therefore the set of functions
28handling this mechanism is referred to as 'the freezer' (these functions are 28handling this mechanism is referred to as 'the freezer' (these functions are
29defined in kernel/power/process.c and include/linux/freezer.h). User space 29defined in kernel/power/process.c, kernel/freezer.c & include/linux/freezer.h).
30processes are generally frozen before kernel threads. 30User space processes are generally frozen before kernel threads.
31 31
32It is not recommended to call refrigerator() directly. Instead, it is 32__refrigerator() must not be called directly. Instead, use the
33recommended to use the try_to_freeze() function (defined in 33try_to_freeze() function (defined in include/linux/freezer.h), that checks
34include/linux/freezer.h), that checks the task's TIF_FREEZE flag and makes the 34the task's TIF_FREEZE flag and makes the task enter __refrigerator() if the
35task enter refrigerator() if the flag is set. 35flag is set.
36 36
37For user space processes try_to_freeze() is called automatically from the 37For user space processes try_to_freeze() is called automatically from the
38signal-handling code, but the freezable kernel threads need to call it 38signal-handling code, but the freezable kernel threads need to call it
@@ -61,13 +61,13 @@ wait_event_freezable() and wait_event_freezable_timeout() macros.
61After the system memory state has been restored from a hibernation image and 61After the system memory state has been restored from a hibernation image and
62devices have been reinitialized, the function thaw_processes() is called in 62devices have been reinitialized, the function thaw_processes() is called in
63order to clear the PF_FROZEN flag for each frozen task. Then, the tasks that 63order to clear the PF_FROZEN flag for each frozen task. Then, the tasks that
64have been frozen leave refrigerator() and continue running. 64have been frozen leave __refrigerator() and continue running.
65 65
66III. Which kernel threads are freezable? 66III. Which kernel threads are freezable?
67 67
68Kernel threads are not freezable by default. However, a kernel thread may clear 68Kernel threads are not freezable by default. However, a kernel thread may clear
69PF_NOFREEZE for itself by calling set_freezable() (the resetting of PF_NOFREEZE 69PF_NOFREEZE for itself by calling set_freezable() (the resetting of PF_NOFREEZE
70directly is strongly discouraged). From this point it is regarded as freezable 70directly is not allowed). From this point it is regarded as freezable
71and must call try_to_freeze() in a suitable place. 71and must call try_to_freeze() in a suitable place.
72 72
73IV. Why do we do that? 73IV. Why do we do that?
@@ -95,7 +95,7 @@ after the memory for the image has been freed, we don't want tasks to allocate
95additional memory and we prevent them from doing that by freezing them earlier. 95additional memory and we prevent them from doing that by freezing them earlier.
96[Of course, this also means that device drivers should not allocate substantial 96[Of course, this also means that device drivers should not allocate substantial
97amounts of memory from their .suspend() callbacks before hibernation, but this 97amounts of memory from their .suspend() callbacks before hibernation, but this
98is e separate issue.] 98is a separate issue.]
99 99
1003. The third reason is to prevent user space processes and some kernel threads 1003. The third reason is to prevent user space processes and some kernel threads
101from interfering with the suspending and resuming of devices. A user space 101from interfering with the suspending and resuming of devices. A user space
@@ -176,3 +176,28 @@ tasks, since it generally exists anyway.
176A driver must have all firmwares it may need in RAM before suspend() is called. 176A driver must have all firmwares it may need in RAM before suspend() is called.
177If keeping them is not practical, for example due to their size, they must be 177If keeping them is not practical, for example due to their size, they must be
178requested early enough using the suspend notifier API described in notifiers.txt. 178requested early enough using the suspend notifier API described in notifiers.txt.
179
180VI. Are there any precautions to be taken to prevent freezing failures?
181
182Yes, there are.
183
184First of all, grabbing the 'pm_mutex' lock to mutually exclude a piece of code
185from system-wide sleep such as suspend/hibernation is not encouraged.
186If possible, that piece of code must instead hook onto the suspend/hibernation
187notifiers to achieve mutual exclusion. Look at the CPU-Hotplug code
188(kernel/cpu.c) for an example.
189
190However, if that is not feasible, and grabbing 'pm_mutex' is deemed necessary,
191it is strongly discouraged to directly call mutex_[un]lock(&pm_mutex) since
192that could lead to freezing failures, because if the suspend/hibernate code
193successfully acquired the 'pm_mutex' lock, and hence that other entity failed
194to acquire the lock, then that task would get blocked in TASK_UNINTERRUPTIBLE
195state. As a consequence, the freezer would not be able to freeze that task,
196leading to freezing failure.
197
198However, the [un]lock_system_sleep() APIs are safe to use in this scenario,
199since they ask the freezer to skip freezing this task, since it is anyway
200"frozen enough" as it is blocked on 'pm_mutex', which will be released
201only after the entire suspend/hibernation sequence is complete.
202So, to summarize, use [un]lock_system_sleep() instead of directly using
203mutex_[un]lock(&pm_mutex). That would prevent freezing failures.