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