1ARM Versatile Express boards family
2-----------------------------------
3
4ARM's Versatile Express platform consists of a motherboard and one
5or more daughterboards (tiles). The motherboard provides a set of
6peripherals. Processor and RAM "live" on the tiles.
7
8The motherboard and each core tile should be described by a separate
9Device Tree source file, with the tile's description including
10the motherboard file using a /include/ directive. As the motherboard
11can be initialized in one of two different configurations ("memory
12maps"), care must be taken to include the correct one.
13
14
15Root node
16---------
17
18Required properties in the root node:
19- compatible value:
20	compatible = "arm,vexpress,<model>", "arm,vexpress";
21  where <model> is the full tile model name (as used in the tile's
22    Technical Reference Manual), eg.:
23    - for Coretile Express A5x2 (V2P-CA5s):
24	compatible = "arm,vexpress,v2p-ca5s", "arm,vexpress";
25    - for Coretile Express A9x4 (V2P-CA9):
26	compatible = "arm,vexpress,v2p-ca9", "arm,vexpress";
27  If a tile comes in several variants or can be used in more then one
28  configuration, the compatible value should be:
29	compatible = "arm,vexpress,<model>,<variant>", \
30				"arm,vexpress,<model>", "arm,vexpress";
31  eg:
32    - Coretile Express A15x2 (V2P-CA15) with Tech Chip 1:
33	compatible = "arm,vexpress,v2p-ca15,tc1", \
34				"arm,vexpress,v2p-ca15", "arm,vexpress";
35    - LogicTile Express 13MG (V2F-2XV6) running Cortex-A7 (3 cores) SMM:
36	compatible = "arm,vexpress,v2f-2xv6,ca7x3", \
37				"arm,vexpress,v2f-2xv6", "arm,vexpress";
38
39Optional properties in the root node:
40- tile model name (use name from the tile's Technical Reference
41  Manual, eg. "V2P-CA5s")
42	model = "<model>";
43- tile's HBI number (unique ARM's board model ID, visible on the
44  PCB's silkscreen) in hexadecimal transcription:
45	arm,hbi = <0xhbi>
46  eg:
47  - for Coretile Express A5x2 (V2P-CA5s) HBI-0191:
48	arm,hbi = <0x191>;
49  - Coretile Express A9x4 (V2P-CA9) HBI-0225:
50	arm,hbi = <0x225>;
51
52
53CPU nodes
54---------
55
56Top-level standard "cpus" node is required. It must contain a node
57with device_type = "cpu" property for every available core, eg.:
58
59	cpus {
60		#address-cells = <1>;
61		#size-cells = <0>;
62
63		cpu@0 {
64			device_type = "cpu";
65			compatible = "arm,cortex-a5";
66			reg = <0>;
67		};
68	};
69
70
71Configuration infrastructure
72----------------------------
73
74The platform has an elaborated configuration system, consisting of
75microcontrollers residing on the mother- and daughterboards known
76as Motherboard/Daughterboard Configuration Controller (MCC and DCC).
77The controllers are responsible for the platform initialization
78(reset generation, flash programming, FPGA bitfiles loading etc.)
79but also control clock generators, voltage regulators, gather
80environmental data like temperature, power consumption etc. Even
81the video output switch (FPGA) is controlled that way.
82
83The controllers are not mapped into normal memory address space
84and must be accessed through bridges - other devices capable
85of generating transactions on the configuration bus.
86
87The nodes describing configuration controllers must define
88the following properties:
89- compatible value:
90	compatible = "arm,vexpress,config-bus";
91- bridge phandle:
92	arm,vexpress,config-bridge = <phandle>;
93and children describing available functions.
94
95
96Platform topology
97-----------------
98
99As Versatile Express can be configured in number of physically
100different setups, the device tree should describe platform topology.
101Root node and main motherboard node must define the following
102property, describing physical location of the children nodes:
103- site number:
104	arm,vexpress,site = <number>;
105  where 0 means motherboard, 1 or 2 are daugtherboard sites,
106  0xf means "master" site (site containing main CPU tile)
107- when daughterboards are stacked on one site, their position
108  in the stack be be described with:
109	arm,vexpress,position = <number>;
110- when describing tiles consisting more than one DCC, its number
111  can be described with:
112	arm,vexpress,dcc = <number>;
113
114Any of the numbers above defaults to zero if not defined in
115the node or any of its parent.
116
117
118Motherboard
119-----------
120
121The motherboard description file provides a single "motherboard" node
122using 2 address cells corresponding to the Static Memory Bus used
123between the motherboard and the tile. The first cell defines the Chip
124Select (CS) line number, the second cell address offset within the CS.
125All interrupt lines between the motherboard and the tile are active
126high and are described using single cell.
127
128Optional properties of the "motherboard" node:
129- motherboard's memory map variant:
130	arm,v2m-memory-map = "<name>";
131  where name is one of:
132  - "rs1" - for RS1 map (i.a. peripherals on CS3); this map is also
133            referred to as "ARM Cortex-A Series memory map":
134	arm,v2m-memory-map = "rs1";
135  When this property is missing, the motherboard is using the original
136  memory map (also known as the "Legacy memory map", primarily used
137  with the original CoreTile Express A9x4) with peripherals on CS7.
138
139Motherboard .dtsi files provide a set of labelled peripherals that
140can be used to obtain required phandle in the tile's "aliases" node:
141- UARTs, note that the numbers correspond to the physical connectors
142  on the motherboard's back panel:
143	v2m_serial0, v2m_serial1, v2m_serial2 and v2m_serial3
144- I2C controllers:
145	v2m_i2c_dvi and v2m_i2c_pcie
146- SP804 timers:
147	v2m_timer01 and v2m_timer23
148
149The tile description should define a "smb" node, describing the
150Static Memory Bus between the tile and motherboard. It must define
151the following properties:
152- "simple-bus" compatible value (to ensure creation of the children)
153	compatible = "simple-bus";
154- mapping of the SMB CS/offset addresses into main address space:
155	#address-cells = <2>;
156	#size-cells = <1>;
157	ranges = <...>;
158- interrupts mapping:
159	#interrupt-cells = <1>;
160	interrupt-map-mask = <0 0 63>;
161	interrupt-map = <...>;
162
163
164Example of a VE tile description (simplified)
165---------------------------------------------
166
167/dts-v1/;
168
169/ {
170	model = "V2P-CA5s";
171	arm,hbi = <0x225>;
172	arm,vexpress,site = <0xf>;
173	compatible = "arm,vexpress-v2p-ca5s", "arm,vexpress";
174	interrupt-parent = <&gic>;
175	#address-cells = <1>;
176	#size-cells = <1>;
177
178	chosen { };
179
180	aliases {
181		serial0 = &v2m_serial0;
182	};
183
184	cpus {
185		#address-cells = <1>;
186		#size-cells = <0>;
187
188		cpu@0 {
189			device_type = "cpu";
190			compatible = "arm,cortex-a5";
191			reg = <0>;
192		};
193	};
194
195	gic: interrupt-controller@2c001000 {
196		compatible = "arm,cortex-a9-gic";
197		#interrupt-cells = <3>;
198		#address-cells = <0>;
199		interrupt-controller;
200		reg = <0x2c001000 0x1000>,
201		      <0x2c000100 0x100>;
202	};
203
204	dcc {
205		compatible = "arm,vexpress,config-bus";
206		arm,vexpress,config-bridge = <&v2m_sysreg>;
207
208		osc@0 {
209			compatible = "arm,vexpress-osc";
210		};
211	};
212
213	smb {
214		compatible = "simple-bus";
215
216		#address-cells = <2>;
217		#size-cells = <1>;
218		/* CS0 is visible at 0x08000000 */
219		ranges = <0 0 0x08000000 0x04000000>;
220
221		#interrupt-cells = <1>;
222		interrupt-map-mask = <0 0 63>;
223		/* Active high IRQ 0 is connected to GIC's SPI0 */
224		interrupt-map = <0 0 0 &gic 0 0 4>;
225
226		/include/ "vexpress-v2m-rs1.dtsi"
227	};
228};
229
230