[PATCH 6/8] clk: mediatek: clarify mapped vs. unmapped ID

[David Lechner]

Update documentation comments to clarify the difference between which
.id fields are mapped (only struct clk.id) vs. unmapped (all struct
mtk_*.id and .parent fields). The unmapped IDs are the ones defined
in the devicetree bindings, while the mapped IDs are the ones used as
the index into the various clk arrays.

Also fix spelling of "parent" while we are touching this.

Signed-off-by: David Lechner <dlechner at baylibre.com>
---
This applies on top of [1] which removed a duplicate @parent doc line.

[1]: https://patchwork.ozlabs.org/project/uboot/patch/20251211-clk-mtk-fix-dup-parent-doc-v1-1-41816d98f857@baylibre.com/
---
 drivers/clk/mediatek/clk-mtk.h | 34 +++++++++++++++++++---------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/drivers/clk/mediatek/clk-mtk.h b/drivers/clk/mediatek/clk-mtk.h
index 980d9aab809..915b872ec36 100644
--- a/drivers/clk/mediatek/clk-mtk.h
+++ b/drivers/clk/mediatek/clk-mtk.h
@@ -50,6 +50,7 @@
 
 /* struct mtk_pll_data - hardware-specific PLLs data */
 struct mtk_pll_data {
+	/* unmapped ID of clock */
 	const int id;
 	u32 reg;
 	u32 pwr_reg;
@@ -70,8 +71,8 @@ struct mtk_pll_data {
 /**
  * struct mtk_fixed_clk - fixed clocks
  *
- * @id:		index of clocks
- * @parent:	index of parnet clocks
+ * @id:		unmapped ID of clock
+ * @parent:	unmapped ID of parent clock
  * @rate:	fixed rate
  */
 struct mtk_fixed_clk {
@@ -89,8 +90,8 @@ struct mtk_fixed_clk {
 /**
  * struct mtk_fixed_factor - fixed multiplier and divider clocks
  *
- * @id:		index of clocks
- * @parent:	index of parnet clocks
+ * @id:		unmapped ID of clock
+ * @parent:	unmapped ID of parent clock
  * @mult:	multiplier
  * @div:	divider
  * @flag:	hardware-specific flags
@@ -115,7 +116,7 @@ struct mtk_fixed_factor {
  * struct mtk_parent -  clock parent with flags. Needed for MUX that
  *			parent with mixed infracfg and topckgen.
  *
- * @id:			index of parent clocks
+ * @id:			unmapped ID of parent clocks
  * @flags:		hardware-specific flags (parent location,
  *			infracfg, topckgen, APMIXED, xtal ...)
  */
@@ -132,8 +133,8 @@ struct mtk_parent {
 /**
  * struct mtk_composite - aggregate clock of mux, divider and gate clocks
  *
- * @id:			index of clocks
- * @parent:		index of parent clocks
+ * @id:			unmapped ID of clocks
+ * @parent:		unmapped ID of parent clocks
  * @parent_flags:	table of parent clocks with flags
  * @mux_reg:		hardware-specific mux register
  * @gate_reg:		hardware-specific gate register
@@ -231,8 +232,8 @@ struct mtk_gate_regs {
 /**
  * struct mtk_gate - gate clocks
  *
- * @id:		index of gate clocks
- * @parent:	index of parnet clocks
+ * @id:		unmapped ID of gate clocks
+ * @parent:	unmapped ID of parent clocks
  * @regs:	hardware-specific mux register
  * @shift:	shift to the gate bit field
  * @flags:	hardware-specific flags
@@ -250,13 +251,16 @@ struct mtk_clk_tree {
 	unsigned long xtal_rate;
 	unsigned long xtal2_rate;
 	/*
-	 * Clock ID offset are remapped with an auxiliary table.
-	 * Enable this by defining .id_offs_map.
-	 * This is needed for upstream linux kernel <soc>-clk.h that
-	 * have mixed clk ID and doesn't have clear distinction between
-	 * ID for factor, mux and gates.
+	 * Clock IDs may be remapped with an auxiliary table. Enable this by
+	 * defining .id_offs_map and .id_offs_map_size. This is needed e.g. when
+	 * the upstream Linux kernel <soc>-clk.h has mixed clk IDs and doesn't
+	 * have clear distinction between ID for factor, mux and gates. When
+	 * this is enabled, the struct clk->id will contained the mapped ID that
+	 * is the index in the various arrays in this struct. The .id and
+	 * .parent fields in the various mtk_* structs will contain the
+	 * unmapped IDs as defined in the upstream Linux kernel <soc>-clk.h.
 	 */
-	const int *id_offs_map; /* optional, table clk.h to driver ID */
+	const int *id_offs_map; /* optional, maps clk.h ID to array index */
 	const int id_offs_map_size;
 	const int fdivs_offs;
 	const int muxes_offs;

-- 
2.43.0