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