[PATCH] clk: document struct clk_ops

[Ahmad Fatoum]

We already import the API from Linux, so let's import the documentation
for reference as well and add a note about clk_unprepare/clk_prepare.

Signed-off-by: Ahmad Fatoum <a.fatoum at pengutronix.de>
---
 include/linux/clk.h | 65 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/include/linux/clk.h b/include/linux/clk.h
index edcc43d9f1df..7657ab6fc245 100644
--- a/include/linux/clk.h
+++ b/include/linux/clk.h
@@ -240,6 +240,71 @@ static inline void clk_put(struct clk *clk)
 #define CLK_GATE_SET_TO_DISABLE	(1 << 0)
 #define CLK_GATE_HIWORD_MASK	(1 << 1)
 
+/**
+ * struct clk_ops -  Callback operations for hardware clocks; these are to
+ * be provided by the clock implementation, and will be called by drivers
+ * through the clk_* api.
+ *
+ * @init:	Perform platform-specific initialization magic.
+ *		This is not used by any of the basic clock types.
+ *		This callback exist for HW which needs to perform some
+ *		initialisation magic for CCF to get an accurate view of the
+ *		clock. It may also be used dynamic resource allocation is
+ *		required. It shall not used to deal with clock parameters,
+ *		such as rate or parents.
+ *		Returns 0 on success, -EERROR otherwise.
+ *
+ * @enable:	Prepare and enable the clock atomically. This must not return
+ *		until the clock is generating a valid clock signal, usable by
+ *		consumer devices.
+ *
+ * @disable:	Unprepare and disable the clock atomically.
+ *
+ * @is_enabled:	Queries the hardware to determine if the clock is enabled.
+ *		Optional, if this op is not set then the enable count will be
+ *		used.
+ *
+ * @recalc_rate	Recalculate the rate of this clock, by querying hardware. The
+ *		parent rate is an input parameter. If the driver cannot figure
+ *		out a rate for this clock, it must return 0. Returns the
+ *		calculated rate. Optional, but recommended - if this op is not
+ *		set then clock rate will be initialized to 0.
+ *
+ * @round_rate:	Given a target rate as input, returns the closest rate actually
+ *		supported by the clock. The parent rate is an input/output
+ *		parameter.
+ *
+ * @set_parent:	Change the input source of this clock; for clocks with multiple
+ *		possible parents specify a new parent by passing in the index
+ *		as a u8 corresponding to the parent in either the .parent_names
+ *		or .parents arrays.  This function in affect translates an
+ *		array index into the value programmed into the hardware.
+ *		Returns 0 on success, -EERROR otherwise.
+ *
+ * @get_parent:	Queries the hardware to determine the parent of a clock.  The
+ *		return value is a u8 which specifies the index corresponding to
+ *		the parent clock.  This index can be applied to either the
+ *		.parent_names or .parents arrays.  In short, this function
+ *		translates the parent value read from hardware into an array
+ *		index.
+ *
+ * @set_rate:	Change the rate of this clock. The requested rate is specified
+ *		by the second argument, which should typically be the return
+ *		of .round_rate call.  The third argument gives the parent rate
+ *		which is likely helpful for most .set_rate implementation.
+ *		Returns 0 on success, -EERROR otherwise.
+ *
+ * @set_phase:	Shift the phase this clock signal in degrees specified
+ *		by the second argument. Valid values for degrees are
+ *		0-359. Return 0 on success, otherwise -EERROR.
+ *
+ * @get_phase:	Queries the hardware to get the current phase of a clock.
+ *		Returned values are 0-359 degrees on success, negative
+ *		error codes on failure.
+ *
+ * Unlike Linux, there is no differentiation between clk_prepare/clk_enable
+ * and clk_unprepare/clk_disable in barebox as all work is atomic.
+ */
 struct clk_ops {
 	int 		(*init)(struct clk_hw *hw);
 	int		(*enable)(struct clk_hw *hw);
-- 
2.39.2