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