bindings/firmware/arm,scmi.yaml

   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 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 additionalProperties: false
 251
 252 $defs:
 253   protocol-node:
 254     type: object
 255     description:
 256       Each sub-node represents a protocol supported. If the platform
 257       supports a dedicated communication channel for a particular protocol,
 258       then the corresponding transport properties must be present.
 259       The virtio transport does not support a dedicated communication channel.
 260
 261     properties:
 262       reg:
 263         maxItems: 1
 264
 265       mbox-names:
 266         oneOf:
 267           - items:
 268               - const: tx
 269               - const: rx
 270             minItems: 1
 271           - items:
 272               - const: tx
 273               - const: tx_reply
 274               - const: rx
 275             minItems: 2
 276
 277       mboxes:
 278         minItems: 1
 279         maxItems: 3
 280
 281       shmem:
 282         minItems: 1
 283         maxItems: 2
 284
 285       linaro,optee-channel-id:
 286         $ref: /schemas/types.yaml#/definitions/uint32
 287         description:
 288           Channel specifier required when using OP-TEE transport and
 289           protocol has a dedicated communication channel.
 290
 291     required:
 292       - reg
 293
 294 required:
 295   - compatible
 296
 297 if:
 298   properties:
 299     compatible:
 300       contains:
 301         const: arm,scmi
 302 then:
 303   properties:
 304     interrupts: false
 305     interrupt-names: false
 306
 307   required:
 308     - mboxes
 309     - shmem
 310
 311 else:
 312   if:
 313     properties:
 314       compatible:
 315         contains:
 316           enum:
 317             - arm,scmi-smc
 318             - arm,scmi-smc-param
 319             - qcom,scmi-smc
 320   then:
 321     required:
 322       - arm,smc-id
 323       - shmem
 324
 325   else:
 326     if:
 327       properties:
 328         compatible:
 329           contains:
 330             const: linaro,scmi-optee
 331     then:
 332       required:
 333         - linaro,optee-channel-id
 334
 335 examples:
 336   - |
 337     firmware {
 338         scmi {
 339             compatible = "arm,scmi";
 340             mboxes = <&mhuB 0 0>,
 341                      <&mhuB 0 1>;
 342             mbox-names = "tx", "rx";
 343             shmem = <&cpu_scp_lpri0>,
 344                     <&cpu_scp_lpri1>;
 345
 346             #address-cells = <1>;
 347             #size-cells = <0>;
 348
 349             atomic-threshold-us = <10000>;
 350
 351             scmi_devpd: protocol@11 {
 352                 reg = <0x11>;
 353                 #power-domain-cells = <1>;
 354             };
 355
 356             scmi_dvfs: protocol@13 {
 357                 reg = <0x13>;
 358                 #clock-cells = <1>;
 359
 360                 mboxes = <&mhuB 1 0>,
 361                          <&mhuB 1 1>;
 362                 mbox-names = "tx", "rx";
 363                 shmem = <&cpu_scp_hpri0>,
 364                         <&cpu_scp_hpri1>;
 365             };
 366
 367             scmi_clk: protocol@14 {
 368                 reg = <0x14>;
 369                 #clock-cells = <1>;
 370             };
 371
 372             scmi_sensors: protocol@15 {
 373                 reg = <0x15>;
 374                 #thermal-sensor-cells = <1>;
 375             };
 376
 377             scmi_reset: protocol@16 {
 378                 reg = <0x16>;
 379                 #reset-cells = <1>;
 380             };
 381
 382             scmi_voltage: protocol@17 {
 383                 reg = <0x17>;
 384                 regulators {
 385                     #address-cells = <1>;
 386                     #size-cells = <0>;
 387
 388                     regulator_devX: regulator@0 {
 389                         reg = <0x0>;
 390                         regulator-max-microvolt = <3300000>;
 391                     };
 392
 393                     regulator_devY: regulator@9 {
 394                         reg = <0x9>;
 395                         regulator-min-microvolt = <500000>;
 396                         regulator-max-microvolt = <4200000>;
 397                     };
 398                 };
 399             };
 400
 401             scmi_powercap: protocol@18 {
 402                 reg = <0x18>;
 403             };
 404         };
 405     };
 406
 407     soc {
 408         #address-cells = <2>;
 409         #size-cells = <2>;
 410
 411         sram@50000000 {
 412             compatible = "mmio-sram";
 413             reg = <0x0 0x50000000 0x0 0x10000>;
 414
 415             #address-cells = <1>;
 416             #size-cells = <1>;
 417             ranges = <0 0x0 0x50000000 0x10000>;
 418
 419             cpu_scp_lpri0: scp-sram-section@0 {
 420                 compatible = "arm,scmi-shmem";
 421                 reg = <0x0 0x80>;
 422             };
 423
 424             cpu_scp_lpri1: scp-sram-section@80 {
 425                 compatible = "arm,scmi-shmem";
 426                 reg = <0x80 0x80>;
 427             };
 428
 429             cpu_scp_hpri0: scp-sram-section@100 {
 430                 compatible = "arm,scmi-shmem";
 431                 reg = <0x100 0x80>;
 432             };
 433
 434             cpu_scp_hpri2: scp-sram-section@180 {
 435                 compatible = "arm,scmi-shmem";
 436                 reg = <0x180 0x80>;
 437             };
 438         };
 439     };
 440
 441   - |
 442     firmware {
 443         scmi {
 444             compatible = "arm,scmi-smc";
 445             shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
 446             arm,smc-id = <0xc3000001>;
 447
 448             #address-cells = <1>;
 449             #size-cells = <0>;
 450
 451             scmi_devpd1: protocol@11 {
 452                 reg = <0x11>;
 453                 #power-domain-cells = <1>;
 454             };
 455         };
 456     };
 457
 458   - |
 459     firmware {
 460         scmi {
 461             compatible = "linaro,scmi-optee";
 462             linaro,optee-channel-id = <0>;
 463
 464             #address-cells = <1>;
 465             #size-cells = <0>;
 466
 467             scmi_dvfs1: protocol@13 {
 468                 reg = <0x13>;
 469                 linaro,optee-channel-id = <1>;
 470                 shmem = <&cpu_optee_lpri0>;
 471                 #clock-cells = <1>;
 472             };
 473
 474             scmi_clk0: protocol@14 {
 475                 reg = <0x14>;
 476                 #clock-cells = <1>;
 477             };
 478         };
 479     };
 480
 481     soc {
 482         #address-cells = <2>;
 483         #size-cells = <2>;
 484
 485         sram@51000000 {
 486             compatible = "mmio-sram";
 487             reg = <0x0 0x51000000 0x0 0x10000>;
 488
 489             #address-cells = <1>;
 490             #size-cells = <1>;
 491             ranges = <0 0x0 0x51000000 0x10000>;
 492
 493             cpu_optee_lpri0: optee-sram-section@0 {
 494                 compatible = "arm,scmi-shmem";
 495                 reg = <0x0 0x80>;
 496             };
 497         };
 498     };
 499
 500 ...