[PATCH v1 1/3] PM: runtime: Wrapper macros for ACQUIRE()/ACQUIRE_ERR()

["Rafael J. Wysocki" <rafael@kernel.org>]

From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

Add several wrapper macros for ACQUIRE()/ACQUIRE_ERR() and runtime PM
usage counter guards introduced recently: pm_runtime_active_try,
pm_runtime_active_auto_try, pm_runtime_active_try_enabled, and
pm_runtime_active_auto_try_enabled.

The new macros are simpler and should be more straightforward to use.
Moreover, they do not expose internal details that are not strictly
related to the code using the macros.

For example, they can be used for rewriting a piece of code like below:

        ACQUIRE(pm_runtime_active_try, pm)(dev);
        if ((ret = ACQUIRE_ERR(pm_runtime_active_try, &pm)))
                return ret;

in the following way:

        PM_RUNTIME_ACQUIRE(dev);
        if ((ret = PM_RUNTIME_ACQUIRE_ERR))
                return ret;

If the original code does not care about the specific error code
returned when attempting to resume the device:

        ACQUIRE(pm_runtime_active_try, pm)(dev);
        if (ACQUIRE_ERR(pm_runtime_active_try, &pm))
                return -ENXIO;

it may be changed like this:

        PM_RUNTIME_ACQUIRE(dev);
        if (PM_RUNTIME_ACQUIRE_ERR)
                return -ENXIO;

Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
---
 include/linux/pm_runtime.h |   55 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

--- a/include/linux/pm_runtime.h
+++ b/include/linux/pm_runtime.h
@@ -637,6 +637,61 @@ DEFINE_GUARD_COND(pm_runtime_active_auto
 DEFINE_GUARD_COND(pm_runtime_active_auto, _try_enabled,
 		  pm_runtime_resume_and_get(_T), _RET == 0)
 
+/*
+ * ACQUIRE() wrapper macros for the guards defined above.
+ *
+ * The tagged __PM_RUNTIME_ACQUIRE*() variants are for the cases in which two or
+ * more of these macros are used in the same scope and the tags are necessary to
+ * distinguish the internal guard variables from each other. Don't do that
+ * unless you have to. No, really. If they are needed, using simple tags is
+ * recommended (for example, individual digits or letters).
+ *
+ * The simpler PM_RUNTIME_ACQUIRE*() variants are wrappers around the
+ * corresponding __PM_RUNTIME_ACQUIRE*() that use the underline character
+ * as a (special) tag.  They should be suitable for the vast majority of use
+ * cases.
+ *
+ * Don't mix up PM_RUNTIME_ACQUIRE*() with __PM_RUNTIME_ACQUIRE*() even though
+ * that may work.
+ */
+#define __PM_RUNTIME_ACQUIRE(dev, tag)	\
+	ACQUIRE(pm_runtime_active_try, _pm_runtime_guard_var_##tag)(dev)
+
+#define PM_RUNTIME_ACQUIRE(dev)	\
+	__PM_RUNTIME_ACQUIRE(dev, _)
+
+#define __PM_RUNTIME_ACQUIRE_AUTOSUSPEND(dev, tag)	\
+	ACQUIRE(pm_runtime_active_auto_try, _pm_runtime_guard_var_##tag)(dev)
+
+#define PM_RUNTIME_ACQUIRE_AUTOSUSPEND(dev)	\
+	__PM_RUNTIME_ACQUIRE_AUTOSUSPEND(dev, _)
+
+#define __PM_RUNTIME_ACQUIRE_ENABLED(dev, tag)	\
+	ACQUIRE(pm_runtime_active_try_enabled, _pm_runtime_guard_var_##tag)(dev)
+
+#define PM_RUNTIME_ACQUIRE_ENABLED(dev)	\
+	__PM_RUNTIME_ACQUIRE_ENABLED(dev, _)
+
+#define __PM_RUNTIME_ACQUIRE_ENABLED_AUTOSUSPEND(dev, tag)	\
+	ACQUIRE(pm_runtime_active_auto_try_enabled, _pm_runtime_guard_var_##tag)(dev)
+
+#define PM_RUNTIME_ACQUIRE_ENABLED_AUTOSUSPEND(dev)	\
+	__PM_RUNTIME_ACQUIRE_ENABLED_AUTOSUSPEND(dev, _)
+
+/*
+ * ACQUIRE_ERR() wrapper macros for guard pm_runtime_active.
+ *
+ * Always check __PM_RUNTIME_ACQUIRE_ERR() with a matching tag after using one
+ * of the tagged __PM_RUNTIME_ACQUIRE*() macros defined above (yes, it can be
+ * used with any of them) and avoid accessing the given device if it is nonzero.
+ * Analogously, always check PM_RUNTIME_ACQUIRE_ERR after using any of the
+ * simpler PM_RUNTIME_ACQUIRE*() macros.
+ */
+#define __PM_RUNTIME_ACQUIRE_ERR(tag)	\
+	ACQUIRE_ERR(pm_runtime_active, &_pm_runtime_guard_var_##tag)
+
+#define PM_RUNTIME_ACQUIRE_ERR	__PM_RUNTIME_ACQUIRE_ERR(_)
+
 /**
  * pm_runtime_put_sync - Drop device usage counter and run "idle check" if 0.
  * @dev: Target device.