[ARM] Add additional documentation to the clock source framework

It seems that there's some confusion over how the clock source
framework should be used.  Add some additional comments to explain
the ambiguous areas.

Signed-off-by: Russell King <rmk+kernel@arm.linux.org.uk>

diff --git a/include/asm-arm/hardware/clock.h b/include/asm-arm/hardware/clock.h
index 19da861..5c56894 100644 (file)
--- a/include/asm-arm/hardware/clock.h
+++ b/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);