Line data Source code
1 1 : /*
2 : * Copyright (c) 2019-2020 Peter Bigot Consulting, LLC
3 : * Copyright (c) 2021 NXP
4 : * Copyright (c) 2022 Nordic Semiconductor ASA
5 : * Copyright (c) 2023 EPAM Systems
6 : * Copyright (c) 2023 Meta Platforms
7 : * SPDX-License-Identifier: Apache-2.0
8 : */
9 :
10 : /**
11 : * @file
12 : * @ingroup regulator_interface
13 : * @brief Main header file for regulator driver API.
14 : */
15 :
16 : #ifndef ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
17 : #define ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
18 :
19 : /**
20 : * @brief Interfaces for regulators.
21 : * @defgroup regulator_interface Regulator
22 : * @since 2.4
23 : * @version 0.1.0
24 : * @ingroup io_interfaces
25 : * @{
26 : */
27 :
28 : #include <errno.h>
29 : #include <stdint.h>
30 :
31 : #include <zephyr/device.h>
32 : #include <zephyr/devicetree.h>
33 : #ifdef CONFIG_REGULATOR_THREAD_SAFE_REFCNT
34 : #include <zephyr/kernel.h>
35 : #endif
36 : #include <zephyr/sys/util_macro.h>
37 :
38 : #ifdef __cplusplus
39 : extern "C" {
40 : #endif
41 :
42 : /** Opaque type to store regulator DVS states */
43 1 : typedef uint8_t regulator_dvs_state_t;
44 :
45 : /** Opaque type to store regulator modes */
46 1 : typedef uint8_t regulator_mode_t;
47 :
48 : /** Opaque bit map for regulator error flags (see @ref REGULATOR_ERRORS) */
49 1 : typedef uint8_t regulator_error_flags_t;
50 :
51 : /**
52 : * @name Regulator error flags.
53 : * @anchor REGULATOR_ERRORS
54 : * @{
55 : */
56 :
57 : /** Voltage is too high. */
58 1 : #define REGULATOR_ERROR_OVER_VOLTAGE BIT(0)
59 : /** Current is too high. */
60 1 : #define REGULATOR_ERROR_OVER_CURRENT BIT(1)
61 : /** Temperature is too high. */
62 1 : #define REGULATOR_ERROR_OVER_TEMP BIT(2)
63 :
64 : /** @} */
65 :
66 : /** @cond INTERNAL_HIDDEN */
67 :
68 : typedef int (*regulator_dvs_state_set_t)(const struct device *dev,
69 : regulator_dvs_state_t state);
70 :
71 : typedef int (*regulator_ship_mode_t)(const struct device *dev);
72 :
73 : /** @brief Driver-specific API functions to support parent regulator control. */
74 : __subsystem struct regulator_parent_driver_api {
75 : regulator_dvs_state_set_t dvs_state_set;
76 : regulator_ship_mode_t ship_mode;
77 : };
78 :
79 : typedef int (*regulator_enable_t)(const struct device *dev);
80 : typedef int (*regulator_disable_t)(const struct device *dev);
81 : typedef unsigned int (*regulator_count_voltages_t)(const struct device *dev);
82 : typedef int (*regulator_list_voltage_t)(const struct device *dev,
83 : unsigned int idx, int32_t *volt_uv);
84 : typedef int (*regulator_set_voltage_t)(const struct device *dev, int32_t min_uv,
85 : int32_t max_uv);
86 : typedef int (*regulator_get_voltage_t)(const struct device *dev,
87 : int32_t *volt_uv);
88 : typedef unsigned int (*regulator_count_current_limits_t)(const struct device *dev);
89 : typedef int (*regulator_list_current_limit_t)(const struct device *dev,
90 : unsigned int idx, int32_t *current_ua);
91 : typedef int (*regulator_set_current_limit_t)(const struct device *dev,
92 : int32_t min_ua, int32_t max_ua);
93 : typedef int (*regulator_get_current_limit_t)(const struct device *dev,
94 : int32_t *curr_ua);
95 : typedef int (*regulator_set_mode_t)(const struct device *dev,
96 : regulator_mode_t mode);
97 : typedef int (*regulator_get_mode_t)(const struct device *dev,
98 : regulator_mode_t *mode);
99 : typedef int (*regulator_set_active_discharge_t)(const struct device *dev,
100 : bool active_discharge);
101 : typedef int (*regulator_get_active_discharge_t)(const struct device *dev,
102 : bool *active_discharge);
103 : typedef int (*regulator_get_error_flags_t)(
104 : const struct device *dev, regulator_error_flags_t *flags);
105 :
106 : /** @brief Driver-specific API functions to support regulator control. */
107 : __subsystem struct regulator_driver_api {
108 : regulator_enable_t enable;
109 : regulator_disable_t disable;
110 : regulator_count_voltages_t count_voltages;
111 : regulator_list_voltage_t list_voltage;
112 : regulator_set_voltage_t set_voltage;
113 : regulator_get_voltage_t get_voltage;
114 : regulator_count_current_limits_t count_current_limits;
115 : regulator_list_current_limit_t list_current_limit;
116 : regulator_set_current_limit_t set_current_limit;
117 : regulator_get_current_limit_t get_current_limit;
118 : regulator_set_mode_t set_mode;
119 : regulator_get_mode_t get_mode;
120 : regulator_set_active_discharge_t set_active_discharge;
121 : regulator_get_active_discharge_t get_active_discharge;
122 : regulator_get_error_flags_t get_error_flags;
123 : };
124 :
125 : /**
126 : * @name Regulator flags
127 : * @anchor REGULATOR_FLAGS
128 : * @{
129 : */
130 : /** Indicates regulator must stay always ON */
131 : #define REGULATOR_ALWAYS_ON BIT(0)
132 : /** Indicates regulator must be initialized ON */
133 : #define REGULATOR_BOOT_ON BIT(1)
134 : /** Indicates if regulator must be enabled when initialized */
135 : #define REGULATOR_INIT_ENABLED (REGULATOR_ALWAYS_ON | REGULATOR_BOOT_ON)
136 : /** Regulator active discharge state mask */
137 : #define REGULATOR_ACTIVE_DISCHARGE_MASK GENMASK(3, 2)
138 : /** Regulator active discharge state flag position*/
139 : #define REGULATOR_ACTIVE_DISCHARGE_POS 2
140 : /** Disable regulator active discharge */
141 : #define REGULATOR_ACTIVE_DISCHARGE_DISABLE 0
142 : /** Enable regulator active discharge */
143 : #define REGULATOR_ACTIVE_DISCHARGE_ENABLE 1
144 : /** Leave regulator active discharge state as default */
145 : #define REGULATOR_ACTIVE_DISCHARGE_DEFAULT 2
146 : /** Regulator active discharge set bits */
147 : #define REGULATOR_ACTIVE_DISCHARGE_SET_BITS(x) \
148 : (((x) << REGULATOR_ACTIVE_DISCHARGE_POS) & REGULATOR_ACTIVE_DISCHARGE_MASK)
149 : /** Regulator active discharge get bits */
150 : #define REGULATOR_ACTIVE_DISCHARGE_GET_BITS(x) \
151 : (((x) & REGULATOR_ACTIVE_DISCHARGE_MASK) >> REGULATOR_ACTIVE_DISCHARGE_POS)
152 : /** Indicates regulator must be initialized OFF */
153 : #define REGULATOR_BOOT_OFF BIT(4)
154 :
155 : /** @} */
156 :
157 : /** Indicates initial mode is unknown/not specified */
158 : #define REGULATOR_INITIAL_MODE_UNKNOWN UINT8_MAX
159 :
160 : /**
161 : * @brief Common regulator config.
162 : *
163 : * This structure **must** be placed first in the driver's config structure.
164 : */
165 : struct regulator_common_config {
166 : /** Minimum allowed voltage, in microvolts. */
167 : int32_t min_uv;
168 : /** Maximum allowed voltage, in microvolts. */
169 : int32_t max_uv;
170 : /** Initial voltage, in microvolts. */
171 : int32_t init_uv;
172 : /** Minimum allowed current, in microamps. */
173 : int32_t min_ua;
174 : /** Maximum allowed current, in microamps. */
175 : int32_t max_ua;
176 : /** Initial current, in microamps. */
177 : int32_t init_ua;
178 : /** Startup delay, in microseconds. */
179 : uint32_t startup_delay_us;
180 : /** Off to on delay, in microseconds. */
181 : uint32_t off_on_delay_us;
182 : /** Allowed modes */
183 : const regulator_mode_t *allowed_modes;
184 : /** Number of allowed modes */
185 : uint8_t allowed_modes_cnt;
186 : /** Regulator initial mode */
187 : regulator_mode_t initial_mode;
188 : /** Flags (@ref REGULATOR_FLAGS). */
189 : uint8_t flags;
190 : };
191 :
192 : /**
193 : * @brief Initialize common driver config from devicetree.
194 : *
195 : * @param node_id Node identifier.
196 : */
197 : #define REGULATOR_DT_COMMON_CONFIG_INIT(node_id) \
198 : { \
199 : .min_uv = DT_PROP_OR(node_id, regulator_min_microvolt, \
200 : INT32_MIN), \
201 : .max_uv = DT_PROP_OR(node_id, regulator_max_microvolt, \
202 : INT32_MAX), \
203 : .init_uv = DT_PROP_OR(node_id, regulator_init_microvolt, \
204 : INT32_MIN), \
205 : .min_ua = DT_PROP_OR(node_id, regulator_min_microamp, \
206 : INT32_MIN), \
207 : .max_ua = DT_PROP_OR(node_id, regulator_max_microamp, \
208 : INT32_MAX), \
209 : .init_ua = DT_PROP_OR(node_id, regulator_init_microamp, \
210 : INT32_MIN), \
211 : .startup_delay_us = DT_PROP_OR(node_id, startup_delay_us, 0), \
212 : .off_on_delay_us = DT_PROP_OR(node_id, off_on_delay_us, 0), \
213 : .allowed_modes = (const regulator_mode_t []) \
214 : DT_PROP_OR(node_id, regulator_allowed_modes, {}), \
215 : .allowed_modes_cnt = \
216 : DT_PROP_LEN_OR(node_id, regulator_allowed_modes, 0), \
217 : .initial_mode = DT_PROP_OR(node_id, regulator_initial_mode, \
218 : REGULATOR_INITIAL_MODE_UNKNOWN), \
219 : .flags = ((DT_PROP_OR(node_id, regulator_always_on, 0U) * \
220 : REGULATOR_ALWAYS_ON) | \
221 : (DT_PROP_OR(node_id, regulator_boot_on, 0U) * \
222 : REGULATOR_BOOT_ON) | \
223 : (REGULATOR_ACTIVE_DISCHARGE_SET_BITS( \
224 : DT_PROP_OR(node_id, regulator_active_discharge, \
225 : REGULATOR_ACTIVE_DISCHARGE_DEFAULT))) | \
226 : (DT_PROP_OR(node_id, regulator_boot_off, 0U) * \
227 : REGULATOR_BOOT_OFF)), \
228 : }
229 :
230 : /**
231 : * @brief Initialize common driver config from devicetree instance.
232 : *
233 : * @param inst Instance.
234 : */
235 : #define REGULATOR_DT_INST_COMMON_CONFIG_INIT(inst) \
236 : REGULATOR_DT_COMMON_CONFIG_INIT(DT_DRV_INST(inst))
237 :
238 : /**
239 : * @brief Common regulator data.
240 : *
241 : * This structure **must** be placed first in the driver's data structure.
242 : */
243 : struct regulator_common_data {
244 : #if defined(CONFIG_REGULATOR_THREAD_SAFE_REFCNT) || defined(__DOXYGEN__)
245 : /** Lock (only if @kconfig{CONFIG_REGULATOR_THREAD_SAFE_REFCNT}=y) */
246 : struct k_mutex lock;
247 : #endif
248 : /** Reference count */
249 : int refcnt;
250 : };
251 :
252 : /**
253 : * @brief Initialize common regulator data.
254 : *
255 : * This function **must** be called when driver is initialized.
256 : *
257 : * @param dev Regulator device instance.
258 : */
259 : void regulator_common_data_init(const struct device *dev);
260 :
261 : /**
262 : * @brief Common function to initialize the regulator at init time.
263 : *
264 : * This function needs to be called after drivers initialize the regulator. It
265 : * will:
266 : *
267 : * - Automatically enable the regulator if it is set to `regulator-boot-on`
268 : * or `regulator-always-on` and increase its usage count.
269 : * - Automatically disable the regulator if it is set to `regulator-boot-off`.
270 : * - Configure the regulator mode if `regulator-initial-mode` is set.
271 : * - Ensure regulator voltage is set to a valid range.
272 : *
273 : * Regulators that are enabled by default in hardware, must set @p is_enabled to
274 : * `true`.
275 : *
276 : * @param dev Regulator device instance
277 : * @param is_enabled Indicate if the regulator is enabled by default in
278 : * hardware.
279 : *
280 : * @retval 0 If enabled successfully.
281 : * @retval -errno Negative errno in case of failure.
282 : */
283 : int regulator_common_init(const struct device *dev, bool is_enabled);
284 :
285 : /**
286 : * @brief Check if regulator is expected to be enabled at init time.
287 : *
288 : * @param dev Regulator device instance
289 : * @return true If regulator needs to be enabled at init time.
290 : * @return false If regulator does not need to be enabled at init time.
291 : */
292 : static inline bool regulator_common_is_init_enabled(const struct device *dev)
293 : {
294 : const struct regulator_common_config *config =
295 : (const struct regulator_common_config *)dev->config;
296 :
297 : return (config->flags & REGULATOR_INIT_ENABLED) != 0U;
298 : }
299 :
300 : /**
301 : * @brief Get minimum supported voltage.
302 : *
303 : * @param dev Regulator device instance.
304 : * @param min_uv Where minimum voltage will be stored, in microvolts.
305 : *
306 : * @retval 0 If successful
307 : * @retval -ENOENT If minimum voltage is not specified.
308 : */
309 : static inline int regulator_common_get_min_voltage(const struct device *dev, int32_t *min_uv)
310 : {
311 : const struct regulator_common_config *config =
312 : (const struct regulator_common_config *)dev->config;
313 :
314 : if (config->min_uv == INT32_MIN) {
315 : return -ENOENT;
316 : }
317 :
318 : *min_uv = config->min_uv;
319 : return 0;
320 : }
321 :
322 : /**
323 : * @brief Get maximum supported voltage.
324 : *
325 : * @param dev Regulator device instance.
326 : * @param max_uv Where maximum voltage will be stored, in microvolts.
327 : *
328 : * @retval 0 If successful
329 : * @retval -ENOENT If maximum voltage is not specified.
330 : */
331 : static inline int regulator_common_get_max_voltage(const struct device *dev, int32_t *max_uv)
332 : {
333 : const struct regulator_common_config *config =
334 : (const struct regulator_common_config *)dev->config;
335 :
336 : if (config->max_uv == INT32_MAX) {
337 : return -ENOENT;
338 : }
339 :
340 : *max_uv = config->max_uv;
341 : return 0;
342 : }
343 :
344 : /** @endcond */
345 :
346 : /**
347 : * @brief Regulator Parent Interface
348 : * @defgroup regulator_parent_interface Regulator Parent Interface
349 : * @{
350 : */
351 :
352 : /**
353 : * @brief Set a DVS state.
354 : *
355 : * Some PMICs feature DVS (Dynamic Voltage Scaling) by allowing to program the
356 : * voltage level for multiple states. Such states may be automatically changed
357 : * by hardware using GPIO pins. Certain MCUs even allow to automatically
358 : * configure specific output pins when entering low-power modes so that PMIC
359 : * state is changed without software intervention. This API can be used when
360 : * state needs to be changed by software.
361 : *
362 : * @param dev Parent regulator device instance.
363 : * @param state DVS state (vendor specific identifier).
364 : *
365 : * @retval 0 If successful.
366 : * @retval -ENOTSUP If given state is not supported.
367 : * @retval -EPERM If state can't be changed by software.
368 : * @retval -ENOSYS If function is not implemented.
369 : * @retval -errno In case of any other error.
370 : */
371 1 : static inline int regulator_parent_dvs_state_set(const struct device *dev,
372 : regulator_dvs_state_t state)
373 : {
374 : const struct regulator_parent_driver_api *api =
375 : (const struct regulator_parent_driver_api *)dev->api;
376 :
377 : if (api->dvs_state_set == NULL) {
378 : return -ENOSYS;
379 : }
380 :
381 : return api->dvs_state_set(dev, state);
382 : }
383 :
384 : /**
385 : * @brief Enter ship mode.
386 : *
387 : * Some PMICs feature a ship mode, which allows the system to save power.
388 : * Exit from low power is normally by pin transition.
389 : *
390 : * This API can be used when ship mode needs to be entered.
391 : *
392 : * @param dev Parent regulator device instance.
393 : *
394 : * @retval 0 If successful.
395 : * @retval -ENOSYS If function is not implemented.
396 : * @retval -errno In case of any other error.
397 : */
398 1 : static inline int regulator_parent_ship_mode(const struct device *dev)
399 : {
400 : const struct regulator_parent_driver_api *api =
401 : (const struct regulator_parent_driver_api *)dev->api;
402 :
403 : if (api->ship_mode == NULL) {
404 : return -ENOSYS;
405 : }
406 :
407 : return api->ship_mode(dev);
408 : }
409 :
410 : /** @} */
411 :
412 : /**
413 : * @brief Enable a regulator.
414 : *
415 : * Reference-counted request that a regulator be turned on. A regulator is
416 : * considered "on" when it has reached a stable/usable state. Regulators that
417 : * are always on, or configured in devicetree with `regulator-always-on` will
418 : * always stay enabled, and so this function will always succeed.
419 : *
420 : * @param dev Regulator device instance
421 : *
422 : * @retval 0 If regulator has been successfully enabled.
423 : * @retval -errno Negative errno in case of failure.
424 : * @retval -ENOTSUP If regulator enablement can not be controlled.
425 : */
426 1 : int regulator_enable(const struct device *dev);
427 :
428 : /**
429 : * @brief Check if a regulator is enabled.
430 : *
431 : * @param dev Regulator device instance.
432 : *
433 : * @retval true If regulator is enabled.
434 : * @retval false If regulator is disabled.
435 : */
436 1 : bool regulator_is_enabled(const struct device *dev);
437 :
438 : /**
439 : * @brief Disable a regulator.
440 : *
441 : * Release a regulator after a previous regulator_enable() completed
442 : * successfully. Regulators that are always on, or configured in devicetree with
443 : * `regulator-always-on` will always stay enabled, and so this function will
444 : * always succeed.
445 : *
446 : * This must be invoked at most once for each successful regulator_enable().
447 : *
448 : * @param dev Regulator device instance.
449 : *
450 : * @retval 0 If regulator has been successfully disabled.
451 : * @retval -errno Negative errno in case of failure.
452 : * @retval -ENOTSUP If regulator disablement can not be controlled.
453 : */
454 1 : int regulator_disable(const struct device *dev);
455 :
456 : /**
457 : * @brief Obtain the number of supported voltage levels.
458 : *
459 : * Each voltage level supported by a regulator gets an index, starting from
460 : * zero. The total number of supported voltage levels can be used together with
461 : * regulator_list_voltage() to list all supported voltage levels.
462 : *
463 : * @param dev Regulator device instance.
464 : *
465 : * @return Number of supported voltages.
466 : */
467 1 : static inline unsigned int regulator_count_voltages(const struct device *dev)
468 : {
469 : const struct regulator_driver_api *api =
470 : (const struct regulator_driver_api *)dev->api;
471 :
472 : if (api->count_voltages == NULL) {
473 : return 0U;
474 : }
475 :
476 : return api->count_voltages(dev);
477 : }
478 :
479 : /**
480 : * @brief Obtain the value of a voltage given an index.
481 : *
482 : * Each voltage level supported by a regulator gets an index, starting from
483 : * zero. Together with regulator_count_voltages(), this function can be used
484 : * to iterate over all supported voltages.
485 : *
486 : * @param dev Regulator device instance.
487 : * @param idx Voltage index.
488 : * @param[out] volt_uv Where voltage for the given @p index will be stored, in
489 : * microvolts.
490 : *
491 : * @retval 0 If @p index corresponds to a supported voltage.
492 : * @retval -EINVAL If @p index does not correspond to a supported voltage.
493 : */
494 1 : static inline int regulator_list_voltage(const struct device *dev,
495 : unsigned int idx, int32_t *volt_uv)
496 : {
497 : const struct regulator_driver_api *api =
498 : (const struct regulator_driver_api *)dev->api;
499 :
500 : if (api->list_voltage == NULL) {
501 : return -EINVAL;
502 : }
503 :
504 : return api->list_voltage(dev, idx, volt_uv);
505 : }
506 :
507 : /**
508 : * @brief Check if a voltage within a window is supported.
509 : *
510 : * @param dev Regulator device instance.
511 : * @param min_uv Minimum voltage in microvolts.
512 : * @param max_uv maximum voltage in microvolts.
513 : *
514 : * @retval true If voltage is supported.
515 : * @retval false If voltage is not supported.
516 : */
517 1 : bool regulator_is_supported_voltage(const struct device *dev, int32_t min_uv,
518 : int32_t max_uv);
519 :
520 : /**
521 : * @brief Set the output voltage.
522 : *
523 : * The output voltage will be configured to the closest supported output
524 : * voltage. regulator_get_voltage() can be used to obtain the actual configured
525 : * voltage. The voltage will be applied to the active or selected mode. Output
526 : * voltage may be limited using `regulator-min-microvolt` and/or
527 : * `regulator-max-microvolt` in devicetree.
528 : *
529 : * @param dev Regulator device instance.
530 : * @param min_uv Minimum acceptable voltage in microvolts.
531 : * @param max_uv Maximum acceptable voltage in microvolts.
532 : *
533 : * @retval 0 If successful.
534 : * @retval -EINVAL If the given voltage window is not valid.
535 : * @retval -ENOSYS If function is not implemented.
536 : * @retval -errno In case of any other error.
537 : */
538 1 : int regulator_set_voltage(const struct device *dev, int32_t min_uv,
539 : int32_t max_uv);
540 :
541 : /**
542 : * @brief Obtain output voltage.
543 : *
544 : * @param dev Regulator device instance.
545 : * @param[out] volt_uv Where configured output voltage will be stored.
546 : *
547 : * @retval 0 If successful
548 : * @retval -ENOSYS If function is not implemented.
549 : * @retval -errno In case of any other error.
550 : */
551 1 : static inline int regulator_get_voltage(const struct device *dev,
552 : int32_t *volt_uv)
553 : {
554 : const struct regulator_driver_api *api =
555 : (const struct regulator_driver_api *)dev->api;
556 :
557 : if (api->get_voltage == NULL) {
558 : return -ENOSYS;
559 : }
560 :
561 : return api->get_voltage(dev, volt_uv);
562 : }
563 :
564 : /**
565 : * @brief Obtain the number of supported current limit levels.
566 : *
567 : * Each current limit level supported by a regulator gets an index, starting from
568 : * zero. The total number of supported current limit levels can be used together with
569 : * regulator_list_current_limit() to list all supported current limit levels.
570 : *
571 : * @param dev Regulator device instance.
572 : *
573 : * @return Number of supported current limits.
574 : */
575 1 : static inline unsigned int regulator_count_current_limits(const struct device *dev)
576 : {
577 : const struct regulator_driver_api *api =
578 : (const struct regulator_driver_api *)dev->api;
579 :
580 : if (api->count_current_limits == NULL) {
581 : return 0U;
582 : }
583 :
584 : return api->count_current_limits(dev);
585 : }
586 :
587 : /**
588 : * @brief Obtain the value of a current limit given an index.
589 : *
590 : * Each current limit level supported by a regulator gets an index, starting from
591 : * zero. Together with regulator_count_current_limits(), this function can be used
592 : * to iterate over all supported current limits.
593 : *
594 : * @param dev Regulator device instance.
595 : * @param idx Current index.
596 : * @param[out] current_ua Where current for the given @p index will be stored, in
597 : * microamps.
598 : *
599 : * @retval 0 If @p index corresponds to a supported current limit.
600 : * @retval -EINVAL If @p index does not correspond to a supported current limit.
601 : */
602 1 : static inline int regulator_list_current_limit(const struct device *dev,
603 : unsigned int idx, int32_t *current_ua)
604 : {
605 : const struct regulator_driver_api *api =
606 : (const struct regulator_driver_api *)dev->api;
607 :
608 : if (api->list_current_limit == NULL) {
609 : return -EINVAL;
610 : }
611 :
612 : return api->list_current_limit(dev, idx, current_ua);
613 : }
614 :
615 : /**
616 : * @brief Set output current limit.
617 : *
618 : * The output current limit will be configured to the closest supported output
619 : * current limit. regulator_get_current_limit() can be used to obtain the actual
620 : * configured current limit. Current may be limited using `current-min-microamp`
621 : * and/or `current-max-microamp` in Devicetree.
622 : *
623 : * @param dev Regulator device instance.
624 : * @param min_ua Minimum acceptable current limit in microamps.
625 : * @param max_ua Maximum acceptable current limit in microamps.
626 : *
627 : * @retval 0 If successful.
628 : * @retval -EINVAL If the given current limit window is not valid.
629 : * @retval -ENOSYS If function is not implemented.
630 : * @retval -errno In case of any other error.
631 : */
632 1 : int regulator_set_current_limit(const struct device *dev, int32_t min_ua,
633 : int32_t max_ua);
634 :
635 : /**
636 : * @brief Get output current limit.
637 : *
638 : * @param dev Regulator device instance.
639 : * @param[out] curr_ua Where output current limit will be stored.
640 : *
641 : * @retval 0 If successful.
642 : * @retval -ENOSYS If function is not implemented.
643 : * @retval -errno In case of any other error.
644 : */
645 1 : static inline int regulator_get_current_limit(const struct device *dev,
646 : int32_t *curr_ua)
647 : {
648 : const struct regulator_driver_api *api =
649 : (const struct regulator_driver_api *)dev->api;
650 :
651 : if (api->get_current_limit == NULL) {
652 : return -ENOSYS;
653 : }
654 :
655 : return api->get_current_limit(dev, curr_ua);
656 : }
657 :
658 : /**
659 : * @brief Set mode.
660 : *
661 : * Regulators can support multiple modes in order to permit different voltage
662 : * configuration or better power savings. This API will apply a mode for
663 : * the regulator. Allowed modes may be limited using `regulator-allowed-modes`
664 : * devicetree property.
665 : *
666 : * @param dev Regulator device instance.
667 : * @param mode Mode to select for this regulator.
668 : *
669 : * @retval 0 If successful.
670 : * @retval -ENOTSUP If mode is not supported.
671 : * @retval -ENOSYS If function is not implemented.
672 : * @retval -errno In case of any other error.
673 : */
674 1 : int regulator_set_mode(const struct device *dev, regulator_mode_t mode);
675 :
676 : /**
677 : * @brief Get mode.
678 : *
679 : * @param dev Regulator device instance.
680 : * @param[out] mode Where mode will be stored.
681 : *
682 : * @retval 0 If successful.
683 : * @retval -ENOSYS If function is not implemented.
684 : * @retval -errno In case of any other error.
685 : */
686 1 : static inline int regulator_get_mode(const struct device *dev,
687 : regulator_mode_t *mode)
688 : {
689 : const struct regulator_driver_api *api =
690 : (const struct regulator_driver_api *)dev->api;
691 :
692 : if (api->get_mode == NULL) {
693 : return -ENOSYS;
694 : }
695 :
696 : return api->get_mode(dev, mode);
697 : }
698 :
699 : /**
700 : * @brief Set active discharge setting.
701 : *
702 : * @param dev Regulator device instance.
703 : * @param active_discharge Active discharge enable or disable.
704 : *
705 : * @retval 0 If successful.
706 : * @retval -ENOSYS If function is not implemented.
707 : * @retval -errno In case of any other error.
708 : */
709 1 : static inline int regulator_set_active_discharge(const struct device *dev,
710 : bool active_discharge)
711 : {
712 : const struct regulator_driver_api *api =
713 : (const struct regulator_driver_api *)dev->api;
714 :
715 : if (api->set_active_discharge == NULL) {
716 : return -ENOSYS;
717 : }
718 :
719 : return api->set_active_discharge(dev, active_discharge);
720 : }
721 :
722 : /**
723 : * @brief Get active discharge setting.
724 : *
725 : * @param dev Regulator device instance.
726 : * @param[out] active_discharge Where active discharge will be stored.
727 : *
728 : * @retval 0 If successful.
729 : * @retval -ENOSYS If function is not implemented.
730 : * @retval -errno In case of any other error.
731 : */
732 1 : static inline int regulator_get_active_discharge(const struct device *dev,
733 : bool *active_discharge)
734 : {
735 : const struct regulator_driver_api *api =
736 : (const struct regulator_driver_api *)dev->api;
737 :
738 : if (api->get_active_discharge == NULL) {
739 : return -ENOSYS;
740 : }
741 :
742 : return api->get_active_discharge(dev, active_discharge);
743 : }
744 :
745 : /**
746 : * @brief Get active error flags.
747 : *
748 : * @param dev Regulator device instance.
749 : * @param[out] flags Where error flags will be stored.
750 : *
751 : * @retval 0 If successful.
752 : * @retval -ENOSYS If function is not implemented.
753 : * @retval -errno In case of any other error.
754 : */
755 1 : static inline int regulator_get_error_flags(const struct device *dev,
756 : regulator_error_flags_t *flags)
757 : {
758 : const struct regulator_driver_api *api =
759 : (const struct regulator_driver_api *)dev->api;
760 :
761 : if (api->get_error_flags == NULL) {
762 : return -ENOSYS;
763 : }
764 :
765 : return api->get_error_flags(dev, flags);
766 : }
767 :
768 : #ifdef __cplusplus
769 : }
770 : #endif
771 :
772 : /** @} */
773 :
774 : #endif /* ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_ */
|
