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
7 title: Power State Coordination Interface (PSCI)
8
9 maintainers:
10 - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
11
12 description: |+
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
34 properties:
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
101 patternProperties:
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
126 required:
127 - compatible
128 - method
129
130 allOf:
131 - if:
132 properties:
133 compatible:
134 contains:
135 const: arm,psci
136 then:
137 required:
138 - cpu_off
139 - cpu_on
140
141 additionalProperties: false
142
143 examples:
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 ...
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.