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
 217   regulator-coupled-max-spread:
 218     description: Array of maximum spread between voltages of coupled regulators
 219       in microvolts, each value in the array relates to the corresponding
 220       couple specified by the regulator-coupled-with property.
 221     $ref: "/schemas/types.yaml#/definitions/uint32"
 222
 223   regulator-max-step-microvolt:
 224     description: Maximum difference between current and target voltages
 225       that can be changed safely in a single step.
 226
 227 patternProperties:
 228   ".*-supply$":
 229     description: Input supply phandle(s) for this node
 230
 231   regulator-state-(standby|mem|disk):
 232     type: object
 233     description:
 234       sub-nodes for regulator state in Standby, Suspend-to-RAM, and
 235       Suspend-to-DISK modes. Equivalent with standby, mem, and disk Linux
 236       sleep states.
 237
 238     properties:
 239       regulator-on-in-suspend:
 240         description: regulator should be on in suspend state.
 241         type: boolean
 242
 243       regulator-off-in-suspend:
 244         description: regulator should be off in suspend state.
 245         type: boolean
 246
 247       regulator-suspend-min-microvolt:
 248         description: minimum voltage may be set in suspend state.
 249
 250       regulator-suspend-max-microvolt:
 251         description: maximum voltage may be set in suspend state.
 252
 253       regulator-suspend-microvolt:
 254         description: the default voltage which regulator would be set in
 255           suspend. This property is now deprecated, instead setting voltage
 256           for suspend mode via the API which regulator driver provides is
 257           recommended.
 258
 259       regulator-changeable-in-suspend:
 260         description: whether the default voltage and the regulator on/off
 261           in suspend can be changed in runtime.
 262         type: boolean
 263
 264       regulator-mode:
 265         description: operating mode in the given suspend state. The set
 266           of possible operating modes depends on the capabilities of every
 267           hardware so the valid modes are documented on each regulator device
 268           tree binding document.
 269         $ref: "/schemas/types.yaml#/definitions/uint32"
 270
 271     additionalProperties: false
 272
 273 additionalProperties: true
 274
 275 examples:
 276   - |
 277     xyzreg: regulator {
 278       regulator-min-microvolt = <1000000>;
 279       regulator-max-microvolt = <2500000>;
 280       regulator-always-on;
 281       vin-supply = <&vin>;
 282
 283       regulator-state-mem {
 284         regulator-on-in-suspend;
 285       };
 286     };
 287
 288 ...