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 181 static inline TEE_Result regulator_enable(struct regulator *regulator __unused) 182 { 183 return TEE_ERROR_NOT_SUPPORTED; 184 } 185 186 static inline TEE_Result regulator_disable(struct regulator *regulator __unused) 187 { 188 return TEE_ERROR_NOT_SUPPORTED; 189 } 190 191 static inline bool regulator_is_enabled(struct regulator *regulator __unused) 192 { 193 return false; 194 } 195 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 202 static inline TEE_Result regulator_init(struct regulator *regulator __unused) 203 { 204 return TEE_ERROR_NOT_SUPPORTED; 205 } 206 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 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 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 */ 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 */ 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 */ 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 */ 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 334 static inline void regulator_print_tree(void) 335 { 336 } 337 #endif /* CFG_DRIVERS_REGULATOR */ 338 #endif /* __DRIVERS_REGULATOR_H */ 339