1 /* SPDX-License-Identifier: BSD-2-Clause */
2 /*
3 * Copyright (c) 2023, STMicroelectronics
4 */
5 #ifndef __DRIVERS_REGULATOR_H
6 #define __DRIVERS_REGULATOR_H
7
8 #include <assert.h>
9 #include <bitstring.h>
10 #include <kernel/mutex_pm_aware.h>
11 #include <sys/queue.h>
12 #include <tee_api_types.h>
13 #include <stdbool.h>
14 #include <stdint.h>
15 #include <util.h>
16
17 /* Regulator property flags: related to device tree binding properties */
18
19 /* Regulator should never be disabled. DT property: regulator-always-on */
20 #define REGULATOR_ALWAYS_ON BIT(0)
21 /* Enables pull down mode. DT property: regulator-pull-down */
22 #define REGULATOR_PULL_DOWN BIT(1)
23 /*
24 * It's expected that this regulator was left on by the bootloader.
25 * The core shouldn't prevent it from being turned off later.
26 * DT property: regulator-boot-on
27 */
28 #define REGULATOR_BOOT_ON BIT(2)
29 /*
30 * Enables over current protection.
31 * DT property: regulator-over-current-protection
32 */
33 #define REGULATOR_OVER_CURRENT BIT(3)
34
35 #define REGULATOR_FLAGS_MASK (REGULATOR_ALWAYS_ON | REGULATOR_PULL_DOWN | \
36 REGULATOR_BOOT_ON | REGULATOR_OVER_CURRENT)
37
38 struct regulator_ops;
39
40 /*
41 * struct regu_dt_desc - Regulator description passed to regulator_dt_register()
42 * @priv: Regulator driver private data
43 * @name: Regulator string name for debug purpose
44 * @supply_name: Regulator supply name for node property *-supply or NULL
45 * @ops: Operation handlers for the regulator
46 * @regulator: Pointer to preallocated regulator or NULL if none
47 */
48 struct regu_dt_desc {
49 void *priv;
50 const char *name;
51 const char *supply_name;
52 const struct regulator_ops *ops;
53 struct regulator *regulator;
54 };
55
56 /*
57 * Defines the format of struct voltages::entries
58 *
59 * If regulator_voltages::type is VOLTAGE_TYPE_FULL_LIST, then
60 * regulator_voltages@entries stores regulator_voltages::num_levels cells,
61 * listing supported voltage levels in uV from lowest to highest value.
62 *
63 * If regulator_voltages::type is VOLTAGE_TYPE_INCREMENT, then
64 * regulator_voltages::entries stores 3 cells: min level, max level and
65 * level increment step, all in uV. When so, regulator_voltages::num_levels
66 * is meaningless.
67 */
68 enum voltage_type {
69 VOLTAGE_TYPE_INVALID = 0,
70 VOLTAGE_TYPE_FULL_LIST, /* extensive list in uV */
71 VOLTAGE_TYPE_INCREMENT /* min, max, increment (in uV) */
72 };
73
74 /*
75 * struct regulator_voltages_desc - Voltage levels description
76 * @type: Type of level description
77 * @num_levels: Number of voltage levels when @type is VOLTAGE_TYPE_FULL_LIST
78 *
79 */
80 struct regulator_voltages_desc {
81 enum voltage_type type;
82 size_t num_levels;
83 };
84
85 /*
86 * struct regulator - A regulator instance
87 * @ops: Operation handlers for the regulator
88 * @supply: Regulator supply reference or NULL if none
89 * @priv: Regulator driver private data
90 * @name: Regulator string name for debug purpose or NULL
91 * @min_uv: Min possible voltage level in microvolt (uV)
92 * @max_uv: Max possible voltage level in microvolt (uV)
93 * @ramp_delay_uv_per_us: Voltage level change delay in uV/s
94 * @enable_ramp_delay_us: Delay after enable, in microseconds (us)
95 * @flags: REGULATOR_* property flags
96 * @refcount: Regulator enable request reference counter
97 * @mutex: Concurrent access protection considering PM context sequences
98 * @voltages_fallback: Default supported voltage range description
99 * @link: Link in initialized regulator list
100 */
101 struct regulator {
102 /* Fields initialized by caller of regulator_register() */
103 const struct regulator_ops *ops;
104 struct regulator *supply;
105 void *priv;
106 char *name;
107 int min_uv;
108 int max_uv;
109 unsigned int ramp_delay_uv_per_us;
110 unsigned int enable_ramp_delay_us;
111 /* Fields internal to regulator framework */
112 unsigned int flags;
113 unsigned int refcount;
114 struct mutex_pm_aware mutex;
115 struct voltages_fallback {
116 struct regulator_voltages_desc desc;
117 int levels[3];
118 } voltages_fallback;
119 size_t levels_count_fallback;
120 SLIST_ENTRY(regulator) link;
121 };
122
123 /*
124 * struct regulator_ops - Regulator operation handlers
125 *
126 * @set_state: Enable or disable a regulator
127 * @get_state: Get regulator effective state
128 * @set_voltage: Set voltage level in microvolt (uV)
129 * @get_voltage: Get current voltage in microvolt (uV)
130 * @supported_voltages: Get supported levels description
131 * @supplied_init: Optional, finalize initialization once supply is ready
132 */
133 struct regulator_ops {
134 TEE_Result (*set_state)(struct regulator *r, bool enabled);
135 TEE_Result (*get_state)(struct regulator *r, bool *enabled);
136 TEE_Result (*set_voltage)(struct regulator *r, int level_uv);
137 TEE_Result (*get_voltage)(struct regulator *r, int *level_uv);
138 TEE_Result (*supported_voltages)(struct regulator *r,
139 struct regulator_voltages_desc **desc,
140 const int **levels);
141 TEE_Result (*supplied_init)(struct regulator *r, const void *fdt,
142 int node);
143 };
144
145 #ifdef CFG_DRIVERS_REGULATOR
146 /*
147 * regulator_enable() - Enable regulator
148 * @regulator: Regulator reference
149 */
150 TEE_Result regulator_enable(struct regulator *regulator);
151
152 /*
153 * regulator_disable() - Disable regulator
154 * @regulator: Regulator reference
155 */
156 TEE_Result regulator_disable(struct regulator *regulator);
157
158 /*
159 * regulator_is_enabled() - Return whether or not regulator is currently enabled
160 * despite its refcount value.
161 * @regulator: Regulator reference
162 */
163 bool regulator_is_enabled(struct regulator *regulator);
164
165 /*
166 * regulator_set_voltage() - Set regulator to target level in microvolt
167 * @regulator: Regulator reference
168 * @level_uv: Level in microvolt
169 */
170 TEE_Result regulator_set_voltage(struct regulator *regulator, int level_uv);
171
172 /*
173 * regulator_register() - Register and initialize a regulator
174 * @regulator: Regulator reference
175 */
176 TEE_Result regulator_register(struct regulator *regulator);
177
178 /* Print registered regulators and their state to the output console */
179 void regulator_print_state(const char *message);
180 #else
regulator_enable(struct regulator * regulator __unused)181 static inline TEE_Result regulator_enable(struct regulator *regulator __unused)
182 {
183 return TEE_ERROR_NOT_SUPPORTED;
184 }
185
regulator_disable(struct regulator * regulator __unused)186 static inline TEE_Result regulator_disable(struct regulator *regulator __unused)
187 {
188 return TEE_ERROR_NOT_SUPPORTED;
189 }
190
regulator_is_enabled(struct regulator * regulator __unused)191 static inline bool regulator_is_enabled(struct regulator *regulator __unused)
192 {
193 return false;
194 }
195
regulator_set_voltage(struct regulator * regul __unused,int level_mv __unused)196 static inline TEE_Result regulator_set_voltage(struct regulator *regul __unused,
197 int level_mv __unused)
198 {
199 return TEE_ERROR_NOT_SUPPORTED;
200 }
201
regulator_init(struct regulator * regulator __unused)202 static inline TEE_Result regulator_init(struct regulator *regulator __unused)
203 {
204 return TEE_ERROR_NOT_SUPPORTED;
205 }
206
regulator_print_state(const char * message __unused)207 static inline void regulator_print_state(const char *message __unused)
208 {
209 }
210 #endif /*CFG_DRIVERS_REGULATOR*/
211
212 #if defined(CFG_DRIVERS_REGULATOR) && defined(CFG_DT)
213 /*
214 * regulator_dt_get_supply() - Get a regulator supply from name and DT node
215 * @fdt: FDT to work on
216 * @node: DT node of the regulator consumer
217 * @supply_name: Name of the supply in DT property xxx-supply
218 * @regulator: Output regulator upon success
219 *
220 * Upon success, this function provides the pointer to regulator
221 * defined by DT binding property @name-supply phandle reference.
222 *
223 * This function returns TEE_ERROR_DEFER_DRIVER_INIT if supply exists but is
224 * not yet initialized.
225 */
226 TEE_Result regulator_dt_get_supply(const void *fdt, int node,
227 const char *supply_name,
228 struct regulator **regulator);
229
230 /*
231 * regulator_dt_register() - Register a regulator to related to a DT node
232 * @fdt: FDT to work on
233 * @node: DT node of the regulator exposed by regulator driver
234 * @provider_node: Node where xxx-supply property is found or -1 if no supply.
235 * @desc: Description of the regulator to register
236 *
237 * This function registers and initializes a regulator instance once its supply
238 * if found, if any. Regulators registered with this function can be found by
239 * their consumer drivers using API function regulator_dt_get_supply() or like.
240 *
241 * Return TEE_SUCCESS in case of success
242 * Return TEE_ERROR_OUT_OF_MEMORY if failed on memory allocation
243 * Return any other TEE_Result compliant code in case of error
244 */
245 TEE_Result regulator_dt_register(const void *fdt, int node, int provider_node,
246 const struct regu_dt_desc *desc);
247 #else
regulator_dt_get_supply(const void * fdt __unused,int node __unused,const char * supply __unused,struct regulator ** r __unused)248 static inline TEE_Result regulator_dt_get_supply(const void *fdt __unused,
249 int node __unused,
250 const char *supply __unused,
251 struct regulator **r __unused)
252 {
253 return TEE_ERROR_NOT_SUPPORTED;
254 }
255
256 static inline TEE_Result
regulator_dt_register(const void * fdt __unused,int node __unused,int provider_node __unused,const struct regu_dt_desc * d __unused)257 regulator_dt_register(const void *fdt __unused, int node __unused,
258 int provider_node __unused,
259 const struct regu_dt_desc *d __unused)
260 {
261 return TEE_ERROR_NOT_SUPPORTED;
262 }
263 #endif /* CFG_DRIVERS_REGULATOR && CFG_DT */
264
265 /*
266 * regulator_name() - Return regulator name or NULL
267 * @regulator: Regulator reference
268 */
regulator_name(struct regulator * regulator)269 static inline const char *regulator_name(struct regulator *regulator)
270 {
271 return regulator->name;
272 }
273
274 /*
275 * regulator_is_always_on() - Return the state of REGULATOR_ALWAYS_ON flag
276 * @regulator: Regulator reference
277 */
regulator_is_always_on(struct regulator * regulator)278 static inline bool regulator_is_always_on(struct regulator *regulator)
279 {
280 return regulator->flags & REGULATOR_ALWAYS_ON;
281 }
282
283 /*
284 * regulator_set_min_voltage() - Set regulator to its min level
285 * @regulator: Regulator reference
286 */
regulator_set_min_voltage(struct regulator * regulator)287 static inline TEE_Result regulator_set_min_voltage(struct regulator *regulator)
288 {
289 return regulator_set_voltage(regulator, regulator->min_uv);
290 }
291
292 /*
293 * regulator_get_voltage() - Get regulator effective voltage level in microvolt
294 * @regulator: Regulator reference
295 */
296 int regulator_get_voltage(struct regulator *regulator);
297
298 /*
299 * regulator_get_range() - Get regulator min and/or max support levels
300 * @regulator: Regulator reference
301 * @min_mv: Output reference to min level in microvolt (uV) or NULL
302 * @max_mv: Output reference to max level in microvolt (uV) or NULL
303 */
regulator_get_range(struct regulator * regulator,int * min_uv,int * max_uv)304 static inline void regulator_get_range(struct regulator *regulator, int *min_uv,
305 int *max_uv)
306 {
307 assert(regulator);
308 if (min_uv)
309 *min_uv = regulator->min_uv;
310 if (max_uv)
311 *max_uv = regulator->max_uv;
312 }
313
314 /*
315 * regulator_supported_voltages() - Get regulator supported levels in microvolt
316 * @regulator: Regulator reference
317 * @desc: Output reference to supported voltage levels description
318 * @levels: Output reference to voltage level array, in microvolts
319 *
320 * When @desc->type is VOLTAGE_TYPE_FULL_LIST, number of cells of @*levels
321 * is defined by @desc->num_levels, each cell being a level in microvolts (uV).
322 * When @desc->type is VOLTAGE_TYPE_INCREMENT, @levels has 3 cells:
323 * @levels[0] is the min voltage level, @levels[1] is the max level, @levels[2]
324 * is the incremental level step, all in microvolts (uV).
325 */
326 TEE_Result regulator_supported_voltages(struct regulator *regulator,
327 struct regulator_voltages_desc **desc,
328 const int **levels);
329
330 /* Print current regulator tree summary to console with info trace level */
331 #ifdef CFG_DRIVERS_REGULATOR
332 void regulator_print_tree(void);
333 #else
regulator_print_tree(void)334 static inline void regulator_print_tree(void)
335 {
336 }
337 #endif /* CFG_DRIVERS_REGULATOR */
338 #endif /* __DRIVERS_REGULATOR_H */
339