283c520a2224347051cf81bb9be7a02d13887e19
[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                             "allwinner,sun6i-a31"
198                             "allwinner,sun8i-a23"
199                             "arm,realview-smp"
200                             "brcm,bcm11351-cpu-method"
201                             "brcm,bcm23550"
202                             "brcm,bcm-nsp-smp"
203                             "brcm,brahma-b15"
204                             "marvell,armada-375-smp"
205                             "marvell,armada-380-smp"
206                             "marvell,armada-390-smp"
207                             "marvell,armada-xp-smp"
208                             "marvell,98dx3236-smp"
209                             "mediatek,mt6589-smp"
210                             "mediatek,mt81xx-tz-smp"
211                             "qcom,gcc-msm8660"
212                             "qcom,kpss-acc-v1"
213                             "qcom,kpss-acc-v2"
214                             "renesas,apmu"
215                             "rockchip,rk3036-smp"
216                             "rockchip,rk3066-smp"
217                             "ste,dbx500-smp"
218
219         - cpu-release-addr
220                 Usage: required for systems that have an "enable-method"
221                        property value of "spin-table".
222                 Value type: <prop-encoded-array>
223                 Definition:
224                         # On ARM v8 64-bit systems must be a two cell
225                           property identifying a 64-bit zero-initialised
226                           memory location.
227
228         - qcom,saw
229                 Usage: required for systems that have an "enable-method"
230                        property value of "qcom,kpss-acc-v1" or
231                        "qcom,kpss-acc-v2"
232                 Value type: <phandle>
233                 Definition: Specifies the SAW[1] node associated with this CPU.
234
235         - qcom,acc
236                 Usage: required for systems that have an "enable-method"
237                        property value of "qcom,kpss-acc-v1" or
238                        "qcom,kpss-acc-v2"
239                 Value type: <phandle>
240                 Definition: Specifies the ACC[2] node associated with this CPU.
241
242         - cpu-idle-states
243                 Usage: Optional
244                 Value type: <prop-encoded-array>
245                 Definition:
246                         # List of phandles to idle state nodes supported
247                           by this cpu [3].
248
249         - capacity-dmips-mhz
250                 Usage: Optional
251                 Value type: <u32>
252                 Definition:
253                         # u32 value representing CPU capacity [3] in
254                           DMIPS/MHz, relative to highest capacity-dmips-mhz
255                           in the system.
256
257         - rockchip,pmu
258                 Usage: optional for systems that have an "enable-method"
259                        property value of "rockchip,rk3066-smp"
260                        While optional, it is the preferred way to get access to
261                        the cpu-core power-domains.
262                 Value type: <phandle>
263                 Definition: Specifies the syscon node controlling the cpu core
264                             power domains.
265
266         - dynamic-power-coefficient
267                 Usage: optional
268                 Value type: <prop-encoded-array>
269                 Definition: A u32 value that represents the running time dynamic
270                             power coefficient in units of mW/MHz/uV^2. The
271                             coefficient can either be calculated from power
272                             measurements or derived by analysis.
273
274                             The dynamic power consumption of the CPU  is
275                             proportional to the square of the Voltage (V) and
276                             the clock frequency (f). The coefficient is used to
277                             calculate the dynamic power as below -
278
279                             Pdyn = dynamic-power-coefficient * V^2 * f
280
281                             where voltage is in uV, frequency is in MHz.
282
283 Example 1 (dual-cluster big.LITTLE system 32-bit):
284
285         cpus {
286                 #size-cells = <0>;
287                 #address-cells = <1>;
288
289                 cpu@0 {
290                         device_type = "cpu";
291                         compatible = "arm,cortex-a15";
292                         reg = <0x0>;
293                 };
294
295                 cpu@1 {
296                         device_type = "cpu";
297                         compatible = "arm,cortex-a15";
298                         reg = <0x1>;
299                 };
300
301                 cpu@100 {
302                         device_type = "cpu";
303                         compatible = "arm,cortex-a7";
304                         reg = <0x100>;
305                 };
306
307                 cpu@101 {
308                         device_type = "cpu";
309                         compatible = "arm,cortex-a7";
310                         reg = <0x101>;
311                 };
312         };
313
314 Example 2 (Cortex-A8 uniprocessor 32-bit system):
315
316         cpus {
317                 #size-cells = <0>;
318                 #address-cells = <1>;
319
320                 cpu@0 {
321                         device_type = "cpu";
322                         compatible = "arm,cortex-a8";
323                         reg = <0x0>;
324                 };
325         };
326
327 Example 3 (ARM 926EJ-S uniprocessor 32-bit system):
328
329         cpus {
330                 #size-cells = <0>;
331                 #address-cells = <1>;
332
333                 cpu@0 {
334                         device_type = "cpu";
335                         compatible = "arm,arm926ej-s";
336                         reg = <0x0>;
337                 };
338         };
339
340 Example 4 (ARM Cortex-A57 64-bit system):
341
342 cpus {
343         #size-cells = <0>;
344         #address-cells = <2>;
345
346         cpu@0 {
347                 device_type = "cpu";
348                 compatible = "arm,cortex-a57";
349                 reg = <0x0 0x0>;
350                 enable-method = "spin-table";
351                 cpu-release-addr = <0 0x20000000>;
352         };
353
354         cpu@1 {
355                 device_type = "cpu";
356                 compatible = "arm,cortex-a57";
357                 reg = <0x0 0x1>;
358                 enable-method = "spin-table";
359                 cpu-release-addr = <0 0x20000000>;
360         };
361
362         cpu@100 {
363                 device_type = "cpu";
364                 compatible = "arm,cortex-a57";
365                 reg = <0x0 0x100>;
366                 enable-method = "spin-table";
367                 cpu-release-addr = <0 0x20000000>;
368         };
369
370         cpu@101 {
371                 device_type = "cpu";
372                 compatible = "arm,cortex-a57";
373                 reg = <0x0 0x101>;
374                 enable-method = "spin-table";
375                 cpu-release-addr = <0 0x20000000>;
376         };
377
378         cpu@10000 {
379                 device_type = "cpu";
380                 compatible = "arm,cortex-a57";
381                 reg = <0x0 0x10000>;
382                 enable-method = "spin-table";
383                 cpu-release-addr = <0 0x20000000>;
384         };
385
386         cpu@10001 {
387                 device_type = "cpu";
388                 compatible = "arm,cortex-a57";
389                 reg = <0x0 0x10001>;
390                 enable-method = "spin-table";
391                 cpu-release-addr = <0 0x20000000>;
392         };
393
394         cpu@10100 {
395                 device_type = "cpu";
396                 compatible = "arm,cortex-a57";
397                 reg = <0x0 0x10100>;
398                 enable-method = "spin-table";
399                 cpu-release-addr = <0 0x20000000>;
400         };
401
402         cpu@10101 {
403                 device_type = "cpu";
404                 compatible = "arm,cortex-a57";
405                 reg = <0x0 0x10101>;
406                 enable-method = "spin-table";
407                 cpu-release-addr = <0 0x20000000>;
408         };
409
410         cpu@100000000 {
411                 device_type = "cpu";
412                 compatible = "arm,cortex-a57";
413                 reg = <0x1 0x0>;
414                 enable-method = "spin-table";
415                 cpu-release-addr = <0 0x20000000>;
416         };
417
418         cpu@100000001 {
419                 device_type = "cpu";
420                 compatible = "arm,cortex-a57";
421                 reg = <0x1 0x1>;
422                 enable-method = "spin-table";
423                 cpu-release-addr = <0 0x20000000>;
424         };
425
426         cpu@100000100 {
427                 device_type = "cpu";
428                 compatible = "arm,cortex-a57";
429                 reg = <0x1 0x100>;
430                 enable-method = "spin-table";
431                 cpu-release-addr = <0 0x20000000>;
432         };
433
434         cpu@100000101 {
435                 device_type = "cpu";
436                 compatible = "arm,cortex-a57";
437                 reg = <0x1 0x101>;
438                 enable-method = "spin-table";
439                 cpu-release-addr = <0 0x20000000>;
440         };
441
442         cpu@100010000 {
443                 device_type = "cpu";
444                 compatible = "arm,cortex-a57";
445                 reg = <0x1 0x10000>;
446                 enable-method = "spin-table";
447                 cpu-release-addr = <0 0x20000000>;
448         };
449
450         cpu@100010001 {
451                 device_type = "cpu";
452                 compatible = "arm,cortex-a57";
453                 reg = <0x1 0x10001>;
454                 enable-method = "spin-table";
455                 cpu-release-addr = <0 0x20000000>;
456         };
457
458         cpu@100010100 {
459                 device_type = "cpu";
460                 compatible = "arm,cortex-a57";
461                 reg = <0x1 0x10100>;
462                 enable-method = "spin-table";
463                 cpu-release-addr = <0 0x20000000>;
464         };
465
466         cpu@100010101 {
467                 device_type = "cpu";
468                 compatible = "arm,cortex-a57";
469                 reg = <0x1 0x10101>;
470                 enable-method = "spin-table";
471                 cpu-release-addr = <0 0x20000000>;
472         };
473 };
474
475 --
476 [1] arm/msm/qcom,saw2.txt
477 [2] arm/msm/qcom,kpss-acc.txt
478 [3] ARM Linux kernel documentation - idle states bindings
479     Documentation/devicetree/bindings/arm/idle-states.txt
480 [3] ARM Linux kernel documentation - cpu capacity bindings
481     Documentation/devicetree/bindings/arm/cpu-capacity.txt