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