0bc3c43a525ab2e801ead474be3b135824f04690
[muen/linux.git] / Documentation / devicetree / bindings / arm / psci.yaml
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   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.yaml
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.yaml
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
134 required:
135   - compatible
136   - method
137
138 allOf:
139   - if:
140       properties:
141         compatible:
142           contains:
143             const: arm,psci
144     then:
145       required:
146         - cpu_off
147         - cpu_on
148
149 examples:
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";
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-a53";
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 ...