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 $nodename: 36 const: psci 37 38 compatible: 39 oneOf: 40 - description: 41 For implementations complying to PSCI versions prior to 0.2. 42 const: arm,psci 43 44 - description: 45 For implementations complying to PSCI 0.2. 46 Function IDs are not required and should be ignored by an OS with 47 PSCI 0.2 support, but are permitted to be present for compatibility 48 with existing software when "arm,psci" is later in the compatible 49 list. 50 minItems: 1 51 items: 52 - const: arm,psci-0.2 53 - const: arm,psci 54 55 - description: 56 For implementations complying to PSCI 1.0. 57 PSCI 1.0 is backward compatible with PSCI 0.2 with minor 58 specification updates, as defined in the PSCI specification[2]. 59 minItems: 1 60 items: 61 - const: arm,psci-1.0 62 - const: arm,psci-0.2 63 - const: arm,psci 64 65 method: 66 description: The method of calling the PSCI firmware. 67 $ref: /schemas/types.yaml#/definitions/string-array 68 enum: 69 - smc 70 # HVC #0, with the register assignments specified in this binding. 71 - hvc 72 73 cpu_suspend: 74 $ref: /schemas/types.yaml#/definitions/uint32 75 description: Function ID for CPU_SUSPEND operation 76 77 cpu_off: 78 $ref: /schemas/types.yaml#/definitions/uint32 79 description: Function ID for CPU_OFF operation 80 81 cpu_on: 82 $ref: /schemas/types.yaml#/definitions/uint32 83 description: Function ID for CPU_ON operation 84 85 migrate: 86 $ref: /schemas/types.yaml#/definitions/uint32 87 description: Function ID for MIGRATE operation 88 89 arm,psci-suspend-param: 90 $ref: /schemas/types.yaml#/definitions/uint32 91 description: | 92 power_state parameter to pass to the PSCI suspend call. 93 94 Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie 95 idle state nodes with entry-method property is set to "psci", as per 96 bindings in [1]) must specify this property. 97 98 [1] Kernel documentation - ARM idle states bindings 99 Documentation/devicetree/bindings/cpu/idle-states.yaml 100 101patternProperties: 102 "^power-domain-": 103 $ref: /schemas/power/power-domain.yaml# 104 unevaluatedProperties: false 105 106 type: object 107 description: | 108 ARM systems can have multiple cores, sometimes in an hierarchical 109 arrangement. This often, but not always, maps directly to the processor 110 power topology of the system. Individual nodes in a topology have their 111 own specific power states and can be better represented hierarchically. 112 113 For these cases, the definitions of the idle states for the CPUs and the 114 CPU topology, must conform to the binding in [3]. The idle states 115 themselves must conform to the binding in [4] and must specify the 116 arm,psci-suspend-param property. 117 118 It should also be noted that, in PSCI firmware v1.0 the OS-Initiated 119 (OSI) CPU suspend mode is introduced. Using a hierarchical representation 120 helps to implement support for OSI mode and OS implementations may choose 121 to mandate it. 122 123 [3] Documentation/devicetree/bindings/power/power-domain.yaml 124 [4] Documentation/devicetree/bindings/power/domain-idle-state.yaml 125 126required: 127 - compatible 128 - method 129 130allOf: 131 - if: 132 properties: 133 compatible: 134 contains: 135 const: arm,psci 136 then: 137 required: 138 - cpu_off 139 - cpu_on 140 141additionalProperties: false 142 143examples: 144 - |+ 145 146 // Case 1: PSCI v0.1 only. 147 148 psci { 149 compatible = "arm,psci"; 150 method = "smc"; 151 cpu_suspend = <0x95c10000>; 152 cpu_off = <0x95c10001>; 153 cpu_on = <0x95c10002>; 154 migrate = <0x95c10003>; 155 }; 156 157 - |+ 158 159 // Case 2: PSCI v0.2 only 160 161 psci { 162 compatible = "arm,psci-0.2"; 163 method = "smc"; 164 }; 165 166 167 - |+ 168 169 // Case 3: PSCI v0.2 and PSCI v0.1. 170 171 /* 172 * A DTB may provide IDs for use by kernels without PSCI 0.2 support, 173 * enabling firmware and hypervisors to support existing and new kernels. 174 * These IDs will be ignored by kernels with PSCI 0.2 support, which will 175 * use the standard PSCI 0.2 IDs exclusively. 176 */ 177 178 psci { 179 compatible = "arm,psci-0.2", "arm,psci"; 180 method = "hvc"; 181 182 cpu_on = <0x95c10002>; 183 cpu_off = <0x95c10001>; 184 }; 185 186 - |+ 187 188 // Case 4: CPUs and CPU idle states described using the hierarchical model. 189 190 cpus { 191 #size-cells = <0>; 192 #address-cells = <1>; 193 194 CPU0: cpu@0 { 195 device_type = "cpu"; 196 compatible = "arm,cortex-a53"; 197 reg = <0x0>; 198 enable-method = "psci"; 199 power-domains = <&CPU_PD0>; 200 power-domain-names = "psci"; 201 }; 202 203 CPU1: cpu@1 { 204 device_type = "cpu"; 205 compatible = "arm,cortex-a53"; 206 reg = <0x100>; 207 enable-method = "psci"; 208 power-domains = <&CPU_PD1>; 209 power-domain-names = "psci"; 210 }; 211 212 idle-states { 213 214 CPU_PWRDN: cpu-power-down { 215 compatible = "arm,idle-state"; 216 arm,psci-suspend-param = <0x0000001>; 217 entry-latency-us = <10>; 218 exit-latency-us = <10>; 219 min-residency-us = <100>; 220 }; 221 }; 222 223 domain-idle-states { 224 225 CLUSTER_RET: cluster-retention { 226 compatible = "domain-idle-state"; 227 arm,psci-suspend-param = <0x1000011>; 228 entry-latency-us = <500>; 229 exit-latency-us = <500>; 230 min-residency-us = <2000>; 231 }; 232 233 CLUSTER_PWRDN: cluster-power-down { 234 compatible = "domain-idle-state"; 235 arm,psci-suspend-param = <0x1000031>; 236 entry-latency-us = <2000>; 237 exit-latency-us = <2000>; 238 min-residency-us = <6000>; 239 }; 240 }; 241 }; 242 243 psci { 244 compatible = "arm,psci-1.0"; 245 method = "smc"; 246 247 CPU_PD0: power-domain-cpu0 { 248 #power-domain-cells = <0>; 249 domain-idle-states = <&CPU_PWRDN>; 250 power-domains = <&CLUSTER_PD>; 251 }; 252 253 CPU_PD1: power-domain-cpu1 { 254 #power-domain-cells = <0>; 255 domain-idle-states = <&CPU_PWRDN>; 256 power-domains = <&CLUSTER_PD>; 257 }; 258 259 CLUSTER_PD: power-domain-cluster { 260 #power-domain-cells = <0>; 261 domain-idle-states = <&CLUSTER_RET>, <&CLUSTER_PWRDN>; 262 }; 263 }; 264... 265