GNU Linux-libre 4.14.266-gnu1
[releases.git] / 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 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
51 For 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
65 Required properties:
66 clocks:         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
71 Optional properties:
72 clock-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.
76 clock-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
80 For example:
81
82     device {
83         clocks = <&osc 1>, <&ref 0>;
84         clock-names = "baud", "register";
85     };
86
87
88 This represents a device with two clock inputs, named "baud" and "register".
89 The baud clock is connected to output 1 of the &osc device, and the register
90 clock 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 = <1>;
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
124 This DT fragment defines three devices: an external oscillator to provide a
125 low-frequency reference clock, a PLL device to generate a higher frequency
126 clock 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
137 Some platforms may require initial configuration of default parent clocks
138 and clock frequencies. Such a configuration can be specified in a device tree
139 node through assigned-clocks, assigned-clock-parents and assigned-clock-rates
140 properties. The assigned-clock-parents property should contain a list of parent
141 clocks in the form of a phandle and clock specifier pair and the
142 assigned-clock-rates property should contain a list of frequencies in Hz. Both
143 these properties should correspond to the clocks listed in the assigned-clocks
144 property.
145
146 To skip setting parent or rate of a clock its corresponding entry should be
147 set 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
161 In this example the <&pll 2> clock is set as parent of clock <&clkcon 0> and
162 the <&pll 2> clock is assigned a frequency value of 460800 Hz.
163
164 Configuring a clock's parent and rate through the device node that consumes
165 the clock can be done only for clocks that have a single user. Specifying
166 conflicting parent or rate configuration in multiple consumer nodes for
167 a shared clock is forbidden.
168
169 Configuration of common clocks, which affect multiple consumer devices can
170 be similarly specified in the clock provider node.