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-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
227patternProperties:
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
273additionalProperties: true
274
275examples:
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...
289