mirror of
https://github.com/torvalds/linux.git
synced 2026-05-27 08:33:17 +02:00
PM: runtime: Update kerneldoc return codes
APIs based on __pm_runtime_idle() (pm_runtime_idle(), pm_request_idle())
do not return 1 when already suspended. They return -EAGAIN. This is
already covered in the docs, so the entry for "1" is redundant and
conflicting.
(pm_runtime_put() and pm_runtime_put_sync() were previously incorrect,
but that's fixed in "PM: runtime: pm_runtime_put{,_sync}() returns 1
when already suspended", to ensure consistency with APIs like
pm_runtime_put_autosuspend().)
RPM_GET_PUT APIs based on __pm_runtime_suspend() do return 1 when
already suspended, but the language is a little unclear -- it's not
really an "error", so it seems better to list as a clarification before
the 0/success case. Additionally, they only actually return 1 when the
refcount makes it to 0; if the usage counter is still non-zero, we
return 0.
pm_runtime_put(), etc., also don't appear at first like they can ever
see "-EAGAIN: Runtime PM usage_count non-zero", because in non-racy
conditions, pm_runtime_put() would drop its reference count, see it's
non-zero, and return early (in __pm_runtime_idle()). However, it's
possible to race with another actor that increments the usage_count
afterward, since rpm_idle() is protected by a separate lock; in such a
case, we may see -EAGAIN.
Because this case is only seen in the presence of concurrent actors, it
makes sense to clarify that this is when "usage_count **became**
non-zero", by way of some racing actor.
Lastly, pm_runtime_put_sync_suspend() duplicated some -EAGAIN language.
Fix that.
Fixes: 271ff96d60 ("PM: runtime: Document return values of suspend-related API functions")
Link: https://lore.kernel.org/linux-pm/aJ5pkEJuixTaybV4@google.com/
Signed-off-by: Brian Norris <briannorris@chromium.org>
Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Cc: 6.17+ <stable@vger.kernel.org> # 6.17+
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
This commit is contained in:
Brian Norris
Rafael J. Wysocki
parent
d0b8651a02
commit
fed7eaa4f0
|
|
@ -350,13 +350,12 @@ static inline int pm_runtime_force_resume(struct device *dev) { return -ENXIO; }
|
|||
* * 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.
|
||||
* * -EAGAIN: Runtime PM usage counter 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.
|
||||
*/
|
||||
|
|
@ -370,14 +369,15 @@ static inline int pm_runtime_idle(struct device *dev)
|
|||
* @dev: Target device.
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success; device was already suspended.
|
||||
* * 0: Success.
|
||||
* * -EINVAL: Runtime PM error.
|
||||
* * -EACCES: Runtime PM disabled.
|
||||
* * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
|
||||
* * -EAGAIN: Runtime PM usage counter 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.
|
||||
*/
|
||||
|
|
@ -396,14 +396,15 @@ static inline int pm_runtime_suspend(struct device *dev)
|
|||
* engaging its "idle check" callback.
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success; device was already suspended.
|
||||
* * 0: Success.
|
||||
* * -EINVAL: Runtime PM error.
|
||||
* * -EACCES: Runtime PM disabled.
|
||||
* * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
|
||||
* * -EAGAIN: Runtime PM usage counter 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.
|
||||
*/
|
||||
|
|
@ -433,13 +434,12 @@ static inline int pm_runtime_resume(struct device *dev)
|
|||
* * 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.
|
||||
* * -EAGAIN: Runtime PM usage counter 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)
|
||||
{
|
||||
|
|
@ -464,15 +464,16 @@ static inline int pm_request_resume(struct device *dev)
|
|||
* equivalent pm_runtime_autosuspend() for @dev asynchronously.
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success; device was already suspended.
|
||||
* * 0: Success.
|
||||
* * -EINVAL: Runtime PM error.
|
||||
* * -EACCES: Runtime PM disabled.
|
||||
* * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
|
||||
* * -EAGAIN: Runtime PM usage counter 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)
|
||||
{
|
||||
|
|
@ -540,15 +541,16 @@ static inline int pm_runtime_resume_and_get(struct device *dev)
|
|||
* equal to 0, queue up a work item for @dev like in pm_request_idle().
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success. Usage counter dropped to zero, but device was already suspended.
|
||||
* * 0: Success.
|
||||
* * -EINVAL: Runtime PM error.
|
||||
* * -EACCES: Runtime PM disabled.
|
||||
* * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
|
||||
* * -EAGAIN: Runtime PM usage counter became 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)
|
||||
{
|
||||
|
|
@ -565,15 +567,16 @@ DEFINE_FREE(pm_runtime_put, struct device *, if (_T) pm_runtime_put(_T))
|
|||
* equal to 0, queue up a work item for @dev like in pm_request_autosuspend().
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success. Usage counter dropped to zero, but device was already suspended.
|
||||
* * 0: Success.
|
||||
* * -EINVAL: Runtime PM error.
|
||||
* * -EACCES: Runtime PM disabled.
|
||||
* * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
|
||||
* * -EAGAIN: Runtime PM usage counter became 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)
|
||||
{
|
||||
|
|
@ -590,15 +593,16 @@ static inline int __pm_runtime_put_autosuspend(struct device *dev)
|
|||
* in pm_request_autosuspend().
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success. Usage counter dropped to zero, but device was already suspended.
|
||||
* * 0: Success.
|
||||
* * -EINVAL: Runtime PM error.
|
||||
* * -EACCES: Runtime PM disabled.
|
||||
* * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
|
||||
* * -EAGAIN: Runtime PM usage counter became 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)
|
||||
{
|
||||
|
|
@ -619,14 +623,15 @@ static inline int pm_runtime_put_autosuspend(struct device *dev)
|
|||
* if it returns an error code.
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success. Usage counter dropped to zero, but device was already suspended.
|
||||
* * 0: Success.
|
||||
* * -EINVAL: Runtime PM error.
|
||||
* * -EACCES: Runtime PM disabled.
|
||||
* * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
|
||||
* * -EAGAIN: Runtime PM usage counter became 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.
|
||||
*/
|
||||
|
|
@ -646,15 +651,15 @@ static inline int pm_runtime_put_sync(struct device *dev)
|
|||
* if it returns an error code.
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success. Usage counter dropped to zero, but device was already suspended.
|
||||
* * 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.
|
||||
* * -EAGAIN: Runtime PM usage counter became 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.
|
||||
*/
|
||||
|
|
@ -677,15 +682,16 @@ static inline int pm_runtime_put_sync_suspend(struct device *dev)
|
|||
* if it returns an error code.
|
||||
*
|
||||
* Return:
|
||||
* * 1: Success. Usage counter dropped to zero, but device was already suspended.
|
||||
* * 0: Success.
|
||||
* * -EINVAL: Runtime PM error.
|
||||
* * -EACCES: Runtime PM disabled.
|
||||
* * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
|
||||
* * -EAGAIN: Runtime PM usage counter became 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.
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user