actions that either require user space to be available, or at least won't
interfere with user space.
-For details refer to :file:`Documentation/power/notifiers.txt`.
+For details refer to :doc:`notifiers`.
Device Low-Power (suspend) States
.. toctree::
devices
+ notifiers
types
.. only:: subproject and html
--- /dev/null
+=============================
+Suspend/Hibernation Notifiers
+=============================
+
+::
+
+ Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+
+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 :c:func:`request_firmware()`
+from their ``->resume()`` or ``->complete()`` callback 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 that.
+
+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 in this case
+ additional work is done between the notifiers and the invocation of PM
+ callbacks for the "freeze" transition.
+
+``PM_POST_HIBERNATION``
+ The system memory state has been restored from a hibernation image or an
+ error occurred during hibernation. Device 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 image kernel will issue a ``PM_POST_HIBERNATION``
+ notification.
+
+``PM_POST_RESTORE``
+ An error occurred during restore from hibernation. Device 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
+ 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 carried out for ``PM_SUSPEND_PREPARE`` should be
+reversed for ``PM_POST_SUSPEND``.
+
+Moreover, if one of the notifiers fails for the ``PM_HIBERNATION_PREPARE`` or
+``PM_SUSPEND_PREPARE`` event, the notifiers that have already succeeded for that
+event will be called for ``PM_POST_HIBERNATION`` or ``PM_POST_SUSPEND``,
+respectively.
+
+The hibernation and suspend notifiers are called with :c:data:`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
+:c:func:`register_pm_notifier()` and :c:func:`unregister_pm_notifier()`,
+respectively (both defined in :file:`include/linux/suspend.h`). If you don't
+need to unregister the notifier, you can also use the :c:func:`pm_notifier()`
+macro defined in :file:`include/linux/suspend.h`.
- How processes and controlled during suspend
interface.txt
- Power management user interface in /sys/power
-notifiers.txt
- - Registering suspend notifiers in device drivers
opp.txt
- Operating Performance Point library
pci.txt
A driver must have all firmwares it may need in RAM before suspend() is called.
If keeping them is not practical, for example due to their size, they must be
-requested early enough using the suspend notifier API described in notifiers.txt.
+requested early enough using the suspend notifier API described in
+Documentation/driver-api/pm/notifiers.rst.
VI. Are there any precautions to be taken to prevent freezing failures?
+++ /dev/null
-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 .
preparing the device to be suspended, although it should not allocate memory
(if additional memory is required to suspend the device, it has to be
preallocated earlier, for example in a suspend/hibernate notifier as described
-in Documentation/power/notifiers.txt).
+in Documentation/driver-api/pm/notifiers.rst).
3.1.2. suspend()
git.samba.org / sfrench / cifs-2.6.git / commitdiff