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
   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     maxItems: 4
  47
  48   shmem:
  49     description:
  50       List of phandle pointing to the shared memory(SHM) area between the
  51       processors using these mailboxes for IPC, one for each mailbox SHM can
  52       be any memory reserved for the purpose of this communication between the
  53       processors.
  54     minItems: 1
  55     maxItems: 4
  56
  57   power-controller:
  58     type: object
  59     description:
  60       This sub-node represents SCPI power domain controller.
  61
  62     properties:
  63       compatible:
  64         const: arm,scpi-power-domains
  65
  66       '#power-domain-cells':
  67         const: 1
  68
  69       num-domains:
  70         $ref: /schemas/types.yaml#/definitions/uint32
  71         description:
  72           Total number of power domains provided by SCPI. This is needed as
  73           the SCPI message protocol lacks a mechanism to query this
  74           information at runtime.
  75
  76     required:
  77       - compatible
  78       - '#power-domain-cells'
  79       - num-domains
  80
  81     additionalProperties: false
  82
  83   sensors:
  84     type: object
  85     description: |
  86       This sub-node represents SCPI sensors controller.
  87
  88     properties:
  89       compatible:
  90         oneOf:
  91           - const: arm,scpi-sensors
  92           - items:
  93               - enum:
  94                   - amlogic,meson-gxbb-scpi-sensors
  95               - const: arm,scpi-sensors
  96
  97       '#thermal-sensor-cells':
  98         const: 1
  99
 100     required:
 101       - compatible
 102       - '#thermal-sensor-cells'
 103
 104     additionalProperties: false
 105
 106   clocks:
 107     type: object
 108     description:
 109       This is the container node. Each sub-node represents one of the types
 110       of clock controller - indexed or full range.
 111
 112     properties:
 113       compatible:
 114         const: arm,scpi-clocks
 115
 116     patternProperties:
 117       "^clocks-[0-9a-f]+$":
 118         type: object
 119         description: |
 120           This sub-node represents one of the types of clock controller
 121           - indexed or full range.
 122
 123           "arm,scpi-dvfs-clocks" - all the clocks that are variable and index
 124           based. These clocks don't provide an entire range of values between
 125           the limits but only discrete points within the range. The firmware
 126           provides the mapping for each such operating frequency and the index
 127           associated with it. The firmware also manages the voltage scaling
 128           appropriately with the clock scaling.
 129
 130           "arm,scpi-variable-clocks" - all the clocks that are variable and
 131           provide full range within the specified range. The firmware provides
 132           the range of values within a specified range.
 133
 134         properties:
 135           compatible:
 136             enum:
 137               - arm,scpi-dvfs-clocks
 138               - arm,scpi-variable-clocks
 139
 140           '#clock-cells':
 141             const: 1
 142
 143           clock-output-names: true
 144
 145           clock-indices:
 146             $ref: /schemas/types.yaml#/definitions/uint32-array
 147             description:
 148               The identifying number for the clocks(i.e.clock_id) in the node.
 149               It can be non linear and hence provide the mapping of identifiers
 150               into the clock-output-names array.
 151
 152         required:
 153           - compatible
 154           - '#clock-cells'
 155           - clock-output-names
 156           - clock-indices
 157
 158         additionalProperties: false
 159
 160     required:
 161       - compatible
 162
 163     additionalProperties: false
 164
 165 additionalProperties: false
 166
 167 required:
 168   - compatible
 169   - mboxes
 170   - shmem
 171
 172 examples:
 173   - |
 174     firmware {
 175         scpi {
 176             compatible = "arm,scpi";
 177             mboxes = <&mhuA 1>;
 178             shmem = <&cpu_scp_hpri>; /* HP-NonSecure */
 179
 180             scpi_devpd: power-controller {
 181                 compatible = "arm,scpi-power-domains";
 182                 num-domains = <2>;
 183                 #power-domain-cells = <1>;
 184             };
 185
 186             clocks {
 187                 compatible = "arm,scpi-clocks";
 188
 189                 scpi_dvfs: clocks-0 {
 190                     compatible = "arm,scpi-dvfs-clocks";
 191                     #clock-cells = <1>;
 192                     clock-indices = <0>, <1>, <2>;
 193                     clock-output-names = "atlclk", "aplclk","gpuclk";
 194                 };
 195
 196                 scpi_clk: clocks-1 {
 197                     compatible = "arm,scpi-variable-clocks";
 198                     #clock-cells = <1>;
 199                     clock-indices = <3>, <4>;
 200                     clock-output-names = "pxlclk0", "pxlclk1";
 201                 };
 202             };
 203
 204             scpi_sensors: sensors {
 205                 compatible = "arm,scpi-sensors";
 206                 #thermal-sensor-cells = <1>;
 207             };
 208
 209         };
 210     };
 211
 212     soc {
 213         #address-cells = <2>;
 214         #size-cells = <2>;
 215
 216         sram@50000000 {
 217             compatible = "mmio-sram";
 218             reg = <0x0 0x50000000 0x0 0x10000>;
 219
 220             #address-cells = <1>;
 221             #size-cells = <1>;
 222             ranges = <0 0x0 0x50000000 0x10000>;
 223
 224             cpu_scp_lpri: scp-sram-section@0 {
 225                 compatible = "arm,scp-shmem";
 226                 reg = <0x0 0x200>;
 227             };
 228
 229             cpu_scp_hpri: scp-sram-section@200 {
 230                 compatible = "arm,scp-shmem";
 231                 reg = <0x200 0x200>;
 232             };
 233         };
 234     };
 235
 236   - |
 237     firmware {
 238         scpi {
 239             compatible = "amlogic,meson-gxbb-scpi", "arm,scpi-pre-1.0";
 240             mboxes = <&mailbox 1>, <&mailbox 2>;
 241             shmem = <&cpu_scp_lpri>, <&cpu_scp_hpri>;
 242
 243             scpi_sensors1: sensors {
 244                 compatible = "amlogic,meson-gxbb-scpi-sensors", "arm,scpi-sensors";
 245                 #thermal-sensor-cells = <1>;
 246             };
 247         };
 248     };
 249 ...