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
106required:
107  - compatible
108  - method
109
110allOf:
111  - if:
112      properties:
113        compatible:
114          contains:
115            const: arm,psci
116    then:
117      required:
118        - cpu_off
119        - cpu_on
120
121examples:
122  - |+
123
124    // Case 1: PSCI v0.1 only.
125
126    psci {
127      compatible      = "arm,psci";
128      method          = "smc";
129      cpu_suspend     = <0x95c10000>;
130      cpu_off         = <0x95c10001>;
131      cpu_on          = <0x95c10002>;
132      migrate         = <0x95c10003>;
133    };
134
135  - |+
136
137    // Case 2: PSCI v0.2 only
138
139    psci {
140      compatible      = "arm,psci-0.2";
141      method          = "smc";
142    };
143
144
145  - |+
146
147    // Case 3: PSCI v0.2 and PSCI v0.1.
148
149    /*
150     * A DTB may provide IDs for use by kernels without PSCI 0.2 support,
151     * enabling firmware and hypervisors to support existing and new kernels.
152     * These IDs will be ignored by kernels with PSCI 0.2 support, which will
153     * use the standard PSCI 0.2 IDs exclusively.
154     */
155
156    psci {
157      compatible = "arm,psci-0.2", "arm,psci";
158      method = "hvc";
159
160      cpu_on = <0x95c10002>;
161      cpu_off = <0x95c10001>;
162    };
163...
164