xref: /linux/Documentation/devicetree/bindings/firmware/arm,scmi.yaml (revision 7482c19173b7eb044d476b3444d7ee55bc669d03) 
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    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
186  protocol@18:
187    type: object
188    properties:
189      reg:
190        const: 0x18
191
192additionalProperties: false
193
194patternProperties:
195  '^protocol@[0-9a-f]+$':
196    type: object
197    description:
198      Each sub-node represents a protocol supported. If the platform
199      supports a dedicated communication channel for a particular protocol,
200      then the corresponding transport properties must be present.
201      The virtio transport does not support a dedicated communication channel.
202
203    properties:
204      reg:
205        maxItems: 1
206
207      mbox-names:
208        items:
209          - const: tx
210          - const: rx
211
212      mboxes:
213        minItems: 1
214        maxItems: 2
215
216      shmem:
217        minItems: 1
218        maxItems: 2
219
220      linaro,optee-channel-id:
221        $ref: /schemas/types.yaml#/definitions/uint32
222        description:
223          Channel specifier required when using OP-TEE transport and
224          protocol has a dedicated communication channel.
225
226    required:
227      - reg
228
229required:
230  - compatible
231
232if:
233  properties:
234    compatible:
235      contains:
236        const: arm,scmi
237then:
238  properties:
239    interrupts: false
240    interrupt-names: false
241
242  required:
243    - mboxes
244    - shmem
245
246else:
247  if:
248    properties:
249      compatible:
250        contains:
251          const: arm,scmi-smc
252  then:
253    required:
254      - arm,smc-id
255      - shmem
256
257  else:
258    if:
259      properties:
260        compatible:
261          contains:
262            const: linaro,scmi-optee
263    then:
264      required:
265        - linaro,optee-channel-id
266
267examples:
268  - |
269    firmware {
270        scmi {
271            compatible = "arm,scmi";
272            mboxes = <&mhuB 0 0>,
273                     <&mhuB 0 1>;
274            mbox-names = "tx", "rx";
275            shmem = <&cpu_scp_lpri0>,
276                    <&cpu_scp_lpri1>;
277
278            #address-cells = <1>;
279            #size-cells = <0>;
280
281            atomic-threshold-us = <10000>;
282
283            scmi_devpd: protocol@11 {
284                reg = <0x11>;
285                #power-domain-cells = <1>;
286            };
287
288            scmi_dvfs: protocol@13 {
289                reg = <0x13>;
290                #clock-cells = <1>;
291
292                mboxes = <&mhuB 1 0>,
293                         <&mhuB 1 1>;
294                mbox-names = "tx", "rx";
295                shmem = <&cpu_scp_hpri0>,
296                        <&cpu_scp_hpri1>;
297            };
298
299            scmi_clk: protocol@14 {
300                reg = <0x14>;
301                #clock-cells = <1>;
302            };
303
304            scmi_sensors: protocol@15 {
305                reg = <0x15>;
306                #thermal-sensor-cells = <1>;
307            };
308
309            scmi_reset: protocol@16 {
310                reg = <0x16>;
311                #reset-cells = <1>;
312            };
313
314            scmi_voltage: protocol@17 {
315                reg = <0x17>;
316                regulators {
317                    #address-cells = <1>;
318                    #size-cells = <0>;
319
320                    regulator_devX: regulator@0 {
321                        reg = <0x0>;
322                        regulator-max-microvolt = <3300000>;
323                    };
324
325                    regulator_devY: regulator@9 {
326                        reg = <0x9>;
327                        regulator-min-microvolt = <500000>;
328                        regulator-max-microvolt = <4200000>;
329                    };
330                };
331            };
332
333            scmi_powercap: protocol@18 {
334                reg = <0x18>;
335            };
336        };
337    };
338
339    soc {
340        #address-cells = <2>;
341        #size-cells = <2>;
342
343        sram@50000000 {
344            compatible = "mmio-sram";
345            reg = <0x0 0x50000000 0x0 0x10000>;
346
347            #address-cells = <1>;
348            #size-cells = <1>;
349            ranges = <0 0x0 0x50000000 0x10000>;
350
351            cpu_scp_lpri0: scp-sram-section@0 {
352                compatible = "arm,scmi-shmem";
353                reg = <0x0 0x80>;
354            };
355
356            cpu_scp_lpri1: scp-sram-section@80 {
357                compatible = "arm,scmi-shmem";
358                reg = <0x80 0x80>;
359            };
360
361            cpu_scp_hpri0: scp-sram-section@100 {
362                compatible = "arm,scmi-shmem";
363                reg = <0x100 0x80>;
364            };
365
366            cpu_scp_hpri2: scp-sram-section@180 {
367                compatible = "arm,scmi-shmem";
368                reg = <0x180 0x80>;
369            };
370        };
371    };
372
373  - |
374    firmware {
375        scmi {
376            compatible = "arm,scmi-smc";
377            shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
378            arm,smc-id = <0xc3000001>;
379
380            #address-cells = <1>;
381            #size-cells = <0>;
382
383            scmi_devpd1: protocol@11 {
384                reg = <0x11>;
385                #power-domain-cells = <1>;
386            };
387        };
388    };
389
390  - |
391    firmware {
392        scmi {
393            compatible = "linaro,scmi-optee";
394            linaro,optee-channel-id = <0>;
395
396            #address-cells = <1>;
397            #size-cells = <0>;
398
399            scmi_dvfs1: protocol@13 {
400                reg = <0x13>;
401                linaro,optee-channel-id = <1>;
402                shmem = <&cpu_optee_lpri0>;
403                #clock-cells = <1>;
404            };
405
406            scmi_clk0: protocol@14 {
407                reg = <0x14>;
408                #clock-cells = <1>;
409            };
410        };
411    };
412
413    soc {
414        #address-cells = <2>;
415        #size-cells = <2>;
416
417        sram@51000000 {
418            compatible = "mmio-sram";
419            reg = <0x0 0x51000000 0x0 0x10000>;
420
421            #address-cells = <1>;
422            #size-cells = <1>;
423            ranges = <0 0x0 0x51000000 0x10000>;
424
425            cpu_optee_lpri0: optee-sram-section@0 {
426                compatible = "arm,scmi-shmem";
427                reg = <0x0 0x80>;
428            };
429        };
430    };
431
432...
433