162306a36Sopenharmony_ci.. SPDX-License-Identifier: GPL-2.0 262306a36Sopenharmony_ci.. include:: <isonum.txt> 362306a36Sopenharmony_ci 462306a36Sopenharmony_ci============================= 562306a36Sopenharmony_ciSuspend/Hibernation Notifiers 662306a36Sopenharmony_ci============================= 762306a36Sopenharmony_ci 862306a36Sopenharmony_ci:Copyright: |copy| 2016 Intel Corporation 962306a36Sopenharmony_ci 1062306a36Sopenharmony_ci:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> 1162306a36Sopenharmony_ci 1262306a36Sopenharmony_ci 1362306a36Sopenharmony_ciThere are some operations that subsystems or drivers may want to carry out 1462306a36Sopenharmony_cibefore hibernation/suspend or after restore/resume, but they require the system 1562306a36Sopenharmony_cito be fully functional, so the drivers' and subsystems' ``->suspend()`` and 1662306a36Sopenharmony_ci``->resume()`` or even ``->prepare()`` and ``->complete()`` callbacks are not 1762306a36Sopenharmony_cisuitable for this purpose. 1862306a36Sopenharmony_ci 1962306a36Sopenharmony_ciFor example, device drivers may want to upload firmware to their devices after 2062306a36Sopenharmony_ciresume/restore, but they cannot do it by calling :c:func:`request_firmware()` 2162306a36Sopenharmony_cifrom their ``->resume()`` or ``->complete()`` callback routines (user land 2262306a36Sopenharmony_ciprocesses are frozen at these points). The solution may be to load the firmware 2362306a36Sopenharmony_ciinto memory before processes are frozen and upload it from there in the 2462306a36Sopenharmony_ci``->resume()`` routine. A suspend/hibernation notifier may be used for that. 2562306a36Sopenharmony_ci 2662306a36Sopenharmony_ciSubsystems or drivers having such needs can register suspend notifiers that 2762306a36Sopenharmony_ciwill be called upon the following events by the PM core: 2862306a36Sopenharmony_ci 2962306a36Sopenharmony_ci``PM_HIBERNATION_PREPARE`` 3062306a36Sopenharmony_ci The system is going to hibernate, tasks will be frozen immediately. This 3162306a36Sopenharmony_ci is different from ``PM_SUSPEND_PREPARE`` below, because in this case 3262306a36Sopenharmony_ci additional work is done between the notifiers and the invocation of PM 3362306a36Sopenharmony_ci callbacks for the "freeze" transition. 3462306a36Sopenharmony_ci 3562306a36Sopenharmony_ci``PM_POST_HIBERNATION`` 3662306a36Sopenharmony_ci The system memory state has been restored from a hibernation image or an 3762306a36Sopenharmony_ci error occurred during hibernation. Device restore callbacks have been 3862306a36Sopenharmony_ci executed and tasks have been thawed. 3962306a36Sopenharmony_ci 4062306a36Sopenharmony_ci``PM_RESTORE_PREPARE`` 4162306a36Sopenharmony_ci The system is going to restore a hibernation image. If all goes well, 4262306a36Sopenharmony_ci the restored image kernel will issue a ``PM_POST_HIBERNATION`` 4362306a36Sopenharmony_ci notification. 4462306a36Sopenharmony_ci 4562306a36Sopenharmony_ci``PM_POST_RESTORE`` 4662306a36Sopenharmony_ci An error occurred during restore from hibernation. Device restore 4762306a36Sopenharmony_ci callbacks have been executed and tasks have been thawed. 4862306a36Sopenharmony_ci 4962306a36Sopenharmony_ci``PM_SUSPEND_PREPARE`` 5062306a36Sopenharmony_ci The system is preparing for suspend. 5162306a36Sopenharmony_ci 5262306a36Sopenharmony_ci``PM_POST_SUSPEND`` 5362306a36Sopenharmony_ci The system has just resumed or an error occurred during suspend. Device 5462306a36Sopenharmony_ci resume callbacks have been executed and tasks have been thawed. 5562306a36Sopenharmony_ci 5662306a36Sopenharmony_ciIt is generally assumed that whatever the notifiers do for 5762306a36Sopenharmony_ci``PM_HIBERNATION_PREPARE``, should be undone for ``PM_POST_HIBERNATION``. 5862306a36Sopenharmony_ciAnalogously, operations carried out for ``PM_SUSPEND_PREPARE`` should be 5962306a36Sopenharmony_cireversed for ``PM_POST_SUSPEND``. 6062306a36Sopenharmony_ci 6162306a36Sopenharmony_ciMoreover, if one of the notifiers fails for the ``PM_HIBERNATION_PREPARE`` or 6262306a36Sopenharmony_ci``PM_SUSPEND_PREPARE`` event, the notifiers that have already succeeded for that 6362306a36Sopenharmony_cievent will be called for ``PM_POST_HIBERNATION`` or ``PM_POST_SUSPEND``, 6462306a36Sopenharmony_cirespectively. 6562306a36Sopenharmony_ci 6662306a36Sopenharmony_ciThe hibernation and suspend notifiers are called with :c:data:`pm_mutex` held. 6762306a36Sopenharmony_ciThey are defined in the usual way, but their last argument is meaningless (it is 6862306a36Sopenharmony_cialways NULL). 6962306a36Sopenharmony_ci 7062306a36Sopenharmony_ciTo register and/or unregister a suspend notifier use 7162306a36Sopenharmony_ci:c:func:`register_pm_notifier()` and :c:func:`unregister_pm_notifier()`, 7262306a36Sopenharmony_cirespectively (both defined in :file:`include/linux/suspend.h`). If you don't 7362306a36Sopenharmony_cineed to unregister the notifier, you can also use the :c:func:`pm_notifier()` 7462306a36Sopenharmony_cimacro defined in :file:`include/linux/suspend.h`. 75