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