Commit | Line | Data |
---|---|---|
766e6a4e GL |
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 | |
6514dff9 | 8 | specifier is an array of zero, one or more cells identifying the clock |
766e6a4e GL |
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 | ||
b4b3bfd0 GU |
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. | |
7a0fc1a3 BD |
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 | ||
b4b3bfd0 | 60 | This ensures we do not have any empty strings in clock-output-names |
7a0fc1a3 BD |
61 | |
62 | ||
766e6a4e GL |
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) | |
86be408b SN |
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 | |
dbc3976d SB |
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. | |
86be408b SN |
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. |