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