Documentation/devicetree/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 bindings
   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 SCMI Virtio transport.
  38                      The virtio transport only supports a single device.
  39         items:
  40           - const: arm,scmi-virtio
  41       - description: SCMI compliant firmware with OP-TEE transport
  42         items:
  43           - const: linaro,scmi-optee
  44
  45   interrupts:
  46     description:
  47       The interrupt that indicates message completion by the platform
  48       rather than by the return of the smc call. This should not be used
  49       except when the platform requires such behavior.
  50     maxItems: 1
  51
  52   interrupt-names:
  53     const: a2p
  54
  55   mbox-names:
  56     description:
  57       Specifies the mailboxes used to communicate with SCMI compliant
  58       firmware.
  59     items:
  60       - const: tx
  61       - const: rx
  62
  63   mboxes:
  64     description:
  65       List of phandle and mailbox channel specifiers. It should contain
  66       exactly one or two mailboxes, one for transmitting messages("tx")
  67       and another optional for receiving the notifications("rx") if supported.
  68     minItems: 1
  69     maxItems: 2
  70
  71   shmem:
  72     description:
  73       List of phandle pointing to the shared memory(SHM) area, for each
  74       transport channel specified.
  75     minItems: 1
  76     maxItems: 2
  77
  78   '#address-cells':
  79     const: 1
  80
  81   '#size-cells':
  82     const: 0
  83
  84   atomic-threshold-us:
  85     description:
  86       An optional time value, expressed in microseconds, representing, on this
  87       platform, the threshold above which any SCMI command, advertised to have
  88       an higher-than-threshold execution latency, should not be considered for
  89       atomic mode of operation, even if requested.
  90     default: 0
  91
  92   arm,smc-id:
  93     $ref: /schemas/types.yaml#/definitions/uint32
  94     description:
  95       SMC id required when using smc or hvc transports
  96
  97   linaro,optee-channel-id:
  98     $ref: /schemas/types.yaml#/definitions/uint32
  99     description:
 100       Channel specifier required when using OP-TEE transport.
 101
 102   protocol@11:
 103     type: object
 104     properties:
 105       reg:
 106         const: 0x11
 107
 108       '#power-domain-cells':
 109         const: 1
 110
 111     required:
 112       - '#power-domain-cells'
 113
 114   protocol@13:
 115     type: object
 116     properties:
 117       reg:
 118         const: 0x13
 119
 120       '#clock-cells':
 121         const: 1
 122
 123     required:
 124       - '#clock-cells'
 125
 126   protocol@14:
 127     type: object
 128     properties:
 129       reg:
 130         const: 0x14
 131
 132       '#clock-cells':
 133         const: 1
 134
 135     required:
 136       - '#clock-cells'
 137
 138   protocol@15:
 139     type: object
 140     properties:
 141       reg:
 142         const: 0x15
 143
 144       '#thermal-sensor-cells':
 145         const: 1
 146
 147     required:
 148       - '#thermal-sensor-cells'
 149
 150   protocol@16:
 151     type: object
 152     properties:
 153       reg:
 154         const: 0x16
 155
 156       '#reset-cells':
 157         const: 1
 158
 159     required:
 160       - '#reset-cells'
 161
 162   protocol@17:
 163     type: object
 164     properties:
 165       reg:
 166         const: 0x17
 167
 168       regulators:
 169         type: object
 170         description:
 171           The list of all regulators provided by this SCMI controller.
 172
 173         patternProperties:
 174           '^regulators@[0-9a-f]+$':
 175             type: object
 176             $ref: "../regulator/regulator.yaml#"
 177
 178             properties:
 179               reg:
 180                 maxItems: 1
 181                 description: Identifier for the voltage regulator.
 182
 183             required:
 184               - reg
 185
 186   protocol@18:
 187     type: object
 188     properties:
 189       reg:
 190         const: 0x18
 191
 192 additionalProperties: false
 193
 194 patternProperties:
 195   '^protocol@[0-9a-f]+$':
 196     type: object
 197     description:
 198       Each sub-node represents a protocol supported. If the platform
 199       supports a dedicated communication channel for a particular protocol,
 200       then the corresponding transport properties must be present.
 201       The virtio transport does not support a dedicated communication channel.
 202
 203     properties:
 204       reg:
 205         maxItems: 1
 206
 207       mbox-names:
 208         items:
 209           - const: tx
 210           - const: rx
 211
 212       mboxes:
 213         minItems: 1
 214         maxItems: 2
 215
 216       shmem:
 217         minItems: 1
 218         maxItems: 2
 219
 220       linaro,optee-channel-id:
 221         $ref: /schemas/types.yaml#/definitions/uint32
 222         description:
 223           Channel specifier required when using OP-TEE transport and
 224           protocol has a dedicated communication channel.
 225
 226     required:
 227       - reg
 228
 229 required:
 230   - compatible
 231
 232 if:
 233   properties:
 234     compatible:
 235       contains:
 236         const: arm,scmi
 237 then:
 238   properties:
 239     interrupts: false
 240     interrupt-names: false
 241
 242   required:
 243     - mboxes
 244     - shmem
 245
 246 else:
 247   if:
 248     properties:
 249       compatible:
 250         contains:
 251           const: arm,scmi-smc
 252   then:
 253     required:
 254       - arm,smc-id
 255       - shmem
 256
 257   else:
 258     if:
 259       properties:
 260         compatible:
 261           contains:
 262             const: linaro,scmi-optee
 263     then:
 264       required:
 265         - linaro,optee-channel-id
 266
 267 examples:
 268   - |
 269     firmware {
 270         scmi {
 271             compatible = "arm,scmi";
 272             mboxes = <&mhuB 0 0>,
 273                      <&mhuB 0 1>;
 274             mbox-names = "tx", "rx";
 275             shmem = <&cpu_scp_lpri0>,
 276                     <&cpu_scp_lpri1>;
 277
 278             #address-cells = <1>;
 279             #size-cells = <0>;
 280
 281             atomic-threshold-us = <10000>;
 282
 283             scmi_devpd: protocol@11 {
 284                 reg = <0x11>;
 285                 #power-domain-cells = <1>;
 286             };
 287
 288             scmi_dvfs: protocol@13 {
 289                 reg = <0x13>;
 290                 #clock-cells = <1>;
 291
 292                 mboxes = <&mhuB 1 0>,
 293                          <&mhuB 1 1>;
 294                 mbox-names = "tx", "rx";
 295                 shmem = <&cpu_scp_hpri0>,
 296                         <&cpu_scp_hpri1>;
 297             };
 298
 299             scmi_clk: protocol@14 {
 300                 reg = <0x14>;
 301                 #clock-cells = <1>;
 302             };
 303
 304             scmi_sensors: protocol@15 {
 305                 reg = <0x15>;
 306                 #thermal-sensor-cells = <1>;
 307             };
 308
 309             scmi_reset: protocol@16 {
 310                 reg = <0x16>;
 311                 #reset-cells = <1>;
 312             };
 313
 314             scmi_voltage: protocol@17 {
 315                 reg = <0x17>;
 316                 regulators {
 317                     #address-cells = <1>;
 318                     #size-cells = <0>;
 319
 320                     regulator_devX: regulator@0 {
 321                         reg = <0x0>;
 322                         regulator-max-microvolt = <3300000>;
 323                     };
 324
 325                     regulator_devY: regulator@9 {
 326                         reg = <0x9>;
 327                         regulator-min-microvolt = <500000>;
 328                         regulator-max-microvolt = <4200000>;
 329                     };
 330                 };
 331             };
 332
 333             scmi_powercap: protocol@18 {
 334                 reg = <0x18>;
 335             };
 336         };
 337     };
 338
 339     soc {
 340         #address-cells = <2>;
 341         #size-cells = <2>;
 342
 343         sram@50000000 {
 344             compatible = "mmio-sram";
 345             reg = <0x0 0x50000000 0x0 0x10000>;
 346
 347             #address-cells = <1>;
 348             #size-cells = <1>;
 349             ranges = <0 0x0 0x50000000 0x10000>;
 350
 351             cpu_scp_lpri0: scp-sram-section@0 {
 352                 compatible = "arm,scmi-shmem";
 353                 reg = <0x0 0x80>;
 354             };
 355
 356             cpu_scp_lpri1: scp-sram-section@80 {
 357                 compatible = "arm,scmi-shmem";
 358                 reg = <0x80 0x80>;
 359             };
 360
 361             cpu_scp_hpri0: scp-sram-section@100 {
 362                 compatible = "arm,scmi-shmem";
 363                 reg = <0x100 0x80>;
 364             };
 365
 366             cpu_scp_hpri2: scp-sram-section@180 {
 367                 compatible = "arm,scmi-shmem";
 368                 reg = <0x180 0x80>;
 369             };
 370         };
 371     };
 372
 373   - |
 374     firmware {
 375         scmi {
 376             compatible = "arm,scmi-smc";
 377             shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
 378             arm,smc-id = <0xc3000001>;
 379
 380             #address-cells = <1>;
 381             #size-cells = <0>;
 382
 383             scmi_devpd1: protocol@11 {
 384                 reg = <0x11>;
 385                 #power-domain-cells = <1>;
 386             };
 387         };
 388     };
 389
 390   - |
 391     firmware {
 392         scmi {
 393             compatible = "linaro,scmi-optee";
 394             linaro,optee-channel-id = <0>;
 395
 396             #address-cells = <1>;
 397             #size-cells = <0>;
 398
 399             scmi_dvfs1: protocol@13 {
 400                 reg = <0x13>;
 401                 linaro,optee-channel-id = <1>;
 402                 shmem = <&cpu_optee_lpri0>;
 403                 #clock-cells = <1>;
 404             };
 405
 406             scmi_clk0: protocol@14 {
 407                 reg = <0x14>;
 408                 #clock-cells = <1>;
 409             };
 410         };
 411     };
 412
 413     soc {
 414         #address-cells = <2>;
 415         #size-cells = <2>;
 416
 417         sram@51000000 {
 418             compatible = "mmio-sram";
 419             reg = <0x0 0x51000000 0x0 0x10000>;
 420
 421             #address-cells = <1>;
 422             #size-cells = <1>;
 423             ranges = <0 0x0 0x51000000 0x10000>;
 424
 425             cpu_optee_lpri0: optee-sram-section@0 {
 426                 compatible = "arm,scmi-shmem";
 427                 reg = <0x0 0x80>;
 428             };
 429         };
 430     };
 431
 432 ...