Commit 730c4c05 authored by Rafael J. Wysocki's avatar Rafael J. Wysocki Committed by Jonathan Corbet
Browse files

PM / sleep / docs: Convert PM notifiers document to reST 



Move the document describing PM notifiers (used during system sleep
state transitions) to Documentation/driver-api/pm/, convert it to reST
and update it to use current terminology.  Also replace the remaining
references to the old version of it in .txt documents with references
to the new one.

Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 2728b2d2

Documentation/driver-api/pm/devices.rst

+1 −1
Original line number Diff line number Diff line
@@ -620,7 +620,7 @@ been thawed. Generally speaking, the PM notifiers are suitable for performing 
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

Documentation/driver-api/pm/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -5,6 +5,7 @@ Device Power Management 
.. toctree::



   devices

   notifiers

   types



.. only::  subproject and html

Documentation/driver-api/pm/notifiers.rst

0 → 100644
+70 −0
Original line number Diff line number Diff line 
=============================

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`.

Documentation/power/00-INDEX

+0 −2
Original line number Diff line number Diff line
@@ -14,8 +14,6 @@ freezing-of-tasks.txt 
	- 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

Documentation/power/freezing-of-tasks.txt

+2 −1
Original line number Diff line number Diff line
@@ -197,7 +197,8 @@ tasks, since it generally exists anyway. 


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?

CRA Git | Maintained and supported by SUSTech CRA and CCSE