1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
4 $id: http://devicetree.org/schemas/arm/idle-states.yaml#
5 $schema: http://devicetree.org/meta-schemas/core.yaml#
7 title: ARM idle states binding description
10 - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
13 ==========================================
15 ==========================================
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.
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:
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).
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.
43 The device tree binding definition for ARM idle states is the subject of this
46 ===========================================
47 2 - idle-states definitions
48 ===========================================
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.
54 The following diagram depicts the CPU execution phases and related timing
55 properties required to enter and exit an idle state:
57 ..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__..
60 |<------ entry ------->|
64 |<-------- min-residency -------->|
65 |<------- wakeup-latency ------->|
67 Diagram 1: CPU idle state execution phases
69 EXEC: Normal CPU execution.
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.
78 ENTRY: The hardware is committed to idle mode. This period must run
79 to completion up to IDLE before anything else can happen.
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.
84 EXIT: Period during which the CPU is brought back to operational
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.
90 min-residency: Minimum period, including preparation and entry, for a given
91 idle state to be worthwhile energywise.
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.
97 These timing parameters can be used by an OS in different circumstances.
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.
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.:
107 wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0)
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
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
123 The min-residency time parameter deserves further explanation since it is
124 expressed in time units but must factor in energy consumption coefficients.
126 The energy consumption of a cpu when it enters a power state can be roughly
127 characterised by the following graph:
146 -----|-------+----------------------------------
149 Graph 1: Energy vs time example
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
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
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.
165 For sake of simplicity, let's consider a system with two idle states IDLE1,
175 r | /-----/--------- IDLE2
176 g | /-------/---------
177 y | ------------ /---|
186 ---/----------------------------+------------------------
187 |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy
191 Graph 2: idle states min-residency example
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
198 This is mainly down to the fact that IDLE1 entry/exit energy costs are lower
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
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.
210 The definitions provided in this section underpin the idle states
211 properties specification that is the subject of the following sections.
213 ===========================================
215 ===========================================
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.
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.
225 ===========================================
227 ===========================================
229 [1] ARM Linux Kernel documentation - CPUs bindings
230 Documentation/devicetree/bindings/arm/cpus.yaml
232 [2] ARM Linux Kernel documentation - PSCI bindings
233 Documentation/devicetree/bindings/arm/psci.yaml
235 [3] ARM Server Base System Architecture (SBSA)
236 http://infocenter.arm.com/help/index.jsp
238 [4] ARM Architecture Reference Manuals
239 http://infocenter.arm.com/help/index.jsp
241 [6] ARM Linux Kernel documentation - Booting AArch64 Linux
242 Documentation/arm64/booting.rst
250 Usage and definition depend on ARM architecture version.
252 On ARM v8 64-bit this property is required.
253 On ARM 32-bit systems this property is optional
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
264 Each state node represents an idle state description and must be defined
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
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.
278 const: arm,idle-state
282 If present the CPU local timer control logic is
283 lost on state entry, otherwise it is retained.
288 Worst case latency in microseconds required to enter the idle state.
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.
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).
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
308 entry-latency-us + exit-latency-us
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.
316 $ref: /schemas/types.yaml#/definitions/string
318 A string used as a descriptive name for the idle state.
326 additionalProperties: false
333 #address-cells = <2>;
337 compatible = "arm,cortex-a57";
339 enable-method = "psci";
340 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
341 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
346 compatible = "arm,cortex-a57";
348 enable-method = "psci";
349 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
350 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
355 compatible = "arm,cortex-a57";
357 enable-method = "psci";
358 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
359 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
364 compatible = "arm,cortex-a57";
366 enable-method = "psci";
367 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
368 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
373 compatible = "arm,cortex-a57";
375 enable-method = "psci";
376 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
377 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
382 compatible = "arm,cortex-a57";
384 enable-method = "psci";
385 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
386 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
391 compatible = "arm,cortex-a57";
393 enable-method = "psci";
394 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
395 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
400 compatible = "arm,cortex-a57";
402 enable-method = "psci";
403 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0
404 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>;
409 compatible = "arm,cortex-a53";
411 enable-method = "psci";
412 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
413 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
418 compatible = "arm,cortex-a53";
420 enable-method = "psci";
421 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
422 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
427 compatible = "arm,cortex-a53";
429 enable-method = "psci";
430 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
431 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
436 compatible = "arm,cortex-a53";
438 enable-method = "psci";
439 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
440 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
445 compatible = "arm,cortex-a53";
447 enable-method = "psci";
448 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
449 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
454 compatible = "arm,cortex-a53";
456 enable-method = "psci";
457 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
458 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
463 compatible = "arm,cortex-a53";
465 enable-method = "psci";
466 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
467 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
472 compatible = "arm,cortex-a53";
474 enable-method = "psci";
475 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0
476 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>;
480 entry-method = "psci";
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>;
490 CLUSTER_RETENTION_0: cluster-retention-0 {
491 compatible = "arm,idle-state";
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>;
500 CPU_SLEEP_0_0: cpu-sleep-0-0 {
501 compatible = "arm,idle-state";
503 arm,psci-suspend-param = <0x0010000>;
504 entry-latency-us = <250>;
505 exit-latency-us = <500>;
506 min-residency-us = <950>;
509 CLUSTER_SLEEP_0: cluster-sleep-0 {
510 compatible = "arm,idle-state";
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>;
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>;
527 CLUSTER_RETENTION_1: cluster-retention-1 {
528 compatible = "arm,idle-state";
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>;
537 CPU_SLEEP_1_0: cpu-sleep-1-0 {
538 compatible = "arm,idle-state";
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>;
547 CLUSTER_SLEEP_1: cluster-sleep-1 {
548 compatible = "arm,idle-state";
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>;
560 // Example 2 (ARM 32-bit, 8-cpu system, two clusters):
564 #address-cells = <1>;
568 compatible = "arm,cortex-a15";
570 cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>;
575 compatible = "arm,cortex-a15";
577 cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>;
582 compatible = "arm,cortex-a15";
584 cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>;
589 compatible = "arm,cortex-a15";
591 cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>;
596 compatible = "arm,cortex-a7";
598 cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>;
603 compatible = "arm,cortex-a7";
605 cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>;
610 compatible = "arm,cortex-a7";
612 cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>;
617 compatible = "arm,cortex-a7";
619 cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>;
623 cpu_sleep_0_0: cpu-sleep-0-0 {
624 compatible = "arm,idle-state";
626 entry-latency-us = <200>;
627 exit-latency-us = <100>;
628 min-residency-us = <400>;
629 wakeup-latency-us = <250>;
632 cluster_sleep_0: cluster-sleep-0 {
633 compatible = "arm,idle-state";
635 entry-latency-us = <500>;
636 exit-latency-us = <1500>;
637 min-residency-us = <2500>;
638 wakeup-latency-us = <1700>;
641 cpu_sleep_1_0: cpu-sleep-1-0 {
642 compatible = "arm,idle-state";
644 entry-latency-us = <300>;
645 exit-latency-us = <500>;
646 min-residency-us = <900>;
647 wakeup-latency-us = <600>;
650 cluster_sleep_1: cluster-sleep-1 {
651 compatible = "arm,idle-state";
653 entry-latency-us = <800>;
654 exit-latency-us = <2000>;
655 min-residency-us = <6500>;
656 wakeup-latency-us = <2300>;