Documentation/devicetree/bindings/arm/vexpress.txt

   1 ARM Versatile Express boards family
   2 -----------------------------------
   3
   4 ARM's Versatile Express platform consists of a motherboard and one
   5 or more daughterboards (tiles). The motherboard provides a set of
   6 peripherals. Processor and RAM "live" on the tiles.
   7
   8 The motherboard and each core tile should be described by a separate
   9 Device Tree source file, with the tile's description including
  10 the motherboard file using a /include/ directive. As the motherboard
  11 can be initialized in one of two different configurations ("memory
  12 maps"), care must be taken to include the correct one.
  13
  14
  15 Root node
  16 ---------
  17
  18 Required 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
  39 Optional 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
  53 CPU nodes
  54 ---------
  55
  56 Top-level standard "cpus" node is required. It must contain a node
  57 with 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
  71 Configuration infrastructure
  72 ----------------------------
  73
  74 The platform has an elaborated configuration system, consisting of
  75 microcontrollers residing on the mother- and daughterboards known
  76 as Motherboard/Daughterboard Configuration Controller (MCC and DCC).
  77 The controllers are responsible for the platform initialization
  78 (reset generation, flash programming, FPGA bitfiles loading etc.)
  79 but also control clock generators, voltage regulators, gather
  80 environmental data like temperature, power consumption etc. Even
  81 the video output switch (FPGA) is controlled that way.
  82
  83 The controllers are not mapped into normal memory address space
  84 and must be accessed through bridges - other devices capable
  85 of generating transactions on the configuration bus.
  86
  87 The nodes describing configuration controllers must define
  88 the following properties:
  89 - compatible value:
  90         compatible = "arm,vexpress,config-bus";
  91 - bridge phandle:
  92         arm,vexpress,config-bridge = <phandle>;
  93 and children describing available functions.
  94
  95
  96 Platform topology
  97 -----------------
  98
  99 As Versatile Express can be configured in number of physically
 100 different setups, the device tree should describe platform topology.
 101 Root node and main motherboard node must define the following
 102 property, 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
 114 Any of the numbers above defaults to zero if not defined in
 115 the node or any of its parent.
 116
 117
 118 Motherboard
 119 -----------
 120
 121 The motherboard description file provides a single "motherboard" node
 122 using 2 address cells corresponding to the Static Memory Bus used
 123 between the motherboard and the tile. The first cell defines the Chip
 124 Select (CS) line number, the second cell address offset within the CS.
 125 All interrupt lines between the motherboard and the tile are active
 126 high and are described using single cell.
 127
 128 Optional 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
 139 Motherboard .dtsi files provide a set of labelled peripherals that
 140 can 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
 149 The tile description should define a "smb" node, describing the
 150 Static Memory Bus between the tile and motherboard. It must define
 151 the 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
 164 Example 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