| Message ID | 20200708074035.31595-4-luca@lucaceresoli.net (mailing list archive) |
|---|---|
| State | Changes Requested, archived |
| Headers | show |
| Series | [v2,1/4] dt-bindings: clk: versaclock5: fix 'idt' prefix typos | expand |
On Wed, Jul 08, 2020 at 09:40:35AM +0200, Luca Ceresoli wrote: > Convert to yaml the VersaClock bindings document. The mapping between > clock specifier and physical pins cannot be described formally in yaml > schema, then keep it verbatim in the description field. > > Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net> > --- > .../bindings/clock/idt,versaclock5.txt | 125 -------------- > .../bindings/clock/idt,versaclock5.yaml | 160 ++++++++++++++++++ > MAINTAINERS | 1 + > 3 files changed, 161 insertions(+), 125 deletions(-) > delete mode 100644 Documentation/devicetree/bindings/clock/idt,versaclock5.txt > create mode 100644 Documentation/devicetree/bindings/clock/idt,versaclock5.yaml > > diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt > deleted file mode 100644 > index 9656d4cf221c..000000000000 > --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt > +++ /dev/null > @@ -1,125 +0,0 @@ > -Binding for IDT VersaClock 5,6 programmable i2c clock generators. > - > -The IDT VersaClock 5 and VersaClock 6 are programmable i2c clock > -generators providing from 3 to 12 output clocks. > - > -==I2C device node== > - > -Required properties: > -- compatible: shall be one of > - "idt,5p49v5923" > - "idt,5p49v5925" > - "idt,5p49v5933" > - "idt,5p49v5935" > - "idt,5p49v6901" > - "idt,5p49v6965" > -- reg: i2c device address, shall be 0x68 or 0x6a. > -- #clock-cells: from common clock binding; shall be set to 1. > -- clocks: from common clock binding; list of parent clock handles, > - - 5p49v5923 and > - 5p49v5925 and > - 5p49v6901: (required) either or both of XTAL or CLKIN > - reference clock. > - - 5p49v5933 and > - - 5p49v5935: (optional) property not present (internal > - Xtal used) or CLKIN reference > - clock. > -- clock-names: from common clock binding; clock input names, can be > - - 5p49v5923 and > - 5p49v5925 and > - 5p49v6901: (required) either or both of "xin", "clkin". > - - 5p49v5933 and > - - 5p49v5935: (optional) property not present or "clkin". > - > -For all output ports, a corresponding, optional child node named OUT1, > -OUT2, etc. can represent a each output, and the node can be used to > -specify the following: > - > -- idt,mode: can be one of the following: > - - VC5_LVPECL > - - VC5_CMOS > - - VC5_HCSL33 > - - VC5_LVDS > - - VC5_CMOS2 > - - VC5_CMOSD > - - VC5_HCSL25 > - > -- idt,voltage-microvolts: can be one of the following > - - 1800000 > - - 2500000 > - - 3300000 > -- idt,slew-percent: Percent of normal, can be one of > - - 80 > - - 85 > - - 90 > - - 100 > - > -==Mapping between clock specifier and physical pins== > - > -When referencing the provided clock in the DT using phandle and > -clock specifier, the following mapping applies: > - > -5P49V5923: > - 0 -- OUT0_SEL_I2CB > - 1 -- OUT1 > - 2 -- OUT2 > - > -5P49V5933: > - 0 -- OUT0_SEL_I2CB > - 1 -- OUT1 > - 2 -- OUT4 > - > -5P49V5925 and > -5P49V5935: > - 0 -- OUT0_SEL_I2CB > - 1 -- OUT1 > - 2 -- OUT2 > - 3 -- OUT3 > - 4 -- OUT4 > - > -5P49V6901: > - 0 -- OUT0_SEL_I2CB > - 1 -- OUT1 > - 2 -- OUT2 > - 3 -- OUT3 > - 4 -- OUT4 > - > -==Example== > - > -/* 25MHz reference crystal */ > -ref25: ref25m { > - compatible = "fixed-clock"; > - #clock-cells = <0>; > - clock-frequency = <25000000>; > -}; > - > -i2c-master-node { > - > - /* IDT 5P49V5923 i2c clock generator */ > - vc5: clock-generator@6a { > - compatible = "idt,5p49v5923"; > - reg = <0x6a>; > - #clock-cells = <1>; > - > - /* Connect XIN input to 25MHz reference */ > - clocks = <&ref25m>; > - clock-names = "xin"; > - > - OUT1 { > - idt,mode = <VC5_CMOS>; > - idt,voltage-microvolts = <1800000>; > - idt,slew-percent = <80>; > - }; > - OUT2 { > - ... > - }; > - ... > - }; > -}; > - > -/* Consumer referencing the 5P49V5923 pin OUT1 */ > -consumer { > - ... > - clocks = <&vc5 1>; > - ... > -} > diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml > new file mode 100644 > index 000000000000..4bdfd6187b48 > --- /dev/null > +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml > @@ -0,0 +1,160 @@ > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/clock/idt,versaclock5.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: Binding for IDT VersaClock 5 and 6 programmable I2C clock generators > + > +description: | > + The IDT VersaClock 5 and VersaClock 6 are programmable I2C > + clock generators providing from 3 to 12 output clocks. > + > + When referencing the provided clock in the DT using phandle and clock > + specifier, the following mapping applies: > + > + - 5P49V5923: > + 0 -- OUT0_SEL_I2CB > + 1 -- OUT1 > + 2 -- OUT2 > + > + - 5P49V5933: > + 0 -- OUT0_SEL_I2CB > + 1 -- OUT1 > + 2 -- OUT4 > + > + - other parts: > + 0 -- OUT0_SEL_I2CB > + 1 -- OUT1 > + 2 -- OUT2 > + 3 -- OUT3 > + 4 -- OUT4 > + > +maintainers: > + - Luca Ceresoli <luca@lucaceresoli.net> > + > +properties: > + compatible: > + enum: > + - idt,5p49v5923 > + - idt,5p49v5925 > + - idt,5p49v5933 > + - idt,5p49v5935 > + - idt,5p49v6901 > + - idt,5p49v6965 > + > + reg: > + maxItems: 1 > + description: I2C device address, shall be 0x68 or 0x6a. Can be a schema: enum: [ 0x68, 0x6a ] > + > + '#clock-cells': > + const: 1 > + > +patternProperties: > + "^OUT[1-4]$": > + type: object > + description: > + Description of one of the outputs (OUT1..OUT4). See "Clock1 Output > + Configuration" in the Versaclock 5/6/6E Family Register Description > + and Programming Guide. > + properties: > + idt,mode: > + description: > + The output drive mode. Values defined in dt-bindings/clk/versaclock.h > + enum: > + - VC5_LVPECL This is defining a string. Can't use defines here. > + - VC5_CMOS > + - VC5_HCSL33 > + - VC5_LVDS > + - VC5_CMOS2 > + - VC5_CMOSD > + - VC5_HCSL25 > + idt,voltage-microvolts: > + description: The output drive voltage. > + $ref: /schemas/types.yaml#/definitions/uint32 Standard unit suffixes have a type already, so drop. > + enum: [ 1800000, 2500000, 3300000 ] > + idt,slew-percent: > + description: The Slew rate control for CMOS single-ended. > + $ref: /schemas/types.yaml#/definitions/uint32 Here too. > + enum: [ 80, 85, 90, 100 ] > + > +required: > + - compatible > + - reg > + - '#clock-cells' > + > +allOf: > + - if: > + properties: > + compatible: > + contains: > + enum: > + - idt,5p49v5933 > + - idt,5p49v5935 > + then: > + # Devices with builtin crystal, optional external input > + properties: > + clock-names: > + const: clkin > + clocks: > + maxItems: 1 > + else: > + # Devices without builtin crystal > + properties: > + clock-names: > + anyOf: > + - required: [ xin ] > + - required: [ clkin ] This isn't valid. I think you want: clock-names: minItems: 1 items: - const: xin - const: clkin This would mean 'xin' is always required, clkin is optional. > + clocks: > + minItems: 1 > + maxItems: 2 > + required: > + - clock-names > + - clocks > + > +examples: > + - | > + #include <dt-bindings/clk/versaclock.h> > + > + /* 25MHz reference crystal */ > + ref25: ref25m { > + compatible = "fixed-clock"; > + #clock-cells = <0>; > + clock-frequency = <25000000>; > + }; > + > + i2c@0 { > + reg = <0x0 0x100>; > + #address-cells = <1>; > + #size-cells = <0>; > + > + /* IDT 5P49V5923 I2C clock generator */ > + vc5: clock-generator@6a { > + compatible = "idt,5p49v5923"; > + reg = <0x6a>; > + #clock-cells = <1>; > + > + /* Connect XIN input to 25MHz reference */ > + clocks = <&ref25m>; > + clock-names = "xin"; > + > + OUT1 { > + idt,drive-mode = <VC5_CMOSD>; > + idt,voltage-microvolts = <1800000>; > + idt,slew-percent = <80>; > + }; > + > + OUT4 { > + idt,drive-mode = <VC5_LVDS>; > + }; > + }; > + }; > + > + /* Consumer referencing the 5P49V5923 pin OUT1 */ > + consumer { > + /* ... */ > + clocks = <&vc5 1>; > + /* ... */ > + }; > + > +... > diff --git a/MAINTAINERS b/MAINTAINERS > index 5aa16c245c63..09d6efd1d0d0 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -8326,6 +8326,7 @@ F: drivers/input/misc/ideapad_slidebar.c > IDT VersaClock 5 CLOCK DRIVER > M: Luca Ceresoli <luca@lucaceresoli.net> > S: Maintained > +F: Documentation/devicetree/bindings/clock/idt,versaclock5.yaml > F: drivers/clk/clk-versaclock5.c > > IEEE 802.15.4 SUBSYSTEM > -- > 2.27.0 >
Hi Rob, thanks for you review! On 14/07/20 05:11, Rob Herring wrote: > On Wed, Jul 08, 2020 at 09:40:35AM +0200, Luca Ceresoli wrote: >> Convert to yaml the VersaClock bindings document. The mapping between >> clock specifier and physical pins cannot be described formally in yaml >> schema, then keep it verbatim in the description field. >> >> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net> [...] >> + reg: >> + maxItems: 1 >> + description: I2C device address, shall be 0x68 or 0x6a. > > Can be a schema: > > enum: [ 0x68, 0x6a ] Nice, will fix. >> + >> + '#clock-cells': >> + const: 1 >> + >> +patternProperties: >> + "^OUT[1-4]$": >> + type: object >> + description: >> + Description of one of the outputs (OUT1..OUT4). See "Clock1 Output >> + Configuration" in the Versaclock 5/6/6E Family Register Description >> + and Programming Guide. >> + properties: >> + idt,mode: >> + description: >> + The output drive mode. Values defined in dt-bindings/clk/versaclock.h >> + enum: >> + - VC5_LVPECL > > This is defining a string. Can't use defines here. How do I use the defines from include/dt-bindings then? Or should I just use the numeric values then, like: idt,mode: description: The output drive mode. Values defined in dt-bindings/clk/versaclock.h minimum: 0 maximum: 6 ? >> + idt,voltage-microvolts: >> + description: The output drive voltage. >> + $ref: /schemas/types.yaml#/definitions/uint32 > > Standard unit suffixes have a type already, so drop. Ok. >> +allOf: >> + - if: >> + properties: >> + compatible: >> + contains: >> + enum: >> + - idt,5p49v5933 >> + - idt,5p49v5935 >> + then: >> + # Devices with builtin crystal, optional external input >> + properties: >> + clock-names: >> + const: clkin >> + clocks: >> + maxItems: 1 >> + else: >> + # Devices without builtin crystal >> + properties: >> + clock-names: >> + anyOf: >> + - required: [ xin ] >> + - required: [ clkin ] > > This isn't valid. I think you want: > > clock-names: > minItems: 1 > items: > - const: xin > - const: clkin > > This would mean 'xin' is always required, clkin is optional. No, what I wanted to mean is that allowed cases are: * for idt,5p49v5933 and idt,5p49v5935: - only 'xin' (required) * for the other parts one of these: - only 'xin' - only 'clkin' - both 'xin' and 'clkin' How do I express that? A general note: as a newcomer to yaml bindings I found a steep learning curve. Finding a correct construct (not to mention the best one) for each situation is time consuming and frustrating. I've been looking at existing files for suitable examples but it doesn't work very well. Is there any guide to yaml bindings for beginners with examples of typical cases? It would greatly help in producing better patches and saving time for everybody. Thanks,
On Tue, Jul 14, 2020 at 3:15 AM Luca Ceresoli <luca@lucaceresoli.net> wrote: > > Hi Rob, > > thanks for you review! > > On 14/07/20 05:11, Rob Herring wrote: > > On Wed, Jul 08, 2020 at 09:40:35AM +0200, Luca Ceresoli wrote: > >> Convert to yaml the VersaClock bindings document. The mapping between > >> clock specifier and physical pins cannot be described formally in yaml > >> schema, then keep it verbatim in the description field. > >> > >> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net> > > [...] > > >> + reg: > >> + maxItems: 1 > >> + description: I2C device address, shall be 0x68 or 0x6a. > > > > Can be a schema: > > > > enum: [ 0x68, 0x6a ] > > Nice, will fix. > > >> + > >> + '#clock-cells': > >> + const: 1 > >> + > >> +patternProperties: > >> + "^OUT[1-4]$": > >> + type: object > >> + description: > >> + Description of one of the outputs (OUT1..OUT4). See "Clock1 Output > >> + Configuration" in the Versaclock 5/6/6E Family Register Description > >> + and Programming Guide. > >> + properties: > >> + idt,mode: > >> + description: > >> + The output drive mode. Values defined in dt-bindings/clk/versaclock.h > >> + enum: > >> + - VC5_LVPECL > > > > This is defining a string. Can't use defines here. > > How do I use the defines from include/dt-bindings then? Or should I just > use the numeric values then, like: > > idt,mode: > description: > The output drive mode. Values defined in > dt-bindings/clk/versaclock.h > minimum: 0 > maximum: 6 > > ? Yes. > > >> + idt,voltage-microvolts: > >> + description: The output drive voltage. > >> + $ref: /schemas/types.yaml#/definitions/uint32 > > > > Standard unit suffixes have a type already, so drop. > > Ok. > > >> +allOf: > >> + - if: > >> + properties: > >> + compatible: > >> + contains: > >> + enum: > >> + - idt,5p49v5933 > >> + - idt,5p49v5935 > >> + then: > >> + # Devices with builtin crystal, optional external input > >> + properties: > >> + clock-names: > >> + const: clkin > >> + clocks: > >> + maxItems: 1 > >> + else: > >> + # Devices without builtin crystal > >> + properties: > >> + clock-names: > >> + anyOf: > >> + - required: [ xin ] > >> + - required: [ clkin ] > > > > This isn't valid. I think you want: > > > > clock-names: > > minItems: 1 > > items: > > - const: xin > > - const: clkin > > > > This would mean 'xin' is always required, clkin is optional. > > No, what I wanted to mean is that allowed cases are: > * for idt,5p49v5933 and idt,5p49v5935: > - only 'xin' (required) For this you need an if/then schema. There are plenty of examples in the tree, but this is what you need: if: properties: compatible: enum: - idt,5p49v5933 - idt,5p49v5935 then: properties: clocks: maxItems: 1 clock-names: const: xin > * for the other parts one of these: > - only 'xin' > - only 'clkin' > - both 'xin' and 'clkin' > > How do I express that? For the 2nd part: clock-names: minItems: 1 maxItems: 2 items: enum: [ xin, clkin ] > A general note: as a newcomer to yaml bindings I found a steep learning > curve. Finding a correct construct (not to mention the best one) for > each situation is time consuming and frustrating. I've been looking at > existing files for suitable examples but it doesn't work very well. > > Is there any guide to yaml bindings for beginners with examples of > typical cases? It would greatly help in producing better patches and > saving time for everybody. bindings/example-schema.yaml is intended to do that. No doubt it could use more examples. Though from my perspective people already don't read and follow things it says there. The problem I think is not the typical cases, but the atypical ones. I don't think we can enumerate all the atypical cases. At that point you really need some understanding of json-schema which I agree has a bit of a learning curve if you've never used anything like it (I hadn't). Rob
Hi Rob, On 14/07/20 05:11, Rob Herring wrote: > On Wed, Jul 08, 2020 at 09:40:35AM +0200, Luca Ceresoli wrote: >> Convert to yaml the VersaClock bindings document. The mapping between >> clock specifier and physical pins cannot be described formally in yaml >> schema, then keep it verbatim in the description field. >> >> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net> >> --- >> .../bindings/clock/idt,versaclock5.txt | 125 -------------- >> .../bindings/clock/idt,versaclock5.yaml | 160 ++++++++++++++++++ >> MAINTAINERS | 1 + >> 3 files changed, 161 insertions(+), 125 deletions(-) >> delete mode 100644 Documentation/devicetree/bindings/clock/idt,versaclock5.txt >> create mode 100644 Documentation/devicetree/bindings/clock/idt,versaclock5.yaml >> >> diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt >> deleted file mode 100644 >> index 9656d4cf221c..000000000000 >> --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt >> +++ /dev/null >> @@ -1,125 +0,0 @@ >> -Binding for IDT VersaClock 5,6 programmable i2c clock generators. >> - >> -The IDT VersaClock 5 and VersaClock 6 are programmable i2c clock >> -generators providing from 3 to 12 output clocks. >> - >> -==I2C device node== >> - >> -Required properties: >> -- compatible: shall be one of >> - "idt,5p49v5923" >> - "idt,5p49v5925" >> - "idt,5p49v5933" >> - "idt,5p49v5935" >> - "idt,5p49v6901" >> - "idt,5p49v6965" >> -- reg: i2c device address, shall be 0x68 or 0x6a. >> -- #clock-cells: from common clock binding; shall be set to 1. >> -- clocks: from common clock binding; list of parent clock handles, >> - - 5p49v5923 and >> - 5p49v5925 and >> - 5p49v6901: (required) either or both of XTAL or CLKIN >> - reference clock. >> - - 5p49v5933 and >> - - 5p49v5935: (optional) property not present (internal >> - Xtal used) or CLKIN reference >> - clock. >> -- clock-names: from common clock binding; clock input names, can be >> - - 5p49v5923 and >> - 5p49v5925 and >> - 5p49v6901: (required) either or both of "xin", "clkin". >> - - 5p49v5933 and >> - - 5p49v5935: (optional) property not present or "clkin". >> - >> -For all output ports, a corresponding, optional child node named OUT1, >> -OUT2, etc. can represent a each output, and the node can be used to >> -specify the following: >> - >> -- idt,mode: can be one of the following: >> - - VC5_LVPECL >> - - VC5_CMOS >> - - VC5_HCSL33 >> - - VC5_LVDS >> - - VC5_CMOS2 >> - - VC5_CMOSD >> - - VC5_HCSL25 >> - >> -- idt,voltage-microvolts: can be one of the following >> - - 1800000 >> - - 2500000 >> - - 3300000 >> -- idt,slew-percent: Percent of normal, can be one of >> - - 80 >> - - 85 >> - - 90 >> - - 100 >> - >> -==Mapping between clock specifier and physical pins== >> - >> -When referencing the provided clock in the DT using phandle and >> -clock specifier, the following mapping applies: >> - >> -5P49V5923: >> - 0 -- OUT0_SEL_I2CB >> - 1 -- OUT1 >> - 2 -- OUT2 >> - >> -5P49V5933: >> - 0 -- OUT0_SEL_I2CB >> - 1 -- OUT1 >> - 2 -- OUT4 >> - >> -5P49V5925 and >> -5P49V5935: >> - 0 -- OUT0_SEL_I2CB >> - 1 -- OUT1 >> - 2 -- OUT2 >> - 3 -- OUT3 >> - 4 -- OUT4 >> - >> -5P49V6901: >> - 0 -- OUT0_SEL_I2CB >> - 1 -- OUT1 >> - 2 -- OUT2 >> - 3 -- OUT3 >> - 4 -- OUT4 >> - >> -==Example== >> - >> -/* 25MHz reference crystal */ >> -ref25: ref25m { >> - compatible = "fixed-clock"; >> - #clock-cells = <0>; >> - clock-frequency = <25000000>; >> -}; >> - >> -i2c-master-node { >> - >> - /* IDT 5P49V5923 i2c clock generator */ >> - vc5: clock-generator@6a { >> - compatible = "idt,5p49v5923"; >> - reg = <0x6a>; >> - #clock-cells = <1>; >> - >> - /* Connect XIN input to 25MHz reference */ >> - clocks = <&ref25m>; >> - clock-names = "xin"; >> - >> - OUT1 { >> - idt,mode = <VC5_CMOS>; >> - idt,voltage-microvolts = <1800000>; >> - idt,slew-percent = <80>; >> - }; >> - OUT2 { >> - ... >> - }; >> - ... >> - }; >> -}; >> - >> -/* Consumer referencing the 5P49V5923 pin OUT1 */ >> -consumer { >> - ... >> - clocks = <&vc5 1>; >> - ... >> -} >> diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml >> new file mode 100644 >> index 000000000000..4bdfd6187b48 >> --- /dev/null >> +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml >> @@ -0,0 +1,160 @@ >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) >> +%YAML 1.2 >> +--- >> +$id: http://devicetree.org/schemas/clock/idt,versaclock5.yaml# >> +$schema: http://devicetree.org/meta-schemas/core.yaml# >> + >> +title: Binding for IDT VersaClock 5 and 6 programmable I2C clock generators >> + >> +description: | >> + The IDT VersaClock 5 and VersaClock 6 are programmable I2C >> + clock generators providing from 3 to 12 output clocks. >> + >> + When referencing the provided clock in the DT using phandle and clock >> + specifier, the following mapping applies: >> + >> + - 5P49V5923: >> + 0 -- OUT0_SEL_I2CB >> + 1 -- OUT1 >> + 2 -- OUT2 >> + >> + - 5P49V5933: >> + 0 -- OUT0_SEL_I2CB >> + 1 -- OUT1 >> + 2 -- OUT4 >> + >> + - other parts: >> + 0 -- OUT0_SEL_I2CB >> + 1 -- OUT1 >> + 2 -- OUT2 >> + 3 -- OUT3 >> + 4 -- OUT4 >> + >> +maintainers: >> + - Luca Ceresoli <luca@lucaceresoli.net> >> + >> +properties: >> + compatible: >> + enum: >> + - idt,5p49v5923 >> + - idt,5p49v5925 >> + - idt,5p49v5933 >> + - idt,5p49v5935 >> + - idt,5p49v6901 >> + - idt,5p49v6965 >> + >> + reg: >> + maxItems: 1 >> + description: I2C device address, shall be 0x68 or 0x6a. > > Can be a schema: > > enum: [ 0x68, 0x6a ] > >> + >> + '#clock-cells': >> + const: 1 >> + >> +patternProperties: >> + "^OUT[1-4]$": >> + type: object >> + description: >> + Description of one of the outputs (OUT1..OUT4). See "Clock1 Output >> + Configuration" in the Versaclock 5/6/6E Family Register Description >> + and Programming Guide. >> + properties: >> + idt,mode: >> + description: >> + The output drive mode. Values defined in dt-bindings/clk/versaclock.h >> + enum: >> + - VC5_LVPECL > > This is defining a string. Can't use defines here. > >> + - VC5_CMOS >> + - VC5_HCSL33 >> + - VC5_LVDS >> + - VC5_CMOS2 >> + - VC5_CMOSD >> + - VC5_HCSL25 >> + idt,voltage-microvolts: >> + description: The output drive voltage. >> + $ref: /schemas/types.yaml#/definitions/uint32 > > Standard unit suffixes have a type already, so drop. After better studying json schema, v3 is coming with this change, but... > >> + enum: [ 1800000, 2500000, 3300000 ] >> + idt,slew-percent: >> + description: The Slew rate control for CMOS single-ended. >> + $ref: /schemas/types.yaml#/definitions/uint32 > > Here too. ...not this one. It doesn't look like "percent" or similar is a standard unit, and reading [0] confirms that. Should it be added? [0] https://github.com/robherring/dt-schema/blob/master/schemas/property-units.yaml Thanks.
diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt deleted file mode 100644 index 9656d4cf221c..000000000000 --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt +++ /dev/null @@ -1,125 +0,0 @@ -Binding for IDT VersaClock 5,6 programmable i2c clock generators. - -The IDT VersaClock 5 and VersaClock 6 are programmable i2c clock -generators providing from 3 to 12 output clocks. - -==I2C device node== - -Required properties: -- compatible: shall be one of - "idt,5p49v5923" - "idt,5p49v5925" - "idt,5p49v5933" - "idt,5p49v5935" - "idt,5p49v6901" - "idt,5p49v6965" -- reg: i2c device address, shall be 0x68 or 0x6a. -- #clock-cells: from common clock binding; shall be set to 1. -- clocks: from common clock binding; list of parent clock handles, - - 5p49v5923 and - 5p49v5925 and - 5p49v6901: (required) either or both of XTAL or CLKIN - reference clock. - - 5p49v5933 and - - 5p49v5935: (optional) property not present (internal - Xtal used) or CLKIN reference - clock. -- clock-names: from common clock binding; clock input names, can be - - 5p49v5923 and - 5p49v5925 and - 5p49v6901: (required) either or both of "xin", "clkin". - - 5p49v5933 and - - 5p49v5935: (optional) property not present or "clkin". - -For all output ports, a corresponding, optional child node named OUT1, -OUT2, etc. can represent a each output, and the node can be used to -specify the following: - -- idt,mode: can be one of the following: - - VC5_LVPECL - - VC5_CMOS - - VC5_HCSL33 - - VC5_LVDS - - VC5_CMOS2 - - VC5_CMOSD - - VC5_HCSL25 - -- idt,voltage-microvolts: can be one of the following - - 1800000 - - 2500000 - - 3300000 -- idt,slew-percent: Percent of normal, can be one of - - 80 - - 85 - - 90 - - 100 - -==Mapping between clock specifier and physical pins== - -When referencing the provided clock in the DT using phandle and -clock specifier, the following mapping applies: - -5P49V5923: - 0 -- OUT0_SEL_I2CB - 1 -- OUT1 - 2 -- OUT2 - -5P49V5933: - 0 -- OUT0_SEL_I2CB - 1 -- OUT1 - 2 -- OUT4 - -5P49V5925 and -5P49V5935: - 0 -- OUT0_SEL_I2CB - 1 -- OUT1 - 2 -- OUT2 - 3 -- OUT3 - 4 -- OUT4 - -5P49V6901: - 0 -- OUT0_SEL_I2CB - 1 -- OUT1 - 2 -- OUT2 - 3 -- OUT3 - 4 -- OUT4 - -==Example== - -/* 25MHz reference crystal */ -ref25: ref25m { - compatible = "fixed-clock"; - #clock-cells = <0>; - clock-frequency = <25000000>; -}; - -i2c-master-node { - - /* IDT 5P49V5923 i2c clock generator */ - vc5: clock-generator@6a { - compatible = "idt,5p49v5923"; - reg = <0x6a>; - #clock-cells = <1>; - - /* Connect XIN input to 25MHz reference */ - clocks = <&ref25m>; - clock-names = "xin"; - - OUT1 { - idt,mode = <VC5_CMOS>; - idt,voltage-microvolts = <1800000>; - idt,slew-percent = <80>; - }; - OUT2 { - ... - }; - ... - }; -}; - -/* Consumer referencing the 5P49V5923 pin OUT1 */ -consumer { - ... - clocks = <&vc5 1>; - ... -} diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml new file mode 100644 index 000000000000..4bdfd6187b48 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/idt,versaclock5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding for IDT VersaClock 5 and 6 programmable I2C clock generators + +description: | + The IDT VersaClock 5 and VersaClock 6 are programmable I2C + clock generators providing from 3 to 12 output clocks. + + When referencing the provided clock in the DT using phandle and clock + specifier, the following mapping applies: + + - 5P49V5923: + 0 -- OUT0_SEL_I2CB + 1 -- OUT1 + 2 -- OUT2 + + - 5P49V5933: + 0 -- OUT0_SEL_I2CB + 1 -- OUT1 + 2 -- OUT4 + + - other parts: + 0 -- OUT0_SEL_I2CB + 1 -- OUT1 + 2 -- OUT2 + 3 -- OUT3 + 4 -- OUT4 + +maintainers: + - Luca Ceresoli <luca@lucaceresoli.net> + +properties: + compatible: + enum: + - idt,5p49v5923 + - idt,5p49v5925 + - idt,5p49v5933 + - idt,5p49v5935 + - idt,5p49v6901 + - idt,5p49v6965 + + reg: + maxItems: 1 + description: I2C device address, shall be 0x68 or 0x6a. + + '#clock-cells': + const: 1 + +patternProperties: + "^OUT[1-4]$": + type: object + description: + Description of one of the outputs (OUT1..OUT4). See "Clock1 Output + Configuration" in the Versaclock 5/6/6E Family Register Description + and Programming Guide. + properties: + idt,mode: + description: + The output drive mode. Values defined in dt-bindings/clk/versaclock.h + enum: + - VC5_LVPECL + - VC5_CMOS + - VC5_HCSL33 + - VC5_LVDS + - VC5_CMOS2 + - VC5_CMOSD + - VC5_HCSL25 + idt,voltage-microvolts: + description: The output drive voltage. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 1800000, 2500000, 3300000 ] + idt,slew-percent: + description: The Slew rate control for CMOS single-ended. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 80, 85, 90, 100 ] + +required: + - compatible + - reg + - '#clock-cells' + +allOf: + - if: + properties: + compatible: + contains: + enum: + - idt,5p49v5933 + - idt,5p49v5935 + then: + # Devices with builtin crystal, optional external input + properties: + clock-names: + const: clkin + clocks: + maxItems: 1 + else: + # Devices without builtin crystal + properties: + clock-names: + anyOf: + - required: [ xin ] + - required: [ clkin ] + clocks: + minItems: 1 + maxItems: 2 + required: + - clock-names + - clocks + +examples: + - | + #include <dt-bindings/clk/versaclock.h> + + /* 25MHz reference crystal */ + ref25: ref25m { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <25000000>; + }; + + i2c@0 { + reg = <0x0 0x100>; + #address-cells = <1>; + #size-cells = <0>; + + /* IDT 5P49V5923 I2C clock generator */ + vc5: clock-generator@6a { + compatible = "idt,5p49v5923"; + reg = <0x6a>; + #clock-cells = <1>; + + /* Connect XIN input to 25MHz reference */ + clocks = <&ref25m>; + clock-names = "xin"; + + OUT1 { + idt,drive-mode = <VC5_CMOSD>; + idt,voltage-microvolts = <1800000>; + idt,slew-percent = <80>; + }; + + OUT4 { + idt,drive-mode = <VC5_LVDS>; + }; + }; + }; + + /* Consumer referencing the 5P49V5923 pin OUT1 */ + consumer { + /* ... */ + clocks = <&vc5 1>; + /* ... */ + }; + +... diff --git a/MAINTAINERS b/MAINTAINERS index 5aa16c245c63..09d6efd1d0d0 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -8326,6 +8326,7 @@ F: drivers/input/misc/ideapad_slidebar.c IDT VersaClock 5 CLOCK DRIVER M: Luca Ceresoli <luca@lucaceresoli.net> S: Maintained +F: Documentation/devicetree/bindings/clock/idt,versaclock5.yaml F: drivers/clk/clk-versaclock5.c IEEE 802.15.4 SUBSYSTEM
Convert to yaml the VersaClock bindings document. The mapping between clock specifier and physical pins cannot be described formally in yaml schema, then keep it verbatim in the description field. Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net> --- .../bindings/clock/idt,versaclock5.txt | 125 -------------- .../bindings/clock/idt,versaclock5.yaml | 160 ++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 161 insertions(+), 125 deletions(-) delete mode 100644 Documentation/devicetree/bindings/clock/idt,versaclock5.txt create mode 100644 Documentation/devicetree/bindings/clock/idt,versaclock5.yaml