[v2,3/4] clk: renesas: r9a06g032: document structs

Commit Message

Ralph Siemsen March 1, 2023, 9:55 p.m. UTC

Add some kerneldoc comments for the structures.

Signed-off-by: Ralph Siemsen <[e-mail]>
---

Changes in v2:
- tweak a few comments
- document remaining fields of clkdesc struct
- fix typo

 drivers/clk/renesas/r9a06g032-clocks.c | 50 +++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

Comments

Miquel Raynal March 2, 2023, 8:23 a.m. UTC | #1

Hi Ralph,

[e-mail] wrote on Wed,  1 Mar 2023 16:55:19 -0500:

> Add some kerneldoc comments for the structures.
> 
> Signed-off-by: Ralph Siemsen <[e-mail]>

Reviewed-by: Miquel Raynal <[e-mail]>

Thanks,
Miquèl

Geert Uytterhoeven March 10, 2023, 1:55 p.m. UTC | #2

On Wed, Mar 1, 2023 at 10:56 PM Ralph Siemsen <[e-mail]> wrote:
> Add some kerneldoc comments for the structures.
>
> Signed-off-by: Ralph Siemsen <[e-mail]>
> ---
>
> Changes in v2:
> - tweak a few comments
> - document remaining fields of clkdesc struct
> - fix typo

> --- a/drivers/clk/renesas/r9a06g032-clocks.c
> +++ b/drivers/clk/renesas/r9a06g032-clocks.c
> @@ -29,6 +29,27 @@
>  #define R9A06G032_SYSCTRL_USB_H2MODE  (1<<1)
>  #define R9A06G032_SYSCTRL_DMAMUX 0xA0
>
> +/**
> + * struct r9a06g032_gate - clock-related control bits
> + * @gate:   clock enable/disable
> + * @reset:  clock module reset (active low)
> + * @ready:  enables NoC forwarding of read/write requests to device,
> + *          (eg. device is ready to handle read/write requests)
> + * @midle:  request to idle the NoC interconnect
> + *
> + * Each of these fields describes a single bit in a register,
> + * which controls some aspect of clock gating. The @gate field
> + * is mandatory, this one enables/disables the clock. The
> + * other fields are optional, with zero indicating "not used".
> + *
> + * In most cases there is a @reset bit which needs to be
> + * de-asserted to bring the module out of reset.
> + *
> + * Modules may also need to signal when the are @ready to

they

> + * handle requests (read/writes) from the NoC interconnect.
> + *
> + * Similarly, the @midle bit is used to idle the master.
> + */

Reviewed-by: Geert Uytterhoeven <[e-mail]>
i.e. will queue in renesas-clk-for-v6.4, with the above fixed.

Gr{oetje,eeting}s,

                        Geert

Patch

diff --git a/drivers/clk/renesas/r9a06g032-clocks.c b/drivers/clk/renesas/r9a06g032-clocks.c
index 79b78e68c272..10c85e4417d5 100644
--- a/drivers/clk/renesas/r9a06g032-clocks.c
+++ b/drivers/clk/renesas/r9a06g032-clocks.c
@@ -29,6 +29,27 @@ 
 #define R9A06G032_SYSCTRL_USB_H2MODE  (1<<1)
 #define R9A06G032_SYSCTRL_DMAMUX 0xA0
 
+/**
+ * struct r9a06g032_gate - clock-related control bits
+ * @gate:   clock enable/disable
+ * @reset:  clock module reset (active low)
+ * @ready:  enables NoC forwarding of read/write requests to device,
+ *          (eg. device is ready to handle read/write requests)
+ * @midle:  request to idle the NoC interconnect
+ *
+ * Each of these fields describes a single bit in a register,
+ * which controls some aspect of clock gating. The @gate field
+ * is mandatory, this one enables/disables the clock. The
+ * other fields are optional, with zero indicating "not used".
+ *
+ * In most cases there is a @reset bit which needs to be
+ * de-asserted to bring the module out of reset.
+ *
+ * Modules may also need to signal when the are @ready to
+ * handle requests (read/writes) from the NoC interconnect.
+ *
+ * Similarly, the @midle bit is used to idle the master.
+ */
 struct r9a06g032_gate {
 	u16 gate, reset, ready, midle;
 	/* Unused fields omitted to save space */
@@ -43,7 +64,34 @@  enum gate_type {
 	K_DUALGATE	/* special for UARTs */
 };
 
-/* This is used to describe a clock for instantiation */
+/**
+ * struct r9a06g032_clkdesc - describe a single clock
+ * @name:      string describing this clock
+ * @managed:   boolean indicating if this clock should be
+ *             started/stopped as part of power management
+ * @type:      see enum @gate_type
+ * @index:     the ID of this clock element
+ * @source:    the ID+1 of the parent clock element.
+ *             Root clock uses ID of ~0 (PARENT_ID);
+ * @gate:      clock enable/disable
+ * @div_min:   smallest permitted clock divider
+ * @div_max:   largest permitted clock divider
+ * @reg:       clock divider register offset, in 32-bit words
+ * @div_table: optional list of fixed clock divider values;
+ *             must be in ascending order, zero for unused
+ * @div:       divisor for fixed-factor clock
+ * @mul:       multiplier for fixed-factor clock
+ * @group:     UART group, 0=UART0/1/2, 1=UART3/4/5/6/7
+ * @sel:       select either g1/r1 or g2/r2 as clock source
+ * @g1:        1st source gate (clock enable/disable)
+ * @r1:        1st source reset (module reset)
+ * @g2:        2nd source gate (clock enable/disable)
+ * @r2:        2nd source reset (module reset)
+ *
+ * Describes a single element in the clock tree hierarchy.
+ * As there are quite a large number of clock elements, this
+ * structure is packed tightly to conserve space.
+ */
 struct r9a06g032_clkdesc {
 	const char *name;
 	uint32_t managed:1;