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