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