1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/opp/opp-v2-base.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Generic OPP (Operating Performance Points) Common Binding
8
9maintainers:
10  - Viresh Kumar <viresh.kumar@linaro.org>
11
12description: |
13  Devices work at voltage-current-frequency combinations and some implementations
14  have the liberty of choosing these. These combinations are called Operating
15  Performance Points aka OPPs. This document defines bindings for these OPPs
16  applicable across wide range of devices. For illustration purpose, this document
17  uses CPU as a device.
18
19  This describes the OPPs belonging to a device.
20
21select: false
22
23properties:
24  $nodename:
25    pattern: '^opp-table(-[a-z0-9]+)?$'
26
27  opp-shared:
28    description:
29      Indicates that device nodes using this OPP Table Node's phandle switch
30      their DVFS state together, i.e. they share clock/voltage/current lines.
31      Missing property means devices have independent clock/voltage/current
32      lines, but they share OPP tables.
33    type: boolean
34
35patternProperties:
36  '^opp(-?[0-9]+)*$':
37    type: object
38    description:
39      One or more OPP nodes describing voltage-current-frequency combinations.
40      Their name isn't significant but their phandle can be used to reference an
41      OPP. These are mandatory except for the case where the OPP table is
42      present only to indicate dependency between devices using the opp-shared
43      property.
44
45    properties:
46      opp-hz:
47        description:
48          Frequency in Hz, expressed as a 64-bit big-endian integer. This is a
49          required property for all device nodes, unless another "required"
50          property to uniquely identify the OPP nodes exists. Devices like power
51          domains must have another (implementation dependent) property.
52
53      opp-microvolt:
54        description: |
55          Voltage for the OPP
56
57          A single regulator's voltage is specified with an array of size one or three.
58          Single entry is for target voltage and three entries are for <target min max>
59          voltages.
60
61          Entries for multiple regulators shall be provided in the same field separated
62          by angular brackets <>. The OPP binding doesn't provide any provisions to
63          relate the values to their power supplies or the order in which the supplies
64          need to be configured and that is left for the implementation specific
65          binding.
66
67          Entries for all regulators shall be of the same size, i.e. either all use a
68          single value or triplets.
69        minItems: 1
70        maxItems: 8   # Should be enough regulators
71        items:
72          minItems: 1
73          maxItems: 3
74
75      opp-microamp:
76        description: |
77          The maximum current drawn by the device in microamperes considering
78          system specific parameters (such as transients, process, aging,
79          maximum operating temperature range etc.) as necessary. This may be
80          used to set the most efficient regulator operating mode.
81
82          Should only be set if opp-microvolt or opp-microvolt-<name> is set for
83          the OPP.
84
85          Entries for multiple regulators shall be provided in the same field
86          separated by angular brackets <>. If current values aren't required
87          for a regulator, then it shall be filled with 0. If current values
88          aren't required for any of the regulators, then this field is not
89          required. The OPP binding doesn't provide any provisions to relate the
90          values to their power supplies or the order in which the supplies need
91          to be configured and that is left for the implementation specific
92          binding.
93        minItems: 1
94        maxItems: 8   # Should be enough regulators
95
96      opp-microwatt:
97        description: |
98          The power for the OPP in micro-Watts.
99
100          Entries for multiple regulators shall be provided in the same field
101          separated by angular brackets <>. If current values aren't required
102          for a regulator, then it shall be filled with 0. If power values
103          aren't required for any of the regulators, then this field is not
104          required. The OPP binding doesn't provide any provisions to relate the
105          values to their power supplies or the order in which the supplies need
106          to be configured and that is left for the implementation specific
107          binding.
108        minItems: 1
109        maxItems: 8   # Should be enough regulators
110
111      opp-level:
112        description:
113          A value representing the performance level of the device.
114        $ref: /schemas/types.yaml#/definitions/uint32
115
116      opp-peak-kBps:
117        description:
118          Peak bandwidth in kilobytes per second, expressed as an array of
119          32-bit big-endian integers. Each element of the array represents the
120          peak bandwidth value of each interconnect path. The number of elements
121          should match the number of interconnect paths.
122        minItems: 1
123        maxItems: 32  # Should be enough
124
125      opp-avg-kBps:
126        description:
127          Average bandwidth in kilobytes per second, expressed as an array
128          of 32-bit big-endian integers. Each element of the array represents the
129          average bandwidth value of each interconnect path. The number of elements
130          should match the number of interconnect paths. This property is only
131          meaningful in OPP tables where opp-peak-kBps is present.
132        minItems: 1
133        maxItems: 32  # Should be enough
134
135      clock-latency-ns:
136        description:
137          Specifies the maximum possible transition latency (in nanoseconds) for
138          switching to this OPP from any other OPP.
139
140      turbo-mode:
141        description:
142          Marks the OPP to be used only for turbo modes. Turbo mode is available
143          on some platforms, where the device can run over its operating
144          frequency for a short duration of time limited by the device's power,
145          current and thermal limits.
146        type: boolean
147
148      opp-suspend:
149        description:
150          Marks the OPP to be used during device suspend. If multiple OPPs in
151          the table have this, the OPP with highest opp-hz will be used.
152        type: boolean
153
154      opp-supported-hw:
155        description: |
156          This property allows a platform to enable only a subset of the OPPs
157          from the larger set present in the OPP table, based on the current
158          version of the hardware (already known to the operating system).
159
160          Each block present in the array of blocks in this property, represents
161          a sub-group of hardware versions supported by the OPP. i.e. <sub-group
162          A>, <sub-group B>, etc. The OPP will be enabled if _any_ of these
163          sub-groups match the hardware's version.
164
165          Each sub-group is a platform defined array representing the hierarchy
166          of hardware versions supported by the platform. For a platform with
167          three hierarchical levels of version (X.Y.Z), this field shall look
168          like
169
170          opp-supported-hw = <X1 Y1 Z1>, <X2 Y2 Z2>, <X3 Y3 Z3>.
171
172          Each level (eg. X1) in version hierarchy is represented by a 32 bit
173          value, one bit per version and so there can be maximum 32 versions per
174          level. Logical AND (&) operation is performed for each level with the
175          hardware's level version and a non-zero output for _all_ the levels in
176          a sub-group means the OPP is supported by hardware. A value of
177          0xFFFFFFFF for each level in the sub-group will enable the OPP for all
178          versions for the hardware.
179        $ref: /schemas/types.yaml#/definitions/uint32-matrix
180        maxItems: 32
181        items:
182          minItems: 1
183          maxItems: 4
184
185      required-opps:
186        description:
187          This contains phandle to an OPP node in another device's OPP table. It
188          may contain an array of phandles, where each phandle points to an OPP
189          of a different device. It should not contain multiple phandles to the
190          OPP nodes in the same OPP table. This specifies the minimum required
191          OPP of the device(s), whose OPP's phandle is present in this property,
192          for the functioning of the current device at the current OPP (where
193          this property is present).
194        $ref: /schemas/types.yaml#/definitions/phandle-array
195        items:
196          maxItems: 1
197
198    patternProperties:
199      '^opp-microvolt-':
200        description:
201          Named opp-microvolt property. This is exactly similar to the above
202          opp-microvolt property, but allows multiple voltage ranges to be
203          provided for the same OPP. At runtime, the platform can pick a <name>
204          and matching opp-microvolt-<name> property will be enabled for all
205          OPPs. If the platform doesn't pick a specific <name> or the <name>
206          doesn't match with any opp-microvolt-<name> properties, then
207          opp-microvolt property shall be used, if present.
208        $ref: /schemas/types.yaml#/definitions/uint32-matrix
209        minItems: 1
210        maxItems: 8   # Should be enough regulators
211        items:
212          minItems: 1
213          maxItems: 3
214
215      '^opp-microamp-':
216        description:
217          Named opp-microamp property. Similar to opp-microvolt-<name> property,
218          but for microamp instead.
219        $ref: /schemas/types.yaml#/definitions/uint32-array
220        minItems: 1
221        maxItems: 8   # Should be enough regulators
222
223      '^opp-microwatt':
224        description:
225          Named opp-microwatt property. Similar to opp-microamp property,
226          but for microwatt instead.
227        $ref: /schemas/types.yaml#/definitions/uint32-array
228        minItems: 1
229        maxItems: 8   # Should be enough regulators
230
231    dependencies:
232      opp-avg-kBps: [ opp-peak-kBps ]
233
234required:
235  - compatible
236
237additionalProperties: true
238
239...
240