[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
--- a/include/asm-arm/hardware/clock.h
+++ b/include/asm-arm/hardware/clock.h
@@ -33,6 +33,8 @@
* 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 @@
/**
* 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 @@
/**
* 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);