| Message ID | 20210526162251.125600-1-krzysztof.kozlowski@canonical.com |
|---|---|
| State | Accepted |
| Commit | c58e7ed28b4534ed073371843d03c433d6a9fe34 |
| Headers | show |
| Series | [v2] PM: runtime: document common mistake with pm_runtime_get_sync() | expand |
On Wed, May 26, 2021 at 6:23 PM Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com> wrote: > > 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> > > --- > > Changes since v1: > 1. Reword after comments from Rafael. > --- > Documentation/power/runtime_pm.rst | 6 +++++- > include/linux/pm_runtime.h | 3 +++ > 2 files changed, 8 insertions(+), 1 deletion(-) > > diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst > index 18ae21bf7f92..33619bf83f69 100644 > --- a/Documentation/power/runtime_pm.rst > +++ b/Documentation/power/runtime_pm.rst > @@ -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; > + be aware that it does not drop the device's usage counter on errors so > + 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 > diff --git a/include/linux/pm_runtime.h b/include/linux/pm_runtime.h > index 6c08a085367b..aab8b35e9f8a 100644 > --- a/include/linux/pm_runtime.h > +++ b/include/linux/pm_runtime.h > @@ -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) > { > -- Applied as 5.14 material (with some cosmetic edits), thanks!
diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst index 18ae21bf7f92..33619bf83f69 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -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; + be aware that it does not drop the device's usage counter on errors so + 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 diff --git a/include/linux/pm_runtime.h b/include/linux/pm_runtime.h index 6c08a085367b..aab8b35e9f8a 100644 --- a/include/linux/pm_runtime.h +++ b/include/linux/pm_runtime.h @@ -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) {
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> --- Changes since v1: 1. Reword after comments from Rafael. --- Documentation/power/runtime_pm.rst | 6 +++++- include/linux/pm_runtime.h | 3 +++ 2 files changed, 8 insertions(+), 1 deletion(-)