Regulators

This subsystem provides control of voltage and current regulators. A common example is a GPIO that controls a transistor that supplies current to a device that is not always needed. Another example is a PMIC, typically a much more complex device.

The *-supply devicetree properties are used to identify the regulator(s) that a devicetree node directly depends on. Within the driver for the node the regulator API is used to issue requests for power when the device is to be active, and release the power request when the device shuts down.

The simplest case where a regulator is needed is one where there is only one client. For those situations the cost of using the regulator device infrastructure is not justified, and *-gpios devicetree properties should be used. There is no device interface to these regulators as they are entirely controlled within the driver for the corresponding node, e.g. a sensor.

API Reference

group regulator_interface

Regulator Interface.

Since

2.4

Version

0.1.0

Regulator error flags.

REGULATOR_ERROR_OVER_VOLTAGE

Voltage is too high.

REGULATOR_ERROR_OVER_CURRENT

Current is too high.

REGULATOR_ERROR_OVER_TEMP

Temperature is too high.

Typedefs

typedef uint8_t regulator_dvs_state_t

Opaque type to store regulator DVS states.

typedef uint8_t regulator_mode_t

Opaque type to store regulator modes.

typedef uint8_t regulator_error_flags_t

Opaque bit map for regulator error flags (see REGULATOR_ERRORS)

Functions

int regulator_enable(const struct device *dev)

Enable a regulator.

Reference-counted request that a regulator be turned on. A regulator is considered “on” when it has reached a stable/usable state. Regulators that are always on, or configured in devicetree with regulator-always-on will always stay enabled, and so this function will always succeed.

Parameters:

  • dev – Regulator device instance

Return values:

  • 0 – If regulator has been successfully enabled.

  • -errno – Negative errno in case of failure.

  • -ENOTSUP – If regulator enablement can not be controlled.

bool regulator_is_enabled(const struct device *dev)

Check if a regulator is enabled.

Parameters:

  • dev – Regulator device instance.

Return values:

  • true – If regulator is enabled.

  • false – If regulator is disabled.

int regulator_disable(const struct device *dev)

Disable a regulator.

Release a regulator after a previous regulator_enable() completed successfully. Regulators that are always on, or configured in devicetree with regulator-always-on will always stay enabled, and so this function will always succeed.

This must be invoked at most once for each successful regulator_enable().

Parameters:

  • dev – Regulator device instance.

Return values:

  • 0 – If regulator has been successfully disabled.

  • -errno – Negative errno in case of failure.

  • -ENOTSUP – If regulator disablement can not be controlled.

static inline unsigned int regulator_count_voltages(const struct device *dev)

Obtain the number of supported voltage levels.

Each voltage level supported by a regulator gets an index, starting from zero. The total number of supported voltage levels can be used together with regulator_list_voltage() to list all supported voltage levels.

Parameters:

  • dev – Regulator device instance.

Returns:

Number of supported voltages.

static inline int regulator_list_voltage(const struct device *dev, unsigned int idx, int32_t *volt_uv)

Obtain the value of a voltage given an index.

Each voltage level supported by a regulator gets an index, starting from zero. Together with regulator_count_voltages(), this function can be used to iterate over all supported voltages.

Parameters:

  • dev – Regulator device instance.

  • idx – Voltage index.

  • volt_uv – [out] Where voltage for the given index will be stored, in microvolts.

Return values:

  • 0 – If index corresponds to a supported voltage.

  • -EINVAL – If index does not correspond to a supported voltage.

bool regulator_is_supported_voltage(const struct device *dev, int32_t min_uv, int32_t max_uv)

Check if a voltage within a window is supported.

Parameters:

  • dev – Regulator device instance.

  • min_uv – Minimum voltage in microvolts.

  • max_uv – maximum voltage in microvolts.

Return values:

  • true – If voltage is supported.

  • false – If voltage is not supported.

int regulator_set_voltage(const struct device *dev, int32_t min_uv, int32_t max_uv)

Set the output voltage.

The output voltage will be configured to the closest supported output voltage. regulator_get_voltage() can be used to obtain the actual configured voltage. The voltage will be applied to the active or selected mode. Output voltage may be limited using regulator-min-microvolt and/or regulator-max-microvolt in devicetree.

Parameters:

  • dev – Regulator device instance.

  • min_uv – Minimum acceptable voltage in microvolts.

  • max_uv – Maximum acceptable voltage in microvolts.

Return values:

  • 0 – If successful.

  • -EINVAL – If the given voltage window is not valid.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_get_voltage(const struct device *dev, int32_t *volt_uv)

Obtain output voltage.

Parameters:

  • dev – Regulator device instance.

  • volt_uv – [out] Where configured output voltage will be stored.

Return values:

  • 0 – If successful

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline unsigned int regulator_count_current_limits(const struct device *dev)

Obtain the number of supported current limit levels.

Each current limit level supported by a regulator gets an index, starting from zero. The total number of supported current limit levels can be used together with regulator_list_current_limit() to list all supported current limit levels.

Parameters:

  • dev – Regulator device instance.

Returns:

Number of supported current limits.

static inline int regulator_list_current_limit(const struct device *dev, unsigned int idx, int32_t *current_ua)

Obtain the value of a current limit given an index.

Each current limit level supported by a regulator gets an index, starting from zero. Together with regulator_count_current_limits(), this function can be used to iterate over all supported current limits.

Parameters:

  • dev – Regulator device instance.

  • idx – Current index.

  • current_ua – [out] Where current for the given index will be stored, in microamps.

Return values:

  • 0 – If index corresponds to a supported current limit.

  • -EINVAL – If index does not correspond to a supported current limit.

int regulator_set_current_limit(const struct device *dev, int32_t min_ua, int32_t max_ua)

Set output current limit.

The output current limit will be configured to the closest supported output current limit. regulator_get_current_limit() can be used to obtain the actual configured current limit. Current may be limited using current-min-microamp and/or current-max-microamp in Devicetree.

Parameters:

  • dev – Regulator device instance.

  • min_ua – Minimum acceptable current limit in microamps.

  • max_ua – Maximum acceptable current limit in microamps.

Return values:

  • 0 – If successful.

  • -EINVAL – If the given current limit window is not valid.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_get_current_limit(const struct device *dev, int32_t *curr_ua)

Get output current limit.

Parameters:

  • dev – Regulator device instance.

  • curr_ua – [out] Where output current limit will be stored.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

int regulator_set_mode(const struct device *dev, regulator_mode_t mode)

Set mode.

Regulators can support multiple modes in order to permit different voltage configuration or better power savings. This API will apply a mode for the regulator. Allowed modes may be limited using regulator-allowed-modes devicetree property.

Parameters:

  • dev – Regulator device instance.

  • mode – Mode to select for this regulator.

Return values:

  • 0 – If successful.

  • -ENOTSUP – If mode is not supported.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_get_mode(const struct device *dev, regulator_mode_t *mode)

Get mode.

Parameters:

  • dev – Regulator device instance.

  • mode – [out] Where mode will be stored.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_set_active_discharge(const struct device *dev, bool active_discharge)

Set active discharge setting.

Parameters:

  • dev – Regulator device instance.

  • active_discharge – Active discharge enable or disable.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_get_active_discharge(const struct device *dev, bool *active_discharge)

Get active discharge setting.

Parameters:

  • dev – Regulator device instance.

  • active_discharge – [out] Where active discharge will be stored.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_get_error_flags(const struct device *dev, regulator_error_flags_t *flags)

Get active error flags.

Parameters:

  • dev – Regulator device instance.

  • flags – [out] Where error flags will be stored.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.