Convert the OMAP divider clock device tree binding to json-schema.
Specify the creator of the original binding as a maintainer.
Signed-off-by: Andreas Kemnade <andreas@kemnade.info>
---
.../devicetree/bindings/clock/ti/divider.txt | 115 ------------
.../bindings/clock/ti/ti,divider-clock.yaml | 175 ++++++++++++++++++
2 files changed, 175 insertions(+), 115 deletions(-)
delete mode 100644 Documentation/devicetree/bindings/clock/ti/divider.txt
create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
diff --git a/Documentation/devicetree/bindings/clock/ti/divider.txt b/Documentation/devicetree/bindings/clock/ti/divider.txt
deleted file mode 100644
index 4d7c76f0b356..000000000000
--- a/Documentation/devicetree/bindings/clock/ti/divider.txt
+++ /dev/null
@@ -1,115 +0,0 @@
-Binding for TI divider clock
-
-This binding uses the common clock binding[1]. It assumes a
-register-mapped adjustable clock rate divider that does not gate and has
-only one input clock or parent. By default the value programmed into
-the register is one less than the actual divisor value. E.g:
-
-register value actual divisor value
-0 1
-1 2
-2 3
-
-This assumption may be modified by the following optional properties:
-
-ti,index-starts-at-one - valid divisor values start at 1, not the default
-of 0. E.g:
-register value actual divisor value
-1 1
-2 2
-3 3
-
-ti,index-power-of-two - valid divisor values are powers of two. E.g:
-register value actual divisor value
-0 1
-1 2
-2 4
-
-Additionally an array of valid dividers may be supplied like so:
-
- ti,dividers = <4>, <8>, <0>, <16>;
-
-Which will map the resulting values to a divisor table by their index:
-register value actual divisor value
-0 4
-1 8
-2 <invalid divisor, skipped>
-3 16
-
-Any zero value in this array means the corresponding bit-value is invalid
-and must not be used.
-
-The binding must also provide the register to control the divider and
-unless the divider array is provided, min and max dividers. Optionally
-the number of bits to shift that mask, if necessary. If the shift value
-is missing it is the same as supplying a zero shift.
-
-This binding can also optionally provide support to the hardware autoidle
-feature, see [2].
-
-[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
-[2] Documentation/devicetree/bindings/clock/ti/autoidle.txt
-
-Required properties:
-- compatible : shall be "ti,divider-clock" or "ti,composite-divider-clock".
-- #clock-cells : from common clock binding; shall be set to 0.
-- clocks : link to phandle of parent clock
-- reg : offset for register controlling adjustable divider
-
-Optional properties:
-- clock-output-names : from common clock binding.
-- ti,dividers : array of integers defining divisors
-- ti,bit-shift : number of bits to shift the divider value, defaults to 0
-- ti,min-div : min divisor for dividing the input clock rate, only
- needed if the first divisor is offset from the default value (1)
-- ti,max-div : max divisor for dividing the input clock rate, only needed
- if ti,dividers is not defined.
-- ti,index-starts-at-one : valid divisor programming starts at 1, not zero,
- only valid if ti,dividers is not defined.
-- ti,index-power-of-two : valid divisor programming must be a power of two,
- only valid if ti,dividers is not defined.
-- ti,autoidle-shift : bit shift of the autoidle enable bit for the clock,
- see [2]
-- ti,invert-autoidle-bit : autoidle is enabled by setting the bit to 0,
- see [2]
-- ti,set-rate-parent : clk_set_rate is propagated to parent
-- ti,latch-bit : latch the divider value to HW, only needed if the register
- access requires this. As an example dra76x DPLL_GMAC H14 divider implements
- such behavior.
-
-Examples:
-dpll_usb_m2_ck: dpll_usb_m2_ck@4a008190 {
- #clock-cells = <0>;
- compatible = "ti,divider-clock";
- clocks = <&dpll_usb_ck>;
- ti,max-div = <127>;
- reg = <0x190>;
- ti,index-starts-at-one;
-};
-
-aess_fclk: aess_fclk@4a004528 {
- #clock-cells = <0>;
- compatible = "ti,divider-clock";
- clocks = <&abe_clk>;
- ti,bit-shift = <24>;
- reg = <0x528>;
- ti,max-div = <2>;
-};
-
-dpll_core_m3x2_div_ck: dpll_core_m3x2_div_ck {
- #clock-cells = <0>;
- compatible = "ti,composite-divider-clock";
- clocks = <&dpll_core_x2_ck>;
- ti,max-div = <31>;
- reg = <0x0134>;
- ti,index-starts-at-one;
-};
-
-ssi_ssr_div_fck_3430es2: ssi_ssr_div_fck_3430es2 {
- #clock-cells = <0>;
- compatible = "ti,composite-divider-clock";
- clocks = <&corex2_fck>;
- ti,bit-shift = <8>;
- reg = <0x0a40>;
- ti,dividers = <0>, <1>, <2>, <3>, <4>, <0>, <6>, <0>, <8>;
-};
diff --git a/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml b/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
new file mode 100644
index 000000000000..31fe876fb40b
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
@@ -0,0 +1,175 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/ti/ti,divider-clock.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments divider clock
+
+maintainers:
+ - Tero Kristo <kristo@kernel.org>
+
+description: |
+ This clock It assumes a register-mapped adjustable clock rate divider
+ that does not gate and has only one input clock or parent. By default the
+ value programmed into the register is one less than the actual divisor value.
+ E.g:
+
+ register value actual divisor value
+ 0 1
+ 1 2
+ 2 3
+
+ This assumption may be modified by the following optional properties:
+
+ ti,index-starts-at-one - valid divisor values start at 1, not the default
+ of 0. E.g:
+ register value actual divisor value
+ 1 1
+ 2 2
+ 3 3
+
+ ti,index-power-of-two - valid divisor values are powers of two. E.g:
+ register value actual divisor value
+ 0 1
+ 1 2
+ 2 4
+
+ Additionally an array of valid dividers may be supplied like so:
+
+ ti,dividers = <4>, <8>, <0>, <16>;
+
+ Which will map the resulting values to a divisor table by their index:
+ register value actual divisor value
+ 0 4
+ 1 8
+ 2 <invalid divisor, skipped>
+ 3 16
+
+ Any zero value in this array means the corresponding bit-value is invalid
+ and must not be used.
+
+ The binding must also provide the register to control the divider and
+ unless the divider array is provided, min and max dividers. Optionally
+ the number of bits to shift that mask, if necessary. If the shift value
+ is missing it is the same as supplying a zero shift.
+
+ This binding can also optionally provide support to the hardware autoidle
+ feature, see [1].
+
+ [1] Documentation/devicetree/bindings/clock/ti/autoidle.txt
+
+properties:
+ compatible:
+ enum:
+ - ti,divider-clock
+ - ti,composite-divider-clock
+
+ "#clock-cells":
+ const: 0
+
+ clocks:
+ maxItems: 1
+
+ clock-output-names:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ ti,dividers: true
+
+ ti,bit-shift:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ number of bits to shift the divider value
+
+ ti,min-div:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ min divisor for dividing the input clock rate, only
+ needed if the first divisor is offset from the default value (1)
+
+ ti,max-div:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ max divisor for dividing the input clock rate, only needed
+ if ti,dividers is not defined.
+
+ ti,index-starts-at-one:
+ type: boolean
+ description:
+ valid divisor programming starts at 1, not zero,
+ only valid if ti,dividers is not defined
+
+ ti,index-power-of-two:
+ type: boolean
+ description:
+ valid divisor programming must be a power of two,
+ only valid if ti,dividers is not defined.
+
+ ti,autoidle-shift:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ bit shift of the autoidle enable bit for the clock,
+ see [1].
+
+ ti,invert-autoidle-bit:
+ type: boolean
+ description:
+ autoidle is enabled by setting the bit to 0,
+ see [1]
+
+ ti,set-rate-parent:
+ type: boolean
+ description:
+ clk_set_rate is propagated to parent |
+
+ ti,latch-bit:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ latch the divider value to HW, only needed if the register
+ compatible access requires this. As an example dra76x DPLL_GMAC
+ H14 divider implements such behavior.
+
+required:
+ - compatible
+ - "#clock-cells"
+ - clocks
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ bus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dpll_usb_m2_ck: clock-controller@190 {
+ #clock-cells = <0>;
+ compatible = "ti,divider-clock";
+ clocks = <&dpll_usb_ck>;
+ ti,max-div = <127>;
+ reg = <0x190>;
+ ti,index-starts-at-one;
+ };
+
+ aess_fclk: clock-controller@528 {
+ #clock-cells = <0>;
+ compatible = "ti,divider-clock";
+ clocks = <&abe_clk>;
+ ti,bit-shift = <24>;
+ reg = <0x528>;
+ ti,max-div = <2>;
+ };
+
+ ssi_ssr_div_fck_3430es2: clock-controller@a40 {
+ #clock-cells = <0>;
+ compatible = "ti,composite-divider-clock";
+ clocks = <&corex2_fck>;
+ ti,bit-shift = <8>;
+ reg = <0x0a40>;
+ ti,dividers = <0>, <1>, <2>, <3>, <4>, <0>, <6>, <0>, <8>;
+ };
+ };
--
2.39.5On Wed, Oct 09, 2024 at 10:56:19PM +0200, Andreas Kemnade wrote:
> Convert the OMAP divider clock device tree binding to json-schema.
> Specify the creator of the original binding as a maintainer.
>
> Signed-off-by: Andreas Kemnade <andreas@kemnade.info>
> ---
> .../devicetree/bindings/clock/ti/divider.txt | 115 ------------
> .../bindings/clock/ti/ti,divider-clock.yaml | 175 ++++++++++++++++++
> 2 files changed, 175 insertions(+), 115 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/clock/ti/divider.txt
> create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
>
> diff --git a/Documentation/devicetree/bindings/clock/ti/divider.txt b/Documentation/devicetree/bindings/clock/ti/divider.txt
> deleted file mode 100644
> index 4d7c76f0b356..000000000000
> --- a/Documentation/devicetree/bindings/clock/ti/divider.txt
> +++ /dev/null
> @@ -1,115 +0,0 @@
> -Binding for TI divider clock
> -
> -This binding uses the common clock binding[1]. It assumes a
> -register-mapped adjustable clock rate divider that does not gate and has
> -only one input clock or parent. By default the value programmed into
> -the register is one less than the actual divisor value. E.g:
> -
> -register value actual divisor value
> -0 1
> -1 2
> -2 3
> -
> -This assumption may be modified by the following optional properties:
> -
> -ti,index-starts-at-one - valid divisor values start at 1, not the default
> -of 0. E.g:
> -register value actual divisor value
> -1 1
> -2 2
> -3 3
> -
> -ti,index-power-of-two - valid divisor values are powers of two. E.g:
> -register value actual divisor value
> -0 1
> -1 2
> -2 4
> -
> -Additionally an array of valid dividers may be supplied like so:
> -
> - ti,dividers = <4>, <8>, <0>, <16>;
> -
> -Which will map the resulting values to a divisor table by their index:
> -register value actual divisor value
> -0 4
> -1 8
> -2 <invalid divisor, skipped>
> -3 16
> -
> -Any zero value in this array means the corresponding bit-value is invalid
> -and must not be used.
> -
> -The binding must also provide the register to control the divider and
> -unless the divider array is provided, min and max dividers. Optionally
> -the number of bits to shift that mask, if necessary. If the shift value
> -is missing it is the same as supplying a zero shift.
> -
> -This binding can also optionally provide support to the hardware autoidle
> -feature, see [2].
> -
> -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
> -[2] Documentation/devicetree/bindings/clock/ti/autoidle.txt
> -
> -Required properties:
> -- compatible : shall be "ti,divider-clock" or "ti,composite-divider-clock".
> -- #clock-cells : from common clock binding; shall be set to 0.
> -- clocks : link to phandle of parent clock
> -- reg : offset for register controlling adjustable divider
> -
> -Optional properties:
> -- clock-output-names : from common clock binding.
> -- ti,dividers : array of integers defining divisors
> -- ti,bit-shift : number of bits to shift the divider value, defaults to 0
> -- ti,min-div : min divisor for dividing the input clock rate, only
> - needed if the first divisor is offset from the default value (1)
> -- ti,max-div : max divisor for dividing the input clock rate, only needed
> - if ti,dividers is not defined.
> -- ti,index-starts-at-one : valid divisor programming starts at 1, not zero,
> - only valid if ti,dividers is not defined.
> -- ti,index-power-of-two : valid divisor programming must be a power of two,
> - only valid if ti,dividers is not defined.
> -- ti,autoidle-shift : bit shift of the autoidle enable bit for the clock,
> - see [2]
> -- ti,invert-autoidle-bit : autoidle is enabled by setting the bit to 0,
> - see [2]
> -- ti,set-rate-parent : clk_set_rate is propagated to parent
> -- ti,latch-bit : latch the divider value to HW, only needed if the register
> - access requires this. As an example dra76x DPLL_GMAC H14 divider implements
> - such behavior.
> -
> -Examples:
> -dpll_usb_m2_ck: dpll_usb_m2_ck@4a008190 {
> - #clock-cells = <0>;
> - compatible = "ti,divider-clock";
> - clocks = <&dpll_usb_ck>;
> - ti,max-div = <127>;
> - reg = <0x190>;
> - ti,index-starts-at-one;
> -};
> -
> -aess_fclk: aess_fclk@4a004528 {
> - #clock-cells = <0>;
> - compatible = "ti,divider-clock";
> - clocks = <&abe_clk>;
> - ti,bit-shift = <24>;
> - reg = <0x528>;
> - ti,max-div = <2>;
> -};
> -
> -dpll_core_m3x2_div_ck: dpll_core_m3x2_div_ck {
> - #clock-cells = <0>;
> - compatible = "ti,composite-divider-clock";
> - clocks = <&dpll_core_x2_ck>;
> - ti,max-div = <31>;
> - reg = <0x0134>;
> - ti,index-starts-at-one;
> -};
> -
> -ssi_ssr_div_fck_3430es2: ssi_ssr_div_fck_3430es2 {
> - #clock-cells = <0>;
> - compatible = "ti,composite-divider-clock";
> - clocks = <&corex2_fck>;
> - ti,bit-shift = <8>;
> - reg = <0x0a40>;
> - ti,dividers = <0>, <1>, <2>, <3>, <4>, <0>, <6>, <0>, <8>;
> -};
> diff --git a/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml b/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
> new file mode 100644
> index 000000000000..31fe876fb40b
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml
> @@ -0,0 +1,175 @@
> +# SPDX-License-Identifier: GPL-2.0-only
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/ti/ti,divider-clock.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments divider clock
> +
> +maintainers:
> + - Tero Kristo <kristo@kernel.org>
> +
> +description: |
> + This clock It assumes a register-mapped adjustable clock rate divider
> + that does not gate and has only one input clock or parent. By default the
> + value programmed into the register is one less than the actual divisor value.
> + E.g:
> +
> + register value actual divisor value
> + 0 1
> + 1 2
> + 2 3
> +
> + This assumption may be modified by the following optional properties:
> +
> + ti,index-starts-at-one - valid divisor values start at 1, not the default
> + of 0. E.g:
> + register value actual divisor value
> + 1 1
> + 2 2
> + 3 3
> +
> + ti,index-power-of-two - valid divisor values are powers of two. E.g:
> + register value actual divisor value
> + 0 1
> + 1 2
> + 2 4
> +
> + Additionally an array of valid dividers may be supplied like so:
> +
> + ti,dividers = <4>, <8>, <0>, <16>;
> +
> + Which will map the resulting values to a divisor table by their index:
> + register value actual divisor value
> + 0 4
> + 1 8
> + 2 <invalid divisor, skipped>
> + 3 16
> +
> + Any zero value in this array means the corresponding bit-value is invalid
> + and must not be used.
> +
> + The binding must also provide the register to control the divider and
> + unless the divider array is provided, min and max dividers. Optionally
> + the number of bits to shift that mask, if necessary. If the shift value
> + is missing it is the same as supplying a zero shift.
> +
> + This binding can also optionally provide support to the hardware autoidle
> + feature, see [1].
> +
> + [1] Documentation/devicetree/bindings/clock/ti/autoidle.txt
> +
> +properties:
> + compatible:
> + enum:
> + - ti,divider-clock
> + - ti,composite-divider-clock
> +
> + "#clock-cells":
> + const: 0
> +
> + clocks:
> + maxItems: 1
> +
> + clock-output-names:
> + maxItems: 1
> +
> + reg:
> + maxItems: 1
> +
> + ti,dividers: true
> +
> + ti,bit-shift:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + number of bits to shift the divider value
maximum: 31 ?
default: 0
> +
> + ti,min-div:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + min divisor for dividing the input clock rate, only
> + needed if the first divisor is offset from the default value (1)
minimum: 1
maximum: ?
default: 1
> +
> + ti,max-div:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + max divisor for dividing the input clock rate, only needed
> + if ti,dividers is not defined.
> +
> + ti,index-starts-at-one:
> + type: boolean
> + description:
> + valid divisor programming starts at 1, not zero,
> + only valid if ti,dividers is not defined
> +
> + ti,index-power-of-two:
> + type: boolean
> + description:
> + valid divisor programming must be a power of two,
> + only valid if ti,dividers is not defined.
This can be expressed as:
dependentSchemas:
ti,dividers:
properties:
ti,min-div: false
ti,max-div: false
ti,index-power-of-two: false
ti,index-starts-at-one: false
> +
> + ti,autoidle-shift:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + bit shift of the autoidle enable bit for the clock,
> + see [1].
maximum: 31
default: 0
> +
> + ti,invert-autoidle-bit:
> + type: boolean
> + description:
> + autoidle is enabled by setting the bit to 0,
> + see [1]
> +
> + ti,set-rate-parent:
> + type: boolean
> + description:
> + clk_set_rate is propagated to parent |
> +
> + ti,latch-bit:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + latch the divider value to HW, only needed if the register
> + compatible access requires this. As an example dra76x DPLL_GMAC
> + H14 divider implements such behavior.
> +
> +required:
> + - compatible
> + - "#clock-cells"
> + - clocks
> + - reg
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + bus {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + dpll_usb_m2_ck: clock-controller@190 {
Drop unused labels.
> + #clock-cells = <0>;
> + compatible = "ti,divider-clock";
> + clocks = <&dpll_usb_ck>;
> + ti,max-div = <127>;
> + reg = <0x190>;
> + ti,index-starts-at-one;
> + };
> +
> + aess_fclk: clock-controller@528 {
> + #clock-cells = <0>;
> + compatible = "ti,divider-clock";
> + clocks = <&abe_clk>;
> + ti,bit-shift = <24>;
> + reg = <0x528>;
> + ti,max-div = <2>;
> + };
> +
> + ssi_ssr_div_fck_3430es2: clock-controller@a40 {
> + #clock-cells = <0>;
> + compatible = "ti,composite-divider-clock";
> + clocks = <&corex2_fck>;
> + ti,bit-shift = <8>;
> + reg = <0x0a40>;
> + ti,dividers = <0>, <1>, <2>, <3>, <4>, <0>, <6>, <0>, <8>;
> + };
> + };
> --
> 2.39.5
>
Am Wed, 9 Oct 2024 22:44:34 -0500 schrieb Rob Herring <robh@kernel.org>: > > + > > + ti,min-div: > > + $ref: /schemas/types.yaml#/definitions/uint32 > > + description: > > + min divisor for dividing the input clock rate, only > > + needed if the first divisor is offset from the default value > > (1) > > minimum: 1 > maximum: ? > default: 1 maximum is complex: there is one place in the code where this runs through a u8 (_get_val). although it it read from the devicetree as a uint32. So, if we do not care about a specific implementation, then in the power-of-two case, the theoretical maximum would be 1 << (1 << (32-bitshift) - 1) clipped to UINT32_MAX due to type constraints. And also the maximum lifetime of electronics and elementary elements and pieces, probably even with the proposed decay time of protons. In the index-starts-at-case, we would have (1 << (32-bitshift)) - 1. otherwise 1 << (32-bitshift). I would propose not to define a maximum here. Regards, Andreas
On Wed, 09 Oct 2024 22:56:19 +0200, Andreas Kemnade wrote: > Convert the OMAP divider clock device tree binding to json-schema. > Specify the creator of the original binding as a maintainer. > > Signed-off-by: Andreas Kemnade <andreas@kemnade.info> > --- > .../devicetree/bindings/clock/ti/divider.txt | 115 ------------ > .../bindings/clock/ti/ti,divider-clock.yaml | 175 ++++++++++++++++++ > 2 files changed, 175 insertions(+), 115 deletions(-) > delete mode 100644 Documentation/devicetree/bindings/clock/ti/divider.txt > create mode 100644 Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml > My bot found errors running 'make dt_binding_check' on your patch: yamllint warnings/errors: dtschema/dtc warnings/errors: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml: ti,dividers: missing type definition doc reference errors (make refcheckdocs): Warning: Documentation/devicetree/bindings/clock/ti/composite.txt references a file that doesn't exist: Documentation/devicetree/bindings/clock/ti/divider.txt Documentation/devicetree/bindings/clock/ti/composite.txt: Documentation/devicetree/bindings/clock/ti/divider.txt See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20241009205619.16250-3-andreas@kemnade.info The base for the series is generally the latest rc1. A different dependency should be noted in *this* patch. If you already ran 'make dt_binding_check' and didn't see the above error(s), then make sure 'yamllint' is installed and dt-schema is up to date: pip3 install dtschema --upgrade Please check and re-submit after running the above command yourself. Note that DT_SCHEMA_FILES can be set to your schema file to speed up checking your schema. However, it must be unset to test all examples with your schema.
© 2016 - 2024 Red Hat, Inc.