Re: [PATCH v2 4/4] dt-bindings: clk: versaclock5: convert to yaml

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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.

> +        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@xxxxxxxxxxxxxxxx>
>  S:	Maintained
> +F:	Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
>  F:	drivers/clk/clk-versaclock5.c
>  
>  IEEE 802.15.4 SUBSYSTEM
> -- 
> 2.27.0
> 



[Index of Archives]     [Device Tree Compilter]     [Device Tree Spec]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux PCI Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]


  Powered by Linux