Documentation/devicetree/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   regulator-over-current-protection:
 118     description: Enable over current protection.
 119     type: boolean
 120
 121   regulator-oc-protection-microamp:
 122     description: Set over current protection limit. This is a limit where
 123       hardware performs emergency shutdown. Zero can be passed to disable
 124       protection and value '1' indicates that protection should be enabled but
 125       limit setting can be omitted.
 126
 127   regulator-oc-error-microamp:
 128     description: Set over current error limit. This is a limit where part of
 129       the hardware propably is malfunctional and damage prevention is requested.
 130       Zero can be passed to disable error detection and value '1' indicates
 131       that detection should be enabled but limit setting can be omitted.
 132
 133   regulator-oc-warn-microamp:
 134     description: Set over current warning limit. This is a limit where hardware
 135       is assumed still to be functional but approaching limit where it gets
 136       damaged. Recovery actions should be initiated. Zero can be passed to
 137       disable detection and value '1' indicates that detection should
 138       be enabled but limit setting can be omitted.
 139
 140   regulator-ov-protection-microvolt:
 141     description: Set over voltage protection limit. This is a limit where
 142       hardware performs emergency shutdown. Zero can be passed to disable
 143       protection and value '1' indicates that protection should be enabled but
 144       limit setting can be omitted. Limit is given as microvolt offset from
 145       voltage set to regulator.
 146
 147   regulator-ov-error-microvolt:
 148     description: Set over voltage error limit. This is a limit where part of
 149       the hardware propably is malfunctional and damage prevention is requested
 150       Zero can be passed to disable error detection and value '1' indicates
 151       that detection should be enabled but limit setting can be omitted. Limit
 152       is given as microvolt offset from voltage set to regulator.
 153
 154   regulator-ov-warn-microvolt:
 155     description: Set over voltage warning limit. This is a limit where hardware
 156       is assumed still to be functional but approaching limit where it gets
 157       damaged. Recovery actions should be initiated. Zero can be passed to
 158       disable detection and value '1' indicates that detection should
 159       be enabled but limit setting can be omitted. Limit is given as microvolt
 160       offset from voltage set to regulator.
 161
 162   regulator-uv-protection-microvolt:
 163     description: Set over under voltage protection limit. This is a limit where
 164       hardware performs emergency shutdown. Zero can be passed to disable
 165       protection and value '1' indicates that protection should be enabled but
 166       limit setting can be omitted. Limit is given as microvolt offset from
 167       voltage set to regulator.
 168
 169   regulator-uv-error-microvolt:
 170     description: Set under voltage error limit. This is a limit where part of
 171       the hardware propably is malfunctional and damage prevention is requested
 172       Zero can be passed to disable error detection and value '1' indicates
 173       that detection should be enabled but limit setting can be omitted. Limit
 174       is given as microvolt offset from voltage set to regulator.
 175
 176   regulator-uv-warn-microvolt:
 177     description: Set over under voltage warning limit. This is a limit where
 178       hardware is assumed still to be functional but approaching limit where
 179       it gets damaged. Recovery actions should be initiated. Zero can be passed
 180       to disable detection and value '1' indicates that detection should
 181       be enabled but limit setting can be omitted. Limit is given as microvolt
 182       offset from voltage set to regulator.
 183
 184   regulator-temp-protection-kelvin:
 185     description: Set over temperature protection limit. This is a limit where
 186       hardware performs emergency shutdown. Zero can be passed to disable
 187       protection and value '1' indicates that protection should be enabled but
 188       limit setting can be omitted.
 189
 190   regulator-temp-error-kelvin:
 191     description: Set over temperature error limit. This is a limit where part of
 192       the hardware propably is malfunctional and damage prevention is requested
 193       Zero can be passed to disable error detection and value '1' indicates
 194       that detection should be enabled but limit setting can be omitted.
 195
 196   regulator-temp-warn-kelvin:
 197     description: Set over temperature warning limit. This is a limit where
 198       hardware is assumed still to be functional but approaching limit where it
 199       gets damaged. Recovery actions should be initiated. Zero can be passed to
 200       disable detection and value '1' indicates that detection should
 201       be enabled but limit setting can be omitted.
 202
 203   regulator-active-discharge:
 204     description: |
 205       tristate, enable/disable active discharge of regulators. The values are:
 206       0: Disable active discharge.
 207       1: Enable active discharge.
 208       Absence of this property will leave configuration to default.
 209     $ref: "/schemas/types.yaml#/definitions/uint32"
 210     enum: [0, 1]
 211
 212   regulator-coupled-with:
 213     description: Regulators with which the regulator is coupled. The linkage
 214       is 2-way - all coupled regulators should be linked with each other.
 215       A regulator should not be coupled with its supplier.
 216     $ref: "/schemas/types.yaml#/definitions/phandle-array"
 217     items:
 218       maxItems: 1
 219
 220   regulator-coupled-max-spread:
 221     description: Array of maximum spread between voltages of coupled regulators
 222       in microvolts, each value in the array relates to the corresponding
 223       couple specified by the regulator-coupled-with property.
 224     $ref: "/schemas/types.yaml#/definitions/uint32-array"
 225
 226   regulator-max-step-microvolt:
 227     description: Maximum difference between current and target voltages
 228       that can be changed safely in a single step.
 229
 230 patternProperties:
 231   ".*-supply$":
 232     description: Input supply phandle(s) for this node
 233
 234   regulator-state-(standby|mem|disk):
 235     type: object
 236     description:
 237       sub-nodes for regulator state in Standby, Suspend-to-RAM, and
 238       Suspend-to-DISK modes. Equivalent with standby, mem, and disk Linux
 239       sleep states.
 240
 241     properties:
 242       regulator-on-in-suspend:
 243         description: regulator should be on in suspend state.
 244         type: boolean
 245
 246       regulator-off-in-suspend:
 247         description: regulator should be off in suspend state.
 248         type: boolean
 249
 250       regulator-suspend-min-microvolt:
 251         description: minimum voltage may be set in suspend state.
 252
 253       regulator-suspend-max-microvolt:
 254         description: maximum voltage may be set in suspend state.
 255
 256       regulator-suspend-microvolt:
 257         description: the default voltage which regulator would be set in
 258           suspend. This property is now deprecated, instead setting voltage
 259           for suspend mode via the API which regulator driver provides is
 260           recommended.
 261
 262       regulator-changeable-in-suspend:
 263         description: whether the default voltage and the regulator on/off
 264           in suspend can be changed in runtime.
 265         type: boolean
 266
 267       regulator-mode:
 268         description: operating mode in the given suspend state. The set
 269           of possible operating modes depends on the capabilities of every
 270           hardware so the valid modes are documented on each regulator device
 271           tree binding document.
 272         $ref: "/schemas/types.yaml#/definitions/uint32"
 273
 274     additionalProperties: false
 275
 276 additionalProperties: true
 277
 278 examples:
 279   - |
 280     xyzreg: regulator {
 281       regulator-min-microvolt = <1000000>;
 282       regulator-max-microvolt = <2500000>;
 283       regulator-always-on;
 284       vin-supply = <&vin>;
 285
 286       regulator-state-mem {
 287         regulator-on-in-suspend;
 288       };
 289     };
 290
 291 ...