| 1 | |
| 2 | .. include:: <isonum.txt>
|
| 3 |
|
| 4 | =============================
|
| 5 | Suspend/Hibernation Notifiers
|
| 6 | =============================
|
| 7 |
|
| 8 | :Copyright: |copy| 2016 Intel Corporation
|
| 9 |
|
| 10 | :Author: Rafael J. Wysocki <[email protected]>
|
| 11 |
|
| 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`.
|