1# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
2# Copyright 2021 ARM Ltd.
3%YAML 1.2
4---
5$id: http://devicetree.org/schemas/firmware/arm,scpi.yaml#
6$schema: http://devicetree.org/meta-schemas/core.yaml#
7
8title: System Control and Power Interface (SCPI) Message Protocol bindings
9
10maintainers:
11  - Sudeep Holla <sudeep.holla@arm.com>
12
13description: |
14  Firmware implementing the SCPI described in ARM document number ARM DUI
15  0922B ("ARM Compute Subsystem SCP: Message Interface Protocols")[0] can be
16  used by Linux to initiate various system control and power operations.
17
18  This binding is intended to define the interface the firmware implementing
19  the SCPI provide for OSPM in the device tree.
20
21  [0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html
22
23properties:
24  $nodename:
25    const: scpi
26
27  compatible:
28    description:
29      SCPI compliant firmware complying to SCPI v1.0 and above OR
30      SCPI compliant firmware complying to all unversioned releases
31      prior to SCPI v1.0
32    oneOf:
33      - const: arm,scpi               # SCPI v1.0 and above
34      - const: arm,scpi-pre-1.0       # Unversioned SCPI before v1.0
35
36  mboxes:
37    description:
38      List of phandle and mailbox channel specifiers. All the channels reserved
39      by remote SCP firmware for use by SCPI message protocol should be
40      specified in any order.
41    minItems: 1
42
43  shmem:
44    description:
45      List of phandle pointing to the shared memory(SHM) area between the
46      processors using these mailboxes for IPC, one for each mailbox SHM can
47      be any memory reserved for the purpose of this communication between the
48      processors.
49    minItems: 1
50
51  power-controller:
52    type: object
53    description:
54      This sub-node represents SCPI power domain controller.
55
56    properties:
57      compatible:
58        const: arm,scpi-power-domains
59
60      '#power-domain-cells':
61        const: 1
62
63      num-domains:
64        $ref: /schemas/types.yaml#/definitions/uint32
65        description:
66          Total number of power domains provided by SCPI. This is needed as
67          the SCPI message protocol lacks a mechanism to query this
68          information at runtime.
69
70    required:
71      - compatible
72      - '#power-domain-cells'
73      - num-domains
74
75    additionalProperties: false
76
77  sensors:
78    type: object
79    description: |
80      This sub-node represents SCPI sensors controller.
81
82    properties:
83      compatible:
84        const: arm,scpi-sensors
85
86      '#thermal-sensor-cells':
87        const: 1
88
89    required:
90      - compatible
91      - '#thermal-sensor-cells'
92
93    additionalProperties: false
94
95  clocks:
96    type: object
97    description:
98      This is the container node. Each sub-node represents one of the types
99      of clock controller - indexed or full range.
100
101    properties:
102      compatible:
103        const: arm,scpi-clocks
104
105    patternProperties:
106      "^clocks-[0-9a-f]+$":
107        type: object
108        description: |
109          This sub-node represents one of the types of clock controller
110          - indexed or full range.
111
112          "arm,scpi-dvfs-clocks" - all the clocks that are variable and index
113          based. These clocks don't provide an entire range of values between
114          the limits but only discrete points within the range. The firmware
115          provides the mapping for each such operating frequency and the index
116          associated with it. The firmware also manages the voltage scaling
117          appropriately with the clock scaling.
118
119          "arm,scpi-variable-clocks" - all the clocks that are variable and
120          provide full range within the specified range. The firmware provides
121          the range of values within a specified range.
122
123        properties:
124          compatible:
125            oneOf:
126              - const: arm,scpi-dvfs-clocks
127              - const: arm,scpi-variable-clocks
128
129          '#clock-cells':
130            const: 1
131
132          clock-output-names: true
133
134          clock-indices:
135            $ref: /schemas/types.yaml#/definitions/uint32-array
136            description:
137              The identifying number for the clocks(i.e.clock_id) in the node.
138              It can be non linear and hence provide the mapping of identifiers
139              into the clock-output-names array.
140
141        required:
142          - compatible
143          - '#clock-cells'
144          - clock-output-names
145          - clock-indices
146
147        additionalProperties: false
148
149    required:
150      - compatible
151
152    additionalProperties: false
153
154additionalProperties: false
155
156required:
157  - compatible
158  - mboxes
159  - shmem
160
161examples:
162  - |
163    firmware {
164        scpi {
165            compatible = "arm,scpi";
166            mboxes = <&mhuA 1>;
167            shmem = <&cpu_scp_hpri>; /* HP-NonSecure */
168
169            scpi_devpd: power-controller {
170                compatible = "arm,scpi-power-domains";
171                num-domains = <2>;
172                #power-domain-cells = <1>;
173            };
174
175            clocks {
176                compatible = "arm,scpi-clocks";
177
178                scpi_dvfs: clocks-0 {
179                    compatible = "arm,scpi-dvfs-clocks";
180                    #clock-cells = <1>;
181                    clock-indices = <0>, <1>, <2>;
182                    clock-output-names = "atlclk", "aplclk","gpuclk";
183                };
184
185                scpi_clk: clocks-1 {
186                    compatible = "arm,scpi-variable-clocks";
187                    #clock-cells = <1>;
188                    clock-indices = <3>, <4>;
189                    clock-output-names = "pxlclk0", "pxlclk1";
190                };
191            };
192
193            scpi_sensors: sensors {
194                compatible = "arm,scpi-sensors";
195                #thermal-sensor-cells = <1>;
196            };
197
198        };
199    };
200
201    soc {
202        #address-cells = <2>;
203        #size-cells = <2>;
204
205        sram@50000000 {
206            compatible = "mmio-sram";
207            reg = <0x0 0x50000000 0x0 0x10000>;
208
209            #address-cells = <1>;
210            #size-cells = <1>;
211            ranges = <0 0x0 0x50000000 0x10000>;
212
213            cpu_scp_lpri: scp-sram-section@0 {
214                compatible = "arm,scp-shmem";
215                reg = <0x0 0x200>;
216            };
217
218            cpu_scp_hpri: scp-sram-section@200 {
219                compatible = "arm,scp-shmem";
220                reg = <0x200 0x200>;
221            };
222        };
223    };
224
225...
226