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          Entries for multiple clocks shall be provided in the same field, as
54          array of frequencies.  The OPP binding doesn't provide any provisions
55          to relate the values to their clocks or the order in which the clocks
56          need to be configured and that is left for the implementation
57          specific binding.
58        minItems: 1
59        maxItems: 16
60        items:
61          maxItems: 1
62
63      opp-microvolt:
64        description: |
65          Voltage for the OPP
66
67          A single regulator's voltage is specified with an array of size one or three.
68          Single entry is for target voltage and three entries are for <target min max>
69          voltages.
70
71          Entries for multiple regulators shall be provided in the same field separated
72          by angular brackets <>. The OPP binding doesn't provide any provisions to
73          relate the values to their power supplies or the order in which the supplies
74          need to be configured and that is left for the implementation specific
75          binding.
76
77          Entries for all regulators shall be of the same size, i.e. either all use a
78          single value or triplets.
79        minItems: 1
80        maxItems: 8   # Should be enough regulators
81        items:
82          minItems: 1
83          maxItems: 3
84
85      opp-microamp:
86        description: |
87          The maximum current drawn by the device in microamperes considering
88          system specific parameters (such as transients, process, aging,
89          maximum operating temperature range etc.) as necessary. This may be
90          used to set the most efficient regulator operating mode.
91
92          Should only be set if opp-microvolt or opp-microvolt-<name> is set for
93          the OPP.
94
95          Entries for multiple regulators shall be provided in the same field
96          separated by angular brackets <>. If current values aren't required
97          for a regulator, then it shall be filled with 0. If current values
98          aren't required for any of the regulators, then this field is not
99          required. The OPP binding doesn't provide any provisions to relate the
100          values to their power supplies or the order in which the supplies need
101          to be configured and that is left for the implementation specific
102          binding.
103        minItems: 1
104        maxItems: 8   # Should be enough regulators
105
106      opp-microwatt:
107        description: |
108          The power for the OPP in micro-Watts.
109
110          Entries for multiple regulators shall be provided in the same field
111          separated by angular brackets <>. If current values aren't required
112          for a regulator, then it shall be filled with 0. If power values
113          aren't required for any of the regulators, then this field is not
114          required. The OPP binding doesn't provide any provisions to relate the
115          values to their power supplies or the order in which the supplies need
116          to be configured and that is left for the implementation specific
117          binding.
118        minItems: 1
119        maxItems: 8   # Should be enough regulators
120
121      opp-level:
122        description:
123          A value representing the performance level of the device.
124        $ref: /schemas/types.yaml#/definitions/uint32
125
126      opp-peak-kBps:
127        description:
128          Peak bandwidth in kilobytes per second, expressed as an array of
129          32-bit big-endian integers. Each element of the array represents the
130          peak bandwidth value of each interconnect path. The number of elements
131          should match the number of interconnect paths.
132        minItems: 1
133        maxItems: 32  # Should be enough
134
135      opp-avg-kBps:
136        description:
137          Average bandwidth in kilobytes per second, expressed as an array
138          of 32-bit big-endian integers. Each element of the array represents the
139          average bandwidth value of each interconnect path. The number of elements
140          should match the number of interconnect paths. This property is only
141          meaningful in OPP tables where opp-peak-kBps is present.
142        minItems: 1
143        maxItems: 32  # Should be enough
144
145      clock-latency-ns:
146        description:
147          Specifies the maximum possible transition latency (in nanoseconds) for
148          switching to this OPP from any other OPP.
149
150      turbo-mode:
151        description:
152          Marks the OPP to be used only for turbo modes. Turbo mode is available
153          on some platforms, where the device can run over its operating
154          frequency for a short duration of time limited by the device's power,
155          current and thermal limits.
156        type: boolean
157
158      opp-suspend:
159        description:
160          Marks the OPP to be used during device suspend. If multiple OPPs in
161          the table have this, the OPP with highest opp-hz will be used.
162        type: boolean
163
164      opp-supported-hw:
165        description: |
166          This property allows a platform to enable only a subset of the OPPs
167          from the larger set present in the OPP table, based on the current
168          version of the hardware (already known to the operating system).
169
170          Each block present in the array of blocks in this property, represents
171          a sub-group of hardware versions supported by the OPP. i.e. <sub-group
172          A>, <sub-group B>, etc. The OPP will be enabled if _any_ of these
173          sub-groups match the hardware's version.
174
175          Each sub-group is a platform defined array representing the hierarchy
176          of hardware versions supported by the platform. For a platform with
177          three hierarchical levels of version (X.Y.Z), this field shall look
178          like
179
180          opp-supported-hw = <X1 Y1 Z1>, <X2 Y2 Z2>, <X3 Y3 Z3>.
181
182          Each level (eg. X1) in version hierarchy is represented by a 32 bit
183          value, one bit per version and so there can be maximum 32 versions per
184          level. Logical AND (&) operation is performed for each level with the
185          hardware's level version and a non-zero output for _all_ the levels in
186          a sub-group means the OPP is supported by hardware. A value of
187          0xFFFFFFFF for each level in the sub-group will enable the OPP for all
188          versions for the hardware.
189        $ref: /schemas/types.yaml#/definitions/uint32-matrix
190        maxItems: 32
191        items:
192          minItems: 1
193          maxItems: 4
194
195      required-opps:
196        description:
197          This contains phandle to an OPP node in another device's OPP table. It
198          may contain an array of phandles, where each phandle points to an OPP
199          of a different device. It should not contain multiple phandles to the
200          OPP nodes in the same OPP table. This specifies the minimum required
201          OPP of the device(s), whose OPP's phandle is present in this property,
202          for the functioning of the current device at the current OPP (where
203          this property is present).
204        $ref: /schemas/types.yaml#/definitions/phandle-array
205        items:
206          maxItems: 1
207
208    patternProperties:
209      '^opp-microvolt-':
210        description:
211          Named opp-microvolt property. This is exactly similar to the above
212          opp-microvolt property, but allows multiple voltage ranges to be
213          provided for the same OPP. At runtime, the platform can pick a <name>
214          and matching opp-microvolt-<name> property will be enabled for all
215          OPPs. If the platform doesn't pick a specific <name> or the <name>
216          doesn't match with any opp-microvolt-<name> properties, then
217          opp-microvolt property shall be used, if present.
218        $ref: /schemas/types.yaml#/definitions/uint32-matrix
219        minItems: 1
220        maxItems: 8   # Should be enough regulators
221        items:
222          minItems: 1
223          maxItems: 3
224
225      '^opp-microamp-':
226        description:
227          Named opp-microamp property. Similar to opp-microvolt-<name> property,
228          but for microamp instead.
229        $ref: /schemas/types.yaml#/definitions/uint32-array
230        minItems: 1
231        maxItems: 8   # Should be enough regulators
232
233      '^opp-microwatt':
234        description:
235          Named opp-microwatt property. Similar to opp-microamp property,
236          but for microwatt instead.
237        $ref: /schemas/types.yaml#/definitions/uint32-array
238        minItems: 1
239        maxItems: 8   # Should be enough regulators
240
241    dependencies:
242      opp-avg-kBps: [ opp-peak-kBps ]
243
244required:
245  - compatible
246
247additionalProperties: true
248
249...
250