ACPI_BATTERY(4) FreeBSD Kernel Interfaces Manual ACPI_BATTERY(4)
NAME
acpi_battery - ACPI battery management subsystem
SYNOPSIS
device acpi
DESCRIPTION
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.
IOCTLS
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.
SYSCTL VARIABLES
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.
EVENT NOTIFICATIONS
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.
SEE ALSO
acpi(4), acpiconf(8)
AUTHORS
Nate Lawson <njl@FreeBSD.org>, Munehiro Matsuda, Takanori Watanabe
<takawata@FreeBSD.org>, Mitsuru IWASAKI <iwasaki@FreeBSD.org>, Hans
Petter Selasky <hselasky@FreeBSD.org>, and Hiroki Sato <hrs@FreeBSD.org>.
This manual page was written by Takanori Watanabe <takawata@FreeBSD.org>
and Hiroki Sato <hrs@FreeBSD.org>.
FreeBSD 13.1-RELEASE-p6 February 16, 2020 FreeBSD 13.1-RELEASE-p6
man2web Home...