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.txt
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.txt
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
134required:
135  - compatible
136  - method
137
138allOf:
139  - if:
140      properties:
141        compatible:
142          contains:
143            const: arm,psci
144    then:
145      required:
146        - cpu_off
147        - cpu_on
148
149examples:
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", "arm,armv8";
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-a57", "arm,armv8";
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...
268