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@xxxxxxxxxxxxxxxx>
>> ---
>> .../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@xxxxxxxxxxxxxxxx>
>> +
>> +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.
--
Luca
