Document the clock controller shipped in Loongson 2K0300 SoC, which
generates various clock signals for SoC peripherals.
Signed-off-by: Yao Zi <ziyao@disroot.org>
---
.../bindings/clock/loongson,ls2k0300-clk.yaml | 52 ++++++++++++++++++
.../dt-bindings/clock/loongson,ls2k0300-clk.h | 54 +++++++++++++++++++
2 files changed, 106 insertions(+)
create mode 100644 Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml
create mode 100644 include/dt-bindings/clock/loongson,ls2k0300-clk.h
diff --git a/Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml b/Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml
new file mode 100644
index 000000000000..d96b9d7cb7c4
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/loongson,ls2k0300-clk.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Loongson-2K0300 SoC Clock Controller
+
+maintainers:
+ - Yao Zi <ziyao@disroot.org>
+
+description: |
+ The Loongson 2K0300 clock controller generates various clocks for SoC
+ peripherals. See include/dt-bindings/clock/loongson,ls2k0300-clk.h for
+ valid clock IDs.
+
+properties:
+ compatible:
+ const: loongson,ls2k0300-clk
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: External 120MHz reference clock
+
+ clock-names:
+ items:
+ - const: ref_120m
+
+ '#clock-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - '#clock-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ clk: clock-controller@16000400 {
+ compatible = "loongson,ls2k0300-clk";
+ reg = <0x16000400 0x100>;
+ clocks = <&ref_120m>;
+ clock-names = "ref_120m";
+ #clock-cells = <1>;
+ };
diff --git a/include/dt-bindings/clock/loongson,ls2k0300-clk.h b/include/dt-bindings/clock/loongson,ls2k0300-clk.h
new file mode 100644
index 000000000000..5e8f7b2f33f2
--- /dev/null
+++ b/include/dt-bindings/clock/loongson,ls2k0300-clk.h
@@ -0,0 +1,54 @@
+/* SPDX-License-Identifier: (GPL-2.0-only OR MIT) */
+/*
+ * Copyright (C) 2025 Yao Zi <ziyao@disroot.org>
+ */
+#ifndef _DT_BINDINGS_CLK_LOONGSON_LS2K300_H_
+#define _DT_BINDINGS_CLK_LOONGSON_LS2K300_H_
+
+/* Derivied from REFCLK */
+#define LS2K0300_CLK_STABLE 0
+#define LS2K0300_PLL_NODE 1
+#define LS2K0300_PLL_DDR 2
+#define LS2K0300_PLL_PIX 3
+#define LS2K0300_CLK_THSENS 4
+
+/* Derived from PLL_NODE */
+#define LS2K0300_CLK_NODE_DIV 5
+#define LS2K0300_CLK_NODE_PLL_GATE 6
+#define LS2K0300_CLK_NODE_SCALE 7
+#define LS2K0300_CLK_NODE_GATE 8
+#define LS2K0300_CLK_GMAC_DIV 9
+#define LS2K0300_CLK_GMAC_GATE 10
+#define LS2K0300_CLK_I2S_DIV 11
+#define LS2K0300_CLK_I2S_SCALE 12
+#define LS2K0300_CLK_I2S_GATE 13
+
+/* Derived from PLL_DDR */
+#define LS2K0300_CLK_DDR_DIV 14
+#define LS2K0300_CLK_DDR_GATE 15
+#define LS2K0300_CLK_NET_DIV 16
+#define LS2K0300_CLK_NET_GATE 17
+#define LS2K0300_CLK_DEV_DIV 18
+#define LS2K0300_CLK_DEV_GATE 19
+
+/* Derived from PLL_PIX */
+#define LS2K0300_CLK_PIX_DIV 20
+#define LS2K0300_CLK_PIX_PLL_GATE 21
+#define LS2K0300_CLK_PIX_SCALE 22
+#define LS2K0300_CLK_PIX_GATE 23
+#define LS2K0300_CLK_GMACBP_DIV 24
+#define LS2K0300_CLK_GMACBP_GATE 25
+
+/* Derived from CLK_DEV */
+#define LS2K0300_CLK_USB_SCALE 26
+#define LS2K0300_CLK_USB_GATE 27
+#define LS2K0300_CLK_APB_SCALE 28
+#define LS2K0300_CLK_APB_GATE 29
+#define LS2K0300_CLK_BOOT_SCALE 30
+#define LS2K0300_CLK_BOOT_GATE 31
+#define LS2K0300_CLK_SDIO_SCALE 32
+#define LS2K0300_CLK_SDIO_GATE 33
+
+#define LS2K0300_CLK_GMAC_IN 34
+
+#endif // _DT_BINDINGS_CLK_LOONGSON_LS2K300_H_
--
2.49.0On Fri, May 23, 2025 at 6:46 PM Yao Zi <ziyao@disroot.org> wrote:
>
> Document the clock controller shipped in Loongson 2K0300 SoC, which
> generates various clock signals for SoC peripherals.
>
> Signed-off-by: Yao Zi <ziyao@disroot.org>
> ---
> .../bindings/clock/loongson,ls2k0300-clk.yaml | 52 ++++++++++++++++++
> .../dt-bindings/clock/loongson,ls2k0300-clk.h | 54 +++++++++++++++++++
> 2 files changed, 106 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml
I don't think a new binding file for 2K0300 is needed. Adding
compatible entries to loongson,ls2k-clk.yaml would be more appropriate
as they are almost all similar.
> create mode 100644 include/dt-bindings/clock/loongson,ls2k0300-clk.h
>
> diff --git a/Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml b/Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml
> new file mode 100644
> index 000000000000..d96b9d7cb7c4
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml
> @@ -0,0 +1,52 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/loongson,ls2k0300-clk.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Loongson-2K0300 SoC Clock Controller
> +
> +maintainers:
> + - Yao Zi <ziyao@disroot.org>
> +
> +description: |
> + The Loongson 2K0300 clock controller generates various clocks for SoC
> + peripherals. See include/dt-bindings/clock/loongson,ls2k0300-clk.h for
> + valid clock IDs.
> +
> +properties:
> + compatible:
> + const: loongson,ls2k0300-clk
> +
> + reg:
> + maxItems: 1
> +
> + clocks:
> + items:
> + - description: External 120MHz reference clock
> +
> + clock-names:
> + items:
> + - const: ref_120m
> +
> + '#clock-cells':
> + const: 1
> +
> +required:
> + - compatible
> + - reg
> + - clocks
> + - clock-names
> + - '#clock-cells'
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + clk: clock-controller@16000400 {
> + compatible = "loongson,ls2k0300-clk";
> + reg = <0x16000400 0x100>;
> + clocks = <&ref_120m>;
> + clock-names = "ref_120m";
> + #clock-cells = <1>;
> + };
> diff --git a/include/dt-bindings/clock/loongson,ls2k0300-clk.h b/include/dt-bindings/clock/loongson,ls2k0300-clk.h
> new file mode 100644
> index 000000000000..5e8f7b2f33f2
> --- /dev/null
> +++ b/include/dt-bindings/clock/loongson,ls2k0300-clk.h
> @@ -0,0 +1,54 @@
> +/* SPDX-License-Identifier: (GPL-2.0-only OR MIT) */
> +/*
> + * Copyright (C) 2025 Yao Zi <ziyao@disroot.org>
> + */
> +#ifndef _DT_BINDINGS_CLK_LOONGSON_LS2K300_H_
> +#define _DT_BINDINGS_CLK_LOONGSON_LS2K300_H_
> +
> +/* Derivied from REFCLK */
> +#define LS2K0300_CLK_STABLE 0
> +#define LS2K0300_PLL_NODE 1
> +#define LS2K0300_PLL_DDR 2
> +#define LS2K0300_PLL_PIX 3
> +#define LS2K0300_CLK_THSENS 4
> +
> +/* Derived from PLL_NODE */
> +#define LS2K0300_CLK_NODE_DIV 5
> +#define LS2K0300_CLK_NODE_PLL_GATE 6
> +#define LS2K0300_CLK_NODE_SCALE 7
> +#define LS2K0300_CLK_NODE_GATE 8
> +#define LS2K0300_CLK_GMAC_DIV 9
> +#define LS2K0300_CLK_GMAC_GATE 10
> +#define LS2K0300_CLK_I2S_DIV 11
> +#define LS2K0300_CLK_I2S_SCALE 12
> +#define LS2K0300_CLK_I2S_GATE 13
> +
> +/* Derived from PLL_DDR */
> +#define LS2K0300_CLK_DDR_DIV 14
> +#define LS2K0300_CLK_DDR_GATE 15
> +#define LS2K0300_CLK_NET_DIV 16
> +#define LS2K0300_CLK_NET_GATE 17
> +#define LS2K0300_CLK_DEV_DIV 18
> +#define LS2K0300_CLK_DEV_GATE 19
> +
> +/* Derived from PLL_PIX */
> +#define LS2K0300_CLK_PIX_DIV 20
> +#define LS2K0300_CLK_PIX_PLL_GATE 21
> +#define LS2K0300_CLK_PIX_SCALE 22
> +#define LS2K0300_CLK_PIX_GATE 23
> +#define LS2K0300_CLK_GMACBP_DIV 24
> +#define LS2K0300_CLK_GMACBP_GATE 25
> +
> +/* Derived from CLK_DEV */
> +#define LS2K0300_CLK_USB_SCALE 26
> +#define LS2K0300_CLK_USB_GATE 27
> +#define LS2K0300_CLK_APB_SCALE 28
> +#define LS2K0300_CLK_APB_GATE 29
> +#define LS2K0300_CLK_BOOT_SCALE 30
> +#define LS2K0300_CLK_BOOT_GATE 31
> +#define LS2K0300_CLK_SDIO_SCALE 32
> +#define LS2K0300_CLK_SDIO_GATE 33
> +
> +#define LS2K0300_CLK_GMAC_IN 34
> +
> +#endif // _DT_BINDINGS_CLK_LOONGSON_LS2K300_H_
> --
> 2.49.0
>
>
--
Thanks.
Binbin
在 5/23/25 8:30 PM, Binbin Zhou 写道: > On Fri, May 23, 2025 at 6:46 PM Yao Zi <ziyao@disroot.org> wrote: >> >> Document the clock controller shipped in Loongson 2K0300 SoC, which >> generates various clock signals for SoC peripherals. >> >> Signed-off-by: Yao Zi <ziyao@disroot.org> >> --- >> .../bindings/clock/loongson,ls2k0300-clk.yaml | 52 ++++++++++++++++++ >> .../dt-bindings/clock/loongson,ls2k0300-clk.h | 54 +++++++++++++++++++ >> 2 files changed, 106 insertions(+) >> create mode 100644 Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml > > I don't think a new binding file for 2K0300 is needed. Adding > compatible entries to loongson,ls2k-clk.yaml would be more appropriate > as they are almost all similar. > Same here! Thanks, Yanteng
On Fri, May 23, 2025 at 08:30:57PM +0800, Binbin Zhou wrote:
> On Fri, May 23, 2025 at 6:46 PM Yao Zi <ziyao@disroot.org> wrote:
> >
> > Document the clock controller shipped in Loongson 2K0300 SoC, which
> > generates various clock signals for SoC peripherals.
> >
> > Signed-off-by: Yao Zi <ziyao@disroot.org>
> > ---
> > .../bindings/clock/loongson,ls2k0300-clk.yaml | 52 ++++++++++++++++++
> > .../dt-bindings/clock/loongson,ls2k0300-clk.h | 54 +++++++++++++++++++
> > 2 files changed, 106 insertions(+)
> > create mode 100644 Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml
>
> I don't think a new binding file for 2K0300 is needed. Adding
> compatible entries to loongson,ls2k-clk.yaml would be more appropriate
> as they are almost all similar.
Originally I've tried to integrate the 2K0300 stuff with
loongson,ls2k-clk.yaml, but found it's hard to describe some properties.
For example, currently in loongson,ls2k-clk.yaml, the clocks property is
described as
clocks:
items:
- description: 100m ref
what should the description look like with 2K0300 introduced, whose
reference clock runs at 120MHz instead of 100MHz? It'll be hard to
describe things correctly without losing existing information. "120MHz
reference clock for Loongson 2K0300, or 100MHz reference clock for other
SoCs" sounds even a worse idea.
Another example is about the description of clock IDs. loongson,ls2k-clk.yaml
describes available clock IDs as
'#clock-cells':
const: 1
description:
The clock consumer should specify the desired clock by having the clock
ID in its "clocks" phandle cell. See include/dt-bindings/clock/loongson,ls2k-clk.h
for the full list of Loongson-2 SoC clock IDs.
what should the description look like if we add 2K0300 support? With a
different header being introduced, the description will be messy.
I think keeping SoCs peripherals that are different in hardware design
in the same binding is really a bad idea. Yes, these clock controllers
are similar enough to reuse the clock hardware driver, but they have
different clock tree structures and register definitions, making them
essentially different things. Trying to keep everything in the same
place only makes the binding messy.
For the reason to introduce a new binding header: loongson,ls2k-clk.h
contains clocks that aren't present in 2K0300 and misses IDs for ones
present. It's just messy if we mix everything in the same place, so here
comes loongson,ls2k0300-clk.h.
Thanks,
Yao Zi
On 23/05/2025 15:28, Yao Zi wrote: > On Fri, May 23, 2025 at 08:30:57PM +0800, Binbin Zhou wrote: >> On Fri, May 23, 2025 at 6:46 PM Yao Zi <ziyao@disroot.org> wrote: >>> >>> Document the clock controller shipped in Loongson 2K0300 SoC, which >>> generates various clock signals for SoC peripherals. >>> >>> Signed-off-by: Yao Zi <ziyao@disroot.org> >>> --- >>> .../bindings/clock/loongson,ls2k0300-clk.yaml | 52 ++++++++++++++++++ >>> .../dt-bindings/clock/loongson,ls2k0300-clk.h | 54 +++++++++++++++++++ >>> 2 files changed, 106 insertions(+) >>> create mode 100644 Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml >> >> I don't think a new binding file for 2K0300 is needed. Adding >> compatible entries to loongson,ls2k-clk.yaml would be more appropriate >> as they are almost all similar. > > Originally I've tried to integrate the 2K0300 stuff with > loongson,ls2k-clk.yaml, but found it's hard to describe some properties. > > For example, currently in loongson,ls2k-clk.yaml, the clocks property is > described as > > clocks: > items: > - description: 100m ref > > what should the description look like with 2K0300 introduced, whose > reference clock runs at 120MHz instead of 100MHz? It'll be hard to > describe things correctly without losing existing information. "120MHz > reference clock for Loongson 2K0300, or 100MHz reference clock for other > SoCs" sounds even a worse idea. Drop the frequency anyway, it is kind of pointless here. > > Another example is about the description of clock IDs. loongson,ls2k-clk.yaml > describes available clock IDs as > > '#clock-cells': > const: 1 > description: > The clock consumer should specify the desired clock by having the clock > ID in its "clocks" phandle cell. See include/dt-bindings/clock/loongson,ls2k-clk.h > for the full list of Loongson-2 SoC clock IDs. > > what should the description look like if we add 2K0300 support? With a > different header being introduced, the description will be messy. No, just list the headers. > > I think keeping SoCs peripherals that are different in hardware design > in the same binding is really a bad idea. Yes, these clock controllers > are similar enough to reuse the clock hardware driver, but they have > different clock tree structures and register definitions, making them > essentially different things. Trying to keep everything in the same > place only makes the binding messy. How is binding messy if you only add one compatible? Best regards, Krzysztof
On Mon, May 26, 2025 at 06:11:22AM +0200, Krzysztof Kozlowski wrote: > On 23/05/2025 15:28, Yao Zi wrote: > > On Fri, May 23, 2025 at 08:30:57PM +0800, Binbin Zhou wrote: > >> On Fri, May 23, 2025 at 6:46 PM Yao Zi <ziyao@disroot.org> wrote: > >>> > >>> Document the clock controller shipped in Loongson 2K0300 SoC, which > >>> generates various clock signals for SoC peripherals. > >>> > >>> Signed-off-by: Yao Zi <ziyao@disroot.org> > >>> --- > >>> .../bindings/clock/loongson,ls2k0300-clk.yaml | 52 ++++++++++++++++++ > >>> .../dt-bindings/clock/loongson,ls2k0300-clk.h | 54 +++++++++++++++++++ > >>> 2 files changed, 106 insertions(+) > >>> create mode 100644 Documentation/devicetree/bindings/clock/loongson,ls2k0300-clk.yaml > >> > >> I don't think a new binding file for 2K0300 is needed. Adding > >> compatible entries to loongson,ls2k-clk.yaml would be more appropriate > >> as they are almost all similar. > > > > Originally I've tried to integrate the 2K0300 stuff with > > loongson,ls2k-clk.yaml, but found it's hard to describe some properties. > > > > For example, currently in loongson,ls2k-clk.yaml, the clocks property is > > described as > > > > clocks: > > items: > > - description: 100m ref > > > > what should the description look like with 2K0300 introduced, whose > > reference clock runs at 120MHz instead of 100MHz? It'll be hard to > > describe things correctly without losing existing information. "120MHz > > reference clock for Loongson 2K0300, or 100MHz reference clock for other > > SoCs" sounds even a worse idea. > > Drop the frequency anyway, it is kind of pointless here. > > > > > Another example is about the description of clock IDs. loongson,ls2k-clk.yaml > > describes available clock IDs as > > > > '#clock-cells': > > const: 1 > > description: > > The clock consumer should specify the desired clock by having the clock > > ID in its "clocks" phandle cell. See include/dt-bindings/clock/loongson,ls2k-clk.h > > for the full list of Loongson-2 SoC clock IDs. > > > > what should the description look like if we add 2K0300 support? With a > > different header being introduced, the description will be messy. > > No, just list the headers. > > > > > I think keeping SoCs peripherals that are different in hardware design > > in the same binding is really a bad idea. Yes, these clock controllers > > are similar enough to reuse the clock hardware driver, but they have > > different clock tree structures and register definitions, making them > > essentially different things. Trying to keep everything in the same > > place only makes the binding messy. > > How is binding messy if you only add one compatible? > > > Best regards, > Krzysztof Okay, thanks for the suggestions. Will merge 2K0300-related stuff into loongson,ls2k-clk.yaml in the next version. Thanks, Yao Zi
On 23/05/2025 12:45, Yao Zi wrote:
> +maintainers:
> + - Yao Zi <ziyao@disroot.org>
> +
> +description: |
Do not need '|' unless you need to preserve formatting.
> + The Loongson 2K0300 clock controller generates various clocks for SoC
> + peripherals. See include/dt-bindings/clock/loongson,ls2k0300-clk.h for
> + valid clock IDs.
> +
> +properties:
> + compatible:
> + const: loongson,ls2k0300-clk
> +
> + reg:
> + maxItems: 1
> +
> + clocks:
> + items:
> + - description: External 120MHz reference clock
> +
> + clock-names:
> + items:
> + - const: ref_120m
Just ref or drop the clock-names completely.
> +
> + '#clock-cells':
> + const: 1
> +
> +required:
> + - compatible
> + - reg
> + - clocks
> + - clock-names
> + - '#clock-cells'
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + clk: clock-controller@16000400 {
Drop unused label
> + compatible = "loongson,ls2k0300-clk";
> + reg = <0x16000400 0x100>;
> + clocks = <&ref_120m>;
> + clock-names = "ref_120m";
> + #clock-cells = <1>;
With above changes:
Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
<form letter>
This is an automated instruction, just in case, because many review tags
are being ignored. If you know the process, you can skip it (please do
not feel offended by me posting it here - no bad intentions intended).
If you do not know the process, here is a short explanation:
Please add Acked-by/Reviewed-by/Tested-by tags when posting new versions
of patchset, under or above your Signed-off-by tag, unless patch changed
significantly (e.g. new properties added to the DT bindings). Tag is
"received", when provided in a message replied to you on the mailing
list. Tools like b4 can help here. However, there's no need to repost
patches *only* to add the tags. The upstream maintainer will do that for
tags received on the version they apply.
Full context and explanation:
https://elixir.bootlin.com/linux/v6.12-rc3/source/Documentation/process/submitting-patches.rst#L577
</form letter>
Best regards,
Krzysztof
© 2016 - 2025 Red Hat, Inc.