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