1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
2 | /* |
3 | * machine.h -- SoC Regulator support, machine/board driver API. |
4 | * |
5 | * Copyright (C) 2007, 2008 Wolfson Microelectronics PLC. |
6 | * |
7 | * Author: Liam Girdwood <lrg@slimlogic.co.uk> |
8 | * |
9 | * Regulator Machine/Board Interface. |
10 | */ |
11 | |
12 | #ifndef __LINUX_REGULATOR_MACHINE_H_ |
13 | #define __LINUX_REGULATOR_MACHINE_H_ |
14 | |
15 | #include <linux/regulator/consumer.h> |
16 | #include <linux/suspend.h> |
17 | |
18 | struct regulator; |
19 | |
20 | /* |
21 | * Regulator operation constraint flags. These flags are used to enable |
22 | * certain regulator operations and can be OR'ed together. |
23 | * |
24 | * VOLTAGE: Regulator output voltage can be changed by software on this |
25 | * board/machine. |
26 | * CURRENT: Regulator output current can be changed by software on this |
27 | * board/machine. |
28 | * MODE: Regulator operating mode can be changed by software on this |
29 | * board/machine. |
30 | * STATUS: Regulator can be enabled and disabled. |
31 | * DRMS: Dynamic Regulator Mode Switching is enabled for this regulator. |
32 | * BYPASS: Regulator can be put into bypass mode |
33 | */ |
34 | |
35 | #define REGULATOR_CHANGE_VOLTAGE 0x1 |
36 | #define REGULATOR_CHANGE_CURRENT 0x2 |
37 | #define REGULATOR_CHANGE_MODE 0x4 |
38 | #define REGULATOR_CHANGE_STATUS 0x8 |
39 | #define REGULATOR_CHANGE_DRMS 0x10 |
40 | #define REGULATOR_CHANGE_BYPASS 0x20 |
41 | |
42 | /* |
43 | * operations in suspend mode |
44 | * DO_NOTHING_IN_SUSPEND - the default value |
45 | * DISABLE_IN_SUSPEND - turn off regulator in suspend states |
46 | * ENABLE_IN_SUSPEND - keep regulator on in suspend states |
47 | */ |
48 | #define DO_NOTHING_IN_SUSPEND 0 |
49 | #define DISABLE_IN_SUSPEND 1 |
50 | #define ENABLE_IN_SUSPEND 2 |
51 | |
52 | /* |
53 | * Default time window (in milliseconds) following a critical under-voltage |
54 | * event during which less critical actions can be safely carried out by the |
55 | * system. |
56 | */ |
57 | #define REGULATOR_DEF_UV_LESS_CRITICAL_WINDOW_MS 10 |
58 | |
59 | /* Regulator active discharge flags */ |
60 | enum regulator_active_discharge { |
61 | REGULATOR_ACTIVE_DISCHARGE_DEFAULT, |
62 | REGULATOR_ACTIVE_DISCHARGE_DISABLE, |
63 | REGULATOR_ACTIVE_DISCHARGE_ENABLE, |
64 | }; |
65 | |
66 | /** |
67 | * struct regulator_state - regulator state during low power system states |
68 | * |
69 | * This describes a regulators state during a system wide low power |
70 | * state. One of enabled or disabled must be set for the |
71 | * configuration to be applied. |
72 | * |
73 | * @uV: Default operating voltage during suspend, it can be adjusted |
74 | * among <min_uV, max_uV>. |
75 | * @min_uV: Minimum suspend voltage may be set. |
76 | * @max_uV: Maximum suspend voltage may be set. |
77 | * @mode: Operating mode during suspend. |
78 | * @enabled: operations during suspend. |
79 | * - DO_NOTHING_IN_SUSPEND |
80 | * - DISABLE_IN_SUSPEND |
81 | * - ENABLE_IN_SUSPEND |
82 | * @changeable: Is this state can be switched between enabled/disabled, |
83 | */ |
84 | struct regulator_state { |
85 | int uV; |
86 | int min_uV; |
87 | int max_uV; |
88 | unsigned int mode; |
89 | int enabled; |
90 | bool changeable; |
91 | }; |
92 | |
93 | #define REGULATOR_NOTIF_LIMIT_DISABLE -1 |
94 | #define REGULATOR_NOTIF_LIMIT_ENABLE -2 |
95 | struct notification_limit { |
96 | int prot; |
97 | int err; |
98 | int warn; |
99 | }; |
100 | |
101 | /** |
102 | * struct regulation_constraints - regulator operating constraints. |
103 | * |
104 | * This struct describes regulator and board/machine specific constraints. |
105 | * |
106 | * @name: Descriptive name for the constraints, used for display purposes. |
107 | * |
108 | * @min_uV: Smallest voltage consumers may set. |
109 | * @max_uV: Largest voltage consumers may set. |
110 | * @uV_offset: Offset applied to voltages from consumer to compensate for |
111 | * voltage drops. |
112 | * |
113 | * @min_uA: Smallest current consumers may set. |
114 | * @max_uA: Largest current consumers may set. |
115 | * @ilim_uA: Maximum input current. |
116 | * @system_load: Load that isn't captured by any consumer requests. |
117 | * |
118 | * @over_curr_limits: Limits for acting on over current. |
119 | * @over_voltage_limits: Limits for acting on over voltage. |
120 | * @under_voltage_limits: Limits for acting on under voltage. |
121 | * @temp_limits: Limits for acting on over temperature. |
122 | * |
123 | * @max_spread: Max possible spread between coupled regulators |
124 | * @max_uV_step: Max possible step change in voltage |
125 | * @valid_modes_mask: Mask of modes which may be configured by consumers. |
126 | * @valid_ops_mask: Operations which may be performed by consumers. |
127 | * |
128 | * @always_on: Set if the regulator should never be disabled. |
129 | * @boot_on: Set if the regulator is enabled when the system is initially |
130 | * started. If the regulator is not enabled by the hardware or |
131 | * bootloader then it will be enabled when the constraints are |
132 | * applied. |
133 | * @apply_uV: Apply the voltage constraint when initialising. |
134 | * @ramp_disable: Disable ramp delay when initialising or when setting voltage. |
135 | * @soft_start: Enable soft start so that voltage ramps slowly. |
136 | * @pull_down: Enable pull down when regulator is disabled. |
137 | * @system_critical: Set if the regulator is critical to system stability or |
138 | * functionality. |
139 | * @over_current_protection: Auto disable on over current event. |
140 | * |
141 | * @over_current_detection: Configure over current limits. |
142 | * @over_voltage_detection: Configure over voltage limits. |
143 | * @under_voltage_detection: Configure under voltage limits. |
144 | * @over_temp_detection: Configure over temperature limits. |
145 | * |
146 | * @input_uV: Input voltage for regulator when supplied by another regulator. |
147 | * |
148 | * @state_disk: State for regulator when system is suspended in disk mode. |
149 | * @state_mem: State for regulator when system is suspended in mem mode. |
150 | * @state_standby: State for regulator when system is suspended in standby |
151 | * mode. |
152 | * @initial_state: Suspend state to set by default. |
153 | * @initial_mode: Mode to set at startup. |
154 | * @ramp_delay: Time to settle down after voltage change (unit: uV/us) |
155 | * @settling_time: Time to settle down after voltage change when voltage |
156 | * change is non-linear (unit: microseconds). |
157 | * @settling_time_up: Time to settle down after voltage increase when voltage |
158 | * change is non-linear (unit: microseconds). |
159 | * @settling_time_down : Time to settle down after voltage decrease when |
160 | * voltage change is non-linear (unit: microseconds). |
161 | * @active_discharge: Enable/disable active discharge. The enum |
162 | * regulator_active_discharge values are used for |
163 | * initialisation. |
164 | * @enable_time: Turn-on time of the rails (unit: microseconds) |
165 | * @uv_less_critical_window_ms: Specifies the time window (in milliseconds) |
166 | * following a critical under-voltage (UV) event |
167 | * during which less critical actions can be |
168 | * safely carried out by the system (for example |
169 | * logging). After this time window more critical |
170 | * actions should be done (for example prevent |
171 | * HW damage). |
172 | */ |
173 | struct regulation_constraints { |
174 | |
175 | const char *name; |
176 | |
177 | /* voltage output range (inclusive) - for voltage control */ |
178 | int min_uV; |
179 | int max_uV; |
180 | |
181 | int uV_offset; |
182 | |
183 | /* current output range (inclusive) - for current control */ |
184 | int min_uA; |
185 | int max_uA; |
186 | int ilim_uA; |
187 | |
188 | int system_load; |
189 | |
190 | /* used for coupled regulators */ |
191 | u32 *max_spread; |
192 | |
193 | /* used for changing voltage in steps */ |
194 | int max_uV_step; |
195 | |
196 | /* valid regulator operating modes for this machine */ |
197 | unsigned int valid_modes_mask; |
198 | |
199 | /* valid operations for regulator on this machine */ |
200 | unsigned int valid_ops_mask; |
201 | |
202 | /* regulator input voltage - only if supply is another regulator */ |
203 | int input_uV; |
204 | |
205 | /* regulator suspend states for global PMIC STANDBY/HIBERNATE */ |
206 | struct regulator_state state_disk; |
207 | struct regulator_state state_mem; |
208 | struct regulator_state state_standby; |
209 | struct notification_limit over_curr_limits; |
210 | struct notification_limit over_voltage_limits; |
211 | struct notification_limit under_voltage_limits; |
212 | struct notification_limit temp_limits; |
213 | suspend_state_t initial_state; /* suspend state to set at init */ |
214 | |
215 | /* mode to set on startup */ |
216 | unsigned int initial_mode; |
217 | |
218 | unsigned int ramp_delay; |
219 | unsigned int settling_time; |
220 | unsigned int settling_time_up; |
221 | unsigned int settling_time_down; |
222 | unsigned int enable_time; |
223 | unsigned int uv_less_critical_window_ms; |
224 | |
225 | unsigned int active_discharge; |
226 | |
227 | /* constraint flags */ |
228 | unsigned always_on:1; /* regulator never off when system is on */ |
229 | unsigned boot_on:1; /* bootloader/firmware enabled regulator */ |
230 | unsigned apply_uV:1; /* apply uV constraint if min == max */ |
231 | unsigned ramp_disable:1; /* disable ramp delay */ |
232 | unsigned soft_start:1; /* ramp voltage slowly */ |
233 | unsigned pull_down:1; /* pull down resistor when regulator off */ |
234 | unsigned system_critical:1; /* critical to system stability */ |
235 | unsigned over_current_protection:1; /* auto disable on over current */ |
236 | unsigned over_current_detection:1; /* notify on over current */ |
237 | unsigned over_voltage_detection:1; /* notify on over voltage */ |
238 | unsigned under_voltage_detection:1; /* notify on under voltage */ |
239 | unsigned over_temp_detection:1; /* notify on over temperature */ |
240 | }; |
241 | |
242 | /** |
243 | * struct regulator_consumer_supply - supply -> device mapping |
244 | * |
245 | * This maps a supply name to a device. Use of dev_name allows support for |
246 | * buses which make struct device available late such as I2C. |
247 | * |
248 | * @dev_name: Result of dev_name() for the consumer. |
249 | * @supply: Name for the supply. |
250 | */ |
251 | struct regulator_consumer_supply { |
252 | const char *dev_name; /* dev_name() for consumer */ |
253 | const char *supply; /* consumer supply - e.g. "vcc" */ |
254 | }; |
255 | |
256 | /* Initialize struct regulator_consumer_supply */ |
257 | #define REGULATOR_SUPPLY(_name, _dev_name) \ |
258 | { \ |
259 | .supply = _name, \ |
260 | .dev_name = _dev_name, \ |
261 | } |
262 | |
263 | /** |
264 | * struct regulator_init_data - regulator platform initialisation data. |
265 | * |
266 | * Initialisation constraints, our supply and consumers supplies. |
267 | * |
268 | * @supply_regulator: Parent regulator. Specified using the regulator name |
269 | * as it appears in the name field in sysfs, which can |
270 | * be explicitly set using the constraints field 'name'. |
271 | * |
272 | * @constraints: Constraints. These must be specified for the regulator to |
273 | * be usable. |
274 | * @num_consumer_supplies: Number of consumer device supplies. |
275 | * @consumer_supplies: Consumer device supply configuration. |
276 | * |
277 | * @regulator_init: Callback invoked when the regulator has been registered. |
278 | * @driver_data: Data passed to regulator_init. |
279 | */ |
280 | struct regulator_init_data { |
281 | const char *supply_regulator; /* or NULL for system supply */ |
282 | |
283 | struct regulation_constraints constraints; |
284 | |
285 | int num_consumer_supplies; |
286 | struct regulator_consumer_supply *consumer_supplies; |
287 | |
288 | /* optional regulator machine specific init */ |
289 | int (*regulator_init)(void *driver_data); |
290 | void *driver_data; /* core does not touch this */ |
291 | }; |
292 | |
293 | #ifdef CONFIG_REGULATOR |
294 | void regulator_has_full_constraints(void); |
295 | #else |
296 | static inline void regulator_has_full_constraints(void) |
297 | { |
298 | } |
299 | #endif |
300 | |
301 | static inline int regulator_suspend_prepare(suspend_state_t state) |
302 | { |
303 | return 0; |
304 | } |
305 | static inline int regulator_suspend_finish(void) |
306 | { |
307 | return 0; |
308 | } |
309 | |
310 | #endif |
311 | |