Documentation/devicetree/bindings/clock/clock-bindings.txt

   1 This binding is a work-in-progress, and are based on some experimental
   2 work by benh[1].
   3
   4 Sources of clock signal can be represented by any node in the device
   5 tree.  Those nodes are designated as clock providers.  Clock consumer
   6 nodes use a phandle and clock specifier pair to connect clock provider
   7 outputs to clock inputs.  Similar to the gpio specifiers, a clock
   8 specifier is an array of zero, one or more cells identifying the clock
   9 output on a device.  The length of a clock specifier is defined by the
  10 value of a #clock-cells property in the clock provider node.
  11
  12 [1] http://patchwork.ozlabs.org/patch/31551/
  13
  14 ==Clock providers==
  15
  16 Required properties:
  17 #clock-cells:      Number of cells in a clock specifier; Typically 0 for nodes
  18                    with a single clock output and 1 for nodes with multiple
  19                    clock outputs.
  20
  21 Optional properties:
  22 clock-output-names: Recommended to be a list of strings of clock output signal
  23                     names indexed by the first cell in the clock specifier.
  24                     However, the meaning of clock-output-names is domain
  25                     specific to the clock provider, and is only provided to
  26                     encourage using the same meaning for the majority of clock
  27                     providers.  This format may not work for clock providers
  28                     using a complex clock specifier format.  In those cases it
  29                     is recommended to omit this property and create a binding
  30                     specific names property.
  31
  32                     Clock consumer nodes must never directly reference
  33                     the provider's clock-output-names property.
  34
  35 For example:
  36
  37     oscillator {
  38         #clock-cells = <1>;
  39         clock-output-names = "ckil", "ckih";
  40     };
  41
  42 - this node defines a device with two clock outputs, the first named
  43   "ckil" and the second named "ckih".  Consumer nodes always reference
  44   clocks by index. The names should reflect the clock output signal
  45   names for the device.
  46
  47 clock-indices:     If the identifyng number for the clocks in the node
  48                    is not linear from zero, then the this mapping allows
  49                    the mapping of identifiers into the clock-output-names
  50                    array.
  51
  52 For example, if we have two clocks <&oscillator 1> and <&oscillator 3>:
  53
  54         oscillator {
  55                 compatible = "myclocktype";
  56                 #clock-cells = <1>;
  57                 clock-indices = <1>, <3>;
  58                 clock-output-names = "clka", "clkb";
  59         }
  60
  61         This ensures we do not have any empty nodes in clock-output-names
  62
  63
  64 ==Clock consumers==
  65
  66 Required properties:
  67 clocks:         List of phandle and clock specifier pairs, one pair
  68                 for each clock input to the device.  Note: if the
  69                 clock provider specifies '0' for #clock-cells, then
  70                 only the phandle portion of the pair will appear.
  71
  72 Optional properties:
  73 clock-names:    List of clock input name strings sorted in the same
  74                 order as the clocks property.  Consumers drivers
  75                 will use clock-names to match clock input names
  76                 with clocks specifiers.
  77 clock-ranges:   Empty property indicating that child nodes can inherit named
  78                 clocks from this node. Useful for bus nodes to provide a
  79                 clock to their children.
  80
  81 For example:
  82
  83     device {
  84         clocks = <&osc 1>, <&ref 0>;
  85         clock-names = "baud", "register";
  86     };
  87
  88
  89 This represents a device with two clock inputs, named "baud" and "register".
  90 The baud clock is connected to output 1 of the &osc device, and the register
  91 clock is connected to output 0 of the &ref.
  92
  93 ==Example==
  94
  95     /* external oscillator */
  96     osc: oscillator {
  97         compatible = "fixed-clock";
  98         #clock-cells = <1>;
  99         clock-frequency  = <32678>;
 100         clock-output-names = "osc";
 101     };
 102
 103     /* phase-locked-loop device, generates a higher frequency clock
 104      * from the external oscillator reference */
 105     pll: pll@4c000 {
 106         compatible = "vendor,some-pll-interface"
 107         #clock-cells = <1>;
 108         clocks = <&osc 0>;
 109         clock-names = "ref";
 110         reg = <0x4c000 0x1000>;
 111         clock-output-names = "pll", "pll-switched";
 112     };
 113
 114     /* UART, using the low frequency oscillator for the baud clock,
 115      * and the high frequency switched PLL output for register
 116      * clocking */
 117     uart@a000 {
 118         compatible = "fsl,imx-uart";
 119         reg = <0xa000 0x1000>;
 120         interrupts = <33>;
 121         clocks = <&osc 0>, <&pll 1>;
 122         clock-names = "baud", "register";
 123     };
 124
 125 This DT fragment defines three devices: an external oscillator to provide a
 126 low-frequency reference clock, a PLL device to generate a higher frequency
 127 clock signal, and a UART.
 128
 129 * The oscillator is fixed-frequency, and provides one clock output, named "osc".
 130 * The PLL is both a clock provider and a clock consumer. It uses the clock
 131   signal generated by the external oscillator, and provides two output signals
 132   ("pll" and "pll-switched").
 133 * The UART has its baud clock connected the external oscillator and its
 134   register clock connected to the PLL clock (the "pll-switched" signal)