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,scmi.yaml#
6$schema: http://devicetree.org/meta-schemas/core.yaml#
7
8title: System Control and Management Interface (SCMI) Message Protocol bindings
9
10maintainers:
11  - Sudeep Holla <sudeep.holla@arm.com>
12
13description: |
14  The SCMI is intended to allow agents such as OSPM to manage various functions
15  that are provided by the hardware platform it is running on, including power
16  and performance functions.
17
18  This binding is intended to define the interface the firmware implementing
19  the SCMI as described in ARM document number ARM DEN 0056 ("ARM System Control
20  and Management Interface Platform Design Document")[0] provide for OSPM in
21  the device tree.
22
23  [0] https://developer.arm.com/documentation/den0056/latest
24
25properties:
26  $nodename:
27    const: scmi
28
29  compatible:
30    oneOf:
31      - description: SCMI compliant firmware with mailbox transport
32        items:
33          - const: arm,scmi
34      - description: SCMI compliant firmware with ARM SMC/HVC transport
35        items:
36          - const: arm,scmi-smc
37      - description: SCMI compliant firmware with SCMI Virtio transport.
38                     The virtio transport only supports a single device.
39        items:
40          - const: arm,scmi-virtio
41      - description: SCMI compliant firmware with OP-TEE transport
42        items:
43          - const: linaro,scmi-optee
44
45  interrupts:
46    description:
47      The interrupt that indicates message completion by the platform
48      rather than by the return of the smc call. This should not be used
49      except when the platform requires such behavior.
50    maxItems: 1
51
52  interrupt-names:
53    const: a2p
54
55  mbox-names:
56    description:
57      Specifies the mailboxes used to communicate with SCMI compliant
58      firmware.
59    items:
60      - const: tx
61      - const: rx
62
63  mboxes:
64    description:
65      List of phandle and mailbox channel specifiers. It should contain
66      exactly one or two mailboxes, one for transmitting messages("tx")
67      and another optional for receiving the notifications("rx") if supported.
68    minItems: 1
69    maxItems: 2
70
71  shmem:
72    description:
73      List of phandle pointing to the shared memory(SHM) area, for each
74      transport channel specified.
75    minItems: 1
76    maxItems: 2
77
78  '#address-cells':
79    const: 1
80
81  '#size-cells':
82    const: 0
83
84  atomic-threshold-us:
85    description:
86      An optional time value, expressed in microseconds, representing, on this
87      platform, the threshold above which any SCMI command, advertised to have
88      an higher-than-threshold execution latency, should not be considered for
89      atomic mode of operation, even if requested.
90    default: 0
91
92  arm,smc-id:
93    $ref: /schemas/types.yaml#/definitions/uint32
94    description:
95      SMC id required when using smc or hvc transports
96
97  linaro,optee-channel-id:
98    $ref: /schemas/types.yaml#/definitions/uint32
99    description:
100      Channel specifier required when using OP-TEE transport.
101
102  protocol@11:
103    type: object
104    properties:
105      reg:
106        const: 0x11
107
108      '#power-domain-cells':
109        const: 1
110
111    required:
112      - '#power-domain-cells'
113
114  protocol@13:
115    type: object
116    properties:
117      reg:
118        const: 0x13
119
120      '#clock-cells':
121        const: 1
122
123    required:
124      - '#clock-cells'
125
126  protocol@14:
127    type: object
128    properties:
129      reg:
130        const: 0x14
131
132      '#clock-cells':
133        const: 1
134
135    required:
136      - '#clock-cells'
137
138  protocol@15:
139    type: object
140    properties:
141      reg:
142        const: 0x15
143
144      '#thermal-sensor-cells':
145        const: 1
146
147    required:
148      - '#thermal-sensor-cells'
149
150  protocol@16:
151    type: object
152    properties:
153      reg:
154        const: 0x16
155
156      '#reset-cells':
157        const: 1
158
159    required:
160      - '#reset-cells'
161
162  protocol@17:
163    type: object
164    properties:
165      reg:
166        const: 0x17
167
168      regulators:
169        type: object
170        description:
171          The list of all regulators provided by this SCMI controller.
172
173        patternProperties:
174          '^regulators@[0-9a-f]+$':
175            type: object
176            $ref: "../regulator/regulator.yaml#"
177
178            properties:
179              reg:
180                maxItems: 1
181                description: Identifier for the voltage regulator.
182
183            required:
184              - reg
185
186additionalProperties: false
187
188patternProperties:
189  '^protocol@[0-9a-f]+$':
190    type: object
191    description:
192      Each sub-node represents a protocol supported. If the platform
193      supports a dedicated communication channel for a particular protocol,
194      then the corresponding transport properties must be present.
195      The virtio transport does not support a dedicated communication channel.
196
197    properties:
198      reg:
199        maxItems: 1
200
201      mbox-names:
202        items:
203          - const: tx
204          - const: rx
205
206      mboxes:
207        minItems: 1
208        maxItems: 2
209
210      shmem:
211        minItems: 1
212        maxItems: 2
213
214      linaro,optee-channel-id:
215        $ref: /schemas/types.yaml#/definitions/uint32
216        description:
217          Channel specifier required when using OP-TEE transport and
218          protocol has a dedicated communication channel.
219
220    required:
221      - reg
222
223required:
224  - compatible
225
226if:
227  properties:
228    compatible:
229      contains:
230        const: arm,scmi
231then:
232  properties:
233    interrupts: false
234    interrupt-names: false
235
236  required:
237    - mboxes
238    - shmem
239
240else:
241  if:
242    properties:
243      compatible:
244        contains:
245          const: arm,scmi-smc
246  then:
247    required:
248      - arm,smc-id
249      - shmem
250
251  else:
252    if:
253      properties:
254        compatible:
255          contains:
256            const: linaro,scmi-optee
257    then:
258      required:
259        - linaro,optee-channel-id
260
261examples:
262  - |
263    firmware {
264        scmi {
265            compatible = "arm,scmi";
266            mboxes = <&mhuB 0 0>,
267                     <&mhuB 0 1>;
268            mbox-names = "tx", "rx";
269            shmem = <&cpu_scp_lpri0>,
270                    <&cpu_scp_lpri1>;
271
272            #address-cells = <1>;
273            #size-cells = <0>;
274
275            atomic-threshold-us = <10000>;
276
277            scmi_devpd: protocol@11 {
278                reg = <0x11>;
279                #power-domain-cells = <1>;
280            };
281
282            scmi_dvfs: protocol@13 {
283                reg = <0x13>;
284                #clock-cells = <1>;
285
286                mboxes = <&mhuB 1 0>,
287                         <&mhuB 1 1>;
288                mbox-names = "tx", "rx";
289                shmem = <&cpu_scp_hpri0>,
290                        <&cpu_scp_hpri1>;
291            };
292
293            scmi_clk: protocol@14 {
294                reg = <0x14>;
295                #clock-cells = <1>;
296            };
297
298            scmi_sensors: protocol@15 {
299                reg = <0x15>;
300                #thermal-sensor-cells = <1>;
301            };
302
303            scmi_reset: protocol@16 {
304                reg = <0x16>;
305                #reset-cells = <1>;
306            };
307
308            scmi_voltage: protocol@17 {
309                reg = <0x17>;
310                regulators {
311                    #address-cells = <1>;
312                    #size-cells = <0>;
313
314                    regulator_devX: regulator@0 {
315                        reg = <0x0>;
316                        regulator-max-microvolt = <3300000>;
317                    };
318
319                    regulator_devY: regulator@9 {
320                        reg = <0x9>;
321                        regulator-min-microvolt = <500000>;
322                        regulator-max-microvolt = <4200000>;
323                    };
324                };
325            };
326        };
327    };
328
329    soc {
330        #address-cells = <2>;
331        #size-cells = <2>;
332
333        sram@50000000 {
334            compatible = "mmio-sram";
335            reg = <0x0 0x50000000 0x0 0x10000>;
336
337            #address-cells = <1>;
338            #size-cells = <1>;
339            ranges = <0 0x0 0x50000000 0x10000>;
340
341            cpu_scp_lpri0: scp-sram-section@0 {
342                compatible = "arm,scmi-shmem";
343                reg = <0x0 0x80>;
344            };
345
346            cpu_scp_lpri1: scp-sram-section@80 {
347                compatible = "arm,scmi-shmem";
348                reg = <0x80 0x80>;
349            };
350
351            cpu_scp_hpri0: scp-sram-section@100 {
352                compatible = "arm,scmi-shmem";
353                reg = <0x100 0x80>;
354            };
355
356            cpu_scp_hpri2: scp-sram-section@180 {
357                compatible = "arm,scmi-shmem";
358                reg = <0x180 0x80>;
359            };
360        };
361    };
362
363  - |
364    firmware {
365        scmi {
366            compatible = "arm,scmi-smc";
367            shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
368            arm,smc-id = <0xc3000001>;
369
370            #address-cells = <1>;
371            #size-cells = <0>;
372
373            scmi_devpd1: protocol@11 {
374                reg = <0x11>;
375                #power-domain-cells = <1>;
376            };
377        };
378    };
379
380  - |
381    firmware {
382        scmi {
383            compatible = "linaro,scmi-optee";
384            linaro,optee-channel-id = <0>;
385
386            #address-cells = <1>;
387            #size-cells = <0>;
388
389            scmi_dvfs1: protocol@13 {
390                reg = <0x13>;
391                linaro,optee-channel-id = <1>;
392                shmem = <&cpu_optee_lpri0>;
393                #clock-cells = <1>;
394            };
395
396            scmi_clk0: protocol@14 {
397                reg = <0x14>;
398                #clock-cells = <1>;
399            };
400        };
401    };
402
403    soc {
404        #address-cells = <2>;
405        #size-cells = <2>;
406
407        sram@51000000 {
408            compatible = "mmio-sram";
409            reg = <0x0 0x51000000 0x0 0x10000>;
410
411            #address-cells = <1>;
412            #size-cells = <1>;
413            ranges = <0 0x0 0x51000000 0x10000>;
414
415            cpu_optee_lpri0: optee-sram-section@0 {
416                compatible = "arm,scmi-shmem";
417                reg = <0x0 0x80>;
418            };
419        };
420    };
421
422...
423