acpi_battery —
ACPI battery management subsystem
device acpi
The
acpi_battery is a driver for battery management
features of the ACPI module.
An ACPI-compatible battery device supports either a Control Method Battery
interface or a Smart Battery subsystem interface. The former is accessed by
the AML (ACPI Machine Language) code control methods, and the latter is
controlled directly through the ACPI EC (Embedded Controller) typically via an
SMBus interface.
This driver supports the
sysctl(8) and
ioctl(2) interfaces as well as the
devd(8) event notification interface.
Every ioctl for the
acpi_battery driver takes a
single integer value for the battery unit number as an argument, and returns a
specific structure for each request. A special unit number
ACPI_BATTERY_ALL_UNITS specifies all of the
attached units and reports accumulated information.
-
ACPIIO_BATT_GET_UNITS
int
- Returns the number of battery units in the system. The unit
number argument will be ignored.
-
ACPIIO_BATT_GET_BATTINFO
struct acpi_battinfo
- Returns the following:
- cap
- Battery capacity in percent,
- min
- Remaining battery life in minutes,
- state
- Current status of the battery encoded in the following:
-
ACPI_BATT_STAT_DISCHARG
(0x0001)
- Battery is discharging,
-
ACPI_BATT_STAT_CHARGING
(0x0002)
- Battery is being charged, or
-
ACPI_BATT_STAT_CRITICAL
(0x0004)
- Remaining battery life is critically low.
Note that the status bits of each battery will be consolidated when
ACPI_BATTERY_ALL_UNITS is
specified.
- rate
- Current battery discharging rate in mW.
-1 means not discharging right now.
-
ACPIIO_BATT_GET_BIX
struct acpi_bix
- Returns battery information given by the ACPI
_BIX (Battery Information) object, which is the
static portion of the Control Method Battery information. In the case of a
Smart Battery attached to SMBus or a Control Method Battery with a
_BIF object, this ioctl will build a
struct acpi_bix structure based on the
obtained information and return it.
- rev
- Revision number of the object. There are the following
well-known values:
-
ACPI_BIX_REV_0
(0x0000)
- A
_BIX object in ACPI
4.0.
-
ACPI_BIX_REV_1
(0x0001)
- A
_BIX object in ACPI
6.0.
-
ACPI_BIX_REV_BIF
(0xffff)
- A
_BIX object built from
the _BIF object found on the system.
Note that this field should be checked by using
ACPI_BIX_REV_MIN_CHECK(var,
rev) macro when checking the minimum
revision number.
- units
- Indicates the units used by the battery to report its
capacity and charge rate encoded in the following:
- ACPI_BIX_UNITS_MW (0x00000000)
- in mW (power)
- ACPI_BIX_UNITS_MA (0x00000001)
- in mA (current)
Note that capacity is expressed in mWh or mAh, and rate is expressed in
mW or mA, respectively.
- dcap
- The Battery's design capacity, which is the nominal
capacity of a new battery. This is expressed as power or current
depending on the value of units.
- lfcap
- Predicted battery capacity when fully charged.
Typically this will decrease every charging cycle.
- btech
- Battery technology:
- 0x00000000 Primary cell (non-rechargable)
-
- 0x00000001 Secondary cell (rechargable)
-
- dvol
- Design voltage in mV, which is the nominal voltage of a
new battery.
- wcap
- Design capacity of warning. When a discharging battery
device reaches this capacity, notification is sent to the system.
- lcap
- Design capacity of low.
- cycles
- (rev 0 or newer) The number of cycles the battery has
experienced. A cycle means an amount of discharge occurred which was
approximately equal to the value of Design Capacity.
- accuracy
- (rev 0 or newer) The accuracy of the battery capacity
measurement, in thousandth of a percent.
- stmax
- (rev 0 or newer) The Maximum Sampling Time of the
battery in milliseconds. This is the maximum duration between two
consecutive measurements of the battery's capacities specified in
_BST. If two succeeding readings of
_BST beyond this duration occur, two different
results can be returned.
- stmin
- (rev 0 or newer) The Minimum Sampling Time of the
battery in milliseconds.
- aimax
- (rev 0 or newer) The Maximum Average Interval of the
battery in milliseconds. This is the length of time within which the
battery averages the capacity measurements specified in
_BST. The Sampling Time specifies the
frequency of measurements, and the Average Interval specifies the
width of the time window of every measurement.
- aimin
- (rev 0 or newer) The Minimum Average Interval of the
battery in milliseconds.
- gra1
- Battery capacity granularity between
low and
warning. This is expressed as power
or current depending on the value of
units.
- gra2
- Battery capacity granularity between
warning and
full. This is expressed as power or
current depending on the value of
units.
- model
- Model number of the battery as a string.
- serial
- Serial number of the battery as a string.
- type
- Type identifier of the battery as a string.
- oeminfo
- OEM-specific information of the battery as a
string.
- scap
- (rev 1 or newer) Battery swapping capability encoded in
the following:
- ACPI_BIX_SCAP_NO (0x00000000)
- Non-swappable
- ACPI_BIX_SCAP_COLD (0x00000001)
- Cold-swappable
- ACPI_BIX_SCAP_HOT (0x00000010)
- Hot-swappable
-
ACPIIO_BATT_GET_BIF
struct acpi_bif
- (deprecated) Returns battery information given by the ACPI
_BIF (Battery Information) object, which was
deprecated in ACPI 4.0 specification. The data structure is a subset of
struct acpi_bix.
Note that this ioctl will built a struct
acpi_bif structure based on the obtained information even if this
object is not available and a _BIX object is
found.
- ACPIIO_BATT_GET_BST struct
acpi_bst
- Returns battery information given by the ACPI
_BST (Battery Status) object, which is the present
battery status. In the case of a Smart Battery attached to SMBus, this
ioctl will build a struct acpi_bst
structure based on the obtained information and return it.
- state
- Battery state. The value is encoded in the same way as
state of
struct acpi_battinfo.
- rate
- Battery present rate of charging or discharging. The
unit of the value depends on unit of
struct acpi_bif.
- cap
- Battery remaining capacity. The unit of this value
depends on unit of
struct acpi_bif.
- volt
- Battery present voltage.
The following
sysctl(8) variables export battery
status. Note that they are accumulated status of all of the connected
batteries:
- hw.acpi.battery.info_expire
- Information cache expiration time in seconds. The battery
information obtained by
_BIX or
_BIF object will be stored and reused for
successive read access to this MIB within the specified period.
- hw.acpi.battery.units
- Number of battery units in the system.
- hw.acpi.battery.state
- Current battery charging status. This is same as
state of
struct acpi_battinfo.
- hw.acpi.battery.rate
- Current battery discharging rate in mW.
- hw.acpi.battery.time
- Remaining battery life in minutes. If the battery is not
discharging, the value shows
-1.
- hw.acpi.battery.life
- Battery capacity in percent.
Battery-related event notifications are sent to the userland via the
devd(8) interface. See
/etc/devd.conf and
devd.conf(5) for more details. Note that
notifications are supported only by the Control Method Battery.
The
acpi_battery driver sends events with the
following attributes:
- system
ACPI- subsystem
CMBAT- type
- The fully qualified battery object path as in the ASL.
- notify
- An integer designating the event:
0x80- Battery status was changed.
0x81- Battery information was changed.
acpi(4),
acpiconf(8)
Nate Lawson
<
[email protected]>,
Munehiro Matsuda,
Takanori Watanabe
<
[email protected]>,
Mitsuru IWASAKI
<
[email protected]>,
Hans Petter Selasky
<
[email protected]>,
and
Hiroki Sato
<
[email protected]>.
This manual page was written by
Takanori
Watanabe
<
[email protected]>
and
Hiroki Sato
<
[email protected]>.