| Rafael J. Wysocki | b10d911 | 2007-07-19 01:47:36 -0700 | [diff] [blame] | 1 | Suspend notifiers |
| 2 | (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL |
| 3 | |
| 4 | There are some operations that device drivers may want to carry out in their |
| 5 | .suspend() routines, but shouldn't, because they can cause the hibernation or |
| 6 | suspend to fail. For example, a driver may want to allocate a substantial amount |
| 7 | of memory (like 50 MB) in .suspend(), but that shouldn't be done after the |
| 8 | swsusp's memory shrinker has run. |
| 9 | |
| 10 | Also, there may be some operations, that subsystems want to carry out before a |
| 11 | hibernation/suspend or after a restore/resume, requiring the system to be fully |
| 12 | functional, so the drivers' .suspend() and .resume() routines are not suitable |
| 13 | for this purpose. For example, device drivers may want to upload firmware to |
| 14 | their devices after a restore from a hibernation image, but they cannot do it by |
| 15 | calling request_firmware() from their .resume() routines (user land processes |
| 16 | are frozen at this point). The solution may be to load the firmware into |
| 17 | memory before processes are frozen and upload it from there in the .resume() |
| 18 | routine. Of course, a hibernation notifier may be used for this purpose. |
| 19 | |
| 20 | The subsystems that have such needs can register suspend notifiers that will be |
| 21 | called upon the following events by the suspend core: |
| 22 | |
| 23 | PM_HIBERNATION_PREPARE The system is going to hibernate or suspend, tasks will |
| 24 | be frozen immediately. |
| 25 | |
| 26 | PM_POST_HIBERNATION The system memory state has been restored from a |
| 27 | hibernation image or an error occured during the |
| 28 | hibernation. Device drivers' .resume() callbacks have |
| 29 | been executed and tasks have been thawed. |
| 30 | |
| Alan Stern | c3e94d8 | 2007-11-19 23:38:25 +0100 | [diff] [blame] | 31 | PM_RESTORE_PREPARE The system is going to restore a hibernation image. |
| 32 | If all goes well the restored kernel will issue a |
| 33 | PM_POST_HIBERNATION notification. |
| 34 | |
| 35 | PM_POST_RESTORE An error occurred during the hibernation restore. |
| 36 | Device drivers' .resume() callbacks have been executed |
| 37 | and tasks have been thawed. |
| 38 | |
| Rafael J. Wysocki | b10d911 | 2007-07-19 01:47:36 -0700 | [diff] [blame] | 39 | PM_SUSPEND_PREPARE The system is preparing for a suspend. |
| 40 | |
| 41 | PM_POST_SUSPEND The system has just resumed or an error occured during |
| 42 | the suspend. Device drivers' .resume() callbacks have |
| 43 | been executed and tasks have been thawed. |
| 44 | |
| 45 | It is generally assumed that whatever the notifiers do for |
| 46 | PM_HIBERNATION_PREPARE, should be undone for PM_POST_HIBERNATION. Analogously, |
| 47 | operations performed for PM_SUSPEND_PREPARE should be reversed for |
| 48 | PM_POST_SUSPEND. Additionally, all of the notifiers are called for |
| 49 | PM_POST_HIBERNATION if one of them fails for PM_HIBERNATION_PREPARE, and |
| 50 | all of the notifiers are called for PM_POST_SUSPEND if one of them fails for |
| 51 | PM_SUSPEND_PREPARE. |
| 52 | |
| 53 | The hibernation and suspend notifiers are called with pm_mutex held. They are |
| 54 | defined in the usual way, but their last argument is meaningless (it is always |
| 55 | NULL). To register and/or unregister a suspend notifier use the functions |
| 56 | register_pm_notifier() and unregister_pm_notifier(), respectively, defined in |
| 57 | include/linux/suspend.h . If you don't need to unregister the notifier, you can |
| 58 | also use the pm_notifier() macro defined in include/linux/suspend.h . |