Suspend/Hibernation Notifiers¶

Copyright:

© 2016 Intel Corporation

Author:

Rafael J. Wysocki <rafael.j.wysocki@intel.com>

There are some operations that subsystems or drivers may want to carry outbefore hibernation/suspend or after restore/resume, but they require the systemto be fully functional, so the drivers’ and subsystems’->suspend() and->resume() or even->prepare() and->complete() callbacks are notsuitable for this purpose.

For example, device drivers may want to upload firmware to their devices afterresume/restore, but they cannot do it by callingrequest_firmware()from their->resume() or->complete() callback routines (user landprocesses are frozen at these points). The solution may be to load the firmwareinto memory before processes are frozen and upload it from there in the->resume() routine. A suspend/hibernation notifier may be used for that.

Subsystems or drivers having such needs can register suspend notifiers thatwill be called upon the following events by the PM core:

PM_HIBERNATION_PREPARE

The system is going to hibernate, tasks will be frozen immediately. Thisis different fromPM_SUSPEND_PREPARE below, because in this caseadditional work is done between the notifiers and the invocation of PMcallbacks for the “freeze” transition.

PM_POST_HIBERNATION

The system memory state has been restored from a hibernation image or anerror occurred during hibernation. Device restore callbacks have beenexecuted and tasks have been thawed.

PM_RESTORE_PREPARE

The system is going to restore a hibernation image. If all goes well,the restored image kernel will issue aPM_POST_HIBERNATIONnotification.

PM_POST_RESTORE

An error occurred during restore from hibernation. Device restorecallbacks have been executed and tasks have been thawed.

PM_SUSPEND_PREPARE

The system is preparing for suspend.

PM_POST_SUSPEND

The system has just resumed or an error occurred during suspend. Deviceresume callbacks have been executed and tasks have been thawed.

It is generally assumed that whatever the notifiers do forPM_HIBERNATION_PREPARE, should be undone forPM_POST_HIBERNATION.Analogously, operations carried out forPM_SUSPEND_PREPARE should bereversed forPM_POST_SUSPEND.

Moreover, if one of the notifiers fails for thePM_HIBERNATION_PREPARE orPM_SUSPEND_PREPARE event, the notifiers that have already succeeded for thatevent will be called forPM_POST_HIBERNATION orPM_POST_SUSPEND,respectively.

The hibernation and suspend notifiers are called withpm_mutex held.They are defined in the usual way, but their last argument is meaningless (it isalways NULL).

To register and/or unregister a suspend notifier useregister_pm_notifier() andunregister_pm_notifier(),respectively (both defined ininclude/linux/suspend.h). If you don’tneed to unregister the notifier, you can also use thepm_notifier()macro defined ininclude/linux/suspend.h.