Documentation/devicetree/bindings/arm/vexpress.txt - maze/linux - Git at Google

 ARM Versatile Express boards family
 -----------------------------------

 ARM's Versatile Express platform consists of a motherboard and one
 or more daughterboards (tiles). The motherboard provides a set of
 peripherals. Processor and RAM "live" on the tiles.

 The motherboard and each core tile should be described by a separate
 Device Tree source file, with the tile's description including
 the motherboard file using a /include/ directive. As the motherboard
 can be initialized in one of two different configurations ("memory
 maps"), care must be taken to include the correct one.


 Root node
 ---------

 Required properties in the root node:
 - compatible value:
 	compatible = "arm,vexpress,<model>", "arm,vexpress";
   where <model> is the full tile model name (as used in the tile's
     Technical Reference Manual), eg.:
     - for Coretile Express A5x2 (V2P-CA5s):
 	compatible = "arm,vexpress,v2p-ca5s", "arm,vexpress";
     - for Coretile Express A9x4 (V2P-CA9):
 	compatible = "arm,vexpress,v2p-ca9", "arm,vexpress";
   If a tile comes in several variants or can be used in more then one
   configuration, the compatible value should be:
 	compatible = "arm,vexpress,<model>,<variant>", \
 				"arm,vexpress,<model>", "arm,vexpress";
   eg:
     - Coretile Express A15x2 (V2P-CA15) with Tech Chip 1:
 	compatible = "arm,vexpress,v2p-ca15,tc1", \
 				"arm,vexpress,v2p-ca15", "arm,vexpress";
     - LogicTile Express 13MG (V2F-2XV6) running Cortex-A7 (3 cores) SMM:
 	compatible = "arm,vexpress,v2f-2xv6,ca7x3", \
 				"arm,vexpress,v2f-2xv6", "arm,vexpress";

 Optional properties in the root node:
 - tile model name (use name from the tile's Technical Reference
   Manual, eg. "V2P-CA5s")
 	model = "<model>";
 - tile's HBI number (unique ARM's board model ID, visible on the
   PCB's silkscreen) in hexadecimal transcription:
 	arm,hbi = <0xhbi>
   eg:
   - for Coretile Express A5x2 (V2P-CA5s) HBI-0191:
 	arm,hbi = <0x191>;
   - Coretile Express A9x4 (V2P-CA9) HBI-0225:
 	arm,hbi = <0x225>;


 CPU nodes
 ---------

 Top-level standard "cpus" node is required. It must contain a node
 with device_type = "cpu" property for every available core, eg.:

 	cpus {
 		#address-cells = <1>;
 		#size-cells = <0>;

 		cpu@0 {
 			device_type = "cpu";
 			compatible = "arm,cortex-a5";
 			reg = <0>;
 		};
 	};


 Configuration infrastructure
 ----------------------------

 The platform has an elaborated configuration system, consisting of
 microcontrollers residing on the mother- and daughterboards known
 as Motherboard/Daughterboard Configuration Controller (MCC and DCC).
 The controllers are responsible for the platform initialization
 (reset generation, flash programming, FPGA bitfiles loading etc.)
 but also control clock generators, voltage regulators, gather
 environmental data like temperature, power consumption etc. Even
 the video output switch (FPGA) is controlled that way.

 Nodes describing devices controlled by this infrastructure should
 point at the bridge device node:
 - bridge phandle:
 	arm,vexpress,config-bridge = <phandle>;
 This property can be also defined in a parent node (eg. for a DCC)
 and is effective for all children.


 Platform topology
 -----------------

 As Versatile Express can be configured in number of physically
 different setups, the device tree should describe platform topology.
 Root node and main motherboard node must define the following
 property, describing physical location of the children nodes:
 - site number:
 	arm,vexpress,site = <number>;
   where 0 means motherboard, 1 or 2 are daugtherboard sites,
   0xf means "master" site (site containing main CPU tile)
 - when daughterboards are stacked on one site, their position
   in the stack be be described with:
 	arm,vexpress,position = <number>;
 - when describing tiles consisting more than one DCC, its number
   can be described with:
 	arm,vexpress,dcc = <number>;

 Any of the numbers above defaults to zero if not defined in
 the node or any of its parent.


 Motherboard
 -----------

 The motherboard description file provides a single "motherboard" node
 using 2 address cells corresponding to the Static Memory Bus used
 between the motherboard and the tile. The first cell defines the Chip
 Select (CS) line number, the second cell address offset within the CS.
 All interrupt lines between the motherboard and the tile are active
 high and are described using single cell.

 Optional properties of the "motherboard" node:
 - motherboard's memory map variant:
 	arm,v2m-memory-map = "<name>";
   where name is one of:
   - "rs1" - for RS1 map (i.a. peripherals on CS3); this map is also
             referred to as "ARM Cortex-A Series memory map":
 	arm,v2m-memory-map = "rs1";
   When this property is missing, the motherboard is using the original
   memory map (also known as the "Legacy memory map", primarily used
   with the original CoreTile Express A9x4) with peripherals on CS7.

 Motherboard .dtsi files provide a set of labelled peripherals that
 can be used to obtain required phandle in the tile's "aliases" node:
 - UARTs, note that the numbers correspond to the physical connectors
   on the motherboard's back panel:
 	v2m_serial0, v2m_serial1, v2m_serial2 and v2m_serial3
 - I2C controllers:
 	v2m_i2c_dvi and v2m_i2c_pcie
 - SP804 timers:
 	v2m_timer01 and v2m_timer23

 The tile description should define a "smb" node, describing the
 Static Memory Bus between the tile and motherboard. It must define
 the following properties:
 - "simple-bus" compatible value (to ensure creation of the children)
 	compatible = "simple-bus";
 - mapping of the SMB CS/offset addresses into main address space:
 	#address-cells = <2>;
 	#size-cells = <1>;
 	ranges = <...>;
 - interrupts mapping:
 	#interrupt-cells = <1>;
 	interrupt-map-mask = <0 0 63>;
 	interrupt-map = <...>;


 Example of a VE tile description (simplified)
 ---------------------------------------------

 /dts-v1/;

 / {
 	model = "V2P-CA5s";
 	arm,hbi = <0x225>;
 	arm,vexpress,site = <0xf>;
 	compatible = "arm,vexpress-v2p-ca5s", "arm,vexpress";
 	interrupt-parent = <&gic>;
 	#address-cells = <1>;
 	#size-cells = <1>;

 	chosen { };

 	aliases {
 		serial0 = &v2m_serial0;
 	};

 	cpus {
 		#address-cells = <1>;
 		#size-cells = <0>;

 		cpu@0 {
 			device_type = "cpu";
 			compatible = "arm,cortex-a5";
 			reg = <0>;
 		};
 	};

 	gic: interrupt-controller@2c001000 {
 		compatible = "arm,cortex-a9-gic";
 		#interrupt-cells = <3>;
 		#address-cells = <0>;
 		interrupt-controller;
 		reg = <0x2c001000 0x1000>,
 		      <0x2c000100 0x100>;
 	};

 	dcc {
 		compatible = "simple-bus";
 		arm,vexpress,config-bridge = <&v2m_sysreg>;

 		osc@0 {
 			compatible = "arm,vexpress-osc";
 		};
 	};

 	smb {
 		compatible = "simple-bus";

 		#address-cells = <2>;
 		#size-cells = <1>;
 		/* CS0 is visible at 0x08000000 */
 		ranges = <0 0 0x08000000 0x04000000>;

 		#interrupt-cells = <1>;
 		interrupt-map-mask = <0 0 63>;
 		/* Active high IRQ 0 is connected to GIC's SPI0 */
 		interrupt-map = <0 0 0 &gic 0 0 4>;

 		/include/ "vexpress-v2m-rs1.dtsi"
 	};
 };
	ARM Versatile Express boards family
	-----------------------------------

	ARM's Versatile Express platform consists of a motherboard and one
	or more daughterboards (tiles). The motherboard provides a set of
	peripherals. Processor and RAM "live" on the tiles.

	The motherboard and each core tile should be described by a separate
	Device Tree source file, with the tile's description including
	the motherboard file using a /include/ directive. As the motherboard
	can be initialized in one of two different configurations ("memory
	maps"), care must be taken to include the correct one.


	Root node
	---------

	Required properties in the root node:
	- compatible value:
	compatible = "arm,vexpress,<model>", "arm,vexpress";
	where <model> is the full tile model name (as used in the tile's
	Technical Reference Manual), eg.:
	- for Coretile Express A5x2 (V2P-CA5s):
	compatible = "arm,vexpress,v2p-ca5s", "arm,vexpress";
	- for Coretile Express A9x4 (V2P-CA9):
	compatible = "arm,vexpress,v2p-ca9", "arm,vexpress";
	If a tile comes in several variants or can be used in more then one
	configuration, the compatible value should be:
	compatible = "arm,vexpress,<model>,<variant>", \
	"arm,vexpress,<model>", "arm,vexpress";
	eg:
	- Coretile Express A15x2 (V2P-CA15) with Tech Chip 1:
	compatible = "arm,vexpress,v2p-ca15,tc1", \
	"arm,vexpress,v2p-ca15", "arm,vexpress";
	- LogicTile Express 13MG (V2F-2XV6) running Cortex-A7 (3 cores) SMM:
	compatible = "arm,vexpress,v2f-2xv6,ca7x3", \
	"arm,vexpress,v2f-2xv6", "arm,vexpress";

	Optional properties in the root node:
	- tile model name (use name from the tile's Technical Reference
	Manual, eg. "V2P-CA5s")
	model = "<model>";
	- tile's HBI number (unique ARM's board model ID, visible on the
	PCB's silkscreen) in hexadecimal transcription:
	arm,hbi = <0xhbi>
	eg:
	- for Coretile Express A5x2 (V2P-CA5s) HBI-0191:
	arm,hbi = <0x191>;
	- Coretile Express A9x4 (V2P-CA9) HBI-0225:
	arm,hbi = <0x225>;


	CPU nodes
	---------

	Top-level standard "cpus" node is required. It must contain a node
	with device_type = "cpu" property for every available core, eg.:

	cpus {
	#address-cells = <1>;
	#size-cells = <0>;

	cpu@0 {
	device_type = "cpu";
	compatible = "arm,cortex-a5";
	reg = <0>;
	};
	};


	Configuration infrastructure
	----------------------------

	The platform has an elaborated configuration system, consisting of
	microcontrollers residing on the mother- and daughterboards known
	as Motherboard/Daughterboard Configuration Controller (MCC and DCC).
	The controllers are responsible for the platform initialization
	(reset generation, flash programming, FPGA bitfiles loading etc.)
	but also control clock generators, voltage regulators, gather
	environmental data like temperature, power consumption etc. Even
	the video output switch (FPGA) is controlled that way.

	Nodes describing devices controlled by this infrastructure should
	point at the bridge device node:
	- bridge phandle:
	arm,vexpress,config-bridge = <phandle>;
	This property can be also defined in a parent node (eg. for a DCC)
	and is effective for all children.


	Platform topology
	-----------------

	As Versatile Express can be configured in number of physically
	different setups, the device tree should describe platform topology.
	Root node and main motherboard node must define the following
	property, describing physical location of the children nodes:
	- site number:
	arm,vexpress,site = <number>;
	where 0 means motherboard, 1 or 2 are daugtherboard sites,
	0xf means "master" site (site containing main CPU tile)
	- when daughterboards are stacked on one site, their position
	in the stack be be described with:
	arm,vexpress,position = <number>;
	- when describing tiles consisting more than one DCC, its number
	can be described with:
	arm,vexpress,dcc = <number>;

	Any of the numbers above defaults to zero if not defined in
	the node or any of its parent.


	Motherboard
	-----------

	The motherboard description file provides a single "motherboard" node
	using 2 address cells corresponding to the Static Memory Bus used
	between the motherboard and the tile. The first cell defines the Chip
	Select (CS) line number, the second cell address offset within the CS.
	All interrupt lines between the motherboard and the tile are active
	high and are described using single cell.

	Optional properties of the "motherboard" node:
	- motherboard's memory map variant:
	arm,v2m-memory-map = "<name>";
	where name is one of:
	- "rs1" - for RS1 map (i.a. peripherals on CS3); this map is also
	referred to as "ARM Cortex-A Series memory map":
	arm,v2m-memory-map = "rs1";
	When this property is missing, the motherboard is using the original
	memory map (also known as the "Legacy memory map", primarily used
	with the original CoreTile Express A9x4) with peripherals on CS7.

	Motherboard .dtsi files provide a set of labelled peripherals that
	can be used to obtain required phandle in the tile's "aliases" node:
	- UARTs, note that the numbers correspond to the physical connectors
	on the motherboard's back panel:
	v2m_serial0, v2m_serial1, v2m_serial2 and v2m_serial3
	- I2C controllers:
	v2m_i2c_dvi and v2m_i2c_pcie
	- SP804 timers:
	v2m_timer01 and v2m_timer23

	The tile description should define a "smb" node, describing the
	Static Memory Bus between the tile and motherboard. It must define
	the following properties:
	- "simple-bus" compatible value (to ensure creation of the children)
	compatible = "simple-bus";
	- mapping of the SMB CS/offset addresses into main address space:
	#address-cells = <2>;
	#size-cells = <1>;
	ranges = <...>;
	- interrupts mapping:
	#interrupt-cells = <1>;
	interrupt-map-mask = <0 0 63>;
	interrupt-map = <...>;


	Example of a VE tile description (simplified)
	---------------------------------------------

	/dts-v1/;

	/ {
	model = "V2P-CA5s";
	arm,hbi = <0x225>;
	arm,vexpress,site = <0xf>;
	compatible = "arm,vexpress-v2p-ca5s", "arm,vexpress";
	interrupt-parent = <&gic>;
	#address-cells = <1>;
	#size-cells = <1>;

	chosen { };

	aliases {
	serial0 = &v2m_serial0;
	};

	cpus {
	#address-cells = <1>;
	#size-cells = <0>;

	cpu@0 {
	device_type = "cpu";
	compatible = "arm,cortex-a5";
	reg = <0>;
	};
	};

	gic: interrupt-controller@2c001000 {
	compatible = "arm,cortex-a9-gic";
	#interrupt-cells = <3>;
	#address-cells = <0>;
	interrupt-controller;
	reg = <0x2c001000 0x1000>,
	<0x2c000100 0x100>;
	};

	dcc {
	compatible = "simple-bus";
	arm,vexpress,config-bridge = <&v2m_sysreg>;

	osc@0 {
	compatible = "arm,vexpress-osc";
	};
	};

	smb {
	compatible = "simple-bus";

	#address-cells = <2>;
	#size-cells = <1>;
	/* CS0 is visible at 0x08000000 */
	ranges = <0 0 0x08000000 0x04000000>;

	#interrupt-cells = <1>;
	interrupt-map-mask = <0 0 63>;
	/* Active high IRQ 0 is connected to GIC's SPI0 */
	interrupt-map = <0 0 0 &gic 0 0 4>;

	/include/ "vexpress-v2m-rs1.dtsi"
	};
	};