Commit cea54f8e authored by Rafael J. Wysocki's avatar Rafael J. Wysocki
Browse files

PM: runtime: docs: Update pm_runtime_allow/forbid() documentation 

Drop confusing descriptions of pm_runtime_allow() and pm_runtime_forbid()
from Documentation/power/runtime_pm.rst and update the kerneldoc comments
of these functions to better explain their purpose.

Link: https://lore.kernel.org/linux-pm/08976178-298f-79d9-1d63-cff5a4e56cc3@linux.intel.com/


Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
Reviewed-by: default avatarBrian Norris <briannorris@chromium.org>
Reviewed-by: default avatarUlf Hansson <ulf.hansson@linaro.org>
Reviewed-by: default avatarIlpo Järvinen <ilpo.jarvinen@linux.intel.com>
Link: https://patch.msgid.link/12780841.O9o76ZdvQC@rafael.j.wysocki
parent db82b8db

Documentation/power/runtime_pm.rst

+0 −10
Original line number Diff line number Diff line
@@ -480,16 +480,6 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: 
  `bool pm_runtime_status_suspended(struct device *dev);`

    - return true if the device's runtime PM status is 'suspended'



  `void pm_runtime_allow(struct device *dev);`

    - set the power.runtime_auto flag for the device and decrease its usage

      counter (used by the /sys/devices/.../power/control interface to

      effectively allow the device to be power managed at run time)



  `void pm_runtime_forbid(struct device *dev);`

    - unset the power.runtime_auto flag for the device and increase its usage

      counter (used by the /sys/devices/.../power/control interface to

      effectively prevent the device from being power managed at run time)



  `void pm_runtime_no_callbacks(struct device *dev);`

    - set the power.no_callbacks flag for the device and remove the runtime

      PM attributes from /sys/devices/.../power (or prevent them from being

drivers/base/power/runtime.c

+13 −4
Original line number Diff line number Diff line
@@ -1664,9 +1664,12 @@ EXPORT_SYMBOL_GPL(devm_pm_runtime_get_noresume); 
 * pm_runtime_forbid - Block runtime PM of a device.

 * @dev: Device to handle.

 *

 * Increase the device's usage count and clear its power.runtime_auto flag,

 * so that it cannot be suspended at run time until pm_runtime_allow() is called

 * for it.

 * Resume @dev if already suspended and block runtime suspend of @dev in such

 * a way that it can be unblocked via the /sys/devices/.../power/control

 * interface, or otherwise by calling pm_runtime_allow().

 *

 * Calling this function many times in a row has the same effect as calling it

 * once.

 */

void pm_runtime_forbid(struct device *dev)

{
@@ -1687,7 +1690,13 @@ EXPORT_SYMBOL_GPL(pm_runtime_forbid); 
 * pm_runtime_allow - Unblock runtime PM of a device.

 * @dev: Device to handle.

 *

 * Decrease the device's usage count and set its power.runtime_auto flag.

 * Unblock runtime suspend of @dev after it has been blocked by

 * pm_runtime_forbid() (for instance, if it has been blocked via the

 * /sys/devices/.../power/control interface), check if @dev can be

 * suspended and suspend it in that case.

 *

 * Calling this function many times in a row has the same effect as calling it

 * once.

 */

void pm_runtime_allow(struct device *dev)

{