[PATCH 0/8] Clk documentation updates

[PATCH 0/8] Clk documentation updates

[Stephen Boyd]

Here's a random collection of core clk documentation updates.
During the process I noticed that the 'flags' member of the fixed rate
clk wasn't used, so I dropped it and updated the user in the NXP driver.
I'm planning to apply this for the v5.2 series.

Stephen Boyd (8):
  clk: Collapse gpio clk kerneldoc
  clk: Document deprecated things
  clk: Document CLK_MUX_READ_ONLY mux flag
  clk: Document __clk_mux_determine_rate()
  clk: nxp: Drop 'flags' on fixed_rate clk macro
  clk: Remove 'flags' member of struct clk_fixed_rate
  clk: Document and simplify clk_core_get_rate_nolock()
  clk: Drop duplicate clk_register() documentation

 drivers/clk/clk.c             | 46 ++++++++++++++++++++---------------
 drivers/clk/nxp/clk-lpc32xx.c |  7 +++---
 include/linux/clk-provider.h  | 39 +++++++++--------------------
 3 files changed, 40 insertions(+), 52 deletions(-)


base-commit: bfeffd155283772bbe78c6a05dec7c0128ee500c
-- 
Sent by a computer through tubes

[PATCH 1/8] clk: Collapse gpio clk kerneldoc

[Stephen Boyd]

We have two kernel-docs for gpio clks, but there is only one gpio clk
structure. Collapse the two so we have proper kerneldoc for this basic
clk type.

Signed-off-by: Stephen Boyd <sboyd@kernel.org>
---
 include/linux/clk-provider.h | 23 ++++++++---------------
 1 file changed, 8 insertions(+), 15 deletions(-)

diff --git a/include/linux/clk-provider.h b/include/linux/clk-provider.h
index e443fa9fa859..b65b48cc31f1 100644
--- a/include/linux/clk-provider.h
+++ b/include/linux/clk-provider.h
@@ -712,16 +712,19 @@ struct clk_hw *clk_hw_register_composite(struct device *dev, const char *name,
 		unsigned long flags);
 void clk_hw_unregister_composite(struct clk_hw *hw);
 
-/***
- * struct clk_gpio_gate - gpio gated clock
+/**
+ * struct clk_gpio - gpio gated clock
  *
  * @hw:		handle between common and hardware-specific interfaces
  * @gpiod:	gpio descriptor
  *
- * Clock with a gpio control for enabling and disabling the parent clock.
- * Implements .enable, .disable and .is_enabled
+ * Clock with a gpio control for enabling and disabling the parent clock
+ * or switching between two parents by asserting or deasserting the gpio.
+ *
+ * Implements .enable, .disable and .is_enabled or
+ * .get_parent, .set_parent and .determine_rate depending on which clk_ops
+ * is used.
  */
-
 struct clk_gpio {
 	struct clk_hw	hw;
 	struct gpio_desc *gpiod;
@@ -738,16 +741,6 @@ struct clk_hw *clk_hw_register_gpio_gate(struct device *dev, const char *name,
 		unsigned long flags);
 void clk_hw_unregister_gpio_gate(struct clk_hw *hw);
 
-/**
- * struct clk_gpio_mux - gpio controlled clock multiplexer
- *
- * @hw:		see struct clk_gpio
- * @gpiod:	gpio descriptor to select the parent of this clock multiplexer
- *
- * Clock with a gpio control for selecting the parent clock.
- * Implements .get_parent, .set_parent and .determine_rate
- */
-
 extern const struct clk_ops clk_gpio_mux_ops;
 struct clk *clk_register_gpio_mux(struct device *dev, const char *name,
 		const char * const *parent_names, u8 num_parents, struct gpio_desc *gpiod,
-- 
Sent by a computer through tubes

[PATCH 2/8] clk: Document deprecated things

[Stephen Boyd]

We don't want driver authors to use the struct clk based registration
and provider APIs. Instead, they should use the clk_hw based APIs. Add
some notes in the kerneldoc to this effect.

Signed-off-by: Stephen Boyd <sboyd@kernel.org>
---
 drivers/clk/clk.c            | 15 ++++++++++-----
 include/linux/clk-provider.h |  2 +-
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
index 75d13c0eff12..592e315f7cfd 100644
--- a/drivers/clk/clk.c
+++ b/drivers/clk/clk.c
@@ -3240,8 +3240,10 @@ void __clk_free_clk(struct clk *clk)
  * @dev: device that is registering this clock
  * @hw: link to hardware-specific clock data
  *
- * clk_register is the primary interface for populating the clock tree with new
- * clock nodes.  It returns a pointer to the newly allocated struct clk which
+ * clk_register is the *deprecated* interface for populating the clock tree with
+ * new clock nodes. Use clk_hw_register() instead.
+ *
+ * Returns: a pointer to the newly allocated struct clk which
  * cannot be dereferenced by driver code but may be used in conjunction with the
  * rest of the clock API.  In the event of an error clk_register will return an
  * error code; drivers must test for an error code after calling clk_register.
@@ -3486,9 +3488,10 @@ static void devm_clk_hw_release(struct device *dev, void *res)
  * @dev: device that is registering this clock
  * @hw: link to hardware-specific clock data
  *
- * Managed clk_register(). Clocks returned from this function are
- * automatically clk_unregister()ed on driver detach. See clk_register() for
- * more information.
+ * Managed clk_register(). This function is *deprecated*, use devm_clk_hw_register() instead.
+ *
+ * Clocks returned from this function are automatically clk_unregister()ed on
+ * driver detach. See clk_register() for more information.
  */
 struct clk *devm_clk_register(struct device *dev, struct clk_hw *hw)
 {
@@ -3820,6 +3823,8 @@ EXPORT_SYMBOL_GPL(of_clk_hw_onecell_get);
  * @np: Device node pointer associated with clock provider
  * @clk_src_get: callback for decoding clock
  * @data: context pointer for @clk_src_get callback.
+ *
+ * This function is *deprecated*. Use of_clk_add_hw_provider() instead.
  */
 int of_clk_add_provider(struct device_node *np,
 			struct clk *(*clk_src_get)(struct of_phandle_args *clkspec,
diff --git a/include/linux/clk-provider.h b/include/linux/clk-provider.h
index b65b48cc31f1..adb8a58e213c 100644
--- a/include/linux/clk-provider.h
+++ b/include/linux/clk-provider.h
@@ -24,7 +24,7 @@
 #define CLK_SET_RATE_PARENT	BIT(2) /* propagate rate change up one level */
 #define CLK_IGNORE_UNUSED	BIT(3) /* do not gate even if unused */
 				/* unused */
-#define CLK_IS_BASIC		BIT(5) /* Basic clk, can't do a to_clk_foo() */
+#define CLK_IS_BASIC		BIT(5) /* deprecated, don't use */
 #define CLK_GET_RATE_NOCACHE	BIT(6) /* do not use the cached clk rate */
 #define CLK_SET_RATE_NO_REPARENT BIT(7) /* don't re-parent on rate change */
 #define CLK_GET_ACCURACY_NOCACHE BIT(8) /* do not use the cached clk accuracy */
-- 
Sent by a computer through tubes

[PATCH 3/8] clk: Document CLK_MUX_READ_ONLY mux flag

[Stephen Boyd]

This flag isn't documented. Document it.

Signed-off-by: Stephen Boyd <sboyd@kernel.org>
---
 include/linux/clk-provider.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/linux/clk-provider.h b/include/linux/clk-provider.h
index adb8a58e213c..edff3c5883bc 100644
--- a/include/linux/clk-provider.h
+++ b/include/linux/clk-provider.h
@@ -499,6 +499,8 @@ void clk_hw_unregister_divider(struct clk_hw *hw);
  *	register, and mask of mux bits are in higher 16-bit of this register.
  *	While setting the mux bits, higher 16-bit should also be updated to
  *	indicate changing mux bits.
+ * CLK_MUX_READ_ONLY - The mux registers can't be written, only read in the
+ * 	.get_parent clk_op.
  * CLK_MUX_ROUND_CLOSEST - Use the parent rate that is closest to the desired
  *	frequency.
  */
-- 
Sent by a computer through tubes

[PATCH 4/8] clk: Document __clk_mux_determine_rate()

[Stephen Boyd]

It had some documentation, but not kerneldoc style so it wasn't getting
picked up. Add some docs so scripts can pick this function out.

Signed-off-by: Stephen Boyd <sboyd@kernel.org>
---
 drivers/clk/clk.c | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
index 592e315f7cfd..c9860074899b 100644
--- a/drivers/clk/clk.c
+++ b/drivers/clk/clk.c
@@ -519,9 +519,15 @@ void clk_hw_set_rate_range(struct clk_hw *hw, unsigned long min_rate,
 EXPORT_SYMBOL_GPL(clk_hw_set_rate_range);
 
 /*
+ * __clk_mux_determine_rate - clk_ops::determine_rate implementation for a mux type clk
+ * @hw: mux type clk to determine rate on
+ * @req: rate request, also used to return preferred parent and frequencies
+ *
  * Helper for finding best parent to provide a given frequency. This can be used
  * directly as a determine_rate callback (e.g. for a mux), or from a more
  * complex clock that may combine a mux with other operations.
+ *
+ * Returns: 0 on success, -EERROR value on error
  */
 int __clk_mux_determine_rate(struct clk_hw *hw,
 			     struct clk_rate_request *req)
-- 
Sent by a computer through tubes

[PATCH 5/8] clk: nxp: Drop 'flags' on fixed_rate clk macro

[Stephen Boyd]

The flags argument here is always 0, and we want to get rid of the flags
member of the clk_fixed_rate struct. So remove this here and just pass 0
when it's used.

Signed-off-by: Stephen Boyd <sboyd@kernel.org>
---
 drivers/clk/nxp/clk-lpc32xx.c | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/drivers/clk/nxp/clk-lpc32xx.c b/drivers/clk/nxp/clk-lpc32xx.c
index 5eeecee17b69..7524d19fe60b 100644
--- a/drivers/clk/nxp/clk-lpc32xx.c
+++ b/drivers/clk/nxp/clk-lpc32xx.c
@@ -1085,13 +1085,12 @@ struct clk_hw_proto {
 	};
 };
 
-#define LPC32XX_DEFINE_FIXED(_idx, _rate, _flags)			\
+#define LPC32XX_DEFINE_FIXED(_idx, _rate)			\
 [CLK_PREFIX(_idx)] = {							\
 	.type = CLK_FIXED,						\
 	{								\
 		.f = {							\
 			.fixed_rate = (_rate),				\
-			.flags = (_flags),				\
 		},							\
 	},								\
 }
@@ -1225,7 +1224,7 @@ struct clk_hw_proto {
 }
 
 static struct clk_hw_proto clk_hw_proto[LPC32XX_CLK_HW_MAX] = {
-	LPC32XX_DEFINE_FIXED(RTC, 32768, 0),
+	LPC32XX_DEFINE_FIXED(RTC, 32768),
 	LPC32XX_DEFINE_PLL(PLL397X, pll_397x, HCLKPLL_CTRL, BIT(1)),
 	LPC32XX_DEFINE_PLL(HCLK_PLL, hclk_pll, HCLKPLL_CTRL, PLL_CTRL_ENABLE),
 	LPC32XX_DEFINE_PLL(USB_PLL, usb_pll, USB_CTRL, PLL_CTRL_ENABLE),
@@ -1468,7 +1467,7 @@ static struct clk * __init lpc32xx_clk_register(u32 id)
 		struct clk_fixed_rate *fixed = &clk_hw->f;
 
 		clk = clk_register_fixed_rate(NULL, lpc32xx_clk->name,
-			parents[0], fixed->flags, fixed->fixed_rate);
+			parents[0], 0, fixed->fixed_rate);
 		break;
 	}
 	default:
-- 
Sent by a computer through tubes

[PATCH 6/8] clk: Remove 'flags' member of struct clk_fixed_rate

[Stephen Boyd]

This member is never used nor documented in the kerneldoc. Remove it.

Signed-off-by: Stephen Boyd <sboyd@kernel.org>
---
 include/linux/clk-provider.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/include/linux/clk-provider.h b/include/linux/clk-provider.h
index edff3c5883bc..a1705a0f08c7 100644
--- a/include/linux/clk-provider.h
+++ b/include/linux/clk-provider.h
@@ -307,7 +307,6 @@ struct clk_fixed_rate {
 	struct		clk_hw hw;
 	unsigned long	fixed_rate;
 	unsigned long	fixed_accuracy;
-	u8		flags;
 };
 
 #define to_clk_fixed_rate(_hw) container_of(_hw, struct clk_fixed_rate, hw)
-- 
Sent by a computer through tubes

[PATCH 7/8] clk: Document and simplify clk_core_get_rate_nolock()

[Stephen Boyd]

This function uses a few gotos and doesn't explain why parents and
numbers of parents are being checked before returning different values
for the clk's rate. Document and simplify this function somewhat to make
this better.

Signed-off-by: Stephen Boyd <sboyd@kernel.org>
---
 drivers/clk/clk.c | 25 ++++++++++---------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
index c9860074899b..79d0466cd180 100644
--- a/drivers/clk/clk.c
+++ b/drivers/clk/clk.c
@@ -345,23 +345,18 @@ unsigned int __clk_get_enable_count(struct clk *clk)
 
 static unsigned long clk_core_get_rate_nolock(struct clk_core *core)
 {
-	unsigned long ret;
-
-	if (!core) {
-		ret = 0;
-		goto out;
-	}
-
-	ret = core->rate;
-
-	if (!core->num_parents)
-		goto out;
+	if (!core)
+		return 0;
 
-	if (!core->parent)
-		ret = 0;
+	if (!core->num_parents || core->parent)
+		return core->rate;
 
-out:
-	return ret;
+	/*
+	 * Clk must have a parent because num_parents > 0 but the parent isn't
+	 * known yet. Best to return 0 as the rate of this clk until we can
+	 * properly recalc the rate based on the parent's rate.
+	 */
+	return 0;
 }
 
 unsigned long clk_hw_get_rate(const struct clk_hw *hw)
-- 
Sent by a computer through tubes

[PATCH 8/8] clk: Drop duplicate clk_register() documentation

[Stephen Boyd]

clk_register() isn't the main way to register a clk anymore. Developers
should use clk_hw_register() instead. Furthermore, this whole chunk of
documentation duplicates what's in the C file, so let's just use that.

Signed-off-by: Stephen Boyd <sboyd@kernel.org>
---
 include/linux/clk-provider.h | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/include/linux/clk-provider.h b/include/linux/clk-provider.h
index a1705a0f08c7..677df7865ac8 100644
--- a/include/linux/clk-provider.h
+++ b/include/linux/clk-provider.h
@@ -751,17 +751,6 @@ struct clk_hw *clk_hw_register_gpio_mux(struct device *dev, const char *name,
 		unsigned long flags);
 void clk_hw_unregister_gpio_mux(struct clk_hw *hw);
 
-/**
- * clk_register - allocate a new clock, register it and return an opaque cookie
- * @dev: device that is registering this clock
- * @hw: link to hardware-specific clock data
- *
- * clk_register is the primary interface for populating the clock tree with new
- * clock nodes.  It returns a pointer to the newly allocated struct clk which
- * cannot be dereferenced by driver code but may be used in conjuction with the
- * rest of the clock API.  In the event of an error clk_register will return an
- * error code; drivers must test for an error code after calling clk_register.
- */
 struct clk *clk_register(struct device *dev, struct clk_hw *hw);
 struct clk *devm_clk_register(struct device *dev, struct clk_hw *hw);
 
-- 
Sent by a computer through tubes