power_supply_class.rst (10684B)
1======================== 2Linux power supply class 3======================== 4 5Synopsis 6~~~~~~~~ 7Power supply class used to represent battery, UPS, AC or DC power supply 8properties to user-space. 9 10It defines core set of attributes, which should be applicable to (almost) 11every power supply out there. Attributes are available via sysfs and uevent 12interfaces. 13 14Each attribute has well defined meaning, up to unit of measure used. While 15the attributes provided are believed to be universally applicable to any 16power supply, specific monitoring hardware may not be able to provide them 17all, so any of them may be skipped. 18 19Power supply class is extensible, and allows to define drivers own attributes. 20The core attribute set is subject to the standard Linux evolution (i.e. 21if it will be found that some attribute is applicable to many power supply 22types or their drivers, it can be added to the core set). 23 24It also integrates with LED framework, for the purpose of providing 25typically expected feedback of battery charging/fully charged status and 26AC/USB power supply online status. (Note that specific details of the 27indication (including whether to use it at all) are fully controllable by 28user and/or specific machine defaults, per design principles of LED 29framework). 30 31 32Attributes/properties 33~~~~~~~~~~~~~~~~~~~~~ 34Power supply class has predefined set of attributes, this eliminates code 35duplication across drivers. Power supply class insist on reusing its 36predefined attributes *and* their units. 37 38So, userspace gets predictable set of attributes and their units for any 39kind of power supply, and can process/present them to a user in consistent 40manner. Results for different power supplies and machines are also directly 41comparable. 42 43See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c 44for the example how to declare and handle attributes. 45 46 47Units 48~~~~~ 49Quoting 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 57Attributes/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 74Postfixes: 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 82STATUS 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 87CHARGE_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 93AUTHENTIC 94 indicates the power supply (battery or charger) connected 95 to the platform is authentic(1) or non authentic(0). 96 97HEALTH 98 represents health of the battery, values corresponds to 99 POWER_SUPPLY_HEALTH_*, defined in battery.h. 100 101VOLTAGE_OCV 102 open circuit voltage of the battery. 103 104VOLTAGE_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 113VOLTAGE_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 118VOLTAGE_BOOT 119 Reports the voltage measured during boot 120 121CURRENT_BOOT 122 Reports the current measured during boot 123 124CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN 125 design charge values, when battery considered full/empty. 126 127ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN 128 same as above but for energy. 129 130CHARGE_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 136ENERGY_FULL, ENERGY_EMPTY 137 same as above but for energy. 138 139CHARGE_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 144PRECHARGE_CURRENT 145 the maximum charge current during precharge phase of charge cycle 146 (typically 20% of battery capacity). 147 148CHARGE_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 153CONSTANT_CHARGE_CURRENT 154 constant charge current programmed by charger. 155 156 157CONSTANT_CHARGE_CURRENT_MAX 158 maximum charge current supported by the power supply object. 159 160CONSTANT_CHARGE_VOLTAGE 161 constant charge voltage programmed by charger. 162CONSTANT_CHARGE_VOLTAGE_MAX 163 maximum charge voltage supported by the power supply object. 164 165INPUT_CURRENT_LIMIT 166 input current limit programmed by charger. Indicates 167 the current drawn from a charging source. 168INPUT_VOLTAGE_LIMIT 169 input voltage limit programmed by charger. Indicates 170 the voltage limit from a charging source. 171INPUT_POWER_LIMIT 172 input power limit programmed by charger. Indicates 173 the power limit from a charging source. 174 175CHARGE_CONTROL_LIMIT 176 current charge control limit setting 177CHARGE_CONTROL_LIMIT_MAX 178 maximum charge control limit setting 179 180CALIBRATE 181 battery or coulomb counter calibration status 182 183CAPACITY 184 capacity in percents. 185CAPACITY_ALERT_MIN 186 minimum capacity alert value in percents. 187CAPACITY_ALERT_MAX 188 maximum capacity alert value in percents. 189CAPACITY_LEVEL 190 capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*. 191 192TEMP 193 temperature of the power supply. 194TEMP_ALERT_MIN 195 minimum battery temperature alert. 196TEMP_ALERT_MAX 197 maximum battery temperature alert. 198TEMP_AMBIENT 199 ambient temperature. 200TEMP_AMBIENT_ALERT_MIN 201 minimum ambient temperature alert. 202TEMP_AMBIENT_ALERT_MAX 203 maximum ambient temperature alert. 204TEMP_MIN 205 minimum operatable temperature 206TEMP_MAX 207 maximum operatable temperature 208 209TIME_TO_EMPTY 210 seconds left for battery to be considered empty 211 (i.e. while battery powers a load) 212TIME_TO_FULL 213 seconds left for battery to be considered full 214 (i.e. while battery is charging) 215 216 217Battery <-> external power supply interaction 218~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 219Often power supplies are acting as supplies and supplicants at the same 220time. Batteries are good example. So, batteries usually care if they're 221externally powered or not. 222 223For that case, power supply class implements notification mechanism for 224batteries. 225 226External power supply (AC) lists supplicants (batteries) names in 227"supplied_to" struct member, and each power_supply_changed() call 228issued by external power supply will notify supplicants via 229external_power_changed callback. 230 231 232Devicetree battery characteristics 233~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 234Drivers should call power_supply_get_battery_info() to obtain battery 235characteristics from a devicetree battery node, defined in 236Documentation/devicetree/bindings/power/supply/battery.yaml. This is 237implemented in drivers/power/supply/bq27xxx_battery.c. 238 239Properties in struct power_supply_battery_info and their counterparts in the 240battery node have names corresponding to elements in enum power_supply_property, 241for naming consistency between sysfs attributes and battery node properties. 242 243 244QA 245~~ 246 247Q: 248 Where is POWER_SUPPLY_PROP_XYZ attribute? 249A: 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 260Q: 261 I have some very specific attribute (e.g. battery color), should I add 262 this attribute to standard ones? 263A: 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 271Q: 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. 276A: 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.