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
  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          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
101patternProperties:
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
126required:
127  - compatible
128  - method
129
130allOf:
131  - if:
132      properties:
133        compatible:
134          contains:
135            const: arm,psci
136    then:
137      required:
138        - cpu_off
139        - cpu_on
140
141additionalProperties: false
142
143examples:
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    // Case 3: PSCI v0.2 and PSCI v0.1.
169
170    /*
171     * A DTB may provide IDs for use by kernels without PSCI 0.2 support,
172     * enabling firmware and hypervisors to support existing and new kernels.
173     * These IDs will be ignored by kernels with PSCI 0.2 support, which will
174     * use the standard PSCI 0.2 IDs exclusively.
175     */
176
177    psci {
178      compatible = "arm,psci-0.2", "arm,psci";
179      method = "hvc";
180
181      cpu_on = <0x95c10002>;
182      cpu_off = <0x95c10001>;
183    };
184
185  - |+
186
187    // Case 4: CPUs and CPU idle states described using the hierarchical model.
188
189    cpus {
190      #size-cells = <0>;
191      #address-cells = <1>;
192
193      cpu@0 {
194        device_type = "cpu";
195        compatible = "arm,cortex-a53";
196        reg = <0x0>;
197        enable-method = "psci";
198        power-domains = <&cpu_pd0>;
199        power-domain-names = "psci";
200      };
201
202      cpu@1 {
203        device_type = "cpu";
204        compatible = "arm,cortex-a53";
205        reg = <0x100>;
206        enable-method = "psci";
207        power-domains = <&cpu_pd1>;
208        power-domain-names = "psci";
209      };
210
211      idle-states {
212
213        cpu_pwrdn: cpu-power-down {
214          compatible = "arm,idle-state";
215          arm,psci-suspend-param = <0x0000001>;
216          entry-latency-us = <10>;
217          exit-latency-us = <10>;
218          min-residency-us = <100>;
219        };
220      };
221
222      domain-idle-states {
223
224        cluster_ret: cluster-retention {
225          compatible = "domain-idle-state";
226          arm,psci-suspend-param = <0x1000011>;
227          entry-latency-us = <500>;
228          exit-latency-us = <500>;
229          min-residency-us = <2000>;
230        };
231
232        cluster_pwrdn: cluster-power-down {
233          compatible = "domain-idle-state";
234          arm,psci-suspend-param = <0x1000031>;
235          entry-latency-us = <2000>;
236          exit-latency-us = <2000>;
237          min-residency-us = <6000>;
238        };
239      };
240    };
241
242    psci {
243      compatible = "arm,psci-1.0";
244      method = "smc";
245
246      cpu_pd0: power-domain-cpu0 {
247        #power-domain-cells = <0>;
248        domain-idle-states = <&cpu_pwrdn>;
249        power-domains = <&cluster_pd>;
250      };
251
252      cpu_pd1: power-domain-cpu1 {
253        #power-domain-cells = <0>;
254        domain-idle-states =  <&cpu_pwrdn>;
255        power-domains = <&cluster_pd>;
256      };
257
258      cluster_pd: power-domain-cluster {
259        #power-domain-cells = <0>;
260        domain-idle-states = <&cluster_ret>, <&cluster_pwrdn>;
261      };
262    };
263...