ARM: OMAP2+: clockdomain: work on wkdep/sleepdep functions

Split the clkdm_(add|del)_(wk|sleep)dep() functions into lockless and
locking versions -- this will be needed in a subsequent patch.  Also,
while here, remove the leading underscore, since these are not
currently static functions.  And for functions that have
kerneldoc-style comment blocks, but which are missing the initial
'/**' tag, fix the tag to indicate that they are kerneldoc.

Signed-off-by: Paul Walmsley <paul@pwsan.com>

3 files changed, 240 insertions, 167 deletions

diff --git a/arch/arm/mach-omap2/clockdomain.c b/arch/arm/mach-omap2/clockdomain.c
index 275bdfbb6fc5..ab194753eb7a 100644
--- a/arch/arm/mach-omap2/clockdomain.c
+++ b/arch/arm/mach-omap2/clockdomain.c
@@ -120,7 +120,7 @@ static struct clkdm_dep *_clkdm_deps_lookup(struct clockdomain *clkdm,
         return cd;
 }
 
-/*
+/**
  * _autodep_lookup - resolve autodep clkdm names to clkdm pointers; store
  * @autodep: struct clkdm_autodep * to resolve
  *
@@ -152,88 +152,202 @@ static void _autodep_lookup(struct clkdm_autodep *autodep)
         autodep->clkdm.ptr = clkdm;
 }
 
-/*
- * _clkdm_add_autodeps - add auto sleepdeps/wkdeps to clkdm upon clock enable
- * @clkdm: struct clockdomain *
+/**
+ * _resolve_clkdm_deps() - resolve clkdm_names in @clkdm_deps to clkdms
+ * @clkdm: clockdomain that we are resolving dependencies for
+ * @clkdm_deps: ptr to array of struct clkdm_deps to resolve
  *
- * Add the "autodep" sleep & wakeup dependencies to clockdomain 'clkdm'
- * in hardware-supervised mode.  Meant to be called from clock framework
- * when a clock inside clockdomain 'clkdm' is enabled.  No return value.
+ * Iterates through @clkdm_deps, looking up the struct clockdomain named by
+ * clkdm_name and storing the clockdomain pointer in the struct clkdm_dep.
+ * No return value.
+ */
+static void _resolve_clkdm_deps(struct clockdomain *clkdm,
+                                struct clkdm_dep *clkdm_deps)
+{
+        struct clkdm_dep *cd;
+
+        for (cd = clkdm_deps; cd && cd->clkdm_name; cd++) {
+                if (cd->clkdm)
+                        continue;
+                cd->clkdm = _clkdm_lookup(cd->clkdm_name);
+
+                WARN(!cd->clkdm, "clockdomain: %s: could not find clkdm %s while resolving dependencies - should never happen",
+                     clkdm->name, cd->clkdm_name);
+        }
+}
+
+/**
+ * _clkdm_add_wkdep - add a wakeup dependency from clkdm2 to clkdm1 (lockless)
+ * @clkdm1: wake this struct clockdomain * up (dependent)
+ * @clkdm2: when this struct clockdomain * wakes up (source)
  *
- * XXX autodeps are deprecated and should be removed at the earliest
- * opportunity
+ * When the clockdomain represented by @clkdm2 wakes up, wake up
+ * @clkdm1. Implemented in hardware on the OMAP, this feature is
+ * designed to reduce wakeup latency of the dependent clockdomain @clkdm1.
+ * Returns -EINVAL if presented with invalid clockdomain pointers,
+ * -ENOENT if @clkdm2 cannot wake up clkdm1 in hardware, or 0 upon
+ * success.
  */
-void _clkdm_add_autodeps(struct clockdomain *clkdm)
+static int _clkdm_add_wkdep(struct clockdomain *clkdm1,
+                            struct clockdomain *clkdm2)
 {
-        struct clkdm_autodep *autodep;
+        struct clkdm_dep *cd;
+        int ret = 0;
 
-        if (!autodeps || clkdm->flags & CLKDM_NO_AUTODEPS)
-                return;
+        if (!clkdm1 || !clkdm2)
+                return -EINVAL;
 
-        for (autodep = autodeps; autodep->clkdm.ptr; autodep++) {
-                if (IS_ERR(autodep->clkdm.ptr))
-                        continue;
+        cd = _clkdm_deps_lookup(clkdm2, clkdm1->wkdep_srcs);
+        if (IS_ERR(cd))
+                ret = PTR_ERR(cd);
 
-                pr_debug("clockdomain: %s: adding %s sleepdep/wkdep\n",
-                         clkdm->name, autodep->clkdm.ptr->name);
+        if (!arch_clkdm || !arch_clkdm->clkdm_add_wkdep)
+                ret = -EINVAL;
 
-                clkdm_add_sleepdep(clkdm, autodep->clkdm.ptr);
-                clkdm_add_wkdep(clkdm, autodep->clkdm.ptr);
+        if (ret) {
+                pr_debug("clockdomain: hardware cannot set/clear wake up of %s when %s wakes up\n",
+                         clkdm1->name, clkdm2->name);
+                return ret;
+        }
+
+        if (atomic_inc_return(&cd->wkdep_usecount) == 1) {
+                pr_debug("clockdomain: hardware will wake up %s when %s wakes up\n",
+                         clkdm1->name, clkdm2->name);
+
+                ret = arch_clkdm->clkdm_add_wkdep(clkdm1, clkdm2);
         }
+
+        return ret;
 }
 
-/*
- * _clkdm_add_autodeps - remove auto sleepdeps/wkdeps from clkdm
- * @clkdm: struct clockdomain *
+/**
+ * _clkdm_del_wkdep - remove a wakeup dep from clkdm2 to clkdm1 (lockless)
+ * @clkdm1: wake this struct clockdomain * up (dependent)
+ * @clkdm2: when this struct clockdomain * wakes up (source)
  *
- * Remove the "autodep" sleep & wakeup dependencies from clockdomain 'clkdm'
- * in hardware-supervised mode.  Meant to be called from clock framework
- * when a clock inside clockdomain 'clkdm' is disabled.  No return value.
+ * Remove a wakeup dependency causing @clkdm1 to wake up when @clkdm2
+ * wakes up.  Returns -EINVAL if presented with invalid clockdomain
+ * pointers, -ENOENT if @clkdm2 cannot wake up clkdm1 in hardware, or
+ * 0 upon success.
+ */
+static int _clkdm_del_wkdep(struct clockdomain *clkdm1,
+                            struct clockdomain *clkdm2)
+{
+        struct clkdm_dep *cd;
+        int ret = 0;
+
+        if (!clkdm1 || !clkdm2)
+                return -EINVAL;
+
+        cd = _clkdm_deps_lookup(clkdm2, clkdm1->wkdep_srcs);
+        if (IS_ERR(cd))
+                ret = PTR_ERR(cd);
+
+        if (!arch_clkdm || !arch_clkdm->clkdm_del_wkdep)
+                ret = -EINVAL;
+
+        if (ret) {
+                pr_debug("clockdomain: hardware cannot set/clear wake up of %s when %s wakes up\n",
+                         clkdm1->name, clkdm2->name);
+                return ret;
+        }
+
+        if (atomic_dec_return(&cd->wkdep_usecount) == 0) {
+                pr_debug("clockdomain: hardware will no longer wake up %s after %s wakes up\n",
+                         clkdm1->name, clkdm2->name);
+
+                ret = arch_clkdm->clkdm_del_wkdep(clkdm1, clkdm2);
+        }
+
+        return ret;
+}
+
+/**
+ * _clkdm_add_sleepdep - add a sleep dependency from clkdm2 to clkdm1 (lockless)
+ * @clkdm1: prevent this struct clockdomain * from sleeping (dependent)
+ * @clkdm2: when this struct clockdomain * is active (source)
  *
- * XXX autodeps are deprecated and should be removed at the earliest
- * opportunity
+ * Prevent @clkdm1 from automatically going inactive (and then to
+ * retention or off) if @clkdm2 is active.  Returns -EINVAL if
+ * presented with invalid clockdomain pointers or called on a machine
+ * that does not support software-configurable hardware sleep
+ * dependencies, -ENOENT if the specified dependency cannot be set in
+ * hardware, or 0 upon success.
  */
-void _clkdm_del_autodeps(struct clockdomain *clkdm)
+static int _clkdm_add_sleepdep(struct clockdomain *clkdm1,
+                               struct clockdomain *clkdm2)
 {
-        struct clkdm_autodep *autodep;
+        struct clkdm_dep *cd;
+        int ret = 0;
 
-        if (!autodeps || clkdm->flags & CLKDM_NO_AUTODEPS)
-                return;
+        if (!clkdm1 || !clkdm2)
+                return -EINVAL;
 
-        for (autodep = autodeps; autodep->clkdm.ptr; autodep++) {
-                if (IS_ERR(autodep->clkdm.ptr))
-                        continue;
+        cd = _clkdm_deps_lookup(clkdm2, clkdm1->sleepdep_srcs);
+        if (IS_ERR(cd))
+                ret = PTR_ERR(cd);
 
-                pr_debug("clockdomain: %s: removing %s sleepdep/wkdep\n",
-                         clkdm->name, autodep->clkdm.ptr->name);
+        if (!arch_clkdm || !arch_clkdm->clkdm_add_sleepdep)
+                ret = -EINVAL;
 
-                clkdm_del_sleepdep(clkdm, autodep->clkdm.ptr);
-                clkdm_del_wkdep(clkdm, autodep->clkdm.ptr);
+        if (ret) {
+                pr_debug("clockdomain: hardware cannot set/clear sleep dependency affecting %s from %s\n",
+                         clkdm1->name, clkdm2->name);
+                return ret;
         }
+
+        if (atomic_inc_return(&cd->sleepdep_usecount) == 1) {
+                pr_debug("clockdomain: will prevent %s from sleeping if %s is active\n",
+                         clkdm1->name, clkdm2->name);
+
+                ret = arch_clkdm->clkdm_add_sleepdep(clkdm1, clkdm2);
+        }
+
+        return ret;
 }
 
 /**
- * _resolve_clkdm_deps() - resolve clkdm_names in @clkdm_deps to clkdms
- * @clkdm: clockdomain that we are resolving dependencies for
- * @clkdm_deps: ptr to array of struct clkdm_deps to resolve
+ * _clkdm_del_sleepdep - remove a sleep dep from clkdm2 to clkdm1 (lockless)
+ * @clkdm1: prevent this struct clockdomain * from sleeping (dependent)
+ * @clkdm2: when this struct clockdomain * is active (source)
  *
- * Iterates through @clkdm_deps, looking up the struct clockdomain named by
- * clkdm_name and storing the clockdomain pointer in the struct clkdm_dep.
- * No return value.
+ * Allow @clkdm1 to automatically go inactive (and then to retention or
+ * off), independent of the activity state of @clkdm2.  Returns -EINVAL
+ * if presented with invalid clockdomain pointers or called on a machine
+ * that does not support software-configurable hardware sleep dependencies,
+ * -ENOENT if the specified dependency cannot be cleared in hardware, or
+ * 0 upon success.
  */
-static void _resolve_clkdm_deps(struct clockdomain *clkdm,
-                                struct clkdm_dep *clkdm_deps)
+static int _clkdm_del_sleepdep(struct clockdomain *clkdm1,
+                               struct clockdomain *clkdm2)
 {
         struct clkdm_dep *cd;
+        int ret = 0;
 
-        for (cd = clkdm_deps; cd && cd->clkdm_name; cd++) {
-                if (cd->clkdm)
-                        continue;
-                cd->clkdm = _clkdm_lookup(cd->clkdm_name);
+        if (!clkdm1 || !clkdm2)
+                return -EINVAL;
 
-                WARN(!cd->clkdm, "clockdomain: %s: could not find clkdm %s while resolving dependencies - should never happen",
-                     clkdm->name, cd->clkdm_name);
+        cd = _clkdm_deps_lookup(clkdm2, clkdm1->sleepdep_srcs);
+        if (IS_ERR(cd))
+                ret = PTR_ERR(cd);
+
+        if (!arch_clkdm || !arch_clkdm->clkdm_del_sleepdep)
+                ret = -EINVAL;
+
+        if (ret) {
+                pr_debug("clockdomain: hardware cannot set/clear sleep dependency affecting %s from %s\n",
+                         clkdm1->name, clkdm2->name);
+                return ret;
         }
+
+        if (atomic_dec_return(&cd->sleepdep_usecount) == 0) {
+                pr_debug("clockdomain: will no longer prevent %s from sleeping if %s is active\n",
+                         clkdm1->name, clkdm2->name);
+
+                ret = arch_clkdm->clkdm_del_sleepdep(clkdm1, clkdm2);
+        }
+
+        return ret;
 }
 
 /* Public functions */
@@ -453,33 +567,7 @@ struct powerdomain *clkdm_get_pwrdm(struct clockdomain *clkdm)
  */
 int clkdm_add_wkdep(struct clockdomain *clkdm1, struct clockdomain *clkdm2)
 {
-        struct clkdm_dep *cd;
-        int ret = 0;
-
-        if (!clkdm1 || !clkdm2)
-                return -EINVAL;
-
-        cd = _clkdm_deps_lookup(clkdm2, clkdm1->wkdep_srcs);
-        if (IS_ERR(cd))
-                ret = PTR_ERR(cd);
-
-        if (!arch_clkdm || !arch_clkdm->clkdm_add_wkdep)
-                ret = -EINVAL;
-
-        if (ret) {
-                pr_debug("clockdomain: hardware cannot set/clear wake up of %s when %s wakes up\n",
-                         clkdm1->name, clkdm2->name);
-                return ret;
-        }
-
-        if (atomic_inc_return(&cd->wkdep_usecount) == 1) {
-                pr_debug("clockdomain: hardware will wake up %s when %s wakes up\n",
-                         clkdm1->name, clkdm2->name);
-
-                ret = arch_clkdm->clkdm_add_wkdep(clkdm1, clkdm2);
-        }
-
-        return ret;
+        return _clkdm_add_wkdep(clkdm1, clkdm2);
 }
 
 /**
@@ -494,33 +582,7 @@ int clkdm_add_wkdep(struct clockdomain *clkdm1, struct clockdomain *clkdm2)
  */
 int clkdm_del_wkdep(struct clockdomain *clkdm1, struct clockdomain *clkdm2)
 {
-        struct clkdm_dep *cd;
-        int ret = 0;
-
-        if (!clkdm1 || !clkdm2)
-                return -EINVAL;
-
-        cd = _clkdm_deps_lookup(clkdm2, clkdm1->wkdep_srcs);
-        if (IS_ERR(cd))
-                ret = PTR_ERR(cd);
-
-        if (!arch_clkdm || !arch_clkdm->clkdm_del_wkdep)
-                ret = -EINVAL;
-
-        if (ret) {
-                pr_debug("clockdomain: hardware cannot set/clear wake up of %s when %s wakes up\n",
-                         clkdm1->name, clkdm2->name);
-                return ret;
-        }
-
-        if (atomic_dec_return(&cd->wkdep_usecount) == 0) {
-                pr_debug("clockdomain: hardware will no longer wake up %s after %s wakes up\n",
-                         clkdm1->name, clkdm2->name);
-
-                ret = arch_clkdm->clkdm_del_wkdep(clkdm1, clkdm2);
-        }
-
-        return ret;
+        return _clkdm_del_wkdep(clkdm1, clkdm2);
 }
 
 /**
@@ -597,33 +659,7 @@ int clkdm_clear_all_wkdeps(struct clockdomain *clkdm)
  */
 int clkdm_add_sleepdep(struct clockdomain *clkdm1, struct clockdomain *clkdm2)
 {
-        struct clkdm_dep *cd;
-        int ret = 0;
-
-        if (!clkdm1 || !clkdm2)
-                return -EINVAL;
-
-        cd = _clkdm_deps_lookup(clkdm2, clkdm1->sleepdep_srcs);
-        if (IS_ERR(cd))
-                ret = PTR_ERR(cd);
-
-        if (!arch_clkdm || !arch_clkdm->clkdm_add_sleepdep)
-                ret = -EINVAL;
-
-        if (ret) {
-                pr_debug("clockdomain: hardware cannot set/clear sleep dependency affecting %s from %s\n",
-                         clkdm1->name, clkdm2->name);
-                return ret;
-        }
-
-        if (atomic_inc_return(&cd->sleepdep_usecount) == 1) {
-                pr_debug("clockdomain: will prevent %s from sleeping if %s is active\n",
-                         clkdm1->name, clkdm2->name);
-
-                ret = arch_clkdm->clkdm_add_sleepdep(clkdm1, clkdm2);
-        }
-
-        return ret;
+        return _clkdm_add_sleepdep(clkdm1, clkdm2);
 }
 
 /**
@@ -640,33 +676,7 @@ int clkdm_add_sleepdep(struct clockdomain *clkdm1, struct clockdomain *clkdm2)
  */
 int clkdm_del_sleepdep(struct clockdomain *clkdm1, struct clockdomain *clkdm2)
 {
-        struct clkdm_dep *cd;
-        int ret = 0;
-
-        if (!clkdm1 || !clkdm2)
-                return -EINVAL;
-
-        cd = _clkdm_deps_lookup(clkdm2, clkdm1->sleepdep_srcs);
-        if (IS_ERR(cd))
-                ret = PTR_ERR(cd);
-
-        if (!arch_clkdm || !arch_clkdm->clkdm_del_sleepdep)
-                ret = -EINVAL;
-
-        if (ret) {
-                pr_debug("clockdomain: hardware cannot set/clear sleep dependency affecting %s from %s\n",
-                         clkdm1->name, clkdm2->name);
-                return ret;
-        }
-
-        if (atomic_dec_return(&cd->sleepdep_usecount) == 0) {
-                pr_debug("clockdomain: will no longer prevent %s from sleeping if %s is active\n",
-                         clkdm1->name, clkdm2->name);
-
-                ret = arch_clkdm->clkdm_del_sleepdep(clkdm1, clkdm2);
-        }
-
-        return ret;
+        return _clkdm_del_sleepdep(clkdm1, clkdm2);
 }
 
 /**
@@ -977,6 +987,68 @@ bool clkdm_missing_idle_reporting(struct clockdomain *clkdm)
         return (clkdm->flags & CLKDM_MISSING_IDLE_REPORTING) ? true : false;
 }
 
+/* Public autodep handling functions (deprecated) */
+
+/**
+ * clkdm_add_autodeps - add auto sleepdeps/wkdeps to clkdm upon clock enable
+ * @clkdm: struct clockdomain *
+ *
+ * Add the "autodep" sleep & wakeup dependencies to clockdomain 'clkdm'
+ * in hardware-supervised mode.  Meant to be called from clock framework
+ * when a clock inside clockdomain 'clkdm' is enabled.  No return value.
+ *
+ * XXX autodeps are deprecated and should be removed at the earliest
+ * opportunity
+ */
+void clkdm_add_autodeps(struct clockdomain *clkdm)
+{
+        struct clkdm_autodep *autodep;
+
+        if (!autodeps || clkdm->flags & CLKDM_NO_AUTODEPS)
+                return;
+
+        for (autodep = autodeps; autodep->clkdm.ptr; autodep++) {
+                if (IS_ERR(autodep->clkdm.ptr))
+                        continue;
+
+                pr_debug("clockdomain: %s: adding %s sleepdep/wkdep\n",
+                         clkdm->name, autodep->clkdm.ptr->name);
+
+                _clkdm_add_sleepdep(clkdm, autodep->clkdm.ptr);
+                _clkdm_add_wkdep(clkdm, autodep->clkdm.ptr);
+        }
+}
+
+/**
+ * clkdm_del_autodeps - remove auto sleepdeps/wkdeps from clkdm
+ * @clkdm: struct clockdomain *
+ *
+ * Remove the "autodep" sleep & wakeup dependencies from clockdomain 'clkdm'
+ * in hardware-supervised mode.  Meant to be called from clock framework
+ * when a clock inside clockdomain 'clkdm' is disabled.  No return value.
+ *
+ * XXX autodeps are deprecated and should be removed at the earliest
+ * opportunity
+ */
+void clkdm_del_autodeps(struct clockdomain *clkdm)
+{
+        struct clkdm_autodep *autodep;
+
+        if (!autodeps || clkdm->flags & CLKDM_NO_AUTODEPS)
+                return;
+
+        for (autodep = autodeps; autodep->clkdm.ptr; autodep++) {
+                if (IS_ERR(autodep->clkdm.ptr))
+                        continue;
+
+                pr_debug("clockdomain: %s: removing %s sleepdep/wkdep\n",
+                         clkdm->name, autodep->clkdm.ptr->name);
+
+                _clkdm_del_sleepdep(clkdm, autodep->clkdm.ptr);
+                _clkdm_del_wkdep(clkdm, autodep->clkdm.ptr);
+        }
+}
+
 /* Clockdomain-to-clock/hwmod framework interface code */
 
 static int _clkdm_clk_hwmod_enable(struct clockdomain *clkdm)
diff --git a/arch/arm/mach-omap2/clockdomain.h b/arch/arm/mach-omap2/clockdomain.h
index e7f1b4ba2d5b..50c3cd8bd706 100644
--- a/arch/arm/mach-omap2/clockdomain.h
+++ b/arch/arm/mach-omap2/clockdomain.h
@@ -216,8 +216,9 @@ extern void __init omap243x_clockdomains_init(void);
 extern void __init omap3xxx_clockdomains_init(void);
 extern void __init am33xx_clockdomains_init(void);
 extern void __init omap44xx_clockdomains_init(void);
-extern void _clkdm_add_autodeps(struct clockdomain *clkdm);
-extern void _clkdm_del_autodeps(struct clockdomain *clkdm);
+
+extern void clkdm_add_autodeps(struct clockdomain *clkdm);
+extern void clkdm_del_autodeps(struct clockdomain *clkdm);
 
 extern struct clkdm_ops omap2_clkdm_operations;
 extern struct clkdm_ops omap3_clkdm_operations;
diff --git a/arch/arm/mach-omap2/cm3xxx.c b/arch/arm/mach-omap2/cm3xxx.c
index c2086f2e86b6..b94af4cb9dd9 100644
--- a/arch/arm/mach-omap2/cm3xxx.c
+++ b/arch/arm/mach-omap2/cm3xxx.c
@@ -210,7 +210,7 @@ static int omap3xxx_clkdm_wakeup(struct clockdomain *clkdm)
 static void omap3xxx_clkdm_allow_idle(struct clockdomain *clkdm)
 {
         if (atomic_read(&clkdm->usecount) > 0)
-                _clkdm_add_autodeps(clkdm);
+                clkdm_add_autodeps(clkdm);
 
         omap3xxx_cm_clkdm_enable_hwsup(clkdm->pwrdm.ptr->prcm_offs,
                                        clkdm->clktrctrl_mask);
@@ -222,7 +222,7 @@ static void omap3xxx_clkdm_deny_idle(struct clockdomain *clkdm)
                                         clkdm->clktrctrl_mask);
 
         if (atomic_read(&clkdm->usecount) > 0)
-                _clkdm_del_autodeps(clkdm);
+                clkdm_del_autodeps(clkdm);
 }
 
 static int omap3xxx_clkdm_clk_enable(struct clockdomain *clkdm)
@@ -250,7 +250,7 @@ static int omap3xxx_clkdm_clk_enable(struct clockdomain *clkdm)
                 /* Disable HW transitions when we are changing deps */
                 omap3xxx_cm_clkdm_disable_hwsup(clkdm->pwrdm.ptr->prcm_offs,
                                                 clkdm->clktrctrl_mask);
-                _clkdm_add_autodeps(clkdm);
+                clkdm_add_autodeps(clkdm);
                 omap3xxx_cm_clkdm_enable_hwsup(clkdm->pwrdm.ptr->prcm_offs,
                                                clkdm->clktrctrl_mask);
         } else {
@@ -287,7 +287,7 @@ static int omap3xxx_clkdm_clk_disable(struct clockdomain *clkdm)
                 /* Disable HW transitions when we are changing deps */
                 omap3xxx_cm_clkdm_disable_hwsup(clkdm->pwrdm.ptr->prcm_offs,
                                                 clkdm->clktrctrl_mask);
-                _clkdm_del_autodeps(clkdm);
+                clkdm_del_autodeps(clkdm);
                 omap3xxx_cm_clkdm_enable_hwsup(clkdm->pwrdm.ptr->prcm_offs,
                                                clkdm->clktrctrl_mask);
         } else {