Merge branch 'work.misc' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs
[linux-2.6-microblaze.git] / Documentation / devicetree / bindings / arm / idle-states.yaml
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 ...