Merge remote-tracking branch 'linaro_mturquette_linux/clk-for-3.10' into for-3.10/clk

Frequently asked questions about the sunxi clock system

=======================================================

This document contains useful bits of information that people tend to ask

about the sunxi clock system, as well as accompanying ASCII art when adequate.

Q: Why is the main 24MHz oscillator gatable? Wouldn't that break the

   system?

A: The 24MHz oscillator allows gating to save power. Indeed, if gated

   carelessly the system would stop functioning, but with the right

   steps, one can gate it and keep the system running. Consider this

   simplified suspend example:

   While the system is operational, you would see something like

      24MHz         32kHz

       |

      PLL1

       \

        \_ CPU Mux

             |

           [CPU]

   When you are about to suspend, you switch the CPU Mux to the 32kHz

   oscillator:

      24Mhz         32kHz

       |              |

      PLL1            |

                     /

           CPU Mux _/

             |

           [CPU]

    Finally you can gate the main oscillator

                    32kHz

                      |

                      |

                     /

           CPU Mux _/

             |

           [CPU]

Q: Were can I learn more about the sunxi clocks?

A: The linux-sunxi wiki contains a page documenting the clock registers,

   you can find it at

        http://linux-sunxi.org/A10/CCM

   The authoritative source for information at this time is the ccmu driver

   released by Allwinner, you can find it at

        https://github.com/linux-sunxi/linux-sunxi/tree/sunxi-3.0/arch/arm/mach-sun4i/clock/ccmu

};

Below is a matrix detailing which clk_ops are mandatory based upon the

hardware capbilities of that clock.  A cell marked as "y" means

hardware capabilities of that clock.  A cell marked as "y" means

mandatory, a cell marked as "n" implies that either including that

callback is invalid or otherwise uneccesary.  Empty cells are either

callback is invalid or otherwise unnecessary.  Empty cells are either

optional or must be evaluated on a case-by-case basis.

                           clock hardware characteristics

Binding for the axi-clkgen clock generator

This binding uses the common clock binding[1].

[1] Documentation/devicetree/bindings/clock/clock-bindings.txt

Required properties:

- compatible : shall be "adi,axi-clkgen".

- #clock-cells : from common clock binding; Should always be set to 0.

- reg : Address and length of the axi-clkgen register set.

- clocks : Phandle and clock specifier for the parent clock.

Optional properties:

- clock-output-names : From common clock binding.

Example:

	clock@0xff000000 {

		compatible = "adi,axi-clkgen";

		#clock-cells = <0>;

		reg = <0xff000000 0x1000>;

		clocks = <&osc 1>;

	};

Device Tree Clock bindings for arch-sunxi

This binding uses the common clock binding[1].

[1] Documentation/devicetree/bindings/clock/clock-bindings.txt

Required properties:

- compatible : shall be one of the following:

	"allwinner,sun4i-osc-clk" - for a gatable oscillator

	"allwinner,sun4i-pll1-clk" - for the main PLL clock

	"allwinner,sun4i-cpu-clk" - for the CPU multiplexer clock

	"allwinner,sun4i-axi-clk" - for the AXI clock

	"allwinner,sun4i-ahb-clk" - for the AHB clock

	"allwinner,sun4i-apb0-clk" - for the APB0 clock

	"allwinner,sun4i-apb1-clk" - for the APB1 clock

	"allwinner,sun4i-apb1-mux-clk" - for the APB1 clock muxing

Required properties for all clocks:

- reg : shall be the control register address for the clock.

- clocks : shall be the input parent clock(s) phandle for the clock

- #clock-cells : from common clock binding; shall be set to 0.

For example:

osc24M: osc24M@01c20050 {

	#clock-cells = <0>;

	compatible = "allwinner,sun4i-osc-clk";

	reg = <0x01c20050 0x4>;

	clocks = <&osc24M_fixed>;

};

pll1: pll1@01c20000 {

	#clock-cells = <0>;

	compatible = "allwinner,sun4i-pll1-clk";

	reg = <0x01c20000 0x4>;

	clocks = <&osc24M>;

};

cpu: cpu@01c20054 {

	#clock-cells = <0>;

	compatible = "allwinner,sun4i-cpu-clk";

	reg = <0x01c20054 0x4>;

	clocks = <&osc32k>, <&osc24M>, <&pll1>;

};

	busy->mux.reg = reg;

	busy->mux.shift = shift;

	busy->mux.width = width;

	busy->mux.mask = BIT(width) - 1;

	busy->mux.lock = &imx_ccm_lock;

	busy->mux_ops = &clk_mux_ops;