---

yaml
---
r: 16739
b: refs/heads/master
c: f47fc0a
h: refs/heads/master
i:
  16737: 0b76bfe
  16735: 54e15f3
v: v3

[refs]

@@ -1,2 +1,2 @@
 ---
-refs/heads/master: 78ff18a412da24a4b79c6a97000ef5e467e813da
+refs/heads/master: f47fc0ac7ead5ed91a11fcabfad6ee44c17ee934

trunk/include/asm-arm/hardware/clock.h

@@ -33,6 +33,8 @@ struct clk;
  * uses @dev and @id to determine the clock consumer, and thereby
  * the clock producer.  (IOW, @id may be identical strings, but
  * clk_get may return different clock producers depending on @dev.)
+ *
+ * Drivers must assume that the clock source is not enabled.
  */
 struct clk *clk_get(struct device *dev, const char *id);
 
@@ -49,6 +51,14 @@ int clk_enable(struct clk *clk);
 /**
  * clk_disable - inform the system when the clock source is no longer required.
  * @clk: clock source
+ *
+ * Inform the system that a clock source is no longer required by
+ * a driver and may be shut down.
+ *
+ * Implementation detail: if the clock source is shared between
+ * multiple drivers, clk_enable() calls must be balanced by the
+ * same number of clk_disable() calls for the clock source to be
+ * disabled.
  */
 void clk_disable(struct clk *clk);
 
@@ -76,6 +86,10 @@ unsigned long clk_get_rate(struct clk *clk);
 /**
  * clk_put	- "free" the clock source
  * @clk: clock source
+ *
+ * Note: drivers must ensure that all clk_enable calls made on this
+ * clock source are balanced by clk_disable calls prior to calling
+ * this function.
  */
 void clk_put(struct clk *clk);