1.. _regulator_api:
2
3Regulators
4##########
5
6This subsystem provides control of voltage and current regulators.  A
7common example is a GPIO that controls a transistor that supplies
8current to a device that is not always needed.
9
10Conceptually regulators have two modes: off and on.  A transition
11between modes may involve a time delay, so operations on regulators are
12inherently asynchronous.  To maximize flexibility the
13:ref:`resource_mgmt_onoff` infrastructure is used in the generic API for
14the regulator subsystem.  Nodes with a devicetree compatible of
15``regulator-fixed`` are the most common flexible regulators.
16
17In some cases the transitions are close enough to instantaneous that the
18the asynchronous driver implementation is not needed, and the resource
19cost in RAM is not justified.  Such a regulator still uses the
20asynchronous API, but may be implemented internally in a way that
21ensures the result of the operation is presented before the transition
22completes.  Zephyr recognizes devicetree nodes with a compatible of
23``regulator-fixed-sync`` as devices with synchronous transitions.
24
25The ``vin-supply`` devicetree property is used to identify the
26regulator(s) that a devicetree node directly depends on.  Within the
27driver for the node the regulator API is used to issue requests for
28power when the device is to be active, and release the power request
29when the device shuts down.
30
31The simplest case where a regulator is needed is one where there is only
32one client.  For those situations the cost of using even the optimized
33synchronous regulator device infrastructure is not justified, and the
34``supply-gpios`` devicetree property should be used.  There is no device
35interface to these regulators as they are entirely controlled within the
36driver for the corresponding node, e.g. a sensor.
37
38.. _regulator_api_reference:
39
40API Reference
41**************
42
43.. doxygengroup:: regulator_interface
44