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