0001 ========================
0002 Linux power supply class
0003 ========================
0004
0005 Synopsis
0006 ~~~~~~~~
0007 Power supply class used to represent battery, UPS, AC or DC power supply
0008 properties to user-space.
0009
0010 It defines core set of attributes, which should be applicable to (almost)
0011 every power supply out there. Attributes are available via sysfs and uevent
0012 interfaces.
0013
0014 Each attribute has well defined meaning, up to unit of measure used. While
0015 the attributes provided are believed to be universally applicable to any
0016 power supply, specific monitoring hardware may not be able to provide them
0017 all, so any of them may be skipped.
0018
0019 Power supply class is extensible, and allows to define drivers own attributes.
0020 The core attribute set is subject to the standard Linux evolution (i.e.
0021 if it will be found that some attribute is applicable to many power supply
0022 types or their drivers, it can be added to the core set).
0023
0024 It also integrates with LED framework, for the purpose of providing
0025 typically expected feedback of battery charging/fully charged status and
0026 AC/USB power supply online status. (Note that specific details of the
0027 indication (including whether to use it at all) are fully controllable by
0028 user and/or specific machine defaults, per design principles of LED
0029 framework).
0030
0031
0032 Attributes/properties
0033 ~~~~~~~~~~~~~~~~~~~~~
0034 Power supply class has predefined set of attributes, this eliminates code
0035 duplication across drivers. Power supply class insist on reusing its
0036 predefined attributes *and* their units.
0037
0038 So, userspace gets predictable set of attributes and their units for any
0039 kind of power supply, and can process/present them to a user in consistent
0040 manner. Results for different power supplies and machines are also directly
0041 comparable.
0042
0043 See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
0044 for the example how to declare and handle attributes.
0045
0046
0047 Units
0048 ~~~~~
0049 Quoting include/linux/power_supply.h:
0050
0051 All voltages, currents, charges, energies, time and temperatures in µV,
0052 µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
0053 stated. It's driver's job to convert its raw values to units in which
0054 this class operates.
0055
0056
0057 Attributes/properties detailed
0058 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0059
0060 +--------------------------------------------------------------------------+
0061 | **Charge/Energy/Capacity - how to not confuse** |
0062 +--------------------------------------------------------------------------+
0063 | **Because both "charge" (µAh) and "energy" (µWh) represents "capacity" |
0064 | of battery, this class distinguish these terms. Don't mix them!** |
0065 | |
0066 | - `CHARGE_*` |
0067 | attributes represents capacity in µAh only. |
0068 | - `ENERGY_*` |
0069 | attributes represents capacity in µWh only. |
0070 | - `CAPACITY` |
0071 | attribute represents capacity in *percents*, from 0 to 100. |
0072 +--------------------------------------------------------------------------+
0073
0074 Postfixes:
0075
0076 _AVG
0077 *hardware* averaged value, use it if your hardware is really able to
0078 report averaged values.
0079 _NOW
0080 momentary/instantaneous values.
0081
0082 STATUS
0083 this attribute represents operating status (charging, full,
0084 discharging (i.e. powering a load), etc.). This corresponds to
0085 `BATTERY_STATUS_*` values, as defined in battery.h.
0086
0087 CHARGE_TYPE
0088 batteries can typically charge at different rates.
0089 This defines trickle and fast charges. For batteries that
0090 are already charged or discharging, 'n/a' can be displayed (or
0091 'unknown', if the status is not known).
0092
0093 AUTHENTIC
0094 indicates the power supply (battery or charger) connected
0095 to the platform is authentic(1) or non authentic(0).
0096
0097 HEALTH
0098 represents health of the battery, values corresponds to
0099 POWER_SUPPLY_HEALTH_*, defined in battery.h.
0100
0101 VOLTAGE_OCV
0102 open circuit voltage of the battery.
0103
0104 VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN
0105 design values for maximal and minimal power supply voltages.
0106 Maximal/minimal means values of voltages when battery considered
0107 "full"/"empty" at normal conditions. Yes, there is no direct relation
0108 between voltage and battery capacity, but some dumb
0109 batteries use voltage for very approximated calculation of capacity.
0110 Battery driver also can use this attribute just to inform userspace
0111 about maximal and minimal voltage thresholds of a given battery.
0112
0113 VOLTAGE_MAX, VOLTAGE_MIN
0114 same as _DESIGN voltage values except that these ones should be used
0115 if hardware could only guess (measure and retain) the thresholds of a
0116 given power supply.
0117
0118 VOLTAGE_BOOT
0119 Reports the voltage measured during boot
0120
0121 CURRENT_BOOT
0122 Reports the current measured during boot
0123
0124 CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN
0125 design charge values, when battery considered full/empty.
0126
0127 ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN
0128 same as above but for energy.
0129
0130 CHARGE_FULL, CHARGE_EMPTY
0131 These attributes means "last remembered value of charge when battery
0132 became full/empty". It also could mean "value of charge when battery
0133 considered full/empty at given conditions (temperature, age)".
0134 I.e. these attributes represents real thresholds, not design values.
0135
0136 ENERGY_FULL, ENERGY_EMPTY
0137 same as above but for energy.
0138
0139 CHARGE_COUNTER
0140 the current charge counter (in µAh). This could easily
0141 be negative; there is no empty or full value. It is only useful for
0142 relative, time-based measurements.
0143
0144 PRECHARGE_CURRENT
0145 the maximum charge current during precharge phase of charge cycle
0146 (typically 20% of battery capacity).
0147
0148 CHARGE_TERM_CURRENT
0149 Charge termination current. The charge cycle terminates when battery
0150 voltage is above recharge threshold, and charge current is below
0151 this setting (typically 10% of battery capacity).
0152
0153 CONSTANT_CHARGE_CURRENT
0154 constant charge current programmed by charger.
0155
0156
0157 CONSTANT_CHARGE_CURRENT_MAX
0158 maximum charge current supported by the power supply object.
0159
0160 CONSTANT_CHARGE_VOLTAGE
0161 constant charge voltage programmed by charger.
0162 CONSTANT_CHARGE_VOLTAGE_MAX
0163 maximum charge voltage supported by the power supply object.
0164
0165 INPUT_CURRENT_LIMIT
0166 input current limit programmed by charger. Indicates
0167 the current drawn from a charging source.
0168 INPUT_VOLTAGE_LIMIT
0169 input voltage limit programmed by charger. Indicates
0170 the voltage limit from a charging source.
0171 INPUT_POWER_LIMIT
0172 input power limit programmed by charger. Indicates
0173 the power limit from a charging source.
0174
0175 CHARGE_CONTROL_LIMIT
0176 current charge control limit setting
0177 CHARGE_CONTROL_LIMIT_MAX
0178 maximum charge control limit setting
0179
0180 CALIBRATE
0181 battery or coulomb counter calibration status
0182
0183 CAPACITY
0184 capacity in percents.
0185 CAPACITY_ALERT_MIN
0186 minimum capacity alert value in percents.
0187 CAPACITY_ALERT_MAX
0188 maximum capacity alert value in percents.
0189 CAPACITY_LEVEL
0190 capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*.
0191
0192 TEMP
0193 temperature of the power supply.
0194 TEMP_ALERT_MIN
0195 minimum battery temperature alert.
0196 TEMP_ALERT_MAX
0197 maximum battery temperature alert.
0198 TEMP_AMBIENT
0199 ambient temperature.
0200 TEMP_AMBIENT_ALERT_MIN
0201 minimum ambient temperature alert.
0202 TEMP_AMBIENT_ALERT_MAX
0203 maximum ambient temperature alert.
0204 TEMP_MIN
0205 minimum operatable temperature
0206 TEMP_MAX
0207 maximum operatable temperature
0208
0209 TIME_TO_EMPTY
0210 seconds left for battery to be considered empty
0211 (i.e. while battery powers a load)
0212 TIME_TO_FULL
0213 seconds left for battery to be considered full
0214 (i.e. while battery is charging)
0215
0216
0217 Battery <-> external power supply interaction
0218 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0219 Often power supplies are acting as supplies and supplicants at the same
0220 time. Batteries are good example. So, batteries usually care if they're
0221 externally powered or not.
0222
0223 For that case, power supply class implements notification mechanism for
0224 batteries.
0225
0226 External power supply (AC) lists supplicants (batteries) names in
0227 "supplied_to" struct member, and each power_supply_changed() call
0228 issued by external power supply will notify supplicants via
0229 external_power_changed callback.
0230
0231
0232 Devicetree battery characteristics
0233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0234 Drivers should call power_supply_get_battery_info() to obtain battery
0235 characteristics from a devicetree battery node, defined in
0236 Documentation/devicetree/bindings/power/supply/battery.yaml. This is
0237 implemented in drivers/power/supply/bq27xxx_battery.c.
0238
0239 Properties in struct power_supply_battery_info and their counterparts in the
0240 battery node have names corresponding to elements in enum power_supply_property,
0241 for naming consistency between sysfs attributes and battery node properties.
0242
0243
0244 QA
0245 ~~
0246
0247 Q:
0248 Where is POWER_SUPPLY_PROP_XYZ attribute?
0249 A:
0250 If you cannot find attribute suitable for your driver needs, feel free
0251 to add it and send patch along with your driver.
0252
0253 The attributes available currently are the ones currently provided by the
0254 drivers written.
0255
0256 Good candidates to add in future: model/part#, cycle_time, manufacturer,
0257 etc.
0258
0259
0260 Q:
0261 I have some very specific attribute (e.g. battery color), should I add
0262 this attribute to standard ones?
0263 A:
0264 Most likely, no. Such attribute can be placed in the driver itself, if
0265 it is useful. Of course, if the attribute in question applicable to
0266 large set of batteries, provided by many drivers, and/or comes from
0267 some general battery specification/standard, it may be a candidate to
0268 be added to the core attribute set.
0269
0270
0271 Q:
0272 Suppose, my battery monitoring chip/firmware does not provides capacity
0273 in percents, but provides charge_{now,full,empty}. Should I calculate
0274 percentage capacity manually, inside the driver, and register CAPACITY
0275 attribute? The same question about time_to_empty/time_to_full.
0276 A:
0277 Most likely, no. This class is designed to export properties which are
0278 directly measurable by the specific hardware available.
0279
0280 Inferring not available properties using some heuristics or mathematical
0281 model is not subject of work for a battery driver. Such functionality
0282 should be factored out, and in fact, apm_power, the driver to serve
0283 legacy APM API on top of power supply class, uses a simple heuristic of
0284 approximating remaining battery capacity based on its charge, current,
0285 voltage and so on. But full-fledged battery model is likely not subject
0286 for kernel at all, as it would require floating point calculation to deal
0287 with things like differential equations and Kalman filters. This is
0288 better be handled by batteryd/libbattery, yet to be written.
