| 1 |
============================================= |
| 2 |
Linux voltage and current regulator framework |
| 3 |
============================================= |
| 4 |
|
| 5 |
About |
| 6 |
===== |
| 7 |
|
| 8 |
This framework is designed to provide a standard kernel interface to control |
| 9 |
voltage and current regulators. |
| 10 |
|
| 11 |
The intention is to allow systems to dynamically control regulator power output |
| 12 |
in order to save power and prolong battery life. This applies to both voltage |
| 13 |
regulators (where voltage output is controllable) and current sinks (where |
| 14 |
current limit is controllable). |
| 15 |
|
| 16 |
(C) 2008 Wolfson Microelectronics PLC. |
| 17 |
|
| 18 |
Author: Liam Girdwood <[email protected]> |
| 19 |
|
| 20 |
|
| 21 |
Nomenclature |
| 22 |
============ |
| 23 |
|
| 24 |
Some terms used in this document: |
| 25 |
|
| 26 |
- Regulator |
| 27 |
- Electronic device that supplies power to other devices. |
| 28 |
Most regulators can enable and disable their output while |
| 29 |
some can control their output voltage and or current. |
| 30 |
|
| 31 |
Input Voltage -> Regulator -> Output Voltage |
| 32 |
|
| 33 |
|
| 34 |
- PMIC |
| 35 |
- Power Management IC. An IC that contains numerous |
| 36 |
regulators and often contains other subsystems. |
| 37 |
|
| 38 |
|
| 39 |
- Consumer |
| 40 |
- Electronic device that is supplied power by a regulator. |
| 41 |
Consumers can be classified into two types:- |
| 42 |
|
| 43 |
Static: consumer does not change its supply voltage or |
| 44 |
current limit. It only needs to enable or disable its |
| 45 |
power supply. Its supply voltage is set by the hardware, |
| 46 |
bootloader, firmware or kernel board initialisation code. |
| 47 |
|
| 48 |
Dynamic: consumer needs to change its supply voltage or |
| 49 |
current limit to meet operation demands. |
| 50 |
|
| 51 |
|
| 52 |
- Power Domain |
| 53 |
- Electronic circuit that is supplied its input power by the |
| 54 |
output power of a regulator, switch or by another power |
| 55 |
domain. |
| 56 |
|
| 57 |
The supply regulator may be behind a switch(s). i.e.:: |
| 58 |
|
| 59 |
Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A] |
| 60 |
| | |
| 61 |
| +-> [Consumer B], [Consumer C] |
| 62 |
| |
| 63 |
+-> [Consumer D], [Consumer E] |
| 64 |
|
| 65 |
That is one regulator and three power domains: |
| 66 |
|
| 67 |
- Domain 1: Switch-1, Consumers D & E. |
| 68 |
- Domain 2: Switch-2, Consumers B & C. |
| 69 |
- Domain 3: Consumer A. |
| 70 |
|
| 71 |
and this represents a "supplies" relationship: |
| 72 |
|
| 73 |
Domain-1 --> Domain-2 --> Domain-3. |
| 74 |
|
| 75 |
A power domain may have regulators that are supplied power |
| 76 |
by other regulators. i.e.:: |
| 77 |
|
| 78 |
Regulator-1 -+-> Regulator-2 -+-> [Consumer A] |
| 79 |
| |
| 80 |
+-> [Consumer B] |
| 81 |
|
| 82 |
This gives us two regulators and two power domains: |
| 83 |
|
| 84 |
- Domain 1: Regulator-2, Consumer B. |
| 85 |
- Domain 2: Consumer A. |
| 86 |
|
| 87 |
and a "supplies" relationship: |
| 88 |
|
| 89 |
Domain-1 --> Domain-2 |
| 90 |
|
| 91 |
|
| 92 |
- Constraints |
| 93 |
- Constraints are used to define power levels for performance |
| 94 |
and hardware protection. Constraints exist at three levels: |
| 95 |
|
| 96 |
Regulator Level: This is defined by the regulator hardware |
| 97 |
operating parameters and is specified in the regulator |
| 98 |
datasheet. i.e. |
| 99 |
|
| 100 |
- voltage output is in the range 800mV -> 3500mV. |
| 101 |
- regulator current output limit is 20mA @ 5V but is |
| 102 |
10mA @ 10V. |
| 103 |
|
| 104 |
Power Domain Level: This is defined in software by kernel |
| 105 |
level board initialisation code. It is used to constrain a |
| 106 |
power domain to a particular power range. i.e. |
| 107 |
|
| 108 |
- Domain-1 voltage is 3300mV |
| 109 |
- Domain-2 voltage is 1400mV -> 1600mV |
| 110 |
- Domain-3 current limit is 0mA -> 20mA. |
| 111 |
|
| 112 |
Consumer Level: This is defined by consumer drivers |
| 113 |
dynamically setting voltage or current limit levels. |
| 114 |
|
| 115 |
e.g. a consumer backlight driver asks for a current increase |
| 116 |
from 5mA to 10mA to increase LCD illumination. This passes |
| 117 |
to through the levels as follows :- |
| 118 |
|
| 119 |
Consumer: need to increase LCD brightness. Lookup and |
| 120 |
request next current mA value in brightness table (the |
| 121 |
consumer driver could be used on several different |
| 122 |
personalities based upon the same reference device). |
| 123 |
|
| 124 |
Power Domain: is the new current limit within the domain |
| 125 |
operating limits for this domain and system state (e.g. |
| 126 |
battery power, USB power) |
| 127 |
|
| 128 |
Regulator Domains: is the new current limit within the |
| 129 |
regulator operating parameters for input/output voltage. |
| 130 |
|
| 131 |
If the regulator request passes all the constraint tests |
| 132 |
then the new regulator value is applied. |
| 133 |
|
| 134 |
|
| 135 |
Design |
| 136 |
====== |
| 137 |
|
| 138 |
The framework is designed and targeted at SoC based devices but may also be |
| 139 |
relevant to non SoC devices and is split into the following four interfaces:- |
| 140 |
|
| 141 |
|
| 142 |
1. Consumer driver interface. |
| 143 |
|
| 144 |
This uses a similar API to the kernel clock interface in that consumer |
| 145 |
drivers can get and put a regulator (like they can with clocks atm) and |
| 146 |
get/set voltage, current limit, mode, enable and disable. This should |
| 147 |
allow consumers complete control over their supply voltage and current |
| 148 |
limit. This also compiles out if not in use so drivers can be reused in |
| 149 |
systems with no regulator based power control. |
| 150 |
|
| 151 |
See Documentation/power/regulator/consumer.rst |
| 152 |
|
| 153 |
2. Regulator driver interface. |
| 154 |
|
| 155 |
This allows regulator drivers to register their regulators and provide |
| 156 |
operations to the core. It also has a notifier call chain for propagating |
| 157 |
regulator events to clients. |
| 158 |
|
| 159 |
See Documentation/power/regulator/regulator.rst |
| 160 |
|
| 161 |
3. Machine interface. |
| 162 |
|
| 163 |
This interface is for machine specific code and allows the creation of |
| 164 |
voltage/current domains (with constraints) for each regulator. It can |
| 165 |
provide regulator constraints that will prevent device damage through |
| 166 |
overvoltage or overcurrent caused by buggy client drivers. It also |
| 167 |
allows the creation of a regulator tree whereby some regulators are |
| 168 |
supplied by others (similar to a clock tree). |
| 169 |
|
| 170 |
See Documentation/power/regulator/machine.rst |
| 171 |
|
| 172 |
4. Userspace ABI. |
| 173 |
|
| 174 |
The framework also exports a lot of useful voltage/current/opmode data to |
| 175 |
userspace via sysfs. This could be used to help monitor device power |
| 176 |
consumption and status. |
| 177 |
|
| 178 |
See Documentation/ABI/testing/sysfs-class-regulator |