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
>
