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