Documentation/power/power_supply_class.rst

2 Linux power supply class
7 Power supply class used to represent battery, UPS, AC or DC power supply
8 properties to user-space.
11 every power supply out there. Attributes are available via sysfs and uevent
16 power supply, specific monitoring hardware may not be able to provide them
19 Power supply class is extensible, and allows to define drivers own attributes.
21 if it will be found that some attribute is applicable to many power supply
25 typically expected feedback of battery charging/fully charged status and
26 AC/USB power supply online status. (Note that specific details of the
34 Power supply class has predefined set of attributes, this eliminates code
35 duplication across drivers. Power supply class insist on reusing its
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
43 See drivers/power/supply/ds2760_battery.c for the example how to declare
60 +--------------------------------------------------------------------------+
61 |               **Charge/Energy/Capacity - how to not confuse**            |
62 +--------------------------------------------------------------------------+
64 | of battery, this class distinguish these terms. Don't mix them!**        |
66 | - `CHARGE_*`                                                             |
68 | - `ENERGY_*`                                                             |
70 | - `CAPACITY`                                                             |
72 +--------------------------------------------------------------------------+
85   `BATTERY_STATUS_*` values, as defined in battery.h.
94   indicates the power supply (battery or charger) connected
98   represents health of the battery, values corresponds to
99   POWER_SUPPLY_HEALTH_*, defined in battery.h.
102   open circuit voltage of the battery.
105   design values for maximal and minimal power supply voltages.
106   Maximal/minimal means values of voltages when battery considered
108   between voltage and battery capacity, but some dumb
110   Battery driver also can use this attribute just to inform userspace
111   about maximal and minimal voltage thresholds of a given battery.
116   given power supply.
125   design charge values, when battery considered full/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
142   relative, time-based measurements.
146   (typically 20% of battery capacity).
149   Charge termination current. The charge cycle terminates when battery
151   this setting (typically 10% of battery capacity).
158   maximum charge current supported by the power supply object.
163   maximum charge voltage supported by the power supply object.
172   input power limit programmed by charger. Indicates
173   the power limit from a charging source.
181   battery or coulomb counter calibration status
193   temperature of the power supply.
195   minimum battery temperature alert.
197   maximum battery temperature alert.
210   seconds left for battery to be considered empty
211   (i.e. while battery powers a load)
213   seconds left for battery to be considered full
214   (i.e. while battery is charging)
217 Battery <-> external power supply interaction
219 Often power supplies are acting as supplies and supplicants at the same
223 For that case, power supply class implements notification mechanism for
226 External power supply (AC) lists supplicants (batteries) names in
228 issued by external power supply will notify supplicants via
232 Devicetree battery characteristics
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.
240 battery node have names corresponding to elements in enum power_supply_property,
241 for naming consistency between sysfs attributes and battery node properties.
261    I have some very specific attribute (e.g. battery color), should I add
267    some general battery specification/standard, it may be a candidate to
272    Suppose, my battery monitoring chip/firmware does not provides capacity
281    model is not subject of work for a battery driver. Such functionality
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