1========================================== 2ARM idle states binding description 3========================================== 4 5========================================== 61 - Introduction 7========================================== 8 9ARM systems contain HW capable of managing power consumption dynamically, 10where cores can be put in different low-power states (ranging from simple 11wfi to power gating) according to OS PM policies. The CPU states representing 12the range of dynamic idle states that a processor can enter at run-time, can be 13specified through device tree bindings representing the parameters required 14to enter/exit specific idle states on a given processor. 15 16According to the Server Base System Architecture document (SBSA, [3]), the 17power states an ARM CPU can be put into are identified by the following list: 18 19- Running 20- Idle_standby 21- Idle_retention 22- Sleep 23- Off 24 25The power states described in the SBSA document define the basic CPU states on 26top of which ARM platforms implement power management schemes that allow an OS 27PM implementation to put the processor in different idle states (which include 28states listed above; "off" state is not an idle state since it does not have 29wake-up capabilities, hence it is not considered in this document). 30 31Idle state parameters (e.g. entry latency) are platform specific and need to be 32characterized with bindings that provide the required information to OS PM 33code so that it can build the required tables and use them at runtime. 34 35The device tree binding definition for ARM idle states is the subject of this 36document. 37 38=========================================== 392 - idle-states definitions 40=========================================== 41 42Idle states are characterized for a specific system through a set of 43timing and energy related properties, that underline the HW behaviour 44triggered upon idle states entry and exit. 45 46The following diagram depicts the CPU execution phases and related timing 47properties required to enter and exit an idle state: 48 49..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__.. 50 | | | | | 51 52 |<------ entry ------->| 53 | latency | 54 |<- exit ->| 55 | latency | 56 |<-------- min-residency -------->| 57 |<------- wakeup-latency ------->| 58 59 Diagram 1: CPU idle state execution phases 60 61EXEC: Normal CPU execution. 62 63PREP: Preparation phase before committing the hardware to idle mode 64 like cache flushing. This is abortable on pending wake-up 65 event conditions. The abort latency is assumed to be negligible 66 (i.e. less than the ENTRY + EXIT duration). If aborted, CPU 67 goes back to EXEC. This phase is optional. If not abortable, 68 this should be included in the ENTRY phase instead. 69 70ENTRY: The hardware is committed to idle mode. This period must run 71 to completion up to IDLE before anything else can happen. 72 73IDLE: This is the actual energy-saving idle period. This may last 74 between 0 and infinite time, until a wake-up event occurs. 75 76EXIT: Period during which the CPU is brought back to operational 77 mode (EXEC). 78 79entry-latency: Worst case latency required to enter the idle state. The 80exit-latency may be guaranteed only after entry-latency has passed. 81 82min-residency: Minimum period, including preparation and entry, for a given 83idle state to be worthwhile energywise. 84 85wakeup-latency: Maximum delay between the signaling of a wake-up event and the 86CPU being able to execute normal code again. If not specified, this is assumed 87to be entry-latency + exit-latency. 88 89These timing parameters can be used by an OS in different circumstances. 90 91An idle CPU requires the expected min-residency time to select the most 92appropriate idle state based on the expected expiry time of the next IRQ 93(i.e. wake-up) that causes the CPU to return to the EXEC phase. 94 95An operating system scheduler may need to compute the shortest wake-up delay 96for CPUs in the system by detecting how long will it take to get a CPU out 97of an idle state, e.g.: 98 99wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0) 100 101In other words, the scheduler can make its scheduling decision by selecting 102(e.g. waking-up) the CPU with the shortest wake-up delay. 103The wake-up delay must take into account the entry latency if that period 104has not expired. The abortable nature of the PREP period can be ignored 105if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than 106the worst case since it depends on the CPU operating conditions, i.e. caches 107state). 108 109An OS has to reliably probe the wakeup-latency since some devices can enforce 110latency constraint guarantees to work properly, so the OS has to detect the 111worst case wake-up latency it can incur if a CPU is allowed to enter an 112idle state, and possibly to prevent that to guarantee reliable device 113functioning. 114 115The min-residency time parameter deserves further explanation since it is 116expressed in time units but must factor in energy consumption coefficients. 117 118The energy consumption of a cpu when it enters a power state can be roughly 119characterised by the following graph: 120 121 | 122 | 123 | 124 e | 125 n | /--- 126 e | /------ 127 r | /------ 128 g | /----- 129 y | /------ 130 | ---- 131 | /| 132 | / | 133 | / | 134 | / | 135 | / | 136 | / | 137 |/ | 138 -----|-------+---------------------------------- 139 0| 1 time(ms) 140 141 Graph 1: Energy vs time example 142 143The graph is split in two parts delimited by time 1ms on the X-axis. 144The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope 145and denotes the energy costs incurred while entering and leaving the idle 146state. 147The graph curve in the area delimited by X-axis values = {x | x > 1ms } has 148shallower slope and essentially represents the energy consumption of the idle 149state. 150 151min-residency is defined for a given idle state as the minimum expected 152residency time for a state (inclusive of preparation and entry) after 153which choosing that state become the most energy efficient option. A good 154way to visualise this, is by taking the same graph above and comparing some 155states energy consumptions plots. 156 157For sake of simplicity, let's consider a system with two idle states IDLE1, 158and IDLE2: 159 160 | 161 | 162 | 163 | /-- IDLE1 164 e | /--- 165 n | /---- 166 e | /--- 167 r | /-----/--------- IDLE2 168 g | /-------/--------- 169 y | ------------ /---| 170 | / /---- | 171 | / /--- | 172 | / /---- | 173 | / /--- | 174 | --- | 175 | / | 176 | / | 177 |/ | time 178 ---/----------------------------+------------------------ 179 |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy 180 | 181 IDLE2-min-residency 182 183 Graph 2: idle states min-residency example 184 185In graph 2 above, that takes into account idle states entry/exit energy 186costs, it is clear that if the idle state residency time (i.e. time till next 187wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state 188choice energywise. 189 190This is mainly down to the fact that IDLE1 entry/exit energy costs are lower 191than IDLE2. 192 193However, the lower power consumption (i.e. shallower energy curve slope) of 194idle state IDLE2 implies that after a suitable time, IDLE2 becomes more energy 195efficient. 196 197The time at which IDLE2 becomes more energy efficient than IDLE1 (and other 198shallower states in a system with multiple idle states) is defined 199IDLE2-min-residency and corresponds to the time when energy consumption of 200IDLE1 and IDLE2 states breaks even. 201 202The definitions provided in this section underpin the idle states 203properties specification that is the subject of the following sections. 204 205=========================================== 2063 - idle-states node 207=========================================== 208 209ARM processor idle states are defined within the idle-states node, which is 210a direct child of the cpus node [1] and provides a container where the 211processor idle states, defined as device tree nodes, are listed. 212 213- idle-states node 214 215 Usage: Optional - On ARM systems, it is a container of processor idle 216 states nodes. If the system does not provide CPU 217 power management capabilities, or the processor just 218 supports idle_standby, an idle-states node is not 219 required. 220 221 Description: idle-states node is a container node, where its 222 subnodes describe the CPU idle states. 223 224 Node name must be "idle-states". 225 226 The idle-states node's parent node must be the cpus node. 227 228 The idle-states node's child nodes can be: 229 230 - one or more state nodes 231 232 Any other configuration is considered invalid. 233 234 An idle-states node defines the following properties: 235 236 - entry-method 237 Value type: <stringlist> 238 Usage and definition depend on ARM architecture version. 239 # On ARM v8 64-bit this property is required and must 240 be: 241 - "psci" 242 # On ARM 32-bit systems this property is optional 243 244This assumes that the "enable-method" property is set to "psci" in the cpu 245node[6] that is responsible for setting up CPU idle management in the OS 246implementation. 247 248The nodes describing the idle states (state) can only be defined 249within the idle-states node, any other configuration is considered invalid 250and therefore must be ignored. 251 252=========================================== 2534 - state node 254=========================================== 255 256A state node represents an idle state description and must be defined as 257follows: 258 259- state node 260 261 Description: must be child of the idle-states node 262 263 The state node name shall follow standard device tree naming 264 rules ([5], 2.2.1 "Node names"), in particular state nodes which 265 are siblings within a single common parent must be given a unique name. 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 With the definitions provided above, the following list represents 272 the valid properties for a state node: 273 274 - compatible 275 Usage: Required 276 Value type: <stringlist> 277 Definition: Must be "arm,idle-state". 278 279 - local-timer-stop 280 Usage: See definition 281 Value type: <none> 282 Definition: if present the CPU local timer control logic is 283 lost on state entry, otherwise it is retained. 284 285 - entry-latency-us 286 Usage: Required 287 Value type: <prop-encoded-array> 288 Definition: u32 value representing worst case latency in 289 microseconds required to enter the idle state. 290 291 - exit-latency-us 292 Usage: Required 293 Value type: <prop-encoded-array> 294 Definition: u32 value representing worst case latency 295 in microseconds required to exit the idle state. 296 The exit-latency-us duration may be guaranteed 297 only after entry-latency-us has passed. 298 299 - min-residency-us 300 Usage: Required 301 Value type: <prop-encoded-array> 302 Definition: u32 value representing minimum residency duration 303 in microseconds, inclusive of preparation and 304 entry, for this idle state to be considered 305 worthwhile energy wise (refer to section 2 of 306 this document for a complete description). 307 308 - wakeup-latency-us: 309 Usage: Optional 310 Value type: <prop-encoded-array> 311 Definition: u32 value representing maximum delay between the 312 signaling of a wake-up event and the CPU being 313 able to execute normal code again. If omitted, 314 this is assumed to be equal to: 315 316 entry-latency-us + exit-latency-us 317 318 It is important to supply this value on systems 319 where the duration of PREP phase (see diagram 1, 320 section 2) is non-neglibigle. 321 In such systems entry-latency-us + exit-latency-us 322 will exceed wakeup-latency-us by this duration. 323 324 - status: 325 Usage: Optional 326 Value type: <string> 327 Definition: A standard device tree property [5] that indicates 328 the operational status of an idle-state. 329 If present, it shall be: 330 "okay": to indicate that the idle state is 331 operational. 332 "disabled": to indicate that the idle state has 333 been disabled in firmware so it is not 334 operational. 335 If the property is not present the idle-state must 336 be considered operational. 337 338 - idle-state-name: 339 Usage: Optional 340 Value type: <string> 341 Definition: A string used as a descriptive name for the idle 342 state. 343 344 In addition to the properties listed above, a state node may require 345 additional properties specific to the entry-method defined in the 346 idle-states node. Please refer to the entry-method bindings 347 documentation for properties definitions. 348 349=========================================== 3504 - Examples 351=========================================== 352 353Example 1 (ARM 64-bit, 16-cpu system, PSCI enable-method): 354 355cpus { 356 #size-cells = <0>; 357 #address-cells = <2>; 358 359 CPU0: cpu@0 { 360 device_type = "cpu"; 361 compatible = "arm,cortex-a57"; 362 reg = <0x0 0x0>; 363 enable-method = "psci"; 364 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 365 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; 366 }; 367 368 CPU1: cpu@1 { 369 device_type = "cpu"; 370 compatible = "arm,cortex-a57"; 371 reg = <0x0 0x1>; 372 enable-method = "psci"; 373 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 374 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; 375 }; 376 377 CPU2: cpu@100 { 378 device_type = "cpu"; 379 compatible = "arm,cortex-a57"; 380 reg = <0x0 0x100>; 381 enable-method = "psci"; 382 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 383 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; 384 }; 385 386 CPU3: cpu@101 { 387 device_type = "cpu"; 388 compatible = "arm,cortex-a57"; 389 reg = <0x0 0x101>; 390 enable-method = "psci"; 391 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 392 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; 393 }; 394 395 CPU4: cpu@10000 { 396 device_type = "cpu"; 397 compatible = "arm,cortex-a57"; 398 reg = <0x0 0x10000>; 399 enable-method = "psci"; 400 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 401 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; 402 }; 403 404 CPU5: cpu@10001 { 405 device_type = "cpu"; 406 compatible = "arm,cortex-a57"; 407 reg = <0x0 0x10001>; 408 enable-method = "psci"; 409 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 410 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; 411 }; 412 413 CPU6: cpu@10100 { 414 device_type = "cpu"; 415 compatible = "arm,cortex-a57"; 416 reg = <0x0 0x10100>; 417 enable-method = "psci"; 418 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 419 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; 420 }; 421 422 CPU7: cpu@10101 { 423 device_type = "cpu"; 424 compatible = "arm,cortex-a57"; 425 reg = <0x0 0x10101>; 426 enable-method = "psci"; 427 cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 428 &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; 429 }; 430 431 CPU8: cpu@100000000 { 432 device_type = "cpu"; 433 compatible = "arm,cortex-a53"; 434 reg = <0x1 0x0>; 435 enable-method = "psci"; 436 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 437 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; 438 }; 439 440 CPU9: cpu@100000001 { 441 device_type = "cpu"; 442 compatible = "arm,cortex-a53"; 443 reg = <0x1 0x1>; 444 enable-method = "psci"; 445 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 446 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; 447 }; 448 449 CPU10: cpu@100000100 { 450 device_type = "cpu"; 451 compatible = "arm,cortex-a53"; 452 reg = <0x1 0x100>; 453 enable-method = "psci"; 454 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 455 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; 456 }; 457 458 CPU11: cpu@100000101 { 459 device_type = "cpu"; 460 compatible = "arm,cortex-a53"; 461 reg = <0x1 0x101>; 462 enable-method = "psci"; 463 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 464 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; 465 }; 466 467 CPU12: cpu@100010000 { 468 device_type = "cpu"; 469 compatible = "arm,cortex-a53"; 470 reg = <0x1 0x10000>; 471 enable-method = "psci"; 472 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 473 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; 474 }; 475 476 CPU13: cpu@100010001 { 477 device_type = "cpu"; 478 compatible = "arm,cortex-a53"; 479 reg = <0x1 0x10001>; 480 enable-method = "psci"; 481 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 482 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; 483 }; 484 485 CPU14: cpu@100010100 { 486 device_type = "cpu"; 487 compatible = "arm,cortex-a53"; 488 reg = <0x1 0x10100>; 489 enable-method = "psci"; 490 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 491 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; 492 }; 493 494 CPU15: cpu@100010101 { 495 device_type = "cpu"; 496 compatible = "arm,cortex-a53"; 497 reg = <0x1 0x10101>; 498 enable-method = "psci"; 499 cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 500 &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; 501 }; 502 503 idle-states { 504 entry-method = "psci"; 505 506 CPU_RETENTION_0_0: cpu-retention-0-0 { 507 compatible = "arm,idle-state"; 508 arm,psci-suspend-param = <0x0010000>; 509 entry-latency-us = <20>; 510 exit-latency-us = <40>; 511 min-residency-us = <80>; 512 }; 513 514 CLUSTER_RETENTION_0: cluster-retention-0 { 515 compatible = "arm,idle-state"; 516 local-timer-stop; 517 arm,psci-suspend-param = <0x1010000>; 518 entry-latency-us = <50>; 519 exit-latency-us = <100>; 520 min-residency-us = <250>; 521 wakeup-latency-us = <130>; 522 }; 523 524 CPU_SLEEP_0_0: cpu-sleep-0-0 { 525 compatible = "arm,idle-state"; 526 local-timer-stop; 527 arm,psci-suspend-param = <0x0010000>; 528 entry-latency-us = <250>; 529 exit-latency-us = <500>; 530 min-residency-us = <950>; 531 }; 532 533 CLUSTER_SLEEP_0: cluster-sleep-0 { 534 compatible = "arm,idle-state"; 535 local-timer-stop; 536 arm,psci-suspend-param = <0x1010000>; 537 entry-latency-us = <600>; 538 exit-latency-us = <1100>; 539 min-residency-us = <2700>; 540 wakeup-latency-us = <1500>; 541 }; 542 543 CPU_RETENTION_1_0: cpu-retention-1-0 { 544 compatible = "arm,idle-state"; 545 arm,psci-suspend-param = <0x0010000>; 546 entry-latency-us = <20>; 547 exit-latency-us = <40>; 548 min-residency-us = <90>; 549 }; 550 551 CLUSTER_RETENTION_1: cluster-retention-1 { 552 compatible = "arm,idle-state"; 553 local-timer-stop; 554 arm,psci-suspend-param = <0x1010000>; 555 entry-latency-us = <50>; 556 exit-latency-us = <100>; 557 min-residency-us = <270>; 558 wakeup-latency-us = <100>; 559 }; 560 561 CPU_SLEEP_1_0: cpu-sleep-1-0 { 562 compatible = "arm,idle-state"; 563 local-timer-stop; 564 arm,psci-suspend-param = <0x0010000>; 565 entry-latency-us = <70>; 566 exit-latency-us = <100>; 567 min-residency-us = <300>; 568 wakeup-latency-us = <150>; 569 }; 570 571 CLUSTER_SLEEP_1: cluster-sleep-1 { 572 compatible = "arm,idle-state"; 573 local-timer-stop; 574 arm,psci-suspend-param = <0x1010000>; 575 entry-latency-us = <500>; 576 exit-latency-us = <1200>; 577 min-residency-us = <3500>; 578 wakeup-latency-us = <1300>; 579 }; 580 }; 581 582}; 583 584Example 2 (ARM 32-bit, 8-cpu system, two clusters): 585 586cpus { 587 #size-cells = <0>; 588 #address-cells = <1>; 589 590 CPU0: cpu@0 { 591 device_type = "cpu"; 592 compatible = "arm,cortex-a15"; 593 reg = <0x0>; 594 cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; 595 }; 596 597 CPU1: cpu@1 { 598 device_type = "cpu"; 599 compatible = "arm,cortex-a15"; 600 reg = <0x1>; 601 cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; 602 }; 603 604 CPU2: cpu@2 { 605 device_type = "cpu"; 606 compatible = "arm,cortex-a15"; 607 reg = <0x2>; 608 cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; 609 }; 610 611 CPU3: cpu@3 { 612 device_type = "cpu"; 613 compatible = "arm,cortex-a15"; 614 reg = <0x3>; 615 cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; 616 }; 617 618 CPU4: cpu@100 { 619 device_type = "cpu"; 620 compatible = "arm,cortex-a7"; 621 reg = <0x100>; 622 cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; 623 }; 624 625 CPU5: cpu@101 { 626 device_type = "cpu"; 627 compatible = "arm,cortex-a7"; 628 reg = <0x101>; 629 cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; 630 }; 631 632 CPU6: cpu@102 { 633 device_type = "cpu"; 634 compatible = "arm,cortex-a7"; 635 reg = <0x102>; 636 cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; 637 }; 638 639 CPU7: cpu@103 { 640 device_type = "cpu"; 641 compatible = "arm,cortex-a7"; 642 reg = <0x103>; 643 cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; 644 }; 645 646 idle-states { 647 CPU_SLEEP_0_0: cpu-sleep-0-0 { 648 compatible = "arm,idle-state"; 649 local-timer-stop; 650 entry-latency-us = <200>; 651 exit-latency-us = <100>; 652 min-residency-us = <400>; 653 wakeup-latency-us = <250>; 654 }; 655 656 CLUSTER_SLEEP_0: cluster-sleep-0 { 657 compatible = "arm,idle-state"; 658 local-timer-stop; 659 entry-latency-us = <500>; 660 exit-latency-us = <1500>; 661 min-residency-us = <2500>; 662 wakeup-latency-us = <1700>; 663 }; 664 665 CPU_SLEEP_1_0: cpu-sleep-1-0 { 666 compatible = "arm,idle-state"; 667 local-timer-stop; 668 entry-latency-us = <300>; 669 exit-latency-us = <500>; 670 min-residency-us = <900>; 671 wakeup-latency-us = <600>; 672 }; 673 674 CLUSTER_SLEEP_1: cluster-sleep-1 { 675 compatible = "arm,idle-state"; 676 local-timer-stop; 677 entry-latency-us = <800>; 678 exit-latency-us = <2000>; 679 min-residency-us = <6500>; 680 wakeup-latency-us = <2300>; 681 }; 682 }; 683 684}; 685 686=========================================== 6875 - References 688=========================================== 689 690[1] ARM Linux Kernel documentation - CPUs bindings 691 Documentation/devicetree/bindings/arm/cpus.yaml 692 693[2] ARM Linux Kernel documentation - PSCI bindings 694 Documentation/devicetree/bindings/arm/psci.yaml 695 696[3] ARM Server Base System Architecture (SBSA) 697 http://infocenter.arm.com/help/index.jsp 698 699[4] ARM Architecture Reference Manuals 700 http://infocenter.arm.com/help/index.jsp 701 702[5] Devicetree Specification 703 https://www.devicetree.org/specifications/ 704 705[6] ARM Linux Kernel documentation - Booting AArch64 Linux 706 Documentation/arm64/booting.rst 707
