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