[PATCH] clk: document struct clk_ops

[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@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

Re: [PATCH] clk: document struct clk_ops

[Sascha Hauer]

On Wed, Nov 22, 2023 at 07:15:35PM +0100, Ahmad Fatoum wrote:
> 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@pengutronix.de>
> ---
>  include/linux/clk.h | 65 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 65 insertions(+)

Applied, thanks

Sascha

> 
> 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
> 
> 
> 

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |