Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) .. include:: <isonum.txt>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) Suspend/Hibernation Notifiers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) :Copyright: |copy| 2016 Intel Corporation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) There are some operations that subsystems or drivers may want to carry out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) before hibernation/suspend or after restore/resume, but they require the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) to be fully functional, so the drivers' and subsystems' ``->suspend()`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ``->resume()`` or even ``->prepare()`` and ``->complete()`` callbacks are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) suitable for this purpose.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) For example, device drivers may want to upload firmware to their devices after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) resume/restore, but they cannot do it by calling :c:func:`request_firmware()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) from their ``->resume()`` or ``->complete()`` callback routines (user land
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) processes are frozen at these points).  The solution may be to load the firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) into memory before processes are frozen and upload it from there in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ``->resume()`` routine.  A suspend/hibernation notifier may be used for that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Subsystems or drivers having such needs can register suspend notifiers that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) will be called upon the following events by the PM core:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) ``PM_HIBERNATION_PREPARE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) 	The system is going to hibernate, tasks will be frozen immediately. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) 	is different from ``PM_SUSPEND_PREPARE`` below,	because in this case
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) 	additional work is done between the notifiers and the invocation of PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) 	callbacks for the "freeze" transition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) ``PM_POST_HIBERNATION``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) 	The system memory state has been restored from a hibernation image or an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 	error occurred during hibernation.  Device restore callbacks have been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) 	executed and tasks have been thawed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) ``PM_RESTORE_PREPARE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) 	The system is going to restore a hibernation image.  If all goes well,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) 	the restored image kernel will issue a ``PM_POST_HIBERNATION``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) 	notification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) ``PM_POST_RESTORE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) 	An error occurred during restore from hibernation.  Device restore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) 	callbacks have been executed and tasks have been thawed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) ``PM_SUSPEND_PREPARE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 	The system is preparing for suspend.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) ``PM_POST_SUSPEND``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 	The system has just resumed or an error occurred during suspend.  Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) 	resume callbacks have been executed and tasks have been thawed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) It is generally assumed that whatever the notifiers do for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) ``PM_HIBERNATION_PREPARE``, should be undone for ``PM_POST_HIBERNATION``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Analogously, operations carried out for ``PM_SUSPEND_PREPARE`` should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) reversed for ``PM_POST_SUSPEND``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Moreover, if one of the notifiers fails for the ``PM_HIBERNATION_PREPARE`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) ``PM_SUSPEND_PREPARE`` event, the notifiers that have already succeeded for that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) event will be called for ``PM_POST_HIBERNATION`` or ``PM_POST_SUSPEND``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) The hibernation and suspend notifiers are called with :c:data:`pm_mutex` held.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) They are defined in the usual way, but their last argument is meaningless (it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) always NULL).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) To register and/or unregister a suspend notifier use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) :c:func:`register_pm_notifier()` and :c:func:`unregister_pm_notifier()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) respectively (both defined in :file:`include/linux/suspend.h`).  If you don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) need to unregister the notifier, you can also use the :c:func:`pm_notifier()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) macro defined in :file:`include/linux/suspend.h`.