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.

In some cases the transitions are close enough to instantaneous that the the asynchronous driver implementation is not needed, and the resource cost in RAM is not justified. Such a regulator still uses the asynchronous API, but may be implemented internally in a way that ensures the result of the operation is presented before the transition completes. Zephyr recognizes devicetree nodes with a compatible of regulator-fixed-sync as devices with synchronous transitions.

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 *reg, struct onoff_client *cli)

Enable a regulator.

Reference-counted request that a regulator be turned on. This is an asynchronous operation; if successfully initiated the result will be communicated through the cli parameter.

A regulator is considered “on” when it has reached a stable/usable state.

Note

This function is isr-ok and pre-kernel-ok.

Return

non-negative on successful initiation of the request. Negative values indicate failures from onoff_request() or individual regulator drivers.

Parameters

• reg: a regulator device

• cli: used to notify the caller when the attempt to turn on the regulator has completed.

int regulator_disable(const struct device *reg)

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().

Note

This function is isr-ok.

Return

non-negative on successful completion of the release request. Negative values indicate failures from onoff_release() or individual regulator drivers.

Parameters

• reg: a regulator device

struct regulator_driver_api

#include <regulator.h>

Driver-specific API functions to support regulator control.