| Suspend notifiers |
| (C) 2007-2011 Rafael J. Wysocki <rjw@sisk.pl>, 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 |
| PM_SUSPEND_PREPARE. |
| |
| 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 . |