Merge tag 'devicetree-for-4.13' of git://git.kernel.org/pub/scm/linux/kernel/git...
[muen/linux.git] / Documentation / devicetree / bindings / arm / cpus.txt
1 =================
2 ARM CPUs bindings
3 =================
4
5 The device tree allows to describe the layout of CPUs in a system through
6 the "cpus" node, which in turn contains a number of subnodes (ie "cpu")
7 defining properties for every cpu.
8
9 Bindings for CPU nodes follow the Devicetree Specification, available from:
10
11 https://www.devicetree.org/specifications/
12
13 with updates for 32-bit and 64-bit ARM systems provided in this document.
14
15 ================================
16 Convention used in this document
17 ================================
18
19 This document follows the conventions described in the Devicetree
20 Specification, with the addition:
21
22 - square brackets define bitfields, eg reg[7:0] value of the bitfield in
23   the reg property contained in bits 7 down to 0
24
25 =====================================
26 cpus and cpu node bindings definition
27 =====================================
28
29 The ARM architecture, in accordance with the Devicetree Specification,
30 requires the cpus and cpu nodes to be present and contain the properties
31 described below.
32
33 - cpus node
34
35         Description: Container of cpu nodes
36
37         The node name must be "cpus".
38
39         A cpus node must define the following properties:
40
41         - #address-cells
42                 Usage: required
43                 Value type: <u32>
44
45                 Definition depends on ARM architecture version and
46                 configuration:
47
48                         # On uniprocessor ARM architectures previous to v7
49                           value must be 1, to enable a simple enumeration
50                           scheme for processors that do not have a HW CPU
51                           identification register.
52                         # On 32-bit ARM 11 MPcore, ARM v7 or later systems
53                           value must be 1, that corresponds to CPUID/MPIDR
54                           registers sizes.
55                         # On ARM v8 64-bit systems value should be set to 2,
56                           that corresponds to the MPIDR_EL1 register size.
57                           If MPIDR_EL1[63:32] value is equal to 0 on all CPUs
58                           in the system, #address-cells can be set to 1, since
59                           MPIDR_EL1[63:32] bits are not used for CPUs
60                           identification.
61         - #size-cells
62                 Usage: required
63                 Value type: <u32>
64                 Definition: must be set to 0
65
66 - cpu node
67
68         Description: Describes a CPU in an ARM based system
69
70         PROPERTIES
71
72         - device_type
73                 Usage: required
74                 Value type: <string>
75                 Definition: must be "cpu"
76         - reg
77                 Usage and definition depend on ARM architecture version and
78                 configuration:
79
80                         # On uniprocessor ARM architectures previous to v7
81                           this property is required and must be set to 0.
82
83                         # On ARM 11 MPcore based systems this property is
84                           required and matches the CPUID[11:0] register bits.
85
86                           Bits [11:0] in the reg cell must be set to
87                           bits [11:0] in CPU ID register.
88
89                           All other bits in the reg cell must be set to 0.
90
91                         # On 32-bit ARM v7 or later systems this property is
92                           required and matches the CPU MPIDR[23:0] register
93                           bits.
94
95                           Bits [23:0] in the reg cell must be set to
96                           bits [23:0] in MPIDR.
97
98                           All other bits in the reg cell must be set to 0.
99
100                         # On ARM v8 64-bit systems this property is required
101                           and matches the MPIDR_EL1 register affinity bits.
102
103                           * If cpus node's #address-cells property is set to 2
104
105                             The first reg cell bits [7:0] must be set to
106                             bits [39:32] of MPIDR_EL1.
107
108                             The second reg cell bits [23:0] must be set to
109                             bits [23:0] of MPIDR_EL1.
110
111                           * If cpus node's #address-cells property is set to 1
112
113                             The reg cell bits [23:0] must be set to bits [23:0]
114                             of MPIDR_EL1.
115
116                           All other bits in the reg cells must be set to 0.
117
118         - compatible:
119                 Usage: required
120                 Value type: <string>
121                 Definition: should be one of:
122                             "arm,arm710t"
123                             "arm,arm720t"
124                             "arm,arm740t"
125                             "arm,arm7ej-s"
126                             "arm,arm7tdmi"
127                             "arm,arm7tdmi-s"
128                             "arm,arm9es"
129                             "arm,arm9ej-s"
130                             "arm,arm920t"
131                             "arm,arm922t"
132                             "arm,arm925"
133                             "arm,arm926e-s"
134                             "arm,arm926ej-s"
135                             "arm,arm940t"
136                             "arm,arm946e-s"
137                             "arm,arm966e-s"
138                             "arm,arm968e-s"
139                             "arm,arm9tdmi"
140                             "arm,arm1020e"
141                             "arm,arm1020t"
142                             "arm,arm1022e"
143                             "arm,arm1026ej-s"
144                             "arm,arm1136j-s"
145                             "arm,arm1136jf-s"
146                             "arm,arm1156t2-s"
147                             "arm,arm1156t2f-s"
148                             "arm,arm1176jzf"
149                             "arm,arm1176jz-s"
150                             "arm,arm1176jzf-s"
151                             "arm,arm11mpcore"
152                             "arm,cortex-a5"
153                             "arm,cortex-a7"
154                             "arm,cortex-a8"
155                             "arm,cortex-a9"
156                             "arm,cortex-a12"
157                             "arm,cortex-a15"
158                             "arm,cortex-a17"
159                             "arm,cortex-a53"
160                             "arm,cortex-a57"
161                             "arm,cortex-a72"
162                             "arm,cortex-a73"
163                             "arm,cortex-m0"
164                             "arm,cortex-m0+"
165                             "arm,cortex-m1"
166                             "arm,cortex-m3"
167                             "arm,cortex-m4"
168                             "arm,cortex-r4"
169                             "arm,cortex-r5"
170                             "arm,cortex-r7"
171                             "brcm,brahma-b15"
172                             "brcm,vulcan"
173                             "cavium,thunder"
174                             "cavium,thunder2"
175                             "faraday,fa526"
176                             "intel,sa110"
177                             "intel,sa1100"
178                             "marvell,feroceon"
179                             "marvell,mohawk"
180                             "marvell,pj4a"
181                             "marvell,pj4b"
182                             "marvell,sheeva-v5"
183                             "nvidia,tegra132-denver"
184                             "nvidia,tegra186-denver"
185                             "qcom,krait"
186                             "qcom,kryo"
187                             "qcom,scorpion"
188         - enable-method
189                 Value type: <stringlist>
190                 Usage and definition depend on ARM architecture version.
191                         # On ARM v8 64-bit this property is required and must
192                           be one of:
193                              "psci"
194                              "spin-table"
195                         # On ARM 32-bit systems this property is optional and
196                           can be one of:
197                             "actions,s500-smp"
198                             "allwinner,sun6i-a31"
199                             "allwinner,sun8i-a23"
200                             "arm,realview-smp"
201                             "brcm,bcm11351-cpu-method"
202                             "brcm,bcm23550"
203                             "brcm,bcm-nsp-smp"
204                             "brcm,brahma-b15"
205                             "marvell,armada-375-smp"
206                             "marvell,armada-380-smp"
207                             "marvell,armada-390-smp"
208                             "marvell,armada-xp-smp"
209                             "marvell,98dx3236-smp"
210                             "mediatek,mt6589-smp"
211                             "mediatek,mt81xx-tz-smp"
212                             "qcom,gcc-msm8660"
213                             "qcom,kpss-acc-v1"
214                             "qcom,kpss-acc-v2"
215                             "renesas,apmu"
216                             "rockchip,rk3036-smp"
217                             "rockchip,rk3066-smp"
218                             "ste,dbx500-smp"
219
220         - cpu-release-addr
221                 Usage: required for systems that have an "enable-method"
222                        property value of "spin-table".
223                 Value type: <prop-encoded-array>
224                 Definition:
225                         # On ARM v8 64-bit systems must be a two cell
226                           property identifying a 64-bit zero-initialised
227                           memory location.
228
229         - qcom,saw
230                 Usage: required for systems that have an "enable-method"
231                        property value of "qcom,kpss-acc-v1" or
232                        "qcom,kpss-acc-v2"
233                 Value type: <phandle>
234                 Definition: Specifies the SAW[1] node associated with this CPU.
235
236         - qcom,acc
237                 Usage: required for systems that have an "enable-method"
238                        property value of "qcom,kpss-acc-v1" or
239                        "qcom,kpss-acc-v2"
240                 Value type: <phandle>
241                 Definition: Specifies the ACC[2] node associated with this CPU.
242
243         - cpu-idle-states
244                 Usage: Optional
245                 Value type: <prop-encoded-array>
246                 Definition:
247                         # List of phandles to idle state nodes supported
248                           by this cpu [3].
249
250         - capacity-dmips-mhz
251                 Usage: Optional
252                 Value type: <u32>
253                 Definition:
254                         # u32 value representing CPU capacity [4] in
255                           DMIPS/MHz, relative to highest capacity-dmips-mhz
256                           in the system.
257
258         - rockchip,pmu
259                 Usage: optional for systems that have an "enable-method"
260                        property value of "rockchip,rk3066-smp"
261                        While optional, it is the preferred way to get access to
262                        the cpu-core power-domains.
263                 Value type: <phandle>
264                 Definition: Specifies the syscon node controlling the cpu core
265                             power domains.
266
267         - dynamic-power-coefficient
268                 Usage: optional
269                 Value type: <prop-encoded-array>
270                 Definition: A u32 value that represents the running time dynamic
271                             power coefficient in units of mW/MHz/uV^2. The
272                             coefficient can either be calculated from power
273                             measurements or derived by analysis.
274
275                             The dynamic power consumption of the CPU  is
276                             proportional to the square of the Voltage (V) and
277                             the clock frequency (f). The coefficient is used to
278                             calculate the dynamic power as below -
279
280                             Pdyn = dynamic-power-coefficient * V^2 * f
281
282                             where voltage is in uV, frequency is in MHz.
283
284 Example 1 (dual-cluster big.LITTLE system 32-bit):
285
286         cpus {
287                 #size-cells = <0>;
288                 #address-cells = <1>;
289
290                 cpu@0 {
291                         device_type = "cpu";
292                         compatible = "arm,cortex-a15";
293                         reg = <0x0>;
294                 };
295
296                 cpu@1 {
297                         device_type = "cpu";
298                         compatible = "arm,cortex-a15";
299                         reg = <0x1>;
300                 };
301
302                 cpu@100 {
303                         device_type = "cpu";
304                         compatible = "arm,cortex-a7";
305                         reg = <0x100>;
306                 };
307
308                 cpu@101 {
309                         device_type = "cpu";
310                         compatible = "arm,cortex-a7";
311                         reg = <0x101>;
312                 };
313         };
314
315 Example 2 (Cortex-A8 uniprocessor 32-bit system):
316
317         cpus {
318                 #size-cells = <0>;
319                 #address-cells = <1>;
320
321                 cpu@0 {
322                         device_type = "cpu";
323                         compatible = "arm,cortex-a8";
324                         reg = <0x0>;
325                 };
326         };
327
328 Example 3 (ARM 926EJ-S uniprocessor 32-bit system):
329
330         cpus {
331                 #size-cells = <0>;
332                 #address-cells = <1>;
333
334                 cpu@0 {
335                         device_type = "cpu";
336                         compatible = "arm,arm926ej-s";
337                         reg = <0x0>;
338                 };
339         };
340
341 Example 4 (ARM Cortex-A57 64-bit system):
342
343 cpus {
344         #size-cells = <0>;
345         #address-cells = <2>;
346
347         cpu@0 {
348                 device_type = "cpu";
349                 compatible = "arm,cortex-a57";
350                 reg = <0x0 0x0>;
351                 enable-method = "spin-table";
352                 cpu-release-addr = <0 0x20000000>;
353         };
354
355         cpu@1 {
356                 device_type = "cpu";
357                 compatible = "arm,cortex-a57";
358                 reg = <0x0 0x1>;
359                 enable-method = "spin-table";
360                 cpu-release-addr = <0 0x20000000>;
361         };
362
363         cpu@100 {
364                 device_type = "cpu";
365                 compatible = "arm,cortex-a57";
366                 reg = <0x0 0x100>;
367                 enable-method = "spin-table";
368                 cpu-release-addr = <0 0x20000000>;
369         };
370
371         cpu@101 {
372                 device_type = "cpu";
373                 compatible = "arm,cortex-a57";
374                 reg = <0x0 0x101>;
375                 enable-method = "spin-table";
376                 cpu-release-addr = <0 0x20000000>;
377         };
378
379         cpu@10000 {
380                 device_type = "cpu";
381                 compatible = "arm,cortex-a57";
382                 reg = <0x0 0x10000>;
383                 enable-method = "spin-table";
384                 cpu-release-addr = <0 0x20000000>;
385         };
386
387         cpu@10001 {
388                 device_type = "cpu";
389                 compatible = "arm,cortex-a57";
390                 reg = <0x0 0x10001>;
391                 enable-method = "spin-table";
392                 cpu-release-addr = <0 0x20000000>;
393         };
394
395         cpu@10100 {
396                 device_type = "cpu";
397                 compatible = "arm,cortex-a57";
398                 reg = <0x0 0x10100>;
399                 enable-method = "spin-table";
400                 cpu-release-addr = <0 0x20000000>;
401         };
402
403         cpu@10101 {
404                 device_type = "cpu";
405                 compatible = "arm,cortex-a57";
406                 reg = <0x0 0x10101>;
407                 enable-method = "spin-table";
408                 cpu-release-addr = <0 0x20000000>;
409         };
410
411         cpu@100000000 {
412                 device_type = "cpu";
413                 compatible = "arm,cortex-a57";
414                 reg = <0x1 0x0>;
415                 enable-method = "spin-table";
416                 cpu-release-addr = <0 0x20000000>;
417         };
418
419         cpu@100000001 {
420                 device_type = "cpu";
421                 compatible = "arm,cortex-a57";
422                 reg = <0x1 0x1>;
423                 enable-method = "spin-table";
424                 cpu-release-addr = <0 0x20000000>;
425         };
426
427         cpu@100000100 {
428                 device_type = "cpu";
429                 compatible = "arm,cortex-a57";
430                 reg = <0x1 0x100>;
431                 enable-method = "spin-table";
432                 cpu-release-addr = <0 0x20000000>;
433         };
434
435         cpu@100000101 {
436                 device_type = "cpu";
437                 compatible = "arm,cortex-a57";
438                 reg = <0x1 0x101>;
439                 enable-method = "spin-table";
440                 cpu-release-addr = <0 0x20000000>;
441         };
442
443         cpu@100010000 {
444                 device_type = "cpu";
445                 compatible = "arm,cortex-a57";
446                 reg = <0x1 0x10000>;
447                 enable-method = "spin-table";
448                 cpu-release-addr = <0 0x20000000>;
449         };
450
451         cpu@100010001 {
452                 device_type = "cpu";
453                 compatible = "arm,cortex-a57";
454                 reg = <0x1 0x10001>;
455                 enable-method = "spin-table";
456                 cpu-release-addr = <0 0x20000000>;
457         };
458
459         cpu@100010100 {
460                 device_type = "cpu";
461                 compatible = "arm,cortex-a57";
462                 reg = <0x1 0x10100>;
463                 enable-method = "spin-table";
464                 cpu-release-addr = <0 0x20000000>;
465         };
466
467         cpu@100010101 {
468                 device_type = "cpu";
469                 compatible = "arm,cortex-a57";
470                 reg = <0x1 0x10101>;
471                 enable-method = "spin-table";
472                 cpu-release-addr = <0 0x20000000>;
473         };
474 };
475
476 --
477 [1] arm/msm/qcom,saw2.txt
478 [2] arm/msm/qcom,kpss-acc.txt
479 [3] ARM Linux kernel documentation - idle states bindings
480     Documentation/devicetree/bindings/arm/idle-states.txt
481 [4] ARM Linux kernel documentation - cpu capacity bindings
482     Documentation/devicetree/bindings/arm/cpu-capacity.txt