[ARM] Add additional documentation to the clock source framework
authorRussell King <rmk@dyn-67.arm.linux.org.uk>
Tue, 3 Jan 2006 18:34:20 +0000 (18:34 +0000)
committerRussell King <rmk+kernel@arm.linux.org.uk>
Tue, 3 Jan 2006 18:34:20 +0000 (18:34 +0000)
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>
include/asm-arm/hardware/clock.h

index 19da861e523d8dbbfe327e4b07d166c61544a623..5c5689409a4b59ad3bb508fbcbdf35c83036da67 100644 (file)
@@ -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);