| 1 | |
| 2 |
|
| 3 | |
| 4 | |
| 5 | |
| 6 |
|
| 7 | =================================
|
| 8 | Voltage and current regulator API
|
| 9 | =================================
|
| 10 |
|
| 11 | :Author: Liam Girdwood
|
| 12 | :Author: Mark Brown
|
| 13 |
|
| 14 | Introduction
|
| 15 | ============
|
| 16 |
|
| 17 | This framework is designed to provide a standard kernel interface to
|
| 18 | control voltage and current regulators.
|
| 19 |
|
| 20 | The intention is to allow systems to dynamically control regulator power
|
| 21 | output in order to save power and prolong battery life. This applies to
|
| 22 | both voltage regulators (where voltage output is controllable) and
|
| 23 | current sinks (where current limit is controllable).
|
| 24 |
|
| 25 | Note that additional (and currently more complete) documentation is
|
| 26 | available in the Linux kernel source under
|
| 27 | ``Documentation/power/regulator``.
|
| 28 |
|
| 29 | Glossary
|
| 30 | --------
|
| 31 |
|
| 32 | The regulator API uses a number of terms which may not be familiar:
|
| 33 |
|
| 34 | Regulator
|
| 35 |
|
| 36 | Electronic device that supplies power to other devices. Most regulators
|
| 37 | can enable and disable their output and some can also control their
|
| 38 | output voltage or current.
|
| 39 |
|
| 40 | Consumer
|
| 41 |
|
| 42 | Electronic device which consumes power provided by a regulator. These
|
| 43 | may either be static, requiring only a fixed supply, or dynamic,
|
| 44 | requiring active management of the regulator at runtime.
|
| 45 |
|
| 46 | Power Domain
|
| 47 |
|
| 48 | The electronic circuit supplied by a given regulator, including the
|
| 49 | regulator and all consumer devices. The configuration of the regulator
|
| 50 | is shared between all the components in the circuit.
|
| 51 |
|
| 52 | Power Management Integrated Circuit (PMIC)
|
| 53 |
|
| 54 | An IC which contains numerous regulators and often also other
|
| 55 | subsystems. In an embedded system the primary PMIC is often equivalent
|
| 56 | to a combination of the PSU and southbridge in a desktop system.
|
| 57 |
|
| 58 | Consumer driver interface
|
| 59 | =========================
|
| 60 |
|
| 61 | This offers a similar API to the kernel clock framework. Consumer
|
| 62 | drivers use `get <#API-regulator-get>`__ and
|
| 63 | `put <#API-regulator-put>`__ operations to acquire and release
|
| 64 | regulators. Functions are provided to `enable <#API-regulator-enable>`__
|
| 65 | and `disable <#API-regulator-disable>`__ the regulator and to get and
|
| 66 | set the runtime parameters of the regulator.
|
| 67 |
|
| 68 | When requesting regulators consumers use symbolic names for their
|
| 69 | supplies, such as "Vcc", which are mapped into actual regulator devices
|
| 70 | by the machine interface.
|
| 71 |
|
| 72 | A stub version of this API is provided when the regulator framework is
|
| 73 | not in use in order to minimise the need to use ifdefs.
|
| 74 |
|
| 75 | Enabling and disabling
|
| 76 | ----------------------
|
| 77 |
|
| 78 | The regulator API provides reference counted enabling and disabling of
|
| 79 | regulators. Consumer devices use the :c:func:`regulator_enable()` and
|
| 80 | :c:func:`regulator_disable()` functions to enable and disable
|
| 81 | regulators. Calls to the two functions must be balanced.
|
| 82 |
|
| 83 | Note that since multiple consumers may be using a regulator and machine
|
| 84 | constraints may not allow the regulator to be disabled there is no
|
| 85 | guarantee that calling :c:func:`regulator_disable()` will actually
|
| 86 | cause the supply provided by the regulator to be disabled. Consumer
|
| 87 | drivers should assume that the regulator may be enabled at all times.
|
| 88 |
|
| 89 | Configuration
|
| 90 | -------------
|
| 91 |
|
| 92 | Some consumer devices may need to be able to dynamically configure their
|
| 93 | supplies. For example, MMC drivers may need to select the correct
|
| 94 | operating voltage for their cards. This may be done while the regulator
|
| 95 | is enabled or disabled.
|
| 96 |
|
| 97 | The :c:func:`regulator_set_voltage()` and
|
| 98 | :c:func:`regulator_set_current_limit()` functions provide the primary
|
| 99 | interface for this. Both take ranges of voltages and currents, supporting
|
| 100 | drivers that do not require a specific value (eg, CPU frequency scaling
|
| 101 | normally permits the CPU to use a wider range of supply voltages at lower
|
| 102 | frequencies but does not require that the supply voltage be lowered). Where
|
| 103 | an exact value is required both minimum and maximum values should be
|
| 104 | identical.
|
| 105 |
|
| 106 | Callbacks
|
| 107 | ---------
|
| 108 |
|
| 109 | Callbacks may also be registered for events such as regulation failures.
|
| 110 |
|
| 111 | Regulator driver interface
|
| 112 | ==========================
|
| 113 |
|
| 114 | Drivers for regulator chips register the regulators with the regulator
|
| 115 | core, providing operations structures to the core. A notifier interface
|
| 116 | allows error conditions to be reported to the core.
|
| 117 |
|
| 118 | Registration should be triggered by explicit setup done by the platform,
|
| 119 | supplying a struct regulator_init_data for the regulator
|
| 120 | containing constraint and supply information.
|
| 121 |
|
| 122 | Machine interface
|
| 123 | =================
|
| 124 |
|
| 125 | This interface provides a way to define how regulators are connected to
|
| 126 | consumers on a given system and what the valid operating parameters are
|
| 127 | for the system.
|
| 128 |
|
| 129 | Supplies
|
| 130 | --------
|
| 131 |
|
| 132 | Regulator supplies are specified using struct
|
| 133 | :c:type:`regulator_consumer_supply`. This is done at driver registration
|
| 134 | time as part of the machine constraints.
|
| 135 |
|
| 136 | Constraints
|
| 137 | -----------
|
| 138 |
|
| 139 | As well as defining the connections the machine interface also provides
|
| 140 | constraints defining the operations that clients are allowed to perform
|
| 141 | and the parameters that may be set. This is required since generally
|
| 142 | regulator devices will offer more flexibility than it is safe to use on
|
| 143 | a given system, for example supporting higher supply voltages than the
|
| 144 | consumers are rated for.
|
| 145 |
|
| 146 | This is done at driver registration time` by providing a
|
| 147 | struct regulation_constraints.
|
| 148 |
|
| 149 | The constraints may also specify an initial configuration for the
|
| 150 | regulator in the constraints, which is particularly useful for use with
|
| 151 | static consumers.
|
| 152 |
|
| 153 | API reference
|
| 154 | =============
|
| 155 |
|
| 156 | Due to limitations of the kernel documentation framework and the
|
| 157 | existing layout of the source code the entire regulator API is
|
| 158 | documented here.
|
| 159 |
|
| 160 | .. kernel-doc:: include/linux/regulator/consumer.h
|
| 161 | :internal:
|
| 162 |
|
| 163 | .. kernel-doc:: include/linux/regulator/machine.h
|
| 164 | :internal:
|
| 165 |
|
| 166 | .. kernel-doc:: include/linux/regulator/driver.h
|
| 167 | :internal:
|
| 168 |
|
| 169 | .. kernel-doc:: drivers/regulator/core.c
|
| 170 | :export:
|