xref: /linux/Documentation/devicetree/bindings/firmware/arm,scmi.yaml (revision e7d759f31ca295d589f7420719c311870bb3166f) 
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
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 ARM SMC/HVC transport
38                     with shmem address(4KB-page, offset) as parameters
39        items:
40          - const: arm,scmi-smc-param
41      - description: SCMI compliant firmware with Qualcomm SMC/HVC transport
42        items:
43          - const: qcom,scmi-smc
44      - description: SCMI compliant firmware with SCMI Virtio transport.
45                     The virtio transport only supports a single device.
46        items:
47          - const: arm,scmi-virtio
48      - description: SCMI compliant firmware with OP-TEE transport
49        items:
50          - const: linaro,scmi-optee
51
52  interrupts:
53    description:
54      The interrupt that indicates message completion by the platform
55      rather than by the return of the smc call. This should not be used
56      except when the platform requires such behavior.
57    maxItems: 1
58
59  interrupt-names:
60    const: a2p
61
62  mbox-names:
63    description:
64      Specifies the mailboxes used to communicate with SCMI compliant
65      firmware.
66    oneOf:
67      - items:
68          - const: tx
69          - const: rx
70        minItems: 1
71      - items:
72          - const: tx
73          - const: tx_reply
74          - const: rx
75        minItems: 2
76
77  mboxes:
78    description:
79      List of phandle and mailbox channel specifiers. It should contain
80      exactly one, two or three mailboxes; the first one or two for transmitting
81      messages ("tx") and another optional ("rx") for receiving notifications
82      and delayed responses, if supported by the platform.
83      The number of mailboxes needed for transmitting messages depends on the
84      type of channels exposed by the specific underlying mailbox controller;
85      one single channel descriptor is enough if such channel is bidirectional,
86      while two channel descriptors are needed to represent the SCMI ("tx")
87      channel if the underlying mailbox channels are of unidirectional type.
88      The effective combination in numbers of mboxes and shmem descriptors let
89      the SCMI subsystem determine unambiguosly which type of SCMI channels are
90      made available by the underlying mailbox controller and how to use them.
91       1 mbox / 1 shmem => SCMI TX over 1 mailbox bidirectional channel
92       2 mbox / 2 shmem => SCMI TX and RX over 2 mailbox bidirectional channels
93       2 mbox / 1 shmem => SCMI TX over 2 mailbox unidirectional channels
94       3 mbox / 2 shmem => SCMI TX and RX over 3 mailbox unidirectional channels
95      Any other combination of mboxes and shmem is invalid.
96    minItems: 1
97    maxItems: 3
98
99  shmem:
100    description:
101      List of phandle pointing to the shared memory(SHM) area, for each
102      transport channel specified.
103    minItems: 1
104    maxItems: 2
105
106  '#address-cells':
107    const: 1
108
109  '#size-cells':
110    const: 0
111
112  atomic-threshold-us:
113    description:
114      An optional time value, expressed in microseconds, representing, on this
115      platform, the threshold above which any SCMI command, advertised to have
116      an higher-than-threshold execution latency, should not be considered for
117      atomic mode of operation, even if requested.
118    default: 0
119
120  arm,smc-id:
121    $ref: /schemas/types.yaml#/definitions/uint32
122    description:
123      SMC id required when using smc or hvc transports
124
125  linaro,optee-channel-id:
126    $ref: /schemas/types.yaml#/definitions/uint32
127    description:
128      Channel specifier required when using OP-TEE transport.
129
130  protocol@11:
131    $ref: '#/$defs/protocol-node'
132    unevaluatedProperties: false
133
134    properties:
135      reg:
136        const: 0x11
137
138      '#power-domain-cells':
139        const: 1
140
141    required:
142      - '#power-domain-cells'
143
144  protocol@13:
145    $ref: '#/$defs/protocol-node'
146    unevaluatedProperties: false
147
148    properties:
149      reg:
150        const: 0x13
151
152      '#clock-cells':
153        const: 1
154
155      '#power-domain-cells':
156        const: 1
157
158    oneOf:
159      - required:
160          - '#clock-cells'
161
162      - required:
163          - '#power-domain-cells'
164
165  protocol@14:
166    $ref: '#/$defs/protocol-node'
167    unevaluatedProperties: false
168
169    properties:
170      reg:
171        const: 0x14
172
173      '#clock-cells':
174        const: 1
175
176    required:
177      - '#clock-cells'
178
179  protocol@15:
180    $ref: '#/$defs/protocol-node'
181    unevaluatedProperties: false
182
183    properties:
184      reg:
185        const: 0x15
186
187      '#thermal-sensor-cells':
188        const: 1
189
190    required:
191      - '#thermal-sensor-cells'
192
193  protocol@16:
194    $ref: '#/$defs/protocol-node'
195    unevaluatedProperties: false
196
197    properties:
198      reg:
199        const: 0x16
200
201      '#reset-cells':
202        const: 1
203
204    required:
205      - '#reset-cells'
206
207  protocol@17:
208    $ref: '#/$defs/protocol-node'
209    unevaluatedProperties: false
210
211    properties:
212      reg:
213        const: 0x17
214
215      regulators:
216        type: object
217        additionalProperties: false
218        description:
219          The list of all regulators provided by this SCMI controller.
220
221        properties:
222          '#address-cells':
223            const: 1
224
225          '#size-cells':
226            const: 0
227
228        patternProperties:
229          '^regulator@[0-9a-f]+$':
230            type: object
231            $ref: /schemas/regulator/regulator.yaml#
232            unevaluatedProperties: false
233
234            properties:
235              reg:
236                maxItems: 1
237                description: Identifier for the voltage regulator.
238
239            required:
240              - reg
241
242  protocol@18:
243    $ref: '#/$defs/protocol-node'
244    unevaluatedProperties: false
245
246    properties:
247      reg:
248        const: 0x18
249
250additionalProperties: false
251
252$defs:
253  protocol-node:
254    type: object
255    description:
256      Each sub-node represents a protocol supported. If the platform
257      supports a dedicated communication channel for a particular protocol,
258      then the corresponding transport properties must be present.
259      The virtio transport does not support a dedicated communication channel.
260
261    properties:
262      reg:
263        maxItems: 1
264
265      mbox-names:
266        oneOf:
267          - items:
268              - const: tx
269              - const: rx
270            minItems: 1
271          - items:
272              - const: tx
273              - const: tx_reply
274              - const: rx
275            minItems: 2
276
277      mboxes:
278        minItems: 1
279        maxItems: 3
280
281      shmem:
282        minItems: 1
283        maxItems: 2
284
285      linaro,optee-channel-id:
286        $ref: /schemas/types.yaml#/definitions/uint32
287        description:
288          Channel specifier required when using OP-TEE transport and
289          protocol has a dedicated communication channel.
290
291    required:
292      - reg
293
294required:
295  - compatible
296
297if:
298  properties:
299    compatible:
300      contains:
301        const: arm,scmi
302then:
303  properties:
304    interrupts: false
305    interrupt-names: false
306
307  required:
308    - mboxes
309    - shmem
310
311else:
312  if:
313    properties:
314      compatible:
315        contains:
316          enum:
317            - arm,scmi-smc
318            - arm,scmi-smc-param
319            - qcom,scmi-smc
320  then:
321    required:
322      - arm,smc-id
323      - shmem
324
325  else:
326    if:
327      properties:
328        compatible:
329          contains:
330            const: linaro,scmi-optee
331    then:
332      required:
333        - linaro,optee-channel-id
334
335examples:
336  - |
337    firmware {
338        scmi {
339            compatible = "arm,scmi";
340            mboxes = <&mhuB 0 0>,
341                     <&mhuB 0 1>;
342            mbox-names = "tx", "rx";
343            shmem = <&cpu_scp_lpri0>,
344                    <&cpu_scp_lpri1>;
345
346            #address-cells = <1>;
347            #size-cells = <0>;
348
349            atomic-threshold-us = <10000>;
350
351            scmi_devpd: protocol@11 {
352                reg = <0x11>;
353                #power-domain-cells = <1>;
354            };
355
356            scmi_dvfs: protocol@13 {
357                reg = <0x13>;
358                #clock-cells = <1>;
359
360                mboxes = <&mhuB 1 0>,
361                         <&mhuB 1 1>;
362                mbox-names = "tx", "rx";
363                shmem = <&cpu_scp_hpri0>,
364                        <&cpu_scp_hpri1>;
365            };
366
367            scmi_clk: protocol@14 {
368                reg = <0x14>;
369                #clock-cells = <1>;
370            };
371
372            scmi_sensors: protocol@15 {
373                reg = <0x15>;
374                #thermal-sensor-cells = <1>;
375            };
376
377            scmi_reset: protocol@16 {
378                reg = <0x16>;
379                #reset-cells = <1>;
380            };
381
382            scmi_voltage: protocol@17 {
383                reg = <0x17>;
384                regulators {
385                    #address-cells = <1>;
386                    #size-cells = <0>;
387
388                    regulator_devX: regulator@0 {
389                        reg = <0x0>;
390                        regulator-max-microvolt = <3300000>;
391                    };
392
393                    regulator_devY: regulator@9 {
394                        reg = <0x9>;
395                        regulator-min-microvolt = <500000>;
396                        regulator-max-microvolt = <4200000>;
397                    };
398                };
399            };
400
401            scmi_powercap: protocol@18 {
402                reg = <0x18>;
403            };
404        };
405    };
406
407    soc {
408        #address-cells = <2>;
409        #size-cells = <2>;
410
411        sram@50000000 {
412            compatible = "mmio-sram";
413            reg = <0x0 0x50000000 0x0 0x10000>;
414
415            #address-cells = <1>;
416            #size-cells = <1>;
417            ranges = <0 0x0 0x50000000 0x10000>;
418
419            cpu_scp_lpri0: scp-sram-section@0 {
420                compatible = "arm,scmi-shmem";
421                reg = <0x0 0x80>;
422            };
423
424            cpu_scp_lpri1: scp-sram-section@80 {
425                compatible = "arm,scmi-shmem";
426                reg = <0x80 0x80>;
427            };
428
429            cpu_scp_hpri0: scp-sram-section@100 {
430                compatible = "arm,scmi-shmem";
431                reg = <0x100 0x80>;
432            };
433
434            cpu_scp_hpri2: scp-sram-section@180 {
435                compatible = "arm,scmi-shmem";
436                reg = <0x180 0x80>;
437            };
438        };
439    };
440
441  - |
442    firmware {
443        scmi {
444            compatible = "arm,scmi-smc";
445            shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
446            arm,smc-id = <0xc3000001>;
447
448            #address-cells = <1>;
449            #size-cells = <0>;
450
451            scmi_devpd1: protocol@11 {
452                reg = <0x11>;
453                #power-domain-cells = <1>;
454            };
455        };
456    };
457
458  - |
459    firmware {
460        scmi {
461            compatible = "linaro,scmi-optee";
462            linaro,optee-channel-id = <0>;
463
464            #address-cells = <1>;
465            #size-cells = <0>;
466
467            scmi_dvfs1: protocol@13 {
468                reg = <0x13>;
469                linaro,optee-channel-id = <1>;
470                shmem = <&cpu_optee_lpri0>;
471                #clock-cells = <1>;
472            };
473
474            scmi_clk0: protocol@14 {
475                reg = <0x14>;
476                #clock-cells = <1>;
477            };
478        };
479    };
480
481    soc {
482        #address-cells = <2>;
483        #size-cells = <2>;
484
485        sram@51000000 {
486            compatible = "mmio-sram";
487            reg = <0x0 0x51000000 0x0 0x10000>;
488
489            #address-cells = <1>;
490            #size-cells = <1>;
491            ranges = <0 0x0 0x51000000 0x10000>;
492
493            cpu_optee_lpri0: optee-sram-section@0 {
494                compatible = "arm,scmi-shmem";
495                reg = <0x0 0x80>;
496            };
497        };
498    };
499
500...
501