xref: /linux/Documentation/devicetree/bindings/firmware/arm,scmi.yaml (revision 53597deca0e38c30e6cd4ba2114fa42d2bcd85bb) 
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    pattern: '^scmi(-[0-9]+)?$'
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  arm,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,max-msg-size:
135    $ref: /schemas/types.yaml#/definitions/uint32
136    description:
137      An optional value, expressed in bytes, representing the maximum size
138      allowed for the payload of messages transmitted on this transport.
139
140  arm,max-msg:
141    $ref: /schemas/types.yaml#/definitions/uint32
142    description:
143      An optional value representing the maximum number of concurrent in-flight
144      messages allowed by this transport; this number represents the maximum
145      number of concurrently outstanding messages that the server can handle on
146      this platform. If set, the value should be non-zero.
147    minimum: 1
148
149  arm,no-completion-irq:
150    type: boolean
151    description:
152      This optional property is intended for hardware that does not generate
153      completion interrupts and can be used to unconditionally enable forced
154      polling mode of operation.
155
156  arm,smc-id:
157    $ref: /schemas/types.yaml#/definitions/uint32
158    description:
159      SMC id required when using smc or hvc transports
160
161  linaro,optee-channel-id:
162    $ref: /schemas/types.yaml#/definitions/uint32
163    description:
164      Channel specifier required when using OP-TEE transport.
165
166  protocol@11:
167    $ref: '#/$defs/protocol-node'
168    unevaluatedProperties: false
169
170    properties:
171      reg:
172        const: 0x11
173
174      '#power-domain-cells':
175        const: 1
176
177    required:
178      - '#power-domain-cells'
179
180  protocol@12:
181    $ref: '#/$defs/protocol-node'
182    unevaluatedProperties: false
183
184    properties:
185      reg:
186        const: 0x12
187
188  protocol@13:
189    $ref: '#/$defs/protocol-node'
190    unevaluatedProperties: false
191
192    properties:
193      reg:
194        const: 0x13
195
196      '#clock-cells':
197        const: 1
198
199      '#power-domain-cells':
200        const: 1
201
202    oneOf:
203      - required:
204          - '#clock-cells'
205
206      - required:
207          - '#power-domain-cells'
208
209  protocol@14:
210    $ref: '#/$defs/protocol-node'
211    unevaluatedProperties: false
212
213    properties:
214      reg:
215        const: 0x14
216
217      '#clock-cells':
218        const: 1
219
220    required:
221      - '#clock-cells'
222
223  protocol@15:
224    $ref: '#/$defs/protocol-node'
225    unevaluatedProperties: false
226
227    properties:
228      reg:
229        const: 0x15
230
231      '#thermal-sensor-cells':
232        const: 1
233
234    required:
235      - '#thermal-sensor-cells'
236
237  protocol@16:
238    $ref: '#/$defs/protocol-node'
239    unevaluatedProperties: false
240
241    properties:
242      reg:
243        const: 0x16
244
245      '#reset-cells':
246        const: 1
247
248    required:
249      - '#reset-cells'
250
251  protocol@17:
252    $ref: '#/$defs/protocol-node'
253    unevaluatedProperties: false
254
255    properties:
256      reg:
257        const: 0x17
258
259      regulators:
260        type: object
261        additionalProperties: false
262        description:
263          The list of all regulators provided by this SCMI controller.
264
265        properties:
266          '#address-cells':
267            const: 1
268
269          '#size-cells':
270            const: 0
271
272        patternProperties:
273          '^regulator@[0-9a-f]+$':
274            type: object
275            $ref: /schemas/regulator/regulator.yaml#
276            unevaluatedProperties: false
277
278            properties:
279              reg:
280                maxItems: 1
281                description: Identifier for the voltage regulator.
282
283            required:
284              - reg
285
286  protocol@18:
287    $ref: '#/$defs/protocol-node'
288    unevaluatedProperties: false
289
290    properties:
291      reg:
292        const: 0x18
293
294  protocol@19:
295    type: object
296    allOf:
297      - $ref: '#/$defs/protocol-node'
298      - anyOf:
299          - $ref: /schemas/pinctrl/pinctrl.yaml
300          - $ref: /schemas/firmware/nxp,imx95-scmi-pinctrl.yaml
301
302    unevaluatedProperties: false
303
304    properties:
305      reg:
306        const: 0x19
307
308    patternProperties:
309      '-pins$':
310        type: object
311        allOf:
312          - $ref: /schemas/pinctrl/pincfg-node.yaml#
313          - $ref: /schemas/pinctrl/pinmux-node.yaml#
314        unevaluatedProperties: false
315
316        description:
317          A pin multiplexing sub-node describes how to configure a
318          set of pins in some desired function.
319          A single sub-node may define several pin configurations.
320          This sub-node is using the default pinctrl bindings to configure
321          pin multiplexing and using SCMI protocol to apply a specified
322          configuration.
323
324    required:
325      - reg
326
327unevaluatedProperties: false
328
329$defs:
330  protocol-node:
331    type: object
332    description:
333      Each sub-node represents a protocol supported. If the platform
334      supports a dedicated communication channel for a particular protocol,
335      then the corresponding transport properties must be present.
336      The virtio transport does not support a dedicated communication channel.
337
338    properties:
339      reg:
340        maxItems: 1
341
342      mbox-names:
343        oneOf:
344          - items:
345              - const: tx
346              - const: rx
347            minItems: 1
348          - items:
349              - const: tx
350              - const: tx_reply
351              - const: rx
352            minItems: 2
353
354      mboxes:
355        minItems: 1
356        maxItems: 3
357
358      shmem:
359        minItems: 1
360        maxItems: 2
361
362      linaro,optee-channel-id:
363        $ref: /schemas/types.yaml#/definitions/uint32
364        description:
365          Channel specifier required when using OP-TEE transport and
366          protocol has a dedicated communication channel.
367
368    required:
369      - reg
370
371required:
372  - compatible
373
374if:
375  properties:
376    compatible:
377      contains:
378        const: arm,scmi
379then:
380  properties:
381    interrupts: false
382    interrupt-names: false
383
384  required:
385    - mboxes
386    - shmem
387
388else:
389  properties:
390    arm,no-completion-irq: false
391
392  if:
393    properties:
394      compatible:
395        contains:
396          enum:
397            - arm,scmi-smc
398            - arm,scmi-smc-param
399            - qcom,scmi-smc
400  then:
401    required:
402      - arm,smc-id
403      - shmem
404
405  else:
406    if:
407      properties:
408        compatible:
409          contains:
410            const: linaro,scmi-optee
411    then:
412      required:
413        - linaro,optee-channel-id
414
415examples:
416  - |
417    firmware {
418        scmi {
419            compatible = "arm,scmi";
420            mboxes = <&mhuB 0 0>,
421                     <&mhuB 0 1>;
422            mbox-names = "tx", "rx";
423            shmem = <&cpu_scp_lpri0>,
424                    <&cpu_scp_lpri1>;
425
426            #address-cells = <1>;
427            #size-cells = <0>;
428
429            atomic-threshold-us = <10000>;
430
431            scmi_devpd: protocol@11 {
432                reg = <0x11>;
433                #power-domain-cells = <1>;
434            };
435
436            scmi_dvfs: protocol@13 {
437                reg = <0x13>;
438                #power-domain-cells = <1>;
439
440                mboxes = <&mhuB 1 0>,
441                         <&mhuB 1 1>;
442                mbox-names = "tx", "rx";
443                shmem = <&cpu_scp_hpri0>,
444                        <&cpu_scp_hpri1>;
445            };
446
447            scmi_clk: protocol@14 {
448                reg = <0x14>;
449                #clock-cells = <1>;
450            };
451
452            scmi_sensors: protocol@15 {
453                reg = <0x15>;
454                #thermal-sensor-cells = <1>;
455            };
456
457            scmi_reset: protocol@16 {
458                reg = <0x16>;
459                #reset-cells = <1>;
460            };
461
462            scmi_voltage: protocol@17 {
463                reg = <0x17>;
464                regulators {
465                    #address-cells = <1>;
466                    #size-cells = <0>;
467
468                    regulator_devX: regulator@0 {
469                        reg = <0x0>;
470                        regulator-max-microvolt = <3300000>;
471                    };
472
473                    regulator_devY: regulator@9 {
474                        reg = <0x9>;
475                        regulator-min-microvolt = <500000>;
476                        regulator-max-microvolt = <4200000>;
477                    };
478                };
479            };
480
481            scmi_powercap: protocol@18 {
482                reg = <0x18>;
483            };
484
485            scmi_pinctrl: protocol@19 {
486                reg = <0x19>;
487
488                i2c2-pins {
489                    groups = "g_i2c2_a", "g_i2c2_b";
490                    function = "f_i2c2";
491                };
492
493                mdio-pins {
494                    groups = "g_avb_mdio";
495                    drive-strength = <24>;
496                };
497
498                keys_pins: keys-pins {
499                    pins = "gpio_5_17", "gpio_5_20", "gpio_5_22", "gpio_2_1";
500                    bias-pull-up;
501                };
502            };
503        };
504    };
505
506    soc {
507        #address-cells = <2>;
508        #size-cells = <2>;
509
510        sram@50000000 {
511            compatible = "mmio-sram";
512            reg = <0x0 0x50000000 0x0 0x10000>;
513
514            #address-cells = <1>;
515            #size-cells = <1>;
516            ranges = <0 0x0 0x50000000 0x10000>;
517
518            cpu_scp_lpri0: scp-sram-section@0 {
519                compatible = "arm,scmi-shmem";
520                reg = <0x0 0x80>;
521            };
522
523            cpu_scp_lpri1: scp-sram-section@80 {
524                compatible = "arm,scmi-shmem";
525                reg = <0x80 0x80>;
526            };
527
528            cpu_scp_hpri0: scp-sram-section@100 {
529                compatible = "arm,scmi-shmem";
530                reg = <0x100 0x80>;
531            };
532
533            cpu_scp_hpri2: scp-sram-section@180 {
534                compatible = "arm,scmi-shmem";
535                reg = <0x180 0x80>;
536            };
537        };
538    };
539
540  - |
541    firmware {
542        scmi {
543            compatible = "arm,scmi-smc";
544            shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
545            arm,smc-id = <0xc3000001>;
546
547            #address-cells = <1>;
548            #size-cells = <0>;
549
550            scmi_devpd1: protocol@11 {
551                reg = <0x11>;
552                #power-domain-cells = <1>;
553            };
554        };
555    };
556
557  - |
558    firmware {
559        scmi {
560            compatible = "linaro,scmi-optee";
561            linaro,optee-channel-id = <0>;
562
563            #address-cells = <1>;
564            #size-cells = <0>;
565
566            scmi_dvfs1: protocol@13 {
567                reg = <0x13>;
568                linaro,optee-channel-id = <1>;
569                shmem = <&cpu_optee_lpri0>;
570                #power-domain-cells = <1>;
571            };
572
573            scmi_clk0: protocol@14 {
574                reg = <0x14>;
575                #clock-cells = <1>;
576            };
577        };
578    };
579
580    soc {
581        #address-cells = <2>;
582        #size-cells = <2>;
583
584        sram@51000000 {
585            compatible = "mmio-sram";
586            reg = <0x0 0x51000000 0x0 0x10000>;
587
588            #address-cells = <1>;
589            #size-cells = <1>;
590            ranges = <0 0x0 0x51000000 0x10000>;
591
592            cpu_optee_lpri0: optee-sram-section@0 {
593                compatible = "arm,scmi-shmem";
594                reg = <0x0 0x80>;
595            };
596        };
597    };
598
599...
600