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