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