summaryrefslogtreecommitdiff
path: root/Documentation/devicetree/bindings/arm/psci.yaml
blob: 7abdf58b335eb82b493b3ee7fe105f551e1db4c3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/arm/psci.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Power State Coordination Interface (PSCI)

maintainers:
  - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>

description: |+
  Firmware implementing the PSCI functions described in ARM document number
  ARM DEN 0022A ("Power State Coordination Interface System Software on ARM
  processors") can be used by Linux to initiate various CPU-centric power
  operations.

  Issue A of the specification describes functions for CPU suspend, hotplug
  and migration of secure software.

  Functions are invoked by trapping to the privilege level of the PSCI
  firmware (specified as part of the binding below) and passing arguments
  in a manner similar to that specified by AAPCS:

     r0       => 32-bit Function ID / return value
    {r1 - r3}	=> Parameters

  Note that the immediate field of the trapping instruction must be set
  to #0.

  [2] Power State Coordination Interface (PSCI) specification
    http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf

properties:
  compatible:
    oneOf:
      - description:
          For implementations complying to PSCI versions prior to 0.2.
        const: arm,psci

      - description:
          For implementations complying to PSCI 0.2.
        const: arm,psci-0.2

      - description:
          For implementations complying to PSCI 0.2.
          Function IDs are not required and should be ignored by an OS with
          PSCI 0.2 support, but are permitted to be present for compatibility
          with existing software when "arm,psci" is later in the compatible
          list.
        items:
          - const: arm,psci-0.2
          - const: arm,psci

      - description:
          For implementations complying to PSCI 1.0.
        const: arm,psci-1.0

      - description:
          For implementations complying to PSCI 1.0.
          PSCI 1.0 is backward compatible with PSCI 0.2 with minor
          specification updates, as defined in the PSCI specification[2].
        items:
          - const: arm,psci-1.0
          - const: arm,psci-0.2

  method:
    description: The method of calling the PSCI firmware.
    allOf:
      - $ref: /schemas/types.yaml#/definitions/string-array
      - enum:
          # SMC #0, with the register assignments specified in this binding.
          - smc
          # HVC #0, with the register assignments specified in this binding.
          - hvc

  cpu_suspend:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Function ID for CPU_SUSPEND operation

  cpu_off:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Function ID for CPU_OFF operation

  cpu_on:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Function ID for CPU_ON operation

  migrate:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Function ID for MIGRATE operation

  arm,psci-suspend-param:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: |
      power_state parameter to pass to the PSCI suspend call.

      Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie
      idle state nodes with entry-method property is set to "psci", as per
      bindings in [1]) must specify this property.

      [1] Kernel documentation - ARM idle states bindings
        Documentation/devicetree/bindings/arm/idle-states.txt


required:
  - compatible
  - method

allOf:
  - if:
      properties:
        compatible:
          contains:
            const: arm,psci
    then:
      required:
        - cpu_off
        - cpu_on

examples:
  - |+

    // Case 1: PSCI v0.1 only.

    psci {
      compatible      = "arm,psci";
      method          = "smc";
      cpu_suspend     = <0x95c10000>;
      cpu_off         = <0x95c10001>;
      cpu_on          = <0x95c10002>;
      migrate         = <0x95c10003>;
    };

  - |+

    // Case 2: PSCI v0.2 only

    psci {
      compatible      = "arm,psci-0.2";
      method          = "smc";
    };


  - |+

    // Case 3: PSCI v0.2 and PSCI v0.1.

    /*
     * A DTB may provide IDs for use by kernels without PSCI 0.2 support,
     * enabling firmware and hypervisors to support existing and new kernels.
     * These IDs will be ignored by kernels with PSCI 0.2 support, which will
     * use the standard PSCI 0.2 IDs exclusively.
     */

    psci {
      compatible = "arm,psci-0.2", "arm,psci";
      method = "hvc";

      cpu_on = <0x95c10002>;
      cpu_off = <0x95c10001>;
    };
...