1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2 %YAML 1.2
3 ---
4 $id: http://devicetree.org/schemas/arm/idle-states.yaml#
5 $schema: http://devicetree.org/meta-schemas/core.yaml#
6
7 title: ARM idle states binding description
8
9 maintainers:
10 - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
11
12 description: |+
13 ==========================================
14 1 - Introduction
15 ==========================================
16
17 ARM systems contain HW capable of managing power consumption dynamically,
18 where cores can be put in different low-power states (ranging from simple wfi
19 to power gating) according to OS PM policies. The CPU states representing the
20 range of dynamic idle states that a processor can enter at run-time, can be
21 specified through device tree bindings representing the parameters required to
22 enter/exit specific idle states on a given processor.
23
24 According to the Server Base System Architecture document (SBSA, [3]), the
25 power states an ARM CPU can be put into are identified by the following list:
26
27 - Running
28 - Idle_standby
29 - Idle_retention
30 - Sleep
31 - Off
32
33 The power states described in the SBSA document define the basic CPU states on
34 top of which ARM platforms implement power management schemes that allow an OS
35 PM implementation to put the processor in different idle states (which include
36 states listed above; "off" state is not an idle state since it does not have
37 wake-up capabilities, hence it is not considered in this document).
38
39 Idle state parameters (e.g. entry latency) are platform specific and need to
40 be characterized with bindings that provide the required information to OS PM
41 code so that it can build the required tables and use them at runtime.
42
43 The device tree binding definition for ARM idle states is the subject of this
44 document.
45
46 ===========================================
47 2 - idle-states definitions
48 ===========================================
49
50 Idle states are characterized for a specific system through a set of
51 timing and energy related properties, that underline the HW behaviour
52 triggered upon idle states entry and exit.
53
54 The following diagram depicts the CPU execution phases and related timing
55 properties required to enter and exit an idle state:
56
57 ..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__..
58 | | | | |
59
60 |<------ entry ------->|
61 | latency |
62 |<- exit ->|
63 | latency |
64 |<-------- min-residency -------->|
65 |<------- wakeup-latency ------->|
66
67 Diagram 1: CPU idle state execution phases
68
69 EXEC: Normal CPU execution.
70
71 PREP: Preparation phase before committing the hardware to idle mode
72 like cache flushing. This is abortable on pending wake-up
73 event conditions. The abort latency is assumed to be negligible
74 (i.e. less than the ENTRY + EXIT duration). If aborted, CPU
75 goes back to EXEC. This phase is optional. If not abortable,
76 this should be included in the ENTRY phase instead.
77
78 ENTRY: The hardware is committed to idle mode. This period must run
79 to completion up to IDLE before anything else can happen.
80
81 IDLE: This is the actual energy-saving idle period. This may last
82 between 0 and infinite time, until a wake-up event occurs.
83
84 EXIT: Period during which the CPU is brought back to operational
85 mode (EXEC).
86
87 entry-latency: Worst case latency required to enter the idle state. The
88 exit-latency may be guaranteed only after entry-latency has passed.
89
90 min-residency: Minimum period, including preparation and entry, for a given
91 idle state to be worthwhile energywise.
92
93 wakeup-latency: Maximum delay between the signaling of a wake-up event and the
94 CPU being able to execute normal code again. If not specified, this is assumed
95 to be entry-latency + exit-latency.
96
97 These timing parameters can be used by an OS in different circumstances.
98
99 An idle CPU requires the expected min-residency time to select the most
100 appropriate idle state based on the expected expiry time of the next IRQ
101 (i.e. wake-up) that causes the CPU to return to the EXEC phase.
102
103 An operating system scheduler may need to compute the shortest wake-up delay
104 for CPUs in the system by detecting how long will it take to get a CPU out
105 of an idle state, e.g.:
106
107 wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0)
108
109 In other words, the scheduler can make its scheduling decision by selecting
110 (e.g. waking-up) the CPU with the shortest wake-up delay.
111 The wake-up delay must take into account the entry latency if that period
112 has not expired. The abortable nature of the PREP period can be ignored
113 if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than
114 the worst case since it depends on the CPU operating conditions, i.e. caches
115 state).
116
117 An OS has to reliably probe the wakeup-latency since some devices can enforce
118 latency constraint guarantees to work properly, so the OS has to detect the
119 worst case wake-up latency it can incur if a CPU is allowed to enter an
120 idle state, and possibly to prevent that to guarantee reliable device
121 functioning.
122
123 The min-residency time parameter deserves further explanation since it is
124 expressed in time units but must factor in energy consumption coefficients.
125
126 The energy consumption of a cpu when it enters a power state can be roughly
127 characterised by the following graph:
128
129 |
130 |
131 |
132 e |
133 n | /---
134 e | /------
135 r | /------
136 g | /-----
137 y | /------
138 | ----
139 | /|
140 | / |
141 | / |
142 | / |
143 | / |
144 | / |
145 |/ |
146 -----|-------+----------------------------------
147 0| 1 time(ms)
148
149 Graph 1: Energy vs time example
150
151 The graph is split in two parts delimited by time 1ms on the X-axis.
152 The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope
153 and denotes the energy costs incurred while entering and leaving the idle
154 state.
155 The graph curve in the area delimited by X-axis values = {x | x > 1ms } has
156 shallower slope and essentially represents the energy consumption of the idle
157 state.
158
159 min-residency is defined for a given idle state as the minimum expected
160 residency time for a state (inclusive of preparation and entry) after
161 which choosing that state become the most energy efficient option. A good
162 way to visualise this, is by taking the same graph above and comparing some
163 states energy consumptions plots.
164
165 For sake of simplicity, let's consider a system with two idle states IDLE1,
166 and IDLE2:
167
168 |
169 |
170 |
171 | /-- IDLE1
172 e | /---
173 n | /----
174 e | /---
175 r | /-----/--------- IDLE2
176 g | /-------/---------
177 y | ------------ /---|
178 | / /---- |
179 | / /--- |
180 | / /---- |
181 | / /--- |
182 | --- |
183 | / |
184 | / |
185 |/ | time
186 ---/----------------------------+------------------------
187 |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy
188 |
189 IDLE2-min-residency
190
191 Graph 2: idle states min-residency example
192
193 In graph 2 above, that takes into account idle states entry/exit energy
194 costs, it is clear that if the idle state residency time (i.e. time till next
195 wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state
196 choice energywise.
197
198 This is mainly down to the fact that IDLE1 entry/exit energy costs are lower
199 than IDLE2.
200
201 However, the lower power consumption (i.e. shallower energy curve slope) of
202 idle state IDLE2 implies that after a suitable time, IDLE2 becomes more energy
203 efficient.
204
205 The time at which IDLE2 becomes more energy efficient than IDLE1 (and other
206 shallower states in a system with multiple idle states) is defined
207 IDLE2-min-residency and corresponds to the time when energy consumption of
208 IDLE1 and IDLE2 states breaks even.
209
210 The definitions provided in this section underpin the idle states
211 properties specification that is the subject of the following sections.
212
213 ===========================================
214 3 - idle-states node
215 ===========================================
216
217 ARM processor idle states are defined within the idle-states node, which is
218 a direct child of the cpus node [1] and provides a container where the
219 processor idle states, defined as device tree nodes, are listed.
220
221 On ARM systems, it is a container of processor idle states nodes. If the
222 system does not provide CPU power management capabilities, or the processor
223 just supports idle_standby, an idle-states node is not required.
224
225 ===========================================
226 4 - References
227 ===========================================
228
229 [1] ARM Linux Kernel documentation - CPUs bindings
230 Documentation/devicetree/bindings/arm/cpus.yaml
231
232 [2] ARM Linux Kernel documentation - PSCI bindings
233 Documentation/devicetree/bindings/arm/psci.yaml
234
235 [3] ARM Server Base System Architecture (SBSA)
236 http://infocenter.arm.com/help/index.jsp
237
238 [4] ARM Architecture Reference Manuals
239 http://infocenter.arm.com/help/index.jsp
240
241 [6] ARM Linux Kernel documentation - Booting AArch64 Linux
242 Documentation/arm64/booting.rst
243
244 properties:
245 $nodename:
246 const: idle-states
247
248 entry-method:
249 description: |
250 Usage and definition depend on ARM architecture version.
251
252 On ARM v8 64-bit this property is required.
253 On ARM 32-bit systems this property is optional
254
255 This assumes that the "enable-method" property is set to "psci" in the cpu
256 node[6] that is responsible for setting up CPU idle management in the OS
257 implementation.
258 const: psci
259
260 patternProperties:
261 "^(cpu|cluster)-":
262 type: object
263 description: |
264 Each state node represents an idle state description and must be defined
265 as follows.
266
267 The idle state entered by executing the wfi instruction (idle_standby
268 SBSA,[3][4]) is considered standard on all ARM platforms and therefore
269 must not be listed.
270
271 In addition to the properties listed above, a state node may require
272 additional properties specific to the entry-method defined in the
273 idle-states node. Please refer to the entry-method bindings
274 documentation for properties definitions.
275
276 properties:
277 compatible:
278 const: arm,idle-state
279
280 local-timer-stop:
281 description:
282 If present the CPU local timer control logic is
283 lost on state entry, otherwise it is retained.
284 type: boolean
285
286 entry-latency-us:
287 description:
288 Worst case latency in microseconds required to enter the idle state.
289
290 exit-latency-us:
291 description:
292 Worst case latency in microseconds required to exit the idle state.
293 The exit-latency-us duration may be guaranteed only after
294 entry-latency-us has passed.
295
296 min-residency-us:
297 description:
298 Minimum residency duration in microseconds, inclusive of preparation
299 and entry, for this idle state to be considered worthwhile energy wise
300 (refer to section 2 of this document for a complete description).
301
302 wakeup-latency-us:
303 description: |
304 Maximum delay between the signaling of a wake-up event and the CPU
305 being able to execute normal code again. If omitted, this is assumed
306 to be equal to:
307
308 entry-latency-us + exit-latency-us
309
310 It is important to supply this value on systems where the duration of
311 PREP phase (see diagram 1, section 2) is non-neglibigle. In such
312 systems entry-latency-us + exit-latency-us will exceed
313 wakeup-latency-us by this duration.
314
315 idle-state-name:
316 $ref: /schemas/types.yaml#/definitions/string
317 description:
318 A string used as a descriptive name for the idle state.
319
320 required:
321 - compatible
322 - entry-latency-us
323 - exit-latency-us
324 - min-residency-us
325
326 additionalProperties: false
327
328 examples:
329 - |
330
331 cpus {
332 #size-cells = <0>;
333 #address-cells = <2>;
334
335 cpu@0 {
336 device_type = "cpu";
337 compatible = "arm,cortex-a57";
338 reg = <0x0 0x0>;
339 enable-method = "psci";
340 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
341 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
342 };
343
344 cpu@1 {
345 device_type = "cpu";
346 compatible = "arm,cortex-a57";
347 reg = <0x0 0x1>;
348 enable-method = "psci";
349 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
350 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
351 };
352
353 cpu@100 {
354 device_type = "cpu";
355 compatible = "arm,cortex-a57";
356 reg = <0x0 0x100>;
357 enable-method = "psci";
358 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
359 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
360 };
361
362 cpu@101 {
363 device_type = "cpu";
364 compatible = "arm,cortex-a57";
365 reg = <0x0 0x101>;
366 enable-method = "psci";
367 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
368 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
369 };
370
371 cpu@10000 {
372 device_type = "cpu";
373 compatible = "arm,cortex-a57";
374 reg = <0x0 0x10000>;
375 enable-method = "psci";
376 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
377 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
378 };
379
380 cpu@10001 {
381 device_type = "cpu";
382 compatible = "arm,cortex-a57";
383 reg = <0x0 0x10001>;
384 enable-method = "psci";
385 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
386 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
387 };
388
389 cpu@10100 {
390 device_type = "cpu";
391 compatible = "arm,cortex-a57";
392 reg = <0x0 0x10100>;
393 enable-method = "psci";
394 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
395 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
396 };
397
398 cpu@10101 {
399 device_type = "cpu";
400 compatible = "arm,cortex-a57";
401 reg = <0x0 0x10101>;
402 enable-method = "psci";
403 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
404 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
405 };
406
407 cpu@100000000 {
408 device_type = "cpu";
409 compatible = "arm,cortex-a53";
410 reg = <0x1 0x0>;
411 enable-method = "psci";
412 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
413 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
414 };
415
416 cpu@100000001 {
417 device_type = "cpu";
418 compatible = "arm,cortex-a53";
419 reg = <0x1 0x1>;
420 enable-method = "psci";
421 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
422 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
423 };
424
425 cpu@100000100 {
426 device_type = "cpu";
427 compatible = "arm,cortex-a53";
428 reg = <0x1 0x100>;
429 enable-method = "psci";
430 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
431 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
432 };
433
434 cpu@100000101 {
435 device_type = "cpu";
436 compatible = "arm,cortex-a53";
437 reg = <0x1 0x101>;
438 enable-method = "psci";
439 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
440 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
441 };
442
443 cpu@100010000 {
444 device_type = "cpu";
445 compatible = "arm,cortex-a53";
446 reg = <0x1 0x10000>;
447 enable-method = "psci";
448 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
449 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
450 };
451
452 cpu@100010001 {
453 device_type = "cpu";
454 compatible = "arm,cortex-a53";
455 reg = <0x1 0x10001>;
456 enable-method = "psci";
457 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
458 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
459 };
460
461 cpu@100010100 {
462 device_type = "cpu";
463 compatible = "arm,cortex-a53";
464 reg = <0x1 0x10100>;
465 enable-method = "psci";
466 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
467 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
468 };
469
470 cpu@100010101 {
471 device_type = "cpu";
472 compatible = "arm,cortex-a53";
473 reg = <0x1 0x10101>;
474 enable-method = "psci";
475 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
476 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
477 };
478
479 idle-states {
480 entry-method = "psci";
481
482 CPU_RETENTION_0_0: cpu-retention-0-0 {
483 compatible = "arm,idle-state";
484 arm,psci-suspend-param = <0x0010000>;
485 entry-latency-us = <20>;
486 exit-latency-us = <40>;
487 min-residency-us = <80>;
488 };
489
490 CLUSTER_RETENTION_0: cluster-retention-0 {
491 compatible = "arm,idle-state";
492 local-timer-stop;
493 arm,psci-suspend-param = <0x1010000>;
494 entry-latency-us = <50>;
495 exit-latency-us = <100>;
496 min-residency-us = <250>;
497 wakeup-latency-us = <130>;
498 };
499
500 CPU_SLEEP_0_0: cpu-sleep-0-0 {
501 compatible = "arm,idle-state";
502 local-timer-stop;
503 arm,psci-suspend-param = <0x0010000>;
504 entry-latency-us = <250>;
505 exit-latency-us = <500>;
506 min-residency-us = <950>;
507 };
508
509 CLUSTER_SLEEP_0: cluster-sleep-0 {
510 compatible = "arm,idle-state";
511 local-timer-stop;
512 arm,psci-suspend-param = <0x1010000>;
513 entry-latency-us = <600>;
514 exit-latency-us = <1100>;
515 min-residency-us = <2700>;
516 wakeup-latency-us = <1500>;
517 };
518
519 CPU_RETENTION_1_0: cpu-retention-1-0 {
520 compatible = "arm,idle-state";
521 arm,psci-suspend-param = <0x0010000>;
522 entry-latency-us = <20>;
523 exit-latency-us = <40>;
524 min-residency-us = <90>;
525 };
526
527 CLUSTER_RETENTION_1: cluster-retention-1 {
528 compatible = "arm,idle-state";
529 local-timer-stop;
530 arm,psci-suspend-param = <0x1010000>;
531 entry-latency-us = <50>;
532 exit-latency-us = <100>;
533 min-residency-us = <270>;
534 wakeup-latency-us = <100>;
535 };
536
537 CPU_SLEEP_1_0: cpu-sleep-1-0 {
538 compatible = "arm,idle-state";
539 local-timer-stop;
540 arm,psci-suspend-param = <0x0010000>;
541 entry-latency-us = <70>;
542 exit-latency-us = <100>;
543 min-residency-us = <300>;
544 wakeup-latency-us = <150>;
545 };
546
547 CLUSTER_SLEEP_1: cluster-sleep-1 {
548 compatible = "arm,idle-state";
549 local-timer-stop;
550 arm,psci-suspend-param = <0x1010000>;
551 entry-latency-us = <500>;
552 exit-latency-us = <1200>;
553 min-residency-us = <3500>;
554 wakeup-latency-us = <1300>;
555 };
556 };
557 };
558
559 - |
560 // Example 2 (ARM 32-bit, 8-cpu system, two clusters):
561
562 cpus {
563 #size-cells = <0>;
564 #address-cells = <1>;
565
566 cpu@0 {
567 device_type = "cpu";
568 compatible = "arm,cortex-a15";
569 reg = <0x0>;
570 cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>;
571 };
572
573 cpu@1 {
574 device_type = "cpu";
575 compatible = "arm,cortex-a15";
576 reg = <0x1>;
577 cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>;
578 };
579
580 cpu@2 {
581 device_type = "cpu";
582 compatible = "arm,cortex-a15";
583 reg = <0x2>;
584 cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>;
585 };
586
587 cpu@3 {
588 device_type = "cpu";
589 compatible = "arm,cortex-a15";
590 reg = <0x3>;
591 cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>;
592 };
593
594 cpu@100 {
595 device_type = "cpu";
596 compatible = "arm,cortex-a7";
597 reg = <0x100>;
598 cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>;
599 };
600
601 cpu@101 {
602 device_type = "cpu";
603 compatible = "arm,cortex-a7";
604 reg = <0x101>;
605 cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>;
606 };
607
608 cpu@102 {
609 device_type = "cpu";
610 compatible = "arm,cortex-a7";
611 reg = <0x102>;
612 cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>;
613 };
614
615 cpu@103 {
616 device_type = "cpu";
617 compatible = "arm,cortex-a7";
618 reg = <0x103>;
619 cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>;
620 };
621
622 idle-states {
623 cpu_sleep_0_0: cpu-sleep-0-0 {
624 compatible = "arm,idle-state";
625 local-timer-stop;
626 entry-latency-us = <200>;
627 exit-latency-us = <100>;
628 min-residency-us = <400>;
629 wakeup-latency-us = <250>;
630 };
631
632 cluster_sleep_0: cluster-sleep-0 {
633 compatible = "arm,idle-state";
634 local-timer-stop;
635 entry-latency-us = <500>;
636 exit-latency-us = <1500>;
637 min-residency-us = <2500>;
638 wakeup-latency-us = <1700>;
639 };
640
641 cpu_sleep_1_0: cpu-sleep-1-0 {
642 compatible = "arm,idle-state";
643 local-timer-stop;
644 entry-latency-us = <300>;
645 exit-latency-us = <500>;
646 min-residency-us = <900>;
647 wakeup-latency-us = <600>;
648 };
649
650 cluster_sleep_1: cluster-sleep-1 {
651 compatible = "arm,idle-state";
652 local-timer-stop;
653 entry-latency-us = <800>;
654 exit-latency-us = <2000>;
655 min-residency-us = <6500>;
656 wakeup-latency-us = <2300>;
657 };
658 };
659 };
660
661 ...
Cache object: 44aa561d45c292d012979c7f067f9fa2
|