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