diff options
author | Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com> | 2011-12-07 16:30:09 -0500 |
---|---|---|
committer | Rafael J. Wysocki <rjw@sisk.pl> | 2011-12-08 17:22:45 -0500 |
commit | cba3176e88fa134ece3ae1cf7e35dab9972d7853 (patch) | |
tree | 87e5eb4cdbda2f2ffeffab35a02710c2f6e81d2b /Documentation/power | |
parent | bcda53faf5814c0c6025a0bd47108adfcbe9f199 (diff) |
PM / Sleep: Recommend [un]lock_system_sleep() over using pm_mutex directly
Update the documentation to explain the perils of directly using
mutex_[un]lock(&pm_mutex) and recommend the usage of the safe
APIs [un]lock_system_sleep() instead.
Signed-off-by: Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
Signed-off-by: Rafael J. Wysocki <rjw@sisk.pl>
Diffstat (limited to 'Documentation/power')
-rw-r--r-- | Documentation/power/freezing-of-tasks.txt | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.txt index 3ab9fbd2800a..6ccb68f68da6 100644 --- a/Documentation/power/freezing-of-tasks.txt +++ b/Documentation/power/freezing-of-tasks.txt | |||
@@ -176,3 +176,28 @@ tasks, since it generally exists anyway. | |||
176 | A driver must have all firmwares it may need in RAM before suspend() is called. | 176 | A driver must have all firmwares it may need in RAM before suspend() is called. |
177 | If keeping them is not practical, for example due to their size, they must be | 177 | If keeping them is not practical, for example due to their size, they must be |
178 | requested early enough using the suspend notifier API described in notifiers.txt. | 178 | requested early enough using the suspend notifier API described in notifiers.txt. |
179 | |||
180 | VI. Are there any precautions to be taken to prevent freezing failures? | ||
181 | |||
182 | Yes, there are. | ||
183 | |||
184 | First of all, grabbing the 'pm_mutex' lock to mutually exclude a piece of code | ||
185 | from system-wide sleep such as suspend/hibernation is not encouraged. | ||
186 | If possible, that piece of code must instead hook onto the suspend/hibernation | ||
187 | notifiers to achieve mutual exclusion. Look at the CPU-Hotplug code | ||
188 | (kernel/cpu.c) for an example. | ||
189 | |||
190 | However, if that is not feasible, and grabbing 'pm_mutex' is deemed necessary, | ||
191 | it is strongly discouraged to directly call mutex_[un]lock(&pm_mutex) since | ||
192 | that could lead to freezing failures, because if the suspend/hibernate code | ||
193 | successfully acquired the 'pm_mutex' lock, and hence that other entity failed | ||
194 | to acquire the lock, then that task would get blocked in TASK_UNINTERRUPTIBLE | ||
195 | state. As a consequence, the freezer would not be able to freeze that task, | ||
196 | leading to freezing failure. | ||
197 | |||
198 | However, the [un]lock_system_sleep() APIs are safe to use in this scenario, | ||
199 | since 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 | ||
201 | only after the entire suspend/hibernation sequence is complete. | ||
202 | So, to summarize, use [un]lock_system_sleep() instead of directly using | ||
203 | mutex_[un]lock(&pm_mutex). That would prevent freezing failures. | ||