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    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
229patternProperties:
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
275additionalProperties: true
276
277examples:
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...
291