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.

Conceptually regulators have two modes: off and on. A transition between modes may involve a time delay, so operations on regulators are inherently asynchronous. To maximize flexibility the On-Off Manager infrastructure is used in the generic API for the regulator subsystem. Nodes with a devicetree compatible of regulator-fixed are the most common flexible regulators.

The vin-supply devicetree property is 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 even the optimized synchronous regulator device infrastructure is not justified, and the supply-gpios devicetree property 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.

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.

Parameters:

  • dev – Regulator device instance

Return values:

  • 0 – If regulator has been successfully enabled.

  • -errno – Negative errno in case of failure.

int regulator_disable(const struct device *dev)

Disable a regulator.

Release a regulator after a previous regulator_enable() completed successfully.

If the release removes the last dependency on the regulator it will begin a transition to its “off” state. There is currently no mechanism to notify when the regulator has completely turned off.

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.

static inline int regulator_count_voltages(const struct device *dev)

Obtain the number of supported voltage levels.

Selectors are numbered starting at zero, and typically correspond to bitfields in hardware registers.

Parameters:

  • dev – Regulator device instance.

Return values:

  • selectors – Number of selectors, if successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_count_modes(const struct device *dev)

Obtain the number of supported modes.

See also

regulator_set_mode()

Parameters:

  • dev – Regulator device instance.

Returns:

Number of supported modes.

static inline int32_t regulator_list_voltages(const struct device *dev, unsigned int selector)

Obtain supported voltages.

Parameters:

  • dev – Regulator device instance.

  • selector – Voltage selector.

Return values:

0 – If selector code can’t be used.

Returns:

voltage Voltage level in microvolts.

static inline int regulator_is_supported_voltage(const struct device *dev, int32_t min_uv, int32_t max_uv)

Check if a voltage range is supported.

Parameters:

  • dev – Regulator device instance.

  • min_uv – Minimum voltage in microvolts.

  • max_uv – maximum voltage in microvolts.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

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

Set output voltage.

Note

The output voltage will be configured to the closest supported output voltage. regulator_get_voltage() can be used to obtain the actual configured voltage.

Parameters:

  • dev – Regulator device instance.

  • min_uv – Minimum acceptable voltage in microvolts.

  • max_uv – Maximum acceptable voltage in microvolts.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int32_t regulator_get_voltage(const struct device *dev)

Obtain output voltage.

Parameters:

  • dev – Regulator device instance.

Returns:

Voltage level in microvolts.

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

Set output current limit.

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.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int32_t regulator_get_current_limit(const struct device *dev)

Get output current limit.

Parameters:

  • dev – Regulator device instance.

Return values:

  • current – Current limit in microamperes

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_set_mode(const struct device *dev, uint32_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.

Parameters:

  • dev – Regulator device instance.

  • mode – Mode to select for this regulator. Only modes present in the regulator-allowed-modes devicetree property are permitted.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_set_mode_voltage(const struct device *dev, uint32_t mode, int32_t min_uv, int32_t max_uv)

Set target voltage for a regulator mode.

Note

Mode does not need to be the active mode. The regulator can be switched to that mode with regulator_set_mode().

Parameters:

  • dev – Regulator device instance.

  • mode – Regulator mode.

  • min_uv – Minimum acceptable voltage in microvolts.

  • max_uv – Maximum acceptable voltage in microvolts.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int32_t regulator_get_mode_voltage(const struct device *dev, uint32_t mode)

Get target voltage for a regulator mode.

This API can be used to read voltages from a regulator mode other than the default. The given mode does not need to be active.

Parameters:

  • dev – Regulator device instance.

  • mode – Regulator mode.

Returns:

Voltage level in microvolts.

static inline int regulator_mode_disable(const struct device *dev, uint32_t mode)

Disable regulator for a given mode.

Parameters:

  • dev – Regulator device instance.

  • mode – Regulator mode.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.

static inline int regulator_mode_enable(const struct device *dev, uint32_t mode)

Enable regulator for a given mode.

Parameters:

  • dev – Regulator device instance.

  • mode – Regulator mode.

Return values:

  • 0 – If successful.

  • -ENOSYS – If function is not implemented.

  • -errno – In case of any other error.