[PATCH 1/2] clk: samsung: Fix kernel-doc comments

[PATCH 1/2] clk: samsung: Fix kernel-doc comments

[Sam Protsenko]

Fix some issues found in kernel-doc comments in Samsung CCF framework.
It makes scripts/kernel-doc happy, which can be checked with:

    $ find drivers/clk/samsung/ -name '*.[ch]' -exec \
      scripts/kernel-doc -v -none {} \;

Signed-off-by: Sam Protsenko <semen.protsenko@linaro.org>
Fixes: ddeac8d968d4 ("clk: samsung: add infrastructure to register cpu clocks")
Fixes: 721c42a351b1 ("clk: samsung: add common clock framework helper functions for Samsung platforms")
Fixes: 3ff6e0d8d64d ("clk: samsung: Add support to register rate_table for samsung plls")
---
 drivers/clk/samsung/clk-cpu.h | 2 +-
 drivers/clk/samsung/clk.h     | 9 ++++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/drivers/clk/samsung/clk-cpu.h b/drivers/clk/samsung/clk-cpu.h
index fc9f67a3b22e..103f64193e42 100644
--- a/drivers/clk/samsung/clk-cpu.h
+++ b/drivers/clk/samsung/clk-cpu.h
@@ -11,7 +11,7 @@
 #include "clk.h"
 
 /**
- * struct exynos_cpuclk_data: config data to setup cpu clocks.
+ * struct exynos_cpuclk_cfg_data: config data to setup cpu clocks.
  * @prate: frequency of the primary parent clock (in KHz).
  * @div0: value to be programmed in the div_cpu0 register.
  * @div1: value to be programmed in the div_cpu1 register.
diff --git a/drivers/clk/samsung/clk.h b/drivers/clk/samsung/clk.h
index ab9c3d7a25b3..4f17d5890a81 100644
--- a/drivers/clk/samsung/clk.h
+++ b/drivers/clk/samsung/clk.h
@@ -55,7 +55,7 @@ struct samsung_clock_alias {
  * @name: name of this fixed-rate clock.
  * @parent_name: optional parent clock name.
  * @flags: optional fixed-rate clock flags.
- * @fixed-rate: fixed clock rate of this clock.
+ * @fixed_rate: fixed clock rate of this clock.
  */
 struct samsung_fixed_rate_clock {
 	unsigned int		id;
@@ -74,7 +74,7 @@ struct samsung_fixed_rate_clock {
 		.fixed_rate	= frate,		\
 	}
 
-/*
+/**
  * struct samsung_fixed_factor_clock: information about fixed-factor clock
  * @id: platform specific id of the clock.
  * @name: name of this fixed-factor clock.
@@ -146,14 +146,16 @@ struct samsung_mux_clock {
 	__MUX(_id, cname, pnames, o, s, w, f, mf)
 
 /**
- * @id: platform specific id of the clock.
  * struct samsung_div_clock: information about div clock
+ * @id: platform specific id of the clock.
  * @name: name of this div clock.
  * @parent_name: name of the parent clock.
  * @flags: optional flags for basic clock.
  * @offset: offset of the register for configuring the div.
  * @shift: starting bit location of the div control bit-field in @reg.
+ * @width: width of the bitfield.
  * @div_flags: flags for div-type clock.
+ * @table: array of divider/value pairs ending with a div set to 0.
  */
 struct samsung_div_clock {
 	unsigned int		id;
@@ -244,6 +246,7 @@ struct samsung_clk_reg_dump {
  * @con_offset: offset of the register for configuring the PLL.
  * @lock_offset: offset of the register for locking the PLL.
  * @type: Type of PLL to be registered.
+ * @rate_table: array of PLL settings for possible PLL rates.
  */
 struct samsung_pll_clock {
 	unsigned int		id;
-- 
2.39.2

[PATCH 2/2] clk: samsung: Improve kernel-doc comments

[Sam Protsenko]

Unify and improve the style of kernel-doc comments in Samsung CCF
framework. Resemble more idiomatic style described in [1] and commonly
used throughout most of the kernel code.

[1] Documentation/doc-guide/kernel-doc.rst

Signed-off-by: Sam Protsenko <semen.protsenko@linaro.org>
---
 drivers/clk/samsung/clk-cpu.h |  30 +++----
 drivers/clk/samsung/clk.h     | 158 ++++++++++++++++++----------------
 2 files changed, 100 insertions(+), 88 deletions(-)

diff --git a/drivers/clk/samsung/clk-cpu.h b/drivers/clk/samsung/clk-cpu.h
index 103f64193e42..0164bd9ad021 100644
--- a/drivers/clk/samsung/clk-cpu.h
+++ b/drivers/clk/samsung/clk-cpu.h
@@ -11,10 +11,10 @@
 #include "clk.h"
 
 /**
- * struct exynos_cpuclk_cfg_data: config data to setup cpu clocks.
- * @prate: frequency of the primary parent clock (in KHz).
- * @div0: value to be programmed in the div_cpu0 register.
- * @div1: value to be programmed in the div_cpu1 register.
+ * struct exynos_cpuclk_cfg_data - config data to setup cpu clocks
+ * @prate: frequency of the primary parent clock (in KHz)
+ * @div0: value to be programmed in the div_cpu0 register
+ * @div1: value to be programmed in the div_cpu1 register
  *
  * This structure holds the divider configuration data for dividers in the CPU
  * clock domain. The parent frequency at which these divider values are valid is
@@ -29,17 +29,17 @@ struct exynos_cpuclk_cfg_data {
 };
 
 /**
- * struct exynos_cpuclk: information about clock supplied to a CPU core.
- * @hw:	handle between CCF and CPU clock.
- * @alt_parent: alternate parent clock to use when switching the speed
- *	of the primary parent clock.
- * @ctrl_base:	base address of the clock controller.
- * @lock: cpu clock domain register access lock.
- * @cfg: cpu clock rate configuration data.
- * @num_cfgs: number of array elements in @cfg array.
- * @clk_nb: clock notifier registered for changes in clock speed of the
- *	primary parent clock.
- * @flags: configuration flags for the CPU clock.
+ * struct exynos_cpuclk - information about clock supplied to a CPU core
+ * @hw:		handle between CCF and CPU clock
+ * @alt_parent:	alternate parent clock to use when switching the speed
+ *		of the primary parent clock
+ * @ctrl_base:	base address of the clock controller
+ * @lock:	cpu clock domain register access lock
+ * @cfg:	cpu clock rate configuration data
+ * @num_cfgs:	number of array elements in @cfg array
+ * @clk_nb:	clock notifier registered for changes in clock speed of the
+ *		primary parent clock
+ * @flags:	configuration flags for the CPU clock
  *
  * This structure holds information required for programming the CPU clock for
  * various clock speeds.
diff --git a/drivers/clk/samsung/clk.h b/drivers/clk/samsung/clk.h
index 4f17d5890a81..516b716407e5 100644
--- a/drivers/clk/samsung/clk.h
+++ b/drivers/clk/samsung/clk.h
@@ -14,11 +14,11 @@
 #include "clk-pll.h"
 
 /**
- * struct samsung_clk_provider: information about clock provider
- * @reg_base: virtual address for the register base.
- * @dev: clock provider device needed for runtime PM.
- * @lock: maintains exclusion between callbacks for a given clock-provider.
- * @clk_data: holds clock related data like clk_hw* and number of clocks.
+ * struct samsung_clk_provider - information about clock provider
+ * @reg_base: virtual address for the register base
+ * @dev: clock provider device needed for runtime PM
+ * @lock: maintains exclusion between callbacks for a given clock-provider
+ * @clk_data: holds clock related data like clk_hw* and number of clocks
  */
 struct samsung_clk_provider {
 	void __iomem *reg_base;
@@ -29,10 +29,10 @@ struct samsung_clk_provider {
 };
 
 /**
- * struct samsung_clock_alias: information about mux clock
- * @id: platform specific id of the clock.
- * @dev_name: name of the device to which this clock belongs.
- * @alias: optional clock alias name to be assigned to this clock.
+ * struct samsung_clock_alias - information about mux clock
+ * @id: platform specific id of the clock
+ * @dev_name: name of the device to which this clock belongs
+ * @alias: optional clock alias name to be assigned to this clock
  */
 struct samsung_clock_alias {
 	unsigned int		id;
@@ -50,12 +50,12 @@ struct samsung_clock_alias {
 #define MHZ (1000 * 1000)
 
 /**
- * struct samsung_fixed_rate_clock: information about fixed-rate clock
- * @id: platform specific id of the clock.
- * @name: name of this fixed-rate clock.
- * @parent_name: optional parent clock name.
- * @flags: optional fixed-rate clock flags.
- * @fixed_rate: fixed clock rate of this clock.
+ * struct samsung_fixed_rate_clock - information about fixed-rate clock
+ * @id: platform specific id of the clock
+ * @name: name of this fixed-rate clock
+ * @parent_name: optional parent clock name
+ * @flags: optional fixed-rate clock flags
+ * @fixed_rate: fixed clock rate of this clock
  */
 struct samsung_fixed_rate_clock {
 	unsigned int		id;
@@ -75,13 +75,13 @@ struct samsung_fixed_rate_clock {
 	}
 
 /**
- * struct samsung_fixed_factor_clock: information about fixed-factor clock
- * @id: platform specific id of the clock.
- * @name: name of this fixed-factor clock.
- * @parent_name: parent clock name.
- * @mult: fixed multiplication factor.
- * @div: fixed division factor.
- * @flags: optional fixed-factor clock flags.
+ * struct samsung_fixed_factor_clock - information about fixed-factor clock
+ * @id: platform specific id of the clock
+ * @name: name of this fixed-factor clock
+ * @parent_name: parent clock name
+ * @mult: fixed multiplication factor
+ * @div: fixed division factor
+ * @flags: optional fixed-factor clock flags
  */
 struct samsung_fixed_factor_clock {
 	unsigned int		id;
@@ -103,16 +103,16 @@ struct samsung_fixed_factor_clock {
 	}
 
 /**
- * struct samsung_mux_clock: information about mux clock
- * @id: platform specific id of the clock.
- * @name: name of this mux clock.
- * @parent_names: array of pointer to parent clock names.
- * @num_parents: number of parents listed in @parent_names.
- * @flags: optional flags for basic clock.
- * @offset: offset of the register for configuring the mux.
- * @shift: starting bit location of the mux control bit-field in @reg.
- * @width: width of the mux control bit-field in @reg.
- * @mux_flags: flags for mux-type clock.
+ * struct samsung_mux_clock - information about mux clock
+ * @id: platform specific id of the clock
+ * @name: name of this mux clock
+ * @parent_names: array of pointer to parent clock names
+ * @num_parents: number of parents listed in @parent_names
+ * @flags: optional flags for basic clock
+ * @offset: offset of the register for configuring the mux
+ * @shift: starting bit location of the mux control bit-field in @reg
+ * @width: width of the mux control bit-field in @reg
+ * @mux_flags: flags for mux-type clock
  */
 struct samsung_mux_clock {
 	unsigned int		id;
@@ -146,16 +146,16 @@ struct samsung_mux_clock {
 	__MUX(_id, cname, pnames, o, s, w, f, mf)
 
 /**
- * struct samsung_div_clock: information about div clock
- * @id: platform specific id of the clock.
- * @name: name of this div clock.
- * @parent_name: name of the parent clock.
- * @flags: optional flags for basic clock.
- * @offset: offset of the register for configuring the div.
- * @shift: starting bit location of the div control bit-field in @reg.
- * @width: width of the bitfield.
- * @div_flags: flags for div-type clock.
- * @table: array of divider/value pairs ending with a div set to 0.
+ * struct samsung_div_clock - information about div clock
+ * @id: platform specific id of the clock
+ * @name: name of this div clock
+ * @parent_name: name of the parent clock
+ * @flags: optional flags for basic clock
+ * @offset: offset of the register for configuring the div
+ * @shift: starting bit location of the div control bit-field in @reg
+ * @width: width of the bitfield
+ * @div_flags: flags for div-type clock
+ * @table: array of divider/value pairs ending with a div set to 0
  */
 struct samsung_div_clock {
 	unsigned int		id;
@@ -192,14 +192,14 @@ struct samsung_div_clock {
 	__DIV(_id, cname, pname, o, s, w, 0, 0, t)
 
 /**
- * struct samsung_gate_clock: information about gate clock
- * @id: platform specific id of the clock.
- * @name: name of this gate clock.
- * @parent_name: name of the parent clock.
- * @flags: optional flags for basic clock.
- * @offset: offset of the register for configuring the gate.
- * @bit_idx: bit index of the gate control bit-field in @reg.
- * @gate_flags: flags for gate-type clock.
+ * struct samsung_gate_clock - information about gate clock
+ * @id: platform specific id of the clock
+ * @name: name of this gate clock
+ * @parent_name: name of the parent clock
+ * @flags: optional flags for basic clock
+ * @offset: offset of the register for configuring the gate
+ * @bit_idx: bit index of the gate control bit-field in @reg
+ * @gate_flags: flags for gate-type clock
  */
 struct samsung_gate_clock {
 	unsigned int		id;
@@ -228,9 +228,9 @@ struct samsung_gate_clock {
 #define PNAME(x) static const char * const x[] __initconst
 
 /**
- * struct samsung_clk_reg_dump: register dump of clock controller registers.
- * @offset: clock register offset from the controller base address.
- * @value: the value to be register at offset.
+ * struct samsung_clk_reg_dump - register dump of clock controller registers
+ * @offset: clock register offset from the controller base address
+ * @value: the value to be register at offset
  */
 struct samsung_clk_reg_dump {
 	u32	offset;
@@ -238,15 +238,15 @@ struct samsung_clk_reg_dump {
 };
 
 /**
- * struct samsung_pll_clock: information about pll clock
- * @id: platform specific id of the clock.
- * @name: name of this pll clock.
- * @parent_name: name of the parent clock.
- * @flags: optional flags for basic clock.
- * @con_offset: offset of the register for configuring the PLL.
- * @lock_offset: offset of the register for locking the PLL.
- * @type: Type of PLL to be registered.
- * @rate_table: array of PLL settings for possible PLL rates.
+ * struct samsung_pll_clock - information about pll clock
+ * @id: platform specific id of the clock
+ * @name: name of this pll clock
+ * @parent_name: name of the parent clock
+ * @flags: optional flags for basic clock
+ * @con_offset: offset of the register for configuring the PLL
+ * @lock_offset: offset of the register for locking the PLL
+ * @type: type of PLL to be registered
+ * @rate_table: array of PLL settings for possible PLL rates
  */
 struct samsung_pll_clock {
 	unsigned int		id;
@@ -305,39 +305,51 @@ struct samsung_clock_reg_cache {
 	unsigned int rsuspend_num;
 };
 
+/**
+ * struct samsung_cmu_info - all clocks information needed for CMU registration
+ * @pll_clks: list of PLL clocks
+ * @nr_pll_clks: count of clocks in @pll_clks
+ * @mux_clks: list of mux clocks
+ * @nr_mux_clks: count of clocks in @mux_clks
+ * @div_clks: list of div clocks
+ * @nr_div_clks: count of clocks in @div_clks
+ * @gate_clks: list of gate clocks
+ * @nr_gate_clks: count of clocks in @gate_clks
+ * @fixed_clks: list of fixed clocks
+ * @nr_fixed_clks: count clocks in @fixed_clks
+ * @fixed_factor_clks: list of fixed factor clocks
+ * @nr_fixed_factor_clks: count of clocks in @fixed_factor_clks
+ * @nr_clk_ids: total number of clocks with IDs assigned
+ * @cpu_clks: list of CPU clocks
+ * @nr_cpu_clks: count of clocks in @cpu_clks
+ * @clk_regs: list of clock registers
+ * @nr_clk_regs: count of clock registers in @clk_regs
+ * @suspend_regs: list of clock registers to set before suspend
+ * @nr_suspend_regs: count of clock registers in @suspend_regs
+ * @clk_name: name of the parent clock needed for CMU register access
+ */
 struct samsung_cmu_info {
-	/* list of pll clocks and respective count */
 	const struct samsung_pll_clock *pll_clks;
 	unsigned int nr_pll_clks;
-	/* list of mux clocks and respective count */
 	const struct samsung_mux_clock *mux_clks;
 	unsigned int nr_mux_clks;
-	/* list of div clocks and respective count */
 	const struct samsung_div_clock *div_clks;
 	unsigned int nr_div_clks;
-	/* list of gate clocks and respective count */
 	const struct samsung_gate_clock *gate_clks;
 	unsigned int nr_gate_clks;
-	/* list of fixed clocks and respective count */
 	const struct samsung_fixed_rate_clock *fixed_clks;
 	unsigned int nr_fixed_clks;
-	/* list of fixed factor clocks and respective count */
 	const struct samsung_fixed_factor_clock *fixed_factor_clks;
 	unsigned int nr_fixed_factor_clks;
-	/* total number of clocks with IDs assigned*/
 	unsigned int nr_clk_ids;
-	/* list of cpu clocks and respective count */
 	const struct samsung_cpu_clock *cpu_clks;
 	unsigned int nr_cpu_clks;
 
-	/* list and number of clocks registers */
 	const unsigned long *clk_regs;
 	unsigned int nr_clk_regs;
 
-	/* list and number of clocks registers to set before suspend */
 	const struct samsung_clk_reg_dump *suspend_regs;
 	unsigned int nr_suspend_regs;
-	/* name of the parent clock needed for CMU register access */
 	const char *clk_name;
 };
 
-- 
2.39.2

Re: [PATCH 1/2] clk: samsung: Fix kernel-doc comments

[Randy Dunlap]

On 11/9/23 11:09, Sam Protsenko wrote:
> Fix some issues found in kernel-doc comments in Samsung CCF framework.
> It makes scripts/kernel-doc happy, which can be checked with:
> 
>     $ find drivers/clk/samsung/ -name '*.[ch]' -exec \
>       scripts/kernel-doc -v -none {} \;
> 
> Signed-off-by: Sam Protsenko <semen.protsenko@linaro.org>
> Fixes: ddeac8d968d4 ("clk: samsung: add infrastructure to register cpu clocks")
> Fixes: 721c42a351b1 ("clk: samsung: add common clock framework helper functions for Samsung platforms")
> Fixes: 3ff6e0d8d64d ("clk: samsung: Add support to register rate_table for samsung plls")
> ---
>  drivers/clk/samsung/clk-cpu.h | 2 +-
>  drivers/clk/samsung/clk.h     | 9 ++++++---
>  2 files changed, 7 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/clk/samsung/clk-cpu.h b/drivers/clk/samsung/clk-cpu.h
> index fc9f67a3b22e..103f64193e42 100644
> --- a/drivers/clk/samsung/clk-cpu.h
> +++ b/drivers/clk/samsung/clk-cpu.h
> @@ -11,7 +11,7 @@
>  #include "clk.h"
>  
>  /**
> - * struct exynos_cpuclk_data: config data to setup cpu clocks.
> + * struct exynos_cpuclk_cfg_data: config data to setup cpu clocks.

Hm, OK, the ':' separator works. '-' is the documented separator here,
but it's not worth updating the patch for that.

>   * @prate: frequency of the primary parent clock (in KHz).
>   * @div0: value to be programmed in the div_cpu0 register.
>   * @div1: value to be programmed in the div_cpu1 register.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

thanks.

-- 
~Randy

Re: [PATCH 2/2] clk: samsung: Improve kernel-doc comments

[Randy Dunlap]

On 11/9/23 11:09, Sam Protsenko wrote:
> Unify and improve the style of kernel-doc comments in Samsung CCF
> framework. Resemble more idiomatic style described in [1] and commonly
> used throughout most of the kernel code.
> 
> [1] Documentation/doc-guide/kernel-doc.rst
> 
> Signed-off-by: Sam Protsenko <semen.protsenko@linaro.org>
> ---
>  drivers/clk/samsung/clk-cpu.h |  30 +++----
>  drivers/clk/samsung/clk.h     | 158 ++++++++++++++++++----------------
>  2 files changed, 100 insertions(+), 88 deletions(-)
> 

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

thanks.

-- 
~Randy

Re: [PATCH 1/2] clk: samsung: Fix kernel-doc comments

[Sam Protsenko]

On Thu, Nov 9, 2023 at 4:42 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
>
> On 11/9/23 11:09, Sam Protsenko wrote:
> > Fix some issues found in kernel-doc comments in Samsung CCF framework.
> > It makes scripts/kernel-doc happy, which can be checked with:
> >
> >     $ find drivers/clk/samsung/ -name '*.[ch]' -exec \
> >       scripts/kernel-doc -v -none {} \;
> >
> > Signed-off-by: Sam Protsenko <semen.protsenko@linaro.org>
> > Fixes: ddeac8d968d4 ("clk: samsung: add infrastructure to register cpu clocks")
> > Fixes: 721c42a351b1 ("clk: samsung: add common clock framework helper functions for Samsung platforms")
> > Fixes: 3ff6e0d8d64d ("clk: samsung: Add support to register rate_table for samsung plls")
> > ---
> >  drivers/clk/samsung/clk-cpu.h | 2 +-
> >  drivers/clk/samsung/clk.h     | 9 ++++++---
> >  2 files changed, 7 insertions(+), 4 deletions(-)
> >
> > diff --git a/drivers/clk/samsung/clk-cpu.h b/drivers/clk/samsung/clk-cpu.h
> > index fc9f67a3b22e..103f64193e42 100644
> > --- a/drivers/clk/samsung/clk-cpu.h
> > +++ b/drivers/clk/samsung/clk-cpu.h
> > @@ -11,7 +11,7 @@
> >  #include "clk.h"
> >
> >  /**
> > - * struct exynos_cpuclk_data: config data to setup cpu clocks.
> > + * struct exynos_cpuclk_cfg_data: config data to setup cpu clocks.
>
> Hm, OK, the ':' separator works. '-' is the documented separator here,
> but it's not worth updating the patch for that.
>

Thanks for reviewing, Randy! As you probably already noticed, I
updated ':' bits in patch #2. Just wanted to keep this one as minimal
as possible.

> >   * @prate: frequency of the primary parent clock (in KHz).
> >   * @div0: value to be programmed in the div_cpu0 register.
> >   * @div1: value to be programmed in the div_cpu1 register.
>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>
> thanks.
>
> --
> ~Randy

Re: [PATCH 1/2] clk: samsung: Fix kernel-doc comments

[Krzysztof Kozlowski]

On Thu, 09 Nov 2023 13:09:24 -0600, Sam Protsenko wrote:
> Fix some issues found in kernel-doc comments in Samsung CCF framework.
> It makes scripts/kernel-doc happy, which can be checked with:
> 
>     $ find drivers/clk/samsung/ -name '*.[ch]' -exec \
>       scripts/kernel-doc -v -none {} \;
> 
> 
> [...]

Applied, thanks!

[1/2] clk: samsung: Fix kernel-doc comments
      https://git.kernel.org/krzk/linux/c/d1d53909bb5fbc9bf618ab78515fdbd5d6b691c6
[2/2] clk: samsung: Improve kernel-doc comments
      https://git.kernel.org/krzk/linux/c/5583e92be5c45448e6ea461e1780d46c17d14963

Best regards,
-- 
Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>