Bindings/regulator/regulator.yaml

   1 # SPDX-License-Identifier: GPL-2.0
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/regulator/regulator.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: Voltage/Current Regulators
   8
   9 maintainers:
  10   - Liam Girdwood <lgirdwood@gmail.com>
  11   - Mark Brown <broonie@kernel.org>
  12
  13 properties:
  14   regulator-name:
  15     description: A string used as a descriptive name for regulator outputs
  16     $ref: /schemas/types.yaml#/definitions/string
  17
  18   regulator-min-microvolt:
  19     description: smallest voltage consumers may set
  20
  21   regulator-max-microvolt:
  22     description: largest voltage consumers may set
  23
  24   regulator-microvolt-offset:
  25     description: Offset applied to voltages to compensate for voltage drops
  26     $ref: /schemas/types.yaml#/definitions/uint32
  27
  28   regulator-min-microamp:
  29     description: smallest current consumers may set
  30
  31   regulator-max-microamp:
  32     description: largest current consumers may set
  33
  34   regulator-input-current-limit-microamp:
  35     description: maximum input current regulator allows
  36
  37   regulator-always-on:
  38     description: boolean, regulator should never be disabled
  39     type: boolean
  40
  41   regulator-boot-on:
  42     description: bootloader/firmware enabled regulator.
  43       It's expected that this regulator was left on by the bootloader.
  44       If the bootloader didn't leave it on then OS should turn it on
  45       at boot but shouldn't prevent it from being turned off later.
  46       This property is intended to only be used for regulators where
  47       software cannot read the state of the regulator.
  48     type: boolean
  49
  50   regulator-allow-bypass:
  51     description: allow the regulator to go into bypass mode
  52     type: boolean
  53
  54   regulator-allow-set-load:
  55     description: allow the regulator performance level to be configured
  56     type: boolean
  57
  58   regulator-ramp-delay:
  59     description: ramp delay for regulator(in uV/us) For hardware which supports
  60       disabling ramp rate, it should be explicitly initialised to zero (regulator-ramp-delay
  61       = <0>) for disabling ramp delay.
  62     $ref: /schemas/types.yaml#/definitions/uint32
  63
  64   regulator-enable-ramp-delay:
  65     description: The time taken, in microseconds, for the supply rail to
  66       reach the target voltage, plus/minus whatever tolerance the board
  67       design requires. This property describes the total system ramp time
  68       required due to the combination of internal ramping of the regulator
  69       itself, and board design issues such as trace capacitance and load
  70       on the supply.
  71     $ref: /schemas/types.yaml#/definitions/uint32
  72
  73   regulator-settling-time-us:
  74     description: Settling time, in microseconds, for voltage change if regulator
  75       have the constant time for any level voltage change. This is useful
  76       when regulator have exponential voltage change.
  77
  78   regulator-settling-time-up-us:
  79     description: Settling time, in microseconds, for voltage increase if
  80       the regulator needs a constant time to settle after voltage increases
  81       of any level. This is useful for regulators with exponential voltage
  82       changes.
  83
  84   regulator-settling-time-down-us:
  85     description: Settling time, in microseconds, for voltage decrease if
  86       the regulator needs a constant time to settle after voltage decreases
  87       of any level. This is useful for regulators with exponential voltage
  88       changes.
  89
  90   regulator-soft-start:
  91     description: Enable soft start so that voltage ramps slowly
  92     type: boolean
  93
  94   regulator-initial-mode:
  95     description: initial operating mode. The set of possible operating modes
  96       depends on the capabilities of every hardware so each device binding
  97       documentation explains which values the regulator supports.
  98     $ref: /schemas/types.yaml#/definitions/uint32
  99
 100   regulator-allowed-modes:
 101     description: list of operating modes that software is allowed to configure
 102       for the regulator at run-time.  Elements may be specified in any order.
 103       The set of possible operating modes depends on the capabilities of
 104       every hardware so each device binding document explains which values
 105       the regulator supports.
 106     $ref: /schemas/types.yaml#/definitions/uint32-array
 107
 108   regulator-system-load:
 109     description: Load in uA present on regulator that is not captured by
 110       any consumer request.
 111     $ref: /schemas/types.yaml#/definitions/uint32
 112
 113   regulator-pull-down:
 114     description: Enable pull down resistor when the regulator is disabled.
 115     type: boolean
 116
 117   system-critical-regulator:
 118     description: Set if the regulator is critical to system stability or
 119       functionality.
 120     type: boolean
 121
 122   regulator-over-current-protection:
 123     description: Enable over current protection.
 124     type: boolean
 125
 126   regulator-oc-protection-microamp:
 127     description: Set over current protection limit. This is a limit where
 128       hardware performs emergency shutdown. Zero can be passed to disable
 129       protection and value '1' indicates that protection should be enabled but
 130       limit setting can be omitted.
 131
 132   regulator-oc-error-microamp:
 133     description: Set over current error limit. This is a limit where part of
 134       the hardware probably is malfunctional and damage prevention is requested.
 135       Zero can be passed to disable error detection and value '1' indicates
 136       that detection should be enabled but limit setting can be omitted.
 137
 138   regulator-oc-warn-microamp:
 139     description: Set over current warning limit. This is a limit where hardware
 140       is assumed still to be functional but approaching limit where it gets
 141       damaged. Recovery actions should be initiated. Zero can be passed to
 142       disable detection and value '1' indicates that detection should
 143       be enabled but limit setting can be omitted.
 144
 145   regulator-ov-protection-microvolt:
 146     description: Set over voltage protection limit. This is a limit where
 147       hardware performs emergency shutdown. Zero can be passed to disable
 148       protection and value '1' indicates that protection should be enabled but
 149       limit setting can be omitted. Limit is given as microvolt offset from
 150       voltage set to regulator.
 151
 152   regulator-ov-error-microvolt:
 153     description: Set over voltage error limit. This is a limit where part of
 154       the hardware probably is malfunctional and damage prevention is requested
 155       Zero can be passed to disable error detection and value '1' indicates
 156       that detection should be enabled but limit setting can be omitted. Limit
 157       is given as microvolt offset from voltage set to regulator.
 158
 159   regulator-ov-warn-microvolt:
 160     description: Set over voltage warning limit. This is a limit where hardware
 161       is assumed still to be functional but approaching limit where it gets
 162       damaged. Recovery actions should be initiated. Zero can be passed to
 163       disable detection and value '1' indicates that detection should
 164       be enabled but limit setting can be omitted. Limit is given as microvolt
 165       offset from voltage set to regulator.
 166
 167   regulator-uv-protection-microvolt:
 168     description: Set over under voltage protection limit. This is a limit where
 169       hardware performs emergency shutdown. Zero can be passed to disable
 170       protection and value '1' indicates that protection should be enabled but
 171       limit setting can be omitted. Limit is given as microvolt offset from
 172       voltage set to regulator.
 173
 174   regulator-uv-error-microvolt:
 175     description: Set under voltage error limit. This is a limit where part of
 176       the hardware probably is malfunctional and damage prevention is requested
 177       Zero can be passed to disable error detection and value '1' indicates
 178       that detection should be enabled but limit setting can be omitted. Limit
 179       is given as microvolt offset from voltage set to regulator.
 180
 181   regulator-uv-warn-microvolt:
 182     description: Set over under voltage warning limit. This is a limit where
 183       hardware is assumed still to be functional but approaching limit where
 184       it gets damaged. Recovery actions should be initiated. Zero can be passed
 185       to disable detection and value '1' indicates that detection should
 186       be enabled but limit setting can be omitted. Limit is given as microvolt
 187       offset from voltage set to regulator.
 188
 189   regulator-uv-less-critical-window-ms:
 190     description: Specifies the time window (in milliseconds) following a
 191       critical under-voltage event during which the system can continue to
 192       operate safely while performing less critical operations. This property
 193       provides a defined duration before a more severe reaction to the
 194       under-voltage event is needed, allowing for certain non-urgent actions to
 195       be carried out in preparation for potential power loss.
 196
 197   regulator-temp-protection-kelvin:
 198     description: Set over temperature protection limit. This is a limit where
 199       hardware performs emergency shutdown. Zero can be passed to disable
 200       protection and value '1' indicates that protection should be enabled but
 201       limit setting can be omitted.
 202
 203   regulator-temp-error-kelvin:
 204     description: Set over temperature error limit. This is a limit where part of
 205       the hardware probably is malfunctional and damage prevention is requested
 206       Zero can be passed to disable error detection and value '1' indicates
 207       that detection should be enabled but limit setting can be omitted.
 208
 209   regulator-temp-warn-kelvin:
 210     description: Set over temperature warning limit. This is a limit where
 211       hardware is assumed still to be functional but approaching limit where it
 212       gets damaged. Recovery actions should be initiated. Zero can be passed to
 213       disable detection and value '1' indicates that detection should
 214       be enabled but limit setting can be omitted.
 215
 216   regulator-active-discharge:
 217     description: |
 218       tristate, enable/disable active discharge of regulators. The values are:
 219       0: Disable active discharge.
 220       1: Enable active discharge.
 221       Absence of this property will leave configuration to default.
 222     $ref: /schemas/types.yaml#/definitions/uint32
 223     enum: [0, 1]
 224
 225   regulator-coupled-with:
 226     description: Regulators with which the regulator is coupled. The linkage
 227       is 2-way - all coupled regulators should be linked with each other.
 228       A regulator should not be coupled with its supplier.
 229     $ref: /schemas/types.yaml#/definitions/phandle-array
 230     items:
 231       maxItems: 1
 232
 233   regulator-coupled-max-spread:
 234     description: Array of maximum spread between voltages of coupled regulators
 235       in microvolts, each value in the array relates to the corresponding
 236       couple specified by the regulator-coupled-with property.
 237     $ref: /schemas/types.yaml#/definitions/uint32-array
 238
 239   regulator-max-step-microvolt:
 240     description: Maximum difference between current and target voltages
 241       that can be changed safely in a single step.
 242
 243 patternProperties:
 244   ".*-supply$":
 245     description: Input supply phandle(s) for this node
 246
 247   "^regulator-state-(standby|mem|disk)$":
 248     type: object
 249     description:
 250       sub-nodes for regulator state in Standby, Suspend-to-RAM, and
 251       Suspend-to-DISK modes. Equivalent with standby, mem, and disk Linux
 252       sleep states.
 253
 254     properties:
 255       regulator-on-in-suspend:
 256         description: regulator should be on in suspend state.
 257         type: boolean
 258
 259       regulator-off-in-suspend:
 260         description: regulator should be off in suspend state.
 261         type: boolean
 262
 263       regulator-suspend-min-microvolt:
 264         description: minimum voltage may be set in suspend state.
 265
 266       regulator-suspend-max-microvolt:
 267         description: maximum voltage may be set in suspend state.
 268
 269       regulator-suspend-microvolt:
 270         description: the default voltage which regulator would be set in
 271           suspend. This property is now deprecated, instead setting voltage
 272           for suspend mode via the API which regulator driver provides is
 273           recommended.
 274
 275       regulator-changeable-in-suspend:
 276         description: whether the default voltage and the regulator on/off
 277           in suspend can be changed in runtime.
 278         type: boolean
 279
 280       regulator-mode:
 281         description: operating mode in the given suspend state. The set
 282           of possible operating modes depends on the capabilities of every
 283           hardware so the valid modes are documented on each regulator device
 284           tree binding document.
 285         $ref: /schemas/types.yaml#/definitions/uint32
 286
 287     additionalProperties: false
 288
 289 additionalProperties: true
 290
 291 examples:
 292   - |
 293     xyzreg: regulator {
 294       regulator-min-microvolt = <1000000>;
 295       regulator-max-microvolt = <2500000>;
 296       regulator-always-on;
 297       vin-supply = <&vin>;
 298
 299       regulator-state-mem {
 300         regulator-on-in-suspend;
 301       };
 302     };
 303
 304 ...