Merge tag 'clk-2024.04-rc2' of https://source.denx.de/u-boot/custodians/u-boot-clk

Clock changes for v2024.04

This pull has the usual fixes and new (clock-adjacent) drivers. It also has some
cleanups for the clock API; in particular removing the unused rfree callback.

CI: https://source.denx.de/u-boot/custodians/u-boot-clk/-/pipelines/19486

2 files changed, 103 insertions, 51 deletions

diff --git a/include/clk-uclass.h b/include/clk-uclass.h
index cd62848bece..8c07e723cff 100644
--- a/include/clk-uclass.h
+++ b/include/clk-uclass.h
@@ -18,7 +18,6 @@ struct ofnode_phandle_args;
  * struct clk_ops - The functions that a clock driver must implement.
  * @of_xlate: Translate a client's device-tree (OF) clock specifier.
  * @request: Request a translated clock.
- * @rfree: Free a previously requested clock.
  * @round_rate: Adjust a rate to the exact rate a clock can provide.
  * @get_rate: Get current clock rate.
  * @set_rate: Set current clock rate.
@@ -33,7 +32,6 @@ struct clk_ops {
 	int (*of_xlate)(struct clk *clock,
 			struct ofnode_phandle_args *args);
 	int (*request)(struct clk *clock);
-	void (*rfree)(struct clk *clock);
 	ulong (*round_rate)(struct clk *clk, ulong rate);
 	ulong (*get_rate)(struct clk *clk);
 	ulong (*set_rate)(struct clk *clk, ulong rate);
@@ -58,11 +56,20 @@ struct clk_ops {
  * default implementation, which assumes #clock-cells = <1>, and that
  * the DT cell contains a simple integer clock ID.
  *
+ * This function should be a simple translation of @args into @clock->id and
+ * (optionally) @clock->data. All other processing, allocation, or error
+ * checking should take place in request().
+ *
  * At present, the clock API solely supports device-tree. If this
  * changes, other xxx_xlate() functions may be added to support those
  * other mechanisms.
  *
- * Return: 0 if OK, or a negative error code.
+ * Return:
+ * * 0 on success
+ * * -%EINVAL if @args does not have the correct format. For example, it could
+ *   have too many/few arguments.
+ * * -%ENOENT if @args has the correct format but cannot be translated. This can
+ *   happen if translation involves a table lookup and @args is not present.
  */
 int of_xlate(struct clk *clock, struct ofnode_phandle_args *args);
 
@@ -77,24 +84,36 @@ int of_xlate(struct clk *clock, struct ofnode_phandle_args *args);
  * xxx_xlate() call, or as the only step in implementing a client's
  * clk_request() call.
  *
- * Return: 0 if OK, or a negative error code.
- */
-int request(struct clk *clock);
-
-/**
- * rfree() - Free a previously requested clock.
- * @clock:	The clock to free.
+ * This is the right place to do bounds checking (rejecting invalid or
+ * unimplemented clocks), allocate resources, or perform other setup not done
+ * during driver probe(). Most clock drivers should allocate resources in their
+ * probe() function, but it is possible to lazily initialize something here.
  *
- * Free any resources allocated in request().
+ * Return:
+ * * 0 on success
+ * * -%ENOENT, if there is no clock corresponding to @clock->id and
+ *   @clock->data.
  */
-void rfree(struct clk *clock);
+int request(struct clk *clock);
 
 /**
  * round_rate() - Adjust a rate to the exact rate a clock can provide.
- * @clk:	The clock to manipulate.
- * @rate:	Desidered clock rate in Hz.
+ * @clk:	The clock to query.
+ * @rate:	Desired clock rate in Hz.
+ *
+ * This function returns a new rate which can be provided to set_rate(). This
+ * new rate should be the closest rate to @rate which can be set without
+ * rounding. The following pseudo-code should hold::
  *
- * Return: rounded rate in Hz, or -ve error code.
+ *   for all rate in range(ULONG_MAX):
+ *     rounded = round_rate(clk, rate)
+ *     new_rate = set_rate(clk, rate)
+ *     assert(IS_ERR_VALUE(new_rate) || new_rate == rounded)
+ *
+ * Return:
+ * * The rounded rate in Hz on success
+ * * A negative error value from another API (such as clk_get_rate()). This
+ *   function must not return an error for any other reason.
  */
 ulong round_rate(struct clk *clk, ulong rate);
 
@@ -102,7 +121,22 @@ ulong round_rate(struct clk *clk, ulong rate);
  * get_rate() - Get current clock rate.
  * @clk:	The clock to query.
  *
- * Return: clock rate in Hz, or -ve error code
+ * This returns the current rate of a clock. If the clock is disabled, it
+ * returns the rate at which the clock would run if it was enabled. The
+ * following pseudo-code should hold::
+ *
+ *   disable(clk)
+ *   rate = get_rate(clk)
+ *   enable(clk)
+ *   assert(get_rate(clk) == rate)
+ *
+ * Return:
+ * * The rate of @clk
+ * * -%ENOSYS if this function is not implemented for @clk
+ * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing
+ *   this check in request().
+ * * Another negative error value (such as %EIO or %ECOMM) if the rate could
+ *   not be determined due to a bus error.
  */
 ulong get_rate(struct clk *clk);
 
@@ -111,7 +145,27 @@ ulong get_rate(struct clk *clk);
  * @clk:	The clock to manipulate.
  * @rate:	New clock rate in Hz.
  *
- * Return: new rate, or -ve error code.
+ * Set the rate of @clk to @rate. The actual rate may be rounded. However,
+ * excessive rounding should be avoided. It is left to the driver author's
+ * discretion when this function should attempt to round and when it should
+ * return an error. For example, a dividing clock might use the following
+ * pseudo-logic when implemening this function::
+ *
+ *   divisor = parent_rate / rate
+ *   if divisor < min || divisor > max:
+ *     return -EINVAL
+ *
+ * If there is any concern about rounding, prefer to let consumers make the
+ * decision by calling round_rate().
+ *
+ * Return:
+ * * The new rate on success
+ * * -%ENOSYS if this function is not implemented for @clk
+ * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing
+ *   this check in request().
+ * * -%EINVAL if @rate is not valid for @clk.
+ * * Another negative error value (such as %EIO or %ECOMM) if the rate could
+ *   not be set due to a bus error.
  */
 ulong set_rate(struct clk *clk, ulong rate);
 
@@ -120,7 +174,19 @@ ulong set_rate(struct clk *clk, ulong rate);
  * @clk:        The clock to manipulate.
  * @parent:     New clock parent.
  *
- * Return: zero on success, or -ve error code.
+ * Set the current parent of @clk to @parent. The rate of the clock may be
+ * modified by this call. If @clk was enabled before this function, it should
+ * remain enabled after this function, although it may be temporarily disabled
+ * if necessary.
+ *
+ * Return:
+ * * 0 on success
+ * * -%ENOSYS if this function is not implemented for @clk
+ * * -%ENOENT if @clk->id or @parent->id is invalid. Prefer using an assert
+ *   instead, and doing this check in request().
+ * * -%EINVAL if @parent is not a valid parent for @clk.
+ * * Another negative error value (such as %EIO or %ECOMM) if the parent could
+ *   not be set due to a bus error.
  */
 int set_parent(struct clk *clk, struct clk *parent);
 
@@ -128,7 +194,16 @@ int set_parent(struct clk *clk, struct clk *parent);
  * enable() - Enable a clock.
  * @clk:	The clock to manipulate.
  *
- * Return: zero on success, or -ve error code.
+ * Enable (un-gate) the clock. This function should not modify the rate of the
+ * clock (see get_rate() for details).
+ *
+ * Return:
+ * * 0 on success
+ * * -%ENOSYS if this function is not implemented for @clk
+ * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing
+ *   this check in request().
+ * * Another negative error value (such as %EIO or %ECOMM) if the clock could
+ *   not be enabled due to a bus error.
  */
 int enable(struct clk *clk);
 
@@ -136,7 +211,15 @@ int enable(struct clk *clk);
  * disable() - Disable a clock.
  * @clk:	The clock to manipulate.
  *
- * Return: zero on success, or -ve error code.
+ * Disable (gate) the clock. This function should not modify the rate of the
+ * clock (see get_rate() for details).
+ *
+ * * 0 on success
+ * * -%ENOSYS if this function is not implemented for @clk
+ * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing
+ *   this check in request().
+ * * Another negative error value (such as %EIO or %ECOMM) if the clock could
+ *   not be disabled due to a bus error.
  */
 int disable(struct clk *clk);
 
diff --git a/include/clk.h b/include/clk.h
index 3d6394477be..af23e4f3475 100644
--- a/include/clk.h
+++ b/include/clk.h
@@ -247,19 +247,6 @@ static inline struct clk *devm_clk_get_optional(struct udevice *dev,
  */
 int clk_release_all(struct clk *clk, unsigned int count);
 
-/**
- * devm_clk_put	- "free" a managed clock source
- * @dev: device used to acquire the clock
- * @clk: clock source acquired with devm_clk_get()
- *
- * 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.
- *
- * clk_put should not be called from within interrupt context.
- */
-void devm_clk_put(struct udevice *dev, struct clk *clk);
-
 #else
 
 static inline int clk_get_by_phandle(struct udevice *dev, const
@@ -313,10 +300,6 @@ static inline int clk_release_all(struct clk *clk, unsigned int count)
 {
 	return -ENOSYS;
 }
-
-static inline void devm_clk_put(struct udevice *dev, struct clk *clk)
-{
-}
 #endif
 
 /**
@@ -442,15 +425,6 @@ static inline int clk_release_bulk(struct clk_bulk *bulk)
 int clk_request(struct udevice *dev, struct clk *clk);
 
 /**
- * clk_free() - Free a previously requested clock.
- * @clk:	A clock struct that was previously successfully requested by
- *		clk_request/get_by_*().
- *
- * Free resources allocated by clk_request() (or any clk_get_* function).
- */
-void clk_free(struct clk *clk);
-
-/**
  * clk_get_rate() - Get current clock rate.
  * @clk:	A clock struct that was previously successfully requested by
  *		clk_request/get_by_*().
@@ -594,11 +568,6 @@ static inline int clk_request(struct udevice *dev, struct clk *clk)
 	return -ENOSYS;
 }
 
-static inline void clk_free(struct clk *clk)
-{
-	return;
-}
-
 static inline ulong clk_get_rate(struct clk *clk)
 {
 	return -ENOSYS;