1 =================================== 1 ===================================
2 Regulator Consumer Driver Interface 2 Regulator Consumer Driver Interface
3 =================================== 3 ===================================
4 4
5 This text describes the regulator interface fo 5 This text describes the regulator interface for consumer device drivers.
6 Please see overview.txt for a description of t 6 Please see overview.txt for a description of the terms used in this text.
7 7
8 8
9 1. Consumer Regulator Access (static & dynamic 9 1. Consumer Regulator Access (static & dynamic drivers)
10 ============================================== 10 =======================================================
11 11
12 A consumer driver can get access to its supply 12 A consumer driver can get access to its supply regulator by calling ::
13 13
14 regulator = regulator_get(dev, "Vcc"); 14 regulator = regulator_get(dev, "Vcc");
15 15
16 The consumer passes in its struct device point 16 The consumer passes in its struct device pointer and power supply ID. The core
17 then finds the correct regulator by consulting 17 then finds the correct regulator by consulting a machine specific lookup table.
18 If the lookup is successful then this call wil 18 If the lookup is successful then this call will return a pointer to the struct
19 regulator that supplies this consumer. 19 regulator that supplies this consumer.
20 20
21 To release the regulator the consumer driver s 21 To release the regulator the consumer driver should call ::
22 22
23 regulator_put(regulator); 23 regulator_put(regulator);
24 24
25 Consumers can be supplied by more than one reg 25 Consumers can be supplied by more than one regulator e.g. codec consumer with
26 analog and digital supplies :: 26 analog and digital supplies ::
27 27
28 digital = regulator_get(dev, "Vcc"); 28 digital = regulator_get(dev, "Vcc"); /* digital core */
29 analog = regulator_get(dev, "Avdd"); 29 analog = regulator_get(dev, "Avdd"); /* analog */
30 30
31 The regulator access functions regulator_get() 31 The regulator access functions regulator_get() and regulator_put() will
32 usually be called in your device drivers probe 32 usually be called in your device drivers probe() and remove() respectively.
33 33
34 34
35 2. Regulator Output Enable & Disable (static & 35 2. Regulator Output Enable & Disable (static & dynamic drivers)
36 ============================================== 36 ===============================================================
37 37
38 38
39 A consumer can enable its power supply by call 39 A consumer can enable its power supply by calling::
40 40
41 int regulator_enable(regulator); 41 int regulator_enable(regulator);
42 42
43 NOTE: 43 NOTE:
44 The supply may already be enabled before reg 44 The supply may already be enabled before regulator_enable() is called.
45 This may happen if the consumer shares the r 45 This may happen if the consumer shares the regulator or the regulator has been
46 previously enabled by bootloader or kernel b 46 previously enabled by bootloader or kernel board initialization code.
47 47
48 A consumer can determine if a regulator is ena 48 A consumer can determine if a regulator is enabled by calling::
49 49
50 int regulator_is_enabled(regulator); 50 int regulator_is_enabled(regulator);
51 51
52 This will return > zero when the regulator is 52 This will return > zero when the regulator is enabled.
53 53
54 54
55 A consumer can disable its supply when no long 55 A consumer can disable its supply when no longer needed by calling::
56 56
57 int regulator_disable(regulator); 57 int regulator_disable(regulator);
58 58
59 NOTE: 59 NOTE:
60 This may not disable the supply if it's shar 60 This may not disable the supply if it's shared with other consumers. The
61 regulator will only be disabled when the ena 61 regulator will only be disabled when the enabled reference count is zero.
62 62
63 Finally, a regulator can be forcefully disable 63 Finally, a regulator can be forcefully disabled in the case of an emergency::
64 64
65 int regulator_force_disable(regulator) 65 int regulator_force_disable(regulator);
66 66
67 NOTE: 67 NOTE:
68 this will immediately and forcefully shutdow 68 this will immediately and forcefully shutdown the regulator output. All
69 consumers will be powered off. 69 consumers will be powered off.
70 70
71 71
72 3. Regulator Voltage Control & Status (dynamic 72 3. Regulator Voltage Control & Status (dynamic drivers)
73 ============================================== 73 =======================================================
74 74
75 Some consumer drivers need to be able to dynam 75 Some consumer drivers need to be able to dynamically change their supply
76 voltage to match system operating points. e.g. 76 voltage to match system operating points. e.g. CPUfreq drivers can scale
77 voltage along with frequency to save power, SD 77 voltage along with frequency to save power, SD drivers may need to select the
78 correct card voltage, etc. 78 correct card voltage, etc.
79 79
80 Consumers can control their supply voltage by 80 Consumers can control their supply voltage by calling::
81 81
82 int regulator_set_voltage(regulator, m 82 int regulator_set_voltage(regulator, min_uV, max_uV);
83 83
84 Where min_uV and max_uV are the minimum and ma 84 Where min_uV and max_uV are the minimum and maximum acceptable voltages in
85 microvolts. 85 microvolts.
86 86
87 NOTE: this can be called when the regulator is 87 NOTE: this can be called when the regulator is enabled or disabled. If called
88 when enabled, then the voltage changes instant 88 when enabled, then the voltage changes instantly, otherwise the voltage
89 configuration changes and the voltage is physi 89 configuration changes and the voltage is physically set when the regulator is
90 next enabled. 90 next enabled.
91 91
92 The regulators configured voltage output can b 92 The regulators configured voltage output can be found by calling::
93 93
94 int regulator_get_voltage(regulator); 94 int regulator_get_voltage(regulator);
95 95
96 NOTE: 96 NOTE:
97 get_voltage() will return the configured out 97 get_voltage() will return the configured output voltage whether the
98 regulator is enabled or disabled and should 98 regulator is enabled or disabled and should NOT be used to determine regulator
99 output state. However this can be used in co 99 output state. However this can be used in conjunction with is_enabled() to
100 determine the regulator physical output volt 100 determine the regulator physical output voltage.
101 101
102 102
103 4. Regulator Current Limit Control & Status (d 103 4. Regulator Current Limit Control & Status (dynamic drivers)
104 ============================================== 104 =============================================================
105 105
106 Some consumer drivers need to be able to dynam 106 Some consumer drivers need to be able to dynamically change their supply
107 current limit to match system operating points 107 current limit to match system operating points. e.g. LCD backlight driver can
108 change the current limit to vary the backlight 108 change the current limit to vary the backlight brightness, USB drivers may want
109 to set the limit to 500mA when supplying power 109 to set the limit to 500mA when supplying power.
110 110
111 Consumers can control their supply current lim 111 Consumers can control their supply current limit by calling::
112 112
113 int regulator_set_current_limit(regula 113 int regulator_set_current_limit(regulator, min_uA, max_uA);
114 114
115 Where min_uA and max_uA are the minimum and ma 115 Where min_uA and max_uA are the minimum and maximum acceptable current limit in
116 microamps. 116 microamps.
117 117
118 NOTE: 118 NOTE:
119 this can be called when the regulator is ena 119 this can be called when the regulator is enabled or disabled. If called
120 when enabled, then the current limit changes 120 when enabled, then the current limit changes instantly, otherwise the current
121 limit configuration changes and the current 121 limit configuration changes and the current limit is physically set when the
122 regulator is next enabled. 122 regulator is next enabled.
123 123
124 A regulators current limit can be found by cal 124 A regulators current limit can be found by calling::
125 125
126 int regulator_get_current_limit(regula 126 int regulator_get_current_limit(regulator);
127 127
128 NOTE: 128 NOTE:
129 get_current_limit() will return the current 129 get_current_limit() will return the current limit whether the regulator
130 is enabled or disabled and should not be use 130 is enabled or disabled and should not be used to determine regulator current
131 load. 131 load.
132 132
133 133
134 5. Regulator Operating Mode Control & Status ( 134 5. Regulator Operating Mode Control & Status (dynamic drivers)
135 ============================================== 135 ==============================================================
136 136
137 Some consumers can further save system power b 137 Some consumers can further save system power by changing the operating mode of
138 their supply regulator to be more efficient wh 138 their supply regulator to be more efficient when the consumers operating state
139 changes. e.g. consumer driver is idle and subs 139 changes. e.g. consumer driver is idle and subsequently draws less current
140 140
141 Regulator operating mode can be changed indire 141 Regulator operating mode can be changed indirectly or directly.
142 142
143 Indirect operating mode control. 143 Indirect operating mode control.
144 -------------------------------- 144 --------------------------------
145 Consumer drivers can request a change in their 145 Consumer drivers can request a change in their supply regulator operating mode
146 by calling:: 146 by calling::
147 147
148 int regulator_set_load(struct regulato 148 int regulator_set_load(struct regulator *regulator, int load_uA);
149 149
150 This will cause the core to recalculate the to 150 This will cause the core to recalculate the total load on the regulator (based
151 on all its consumers) and change operating mod 151 on all its consumers) and change operating mode (if necessary and permitted)
152 to best match the current operating load. 152 to best match the current operating load.
153 153
154 The load_uA value can be determined from the c 154 The load_uA value can be determined from the consumer's datasheet. e.g. most
155 datasheets have tables showing the maximum cur 155 datasheets have tables showing the maximum current consumed in certain
156 situations. 156 situations.
157 157
158 Most consumers will use indirect operating mod 158 Most consumers will use indirect operating mode control since they have no
159 knowledge of the regulator or whether the regu 159 knowledge of the regulator or whether the regulator is shared with other
160 consumers. 160 consumers.
161 161
162 Direct operating mode control. 162 Direct operating mode control.
163 ------------------------------ 163 ------------------------------
164 164
165 Bespoke or tightly coupled drivers may want to 165 Bespoke or tightly coupled drivers may want to directly control regulator
166 operating mode depending on their operating po 166 operating mode depending on their operating point. This can be achieved by
167 calling:: 167 calling::
168 168
169 int regulator_set_mode(struct regulato 169 int regulator_set_mode(struct regulator *regulator, unsigned int mode);
170 unsigned int regulator_get_mode(struct 170 unsigned int regulator_get_mode(struct regulator *regulator);
171 171
172 Direct mode will only be used by consumers tha 172 Direct mode will only be used by consumers that *know* about the regulator and
173 are not sharing the regulator with other consu 173 are not sharing the regulator with other consumers.
174 174
175 175
176 6. Regulator Events 176 6. Regulator Events
177 =================== 177 ===================
178 178
179 Regulators can notify consumers of external ev 179 Regulators can notify consumers of external events. Events could be received by
180 consumers under regulator stress or failure co 180 consumers under regulator stress or failure conditions.
181 181
182 Consumers can register interest in regulator e 182 Consumers can register interest in regulator events by calling::
183 183
184 int regulator_register_notifier(struct 184 int regulator_register_notifier(struct regulator *regulator,
185 struct 185 struct notifier_block *nb);
186 186
187 Consumers can unregister interest by calling:: 187 Consumers can unregister interest by calling::
188 188
189 int regulator_unregister_notifier(stru 189 int regulator_unregister_notifier(struct regulator *regulator,
190 stru 190 struct notifier_block *nb);
191 191
192 Regulators use the kernel notifier framework t 192 Regulators use the kernel notifier framework to send event to their interested
193 consumers. 193 consumers.
194 194
195 7. Regulator Direct Register Access 195 7. Regulator Direct Register Access
196 =================================== 196 ===================================
197 197
198 Some kinds of power management hardware or fir 198 Some kinds of power management hardware or firmware are designed such that
199 they need to do low-level hardware access to r 199 they need to do low-level hardware access to regulators, with no involvement
200 from the kernel. Examples of such devices are: 200 from the kernel. Examples of such devices are:
201 201
202 - clocksource with a voltage-controlled oscill 202 - clocksource with a voltage-controlled oscillator and control logic to change
203 the supply voltage over I2C to achieve a des 203 the supply voltage over I2C to achieve a desired output clock rate
204 - thermal management firmware that can issue a 204 - thermal management firmware that can issue an arbitrary I2C transaction to
205 perform system poweroff during overtemperatu 205 perform system poweroff during overtemperature conditions
206 206
207 To set up such a device/firmware, various para 207 To set up such a device/firmware, various parameters like I2C address of the
208 regulator, addresses of various regulator regi 208 regulator, addresses of various regulator registers etc. need to be configured
209 to it. The regulator framework provides the fo 209 to it. The regulator framework provides the following helpers for querying
210 these details. 210 these details.
211 211
212 Bus-specific details, like I2C addresses or tr 212 Bus-specific details, like I2C addresses or transfer rates are handled by the
213 regmap framework. To get the regulator's regma 213 regmap framework. To get the regulator's regmap (if supported), use::
214 214
215 struct regmap *regulator_get_regmap(st 215 struct regmap *regulator_get_regmap(struct regulator *regulator);
216 216
217 To obtain the hardware register offset and bit 217 To obtain the hardware register offset and bitmask for the regulator's voltage
218 selector register, use:: 218 selector register, use::
219 219
220 int regulator_get_hardware_vsel_regist 220 int regulator_get_hardware_vsel_register(struct regulator *regulator,
221 221 unsigned *vsel_reg,
222 222 unsigned *vsel_mask);
223 223
224 To convert a regulator framework voltage selec 224 To convert a regulator framework voltage selector code (used by
225 regulator_list_voltage) to a hardware-specific 225 regulator_list_voltage) to a hardware-specific voltage selector that can be
226 directly written to the voltage selector regis 226 directly written to the voltage selector register, use::
227 227
228 int regulator_list_hardware_vsel(struc 228 int regulator_list_hardware_vsel(struct regulator *regulator,
229 unsig 229 unsigned selector);
230 230
231 To access the hardware for enabling/disabling 231 To access the hardware for enabling/disabling the regulator, consumers must
232 use regulator_get_exclusive(), as it can't wor 232 use regulator_get_exclusive(), as it can't work if there's more than one
233 consumer. To enable/disable regulator use:: 233 consumer. To enable/disable regulator use::
234 234
235 int regulator_hardware_enable(struct r 235 int regulator_hardware_enable(struct regulator *regulator, bool enable);
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.