On Mon, Nov 04, 2024 at 02:55:49PM +0100, Andreas Kemnade wrote:
> Convert the OMAP mux clock device tree binding to json-schema.
> Specify the creator of the original binding as a maintainer.
> Choose GPL-only license because original binding was also GPL.
>
> Signed-off-by: Andreas Kemnade <andreas@xxxxxxxxxxxx>
> ---
> .../bindings/clock/ti/composite.txt | 2 +-
> .../devicetree/bindings/clock/ti/mux.txt | 78 -----------
> .../bindings/clock/ti/ti,mux-clock.yaml | 123 ++++++++++++++++++
> 3 files changed, 124 insertions(+), 79 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/clock/ti/mux.txt
> create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,mux-clock.yaml
>
> diff --git a/Documentation/devicetree/bindings/clock/ti/composite.txt b/Documentation/devicetree/bindings/clock/ti/composite.txt
> index b02f22490dcb..238e6f7d74f8 100644
> --- a/Documentation/devicetree/bindings/clock/ti/composite.txt
> +++ b/Documentation/devicetree/bindings/clock/ti/composite.txt
> @@ -16,7 +16,7 @@ merged to this clock. The component clocks shall be of one of the
> "ti,*composite*-clock" types.
>
> [1] Documentation/devicetree/bindings/clock/clock-bindings.txt
> -[2] Documentation/devicetree/bindings/clock/ti/mux.txt
> +[2] Documentation/devicetree/bindings/clock/ti/ti,mux-clock.yaml
> [3] Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
> [4] Documentation/devicetree/bindings/clock/ti/gate.txt
>
> diff --git a/Documentation/devicetree/bindings/clock/ti/mux.txt b/Documentation/devicetree/bindings/clock/ti/mux.txt
> deleted file mode 100644
> index cd56d3c1c09f..000000000000
> --- a/Documentation/devicetree/bindings/clock/ti/mux.txt
> +++ /dev/null
> @@ -1,78 +0,0 @@
> -Binding for TI mux clock.
> -
> -This binding uses the common clock binding[1]. It assumes a
> -register-mapped multiplexer with multiple input clock signals or
> -parents, one of which can be selected as output. This clock does not
> -gate or adjust the parent rate via a divider or multiplier.
> -
> -By default the "clocks" property lists the parents in the same order
> -as they are programmed into the register. E.g:
> -
> - clocks = <&foo_clock>, <&bar_clock>, <&baz_clock>;
> -
> -results in programming the register as follows:
> -
> -register value selected parent clock
> -0 foo_clock
> -1 bar_clock
> -2 baz_clock
> -
> -Some clock controller IPs do not allow a value of zero to be programmed
> -into the register, instead indexing begins at 1. The optional property
> -"index-starts-at-one" modified the scheme as follows:
> -
> -register value selected clock parent
> -1 foo_clock
> -2 bar_clock
> -3 baz_clock
> -
> -The binding must provide the register to control the mux. Optionally
> -the number of bits to shift the control field in the register can be
> -supplied. If the shift value is missing it is the same as supplying
> -a zero shift.
> -
> -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
> -
> -Required properties:
> -- compatible : shall be "ti,mux-clock" or "ti,composite-mux-clock".
> -- #clock-cells : from common clock binding; shall be set to 0.
> -- clocks : link phandles of parent clocks
> -- reg : register offset for register controlling adjustable mux
> -
> -Optional properties:
> -- clock-output-names : from common clock binding.
> -- ti,bit-shift : number of bits to shift the bit-mask, defaults to
> - 0 if not present
> -- ti,index-starts-at-one : valid input select programming starts at 1, not
> - zero
> -- ti,set-rate-parent : clk_set_rate is propagated to parent clock,
> - not supported by the composite-mux-clock subtype
> -- ti,latch-bit : latch the mux value to HW, only needed if the register
> - access requires this. As an example, dra7x DPLL_GMAC H14 muxing
> - implements such behavior.
> -
> -Examples:
> -
> -sys_clkin_ck: sys_clkin_ck@4a306110 {
> - #clock-cells = <0>;
> - compatible = "ti,mux-clock";
> - clocks = <&virt_12000000_ck>, <&virt_13000000_ck>, <&virt_16800000_ck>, <&virt_19200000_ck>, <&virt_26000000_ck>, <&virt_27000000_ck>, <&virt_38400000_ck>;
> - reg = <0x0110>;
> - ti,index-starts-at-one;
> -};
> -
> -abe_dpll_bypass_clk_mux_ck: abe_dpll_bypass_clk_mux_ck@4a306108 {
> - #clock-cells = <0>;
> - compatible = "ti,mux-clock";
> - clocks = <&sys_clkin_ck>, <&sys_32k_ck>;
> - ti,bit-shift = <24>;
> - reg = <0x0108>;
> -};
> -
> -mcbsp5_mux_fck: mcbsp5_mux_fck {
> - #clock-cells = <0>;
> - compatible = "ti,composite-mux-clock";
> - clocks = <&core_96m_fck>, <&mcbsp_clks>;
> - ti,bit-shift = <4>;
> - reg = <0x02d8>;
> -};
> diff --git a/Documentation/devicetree/bindings/clock/ti/ti,mux-clock.yaml b/Documentation/devicetree/bindings/clock/ti/ti,mux-clock.yaml
> new file mode 100644
> index 000000000000..b271ab86dde1
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/ti/ti,mux-clock.yaml
> @@ -0,0 +1,123 @@
> +# SPDX-License-Identifier: GPL-2.0-only
Surely TI as the only author of the original binding would agree to
dual-license this?
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/ti/ti,mux-clock.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments mux clock
> +
> +maintainers:
> + - Tero Kristo <kristo@xxxxxxxxxx>
> +
> +description: |
> + This clock assumes a register-mapped multiplexer with multiple inpt clock
> + signals or parents, one of which can be selected as output. This clock does
> + not gate or adjust the parent rate via a divider or multiplier.
> +
> + By default the "clocks" property lists the parents in the same order
> + as they are programmed into the register. E.g:
> +
> + clocks = <&foo_clock>, <&bar_clock>, <&baz_clock>;
> +
> + results in programming the register as follows:
Results
> +
> + register value selected parent clock
> + 0 foo_clock
> + 1 bar_clock
> + 2 baz_clock
> +
> + Some clock controller IPs do not allow a value of zero to be programmed
> + into the register, instead indexing begins at 1. The optional property
> + "index-starts-at-one" modified the scheme as follows:
> +
> + register value selected clock parent
> + 1 foo_clock
> + 2 bar_clock
> + 3 baz_clock
> +
> + The binding must provide the register to control the mux. Optionally
> + the number of bits to shift the control field in the register can be
> + supplied. If the shift value is missing it is the same as supplying
> + a zero shift.
> +
> +properties:
> + compatible:
> + enum:
> + - ti,mux-clock
> + - ti,composite-mux-clock
> +
> + "#clock-cells":
> + const: 0
> +
> + clocks: true
> +
> + clock-output-names:
> + maxItems: 1
> +
> + reg:
> + maxItems: 1
> +
> + ti,bit-shift:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + number of bits to shift the bit-mask, defaults to 0 if not present
Number
And on all the other descriptions...
No need to say in prose what the constraints say. So drop "defaults to 0
if not present".
> + maximum: 31
> + default: 0
> +
> + ti,index-starts-at-one:
> + type: boolean
> + description:
> + valid input select programming starts at 1, not zero
> +
> + ti,set-rate-parent:
> + type: boolean
> + description:
> + clk_set_rate is propagated to parent clock,
> + not supported by the composite-mux-clock subtype.
blank line.
> + ti,latch-bit:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + latch the mux value to HW, only needed if the register
> + access requires this. As an example, dra7x DPLL_GMAC H14 muxing
> + implements such behavior.
Constraints?
> +
> +if:
> + properties:
> + compatible:
> + contains:
> + const: ti,composite-mux-clock
> +then:
> + properties:
> + ti,set-rate-parent: false
> +
> +required:
> + - compatible
> + - "#clock-cells"
> + - clocks
> + - reg
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + bus {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + clock-controller@110 {
> + #clock-cells = <0>;
> + compatible = "ti,mux-clock";
> + clocks = <&virt_12000000_ck>, <&virt_13000000_ck>, <&virt_16800000_ck>;
> + reg = <0x0110>;
> + ti,index-starts-at-one;
> + ti,set-rate-parent;
> + };
> +
> + clock-controller@120 {
Wrong unit-address.
> + #clock-cells = <0>;
> + compatible = "ti,composite-mux-clock";
> + clocks = <&core_96m_fck>, <&mcbsp_clks>;
> + ti,bit-shift = <4>;
> + reg = <0x02d8>;
> + };
> + };
> --
> 2.39.5
>
