0001 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002 %YAML 1.2
0003 ---
0004 $id: http://devicetree.org/schemas/opp/opp-v2-base.yaml#
0005 $schema: http://devicetree.org/meta-schemas/core.yaml#
0006
0007 title: Generic OPP (Operating Performance Points) Common Binding
0008
0009 maintainers:
0010 - Viresh Kumar <viresh.kumar@linaro.org>
0011
0012 description: |
0013 Devices work at voltage-current-frequency combinations and some implementations
0014 have the liberty of choosing these. These combinations are called Operating
0015 Performance Points aka OPPs. This document defines bindings for these OPPs
0016 applicable across wide range of devices. For illustration purpose, this document
0017 uses CPU as a device.
0018
0019 This describes the OPPs belonging to a device.
0020
0021 select: false
0022
0023 properties:
0024 $nodename:
0025 pattern: '^opp-table(-[a-z0-9]+)?$'
0026
0027 opp-shared:
0028 description:
0029 Indicates that device nodes using this OPP Table Node's phandle switch
0030 their DVFS state together, i.e. they share clock/voltage/current lines.
0031 Missing property means devices have independent clock/voltage/current
0032 lines, but they share OPP tables.
0033 type: boolean
0034
0035 patternProperties:
0036 '^opp(-?[0-9]+)*$':
0037 type: object
0038 description:
0039 One or more OPP nodes describing voltage-current-frequency combinations.
0040 Their name isn't significant but their phandle can be used to reference an
0041 OPP. These are mandatory except for the case where the OPP table is
0042 present only to indicate dependency between devices using the opp-shared
0043 property.
0044
0045 properties:
0046 opp-hz:
0047 description:
0048 Frequency in Hz, expressed as a 64-bit big-endian integer. This is a
0049 required property for all device nodes, unless another "required"
0050 property to uniquely identify the OPP nodes exists. Devices like power
0051 domains must have another (implementation dependent) property.
0052
0053 Entries for multiple clocks shall be provided in the same field, as
0054 array of frequencies. The OPP binding doesn't provide any provisions
0055 to relate the values to their clocks or the order in which the clocks
0056 need to be configured and that is left for the implementation
0057 specific binding.
0058 minItems: 1
0059 maxItems: 16
0060 items:
0061 maxItems: 1
0062
0063 opp-microvolt:
0064 description: |
0065 Voltage for the OPP
0066
0067 A single regulator's voltage is specified with an array of size one or three.
0068 Single entry is for target voltage and three entries are for <target min max>
0069 voltages.
0070
0071 Entries for multiple regulators shall be provided in the same field separated
0072 by angular brackets <>. The OPP binding doesn't provide any provisions to
0073 relate the values to their power supplies or the order in which the supplies
0074 need to be configured and that is left for the implementation specific
0075 binding.
0076
0077 Entries for all regulators shall be of the same size, i.e. either all use a
0078 single value or triplets.
0079 minItems: 1
0080 maxItems: 8 # Should be enough regulators
0081 items:
0082 minItems: 1
0083 maxItems: 3
0084
0085 opp-microamp:
0086 description: |
0087 The maximum current drawn by the device in microamperes considering
0088 system specific parameters (such as transients, process, aging,
0089 maximum operating temperature range etc.) as necessary. This may be
0090 used to set the most efficient regulator operating mode.
0091
0092 Should only be set if opp-microvolt or opp-microvolt-<name> is set for
0093 the OPP.
0094
0095 Entries for multiple regulators shall be provided in the same field
0096 separated by angular brackets <>. If current values aren't required
0097 for a regulator, then it shall be filled with 0. If current values
0098 aren't required for any of the regulators, then this field is not
0099 required. The OPP binding doesn't provide any provisions to relate the
0100 values to their power supplies or the order in which the supplies need
0101 to be configured and that is left for the implementation specific
0102 binding.
0103 minItems: 1
0104 maxItems: 8 # Should be enough regulators
0105
0106 opp-microwatt:
0107 description: |
0108 The power for the OPP in micro-Watts.
0109
0110 Entries for multiple regulators shall be provided in the same field
0111 separated by angular brackets <>. If current values aren't required
0112 for a regulator, then it shall be filled with 0. If power values
0113 aren't required for any of the regulators, then this field is not
0114 required. The OPP binding doesn't provide any provisions to relate the
0115 values to their power supplies or the order in which the supplies need
0116 to be configured and that is left for the implementation specific
0117 binding.
0118 minItems: 1
0119 maxItems: 8 # Should be enough regulators
0120
0121 opp-level:
0122 description:
0123 A value representing the performance level of the device.
0124 $ref: /schemas/types.yaml#/definitions/uint32
0125
0126 opp-peak-kBps:
0127 description:
0128 Peak bandwidth in kilobytes per second, expressed as an array of
0129 32-bit big-endian integers. Each element of the array represents the
0130 peak bandwidth value of each interconnect path. The number of elements
0131 should match the number of interconnect paths.
0132 minItems: 1
0133 maxItems: 32 # Should be enough
0134
0135 opp-avg-kBps:
0136 description:
0137 Average bandwidth in kilobytes per second, expressed as an array
0138 of 32-bit big-endian integers. Each element of the array represents the
0139 average bandwidth value of each interconnect path. The number of elements
0140 should match the number of interconnect paths. This property is only
0141 meaningful in OPP tables where opp-peak-kBps is present.
0142 minItems: 1
0143 maxItems: 32 # Should be enough
0144
0145 clock-latency-ns:
0146 description:
0147 Specifies the maximum possible transition latency (in nanoseconds) for
0148 switching to this OPP from any other OPP.
0149
0150 turbo-mode:
0151 description:
0152 Marks the OPP to be used only for turbo modes. Turbo mode is available
0153 on some platforms, where the device can run over its operating
0154 frequency for a short duration of time limited by the device's power,
0155 current and thermal limits.
0156 type: boolean
0157
0158 opp-suspend:
0159 description:
0160 Marks the OPP to be used during device suspend. If multiple OPPs in
0161 the table have this, the OPP with highest opp-hz will be used.
0162 type: boolean
0163
0164 opp-supported-hw:
0165 description: |
0166 This property allows a platform to enable only a subset of the OPPs
0167 from the larger set present in the OPP table, based on the current
0168 version of the hardware (already known to the operating system).
0169
0170 Each block present in the array of blocks in this property, represents
0171 a sub-group of hardware versions supported by the OPP. i.e. <sub-group
0172 A>, <sub-group B>, etc. The OPP will be enabled if _any_ of these
0173 sub-groups match the hardware's version.
0174
0175 Each sub-group is a platform defined array representing the hierarchy
0176 of hardware versions supported by the platform. For a platform with
0177 three hierarchical levels of version (X.Y.Z), this field shall look
0178 like
0179
0180 opp-supported-hw = <X1 Y1 Z1>, <X2 Y2 Z2>, <X3 Y3 Z3>.
0181
0182 Each level (eg. X1) in version hierarchy is represented by a 32 bit
0183 value, one bit per version and so there can be maximum 32 versions per
0184 level. Logical AND (&) operation is performed for each level with the
0185 hardware's level version and a non-zero output for _all_ the levels in
0186 a sub-group means the OPP is supported by hardware. A value of
0187 0xFFFFFFFF for each level in the sub-group will enable the OPP for all
0188 versions for the hardware.
0189 $ref: /schemas/types.yaml#/definitions/uint32-matrix
0190 maxItems: 32
0191 items:
0192 minItems: 1
0193 maxItems: 4
0194
0195 required-opps:
0196 description:
0197 This contains phandle to an OPP node in another device's OPP table. It
0198 may contain an array of phandles, where each phandle points to an OPP
0199 of a different device. It should not contain multiple phandles to the
0200 OPP nodes in the same OPP table. This specifies the minimum required
0201 OPP of the device(s), whose OPP's phandle is present in this property,
0202 for the functioning of the current device at the current OPP (where
0203 this property is present).
0204 $ref: /schemas/types.yaml#/definitions/phandle-array
0205 items:
0206 maxItems: 1
0207
0208 patternProperties:
0209 '^opp-microvolt-':
0210 description:
0211 Named opp-microvolt property. This is exactly similar to the above
0212 opp-microvolt property, but allows multiple voltage ranges to be
0213 provided for the same OPP. At runtime, the platform can pick a <name>
0214 and matching opp-microvolt-<name> property will be enabled for all
0215 OPPs. If the platform doesn't pick a specific <name> or the <name>
0216 doesn't match with any opp-microvolt-<name> properties, then
0217 opp-microvolt property shall be used, if present.
0218 $ref: /schemas/types.yaml#/definitions/uint32-matrix
0219 minItems: 1
0220 maxItems: 8 # Should be enough regulators
0221 items:
0222 minItems: 1
0223 maxItems: 3
0224
0225 '^opp-microamp-':
0226 description:
0227 Named opp-microamp property. Similar to opp-microvolt-<name> property,
0228 but for microamp instead.
0229 $ref: /schemas/types.yaml#/definitions/uint32-array
0230 minItems: 1
0231 maxItems: 8 # Should be enough regulators
0232
0233 '^opp-microwatt':
0234 description:
0235 Named opp-microwatt property. Similar to opp-microamp property,
0236 but for microwatt instead.
0237 $ref: /schemas/types.yaml#/definitions/uint32-array
0238 minItems: 1
0239 maxItems: 8 # Should be enough regulators
0240
0241 dependencies:
0242 opp-avg-kBps: [ opp-peak-kBps ]
0243
0244 required:
0245 - compatible
0246
0247 additionalProperties: true
0248
0249 ...
