1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
4 $id: http://devicetree.org/schemas/cpu/idle-states.yaml#
5 $schema: http://devicetree.org/meta-schemas/core.yaml#
7 title: Idle states binding description
10 - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
11 - Anup Patel <anup@brainfault.org>
14 ==========================================
16 ==========================================
18 ARM and RISC-V systems contain HW capable of managing power consumption
19 dynamically, where cores can be put in different low-power states (ranging
20 from simple wfi to power gating) according to OS PM policies. The CPU states
21 representing the range of dynamic idle states that a processor can enter at
22 run-time, can be specified through device tree bindings representing the
23 parameters required to enter/exit specific idle states on a given processor.
25 ==========================================
27 ==========================================
29 According to the Server Base System Architecture document (SBSA, [3]), the
30 power states an ARM CPU can be put into are identified by the following list:
38 The power states described in the SBSA document define the basic CPU states on
39 top of which ARM platforms implement power management schemes that allow an OS
40 PM implementation to put the processor in different idle states (which include
41 states listed above; "off" state is not an idle state since it does not have
42 wake-up capabilities, hence it is not considered in this document).
44 Idle state parameters (e.g. entry latency) are platform specific and need to
45 be characterized with bindings that provide the required information to OS PM
46 code so that it can build the required tables and use them at runtime.
48 The device tree binding definition for ARM idle states is the subject of this
51 ==========================================
52 3 - RISC-V idle states
53 ==========================================
55 On RISC-V systems, the HARTs (or CPUs) [6] can be put in platform specific
56 suspend (or idle) states (ranging from simple WFI, power gating, etc). The
57 RISC-V SBI v0.3 (or higher) [7] hart state management extension provides a
58 standard mechanism for OS to request HART state transitions.
60 The platform specific suspend (or idle) states of a hart can be either
61 retentive or non-rententive in nature. A retentive suspend state will
62 preserve HART registers and CSR values for all privilege modes whereas
63 a non-retentive suspend state will not preserve HART registers and CSR
66 ===========================================
67 4 - idle-states definitions
68 ===========================================
70 Idle states are characterized for a specific system through a set of
71 timing and energy related properties, that underline the HW behaviour
72 triggered upon idle states entry and exit.
74 The following diagram depicts the CPU execution phases and related timing
75 properties required to enter and exit an idle state:
77 ..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__..
80 |<------ entry ------->|
84 |<-------- min-residency -------->|
85 |<------- wakeup-latency ------->|
87 Diagram 1: CPU idle state execution phases
89 EXEC: Normal CPU execution.
91 PREP: Preparation phase before committing the hardware to idle mode
92 like cache flushing. This is abortable on pending wake-up
93 event conditions. The abort latency is assumed to be negligible
94 (i.e. less than the ENTRY + EXIT duration). If aborted, CPU
95 goes back to EXEC. This phase is optional. If not abortable,
96 this should be included in the ENTRY phase instead.
98 ENTRY: The hardware is committed to idle mode. This period must run
99 to completion up to IDLE before anything else can happen.
101 IDLE: This is the actual energy-saving idle period. This may last
102 between 0 and infinite time, until a wake-up event occurs.
104 EXIT: Period during which the CPU is brought back to operational
107 entry-latency: Worst case latency required to enter the idle state. The
108 exit-latency may be guaranteed only after entry-latency has passed.
110 min-residency: Minimum period, including preparation and entry, for a given
111 idle state to be worthwhile energywise.
113 wakeup-latency: Maximum delay between the signaling of a wake-up event and the
114 CPU being able to execute normal code again. If not specified, this is assumed
115 to be entry-latency + exit-latency.
117 These timing parameters can be used by an OS in different circumstances.
119 An idle CPU requires the expected min-residency time to select the most
120 appropriate idle state based on the expected expiry time of the next IRQ
121 (i.e. wake-up) that causes the CPU to return to the EXEC phase.
123 An operating system scheduler may need to compute the shortest wake-up delay
124 for CPUs in the system by detecting how long will it take to get a CPU out
125 of an idle state, e.g.:
127 wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0)
129 In other words, the scheduler can make its scheduling decision by selecting
130 (e.g. waking-up) the CPU with the shortest wake-up delay.
131 The wake-up delay must take into account the entry latency if that period
132 has not expired. The abortable nature of the PREP period can be ignored
133 if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than
134 the worst case since it depends on the CPU operating conditions, i.e. caches
137 An OS has to reliably probe the wakeup-latency since some devices can enforce
138 latency constraint guarantees to work properly, so the OS has to detect the
139 worst case wake-up latency it can incur if a CPU is allowed to enter an
140 idle state, and possibly to prevent that to guarantee reliable device
143 The min-residency time parameter deserves further explanation since it is
144 expressed in time units but must factor in energy consumption coefficients.
146 The energy consumption of a cpu when it enters a power state can be roughly
147 characterised by the following graph:
166 -----|-------+----------------------------------
169 Graph 1: Energy vs time example
171 The graph is split in two parts delimited by time 1ms on the X-axis.
172 The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope
173 and denotes the energy costs incurred while entering and leaving the idle
175 The graph curve in the area delimited by X-axis values = {x | x > 1ms } has
176 shallower slope and essentially represents the energy consumption of the idle
179 min-residency is defined for a given idle state as the minimum expected
180 residency time for a state (inclusive of preparation and entry) after
181 which choosing that state become the most energy efficient option. A good
182 way to visualise this, is by taking the same graph above and comparing some
183 states energy consumptions plots.
185 For sake of simplicity, let's consider a system with two idle states IDLE1,
195 r | /-----/--------- IDLE2
196 g | /-------/---------
197 y | ------------ /---|
206 ---/----------------------------+------------------------
207 |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy
211 Graph 2: idle states min-residency example
213 In graph 2 above, that takes into account idle states entry/exit energy
214 costs, it is clear that if the idle state residency time (i.e. time till next
215 wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state
218 This is mainly down to the fact that IDLE1 entry/exit energy costs are lower
221 However, the lower power consumption (i.e. shallower energy curve slope) of
222 idle state IDLE2 implies that after a suitable time, IDLE2 becomes more energy
225 The time at which IDLE2 becomes more energy efficient than IDLE1 (and other
226 shallower states in a system with multiple idle states) is defined
227 IDLE2-min-residency and corresponds to the time when energy consumption of
228 IDLE1 and IDLE2 states breaks even.
230 The definitions provided in this section underpin the idle states
231 properties specification that is the subject of the following sections.
233 ===========================================
235 ===========================================
237 The processor idle states are defined within the idle-states node, which is
238 a direct child of the cpus node [1] and provides a container where the
239 processor idle states, defined as device tree nodes, are listed.
241 On ARM systems, it is a container of processor idle states nodes. If the
242 system does not provide CPU power management capabilities, or the processor
243 just supports idle_standby, an idle-states node is not required.
245 ===========================================
247 ===========================================
249 [1] ARM Linux Kernel documentation - CPUs bindings
250 Documentation/devicetree/bindings/arm/cpus.yaml
252 [2] ARM Linux Kernel documentation - PSCI bindings
253 Documentation/devicetree/bindings/arm/psci.yaml
255 [3] ARM Server Base System Architecture (SBSA)
256 http://infocenter.arm.com/help/index.jsp
258 [4] ARM Architecture Reference Manuals
259 http://infocenter.arm.com/help/index.jsp
261 [5] ARM Linux Kernel documentation - Booting AArch64 Linux
262 Documentation/arm64/booting.rst
264 [6] RISC-V Linux Kernel documentation - CPUs bindings
265 Documentation/devicetree/bindings/riscv/cpus.yaml
267 [7] RISC-V Supervisor Binary Interface (SBI)
268 http://github.com/riscv/riscv-sbi-doc/riscv-sbi.adoc
276 Usage and definition depend on ARM architecture version.
278 On ARM v8 64-bit this property is required.
279 On ARM 32-bit systems this property is optional
281 This assumes that the "enable-method" property is set to "psci" in the cpu
282 node[5] that is responsible for setting up CPU idle management in the OS
290 Each state node represents an idle state description and must be defined
293 The idle state entered by executing the wfi instruction (idle_standby
294 SBSA,[3][4]) is considered standard on all ARM and RISC-V platforms and
295 therefore must not be listed.
297 In addition to the properties listed above, a state node may require
298 additional properties specific to the entry-method defined in the
299 idle-states node. Please refer to the entry-method bindings
300 documentation for properties definitions.
308 arm,psci-suspend-param:
309 $ref: /schemas/types.yaml#/definitions/uint32
311 power_state parameter to pass to the ARM PSCI suspend call.
313 Device tree nodes that require usage of PSCI CPU_SUSPEND function
314 (i.e. idle states node with entry-method property is set to "psci")
315 must specify this property.
317 riscv,sbi-suspend-param:
318 $ref: /schemas/types.yaml#/definitions/uint32
320 suspend_type parameter to pass to the RISC-V SBI HSM suspend call.
322 This property is required in idle state nodes of device tree meant
323 for RISC-V systems. For more details on the suspend_type parameter
324 refer the SBI specifiation v0.3 (or higher) [7].
328 If present the CPU local timer control logic is
329 lost on state entry, otherwise it is retained.
334 Worst case latency in microseconds required to enter the idle state.
338 Worst case latency in microseconds required to exit the idle state.
339 The exit-latency-us duration may be guaranteed only after
340 entry-latency-us has passed.
344 Minimum residency duration in microseconds, inclusive of preparation
345 and entry, for this idle state to be considered worthwhile energy wise
346 (refer to section 2 of this document for a complete description).
350 Maximum delay between the signaling of a wake-up event and the CPU
351 being able to execute normal code again. If omitted, this is assumed
354 entry-latency-us + exit-latency-us
356 It is important to supply this value on systems where the duration of
357 PREP phase (see diagram 1, section 2) is non-neglibigle. In such
358 systems entry-latency-us + exit-latency-us will exceed
359 wakeup-latency-us by this duration.
362 $ref: /schemas/types.yaml#/definitions/string
364 A string used as a descriptive name for the idle state.
366 additionalProperties: false
374 additionalProperties: false
381 #address-cells = <2>;
385 compatible = "arm,cortex-a57";
387 enable-method = "psci";
388 cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
389 <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
394 compatible = "arm,cortex-a57";
396 enable-method = "psci";
397 cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
398 <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
403 compatible = "arm,cortex-a57";
405 enable-method = "psci";
406 cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
407 <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
412 compatible = "arm,cortex-a57";
414 enable-method = "psci";
415 cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
416 <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
421 compatible = "arm,cortex-a57";
423 enable-method = "psci";
424 cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
425 <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
430 compatible = "arm,cortex-a57";
432 enable-method = "psci";
433 cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
434 <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
439 compatible = "arm,cortex-a57";
441 enable-method = "psci";
442 cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
443 <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
448 compatible = "arm,cortex-a57";
450 enable-method = "psci";
451 cpu-idle-states = <&CPU_RETENTION_0_0>, <&CPU_SLEEP_0_0>,
452 <&CLUSTER_RETENTION_0>, <&CLUSTER_SLEEP_0>;
457 compatible = "arm,cortex-a53";
459 enable-method = "psci";
460 cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
461 <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
466 compatible = "arm,cortex-a53";
468 enable-method = "psci";
469 cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
470 <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
475 compatible = "arm,cortex-a53";
477 enable-method = "psci";
478 cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
479 <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
484 compatible = "arm,cortex-a53";
486 enable-method = "psci";
487 cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
488 <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
493 compatible = "arm,cortex-a53";
495 enable-method = "psci";
496 cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
497 <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
502 compatible = "arm,cortex-a53";
504 enable-method = "psci";
505 cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
506 <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
511 compatible = "arm,cortex-a53";
513 enable-method = "psci";
514 cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
515 <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
520 compatible = "arm,cortex-a53";
522 enable-method = "psci";
523 cpu-idle-states = <&CPU_RETENTION_1_0>, <&CPU_SLEEP_1_0>,
524 <&CLUSTER_RETENTION_1>, <&CLUSTER_SLEEP_1>;
528 entry-method = "psci";
530 CPU_RETENTION_0_0: cpu-retention-0-0 {
531 compatible = "arm,idle-state";
532 arm,psci-suspend-param = <0x0010000>;
533 entry-latency-us = <20>;
534 exit-latency-us = <40>;
535 min-residency-us = <80>;
538 CLUSTER_RETENTION_0: cluster-retention-0 {
539 compatible = "arm,idle-state";
541 arm,psci-suspend-param = <0x1010000>;
542 entry-latency-us = <50>;
543 exit-latency-us = <100>;
544 min-residency-us = <250>;
545 wakeup-latency-us = <130>;
548 CPU_SLEEP_0_0: cpu-sleep-0-0 {
549 compatible = "arm,idle-state";
551 arm,psci-suspend-param = <0x0010000>;
552 entry-latency-us = <250>;
553 exit-latency-us = <500>;
554 min-residency-us = <950>;
557 CLUSTER_SLEEP_0: cluster-sleep-0 {
558 compatible = "arm,idle-state";
560 arm,psci-suspend-param = <0x1010000>;
561 entry-latency-us = <600>;
562 exit-latency-us = <1100>;
563 min-residency-us = <2700>;
564 wakeup-latency-us = <1500>;
567 CPU_RETENTION_1_0: cpu-retention-1-0 {
568 compatible = "arm,idle-state";
569 arm,psci-suspend-param = <0x0010000>;
570 entry-latency-us = <20>;
571 exit-latency-us = <40>;
572 min-residency-us = <90>;
575 CLUSTER_RETENTION_1: cluster-retention-1 {
576 compatible = "arm,idle-state";
578 arm,psci-suspend-param = <0x1010000>;
579 entry-latency-us = <50>;
580 exit-latency-us = <100>;
581 min-residency-us = <270>;
582 wakeup-latency-us = <100>;
585 CPU_SLEEP_1_0: cpu-sleep-1-0 {
586 compatible = "arm,idle-state";
588 arm,psci-suspend-param = <0x0010000>;
589 entry-latency-us = <70>;
590 exit-latency-us = <100>;
591 min-residency-us = <300>;
592 wakeup-latency-us = <150>;
595 CLUSTER_SLEEP_1: cluster-sleep-1 {
596 compatible = "arm,idle-state";
598 arm,psci-suspend-param = <0x1010000>;
599 entry-latency-us = <500>;
600 exit-latency-us = <1200>;
601 min-residency-us = <3500>;
602 wakeup-latency-us = <1300>;
608 // Example 2 (ARM 32-bit, 8-cpu system, two clusters):
612 #address-cells = <1>;
616 compatible = "arm,cortex-a15";
618 cpu-idle-states = <&cpu_sleep_0_0>, <&cluster_sleep_0>;
623 compatible = "arm,cortex-a15";
625 cpu-idle-states = <&cpu_sleep_0_0>, <&cluster_sleep_0>;
630 compatible = "arm,cortex-a15";
632 cpu-idle-states = <&cpu_sleep_0_0>, <&cluster_sleep_0>;
637 compatible = "arm,cortex-a15";
639 cpu-idle-states = <&cpu_sleep_0_0>, <&cluster_sleep_0>;
644 compatible = "arm,cortex-a7";
646 cpu-idle-states = <&cpu_sleep_1_0>, <&cluster_sleep_1>;
651 compatible = "arm,cortex-a7";
653 cpu-idle-states = <&cpu_sleep_1_0>, <&cluster_sleep_1>;
658 compatible = "arm,cortex-a7";
660 cpu-idle-states = <&cpu_sleep_1_0>, <&cluster_sleep_1>;
665 compatible = "arm,cortex-a7";
667 cpu-idle-states = <&cpu_sleep_1_0>, <&cluster_sleep_1>;
671 cpu_sleep_0_0: cpu-sleep-0-0 {
672 compatible = "arm,idle-state";
674 entry-latency-us = <200>;
675 exit-latency-us = <100>;
676 min-residency-us = <400>;
677 wakeup-latency-us = <250>;
680 cluster_sleep_0: cluster-sleep-0 {
681 compatible = "arm,idle-state";
683 entry-latency-us = <500>;
684 exit-latency-us = <1500>;
685 min-residency-us = <2500>;
686 wakeup-latency-us = <1700>;
689 cpu_sleep_1_0: cpu-sleep-1-0 {
690 compatible = "arm,idle-state";
692 entry-latency-us = <300>;
693 exit-latency-us = <500>;
694 min-residency-us = <900>;
695 wakeup-latency-us = <600>;
698 cluster_sleep_1: cluster-sleep-1 {
699 compatible = "arm,idle-state";
701 entry-latency-us = <800>;
702 exit-latency-us = <2000>;
703 min-residency-us = <6500>;
704 wakeup-latency-us = <2300>;
710 // Example 3 (RISC-V 64-bit, 4-cpu systems, two clusters):
714 #address-cells = <1>;
718 compatible = "riscv";
720 riscv,isa = "rv64imafdc";
721 mmu-type = "riscv,sv48";
722 cpu-idle-states = <&CPU_RET_0_0>, <&CPU_NONRET_0_0>,
723 <&CLUSTER_RET_0>, <&CLUSTER_NONRET_0>;
725 cpu_intc0: interrupt-controller {
726 #interrupt-cells = <1>;
727 compatible = "riscv,cpu-intc";
728 interrupt-controller;
734 compatible = "riscv";
736 riscv,isa = "rv64imafdc";
737 mmu-type = "riscv,sv48";
738 cpu-idle-states = <&CPU_RET_0_0>, <&CPU_NONRET_0_0>,
739 <&CLUSTER_RET_0>, <&CLUSTER_NONRET_0>;
741 cpu_intc1: interrupt-controller {
742 #interrupt-cells = <1>;
743 compatible = "riscv,cpu-intc";
744 interrupt-controller;
750 compatible = "riscv";
752 riscv,isa = "rv64imafdc";
753 mmu-type = "riscv,sv48";
754 cpu-idle-states = <&CPU_RET_1_0>, <&CPU_NONRET_1_0>,
755 <&CLUSTER_RET_1>, <&CLUSTER_NONRET_1>;
757 cpu_intc10: interrupt-controller {
758 #interrupt-cells = <1>;
759 compatible = "riscv,cpu-intc";
760 interrupt-controller;
766 compatible = "riscv";
768 riscv,isa = "rv64imafdc";
769 mmu-type = "riscv,sv48";
770 cpu-idle-states = <&CPU_RET_1_0>, <&CPU_NONRET_1_0>,
771 <&CLUSTER_RET_1>, <&CLUSTER_NONRET_1>;
773 cpu_intc11: interrupt-controller {
774 #interrupt-cells = <1>;
775 compatible = "riscv,cpu-intc";
776 interrupt-controller;
781 CPU_RET_0_0: cpu-retentive-0-0 {
782 compatible = "riscv,idle-state";
783 riscv,sbi-suspend-param = <0x10000000>;
784 entry-latency-us = <20>;
785 exit-latency-us = <40>;
786 min-residency-us = <80>;
789 CPU_NONRET_0_0: cpu-nonretentive-0-0 {
790 compatible = "riscv,idle-state";
791 riscv,sbi-suspend-param = <0x90000000>;
792 entry-latency-us = <250>;
793 exit-latency-us = <500>;
794 min-residency-us = <950>;
797 CLUSTER_RET_0: cluster-retentive-0 {
798 compatible = "riscv,idle-state";
799 riscv,sbi-suspend-param = <0x11000000>;
801 entry-latency-us = <50>;
802 exit-latency-us = <100>;
803 min-residency-us = <250>;
804 wakeup-latency-us = <130>;
807 CLUSTER_NONRET_0: cluster-nonretentive-0 {
808 compatible = "riscv,idle-state";
809 riscv,sbi-suspend-param = <0x91000000>;
811 entry-latency-us = <600>;
812 exit-latency-us = <1100>;
813 min-residency-us = <2700>;
814 wakeup-latency-us = <1500>;
817 CPU_RET_1_0: cpu-retentive-1-0 {
818 compatible = "riscv,idle-state";
819 riscv,sbi-suspend-param = <0x10000010>;
820 entry-latency-us = <20>;
821 exit-latency-us = <40>;
822 min-residency-us = <80>;
825 CPU_NONRET_1_0: cpu-nonretentive-1-0 {
826 compatible = "riscv,idle-state";
827 riscv,sbi-suspend-param = <0x90000010>;
828 entry-latency-us = <250>;
829 exit-latency-us = <500>;
830 min-residency-us = <950>;
833 CLUSTER_RET_1: cluster-retentive-1 {
834 compatible = "riscv,idle-state";
835 riscv,sbi-suspend-param = <0x11000010>;
837 entry-latency-us = <50>;
838 exit-latency-us = <100>;
839 min-residency-us = <250>;
840 wakeup-latency-us = <130>;
843 CLUSTER_NONRET_1: cluster-nonretentive-1 {
844 compatible = "riscv,idle-state";
845 riscv,sbi-suspend-param = <0x91000010>;
847 entry-latency-us = <600>;
848 exit-latency-us = <1100>;
849 min-residency-us = <2700>;
850 wakeup-latency-us = <1500>;