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