Merge tag 'socfpga-clk-for-3.15' of git://git.rocketboards.org/linux-socfpga-next...

[deliverable/linux.git] / Documentation / devicetree / bindings / clock / clock-bindings.txt

This binding is a work-in-progress, and are based on some experimental
work by benh[1].

Sources of clock signal can be represented by any node in the device
tree.  Those nodes are designated as clock providers.  Clock consumer
nodes use a phandle and clock specifier pair to connect clock provider
outputs to clock inputs.  Similar to the gpio specifiers, a clock
specifier is an array of zero, one or more cells identifying the clock
output on a device.  The length of a clock specifier is defined by the
value of a #clock-cells property in the clock provider node.

[1] http://patchwork.ozlabs.org/patch/31551/

==Clock providers==

Required properties:
#clock-cells:	   Number of cells in a clock specifier; Typically 0 for nodes
		   with a single clock output and 1 for nodes with multiple
		   clock outputs.

Optional properties:
clock-output-names: Recommended to be a list of strings of clock output signal
		    names indexed by the first cell in the clock specifier.
		    However, the meaning of clock-output-names is domain
		    specific to the clock provider, and is only provided to
		    encourage using the same meaning for the majority of clock
		    providers.  This format may not work for clock providers
		    using a complex clock specifier format.  In those cases it
		    is recommended to omit this property and create a binding
		    specific names property.

		    Clock consumer nodes must never directly reference
		    the provider's clock-output-names property.

For example:

    oscillator {
        #clock-cells = <1>;
        clock-output-names = "ckil", "ckih";
    };

- this node defines a device with two clock outputs, the first named
  "ckil" and the second named "ckih".  Consumer nodes always reference
  clocks by index. The names should reflect the clock output signal
  names for the device.

==Clock consumers==

Required properties:
clocks:		List of phandle and clock specifier pairs, one pair
		for each clock input to the device.  Note: if the
		clock provider specifies '0' for #clock-cells, then
		only the phandle portion of the pair will appear.

Optional properties:
clock-names:	List of clock input name strings sorted in the same
		order as the clocks property.  Consumers drivers
		will use clock-names to match clock input names
		with clocks specifiers.
clock-ranges:	Empty property indicating that child nodes can inherit named
		clocks from this node. Useful for bus nodes to provide a
		clock to their children.

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 output 1 of the &osc device, and the register
clock is connected to output 0 of the &ref.

==Example==

    /* external oscillator */
    osc: oscillator {
        compatible = "fixed-clock";
        #clock-cells = <1>;
        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 to provide a
low-frequency reference clock, a PLL device to generate a higher frequency
clock signal, and a UART.

* The oscillator is fixed-frequency, and provides one clock output, named "osc".
* The PLL is both a clock provider and a clock consumer. It uses the clock
  signal generated by the external oscillator, and provides two output signals
  ("pll" and "pll-switched").
* The UART has its baud clock connected the external oscillator and its
  register clock connected to the PLL clock (the "pll-switched" signal)