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
7title: Voltage/Current Regulators
8
9maintainers:
10  - Liam Girdwood <lgirdwood@gmail.com>
11  - Mark Brown <broonie@kernel.org>
12
13properties:
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-active-discharge:
121    description: |
122      tristate, enable/disable active discharge of regulators. The values are:
123      0: Disable active discharge.
124      1: Enable active discharge.
125      Absence of this property will leave configuration to default.
126    allOf:
127      - $ref: "/schemas/types.yaml#/definitions/uint32"
128      - enum: [ 0, 1 ]
129
130  regulator-coupled-with:
131    description: Regulators with which the regulator is coupled. The linkage
132      is 2-way - all coupled regulators should be linked with each other.
133      A regulator should not be coupled with its supplier.
134    $ref: "/schemas/types.yaml#/definitions/phandle-array"
135
136  regulator-coupled-max-spread:
137    description: Array of maximum spread between voltages of coupled regulators
138      in microvolts, each value in the array relates to the corresponding
139      couple specified by the regulator-coupled-with property.
140    $ref: "/schemas/types.yaml#/definitions/uint32"
141
142  regulator-max-step-microvolt:
143    description: Maximum difference between current and target voltages
144      that can be changed safely in a single step.
145
146patternProperties:
147  ".*-supply$":
148    description: Input supply phandle(s) for this node
149
150  regulator-state-(standby|mem|disk):
151    type: object
152    description:
153      sub-nodes for regulator state in Standby, Suspend-to-RAM, and
154      Suspend-to-DISK modes. Equivalent with standby, mem, and disk Linux
155      sleep states.
156
157    properties:
158      regulator-on-in-suspend:
159        description: regulator should be on in suspend state.
160        type: boolean
161
162      regulator-off-in-suspend:
163        description: regulator should be off in suspend state.
164        type: boolean
165
166      regulator-suspend-min-microvolt:
167        description: minimum voltage may be set in suspend state.
168
169      regulator-suspend-max-microvolt:
170        description: maximum voltage may be set in suspend state.
171
172      regulator-suspend-microvolt:
173        description: the default voltage which regulator would be set in
174          suspend. This property is now deprecated, instead setting voltage
175          for suspend mode via the API which regulator driver provides is
176          recommended.
177
178      regulator-changeable-in-suspend:
179        description: whether the default voltage and the regulator on/off
180          in suspend can be changed in runtime.
181        type: boolean
182
183      regulator-mode:
184        description: operating mode in the given suspend state. The set
185          of possible operating modes depends on the capabilities of every
186          hardware so the valid modes are documented on each regulator device
187          tree binding document.
188        $ref: "/schemas/types.yaml#/definitions/uint32"
189
190    additionalProperties: false
191
192examples:
193  - |
194    xyzreg: regulator {
195      regulator-min-microvolt = <1000000>;
196      regulator-max-microvolt = <2500000>;
197      regulator-always-on;
198      vin-supply = <&vin>;
199
200      regulator-state-mem {
201        regulator-on-in-suspend;
202      };
203    };
204
205...
206