1This binding is a work-in-progress, and are based on some experimental
2work by benh[1].
3
4Sources of clock signal can be represented by any node in the device
5tree.  Those nodes are designated as clock providers.  Clock consumer
6nodes use a phandle and clock specifier pair to connect clock provider
7outputs to clock inputs.  Similar to the gpio specifiers, a clock
8specifier is an array of zero, one or more cells identifying the clock
9output on a device.  The length of a clock specifier is defined by the
10value of a #clock-cells property in the clock provider node.
11
12[1] http://patchwork.ozlabs.org/patch/31551/
13
14==Clock providers==
15
16Required 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
21Optional properties:
22clock-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
35For 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
47clock-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
52For 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
66Required properties:
67clocks:		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
72Optional properties:
73clock-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.
77clock-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
81For example:
82
83    device {
84        clocks = <&osc 1>, <&ref 0>;
85        clock-names = "baud", "register";
86    };
87
88
89This represents a device with two clock inputs, named "baud" and "register".
90The baud clock is connected to output 1 of the &osc device, and the register
91clock 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
125This DT fragment defines three devices: an external oscillator to provide a
126low-frequency reference clock, a PLL device to generate a higher frequency
127clock 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)
135