| From 48b23f3e7721987e92b83b9b3be3a3c9746ea8db Mon Sep 17 00:00:00 2001 |
| From: "Srivatsa S. Bhat" <srivatsa.bhat@linux.vnet.ibm.com> |
| Date: Wed, 7 Dec 2011 22:30:09 +0100 |
| Subject: 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> |
| (cherry picked from commit cba3176e88fa134ece3ae1cf7e35dab9972d7853) |
| |
| Signed-off-by: Simon Horman <horms@verge.net.au> |
| --- |
| Documentation/power/freezing-of-tasks.txt | 25 +++++++++++++++++++++++++ |
| 1 file changed, 25 insertions(+) |
| |
| diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.txt |
| index 3ab9fbd..6ccb68f 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. |
| A driver must have all firmwares it may need in RAM before suspend() is called. |
| If keeping them is not practical, for example due to their size, they must be |
| requested early enough using the suspend notifier API described in notifiers.txt. |
| + |
| +VI. Are there any precautions to be taken to prevent freezing failures? |
| + |
| +Yes, there are. |
| + |
| +First of all, grabbing the 'pm_mutex' lock to mutually exclude a piece of code |
| +from system-wide sleep such as suspend/hibernation is not encouraged. |
| +If possible, that piece of code must instead hook onto the suspend/hibernation |
| +notifiers to achieve mutual exclusion. Look at the CPU-Hotplug code |
| +(kernel/cpu.c) for an example. |
| + |
| +However, if that is not feasible, and grabbing 'pm_mutex' is deemed necessary, |
| +it is strongly discouraged to directly call mutex_[un]lock(&pm_mutex) since |
| +that could lead to freezing failures, because if the suspend/hibernate code |
| +successfully acquired the 'pm_mutex' lock, and hence that other entity failed |
| +to acquire the lock, then that task would get blocked in TASK_UNINTERRUPTIBLE |
| +state. As a consequence, the freezer would not be able to freeze that task, |
| +leading to freezing failure. |
| + |
| +However, the [un]lock_system_sleep() APIs are safe to use in this scenario, |
| +since they ask the freezer to skip freezing this task, since it is anyway |
| +"frozen enough" as it is blocked on 'pm_mutex', which will be released |
| +only after the entire suspend/hibernation sequence is complete. |
| +So, to summarize, use [un]lock_system_sleep() instead of directly using |
| +mutex_[un]lock(&pm_mutex). That would prevent freezing failures. |
| -- |
| 1.7.10.1.362.g242cab3 |
| |