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 /* Regulator active discharge flags */
53 enum regulator_active_discharge {
54 	REGULATOR_ACTIVE_DISCHARGE_DEFAULT,
55 	REGULATOR_ACTIVE_DISCHARGE_DISABLE,
56 	REGULATOR_ACTIVE_DISCHARGE_ENABLE,
57 };
58 
59 /**
60  * struct regulator_state - regulator state during low power system states
61  *
62  * This describes a regulators state during a system wide low power
63  * state.  One of enabled or disabled must be set for the
64  * configuration to be applied.
65  *
66  * @uV: Default operating voltage during suspend, it can be adjusted
67  *	among <min_uV, max_uV>.
68  * @min_uV: Minimum suspend voltage may be set.
69  * @max_uV: Maximum suspend voltage may be set.
70  * @mode: Operating mode during suspend.
71  * @enabled: operations during suspend.
72  *	     - DO_NOTHING_IN_SUSPEND
73  *	     - DISABLE_IN_SUSPEND
74  *	     - ENABLE_IN_SUSPEND
75  * @changeable: Is this state can be switched between enabled/disabled,
76  */
77 struct regulator_state {
78 	int uV;
79 	int min_uV;
80 	int max_uV;
81 	unsigned int mode;
82 	int enabled;
83 	bool changeable;
84 };
85 
86 #define REGULATOR_NOTIF_LIMIT_DISABLE -1
87 #define REGULATOR_NOTIF_LIMIT_ENABLE -2
88 struct notification_limit {
89 	int prot;
90 	int err;
91 	int warn;
92 };
93 
94 /**
95  * struct regulation_constraints - regulator operating constraints.
96  *
97  * This struct describes regulator and board/machine specific constraints.
98  *
99  * @name: Descriptive name for the constraints, used for display purposes.
100  *
101  * @min_uV: Smallest voltage consumers may set.
102  * @max_uV: Largest voltage consumers may set.
103  * @uV_offset: Offset applied to voltages from consumer to compensate for
104  *             voltage drops.
105  *
106  * @min_uA: Smallest current consumers may set.
107  * @max_uA: Largest current consumers may set.
108  * @ilim_uA: Maximum input current.
109  * @system_load: Load that isn't captured by any consumer requests.
110  *
111  * @over_curr_limits:		Limits for acting on over current.
112  * @over_voltage_limits:	Limits for acting on over voltage.
113  * @under_voltage_limits:	Limits for acting on under voltage.
114  * @temp_limits:		Limits for acting on over temperature.
115  *
116  * @max_spread: Max possible spread between coupled regulators
117  * @max_uV_step: Max possible step change in voltage
118  * @valid_modes_mask: Mask of modes which may be configured by consumers.
119  * @valid_ops_mask: Operations which may be performed by consumers.
120  *
121  * @always_on: Set if the regulator should never be disabled.
122  * @boot_on: Set if the regulator is enabled when the system is initially
123  *           started.  If the regulator is not enabled by the hardware or
124  *           bootloader then it will be enabled when the constraints are
125  *           applied.
126  * @apply_uV: Apply the voltage constraint when initialising.
127  * @ramp_disable: Disable ramp delay when initialising or when setting voltage.
128  * @soft_start: Enable soft start so that voltage ramps slowly.
129  * @pull_down: Enable pull down when regulator is disabled.
130  * @over_current_protection: Auto disable on over current event.
131  *
132  * @over_current_detection: Configure over current limits.
133  * @over_voltage_detection: Configure over voltage limits.
134  * @under_voltage_detection: Configure under voltage limits.
135  * @over_temp_detection: Configure over temperature limits.
136  *
137  * @input_uV: Input voltage for regulator when supplied by another regulator.
138  *
139  * @state_disk: State for regulator when system is suspended in disk mode.
140  * @state_mem: State for regulator when system is suspended in mem mode.
141  * @state_standby: State for regulator when system is suspended in standby
142  *                 mode.
143  * @initial_state: Suspend state to set by default.
144  * @initial_mode: Mode to set at startup.
145  * @ramp_delay: Time to settle down after voltage change (unit: uV/us)
146  * @settling_time: Time to settle down after voltage change when voltage
147  *		   change is non-linear (unit: microseconds).
148  * @settling_time_up: Time to settle down after voltage increase when voltage
149  *		      change is non-linear (unit: microseconds).
150  * @settling_time_down : Time to settle down after voltage decrease when
151  *			 voltage change is non-linear (unit: microseconds).
152  * @active_discharge: Enable/disable active discharge. The enum
153  *		      regulator_active_discharge values are used for
154  *		      initialisation.
155  * @enable_time: Turn-on time of the rails (unit: microseconds)
156  */
157 struct regulation_constraints {
158 
159 	const char *name;
160 
161 	/* voltage output range (inclusive) - for voltage control */
162 	int min_uV;
163 	int max_uV;
164 
165 	int uV_offset;
166 
167 	/* current output range (inclusive) - for current control */
168 	int min_uA;
169 	int max_uA;
170 	int ilim_uA;
171 
172 	int system_load;
173 
174 	/* used for coupled regulators */
175 	u32 *max_spread;
176 
177 	/* used for changing voltage in steps */
178 	int max_uV_step;
179 
180 	/* valid regulator operating modes for this machine */
181 	unsigned int valid_modes_mask;
182 
183 	/* valid operations for regulator on this machine */
184 	unsigned int valid_ops_mask;
185 
186 	/* regulator input voltage - only if supply is another regulator */
187 	int input_uV;
188 
189 	/* regulator suspend states for global PMIC STANDBY/HIBERNATE */
190 	struct regulator_state state_disk;
191 	struct regulator_state state_mem;
192 	struct regulator_state state_standby;
193 	struct notification_limit over_curr_limits;
194 	struct notification_limit over_voltage_limits;
195 	struct notification_limit under_voltage_limits;
196 	struct notification_limit temp_limits;
197 	suspend_state_t initial_state; /* suspend state to set at init */
198 
199 	/* mode to set on startup */
200 	unsigned int initial_mode;
201 
202 	unsigned int ramp_delay;
203 	unsigned int settling_time;
204 	unsigned int settling_time_up;
205 	unsigned int settling_time_down;
206 	unsigned int enable_time;
207 
208 	unsigned int active_discharge;
209 
210 	/* constraint flags */
211 	unsigned always_on:1;	/* regulator never off when system is on */
212 	unsigned boot_on:1;	/* bootloader/firmware enabled regulator */
213 	unsigned apply_uV:1;	/* apply uV constraint if min == max */
214 	unsigned ramp_disable:1; /* disable ramp delay */
215 	unsigned soft_start:1;	/* ramp voltage slowly */
216 	unsigned pull_down:1;	/* pull down resistor when regulator off */
217 	unsigned over_current_protection:1; /* auto disable on over current */
218 	unsigned over_current_detection:1; /* notify on over current */
219 	unsigned over_voltage_detection:1; /* notify on over voltage */
220 	unsigned under_voltage_detection:1; /* notify on under voltage */
221 	unsigned over_temp_detection:1; /* notify on over temperature */
222 };
223 
224 /**
225  * struct regulator_consumer_supply - supply -> device mapping
226  *
227  * This maps a supply name to a device. Use of dev_name allows support for
228  * buses which make struct device available late such as I2C.
229  *
230  * @dev_name: Result of dev_name() for the consumer.
231  * @supply: Name for the supply.
232  */
233 struct regulator_consumer_supply {
234 	const char *dev_name;   /* dev_name() for consumer */
235 	const char *supply;	/* consumer supply - e.g. "vcc" */
236 };
237 
238 /* Initialize struct regulator_consumer_supply */
239 #define REGULATOR_SUPPLY(_name, _dev_name)			\
240 {								\
241 	.supply		= _name,				\
242 	.dev_name	= _dev_name,				\
243 }
244 
245 /**
246  * struct regulator_init_data - regulator platform initialisation data.
247  *
248  * Initialisation constraints, our supply and consumers supplies.
249  *
250  * @supply_regulator: Parent regulator.  Specified using the regulator name
251  *                    as it appears in the name field in sysfs, which can
252  *                    be explicitly set using the constraints field 'name'.
253  *
254  * @constraints: Constraints.  These must be specified for the regulator to
255  *               be usable.
256  * @num_consumer_supplies: Number of consumer device supplies.
257  * @consumer_supplies: Consumer device supply configuration.
258  *
259  * @regulator_init: Callback invoked when the regulator has been registered.
260  * @driver_data: Data passed to regulator_init.
261  */
262 struct regulator_init_data {
263 	const char *supply_regulator;        /* or NULL for system supply */
264 
265 	struct regulation_constraints constraints;
266 
267 	int num_consumer_supplies;
268 	struct regulator_consumer_supply *consumer_supplies;
269 
270 	/* optional regulator machine specific init */
271 	int (*regulator_init)(void *driver_data);
272 	void *driver_data;	/* core does not touch this */
273 };
274 
275 #ifdef CONFIG_REGULATOR
276 void regulator_has_full_constraints(void);
277 #else
regulator_has_full_constraints(void)278 static inline void regulator_has_full_constraints(void)
279 {
280 }
281 #endif
282 
regulator_suspend_prepare(suspend_state_t state)283 static inline int regulator_suspend_prepare(suspend_state_t state)
284 {
285 	return 0;
286 }
regulator_suspend_finish(void)287 static inline int regulator_suspend_finish(void)
288 {
289 	return 0;
290 }
291 
292 #endif
293