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 for the example how to declare
44 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.
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.
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
236 Documentation/devicetree/bindings/power/supply/battery.yaml. This is
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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.