Commit c58e7ed2 authored May 26, 2021 by Krzysztof Kozlowski Committed by Rafael J. Wysocki May 31, 2021

PM: runtime: document common mistake with pm_runtime_get_sync()



pm_runtime_get_sync(), contradictory to intuition, does not drop the
runtime PM usage counter on errors which lead to several wrong usages in
drivers (missing the put).  pm_runtime_resume_and_get() was added as a
better implementation so document the preference of using it, hoping it
will stop bad patterns.

Suggested-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
[ rjw: Documentation change edits ]
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

parent 8124c8a6

Documentation/power/runtime_pm.rst

+5 −1

Original line number	Diff line number	Diff line
		@@ -378,7 +378,11 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:

		`int pm_runtime_get_sync(struct device *dev);`
		- increment the device's usage counter, run pm_runtime_resume(dev) and
		return its result
		return its result;
		note that it does not drop the device's usage counter on errors, so
		consider using pm_runtime_resume_and_get() instead of it, especially
		if its return value is checked by the caller, as this is likely to
		result in cleaner code.

		`int pm_runtime_get_if_in_use(struct device *dev);`
		- return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the

include/linux/pm_runtime.h

+3 −0

Original line number	Diff line number	Diff line
		@@ -380,6 +380,9 @@ static inline int pm_runtime_get(struct device *dev)
		* The possible return values of this function are the same as for
		* pm_runtime_resume() and the runtime PM usage counter of @dev remains
		* incremented in all cases, even if it returns an error code.
		* Consider using pm_runtime_resume_and_get() instead of it, especially
		* if its return value is checked by the caller, as this is likely to result
		* in cleaner code.
		*/
		static inline int pm_runtime_get_sync(struct device *dev)
		{