| Message ID | 20241009205619.16250-3-andreas@kemnade.info (mailing list archive) |
|---|---|
| State | Changes Requested, archived |
| Headers | show |
| Series | dt-bindings: clock: ti: convert to yaml | expand |
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.
On 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
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>; + }; + };
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