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