| (C) 2007-2011 Rafael J. Wysocki <email@example.com>, GPL
|There are some operations that subsystems or drivers may want to carry out
|before hibernation/suspend or after restore/resume, but they require the system
|to be fully functional, so the drivers' and subsystems' .suspend() and .resume()
|or even .prepare() and .complete() callbacks are not suitable for this purpose.
|For example, device drivers may want to upload firmware to their devices after
|resume/restore, but they cannot do it by calling request_firmware() from their
|.resume() or .complete() routines (user land processes are frozen at these
|points). The solution may be to load the firmware into memory before processes
|are frozen and upload it from there in the .resume() routine.
|A suspend/hibernation notifier may be used for this purpose.
|The subsystems or drivers having such needs can register suspend notifiers that
|will be called upon the following events by the PM core:
|PM_HIBERNATION_PREPARE The system is going to hibernate, tasks will be frozen
| immediately. This is different from PM_SUSPEND_PREPARE
| below because here we do additional work between notifiers
| and drivers freezing.
|PM_POST_HIBERNATION The system memory state has been restored from a
| hibernation image or an error occurred during
| hibernation. Device drivers' restore callbacks have
| been executed and tasks have been thawed.
|PM_RESTORE_PREPARE The system is going to restore a hibernation image.
| If all goes well, the restored kernel will issue a
| PM_POST_HIBERNATION notification.
|PM_POST_RESTORE An error occurred during restore from hibernation.
| Device drivers' restore callbacks 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. Device drivers' resume callbacks have been
| executed and tasks have been thawed.
|It is generally assumed that whatever the notifiers do for
|PM_HIBERNATION_PREPARE, should be undone for PM_POST_HIBERNATION. Analogously,
|operations performed for PM_SUSPEND_PREPARE should be reversed for
|PM_POST_SUSPEND. Additionally, all of the notifiers are called for
|PM_POST_HIBERNATION if one of them fails for PM_HIBERNATION_PREPARE, and
|all of the notifiers are called for PM_POST_SUSPEND if one of them fails for
|The hibernation and suspend notifiers are called with pm_mutex held. They are
|defined in the usual way, but their last argument is meaningless (it is always
|NULL). To register and/or unregister a suspend notifier use the functions
|register_pm_notifier() and unregister_pm_notifier(), respectively, defined in
|include/linux/suspend.h . If you don't need to unregister the notifier, you can
|also use the pm_notifier() macro defined in include/linux/suspend.h .