@@ -7,35 +7,35 @@ Synopsis
77Power supply class used to represent battery, UPS, AC or DC power supply
88properties to user-space.
99
10- It defines core set of attributes, which should be applicable to (almost)
10+ It defines a core set of attributes which should be applicable to (almost)
1111every power supply out there. Attributes are available via sysfs and uevent
1212interfaces.
1313
14- Each attribute has well defined meaning, up to unit of measure used. While
14+ Each attribute has a well- defined meaning, up to the unit of measure used. While
1515the attributes provided are believed to be universally applicable to any
1616power supply, specific monitoring hardware may not be able to provide them
1717all, so any of them may be skipped.
1818
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).
19+ The power supply class is extensible and allows drivers to define their own
20+ attributes. The core attribute set is subject to the standard Linux evolution
21+ (i.e., if some attribute is found to be applicable to many power
22+ supply types or their drivers, it can be added to the core set).
2323
24- It also integrates with LED framework, for the purpose of providing
24+ It also integrates with the LED framework, for the purpose of providing
2525typically expected feedback of battery charging/fully charged status and
2626AC/USB power supply online status. (Note that specific details of the
2727indication (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).
28+ user and/or specific machine defaults, per design principles of the LED
29+ framework.)
3030
3131
3232Attributes/properties
3333~~~~~~~~~~~~~~~~~~~~~
34- Power supply class has predefined set of attributes, this eliminates code
35- duplication across drivers. Power supply class insist on reusing its
34+ The power supply class has a predefined set of attributes. This eliminates code
35+ duplication across drivers. The power supply class insists on reusing its
3636predefined attributes *and * their units.
3737
38- So, userspace gets predictable set of attributes and their units for any
38+ So, userspace gets a predictable set of attributes and their units for any
3939kind of power supply, and can process/present them to a user in consistent
4040manner. Results for different power supplies and machines are also directly
4141comparable.
@@ -61,7 +61,7 @@ Attributes/properties detailed
6161| **Charge/Energy/Capacity - how to not confuse ** |
6262+--------------------------------------------------------------------------+
6363| **Because both "charge" (µAh) and "energy" (µWh) represents "capacity" |
64- | of battery, this class distinguish these terms. Don't mix them!** |
64+ | of battery, this class distinguishes these terms. Don't mix them!** |
6565| |
6666| - `CHARGE_* ` |
6767| attributes represents capacity in µAh only. |
8181
8282STATUS
8383 this attribute represents operating status (charging, full,
84- discharging (i.e. powering a load), etc.). This corresponds to
84+ discharging (i.e., powering a load), etc.). This corresponds to
8585 `BATTERY_STATUS_* ` values, as defined in battery.h.
8686
8787CHARGE_TYPE
@@ -92,22 +92,22 @@ CHARGE_TYPE
9292
9393AUTHENTIC
9494 indicates the power supply (battery or charger) connected
95- to the platform is authentic(1) or non authentic(0).
95+ to the platform is authentic(1) or non- authentic(0).
9696
9797HEALTH
98- represents health of the battery, values corresponds to
98+ represents health of the battery. Values corresponds to
9999 POWER_SUPPLY_HEALTH_*, defined in battery.h.
100100
101101VOLTAGE_OCV
102102 open circuit voltage of the battery.
103103
104104VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN
105105 design values for maximal and minimal power supply voltages.
106- Maximal/minimal means values of voltages when battery considered
106+ Maximal/minimal means values of voltages when battery is considered
107107 "full"/"empty" at normal conditions. Yes, there is no direct relation
108108 between voltage and battery capacity, but some dumb
109109 batteries use voltage for very approximated calculation of capacity.
110- Battery driver also can use this attribute just to inform userspace
110+ A battery driver also can use this attribute just to inform userspace
111111 about maximal and minimal voltage thresholds of a given battery.
112112
113113VOLTAGE_MAX, VOLTAGE_MIN
@@ -122,16 +122,16 @@ CURRENT_BOOT
122122 Reports the current measured during boot
123123
124124CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN
125- design charge values, when battery considered full/empty.
125+ design charge values, when battery is considered full/empty.
126126
127127ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN
128128 same as above but for energy.
129129
130130CHARGE_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
131+ These attributes mean "last remembered value of charge when battery
132+ became full/empty". They also could mean "value of charge when battery is
133133 considered full/empty at given conditions (temperature, age)".
134- I.e. these attributes represents real thresholds, not design values.
134+ I.e., these attributes represents real thresholds, not design values.
135135
136136ENERGY_FULL, ENERGY_EMPTY
137137 same as above but for energy.
@@ -153,12 +153,12 @@ CHARGE_TERM_CURRENT
153153CONSTANT_CHARGE_CURRENT
154154 constant charge current programmed by charger.
155155
156-
157156CONSTANT_CHARGE_CURRENT_MAX
158157 maximum charge current supported by the power supply object.
159158
160159CONSTANT_CHARGE_VOLTAGE
161160 constant charge voltage programmed by charger.
161+
162162CONSTANT_CHARGE_VOLTAGE_MAX
163163 maximum charge voltage supported by the power supply object.
164164
@@ -208,10 +208,10 @@ TEMP_MAX
208208
209209TIME_TO_EMPTY
210210 seconds left for battery to be considered empty
211- (i.e. while battery powers a load)
211+ (i.e., while battery powers a load)
212212TIME_TO_FULL
213213 seconds left for battery to be considered full
214- (i.e. while battery is charging)
214+ (i.e., while battery is charging)
215215
216216
217217Battery <-> external power supply interaction
@@ -220,13 +220,13 @@ Often power supplies are acting as supplies and supplicants at the same
220220time. Batteries are good example. So, batteries usually care if they're
221221externally powered or not.
222222
223- For that case, power supply class implements notification mechanism for
223+ For that case, the power supply class implements a notification mechanism for
224224batteries.
225225
226- External power supply (AC) lists supplicants (batteries) names in
226+ An external power supply (AC) lists supplicants (batteries) names in
227227"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.
228+ issued by an external power supply will notify supplicants via
229+ the external_power_changed callback.
230230
231231
232232Devicetree battery characteristics
@@ -241,14 +241,14 @@ battery node have names corresponding to elements in enum power_supply_property,
241241for naming consistency between sysfs attributes and battery node properties.
242242
243243
244- QA
245- ~~
244+ Q&A
245+ ~~~
246246
247247Q:
248248 Where is POWER_SUPPLY_PROP_XYZ attribute?
249249A:
250- If you cannot find attribute suitable for your driver needs, feel free
251- to add it and send patch along with your driver.
250+ If you cannot find an attribute suitable for your driver needs, feel free
251+ to add it and send a patch along with your driver.
252252
253253 The attributes available currently are the ones currently provided by the
254254 drivers written.
258258
259259
260260Q:
261- I have some very specific attribute (e.g. battery color), should I add
261+ I have some very specific attribute (e.g., battery color). Should I add
262262 this attribute to standard ones?
263263A:
264264 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
265+ it is useful. Of course, if the attribute in question is applicable to
266+ a large set of batteries, provided by many drivers, and/or comes from
267267 some general battery specification/standard, it may be a candidate to
268268 be added to the core attribute set.
269269
270270
271271Q:
272- Suppose, my battery monitoring chip/firmware does not provides capacity
272+ Suppose my battery monitoring chip/firmware does not provide capacity
273273 in percents, but provides charge_{now,full,empty}. Should I calculate
274274 percentage capacity manually, inside the driver, and register CAPACITY
275275 attribute? The same question about time_to_empty/time_to_full.
278278 directly measurable by the specific hardware available.
279279
280280 Inferring not available properties using some heuristics or mathematical
281- model is not subject of work for a battery driver. Such functionality
281+ model is not a subject of work for a battery driver. Such functionality
282282 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
283+ legacy APM API on top of the power supply class, uses a simple heuristic of
284284 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
285+ voltage and so on. But a full-fledged battery model is likely not a subject
286+ for the kernel at all, as it would require floating point calculations to
287+ deal with things like differential equations and Kalman filters. This is
288288 better be handled by batteryd/libbattery, yet to be written.
0 commit comments