This binding is still under development and is based on some experimental work by benh[1].
The clock signal source can be represented by any node in the device tree. These nodes are designated as clock providers. phandleThe clock consumer node connects the clock provider output to the clock input using the and clock indicator pairs. Like the gpio indicator, the clock indicator is an array of 0, 1, or more elements that identify the clock output on the device. The length of the clock indicator is defined by the attribute value in the clock provider node #clock-cells.
[1] https://patchwork.ozlabs.org/patch/31551/
clock provider
Required attributes:
#clock-cells:The number of elements in the clock indicator; typically 0 for nodes with a single clock output and 1 for nodes with multiple clock outputs.
Optional attributes:
clock-output-names: Recommended to be, a list of strings with clock output signal names indexed by the first element in the clock indicator. However, clock-output-namesthe meaning of is specific to the clock provider's domain and is only intended to encourage the use of the same meaning for most clock providers . This format may not work with clock providers that use complex clock indicator formats. In these cases, it is recommended to omit this attribute and create a binding-specific name attribute.
Clock consumer nodes must not directly reference the provider's clock-output-namesproperties.
For example:
oscillator {
#clock-cells = <1>;
clock-output-names = "ckil", "ckih";
};
- This node defines a device with two clock outputs, the first is named "ckil" and the second is named "ckih" . Consumer nodes always reference the clock by index. The name should reflect the device's clock output signal name.
clock-indices: If the identification number of the clock in the node does not increase linearly from 0, this attribute can map the identifier to clock-output-namesan array.
For example, if we have two clocks <&oscillator 1>and <&oscillator 3>:
oscillator {
compatible = "myclocktype";
#clock-cells = <1>;
clock-indices = <1>, <3>;
clock-output-names = "clka", "clkb";
}
This ensures that we clock-output-namesdon't have any empty strings in .
clock consumer
Required attributes:
clocks: phandleA list of clock indicator pairs, one pair for each clock input of the device. Note: If the clock provider specifies that it #clock-cellsis 0, only the right phandlepart is required.
Optional properties:
clock-names: A list of clock input name strings, sorted in the same order as the clock properties . The consumer driver will use clock-namesto match clock input names and clock indicators.
clock-ranges: An empty attribute indicates that child nodes can inherit the named clock from this node. Used by a bus node to provide clocks to its child nodes.
For example:
device {
clocks = <&osc 1>, <&ref 0>;
clock-names = "baud", "register";
};
This represents a device with two clock inputs named "baud" and "register" . The "baud" clock is connected to &oscoutput 1 of the device and the "register" clock is connected to &refoutput 0 of the device.
Example
/* external oscillator */
osc: oscillator {
compatible = "fixed-clock";
#clock-cells = <0>;
clock-frequency = <32678>;
clock-output-names = "osc";
};
/* phase-locked-loop device, generates a higher frequency clock
* from the external oscillator reference */
pll: pll@4c000 {
compatible = "vendor,some-pll-interface"
#clock-cells = <1>;
clocks = <&osc 0>;
clock-names = "ref";
reg = <0x4c000 0x1000>;
clock-output-names = "pll", "pll-switched";
};
/* UART, using the low frequency oscillator for the baud clock,
* and the high frequency switched PLL output for register
* clocking */
uart@a000 {
compatible = "fsl,imx-uart";
reg = <0xa000 0x1000>;
interrupts = <33>;
clocks = <&osc 0>, <&pll 1>;
clock-names = "baud", "register";
};
This DT fragment defines three devices: an external oscillator that provides a low-frequency reference clock, a PLL device that generates a higher-frequency clock signal, and a UART.
- The oscillator is a fixed frequency and provides a clock output named "osc" .
- The PLL is both a clock provider and a clock consumer. It uses a clock signal generated by an external oscillator and provides two output signals ( "pll" and "pll-switched" ).
- The UART connects its "baud" clock to the external oscillator and its "register" clock to the PLL clock ( "pll-switched" signal).
Assign clock parent node and rate
Some platforms may require initial configuration of the default parent clock and clock frequency. Such configuration can be specified in the device tree node via assigned-clocksthe assigned-clock-parentsand assigned-clock-ratesattributes. assigned-clock-parentsThe attribute should phandlecontain a list of parent clocks in the form of a and clock designator pair, and assigned-clock-ratesthe attribute should contain a list of frequencies in Hz. These two properties should correspond to assigned-clocksthe clocks listed in properties.
To skip setting the clock's parent clock or frequency, its corresponding entry should be set to 0, which can be omitted if there are no non-zero entries after it.
uart@a000 {
compatible = "fsl,imx-uart";
reg = <0xa000 0x1000>;
...
clocks = <&osc 0>, <&pll 1>;
clock-names = "baud", "register";
assigned-clocks = <&clkcon 0>, <&pll 2>;
assigned-clock-parents = <&pll 2>;
assigned-clock-rates = <0>, <460800>;
};
In this example, <&pll 2>clock is set as <&clkcon 0>the parent clock of clock , and <&pll 2>clock is assigned a frequency value of 460800 Hz.
Configuring the clock's parent clock and frequency through the device node consuming the clock can only be used for clocks with a single user. Specifying conflicting parent clock or frequency configurations for a shared clock across multiple consumer nodes is prohibited.
The configuration of a common clock, which will affect multiple consumer devices, can be similarly specified in the clock provider node.
protected clock
Some platforms or firmware may not fully expose all clocks to the OS, for example if these clocks are used by drivers running at the ARM secure execution level. In the device tree, this configuration can protected-clocksbe specified as a list of clock indicators via the property. This attribute should only be specified on nodes that provide protected clocks.
clock-controller@a000f000 {
compatible = "vendor,clk95;
reg = <0xa000f000 0x1000>
#clocks-cells = <1>;
...
protected-clocks = <UART3_CLK>, <SPI5_CLK>;
};