diff mbox series

[v2] dt-bindings: clock: brcm,kona-ccu: convert to YAML

Message ID ZTf0oWfOqnyMEKbF@standask-GA-A55M-S2HP (mailing list archive)
State Not Applicable, archived
Headers show
Series [v2] dt-bindings: clock: brcm,kona-ccu: convert to YAML | expand

Commit Message

Stanislav Jakubek Oct. 24, 2023, 4:45 p.m. UTC
Convert Broadcom Kona family clock controller unit (CCU) bindings
to DT schema.

Changes during conversion:
  - remove "dmac" from clock-output-names for brcm,bcm11351-master-ccu,
    it is not used in DT nor the dt-bindings
  - remove "uartb4" from clock-output-names for brcm,bcm21664-slave-ccu,
    it is not used in DT nor the dt-bindings

Signed-off-by: Stanislav Jakubek <stano.jakubek@gmail.com>
---

Changes in V2:
  - remove the table copied from the old txt bindings, replace it with if-then
    blocks individually listing the allowed clock-output-names per compatible
  - remove "dmac" from clock-output-names for brcm,bcm11351-master-ccu,
    it is not used in DT nor the dt-bindings
  - remove "uartb4" from clock-output-names for brcm,bcm21664-slave-ccu,
    it is not used in DT nor the dt-bindings
  - move allOf: after required:
  - Link to V1: https://lore.kernel.org/lkml/ZTUIJrTc6KKyT4xj@standask-GA-A55M-S2HP/

 .../bindings/clock/brcm,kona-ccu.txt          | 138 -------------
 .../bindings/clock/brcm,kona-ccu.yaml         | 181 ++++++++++++++++++
 2 files changed, 181 insertions(+), 138 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/clock/brcm,kona-ccu.txt
 create mode 100644 Documentation/devicetree/bindings/clock/brcm,kona-ccu.yaml

Comments

Stanislav Jakubek Oct. 28, 2023, 11:30 a.m. UTC | #1
On Fri, Oct 27, 2023 at 03:47:48PM +0100, Conor Dooley wrote:
> On Tue, Oct 24, 2023 at 06:45:21PM +0200, Stanislav Jakubek wrote:
> > Convert Broadcom Kona family clock controller unit (CCU) bindings
> > to DT schema.
> 
> I didn't cross-check the clock-output-names, but this conversion mostly
> looks good to me.
> 
> > Changes during conversion:
> >   - remove "dmac" from clock-output-names for brcm,bcm11351-master-ccu,
> >     it is not used in DT nor the dt-bindings
> >   - remove "uartb4" from clock-output-names for brcm,bcm21664-slave-ccu,
> >     it is not used in DT nor the dt-bindings
> 
> This I'm not sure about - they _were_ documented in the text-form
> dt-binding, even if they weren't used in the dts. If the clock
> controller does actually produce these clocks, removing them doesn't
> make sense to me.

Hi Conor. Looking at downstream, I was not able to find these clocks, though
I admit that I'm not familiar enough with the downstream mess to be 100%
confident.

From what I can tell, the BCM21664 arch/arm/mach-hawaii/clock.c (e.g. [1])
doesn't contain any mention of uartb4, only uartb, uartb2 and uartb3.
And similarly, for the BCM281XX arch/arm/mach-capri/clock_capri.c (e.g. [2])
I wasn't able to find any mention of dmac, only dmac_mux_apb and dma_axi
(though these two don't seem to be supported on mainline yet).

Judging by that and the fact that mainline Linux or the dt-bindings includes
don't mention these clocks either, I would say the old txt bindings document
was the wrong one.

The old clock-output-name table also didn't match with the dt-bindings include
it was supposedly describing - for example, BCM281XX_MASTER_CCU_USB_IC is
defined as 4, not 5 as the old table stated.

[1] https://github.com/Samsung-KYLEPROXX/android_kernel_samsung_kyleproxx/blob/cm-14.1/arch/arm/mach-hawaii/clock.c
[2] https://github.com/surblazer/android_kernel_samsung_galaxys2plus-common/blob/android-7.1/arch/arm/mach-capri/clock_capri.c

Thanks,
Stanislav

> 
> Cheers,
> Conor.
Artur Weber Oct. 29, 2023, 9:16 p.m. UTC | #2
On 28/10/2023 13:30, Stanislav Jakubek wrote:
> On Fri, Oct 27, 2023 at 03:47:48PM +0100, Conor Dooley wrote:
>> On Tue, Oct 24, 2023 at 06:45:21PM +0200, Stanislav Jakubek wrote:
>>> Convert Broadcom Kona family clock controller unit (CCU) bindings
>>> to DT schema.
>>
>> I didn't cross-check the clock-output-names, but this conversion mostly
>> looks good to me.
>>
>>> Changes during conversion:
>>>    - remove "dmac" from clock-output-names for brcm,bcm11351-master-ccu,
>>>      it is not used in DT nor the dt-bindings
>>>    - remove "uartb4" from clock-output-names for brcm,bcm21664-slave-ccu,
>>>      it is not used in DT nor the dt-bindings
>>
>> This I'm not sure about - they _were_ documented in the text-form
>> dt-binding, even if they weren't used in the dts. If the clock
>> controller does actually produce these clocks, removing them doesn't
>> make sense to me.
> 
> Hi Conor. Looking at downstream, I was not able to find these clocks, though
> I admit that I'm not familiar enough with the downstream mess to be 100%
> confident.
> 
>  From what I can tell, the BCM21664 arch/arm/mach-hawaii/clock.c (e.g. [1])
> doesn't contain any mention of uartb4, only uartb, uartb2 and uartb3.
> And similarly, for the BCM281XX arch/arm/mach-capri/clock_capri.c (e.g. [2])
> I wasn't able to find any mention of dmac, only dmac_mux_apb and dma_axi
> (though these two don't seem to be supported on mainline yet).

I've done some digging in the downstream kernel; for the BCM21664, I'm
almost certain that the uartb4 clock doesn't exist. Broadcom helpfully
left in "RDB" files containing the entire register layout of all of the
components; and even in the RDB for the slave clock manager[1] (used by
the other uart clocks), there is no uartb4, nor is it mentioned
anywhere else in the kernel (judging by a quick grep in the kernel
sources).

As for the BCM281XX clocks, there indeed doesn't seem to be an exact
"dmac" clock but there is a "dmac" clock gate register[2], which is
used for the dma_axi clock, so perhaps that's what this is referring
to? Also not 100% certain.

Best regards,
Artur

[1] https://github.com/Samsung-KYLEPROXX/android_kernel_samsung_kyleproxx/blob/cm-14.1/arch/arm/mach-hawaii/include/mach/rdb/brcm_rdb_kps_rst_mgr_reg.h
[2] https://github.com/surblazer/android_kernel_samsung_galaxys2plus-common/blob/android-7.1/arch/arm/mach-capri/include/mach/rdb/brcm_rdb_kpm_clk_mgr_reg.h#L417-L433
Conor Dooley Oct. 30, 2023, 11:41 a.m. UTC | #3
On Sun, Oct 29, 2023 at 10:16:14PM +0100, Artur Weber wrote:
> 
> On 28/10/2023 13:30, Stanislav Jakubek wrote:
> > On Fri, Oct 27, 2023 at 03:47:48PM +0100, Conor Dooley wrote:
> > > On Tue, Oct 24, 2023 at 06:45:21PM +0200, Stanislav Jakubek wrote:
> > > > Convert Broadcom Kona family clock controller unit (CCU) bindings
> > > > to DT schema.
> > > 
> > > I didn't cross-check the clock-output-names, but this conversion mostly
> > > looks good to me.
> > > 
> > > > Changes during conversion:
> > > >    - remove "dmac" from clock-output-names for brcm,bcm11351-master-ccu,
> > > >      it is not used in DT nor the dt-bindings
> > > >    - remove "uartb4" from clock-output-names for brcm,bcm21664-slave-ccu,
> > > >      it is not used in DT nor the dt-bindings
> > > 
> > > This I'm not sure about - they _were_ documented in the text-form
> > > dt-binding, even if they weren't used in the dts. If the clock
> > > controller does actually produce these clocks, removing them doesn't
> > > make sense to me.
> > 
> > Hi Conor. Looking at downstream, I was not able to find these clocks, though
> > I admit that I'm not familiar enough with the downstream mess to be 100%
> > confident.
> > 
> >  From what I can tell, the BCM21664 arch/arm/mach-hawaii/clock.c (e.g. [1])
> > doesn't contain any mention of uartb4, only uartb, uartb2 and uartb3.
> > And similarly, for the BCM281XX arch/arm/mach-capri/clock_capri.c (e.g. [2])
> > I wasn't able to find any mention of dmac, only dmac_mux_apb and dma_axi
> > (though these two don't seem to be supported on mainline yet).
> 
> I've done some digging in the downstream kernel; for the BCM21664, I'm
> almost certain that the uartb4 clock doesn't exist. Broadcom helpfully
> left in "RDB" files containing the entire register layout of all of the
> components; and even in the RDB for the slave clock manager[1] (used by
> the other uart clocks), there is no uartb4, nor is it mentioned
> anywhere else in the kernel (judging by a quick grep in the kernel
> sources).
> 
> As for the BCM281XX clocks, there indeed doesn't seem to be an exact
> "dmac" clock but there is a "dmac" clock gate register[2], which is
> used for the dma_axi clock, so perhaps that's what this is referring
> to? Also not 100% certain.

I'm 99% sure I was happy with this otherwise, so thanks for doing the
investigation guys :)

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

Cheers,
Conor.
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/clock/brcm,kona-ccu.txt b/Documentation/devicetree/bindings/clock/brcm,kona-ccu.txt
deleted file mode 100644
index 8e5a7d868557..000000000000
--- a/Documentation/devicetree/bindings/clock/brcm,kona-ccu.txt
+++ /dev/null
@@ -1,138 +0,0 @@ 
-Broadcom Kona Family Clocks
-
-This binding is associated with Broadcom SoCs having "Kona" style
-clock control units (CCUs).  A CCU is a clock provider that manages
-a set of clock signals.  Each CCU is represented by a node in the
-device tree.
-
-This binding uses the common clock binding:
-    Documentation/devicetree/bindings/clock/clock-bindings.txt
-
-Required properties:
-- compatible
-	Shall have a value of the form "brcm,<model>-<which>-ccu",
-	where <model> is a Broadcom SoC model number and <which> is
-	the name of a defined CCU.  For example:
-	    "brcm,bcm11351-root-ccu"
-	The compatible strings used for each supported SoC family
-	are defined below.
-- reg
-	Shall define the base and range of the address space
-	containing clock control registers
-- #clock-cells
-	Shall have value <1>.  The permitted clock-specifier values
-	are defined below.
-- clock-output-names
-	Shall be an ordered list of strings defining the names of
-	the clocks provided by the CCU.
-
-Device tree example:
-
-	slave_ccu: slave_ccu {
-		compatible = "brcm,bcm11351-slave-ccu";
-		reg = <0x3e011000 0x0f00>;
-		#clock-cells = <1>;
-		clock-output-names = "uartb",
-				     "uartb2",
-				     "uartb3",
-				     "uartb4";
-	};
-
-	ref_crystal_clk: ref_crystal {
-		#clock-cells = <0>;
-		compatible = "fixed-clock";
-		clock-frequency = <26000000>;
-	};
-
-	uart@3e002000 {
-		compatible = "brcm,bcm11351-dw-apb-uart", "snps,dw-apb-uart";
-		reg = <0x3e002000 0x1000>;
-		clocks = <&slave_ccu BCM281XX_SLAVE_CCU_UARTB3>;
-		interrupts = <GIC_SPI 65 IRQ_TYPE_LEVEL_HIGH>;
-		reg-shift = <2>;
-		reg-io-width = <4>;
-	};
-
-BCM281XX family
----------------
-CCU compatible string values for SoCs in the BCM281XX family are:
-    "brcm,bcm11351-root-ccu"
-    "brcm,bcm11351-aon-ccu"
-    "brcm,bcm11351-hub-ccu"
-    "brcm,bcm11351-master-ccu"
-    "brcm,bcm11351-slave-ccu"
-
-The following table defines the set of CCUs and clock specifiers for
-BCM281XX family clocks.  When a clock consumer references a clocks,
-its symbolic specifier (rather than its numeric index value) should
-be used.  These specifiers are defined in:
-    "include/dt-bindings/clock/bcm281xx.h"
-
-    CCU     Clock           Type    Index   Specifier
-    ---     -----           ----    -----   ---------
-    root    frac_1m         peri      0     BCM281XX_ROOT_CCU_FRAC_1M
-
-    aon     hub_timer       peri      0     BCM281XX_AON_CCU_HUB_TIMER
-    aon     pmu_bsc         peri      1     BCM281XX_AON_CCU_PMU_BSC
-    aon     pmu_bsc_var     peri      2     BCM281XX_AON_CCU_PMU_BSC_VAR
-
-    hub     tmon_1m         peri      0     BCM281XX_HUB_CCU_TMON_1M
-
-    master  sdio1           peri      0     BCM281XX_MASTER_CCU_SDIO1
-    master  sdio2           peri      1     BCM281XX_MASTER_CCU_SDIO2
-    master  sdio3           peri      2     BCM281XX_MASTER_CCU_SDIO3
-    master  sdio4           peri      3     BCM281XX_MASTER_CCU_SDIO4
-    master  dmac            peri      4     BCM281XX_MASTER_CCU_DMAC
-    master  usb_ic          peri      5     BCM281XX_MASTER_CCU_USB_IC
-    master  hsic2_48m       peri      6     BCM281XX_MASTER_CCU_HSIC_48M
-    master  hsic2_12m       peri      7     BCM281XX_MASTER_CCU_HSIC_12M
-
-    slave   uartb           peri      0     BCM281XX_SLAVE_CCU_UARTB
-    slave   uartb2          peri      1     BCM281XX_SLAVE_CCU_UARTB2
-    slave   uartb3          peri      2     BCM281XX_SLAVE_CCU_UARTB3
-    slave   uartb4          peri      3     BCM281XX_SLAVE_CCU_UARTB4
-    slave   ssp0            peri      4     BCM281XX_SLAVE_CCU_SSP0
-    slave   ssp2            peri      5     BCM281XX_SLAVE_CCU_SSP2
-    slave   bsc1            peri      6     BCM281XX_SLAVE_CCU_BSC1
-    slave   bsc2            peri      7     BCM281XX_SLAVE_CCU_BSC2
-    slave   bsc3            peri      8     BCM281XX_SLAVE_CCU_BSC3
-    slave   pwm             peri      9     BCM281XX_SLAVE_CCU_PWM
-
-
-BCM21664 family
----------------
-CCU compatible string values for SoCs in the BCM21664 family are:
-    "brcm,bcm21664-root-ccu"
-    "brcm,bcm21664-aon-ccu"
-    "brcm,bcm21664-master-ccu"
-    "brcm,bcm21664-slave-ccu"
-
-The following table defines the set of CCUs and clock specifiers for
-BCM21664 family clocks.  When a clock consumer references a clocks,
-its symbolic specifier (rather than its numeric index value) should
-be used.  These specifiers are defined in:
-    "include/dt-bindings/clock/bcm21664.h"
-
-    CCU     Clock           Type    Index   Specifier
-    ---     -----           ----    -----   ---------
-    root    frac_1m         peri      0     BCM21664_ROOT_CCU_FRAC_1M
-
-    aon     hub_timer       peri      0     BCM21664_AON_CCU_HUB_TIMER
-
-    master  sdio1           peri      0     BCM21664_MASTER_CCU_SDIO1
-    master  sdio2           peri      1     BCM21664_MASTER_CCU_SDIO2
-    master  sdio3           peri      2     BCM21664_MASTER_CCU_SDIO3
-    master  sdio4           peri      3     BCM21664_MASTER_CCU_SDIO4
-    master  sdio1_sleep     peri      4     BCM21664_MASTER_CCU_SDIO1_SLEEP
-    master  sdio2_sleep     peri      5     BCM21664_MASTER_CCU_SDIO2_SLEEP
-    master  sdio3_sleep     peri      6     BCM21664_MASTER_CCU_SDIO3_SLEEP
-    master  sdio4_sleep     peri      7     BCM21664_MASTER_CCU_SDIO4_SLEEP
-
-    slave   uartb           peri      0     BCM21664_SLAVE_CCU_UARTB
-    slave   uartb2          peri      1     BCM21664_SLAVE_CCU_UARTB2
-    slave   uartb3          peri      2     BCM21664_SLAVE_CCU_UARTB3
-    slave   uartb4          peri      3     BCM21664_SLAVE_CCU_UARTB4
-    slave   bsc1            peri      4     BCM21664_SLAVE_CCU_BSC1
-    slave   bsc2            peri      5     BCM21664_SLAVE_CCU_BSC2
-    slave   bsc3            peri      6     BCM21664_SLAVE_CCU_BSC3
-    slave   bsc4            peri      7     BCM21664_SLAVE_CCU_BSC4
diff --git a/Documentation/devicetree/bindings/clock/brcm,kona-ccu.yaml b/Documentation/devicetree/bindings/clock/brcm,kona-ccu.yaml
new file mode 100644
index 000000000000..e5656950b3bd
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/brcm,kona-ccu.yaml
@@ -0,0 +1,181 @@ 
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/brcm,kona-ccu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom Kona family clock control units (CCU)
+
+maintainers:
+  - Florian Fainelli <florian.fainelli@broadcom.com>
+  - Ray Jui <rjui@broadcom.com>
+  - Scott Branden <sbranden@broadcom.com>
+
+description: |
+  Broadcom "Kona" style clock control unit (CCU) is a clock provider that
+  manages a set of clock signals.
+
+  All available clock IDs are defined in
+  - include/dt-bindings/clock/bcm281xx.h for BCM281XX family
+  - include/dt-bindings/clock/bcm21664.h for BCM21664 family
+
+properties:
+  compatible:
+    enum:
+      - brcm,bcm11351-aon-ccu
+      - brcm,bcm11351-hub-ccu
+      - brcm,bcm11351-master-ccu
+      - brcm,bcm11351-root-ccu
+      - brcm,bcm11351-slave-ccu
+      - brcm,bcm21664-aon-ccu
+      - brcm,bcm21664-master-ccu
+      - brcm,bcm21664-root-ccu
+      - brcm,bcm21664-slave-ccu
+
+  reg:
+    maxItems: 1
+
+  '#clock-cells':
+    const: 1
+
+  clock-output-names:
+    minItems: 1
+    maxItems: 10
+
+required:
+  - compatible
+  - reg
+  - '#clock-cells'
+  - clock-output-names
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: brcm,bcm11351-aon-ccu
+    then:
+      properties:
+        clock-output-names:
+          items:
+            - const: hub_timer
+            - const: pmu_bsc
+            - const: pmu_bsc_var
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: brcm,bcm11351-hub-ccu
+    then:
+      properties:
+        clock-output-names:
+          const: tmon_1m
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: brcm,bcm11351-master-ccu
+    then:
+      properties:
+        clock-output-names:
+          items:
+            - const: sdio1
+            - const: sdio2
+            - const: sdio3
+            - const: sdio4
+            - const: usb_ic
+            - const: hsic2_48m
+            - const: hsic2_12m
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - brcm,bcm11351-root-ccu
+              - brcm,bcm21664-root-ccu
+    then:
+      properties:
+        clock-output-names:
+          const: frac_1m
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: brcm,bcm11351-slave-ccu
+    then:
+      properties:
+        clock-output-names:
+          items:
+            - const: uartb
+            - const: uartb2
+            - const: uartb3
+            - const: uartb4
+            - const: ssp0
+            - const: ssp2
+            - const: bsc1
+            - const: bsc2
+            - const: bsc3
+            - const: pwm
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: brcm,bcm21664-aon-ccu
+    then:
+      properties:
+        clock-output-names:
+          const: hub_timer
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: brcm,bcm21664-master-ccu
+    then:
+      properties:
+        clock-output-names:
+          items:
+            - const: sdio1
+            - const: sdio2
+            - const: sdio3
+            - const: sdio4
+            - const: sdio1_sleep
+            - const: sdio2_sleep
+            - const: sdio3_sleep
+            - const: sdio4_sleep
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: brcm,bcm21664-slave-ccu
+    then:
+      properties:
+        clock-output-names:
+          items:
+            - const: uartb
+            - const: uartb2
+            - const: uartb3
+            - const: bsc1
+            - const: bsc2
+            - const: bsc3
+            - const: bsc4
+
+additionalProperties: false
+
+examples:
+  - |
+    clock-controller@3e011000 {
+      compatible = "brcm,bcm11351-slave-ccu";
+      reg = <0x3e011000 0x0f00>;
+      #clock-cells = <1>;
+      clock-output-names = "uartb",
+                           "uartb2",
+                           "uartb3",
+                           "uartb4",
+                           "ssp0",
+                           "ssp2",
+                           "bsc1",
+                           "bsc2",
+                           "bsc3",
+                           "pwm";
+    };
+...