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.yaml
104
105patternProperties:
106  "^power-domain-":
107    allOf:
108      - $ref: "../power/power-domain.yaml#"
109    type: object
110    description: |
111      ARM systems can have multiple cores, sometimes in an hierarchical
112      arrangement. This often, but not always, maps directly to the processor
113      power topology of the system. Individual nodes in a topology have their
114      own specific power states and can be better represented hierarchically.
115
116      For these cases, the definitions of the idle states for the CPUs and the
117      CPU topology, must conform to the binding in [3]. The idle states
118      themselves must conform to the binding in [4] and must specify the
119      arm,psci-suspend-param property.
120
121      It should also be noted that, in PSCI firmware v1.0 the OS-Initiated
122      (OSI) CPU suspend mode is introduced. Using a hierarchical representation
123      helps to implement support for OSI mode and OS implementations may choose
124      to mandate it.
125
126      [3] Documentation/devicetree/bindings/power/power-domain.yaml
127      [4] Documentation/devicetree/bindings/power/domain-idle-state.yaml
128
129required:
130  - compatible
131  - method
132
133allOf:
134  - if:
135      properties:
136        compatible:
137          contains:
138            const: arm,psci
139    then:
140      required:
141        - cpu_off
142        - cpu_on
143
144examples:
145  - |+
146
147    // Case 1: PSCI v0.1 only.
148
149    psci {
150      compatible      = "arm,psci";
151      method          = "smc";
152      cpu_suspend     = <0x95c10000>;
153      cpu_off         = <0x95c10001>;
154      cpu_on          = <0x95c10002>;
155      migrate         = <0x95c10003>;
156    };
157
158  - |+
159
160    // Case 2: PSCI v0.2 only
161
162    psci {
163      compatible      = "arm,psci-0.2";
164      method          = "smc";
165    };
166
167
168  - |+
169
170    // Case 3: PSCI v0.2 and PSCI v0.1.
171
172    /*
173     * A DTB may provide IDs for use by kernels without PSCI 0.2 support,
174     * enabling firmware and hypervisors to support existing and new kernels.
175     * These IDs will be ignored by kernels with PSCI 0.2 support, which will
176     * use the standard PSCI 0.2 IDs exclusively.
177     */
178
179    psci {
180      compatible = "arm,psci-0.2", "arm,psci";
181      method = "hvc";
182
183      cpu_on = <0x95c10002>;
184      cpu_off = <0x95c10001>;
185    };
186
187  - |+
188
189    // Case 4: CPUs and CPU idle states described using the hierarchical model.
190
191    cpus {
192      #size-cells = <0>;
193      #address-cells = <1>;
194
195      CPU0: cpu@0 {
196        device_type = "cpu";
197        compatible = "arm,cortex-a53";
198        reg = <0x0>;
199        enable-method = "psci";
200        power-domains = <&CPU_PD0>;
201        power-domain-names = "psci";
202      };
203
204      CPU1: cpu@1 {
205        device_type = "cpu";
206        compatible = "arm,cortex-a53";
207        reg = <0x100>;
208        enable-method = "psci";
209        power-domains = <&CPU_PD1>;
210        power-domain-names = "psci";
211      };
212
213      idle-states {
214
215        CPU_PWRDN: cpu-power-down {
216          compatible = "arm,idle-state";
217          arm,psci-suspend-param = <0x0000001>;
218          entry-latency-us = <10>;
219          exit-latency-us = <10>;
220          min-residency-us = <100>;
221        };
222      };
223
224      domain-idle-states {
225
226        CLUSTER_RET: cluster-retention {
227          compatible = "domain-idle-state";
228          arm,psci-suspend-param = <0x1000011>;
229          entry-latency-us = <500>;
230          exit-latency-us = <500>;
231          min-residency-us = <2000>;
232        };
233
234        CLUSTER_PWRDN: cluster-power-down {
235          compatible = "domain-idle-state";
236          arm,psci-suspend-param = <0x1000031>;
237          entry-latency-us = <2000>;
238          exit-latency-us = <2000>;
239          min-residency-us = <6000>;
240        };
241      };
242    };
243
244    psci {
245      compatible = "arm,psci-1.0";
246      method = "smc";
247
248      CPU_PD0: power-domain-cpu0 {
249        #power-domain-cells = <0>;
250        domain-idle-states = <&CPU_PWRDN>;
251        power-domains = <&CLUSTER_PD>;
252      };
253
254      CPU_PD1: power-domain-cpu1 {
255        #power-domain-cells = <0>;
256        domain-idle-states =  <&CPU_PWRDN>;
257        power-domains = <&CLUSTER_PD>;
258      };
259
260      CLUSTER_PD: power-domain-cluster {
261        #power-domain-cells = <0>;
262        domain-idle-states = <&CLUSTER_RET>, <&CLUSTER_PWRDN>;
263      };
264    };
265...
266