xref: /linux/Documentation/devicetree/bindings/firmware/arm,scmi.yaml (revision ea68a3e9d14e9e0bf017d178fb4bd53b6deb1482) 
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    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    $ref: '#/$defs/protocol-node'
104    unevaluatedProperties: false
105
106    properties:
107      reg:
108        const: 0x11
109
110      '#power-domain-cells':
111        const: 1
112
113    required:
114      - '#power-domain-cells'
115
116  protocol@13:
117    $ref: '#/$defs/protocol-node'
118    unevaluatedProperties: false
119
120    properties:
121      reg:
122        const: 0x13
123
124      '#clock-cells':
125        const: 1
126
127    required:
128      - '#clock-cells'
129
130  protocol@14:
131    $ref: '#/$defs/protocol-node'
132    unevaluatedProperties: false
133
134    properties:
135      reg:
136        const: 0x14
137
138      '#clock-cells':
139        const: 1
140
141    required:
142      - '#clock-cells'
143
144  protocol@15:
145    $ref: '#/$defs/protocol-node'
146    unevaluatedProperties: false
147
148    properties:
149      reg:
150        const: 0x15
151
152      '#thermal-sensor-cells':
153        const: 1
154
155    required:
156      - '#thermal-sensor-cells'
157
158  protocol@16:
159    $ref: '#/$defs/protocol-node'
160    unevaluatedProperties: false
161
162    properties:
163      reg:
164        const: 0x16
165
166      '#reset-cells':
167        const: 1
168
169    required:
170      - '#reset-cells'
171
172  protocol@17:
173    $ref: '#/$defs/protocol-node'
174    unevaluatedProperties: false
175
176    properties:
177      reg:
178        const: 0x17
179
180      regulators:
181        type: object
182        additionalProperties: false
183        description:
184          The list of all regulators provided by this SCMI controller.
185
186        properties:
187          '#address-cells':
188            const: 1
189
190          '#size-cells':
191            const: 0
192
193        patternProperties:
194          '^regulator@[0-9a-f]+$':
195            type: object
196            $ref: "../regulator/regulator.yaml#"
197            unevaluatedProperties: false
198
199            properties:
200              reg:
201                maxItems: 1
202                description: Identifier for the voltage regulator.
203
204            required:
205              - reg
206
207  protocol@18:
208    $ref: '#/$defs/protocol-node'
209    unevaluatedProperties: false
210
211    properties:
212      reg:
213        const: 0x18
214
215additionalProperties: false
216
217$defs:
218  protocol-node:
219    type: object
220    description:
221      Each sub-node represents a protocol supported. If the platform
222      supports a dedicated communication channel for a particular protocol,
223      then the corresponding transport properties must be present.
224      The virtio transport does not support a dedicated communication channel.
225
226    properties:
227      reg:
228        maxItems: 1
229
230      mbox-names:
231        items:
232          - const: tx
233          - const: rx
234
235      mboxes:
236        minItems: 1
237        maxItems: 2
238
239      shmem:
240        minItems: 1
241        maxItems: 2
242
243      linaro,optee-channel-id:
244        $ref: /schemas/types.yaml#/definitions/uint32
245        description:
246          Channel specifier required when using OP-TEE transport and
247          protocol has a dedicated communication channel.
248
249    required:
250      - reg
251
252required:
253  - compatible
254
255if:
256  properties:
257    compatible:
258      contains:
259        const: arm,scmi
260then:
261  properties:
262    interrupts: false
263    interrupt-names: false
264
265  required:
266    - mboxes
267    - shmem
268
269else:
270  if:
271    properties:
272      compatible:
273        contains:
274          const: arm,scmi-smc
275  then:
276    required:
277      - arm,smc-id
278      - shmem
279
280  else:
281    if:
282      properties:
283        compatible:
284          contains:
285            const: linaro,scmi-optee
286    then:
287      required:
288        - linaro,optee-channel-id
289
290examples:
291  - |
292    firmware {
293        scmi {
294            compatible = "arm,scmi";
295            mboxes = <&mhuB 0 0>,
296                     <&mhuB 0 1>;
297            mbox-names = "tx", "rx";
298            shmem = <&cpu_scp_lpri0>,
299                    <&cpu_scp_lpri1>;
300
301            #address-cells = <1>;
302            #size-cells = <0>;
303
304            atomic-threshold-us = <10000>;
305
306            scmi_devpd: protocol@11 {
307                reg = <0x11>;
308                #power-domain-cells = <1>;
309            };
310
311            scmi_dvfs: protocol@13 {
312                reg = <0x13>;
313                #clock-cells = <1>;
314
315                mboxes = <&mhuB 1 0>,
316                         <&mhuB 1 1>;
317                mbox-names = "tx", "rx";
318                shmem = <&cpu_scp_hpri0>,
319                        <&cpu_scp_hpri1>;
320            };
321
322            scmi_clk: protocol@14 {
323                reg = <0x14>;
324                #clock-cells = <1>;
325            };
326
327            scmi_sensors: protocol@15 {
328                reg = <0x15>;
329                #thermal-sensor-cells = <1>;
330            };
331
332            scmi_reset: protocol@16 {
333                reg = <0x16>;
334                #reset-cells = <1>;
335            };
336
337            scmi_voltage: protocol@17 {
338                reg = <0x17>;
339                regulators {
340                    #address-cells = <1>;
341                    #size-cells = <0>;
342
343                    regulator_devX: regulator@0 {
344                        reg = <0x0>;
345                        regulator-max-microvolt = <3300000>;
346                    };
347
348                    regulator_devY: regulator@9 {
349                        reg = <0x9>;
350                        regulator-min-microvolt = <500000>;
351                        regulator-max-microvolt = <4200000>;
352                    };
353                };
354            };
355
356            scmi_powercap: protocol@18 {
357                reg = <0x18>;
358            };
359        };
360    };
361
362    soc {
363        #address-cells = <2>;
364        #size-cells = <2>;
365
366        sram@50000000 {
367            compatible = "mmio-sram";
368            reg = <0x0 0x50000000 0x0 0x10000>;
369
370            #address-cells = <1>;
371            #size-cells = <1>;
372            ranges = <0 0x0 0x50000000 0x10000>;
373
374            cpu_scp_lpri0: scp-sram-section@0 {
375                compatible = "arm,scmi-shmem";
376                reg = <0x0 0x80>;
377            };
378
379            cpu_scp_lpri1: scp-sram-section@80 {
380                compatible = "arm,scmi-shmem";
381                reg = <0x80 0x80>;
382            };
383
384            cpu_scp_hpri0: scp-sram-section@100 {
385                compatible = "arm,scmi-shmem";
386                reg = <0x100 0x80>;
387            };
388
389            cpu_scp_hpri2: scp-sram-section@180 {
390                compatible = "arm,scmi-shmem";
391                reg = <0x180 0x80>;
392            };
393        };
394    };
395
396  - |
397    firmware {
398        scmi {
399            compatible = "arm,scmi-smc";
400            shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
401            arm,smc-id = <0xc3000001>;
402
403            #address-cells = <1>;
404            #size-cells = <0>;
405
406            scmi_devpd1: protocol@11 {
407                reg = <0x11>;
408                #power-domain-cells = <1>;
409            };
410        };
411    };
412
413  - |
414    firmware {
415        scmi {
416            compatible = "linaro,scmi-optee";
417            linaro,optee-channel-id = <0>;
418
419            #address-cells = <1>;
420            #size-cells = <0>;
421
422            scmi_dvfs1: protocol@13 {
423                reg = <0x13>;
424                linaro,optee-channel-id = <1>;
425                shmem = <&cpu_optee_lpri0>;
426                #clock-cells = <1>;
427            };
428
429            scmi_clk0: protocol@14 {
430                reg = <0x14>;
431                #clock-cells = <1>;
432            };
433        };
434    };
435
436    soc {
437        #address-cells = <2>;
438        #size-cells = <2>;
439
440        sram@51000000 {
441            compatible = "mmio-sram";
442            reg = <0x0 0x51000000 0x0 0x10000>;
443
444            #address-cells = <1>;
445            #size-cells = <1>;
446            ranges = <0 0x0 0x51000000 0x10000>;
447
448            cpu_optee_lpri0: optee-sram-section@0 {
449                compatible = "arm,scmi-shmem";
450                reg = <0x0 0x80>;
451            };
452        };
453    };
454
455...
456