Documentation/devicetree/bindings/clock/idt,versaclock5.yaml

   1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/clock/idt,versaclock5.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: Binding for IDT VersaClock 5 and 6 programmable I2C clock generators
   8
   9 description: |
  10   The IDT VersaClock 5 and VersaClock 6 are programmable I2C
  11   clock generators providing from 3 to 12 output clocks.
  12
  13   When referencing the provided clock in the DT using phandle and clock
  14   specifier, the following mapping applies:
  15
  16   - 5P49V5923:
  17     0 -- OUT0_SEL_I2CB
  18     1 -- OUT1
  19     2 -- OUT2
  20
  21   - 5P49V5933:
  22     0 -- OUT0_SEL_I2CB
  23     1 -- OUT1
  24     2 -- OUT4
  25
  26   - other parts:
  27     0 -- OUT0_SEL_I2CB
  28     1 -- OUT1
  29     2 -- OUT2
  30     3 -- OUT3
  31     4 -- OUT4
  32
  33   The idt,shutdown and idt,output-enable-active properties control the
  34   SH (en_global_shutdown) and SP bits of the Primary Source and Shutdown
  35   Register, respectively. Their behavior is summarized by the following
  36   table:
  37
  38   SH SP Output when the SD/OE pin is Low/High
  39   == == =====================================
  40    0  0 Active/Inactive
  41    0  1 Inactive/Active
  42    1  0 Active/Shutdown
  43    1  1 Inactive/Shutdown
  44
  45   The case where SH and SP are both 1 is likely not very interesting.
  46
  47 maintainers:
  48   - Luca Ceresoli <luca.ceresoli@bootlin.com>
  49
  50 properties:
  51   compatible:
  52     enum:
  53       - idt,5p49v5923
  54       - idt,5p49v5925
  55       - idt,5p49v5933
  56       - idt,5p49v5935
  57       - idt,5p49v6901
  58       - idt,5p49v6965
  59       - idt,5p49v6975
  60
  61   reg:
  62     description: I2C device address
  63     enum: [ 0x68, 0x6a ]
  64
  65   '#clock-cells':
  66     const: 1
  67
  68   clock-names:
  69     minItems: 1
  70     maxItems: 2
  71     items:
  72       enum: [ xin, clkin ]
  73   clocks:
  74     minItems: 1
  75     maxItems: 2
  76
  77   idt,xtal-load-femtofarads:
  78     minimum: 9000
  79     maximum: 22760
  80     description: Optional load capacitor for XTAL1 and XTAL2
  81
  82   idt,shutdown:
  83     $ref: /schemas/types.yaml#/definitions/uint32
  84     enum: [0, 1]
  85     description: |
  86       If 1, this enables the shutdown functionality: the chip will be
  87       shut down if the SD/OE pin is driven high. If 0, this disables the
  88       shutdown functionality: the chip will never be shut down based on
  89       the value of the SD/OE pin. This property corresponds to the SH
  90       bit of the Primary Source and Shutdown Register.
  91
  92   idt,output-enable-active:
  93     $ref: /schemas/types.yaml#/definitions/uint32
  94     enum: [0, 1]
  95     description: |
  96       If 1, this enables output when the SD/OE pin is high, and disables
  97       output when the SD/OE pin is low. If 0, this disables output when
  98       the SD/OE pin is high, and enables output when the SD/OE pin is
  99       low. This corresponds to the SP bit of the Primary Source and
 100       Shutdown Register.
 101
 102 patternProperties:
 103   "^OUT[1-4]$":
 104     type: object
 105     description:
 106       Description of one of the outputs (OUT1..OUT4). See "Clock1 Output
 107       Configuration" in the Versaclock 5/6/6E Family Register Description
 108       and Programming Guide.
 109     properties:
 110       idt,mode:
 111         description:
 112           The output drive mode. Values defined in dt-bindings/clock/versaclock.h
 113         $ref: /schemas/types.yaml#/definitions/uint32
 114         minimum: 0
 115         maximum: 6
 116       idt,voltage-microvolt:
 117         description: The output drive voltage.
 118         enum: [ 1800000, 2500000, 3300000 ]
 119       idt,slew-percent:
 120         description: The Slew rate control for CMOS single-ended.
 121         enum: [ 80, 85, 90, 100 ]
 122     additionalProperties: false
 123
 124 required:
 125   - compatible
 126   - reg
 127   - '#clock-cells'
 128   - idt,shutdown
 129   - idt,output-enable-active
 130
 131 allOf:
 132   - if:
 133       properties:
 134         compatible:
 135           enum:
 136             - idt,5p49v5933
 137             - idt,5p49v5935
 138             - idt,5p49v6975
 139     then:
 140       # Devices with builtin crystal + optional external input
 141       properties:
 142         clock-names:
 143           const: clkin
 144         clocks:
 145           maxItems: 1
 146     else:
 147       # Devices without builtin crystal
 148       required:
 149         - clock-names
 150         - clocks
 151
 152 additionalProperties: false
 153
 154 examples:
 155   - |
 156     #include <dt-bindings/clock/versaclock.h>
 157
 158     /* 25MHz reference crystal */
 159     ref25: ref25m {
 160         compatible = "fixed-clock";
 161         #clock-cells = <0>;
 162         clock-frequency = <25000000>;
 163     };
 164
 165     i2c@0 {
 166         reg = <0x0 0x100>;
 167         #address-cells = <1>;
 168         #size-cells = <0>;
 169
 170         /* IDT 5P49V5923 I2C clock generator */
 171         vc5: clock-generator@6a {
 172             compatible = "idt,5p49v5923";
 173             reg = <0x6a>;
 174             #clock-cells = <1>;
 175
 176             /* Connect XIN input to 25MHz reference */
 177             clocks = <&ref25m>;
 178             clock-names = "xin";
 179
 180             /* Set the SD/OE pin's settings */
 181             idt,shutdown = <0>;
 182             idt,output-enable-active = <0>;
 183
 184             OUT1 {
 185                 idt,mode = <VC5_CMOSD>;
 186                 idt,voltage-microvolt = <1800000>;
 187                 idt,slew-percent = <80>;
 188             };
 189
 190             OUT4 {
 191                 idt,mode = <VC5_LVDS>;
 192             };
 193         };
 194     };
 195
 196 ...