Commit | Line | Data |
---|---|---|
fc7db767 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
fc1860d6 | 2 | .. include:: <isonum.txt> |
fc7db767 | 3 | |
730c4c05 RW |
4 | ============================= |
5 | Suspend/Hibernation Notifiers | |
6 | ============================= | |
7 | ||
fc1860d6 RW |
8 | :Copyright: |copy| 2016 Intel Corporation |
9 | ||
10 | :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> | |
730c4c05 | 11 | |
730c4c05 RW |
12 | |
13 | There are some operations that subsystems or drivers may want to carry out | |
14 | before hibernation/suspend or after restore/resume, but they require the system | |
15 | to be fully functional, so the drivers' and subsystems' ``->suspend()`` and | |
16 | ``->resume()`` or even ``->prepare()`` and ``->complete()`` callbacks are not | |
17 | suitable for this purpose. | |
18 | ||
19 | For example, device drivers may want to upload firmware to their devices after | |
20 | resume/restore, but they cannot do it by calling :c:func:`request_firmware()` | |
21 | from their ``->resume()`` or ``->complete()`` callback routines (user land | |
22 | processes are frozen at these points). The solution may be to load the firmware | |
23 | into memory before processes are frozen and upload it from there in the | |
24 | ``->resume()`` routine. A suspend/hibernation notifier may be used for that. | |
25 | ||
26 | Subsystems or drivers having such needs can register suspend notifiers that | |
27 | will be called upon the following events by the PM core: | |
28 | ||
29 | ``PM_HIBERNATION_PREPARE`` | |
30 | The system is going to hibernate, tasks will be frozen immediately. This | |
31 | is different from ``PM_SUSPEND_PREPARE`` below, because in this case | |
32 | additional work is done between the notifiers and the invocation of PM | |
33 | callbacks for the "freeze" transition. | |
34 | ||
35 | ``PM_POST_HIBERNATION`` | |
36 | The system memory state has been restored from a hibernation image or an | |
37 | error occurred during hibernation. Device restore callbacks have been | |
38 | executed and tasks have been thawed. | |
39 | ||
40 | ``PM_RESTORE_PREPARE`` | |
41 | The system is going to restore a hibernation image. If all goes well, | |
42 | the restored image kernel will issue a ``PM_POST_HIBERNATION`` | |
43 | notification. | |
44 | ||
45 | ``PM_POST_RESTORE`` | |
46 | An error occurred during restore from hibernation. Device restore | |
47 | callbacks have been executed and tasks have been thawed. | |
48 | ||
49 | ``PM_SUSPEND_PREPARE`` | |
50 | The system is preparing for suspend. | |
51 | ||
52 | ``PM_POST_SUSPEND`` | |
53 | The system has just resumed or an error occurred during suspend. Device | |
54 | resume callbacks have been executed and tasks have been thawed. | |
55 | ||
56 | It is generally assumed that whatever the notifiers do for | |
57 | ``PM_HIBERNATION_PREPARE``, should be undone for ``PM_POST_HIBERNATION``. | |
58 | Analogously, operations carried out for ``PM_SUSPEND_PREPARE`` should be | |
59 | reversed for ``PM_POST_SUSPEND``. | |
60 | ||
61 | Moreover, if one of the notifiers fails for the ``PM_HIBERNATION_PREPARE`` or | |
62 | ``PM_SUSPEND_PREPARE`` event, the notifiers that have already succeeded for that | |
63 | event will be called for ``PM_POST_HIBERNATION`` or ``PM_POST_SUSPEND``, | |
64 | respectively. | |
65 | ||
66 | The hibernation and suspend notifiers are called with :c:data:`pm_mutex` held. | |
67 | They are defined in the usual way, but their last argument is meaningless (it is | |
68 | always NULL). | |
69 | ||
70 | To register and/or unregister a suspend notifier use | |
71 | :c:func:`register_pm_notifier()` and :c:func:`unregister_pm_notifier()`, | |
72 | respectively (both defined in :file:`include/linux/suspend.h`). If you don't | |
73 | need to unregister the notifier, you can also use the :c:func:`pm_notifier()` | |
74 | macro defined in :file:`include/linux/suspend.h`. |