Documentation/devicetree/bindings/firmware/arm,scpi.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,scpi.yaml#
   6 $schema: http://devicetree.org/meta-schemas/core.yaml#
   7
   8 title: System Control and Power Interface (SCPI) Message Protocol bindings
   9
  10 maintainers:
  11   - Sudeep Holla <sudeep.holla@arm.com>
  12
  13 description: |
  14   Firmware implementing the SCPI described in ARM document number ARM DUI
  15   0922B ("ARM Compute Subsystem SCP: Message Interface Protocols")[0] can be
  16   used by Linux to initiate various system control and power operations.
  17
  18   This binding is intended to define the interface the firmware implementing
  19   the SCPI provide for OSPM in the device tree.
  20
  21   [0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html
  22
  23 properties:
  24   $nodename:
  25     const: scpi
  26
  27   compatible:
  28     description:
  29       SCPI compliant firmware complying to SCPI v1.0 and above OR
  30       SCPI compliant firmware complying to all unversioned releases
  31       prior to SCPI v1.0
  32     oneOf:
  33       - const: arm,scpi               # SCPI v1.0 and above
  34       - const: arm,scpi-pre-1.0       # Unversioned SCPI before v1.0
  35       - items:
  36           - enum:
  37               - amlogic,meson-gxbb-scpi
  38           - const: arm,scpi-pre-1.0
  39
  40   mboxes:
  41     description:
  42       List of phandle and mailbox channel specifiers. All the channels reserved
  43       by remote SCP firmware for use by SCPI message protocol should be
  44       specified in any order.
  45     minItems: 1
  46
  47   shmem:
  48     description:
  49       List of phandle pointing to the shared memory(SHM) area between the
  50       processors using these mailboxes for IPC, one for each mailbox SHM can
  51       be any memory reserved for the purpose of this communication between the
  52       processors.
  53     minItems: 1
  54
  55   power-controller:
  56     type: object
  57     description:
  58       This sub-node represents SCPI power domain controller.
  59
  60     properties:
  61       compatible:
  62         const: arm,scpi-power-domains
  63
  64       '#power-domain-cells':
  65         const: 1
  66
  67       num-domains:
  68         $ref: /schemas/types.yaml#/definitions/uint32
  69         description:
  70           Total number of power domains provided by SCPI. This is needed as
  71           the SCPI message protocol lacks a mechanism to query this
  72           information at runtime.
  73
  74     required:
  75       - compatible
  76       - '#power-domain-cells'
  77       - num-domains
  78
  79     additionalProperties: false
  80
  81   sensors:
  82     type: object
  83     description: |
  84       This sub-node represents SCPI sensors controller.
  85
  86     properties:
  87       compatible:
  88         oneOf:
  89           - const: arm,scpi-sensors
  90           - items:
  91               - enum:
  92                   - amlogic,meson-gxbb-scpi-sensors
  93               - const: arm,scpi-sensors
  94
  95       '#thermal-sensor-cells':
  96         const: 1
  97
  98     required:
  99       - compatible
 100       - '#thermal-sensor-cells'
 101
 102     additionalProperties: false
 103
 104   clocks:
 105     type: object
 106     description:
 107       This is the container node. Each sub-node represents one of the types
 108       of clock controller - indexed or full range.
 109
 110     properties:
 111       compatible:
 112         const: arm,scpi-clocks
 113
 114     patternProperties:
 115       "^clocks-[0-9a-f]+$":
 116         type: object
 117         description: |
 118           This sub-node represents one of the types of clock controller
 119           - indexed or full range.
 120
 121           "arm,scpi-dvfs-clocks" - all the clocks that are variable and index
 122           based. These clocks don't provide an entire range of values between
 123           the limits but only discrete points within the range. The firmware
 124           provides the mapping for each such operating frequency and the index
 125           associated with it. The firmware also manages the voltage scaling
 126           appropriately with the clock scaling.
 127
 128           "arm,scpi-variable-clocks" - all the clocks that are variable and
 129           provide full range within the specified range. The firmware provides
 130           the range of values within a specified range.
 131
 132         properties:
 133           compatible:
 134             enum:
 135               - arm,scpi-dvfs-clocks
 136               - arm,scpi-variable-clocks
 137
 138           '#clock-cells':
 139             const: 1
 140
 141           clock-output-names: true
 142
 143           clock-indices:
 144             $ref: /schemas/types.yaml#/definitions/uint32-array
 145             description:
 146               The identifying number for the clocks(i.e.clock_id) in the node.
 147               It can be non linear and hence provide the mapping of identifiers
 148               into the clock-output-names array.
 149
 150         required:
 151           - compatible
 152           - '#clock-cells'
 153           - clock-output-names
 154           - clock-indices
 155
 156         additionalProperties: false
 157
 158     required:
 159       - compatible
 160
 161     additionalProperties: false
 162
 163 additionalProperties: false
 164
 165 required:
 166   - compatible
 167   - mboxes
 168   - shmem
 169
 170 examples:
 171   - |
 172     firmware {
 173         scpi {
 174             compatible = "arm,scpi";
 175             mboxes = <&mhuA 1>;
 176             shmem = <&cpu_scp_hpri>; /* HP-NonSecure */
 177
 178             scpi_devpd: power-controller {
 179                 compatible = "arm,scpi-power-domains";
 180                 num-domains = <2>;
 181                 #power-domain-cells = <1>;
 182             };
 183
 184             clocks {
 185                 compatible = "arm,scpi-clocks";
 186
 187                 scpi_dvfs: clocks-0 {
 188                     compatible = "arm,scpi-dvfs-clocks";
 189                     #clock-cells = <1>;
 190                     clock-indices = <0>, <1>, <2>;
 191                     clock-output-names = "atlclk", "aplclk","gpuclk";
 192                 };
 193
 194                 scpi_clk: clocks-1 {
 195                     compatible = "arm,scpi-variable-clocks";
 196                     #clock-cells = <1>;
 197                     clock-indices = <3>, <4>;
 198                     clock-output-names = "pxlclk0", "pxlclk1";
 199                 };
 200             };
 201
 202             scpi_sensors: sensors {
 203                 compatible = "arm,scpi-sensors";
 204                 #thermal-sensor-cells = <1>;
 205             };
 206
 207         };
 208     };
 209
 210     soc {
 211         #address-cells = <2>;
 212         #size-cells = <2>;
 213
 214         sram@50000000 {
 215             compatible = "mmio-sram";
 216             reg = <0x0 0x50000000 0x0 0x10000>;
 217
 218             #address-cells = <1>;
 219             #size-cells = <1>;
 220             ranges = <0 0x0 0x50000000 0x10000>;
 221
 222             cpu_scp_lpri: scp-sram-section@0 {
 223                 compatible = "arm,scp-shmem";
 224                 reg = <0x0 0x200>;
 225             };
 226
 227             cpu_scp_hpri: scp-sram-section@200 {
 228                 compatible = "arm,scp-shmem";
 229                 reg = <0x200 0x200>;
 230             };
 231         };
 232     };
 233
 234   - |
 235     firmware {
 236         scpi {
 237             compatible = "amlogic,meson-gxbb-scpi", "arm,scpi-pre-1.0";
 238             mboxes = <&mailbox 1 &mailbox 2>;
 239             shmem = <&cpu_scp_lpri &cpu_scp_hpri>;
 240
 241             scpi_sensors1: sensors {
 242                 compatible = "amlogic,meson-gxbb-scpi-sensors", "arm,scpi-sensors";
 243                 #thermal-sensor-cells = <1>;
 244             };
 245         };
 246     };
 247 ...