2 .\" Copyright (c) 2019 Takanori Watanabe
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd ACPI battery management subsystem
39 is a driver for battery management features of the ACPI module.
41 An ACPI-compatible battery device supports either a Control
42 Method Battery interface or a Smart Battery subsystem interface.
43 The former is accessed by the AML
44 .Pq ACPI Machine Language
46 and the latter is controlled directly through the ACPI EC
47 .Pq Embedded Controller
48 typically via an SMBus interface.
50 This driver supports the
54 interfaces as well as the
56 event notification interface.
60 driver takes a single integer value for the battery unit
61 number as an argument,
62 and returns a specific structure for each request.
64 .Dv ACPI_BATTERY_ALL_UNITS
65 specifies all of the attached units
66 and reports accumulated information.
67 .Bl -tag -width indent
68 .It Dv ACPIIO_BATT_GET_UNITS Vt int
69 Returns the number of battery units in the system.
70 The unit number argument will be ignored.
71 .It Dv ACPIIO_BATT_GET_BATTINFO Vt struct acpi_battinfo
72 Returns the following:
73 .Bl -tag -width indent
75 Battery capacity in percent,
77 Remaining battery life in minutes,
79 Current status of the battery encoded in the following:
80 .Bl -tag -width indent
81 .It Dv ACPI_BATT_STAT_DISCHARG Pq 0x0001
82 Battery is discharging,
83 .It Dv ACPI_BATT_STAT_CHARGING Pq 0x0002
84 Battery is being charged, or
85 .It Dv ACPI_BATT_STAT_CRITICAL Pq 0x0004
86 Remaining battery life is critically low.
89 Note that the status bits of each battery will be
91 .Dv ACPI_BATTERY_ALL_UNITS
94 Current battery discharging rate in mW.
96 means not discharging right now.
98 .It Dv ACPIIO_BATT_GET_BIX Vt struct acpi_bix
99 Returns battery information given by the ACPI
100 .Li _BIX Pq Battery Information
102 which is the static portion of the Control Method
104 In the case of a Smart Battery attached to
105 SMBus or a Control Method Battery with a
108 this ioctl will build a
110 structure based on the obtained information
112 .Bl -tag -width indent
114 Revision number of the object.
115 There are the following well-known values:
116 .Bl -tag -width indent
117 .It Dv ACPI_BIX_REV_0 Pq 0x0000
121 .It Dv ACPI_BIX_REV_1 Pq 0x0001
125 .It Dv ACPI_BIX_REV_BIF Pq 0xffff
128 object built from the
130 object found on the system.
133 Note that this field should be checked by using
134 .Fn ACPI_BIX_REV_MIN_CHECK var rev
135 macro when checking the minimum revision number.
137 Indicates the units used by the battery to report its
138 capacity and charge rate encoded in the following:
139 .Bl -tag -width indent
140 .It ACPI_BIX_UNITS_MW Pq 0x00000000
143 .It ACPI_BIX_UNITS_MA Pq 0x00000001
148 Note that capacity is expressed in mWh or mAh,
149 and rate is expressed in mW or mA,
152 The Battery's design capacity,
153 which is the nominal capacity of a new battery.
154 This is expressed as power or current depending on
158 Predicted battery capacity when fully charged.
159 Typically this will decrease every charging cycle.
162 .Bl -tag -width indent
163 .It 0x00000000 Primary cell Pq non-rechargable
164 .It 0x00000001 Secondary cell Pq rechargable
167 Design voltage in mV,
168 which is the nominal voltage of a new battery.
170 Design capacity of warning.
171 When a discharging battery device reaches this capacity,
172 notification is sent to the system.
174 Design capacity of low.
177 The number of cycles the battery has experienced.
178 A cycle means an amount of discharge occurred which was
179 approximately equal to the value of Design Capacity.
182 The accuracy of the battery capacity measurement,
183 in thousandth of a percent.
186 The Maximum Sampling Time of the battery in
188 This is the maximum duration between two consecutive
189 measurements of the battery's capacities specified in
191 If two succeeding readings of
193 beyond this duration occur,
194 two different results can be returned.
197 The Minimum Sampling Time of the battery in
201 The Maximum Average Interval of the battery in
203 This is the length of time within which the battery
204 averages the capacity measurements specified in
206 The Sampling Time specifies the frequency of measurements,
207 and the Average Interval specifies the width of the time
208 window of every measurement.
211 The Minimum Average Interval of the battery in
214 Battery capacity granularity between
218 This is expressed as power or current depending on
222 Battery capacity granularity between
226 This is expressed as power or current depending on
230 Model number of the battery as a string.
232 Serial number of the battery as a string.
234 Type identifier of the battery as a string.
236 OEM-specific information of the battery as a string.
239 Battery swapping capability encoded in the following:
240 .Bl -tag -width indent
241 .It ACPI_BIX_SCAP_NO Pq 0x00000000
243 .It ACPI_BIX_SCAP_COLD Pq 0x00000001
245 .It ACPI_BIX_SCAP_HOT Pq 0x00000010
249 .It Dv ACPIIO_BATT_GET_BIF Vt struct acpi_bif
251 Returns battery information given by the ACPI
252 .Li _BIF Pq Battery Information
254 which was deprecated in ACPI 4.0 specification.
255 The data structure is a subset of
256 .Vt struct acpi_bix .
258 Note that this ioctl will built a
260 structure based on the obtained information
261 even if this object is not available and a
264 .It ACPIIO_BATT_GET_BST Vt struct acpi_bst
265 Returns battery information given by the ACPI
266 .Li _BST Pq Battery Status
268 which is the present battery status.
269 In the case of a Smart Battery attached to SMBus,
270 this ioctl will build a
272 structure based on the obtained information
274 .Bl -tag -width indent
277 The value is encoded in the same way as
280 .Vt struct acpi_battinfo .
282 Battery present rate of charging or discharging.
283 The unit of the value depends on
286 .Vt struct acpi_bif .
288 Battery remaining capacity.
289 The unit of this value depends on
292 .Vt struct acpi_bif .
294 Battery present voltage.
300 variables export battery status.
301 Note that they are accumulated status of all of the
303 .Bl -tag -width indent
304 .It Va hw.acpi.battery.info_expire
305 Information cache expiration time in seconds.
306 The battery information obtained by
310 object will be stored and reused for successive
311 read access to this MIB within the specified period.
312 .It Va hw.acpi.battery.units
313 Number of battery units in the system.
314 .It Va hw.acpi.battery.state
315 Current battery charging status.
319 .Vt struct acpi_battinfo .
320 .It Va hw.acpi.battery.rate
321 Current battery discharging rate in mW.
322 .It Va hw.acpi.battery.time
323 Remaining battery life in minutes.
324 If the battery is not discharging,
327 .It Va hw.acpi.battery.life
328 Battery capacity in percent.
330 .Sh EVENT NOTIFICATIONS
331 Battery-related event notifications are sent
332 to the userland via the
340 Note that notifications are supported only by
341 the Control Method Battery.
345 driver sends events with the following attributes:
347 .Bl -tag -width "subsystem" -compact
353 The fully qualified battery object path as in the ASL.
355 An integer designating the event:
357 .Bl -tag -width indent -compact
359 Battery status was changed.
361 Battery information was changed.
369 .An Nate Lawson Aq Mt njl@FreeBSD.org ,
370 .An Munehiro Matsuda ,
371 .An Takanori Watanabe Aq Mt takawata@FreeBSD.org ,
372 .An Mitsuru IWASAKI Aq Mt iwasaki@FreeBSD.org ,
373 .An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org ,
375 .An Hiroki Sato Aq Mt hrs@FreeBSD.org .
377 This manual page was written by
378 .An Takanori Watanabe Aq Mt takawata@FreeBSD.org
380 .An Hiroki Sato Aq Mt hrs@FreeBSD.org .