1# SPDX-License-Identifier: GPL-2.0 2%YAML 1.2 3--- 4$id: http://devicetree.org/schemas/arm/psci.yaml# 5$schema: http://devicetree.org/meta-schemas/core.yaml# 6 7title: Power State Coordination Interface (PSCI) 8 9maintainers: 10 - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com> 11 12description: |+ 13 Firmware implementing the PSCI functions described in ARM document number 14 ARM DEN 0022A ("Power State Coordination Interface System Software on ARM 15 processors") can be used by Linux to initiate various CPU-centric power 16 operations. 17 18 Issue A of the specification describes functions for CPU suspend, hotplug 19 and migration of secure software. 20 21 Functions are invoked by trapping to the privilege level of the PSCI 22 firmware (specified as part of the binding below) and passing arguments 23 in a manner similar to that specified by AAPCS: 24 25 r0 => 32-bit Function ID / return value 26 {r1 - r3} => Parameters 27 28 Note that the immediate field of the trapping instruction must be set 29 to #0. 30 31 [2] Power State Coordination Interface (PSCI) specification 32 http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf 33 34properties: 35 compatible: 36 oneOf: 37 - description: 38 For implementations complying to PSCI versions prior to 0.2. 39 const: arm,psci 40 41 - description: 42 For implementations complying to PSCI 0.2. 43 const: arm,psci-0.2 44 45 - description: 46 For implementations complying to PSCI 0.2. 47 Function IDs are not required and should be ignored by an OS with 48 PSCI 0.2 support, but are permitted to be present for compatibility 49 with existing software when "arm,psci" is later in the compatible 50 list. 51 items: 52 - const: arm,psci-0.2 53 - const: arm,psci 54 55 - description: 56 For implementations complying to PSCI 1.0. 57 const: arm,psci-1.0 58 59 - description: 60 For implementations complying to PSCI 1.0. 61 PSCI 1.0 is backward compatible with PSCI 0.2 with minor 62 specification updates, as defined in the PSCI specification[2]. 63 items: 64 - const: arm,psci-1.0 65 - const: arm,psci-0.2 66 67 method: 68 description: The method of calling the PSCI firmware. 69 allOf: 70 - $ref: /schemas/types.yaml#/definitions/string-array 71 - enum: 72 # SMC #0, with the register assignments specified in this binding. 73 - smc 74 # HVC #0, with the register assignments specified in this binding. 75 - hvc 76 77 cpu_suspend: 78 $ref: /schemas/types.yaml#/definitions/uint32 79 description: Function ID for CPU_SUSPEND operation 80 81 cpu_off: 82 $ref: /schemas/types.yaml#/definitions/uint32 83 description: Function ID for CPU_OFF operation 84 85 cpu_on: 86 $ref: /schemas/types.yaml#/definitions/uint32 87 description: Function ID for CPU_ON operation 88 89 migrate: 90 $ref: /schemas/types.yaml#/definitions/uint32 91 description: Function ID for MIGRATE operation 92 93 arm,psci-suspend-param: 94 $ref: /schemas/types.yaml#/definitions/uint32 95 description: | 96 power_state parameter to pass to the PSCI suspend call. 97 98 Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie 99 idle state nodes with entry-method property is set to "psci", as per 100 bindings in [1]) must specify this property. 101 102 [1] Kernel documentation - ARM idle states bindings 103 Documentation/devicetree/bindings/arm/idle-states.txt 104 105 "#power-domain-cells": 106 description: 107 The number of cells in a PM domain specifier as per binding in [3]. 108 Must be 0 as to represent a single PM domain. 109 110 ARM systems can have multiple cores, sometimes in an hierarchical 111 arrangement. This often, but not always, maps directly to the processor 112 power topology of the system. Individual nodes in a topology have their 113 own specific power states and can be better represented hierarchically. 114 115 For these cases, the definitions of the idle states for the CPUs and the 116 CPU topology, must conform to the binding in [3]. The idle states 117 themselves must conform to the binding in [4] and must specify the 118 arm,psci-suspend-param property. 119 120 It should also be noted that, in PSCI firmware v1.0 the OS-Initiated 121 (OSI) CPU suspend mode is introduced. Using a hierarchical representation 122 helps to implement support for OSI mode and OS implementations may choose 123 to mandate it. 124 125 [3] Documentation/devicetree/bindings/power/power_domain.txt 126 [4] Documentation/devicetree/bindings/power/domain-idle-state.txt 127 128 power-domains: 129 $ref: '/schemas/types.yaml#/definitions/phandle-array' 130 description: 131 List of phandles and PM domain specifiers, as defined by bindings of the 132 PM domain provider. 133 134required: 135 - compatible 136 - method 137 138allOf: 139 - if: 140 properties: 141 compatible: 142 contains: 143 const: arm,psci 144 then: 145 required: 146 - cpu_off 147 - cpu_on 148 149examples: 150 - |+ 151 152 // Case 1: PSCI v0.1 only. 153 154 psci { 155 compatible = "arm,psci"; 156 method = "smc"; 157 cpu_suspend = <0x95c10000>; 158 cpu_off = <0x95c10001>; 159 cpu_on = <0x95c10002>; 160 migrate = <0x95c10003>; 161 }; 162 163 - |+ 164 165 // Case 2: PSCI v0.2 only 166 167 psci { 168 compatible = "arm,psci-0.2"; 169 method = "smc"; 170 }; 171 172 173 - |+ 174 175 // Case 3: PSCI v0.2 and PSCI v0.1. 176 177 /* 178 * A DTB may provide IDs for use by kernels without PSCI 0.2 support, 179 * enabling firmware and hypervisors to support existing and new kernels. 180 * These IDs will be ignored by kernels with PSCI 0.2 support, which will 181 * use the standard PSCI 0.2 IDs exclusively. 182 */ 183 184 psci { 185 compatible = "arm,psci-0.2", "arm,psci"; 186 method = "hvc"; 187 188 cpu_on = <0x95c10002>; 189 cpu_off = <0x95c10001>; 190 }; 191 192 - |+ 193 194 // Case 4: CPUs and CPU idle states described using the hierarchical model. 195 196 cpus { 197 #size-cells = <0>; 198 #address-cells = <1>; 199 200 CPU0: cpu@0 { 201 device_type = "cpu"; 202 compatible = "arm,cortex-a53", "arm,armv8"; 203 reg = <0x0>; 204 enable-method = "psci"; 205 power-domains = <&CPU_PD0>; 206 power-domain-names = "psci"; 207 }; 208 209 CPU1: cpu@1 { 210 device_type = "cpu"; 211 compatible = "arm,cortex-a57", "arm,armv8"; 212 reg = <0x100>; 213 enable-method = "psci"; 214 power-domains = <&CPU_PD1>; 215 power-domain-names = "psci"; 216 }; 217 218 idle-states { 219 220 CPU_PWRDN: cpu-power-down { 221 compatible = "arm,idle-state"; 222 arm,psci-suspend-param = <0x0000001>; 223 entry-latency-us = <10>; 224 exit-latency-us = <10>; 225 min-residency-us = <100>; 226 }; 227 228 CLUSTER_RET: cluster-retention { 229 compatible = "domain-idle-state"; 230 arm,psci-suspend-param = <0x1000011>; 231 entry-latency-us = <500>; 232 exit-latency-us = <500>; 233 min-residency-us = <2000>; 234 }; 235 236 CLUSTER_PWRDN: cluster-power-down { 237 compatible = "domain-idle-state"; 238 arm,psci-suspend-param = <0x1000031>; 239 entry-latency-us = <2000>; 240 exit-latency-us = <2000>; 241 min-residency-us = <6000>; 242 }; 243 }; 244 }; 245 246 psci { 247 compatible = "arm,psci-1.0"; 248 method = "smc"; 249 250 CPU_PD0: cpu-pd0 { 251 #power-domain-cells = <0>; 252 domain-idle-states = <&CPU_PWRDN>; 253 power-domains = <&CLUSTER_PD>; 254 }; 255 256 CPU_PD1: cpu-pd1 { 257 #power-domain-cells = <0>; 258 domain-idle-states = <&CPU_PWRDN>; 259 power-domains = <&CLUSTER_PD>; 260 }; 261 262 CLUSTER_PD: cluster-pd { 263 #power-domain-cells = <0>; 264 domain-idle-states = <&CLUSTER_RET>, <&CLUSTER_PWRDN>; 265 }; 266 }; 267... 268