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