Clk documentation updates
Subsystems (2)
Stephen Boyd
maintainercover Clk documentation updates
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
Signature · 1 line
Sent by a computer through tubes
Stephen Boyd
maintainerPATCH 1/8 clk: Collapse gpio clk kerneldoc
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 <[email protected]>
--- include/linux/clk-provider.h | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-)
include/linux/clk-provider.h +8 -15
@@ -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,
Signature · 1 line
Sent by a computer through tubes
Stephen Boyd
maintainerPATCH 2/8 clk: Document deprecated things
In reply to Stephen BoydWe 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 <[email protected]>
--- drivers/clk/clk.c | 15 ++++++++++----- include/linux/clk-provider.h | 2 +- 2 files changed, 11 insertions(+), 6 deletions(-)
drivers/clk/clk.c +10 -5
@@ -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,
include/linux/clk-provider.h +1 -1
@@ -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 */
Signature · 1 line
Sent by a computer through tubes
Stephen Boyd
maintainerPATCH 3/8 clk: Document CLK_MUX_READ_ONLY mux flag
In reply to Stephen BoydThis flag isn't documented. Document it.
Signed-off-by Stephen Boyd <[email protected]>
--- include/linux/clk-provider.h | 2 ++ 1 file changed, 2 insertions(+)
include/linux/clk-provider.h +2 -0
@@ -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. */
Signature · 1 line
Sent by a computer through tubes
Stephen Boyd
maintainerPATCH 4/8 clk: Document __clk_mux_determine_rate()
In reply to Stephen BoydIt 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 <[email protected]>
--- drivers/clk/clk.c | 6 ++++++ 1 file changed, 6 insertions(+)
drivers/clk/clk.c +6 -0
@@ -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)
Signature · 1 line
Sent by a computer through tubes
Stephen Boyd
maintainerPATCH 5/8 clk: nxp: Drop 'flags' on fixed_rate clk macro
In reply to Stephen BoydThe 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 <[email protected]>
--- drivers/clk/nxp/clk-lpc32xx.c | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-)
drivers/clk/nxp/clk-lpc32xx.c +3 -4
@@ -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 :
Signature · 1 line
Sent by a computer through tubes
Stephen Boyd
maintainerPATCH 6/8 clk: Remove 'flags' member of struct clk_fixed_rate
In reply to Stephen BoydThis member is never used nor documented in the kerneldoc. Remove it.
Signed-off-by Stephen Boyd <[email protected]>
--- include/linux/clk-provider.h | 1 - 1 file changed, 1 deletion(-)
include/linux/clk-provider.h +0 -1
@@ -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)
Signature · 1 line
Sent by a computer through tubes
Stephen Boyd
maintainerPATCH 7/8 clk: Document and simplify clk_core_get_rate_nolock()
In reply to Stephen BoydThis 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 <[email protected]>
--- drivers/clk/clk.c | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-)
drivers/clk/clk.c +10 -15
@@ -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)
Signature · 1 line
Sent by a computer through tubes
Stephen Boyd
maintainerPATCH 8/8 clk: Drop duplicate clk_register() documentation
In reply to Stephen Boydclk_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 <[email protected]>
--- include/linux/clk-provider.h | 11 ----------- 1 file changed, 11 deletions(-)
include/linux/clk-provider.h +0 -11
@@ -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);
Signature · 1 line
Sent by a computer through tubes