Merge branch 'tegra/clk' into next/dt2

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

NVIDIA Tegra Power Management Controller (PMC)

Properties:

The PMC block interacts with an external Power Management Unit. The PMC

mostly controls the entry and exit of the system from different sleep

modes. It provides power-gating controllers for SoC and CPU power-islands.

Required properties:

- name : Should be pmc

- compatible : Should contain "nvidia,tegra<chip>-pmc".

- reg : Offset and length of the register set for the device

- clocks : Must contain an entry for each entry in clock-names.

- clock-names : Must include the following entries:

  "pclk" (The Tegra clock of that name),

  "clk32k_in" (The 32KHz clock input to Tegra).

Optional properties:

- nvidia,invert-interrupt : If present, inverts the PMU interrupt signal.

  The PMU is an external Power Management Unit, whose interrupt output

  signal is fed into the PMC. This signal is optionally inverted, and then

  fed into the ARM GIC. The PMC is not involved in the detection or

  handling of this interrupt signal, merely its inversion.

- nvidia,suspend-mode : The suspend mode that the platform should use.

  Valid values are 0, 1 and 2:

  0 (LP0): CPU + Core voltage off and DRAM in self-refresh

  1 (LP1): CPU voltage off and DRAM in self-refresh

  2 (LP2): CPU voltage off

- nvidia,core-power-req-active-high : Boolean, core power request active-high

- nvidia,sys-clock-req-active-high : Boolean, system clock request active-high

- nvidia,combined-power-req : Boolean, combined power request for CPU & Core

- nvidia,cpu-pwr-good-en : Boolean, CPU power good signal (from PMIC to PMC)

			   is enabled.

Required properties when nvidia,suspend-mode is specified:

- nvidia,cpu-pwr-good-time : CPU power good time in uS.

- nvidia,cpu-pwr-off-time : CPU power off time in uS.

- nvidia,core-pwr-good-time : <Oscillator-stable-time Power-stable-time>

			      Core power good time in uS.

- nvidia,core-pwr-off-time : Core power off time in uS.

Required properties when nvidia,suspend-mode=<0>:

- nvidia,lp0-vec : <start length> Starting address and length of LP0 vector

  The LP0 vector contains the warm boot code that is executed by AVP when

  resuming from the LP0 state. The AVP (Audio-Video Processor) is an ARM7

  processor and always being the first boot processor when chip is power on

  or resume from deep sleep mode. When the system is resumed from the deep

  sleep mode, the warm boot code will restore some PLLs, clocks and then

  bring up CPU0 for resuming the system.

Example:

/ SoC dts including file

pmc@7000f400 {

	compatible = "nvidia,tegra20-pmc";

	reg = <0x7000e400 0x400>;

	clocks = <&tegra_car 110>, <&clk32k_in>;

	clock-names = "pclk", "clk32k_in";

	nvidia,invert-interrupt;

	nvidia,suspend-mode = <1>;

	nvidia,cpu-pwr-good-time = <2000>;

	nvidia,cpu-pwr-off-time = <100>;

	nvidia,core-pwr-good-time = <3845 3845>;

	nvidia,core-pwr-off-time = <458>;

	nvidia,core-power-req-active-high;

	nvidia,sys-clock-req-active-high;

	nvidia,lp0-vec = <0xbdffd000 0x2000>;

};

/ Tegra board dts file

{

	...

	clocks {

		compatible = "simple-bus";

		#address-cells = <1>;

		#size-cells = <0>;

		clk32k_in: clock {

			compatible = "fixed-clock";

			reg=<0>;

			#clock-cells = <0>;

			clock-frequency = <32768>;

		};

	};

	...

};

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>;

	};

NVIDIA Tegra114 Clock And Reset Controller

This binding uses the common clock binding:

Documentation/devicetree/bindings/clock/clock-bindings.txt

The CAR (Clock And Reset) Controller on Tegra is the HW module responsible

for muxing and gating Tegra's clocks, and setting their rates.

Required properties :

- compatible : Should be "nvidia,tegra114-car"

- reg : Should contain CAR registers location and length

- clocks : Should contain phandle and clock specifiers for two clocks:

  the 32 KHz "32k_in", and the board-specific oscillator "osc".

- #clock-cells : Should be 1.

  In clock consumers, this cell represents the clock ID exposed by the CAR.

  The first 160 clocks are numbered to match the bits in the CAR's CLK_OUT_ENB

  registers. These IDs often match those in the CAR's RST_DEVICES registers,

  but not in all cases. Some bits in CLK_OUT_ENB affect multiple clocks. In

  this case, those clocks are assigned IDs above 160 in order to highlight

  this issue. Implementations that interpret these clock IDs as bit values

  within the CLK_OUT_ENB or RST_DEVICES registers should be careful to

  explicitly handle these special cases.

  The balance of the clocks controlled by the CAR are assigned IDs of 160 and

  above.

  0	unassigned

  1	unassigned

  2	unassigned

  3	unassigned

  4	rtc

  5	timer

  6	uarta

  7	unassigned	(register bit affects uartb and vfir)

  8	unassigned

  9	sdmmc2

  10	unassigned	(register bit affects spdif_in and spdif_out)

  11	i2s1

  12	i2c1

  13	ndflash

  14	sdmmc1

  15	sdmmc4

  16	unassigned

  17	pwm

  18	i2s2

  19	epp

  20	unassigned	(register bit affects vi and vi_sensor)

  21	2d

  22	usbd

  23	isp

  24	3d

  25	unassigned

  26	disp2

  27	disp1

  28	host1x

  29	vcp

  30	i2s0

  31	unassigned

  32	unassigned

  33	unassigned

  34	apbdma

  35	unassigned

  36	kbc

  37	unassigned

  38	unassigned

  39	unassigned	(register bit affects fuse and fuse_burn)

  40	kfuse

  41	sbc1

  42	nor

  43	unassigned

  44	sbc2

  45	unassigned

  46	sbc3

  47	i2c5

  48	dsia

  49	unassigned

  50	mipi

  51	hdmi

  52	csi

  53	unassigned

  54	i2c2

  55	uartc

  56	mipi-cal

  57	emc

  58	usb2

  59	usb3

  60	msenc

  61	vde

  62	bsea

  63	bsev

  64	unassigned

  65	uartd

  66	unassigned

  67	i2c3

  68	sbc4

  69	sdmmc3

  70	unassigned

  71	owr

  72	afi

  73	csite

  74	unassigned

  75	unassigned

  76	la

  77	trace

  78	soc_therm

  79	dtv

  80	ndspeed

  81	i2cslow

  82	dsib

  83	tsec

  84	unassigned

  85	unassigned

  86	unassigned

  87	unassigned

  88	unassigned

  89	xusb_host

  90	unassigned

  91	msenc

  92	csus

  93	unassigned

  94	unassigned

  95	unassigned	(bit affects xusb_dev and xusb_dev_src)

  96	unassigned

  97	unassigned

  98	unassigned

  99	mselect

  100	tsensor

  101	i2s3

  102	i2s4

  103	i2c4

  104	sbc5

  105	sbc6

  106	d_audio

  107	apbif

  108	dam0

  109	dam1

  110	dam2

  111	hda2codec_2x

  112	unassigned

  113	audio0_2x

  114	audio1_2x

  115	audio2_2x

  116	audio3_2x

  117	audio4_2x

  118	spdif_2x

  119	actmon

  120	extern1

  121	extern2

  122	extern3

  123	unassigned

  124	unassigned

  125	hda

  126	unassigned

  127	se

  128	hda2hdmi

  129	unassigned

  130	unassigned

  131	unassigned

  132	unassigned

  133	unassigned

  134	unassigned

  135	unassigned

  136	unassigned

  137	unassigned

  138	unassigned

  139	unassigned

  140	unassigned

  141	unassigned

  142	unassigned

  143	unassigned	(bit affects xusb_falcon_src, xusb_fs_src,

			 xusb_host_src and xusb_ss_src)

  144	cilab

  145	cilcd

  146	cile

  147	dsialp

  148	dsiblp

  149	unassigned

  150	dds

  151	unassigned

  152	dp2

  153	amx

  154	adx

  155	unassigned	(bit affects dfll_ref and dfll_soc)

  156	xusb_ss

  192	uartb

  193	vfir

  194	spdif_in

  195	spdif_out

  196	vi

  197	vi_sensor

  198	fuse

  199	fuse_burn

  200	clk_32k

  201	clk_m

  202	clk_m_div2

  203	clk_m_div4

  204	pll_ref

  205	pll_c

  206	pll_c_out1

  207	pll_c2

  208	pll_c3

  209	pll_m

  210	pll_m_out1

  211	pll_p

  212	pll_p_out1

  213	pll_p_out2

  214	pll_p_out3

  215	pll_p_out4

  216	pll_a

  217	pll_a_out0

  218	pll_d

  219	pll_d_out0

  220	pll_d2

  221	pll_d2_out0

  222	pll_u

  223	pll_u_480M

  224	pll_u_60M

  225	pll_u_48M

  226	pll_u_12M

  227	pll_x

  228	pll_x_out0

  229	pll_re_vco

  230	pll_re_out

  231	pll_e_out0

  232	spdif_in_sync

  233	i2s0_sync

  234	i2s1_sync

  235	i2s2_sync

  236	i2s3_sync

  237	i2s4_sync

  238	vimclk_sync

  239	audio0

  240	audio1

  241	audio2

  242	audio3

  243	audio4

  244	spdif

  245	clk_out_1

  246	clk_out_2

  247	clk_out_3

  248	blink

  252	xusb_host_src

  253	xusb_falcon_src

  254	xusb_fs_src

  255	xusb_ss_src

  256	xusb_dev_src

  257	xusb_dev

  258	xusb_hs_src

  259	sclk

  260	hclk

  261	pclk

  262	cclk_g

  263	cclk_lp

  264	dfll_ref

  265	dfll_soc

Example SoC include file:

/ {

	tegra_car: clock {

		compatible = "nvidia,tegra114-car";

		reg = <0x60006000 0x1000>;

		#clock-cells = <1>;

	};

	usb@c5004000 {

		clocks = <&tegra_car 58>; /* usb2 */

	};

};

Example board file:

/ {

	clocks {

		compatible = "simple-bus";

		#address-cells = <1>;

		#size-cells = <0>;

		osc: clock@0 {

			compatible = "fixed-clock";

			reg = <0>;

			#clock-cells = <0>;

			clock-frequency = <12000000>;

		};

		clk_32k: clock@1 {

			compatible = "fixed-clock";

			reg = <1>;

			#clock-cells = <0>;

			clock-frequency = <32768>;

		};

	};

	&tegra_car {

		clocks = <&clk_32k> <&osc>;

	};

};