xref: /freebsd/sys/contrib/device-tree/Bindings/firmware/arm,scpi.yaml (revision 7fdf597e96a02165cfe22ff357b857d5fa15ed8a) 
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
8title: System Control and Power Interface (SCPI) Message Protocol
9
10maintainers:
11  - Sudeep Holla <sudeep.holla@arm.com>
12
13description: |
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
23properties:
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
165additionalProperties: false
166
167required:
168  - compatible
169  - mboxes
170  - shmem
171
172examples:
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...
250