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