diff options
Diffstat (limited to 'Documentation/power')
-rw-r--r-- | Documentation/power/notifiers.txt | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/Documentation/power/notifiers.txt b/Documentation/power/notifiers.txt new file mode 100644 index 000000000000..9293e4bc857c --- /dev/null +++ b/Documentation/power/notifiers.txt | |||
@@ -0,0 +1,50 @@ | |||
1 | Suspend notifiers | ||
2 | (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL | ||
3 | |||
4 | There are some operations that device drivers may want to carry out in their | ||
5 | .suspend() routines, but shouldn't, because they can cause the hibernation or | ||
6 | suspend to fail. For example, a driver may want to allocate a substantial amount | ||
7 | of memory (like 50 MB) in .suspend(), but that shouldn't be done after the | ||
8 | swsusp's memory shrinker has run. | ||
9 | |||
10 | Also, there may be some operations, that subsystems want to carry out before a | ||
11 | hibernation/suspend or after a restore/resume, requiring the system to be fully | ||
12 | functional, so the drivers' .suspend() and .resume() routines are not suitable | ||
13 | for this purpose. For example, device drivers may want to upload firmware to | ||
14 | their devices after a restore from a hibernation image, but they cannot do it by | ||
15 | calling request_firmware() from their .resume() routines (user land processes | ||
16 | are frozen at this point). The solution may be to load the firmware into | ||
17 | memory before processes are frozen and upload it from there in the .resume() | ||
18 | routine. Of course, a hibernation notifier may be used for this purpose. | ||
19 | |||
20 | The subsystems that have such needs can register suspend notifiers that will be | ||
21 | called upon the following events by the suspend core: | ||
22 | |||
23 | PM_HIBERNATION_PREPARE The system is going to hibernate or suspend, tasks will | ||
24 | be frozen immediately. | ||
25 | |||
26 | PM_POST_HIBERNATION The system memory state has been restored from a | ||
27 | hibernation image or an error occured during the | ||
28 | hibernation. Device drivers' .resume() callbacks have | ||
29 | been executed and tasks have been thawed. | ||
30 | |||
31 | PM_SUSPEND_PREPARE The system is preparing for a suspend. | ||
32 | |||
33 | PM_POST_SUSPEND The system has just resumed or an error occured during | ||
34 | the suspend. Device drivers' .resume() callbacks have | ||
35 | been executed and tasks have been thawed. | ||
36 | |||
37 | It is generally assumed that whatever the notifiers do for | ||
38 | PM_HIBERNATION_PREPARE, should be undone for PM_POST_HIBERNATION. Analogously, | ||
39 | operations performed for PM_SUSPEND_PREPARE should be reversed for | ||
40 | PM_POST_SUSPEND. Additionally, all of the notifiers are called for | ||
41 | PM_POST_HIBERNATION if one of them fails for PM_HIBERNATION_PREPARE, and | ||
42 | all of the notifiers are called for PM_POST_SUSPEND if one of them fails for | ||
43 | PM_SUSPEND_PREPARE. | ||
44 | |||
45 | The hibernation and suspend notifiers are called with pm_mutex held. They are | ||
46 | defined in the usual way, but their last argument is meaningless (it is always | ||
47 | NULL). To register and/or unregister a suspend notifier use the functions | ||
48 | register_pm_notifier() and unregister_pm_notifier(), respectively, defined in | ||
49 | include/linux/suspend.h . If you don't need to unregister the notifier, you can | ||
50 | also use the pm_notifier() macro defined in include/linux/suspend.h . | ||