diff options
Diffstat (limited to '')
| -rw-r--r-- | Documentation/devicetree/bindings/arm/idle-states.yaml | 661 |
1 files changed, 0 insertions, 661 deletions
diff --git a/Documentation/devicetree/bindings/arm/idle-states.yaml b/Documentation/devicetree/bindings/arm/idle-states.yaml deleted file mode 100644 index 52bce5dbb11f..000000000000 --- a/Documentation/devicetree/bindings/arm/idle-states.yaml +++ /dev/null @@ -1,661 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/arm/idle-states.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: ARM idle states binding description - -maintainers: - - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com> - -description: |+ - ========================================== - 1 - Introduction - ========================================== - - ARM systems contain HW capable of managing power consumption dynamically, - where cores can be put in different low-power states (ranging from simple wfi - to power gating) according to OS PM policies. The CPU states representing the - range of dynamic idle states that a processor can enter at run-time, can be - specified through device tree bindings representing the parameters required to - enter/exit specific idle states on a given processor. - - According to the Server Base System Architecture document (SBSA, [3]), the - power states an ARM CPU can be put into are identified by the following list: - - - Running - - Idle_standby - - Idle_retention - - Sleep - - Off - - The power states described in the SBSA document define the basic CPU states on - top of which ARM platforms implement power management schemes that allow an OS - PM implementation to put the processor in different idle states (which include - states listed above; "off" state is not an idle state since it does not have - wake-up capabilities, hence it is not considered in this document). - - Idle state parameters (e.g. entry latency) are platform specific and need to - be characterized with bindings that provide the required information to OS PM - code so that it can build the required tables and use them at runtime. - - The device tree binding definition for ARM idle states is the subject of this - document. - - =========================================== - 2 - idle-states definitions - =========================================== - - Idle states are characterized for a specific system through a set of - timing and energy related properties, that underline the HW behaviour - triggered upon idle states entry and exit. - - The following diagram depicts the CPU execution phases and related timing - properties required to enter and exit an idle state: - - ..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__.. - | | | | | - - |<------ entry ------->| - | latency | - |<- exit ->| - | latency | - |<-------- min-residency -------->| - |<------- wakeup-latency ------->| - - Diagram 1: CPU idle state execution phases - - EXEC: Normal CPU execution. - - PREP: Preparation phase before committing the hardware to idle mode - like cache flushing. This is abortable on pending wake-up - event conditions. The abort latency is assumed to be negligible - (i.e. less than the ENTRY + EXIT duration). If aborted, CPU - goes back to EXEC. This phase is optional. If not abortable, - this should be included in the ENTRY phase instead. - - ENTRY: The hardware is committed to idle mode. This period must run - to completion up to IDLE before anything else can happen. - - IDLE: This is the actual energy-saving idle period. This may last - between 0 and infinite time, until a wake-up event occurs. - - EXIT: Period during which the CPU is brought back to operational - mode (EXEC). - - entry-latency: Worst case latency required to enter the idle state. The - exit-latency may be guaranteed only after entry-latency has passed. - - min-residency: Minimum period, including preparation and entry, for a given - idle state to be worthwhile energywise. - - wakeup-latency: Maximum delay between the signaling of a wake-up event and the - CPU being able to execute normal code again. If not specified, this is assumed - to be entry-latency + exit-latency. - - These timing parameters can be used by an OS in different circumstances. - - An idle CPU requires the expected min-residency time to select the most - appropriate idle state based on the expected expiry time of the next IRQ - (i.e. wake-up) that causes the CPU to return to the EXEC phase. - - An operating system scheduler may need to compute the shortest wake-up delay - for CPUs in the system by detecting how long will it take to get a CPU out - of an idle state, e.g.: - - wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0) - - In other words, the scheduler can make its scheduling decision by selecting - (e.g. waking-up) the CPU with the shortest wake-up delay. - The wake-up delay must take into account the entry latency if that period - has not expired. The abortable nature of the PREP period can be ignored - if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than - the worst case since it depends on the CPU operating conditions, i.e. caches - state). - - An OS has to reliably probe the wakeup-latency since some devices can enforce - latency constraint guarantees to work properly, so the OS has to detect the - worst case wake-up latency it can incur if a CPU is allowed to enter an - idle state, and possibly to prevent that to guarantee reliable device - functioning. - - The min-residency time parameter deserves further explanation since it is - expressed in time units but must factor in energy consumption coefficients. - - The energy consumption of a cpu when it enters a power state can be roughly - characterised by the following graph: - - | - | - | - e | - n | /--- - e | /------ - r | /------ - g | /----- - y | /------ - | ---- - | /| - | / | - | / | - | / | - | / | - | / | - |/ | - -----|-------+---------------------------------- - 0| 1 time(ms) - - Graph 1: Energy vs time example - - The graph is split in two parts delimited by time 1ms on the X-axis. - The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope - and denotes the energy costs incurred while entering and leaving the idle - state. - The graph curve in the area delimited by X-axis values = {x | x > 1ms } has - shallower slope and essentially represents the energy consumption of the idle - state. - - min-residency is defined for a given idle state as the minimum expected - residency time for a state (inclusive of preparation and entry) after - which choosing that state become the most energy efficient option. A good - way to visualise this, is by taking the same graph above and comparing some - states energy consumptions plots. - - For sake of simplicity, let's consider a system with two idle states IDLE1, - and IDLE2: - - | - | - | - | /-- IDLE1 - e | /--- - n | /---- - e | /--- - r | /-----/--------- IDLE2 - g | /-------/--------- - y | ------------ /---| - | / /---- | - | / /--- | - | / /---- | - | / /--- | - | --- | - | / | - | / | - |/ | time - ---/----------------------------+------------------------ - |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy - | - IDLE2-min-residency - - Graph 2: idle states min-residency example - - In graph 2 above, that takes into account idle states entry/exit energy - costs, it is clear that if the idle state residency time (i.e. time till next - wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state - choice energywise. - - This is mainly down to the fact that IDLE1 entry/exit energy costs are lower - than IDLE2. - - However, the lower power consumption (i.e. shallower energy curve slope) of - idle state IDLE2 implies that after a suitable time, IDLE2 becomes more energy - efficient. - - The time at which IDLE2 becomes more energy efficient than IDLE1 (and other - shallower states in a system with multiple idle states) is defined - IDLE2-min-residency and corresponds to the time when energy consumption of - IDLE1 and IDLE2 states breaks even. - - The definitions provided in this section underpin the idle states - properties specification that is the subject of the following sections. - - =========================================== - 3 - idle-states node - =========================================== - - ARM processor idle states are defined within the idle-states node, which is - a direct child of the cpus node [1] and provides a container where the - processor idle states, defined as device tree nodes, are listed. - - On ARM systems, it is a container of processor idle states nodes. If the - system does not provide CPU power management capabilities, or the processor - just supports idle_standby, an idle-states node is not required. - - =========================================== - 4 - References - =========================================== - - [1] ARM Linux Kernel documentation - CPUs bindings - Documentation/devicetree/bindings/arm/cpus.yaml - - [2] ARM Linux Kernel documentation - PSCI bindings - Documentation/devicetree/bindings/arm/psci.yaml - - [3] ARM Server Base System Architecture (SBSA) - http://infocenter.arm.com/help/index.jsp - - [4] ARM Architecture Reference Manuals - http://infocenter.arm.com/help/index.jsp - - [6] ARM Linux Kernel documentation - Booting AArch64 Linux - Documentation/arm64/booting.rst - -properties: - $nodename: - const: idle-states - - entry-method: - description: | - Usage and definition depend on ARM architecture version. - - On ARM v8 64-bit this property is required. - On ARM 32-bit systems this property is optional - - This assumes that the "enable-method" property is set to "psci" in the cpu - node[6] that is responsible for setting up CPU idle management in the OS - implementation. - const: psci - -patternProperties: - "^(cpu|cluster)-": - type: object - description: | - Each state node represents an idle state description and must be defined - as follows. - - The idle state entered by executing the wfi instruction (idle_standby - SBSA,[3][4]) is considered standard on all ARM platforms and therefore - must not be listed. - - In addition to the properties listed above, a state node may require - additional properties specific to the entry-method defined in the - idle-states node. Please refer to the entry-method bindings - documentation for properties definitions. - - properties: - compatible: - const: arm,idle-state - - local-timer-stop: - description: - If present the CPU local timer control logic is - lost on state entry, otherwise it is retained. - type: boolean - - entry-latency-us: - description: - Worst case latency in microseconds required to enter the idle state. - - exit-latency-us: - description: - Worst case latency in microseconds required to exit the idle state. - The exit-latency-us duration may be guaranteed only after - entry-latency-us has passed. - - min-residency-us: - description: - Minimum residency duration in microseconds, inclusive of preparation - and entry, for this idle state to be considered worthwhile energy wise - (refer to section 2 of this document for a complete description). - - wakeup-latency-us: - description: | - Maximum delay between the signaling of a wake-up event and the CPU - being able to execute normal code again. If omitted, this is assumed - to be equal to: - - entry-latency-us + exit-latency-us - - It is important to supply this value on systems where the duration of - PREP phase (see diagram 1, section 2) is non-neglibigle. In such - systems entry-latency-us + exit-latency-us will exceed - wakeup-latency-us by this duration. - - idle-state-name: - $ref: /schemas/types.yaml#/definitions/string - description: - A string used as a descriptive name for the idle state. - - required: - - compatible - - entry-latency-us - - exit-latency-us - - min-residency-us - -additionalProperties: false - -examples: - - | - - cpus { - #size-cells = <0>; - #address-cells = <2>; - - cpu@0 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x0>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - cpu@1 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x1>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - cpu@100 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x100>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - cpu@101 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x101>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - cpu@10000 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10000>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - cpu@10001 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10001>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - cpu@10100 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10100>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - cpu@10101 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10101>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 - &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; - }; - - cpu@100000000 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x0>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - cpu@100000001 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x1>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - cpu@100000100 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x100>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - cpu@100000101 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x101>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - cpu@100010000 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x10000>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - cpu@100010001 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x10001>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - cpu@100010100 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x10100>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - cpu@100010101 { - device_type = "cpu"; - compatible = "arm,cortex-a53"; - reg = <0x1 0x10101>; - enable-method = "psci"; - cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 - &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; - }; - - idle-states { - entry-method = "psci"; - - CPU_RETENTION_0_0: cpu-retention-0-0 { - compatible = "arm,idle-state"; - arm,psci-suspend-param = <0x0010000>; - entry-latency-us = <20>; - exit-latency-us = <40>; - min-residency-us = <80>; - }; - - CLUSTER_RETENTION_0: cluster-retention-0 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x1010000>; - entry-latency-us = <50>; - exit-latency-us = <100>; - min-residency-us = <250>; - wakeup-latency-us = <130>; - }; - - CPU_SLEEP_0_0: cpu-sleep-0-0 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x0010000>; - entry-latency-us = <250>; - exit-latency-us = <500>; - min-residency-us = <950>; - }; - - CLUSTER_SLEEP_0: cluster-sleep-0 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x1010000>; - entry-latency-us = <600>; - exit-latency-us = <1100>; - min-residency-us = <2700>; - wakeup-latency-us = <1500>; - }; - - CPU_RETENTION_1_0: cpu-retention-1-0 { - compatible = "arm,idle-state"; - arm,psci-suspend-param = <0x0010000>; - entry-latency-us = <20>; - exit-latency-us = <40>; - min-residency-us = <90>; - }; - - CLUSTER_RETENTION_1: cluster-retention-1 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x1010000>; - entry-latency-us = <50>; - exit-latency-us = <100>; - min-residency-us = <270>; - wakeup-latency-us = <100>; - }; - - CPU_SLEEP_1_0: cpu-sleep-1-0 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x0010000>; - entry-latency-us = <70>; - exit-latency-us = <100>; - min-residency-us = <300>; - wakeup-latency-us = <150>; - }; - - CLUSTER_SLEEP_1: cluster-sleep-1 { - compatible = "arm,idle-state"; - local-timer-stop; - arm,psci-suspend-param = <0x1010000>; - entry-latency-us = <500>; - exit-latency-us = <1200>; - min-residency-us = <3500>; - wakeup-latency-us = <1300>; - }; - }; - }; - - - | - // Example 2 (ARM 32-bit, 8-cpu system, two clusters): - - cpus { - #size-cells = <0>; - #address-cells = <1>; - - cpu@0 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x0>; - cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>; - }; - - cpu@1 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x1>; - cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>; - }; - - cpu@2 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x2>; - cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>; - }; - - cpu@3 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x3>; - cpu-idle-states = <&cpu_sleep_0_0 &cluster_sleep_0>; - }; - - cpu@100 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x100>; - cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>; - }; - - cpu@101 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x101>; - cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>; - }; - - cpu@102 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x102>; - cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>; - }; - - cpu@103 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x103>; - cpu-idle-states = <&cpu_sleep_1_0 &cluster_sleep_1>; - }; - - idle-states { - cpu_sleep_0_0: cpu-sleep-0-0 { - compatible = "arm,idle-state"; - local-timer-stop; - entry-latency-us = <200>; - exit-latency-us = <100>; - min-residency-us = <400>; - wakeup-latency-us = <250>; - }; - - cluster_sleep_0: cluster-sleep-0 { - compatible = "arm,idle-state"; - local-timer-stop; - entry-latency-us = <500>; - exit-latency-us = <1500>; - min-residency-us = <2500>; - wakeup-latency-us = <1700>; - }; - - cpu_sleep_1_0: cpu-sleep-1-0 { - compatible = "arm,idle-state"; - local-timer-stop; - entry-latency-us = <300>; - exit-latency-us = <500>; - min-residency-us = <900>; - wakeup-latency-us = <600>; - }; - - cluster_sleep_1: cluster-sleep-1 { - compatible = "arm,idle-state"; - local-timer-stop; - entry-latency-us = <800>; - exit-latency-us = <2000>; - min-residency-us = <6500>; - wakeup-latency-us = <2300>; - }; - }; - }; - -... |