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.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 22 #define REGULATOR_FLAGS_MASK REGULATOR_ALWAYS_ON 23 24 struct regulator_ops; 25 26 /* 27 * struct regu_dt_desc - Regulator description passed to regulator_dt_register() 28 * @priv: Regulator driver private data 29 * @name: Regulator string name for debug purpose 30 * @supply_name: Regulator supply name for node property *-supply or NULL 31 * @ops: Operation handlers for the regulator 32 * @regulator: Pointer to preallocated regulator or NULL if none 33 */ 34 struct regu_dt_desc { 35 void *priv; 36 char *name; 37 const char *supply_name; 38 const struct regulator_ops *ops; 39 struct regulator *regulator; 40 }; 41 42 /* 43 * Defines the format of struct voltages::entries 44 * 45 * If regulator_voltages::type is VOLTAGE_TYPE_FULL_LIST, then 46 * regulator_voltages@entries stores regulator_voltages::num_levels cells, 47 * listing supported voltage levels in uV from lowest to highest value. 48 * 49 * If regulator_voltages::type is VOLTAGE_TYPE_INCREMENT, then 50 * regulator_voltages::entries stores 3 cells: min level, max level and 51 * level increment step, all in uV. When so, regulator_voltages::num_levels 52 * is meaningless. 53 */ 54 enum voltage_type { 55 VOLTAGE_TYPE_INVALID = 0, 56 VOLTAGE_TYPE_FULL_LIST, /* extensive list in uV */ 57 VOLTAGE_TYPE_INCREMENT /* min, max, increment (in uV) */ 58 }; 59 60 /* 61 * struct regulator_voltages - Voltage levels description 62 * @type: Type of level description 63 * @num_levels: Number of cells of @entries when @type is VOLTAGE_TYPE_FULL_LIST 64 * @entries: Voltage level information in uV 65 * 66 */ 67 struct regulator_voltages { 68 enum voltage_type type; 69 size_t num_levels; 70 int entries[]; 71 }; 72 73 /* 74 * struct regulator - A regulator instance 75 * @ops: Operation handlers for the regulator 76 * @supply: Regulator supply reference or NULL if none 77 * @priv: Regulator driver private data 78 * @name: Regulator string name for debug purpose or NULL 79 * @min_uv: Min possible voltage level in microvolt (uV) 80 * @max_uv: Max possible voltage level in microvolt (uV) 81 * @cur_uv: Current voltage level in microvolt (uV) 82 * @flags: REGULATOR_* property flags 83 * @refcount: Regulator enable request reference counter 84 * @lock: Mutex for concurrent access protection 85 * @voltages_fallback: Default supported voltage range description 86 * @link: Link in initialized regulator list 87 */ 88 struct regulator { 89 /* Fields initialized by caller of regulator_register() */ 90 const struct regulator_ops *ops; 91 struct regulator *supply; 92 void *priv; 93 char *name; 94 int min_uv; 95 int max_uv; 96 /* Fields internal to regulator framework */ 97 int cur_uv; 98 unsigned int flags; 99 unsigned int refcount; 100 struct mutex lock; /* Concurrent access protection */ 101 struct voltages_fallback { 102 struct regulator_voltages desc; 103 int levels[3]; 104 } voltages_fallback; 105 size_t levels_count_fallback; 106 SLIST_ENTRY(regulator) link; 107 }; 108 109 /* 110 * struct regulator_ops - Regulator operation handlers 111 * 112 * @set_state: Enable or disable a regulator 113 * @get_state: Get regulator effective state 114 * @set_voltage: Set voltage level in microvolt (uV) 115 * @get_voltage: Get current voltage in microvolt (uV) 116 * @supported_voltages: Get supported levels description 117 * @supplied_init: Optional, finalize initialization once supply is ready 118 */ 119 struct regulator_ops { 120 TEE_Result (*set_state)(struct regulator *r, bool enabled); 121 TEE_Result (*get_state)(struct regulator *r, bool *enabled); 122 TEE_Result (*set_voltage)(struct regulator *r, int level_uv); 123 TEE_Result (*get_voltage)(struct regulator *r, int *level_uv); 124 TEE_Result (*supported_voltages)(struct regulator *r, 125 struct regulator_voltages **voltages); 126 TEE_Result (*supplied_init)(struct regulator *r, const void *fdt, 127 int node); 128 }; 129 130 #ifdef CFG_DRIVERS_REGULATOR 131 /* 132 * regulator_enable() - Enable regulator 133 * @regulator: Regulator reference 134 */ 135 TEE_Result regulator_enable(struct regulator *regulator); 136 137 /* 138 * regulator_disable() - Disable regulator 139 * @regulator: Regulator reference 140 */ 141 TEE_Result regulator_disable(struct regulator *regulator); 142 143 /* 144 * regulator_is_enabled() - Return whether or not regulator is currently enabled 145 * despite its refcount value. 146 * @regulator: Regulator reference 147 */ 148 bool regulator_is_enabled(struct regulator *regulator); 149 150 /* 151 * regulator_set_voltage() - Set regulator to target level in microvolt 152 * @regulator: Regulator reference 153 * @level_uv: Level in microvolt 154 */ 155 TEE_Result regulator_set_voltage(struct regulator *regulator, int level_uv); 156 157 /* 158 * regulator_register() - Register and initialize a regulator 159 * @regulator: Regulator reference 160 */ 161 TEE_Result regulator_register(struct regulator *regulator); 162 163 /* Print registered regulators and their state to the output console */ 164 void regulator_print_state(const char *message); 165 #else 166 static inline TEE_Result regulator_enable(struct regulator *regulator __unused) 167 { 168 return TEE_ERROR_NOT_SUPPORTED; 169 } 170 171 static inline TEE_Result regulator_disable(struct regulator *regulator __unused) 172 { 173 return TEE_ERROR_NOT_SUPPORTED; 174 } 175 176 static inline bool regulator_is_enabled(struct regulator *regulator __unused) 177 { 178 return false; 179 } 180 181 static inline TEE_Result regulator_set_voltage(struct regulator *regul __unused, 182 int level_mv __unused) 183 { 184 return TEE_ERROR_NOT_SUPPORTED; 185 } 186 187 static inline TEE_Result regulator_init(struct regulator *regulator __unused) 188 { 189 return TEE_ERROR_NOT_SUPPORTED; 190 } 191 192 static inline void regulator_print_state(const char *message __unused) 193 { 194 } 195 #endif /*CFG_DRIVERS_REGULATOR*/ 196 197 #if defined(CFG_DRIVERS_REGULATOR) && defined(CFG_DT) 198 /* 199 * regulator_dt_register() - Register a regulator to related to a DT node 200 * @fdt: FDT to work on 201 * @node: DT node of the regulator exposed by regulator driver 202 * @provider_node: Node where xxx-supply property is found or -1 if no supply. 203 * @desc: Description of the regulator to register 204 * 205 * This function registers and initializes a regulator instance once its supply 206 * if found, if any. Regulators registered with this function can be found by 207 * their consumer drivers using API function regulator_dt_get_supply() or like. 208 * 209 * Return TEE_SUCCESS in case of success 210 * Return TEE_ERROR_OUT_OF_MEMORY if failed on memory allocation 211 * Return any other TEE_Result compliant code in case of error 212 */ 213 TEE_Result regulator_dt_register(const void *fdt, int node, int provider_node, 214 const struct regu_dt_desc *desc); 215 #else 216 static inline TEE_Result regulator_dt_get_supply(const void *fdt __unused, 217 int node __unused, 218 const char *supply __unused, 219 struct regulator **r __unused) 220 { 221 return TEE_ERROR_NOT_SUPPORTED; 222 } 223 224 static inline TEE_Result 225 regulator_dt_register(const void *fdt __unused, int node __unused, 226 int provider_node __unused, 227 const struct regu_dt_desc *d __unused) 228 { 229 return TEE_ERROR_NOT_SUPPORTED; 230 } 231 #endif /* CFG_DRIVERS_REGULATOR && CFG_DT */ 232 233 /* 234 * regulator_name() - Return regulator name or NULL 235 * @regulator: Regulator reference 236 */ 237 static inline const char *regulator_name(struct regulator *regulator) 238 { 239 return regulator->name; 240 } 241 242 /* 243 * regulator_is_always_on() - Return the state of REGULATOR_ALWAYS_ON flag 244 * @regulator: Regulator reference 245 */ 246 static inline bool regulator_is_always_on(struct regulator *regulator) 247 { 248 return regulator->flags & REGULATOR_ALWAYS_ON; 249 } 250 251 /* 252 * regulator_set_min_voltage() - Set regulator to its min level 253 * @regulator: Regulator reference 254 */ 255 static inline TEE_Result regulator_set_min_voltage(struct regulator *regulator) 256 { 257 return regulator_set_voltage(regulator, regulator->min_uv); 258 } 259 260 /* 261 * regulator_get_voltage() - Get regulator current level in microvolt 262 * @regulator: Regulator reference 263 */ 264 static inline int regulator_get_voltage(struct regulator *regulator) 265 { 266 return regulator->cur_uv; 267 } 268 269 /* 270 * regulator_get_range() - Get regulator min and/or max support levels 271 * @regulator: Regulator reference 272 * @min_mv: Output reference to min level in microvolt (uV) or NULL 273 * @max_mv: Output reference to max level in microvolt (uV) or NULL 274 */ 275 static inline void regulator_get_range(struct regulator *regulator, int *min_uv, 276 int *max_uv) 277 { 278 assert(regulator); 279 if (min_uv) 280 *min_uv = regulator->min_uv; 281 if (max_uv) 282 *max_uv = regulator->max_uv; 283 } 284 285 /* 286 * regulator_supported_voltages() - Get regulator supported levels in microvolt 287 * @regulator: Regulator reference 288 * @voltages: Output description supported voltage levels 289 */ 290 TEE_Result regulator_supported_voltages(struct regulator *regulator, 291 struct regulator_voltages **voltages); 292 #endif /* DRIVERS_REGULATOR_H */ 293