PM: Document rules on using pm_runtime_resume() in system suspend callbacks
authorRafael J. Wysocki <rafael.j.wysocki@intel.com>
Wed, 20 Sep 2017 00:26:00 +0000 (02:26 +0200)
committerRafael J. Wysocki <rafael.j.wysocki@intel.com>
Sat, 23 Sep 2017 13:00:57 +0000 (15:00 +0200)
commit104dc5e20ff52748a16f756ae946391bdc6a4d0a
treed03a2b3200e0138f362c27b637f6cf3de5bdf932
parent2bd6bf03f4c1c59381d62c61d03f6cc3fe71f66e
PM: Document rules on using pm_runtime_resume() in system suspend callbacks

It quite often is necessary to resume devices from runtime suspend
during system suspend for various reasons (for example, if their
wakeup settings need to be changed), but that requires middle-layer
or subsystem code to follow additional rules which currently are not
clearly documented.

Namely, if a driver calls pm_runtime_resume() for the device from
its ->suspend (or equivalent) system sleep callback, that may not
work if the middle layer above it has updated the state of the
device from its ->prepare or ->suspend callbacks already in an
incompatible way.  For this reason, all middle layers must follow
the rule that, until the ->suspend callback provided by the device's
driver is invoked, the only way in which the device's state can be
updated is by calling pm_runtime_resume() for it, if necessary.
Fortunately enough, all middle layers in the code base today follow
this rule, but it is not explicitly stated anywhere, so do that.

Note that calling pm_runtime_resume() from the ->suspend callback
of a driver will cause the ->runtime_resume callback provided by the
middle layer to be invoked, but the rule above guarantees that this
callback will nest properly with the middle layer's ->suspend
callback and it will play well with the ->prepare one invoked before.

Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Reviewed-by: Ulf Hansson <ulf.hansson@linaro.org>
Documentation/driver-api/pm/devices.rst