Commit 271ff96d authored by Sakari Ailus's avatar Sakari Ailus Committed by Rafael J. Wysocki
Browse files

PM: runtime: Document return values of suspend-related API functions 



Document return values for device suspend and idle related API
functions.

Signed-off-by: default avatarSakari Ailus <sakari.ailus@linux.intel.com>
Link: https://patch.msgid.link/20250616061212.2286741-2-sakari.ailus@linux.intel.com


Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
parent e04c78d8

include/linux/pm_runtime.h

+138 −9
Original line number Diff line number Diff line
@@ -337,6 +337,20 @@ static inline void pm_runtime_release_supplier(struct device_link *link) {} 
 * Invoke the "idle check" callback of @dev and, depending on its return value,

 * set up autosuspend of @dev or suspend it (depending on whether or not

 * autosuspend has been enabled for it).

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero, Runtime PM status change ongoing

 *            or device not in %RPM_ACTIVE state.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -EINPROGRESS: Suspend already in progress.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 * Other values and conditions for the above values are possible as returned by

 * Runtime PM idle and suspend callbacks.

 */

static inline int pm_runtime_idle(struct device *dev)

{
@@ -346,6 +360,18 @@ static inline int pm_runtime_idle(struct device *dev) 
/**

 * pm_runtime_suspend - Suspend a device synchronously.

 * @dev: Target device.

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 * Other values and conditions for the above values are possible as returned by

 * Runtime PM suspend callbacks.

 */

static inline int pm_runtime_suspend(struct device *dev)

{
@@ -358,6 +384,18 @@ static inline int pm_runtime_suspend(struct device *dev) 
 *

 * Set up autosuspend of @dev or suspend it (depending on whether or not

 * autosuspend is enabled for it) without engaging its "idle check" callback.

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 * Other values and conditions for the above values are possible as returned by

 * Runtime PM suspend callbacks.

 */

static inline int pm_runtime_autosuspend(struct device *dev)

{
@@ -379,6 +417,18 @@ static inline int pm_runtime_resume(struct device *dev) 
 *

 * Queue up a work item to run an equivalent of pm_runtime_idle() for @dev

 * asynchronously.

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero, Runtime PM status change ongoing

 *            or device not in %RPM_ACTIVE state.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -EINPROGRESS: Suspend already in progress.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 */

static inline int pm_request_idle(struct device *dev)

{
@@ -400,6 +450,17 @@ static inline int pm_request_resume(struct device *dev) 
 *

 * Queue up a work item to run an equivalent pm_runtime_autosuspend() for @dev

 * asynchronously.

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -EINPROGRESS: Suspend already in progress.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 */

static inline int pm_request_autosuspend(struct device *dev)

{
@@ -464,6 +525,17 @@ static inline int pm_runtime_resume_and_get(struct device *dev) 
 *

 * Decrement the runtime PM usage counter of @dev and if it turns out to be

 * equal to 0, queue up a work item for @dev like in pm_request_idle().

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -EINPROGRESS: Suspend already in progress.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 */

static inline int pm_runtime_put(struct device *dev)

{
@@ -478,6 +550,17 @@ DEFINE_FREE(pm_runtime_put, struct device *, if (_T) pm_runtime_put(_T)) 
 *

 * Decrement the runtime PM usage counter of @dev and if it turns out to be

 * equal to 0, queue up a work item for @dev like in pm_request_autosuspend().

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -EINPROGRESS: Suspend already in progress.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 */

static inline int __pm_runtime_put_autosuspend(struct device *dev)

{
@@ -490,6 +573,17 @@ static inline int __pm_runtime_put_autosuspend(struct device *dev) 
 *

 * Decrement the runtime PM usage counter of @dev and if it turns out to be

 * equal to 0, queue up a work item for @dev like in pm_request_autosuspend().

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -EINPROGRESS: Suspend already in progress.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 */

static inline int pm_runtime_put_autosuspend(struct device *dev)

{
@@ -506,9 +600,20 @@ static inline int pm_runtime_put_autosuspend(struct device *dev) 
 * return value, set up autosuspend of @dev or suspend it (depending on whether

 * or not autosuspend has been enabled for it).

 *

 * The possible return values of this function are the same as for

 * pm_runtime_idle() and the runtime PM usage counter of @dev remains

 * decremented in all cases, even if it returns an error code.

 * The runtime PM usage counter of @dev remains decremented in all cases, even

 * if it returns an error code.

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 * Other values and conditions for the above values are possible as returned by

 * Runtime PM suspend callbacks.

 */

static inline int pm_runtime_put_sync(struct device *dev)

{
@@ -522,9 +627,21 @@ static inline int pm_runtime_put_sync(struct device *dev) 
 * Decrement the runtime PM usage counter of @dev and if it turns out to be

 * equal to 0, carry out runtime-suspend of @dev synchronously.

 *

 * The possible return values of this function are the same as for

 * pm_runtime_suspend() and the runtime PM usage counter of @dev remains

 * decremented in all cases, even if it returns an error code.

 * The runtime PM usage counter of @dev remains decremented in all cases, even

 * if it returns an error code.

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EAGAIN: usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 * Other values and conditions for the above values are possible as returned by

 * Runtime PM suspend callbacks.

 */

static inline int pm_runtime_put_sync_suspend(struct device *dev)

{
@@ -539,9 +656,21 @@ static inline int pm_runtime_put_sync_suspend(struct device *dev) 
 * equal to 0, set up autosuspend of @dev or suspend it synchronously (depending

 * on whether or not autosuspend has been enabled for it).

 *

 * The possible return values of this function are the same as for

 * pm_runtime_autosuspend() and the runtime PM usage counter of @dev remains

 * decremented in all cases, even if it returns an error code.

 * The runtime PM usage counter of @dev remains decremented in all cases, even

 * if it returns an error code.

 *

 * Return:

 * * 0: Success.

 * * -EINVAL: Runtime PM error.

 * * -EACCES: Runtime PM disabled.

 * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.

 * * -EBUSY: Runtime PM child_count non-zero.

 * * -EPERM: Device PM QoS resume latency 0.

 * * -EINPROGRESS: Suspend already in progress.

 * * -ENOSYS: CONFIG_PM not enabled.

 * * 1: Device already suspended.

 * Other values and conditions for the above values are possible as returned by

 * Runtime PM suspend callbacks.

 */

static inline int pm_runtime_put_sync_autosuspend(struct device *dev)

{