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
7title: ARM idle states binding description
8
9maintainers:
10  - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
11
12description: |+
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
244properties:
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
260patternProperties:
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
326additionalProperties: false
327
328examples:
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...
662