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] https://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 identifying number for the clocks in the node
48		   is not linear from zero, then this allows the mapping of
49		   identifiers into the clock-output-names array.
50
51For example, if we have two clocks <&oscillator 1> and <&oscillator 3>:
52
53	oscillator {
54		compatible = "myclocktype";
55		#clock-cells = <1>;
56		clock-indices = <1>, <3>;
57		clock-output-names = "clka", "clkb";
58	}
59
60	This ensures we do not have any empty strings in clock-output-names
61
62
63==Clock consumers==
64
65Required properties:
66clocks:		List of phandle and clock specifier pairs, one pair
67		for each clock input to the device.  Note: if the
68		clock provider specifies '0' for #clock-cells, then
69		only the phandle portion of the pair will appear.
70
71Optional properties:
72clock-names:	List of clock input name strings sorted in the same
73		order as the clocks property.  Consumers drivers
74		will use clock-names to match clock input names
75		with clocks specifiers.
76clock-ranges:	Empty property indicating that child nodes can inherit named
77		clocks from this node. Useful for bus nodes to provide a
78		clock to their children.
79
80For example:
81
82    device {
83        clocks = <&osc 1>, <&ref 0>;
84        clock-names = "baud", "register";
85    };
86
87
88This represents a device with two clock inputs, named "baud" and "register".
89The baud clock is connected to output 1 of the &osc device, and the register
90clock is connected to output 0 of the &ref.
91
92==Example==
93
94    /* external oscillator */
95    osc: oscillator {
96        compatible = "fixed-clock";
97        #clock-cells = <0>;
98        clock-frequency  = <32678>;
99        clock-output-names = "osc";
100    };
101
102    /* phase-locked-loop device, generates a higher frequency clock
103     * from the external oscillator reference */
104    pll: pll@4c000 {
105        compatible = "vendor,some-pll-interface"
106        #clock-cells = <1>;
107        clocks = <&osc 0>;
108        clock-names = "ref";
109        reg = <0x4c000 0x1000>;
110        clock-output-names = "pll", "pll-switched";
111    };
112
113    /* UART, using the low frequency oscillator for the baud clock,
114     * and the high frequency switched PLL output for register
115     * clocking */
116    uart@a000 {
117        compatible = "fsl,imx-uart";
118        reg = <0xa000 0x1000>;
119        interrupts = <33>;
120        clocks = <&osc 0>, <&pll 1>;
121        clock-names = "baud", "register";
122    };
123
124This DT fragment defines three devices: an external oscillator to provide a
125low-frequency reference clock, a PLL device to generate a higher frequency
126clock signal, and a UART.
127
128* The oscillator is fixed-frequency, and provides one clock output, named "osc".
129* The PLL is both a clock provider and a clock consumer. It uses the clock
130  signal generated by the external oscillator, and provides two output signals
131  ("pll" and "pll-switched").
132* The UART has its baud clock connected the external oscillator and its
133  register clock connected to the PLL clock (the "pll-switched" signal)
134
135==Assigned clock parents and rates==
136
137Some platforms may require initial configuration of default parent clocks
138and clock frequencies. Such a configuration can be specified in a device tree
139node through assigned-clocks, assigned-clock-parents and assigned-clock-rates
140properties. The assigned-clock-parents property should contain a list of parent
141clocks in the form of a phandle and clock specifier pair and the
142assigned-clock-rates property should contain a list of frequencies in Hz. Both
143these properties should correspond to the clocks listed in the assigned-clocks
144property.
145
146To skip setting parent or rate of a clock its corresponding entry should be
147set to 0, or can be omitted if it is not followed by any non-zero entry.
148
149    uart@a000 {
150        compatible = "fsl,imx-uart";
151        reg = <0xa000 0x1000>;
152        ...
153        clocks = <&osc 0>, <&pll 1>;
154        clock-names = "baud", "register";
155
156        assigned-clocks = <&clkcon 0>, <&pll 2>;
157        assigned-clock-parents = <&pll 2>;
158        assigned-clock-rates = <0>, <460800>;
159    };
160
161In this example the <&pll 2> clock is set as parent of clock <&clkcon 0> and
162the <&pll 2> clock is assigned a frequency value of 460800 Hz.
163
164Configuring a clock's parent and rate through the device node that consumes
165the clock can be done only for clocks that have a single user. Specifying
166conflicting parent or rate configuration in multiple consumer nodes for
167a shared clock is forbidden.
168
169Configuration of common clocks, which affect multiple consumer devices can
170be similarly specified in the clock provider node.
171
172==Protected clocks==
173
174Some platforms or firmwares may not fully expose all the clocks to the OS, such
175as in situations where those clks are used by drivers running in ARM secure
176execution levels. Such a configuration can be specified in device tree with the
177protected-clocks property in the form of a clock specifier list. This property should
178only be specified in the node that is providing the clocks being protected:
179
180   clock-controller@a000f000 {
181        compatible = "vendor,clk95;
182        reg = <0xa000f000 0x1000>
183        #clocks-cells = <1>;
184        ...
185        protected-clocks = <UART3_CLK>, <SPI5_CLK>;
186   };
187