Commit | Line | Data |
---|---|---|
151f4e2b MCC |
1 | ======================== |
2 | Linux power supply class | |
3 | ======================== | |
4 | ||
5 | Synopsis | |
6 | ~~~~~~~~ | |
7 | Power supply class used to represent battery, UPS, AC or DC power supply | |
8 | properties to user-space. | |
9 | ||
10 | It defines core set of attributes, which should be applicable to (almost) | |
11 | every power supply out there. Attributes are available via sysfs and uevent | |
12 | interfaces. | |
13 | ||
14 | Each attribute has well defined meaning, up to unit of measure used. While | |
15 | the attributes provided are believed to be universally applicable to any | |
16 | power supply, specific monitoring hardware may not be able to provide them | |
17 | all, so any of them may be skipped. | |
18 | ||
19 | Power supply class is extensible, and allows to define drivers own attributes. | |
20 | The core attribute set is subject to the standard Linux evolution (i.e. | |
21 | if it will be found that some attribute is applicable to many power supply | |
22 | types or their drivers, it can be added to the core set). | |
23 | ||
24 | It also integrates with LED framework, for the purpose of providing | |
25 | typically expected feedback of battery charging/fully charged status and | |
26 | AC/USB power supply online status. (Note that specific details of the | |
27 | indication (including whether to use it at all) are fully controllable by | |
28 | user and/or specific machine defaults, per design principles of LED | |
29 | framework). | |
30 | ||
31 | ||
32 | Attributes/properties | |
33 | ~~~~~~~~~~~~~~~~~~~~~ | |
34 | Power supply class has predefined set of attributes, this eliminates code | |
35 | duplication across drivers. Power supply class insist on reusing its | |
36 | predefined attributes *and* their units. | |
37 | ||
38 | So, userspace gets predictable set of attributes and their units for any | |
39 | kind of power supply, and can process/present them to a user in consistent | |
40 | manner. Results for different power supplies and machines are also directly | |
41 | comparable. | |
42 | ||
43 | See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c | |
44 | for the example how to declare and handle attributes. | |
45 | ||
46 | ||
47 | Units | |
48 | ~~~~~ | |
49 | Quoting include/linux/power_supply.h: | |
50 | ||
51 | All voltages, currents, charges, energies, time and temperatures in µV, | |
52 | µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise | |
53 | stated. It's driver's job to convert its raw values to units in which | |
54 | this class operates. | |
55 | ||
56 | ||
57 | Attributes/properties detailed | |
58 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
59 | ||
60 | +--------------------------------------------------------------------------+ | |
61 | | **Charge/Energy/Capacity - how to not confuse** | | |
62 | +--------------------------------------------------------------------------+ | |
63 | | **Because both "charge" (µAh) and "energy" (µWh) represents "capacity" | | |
64 | | of battery, this class distinguish these terms. Don't mix them!** | | |
65 | | | | |
66 | | - `CHARGE_*` | | |
67 | | attributes represents capacity in µAh only. | | |
68 | | - `ENERGY_*` | | |
69 | | attributes represents capacity in µWh only. | | |
70 | | - `CAPACITY` | | |
71 | | attribute represents capacity in *percents*, from 0 to 100. | | |
72 | +--------------------------------------------------------------------------+ | |
73 | ||
74 | Postfixes: | |
75 | ||
76 | _AVG | |
77 | *hardware* averaged value, use it if your hardware is really able to | |
78 | report averaged values. | |
79 | _NOW | |
80 | momentary/instantaneous values. | |
81 | ||
82 | STATUS | |
83 | this attribute represents operating status (charging, full, | |
84 | discharging (i.e. powering a load), etc.). This corresponds to | |
85 | `BATTERY_STATUS_*` values, as defined in battery.h. | |
86 | ||
87 | CHARGE_TYPE | |
88 | batteries can typically charge at different rates. | |
89 | This defines trickle and fast charges. For batteries that | |
90 | are already charged or discharging, 'n/a' can be displayed (or | |
91 | 'unknown', if the status is not known). | |
92 | ||
93 | AUTHENTIC | |
94 | indicates the power supply (battery or charger) connected | |
95 | to the platform is authentic(1) or non authentic(0). | |
96 | ||
97 | HEALTH | |
98 | represents health of the battery, values corresponds to | |
99 | POWER_SUPPLY_HEALTH_*, defined in battery.h. | |
100 | ||
101 | VOLTAGE_OCV | |
102 | open circuit voltage of the battery. | |
103 | ||
104 | VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN | |
105 | design values for maximal and minimal power supply voltages. | |
106 | Maximal/minimal means values of voltages when battery considered | |
107 | "full"/"empty" at normal conditions. Yes, there is no direct relation | |
108 | between voltage and battery capacity, but some dumb | |
109 | batteries use voltage for very approximated calculation of capacity. | |
110 | Battery driver also can use this attribute just to inform userspace | |
111 | about maximal and minimal voltage thresholds of a given battery. | |
112 | ||
113 | VOLTAGE_MAX, VOLTAGE_MIN | |
114 | same as _DESIGN voltage values except that these ones should be used | |
115 | if hardware could only guess (measure and retain) the thresholds of a | |
116 | given power supply. | |
117 | ||
118 | VOLTAGE_BOOT | |
119 | Reports the voltage measured during boot | |
120 | ||
121 | CURRENT_BOOT | |
122 | Reports the current measured during boot | |
123 | ||
124 | CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN | |
125 | design charge values, when battery considered full/empty. | |
126 | ||
127 | ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN | |
128 | same as above but for energy. | |
129 | ||
130 | CHARGE_FULL, CHARGE_EMPTY | |
131 | These attributes means "last remembered value of charge when battery | |
132 | became full/empty". It also could mean "value of charge when battery | |
133 | considered full/empty at given conditions (temperature, age)". | |
134 | I.e. these attributes represents real thresholds, not design values. | |
135 | ||
136 | ENERGY_FULL, ENERGY_EMPTY | |
137 | same as above but for energy. | |
138 | ||
139 | CHARGE_COUNTER | |
140 | the current charge counter (in µAh). This could easily | |
141 | be negative; there is no empty or full value. It is only useful for | |
142 | relative, time-based measurements. | |
143 | ||
144 | PRECHARGE_CURRENT | |
145 | the maximum charge current during precharge phase of charge cycle | |
146 | (typically 20% of battery capacity). | |
147 | ||
148 | CHARGE_TERM_CURRENT | |
149 | Charge termination current. The charge cycle terminates when battery | |
150 | voltage is above recharge threshold, and charge current is below | |
151 | this setting (typically 10% of battery capacity). | |
152 | ||
153 | CONSTANT_CHARGE_CURRENT | |
154 | constant charge current programmed by charger. | |
155 | ||
156 | ||
157 | CONSTANT_CHARGE_CURRENT_MAX | |
158 | maximum charge current supported by the power supply object. | |
159 | ||
160 | CONSTANT_CHARGE_VOLTAGE | |
161 | constant charge voltage programmed by charger. | |
162 | CONSTANT_CHARGE_VOLTAGE_MAX | |
163 | maximum charge voltage supported by the power supply object. | |
164 | ||
165 | INPUT_CURRENT_LIMIT | |
166 | input current limit programmed by charger. Indicates | |
167 | the current drawn from a charging source. | |
5fe7b600 LT |
168 | INPUT_VOLTAGE_LIMIT |
169 | input voltage limit programmed by charger. Indicates | |
170 | the voltage limit from a charging source. | |
171 | INPUT_POWER_LIMIT | |
172 | input power limit programmed by charger. Indicates | |
173 | the power limit from a charging source. | |
151f4e2b MCC |
174 | |
175 | CHARGE_CONTROL_LIMIT | |
176 | current charge control limit setting | |
177 | CHARGE_CONTROL_LIMIT_MAX | |
178 | maximum charge control limit setting | |
179 | ||
180 | CALIBRATE | |
181 | battery or coulomb counter calibration status | |
182 | ||
183 | CAPACITY | |
184 | capacity in percents. | |
185 | CAPACITY_ALERT_MIN | |
186 | minimum capacity alert value in percents. | |
187 | CAPACITY_ALERT_MAX | |
188 | maximum capacity alert value in percents. | |
189 | CAPACITY_LEVEL | |
190 | capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*. | |
191 | ||
192 | TEMP | |
193 | temperature of the power supply. | |
194 | TEMP_ALERT_MIN | |
195 | minimum battery temperature alert. | |
196 | TEMP_ALERT_MAX | |
197 | maximum battery temperature alert. | |
198 | TEMP_AMBIENT | |
199 | ambient temperature. | |
200 | TEMP_AMBIENT_ALERT_MIN | |
201 | minimum ambient temperature alert. | |
202 | TEMP_AMBIENT_ALERT_MAX | |
203 | maximum ambient temperature alert. | |
204 | TEMP_MIN | |
205 | minimum operatable temperature | |
206 | TEMP_MAX | |
207 | maximum operatable temperature | |
208 | ||
209 | TIME_TO_EMPTY | |
210 | seconds left for battery to be considered empty | |
211 | (i.e. while battery powers a load) | |
212 | TIME_TO_FULL | |
213 | seconds left for battery to be considered full | |
214 | (i.e. while battery is charging) | |
215 | ||
216 | ||
217 | Battery <-> external power supply interaction | |
218 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
219 | Often power supplies are acting as supplies and supplicants at the same | |
220 | time. Batteries are good example. So, batteries usually care if they're | |
221 | externally powered or not. | |
222 | ||
223 | For that case, power supply class implements notification mechanism for | |
224 | batteries. | |
225 | ||
226 | External power supply (AC) lists supplicants (batteries) names in | |
227 | "supplied_to" struct member, and each power_supply_changed() call | |
228 | issued by external power supply will notify supplicants via | |
229 | external_power_changed callback. | |
230 | ||
231 | ||
232 | Devicetree battery characteristics | |
233 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
234 | Drivers should call power_supply_get_battery_info() to obtain battery | |
235 | characteristics from a devicetree battery node, defined in | |
e4e40929 | 236 | Documentation/devicetree/bindings/power/supply/battery.yaml. This is |
151f4e2b MCC |
237 | implemented in drivers/power/supply/bq27xxx_battery.c. |
238 | ||
239 | Properties in struct power_supply_battery_info and their counterparts in the | |
240 | battery node have names corresponding to elements in enum power_supply_property, | |
241 | for naming consistency between sysfs attributes and battery node properties. | |
242 | ||
243 | ||
244 | QA | |
245 | ~~ | |
246 | ||
247 | Q: | |
248 | Where is POWER_SUPPLY_PROP_XYZ attribute? | |
249 | A: | |
250 | If you cannot find attribute suitable for your driver needs, feel free | |
251 | to add it and send patch along with your driver. | |
252 | ||
253 | The attributes available currently are the ones currently provided by the | |
254 | drivers written. | |
255 | ||
256 | Good candidates to add in future: model/part#, cycle_time, manufacturer, | |
257 | etc. | |
258 | ||
259 | ||
260 | Q: | |
261 | I have some very specific attribute (e.g. battery color), should I add | |
262 | this attribute to standard ones? | |
263 | A: | |
264 | Most likely, no. Such attribute can be placed in the driver itself, if | |
265 | it is useful. Of course, if the attribute in question applicable to | |
266 | large set of batteries, provided by many drivers, and/or comes from | |
267 | some general battery specification/standard, it may be a candidate to | |
268 | be added to the core attribute set. | |
269 | ||
270 | ||
271 | Q: | |
272 | Suppose, my battery monitoring chip/firmware does not provides capacity | |
273 | in percents, but provides charge_{now,full,empty}. Should I calculate | |
274 | percentage capacity manually, inside the driver, and register CAPACITY | |
275 | attribute? The same question about time_to_empty/time_to_full. | |
276 | A: | |
277 | Most likely, no. This class is designed to export properties which are | |
278 | directly measurable by the specific hardware available. | |
279 | ||
280 | Inferring not available properties using some heuristics or mathematical | |
281 | model is not subject of work for a battery driver. Such functionality | |
282 | should be factored out, and in fact, apm_power, the driver to serve | |
283 | legacy APM API on top of power supply class, uses a simple heuristic of | |
284 | approximating remaining battery capacity based on its charge, current, | |
285 | voltage and so on. But full-fledged battery model is likely not subject | |
286 | for kernel at all, as it would require floating point calculation to deal | |
287 | with things like differential equations and Kalman filters. This is | |
288 | better be handled by batteryd/libbattery, yet to be written. |