Merge branch 'late/clksrc' into late/cleanup

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

		};

	};

	...

};

Timing properties for child nodes. All are optional and default to 0.

 - gpmc,sync-clk:	Minimum clock period for synchronous mode, in picoseconds

 Chip-select signal timings corresponding to GPMC_CONFIG2:

 - gpmc,cs-on:		Assertion time

 - gpmc,cs-rd-off:	Read deassertion time

 - gpmc,cs-wr-off:	Write deassertion time

 ADV signal timings corresponding to GPMC_CONFIG3:

 - gpmc,adv-on:		Assertion time

 - gpmc,adv-rd-off:	Read deassertion time

 - gpmc,adv-wr-off:	Write deassertion time

 WE signals timings corresponding to GPMC_CONFIG4:

 - gpmc,we-on:		Assertion time

 - gpmc,we-off:		Deassertion time

 OE signals timings corresponding to GPMC_CONFIG4:

 - gpmc,oe-on:		Assertion time

 - gpmc,oe-off:		Deassertion time

 Access time and cycle time timings corresponding to GPMC_CONFIG5:

 - gpmc,page-burst-access: Multiple access word delay

 - gpmc,access:		Start-cycle to first data valid delay

 - gpmc,rd-cycle:	Total read cycle time

 - gpmc,wr-cycle:	Total write cycle time

 - gpmc,sync-clk-ps:	Minimum clock period for synchronous mode, in picoseconds

 Chip-select signal timings (in nanoseconds) corresponding to GPMC_CONFIG2:

 - gpmc,cs-on-ns:	Assertion time

 - gpmc,cs-rd-off-ns:	Read deassertion time

 - gpmc,cs-wr-off-ns:	Write deassertion time

 ADV signal timings (in nanoseconds) corresponding to GPMC_CONFIG3:

 - gpmc,adv-on-ns:	Assertion time

 - gpmc,adv-rd-off-ns:	Read deassertion time

 - gpmc,adv-wr-off-ns:	Write deassertion time

 WE signals timings (in nanoseconds) corresponding to GPMC_CONFIG4:

 - gpmc,we-on-ns	Assertion time

 - gpmc,we-off-ns:	Deassertion time

 OE signals timings (in nanoseconds) corresponding to GPMC_CONFIG4:

 - gpmc,oe-on-ns:	Assertion time

 - gpmc,oe-off-ns:	Deassertion time

 Access time and cycle time timings (in nanoseconds) corresponding to

 GPMC_CONFIG5:

 - gpmc,page-burst-access-ns: 	Multiple access word delay

 - gpmc,access-ns:		Start-cycle to first data valid delay

 - gpmc,rd-cycle-ns:		Total read cycle time

 - gpmc,wr-cycle-ns:		Total write cycle time

 - gpmc,bus-turnaround-ns:	Turn-around time between successive accesses

 - gpmc,cycle2cycle-delay-ns:	Delay between chip-select pulses

 - gpmc,clk-activation-ns: 	GPMC clock activation time

 - gpmc,wait-monitoring-ns:	Start of wait monitoring with regard to valid

				data

Boolean timing parameters. If property is present parameter enabled and

disabled if omitted:

 - gpmc,adv-extra-delay:	ADV signal is delayed by half GPMC clock

 - gpmc,cs-extra-delay:		CS signal is delayed by half GPMC clock

 - gpmc,cycle2cycle-diffcsen:	Add "cycle2cycle-delay" between successive

				accesses to a different CS

 - gpmc,cycle2cycle-samecsen:	Add "cycle2cycle-delay" between successive

				accesses to the same CS

 - gpmc,oe-extra-delay:		OE signal is delayed by half GPMC clock

 - gpmc,we-extra-delay:		WE signal is delayed by half GPMC clock

 - gpmc,time-para-granularity:	Multiply all access times by 2

The following are only applicable to OMAP3+ and AM335x:

 - gpmc,wr-access

 - gpmc,wr-data-mux-bus

 - gpmc,wr-access-ns:		In synchronous write mode, for single or

				burst accesses, defines the number of

				GPMC_FCLK cycles from start access time

				to the GPMC_CLK rising edge used by the

				memory device for the first data capture.

 - gpmc,wr-data-mux-bus-ns:	In address-data multiplex mode, specifies

				the time when the first data is driven on

				the address-data bus.

GPMC chip-select settings properties for child nodes. All are optional.

- gpmc,burst-length	Page/burst length. Must be 4, 8 or 16.

- gpmc,burst-wrap	Enables wrap bursting

- gpmc,burst-read	Enables read page/burst mode

- gpmc,burst-write	Enables write page/burst mode

- gpmc,device-nand	Device is NAND

- gpmc,device-width	Total width of device(s) connected to a GPMC

			chip-select in bytes. The GPMC supports 8-bit

			and 16-bit devices and so this property must be

			1 or 2.

- gpmc,mux-add-data	Address and data multiplexing configuration.

			Valid values are 1 for address-address-data

			multiplexing mode and 2 for address-data

			multiplexing mode.

- gpmc,sync-read	Enables synchronous read. Defaults to asynchronous

			is this is not set.

- gpmc,sync-write	Enables synchronous writes. Defaults to asynchronous

			is this is not set.

- gpmc,wait-pin		Wait-pin used by client. Must be less than

			"gpmc,num-waitpins".

- gpmc,wait-on-read	Enables wait monitoring on reads.

- gpmc,wait-on-write	Enables wait monitoring on writes.

Example for an AM33xx board:

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

	};