1 This file has moved to the clock binding schem !! 1 This binding is a work-in-progress, and are based on some experimental
2 https://github.com/devicetree-org/dt-schema/bl !! 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] https://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 = <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
>> 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.
>> 171
>> 172 ==Protected clocks==
>> 173
>> 174 Some platforms or firmwares may not fully expose all the clocks to the OS, such
>> 175 as in situations where those clks are used by drivers running in ARM secure
>> 176 execution levels. Such a configuration can be specified in device tree with the
>> 177 protected-clocks property in the form of a clock specifier list. This property should
>> 178 only 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 };
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.