294de6bbd6
ACPI Control Method Batteries have a _BIF and/or _BIX object which provide static properties of the battery. FreeBSD acpi_cmbat module supported _BIF object only, which was deprecated as of ACPI 4.0. _BIX is an extended version of _BIF defined in ACPI 4.0 or later. As of writing, _BIX has two revisions. One is in ACPI 4.0 (rev.0) and another is in ACPI 6.0 (rev.1). It seems that hardware vendors still stick to _BIF only or _BIX rev.0 + _BIF for the maximum compatibility. Microsoft requires _BIX rev.0 for Windows machines, so there are some laptop machines with _BIX rev.0 only. In this case, FreeBSD does not recognize the battery information. After this change, the acpi_cmbat module gets battery information from _BIX or _BIF object and internally uses _BIX rev.1 data structure as the primary information store in the kernel. ACPIIO_BATT_GET_BI[FX] returns an acpi_bi[fx] structure built by using information obtained from a _BIF or a _BIX object found on the system. The revision number field can be used to check which field is available. The acpiconf(8) utility will show additional information if _BIX is available. Although ABIs of ACPIIO_BATT_* were changed, the existing APIs for userland utilities are not changed and the backward-compatible ABIs are provided. This means that older versions of acpiconf(8) can also work with the new kernel. The (union acpi_battery_ioctl_arg) was padded to 256 byte long to avoid another ABI change in the future. A _BIX object with its revision number >1 will be treated as compatible with the rev.1 _BIX format. Reviewed by: takawata MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D23728
381 lines
10 KiB
Groff
381 lines
10 KiB
Groff
.\"
|
|
.\" Copyright (c) 2019 Takanori Watanabe
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 16, 2020
|
|
.Dt ACPI_BATTERY 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm acpi_battery
|
|
.Nd ACPI battery management subsystem
|
|
.Sh SYNOPSIS
|
|
.Cd "device acpi"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
is a driver for battery management features of the ACPI module.
|
|
.Pp
|
|
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
|
|
.Pq ACPI Machine Language
|
|
code control methods,
|
|
and the latter is controlled directly through the ACPI EC
|
|
.Pq Embedded Controller
|
|
typically via an SMBus interface.
|
|
.Pp
|
|
This driver supports the
|
|
.Xr sysctl 8
|
|
and
|
|
.Xr ioctl 2
|
|
interfaces as well as the
|
|
.Xr devd 8
|
|
event notification interface.
|
|
.Sh IOCTLS
|
|
Every ioctl for the
|
|
.Nm
|
|
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
|
|
.Dv ACPI_BATTERY_ALL_UNITS
|
|
specifies all of the attached units
|
|
and reports accumulated information.
|
|
.Bl -tag -width indent
|
|
.It Dv ACPIIO_BATT_GET_UNITS Vt int
|
|
Returns the number of battery units in the system.
|
|
The unit number argument will be ignored.
|
|
.It Dv ACPIIO_BATT_GET_BATTINFO Vt struct acpi_battinfo
|
|
Returns the following:
|
|
.Bl -tag -width indent
|
|
.It Va cap
|
|
Battery capacity in percent,
|
|
.It Va min
|
|
Remaining battery life in minutes,
|
|
.It Va state
|
|
Current status of the battery encoded in the following:
|
|
.Bl -tag -width indent
|
|
.It Dv ACPI_BATT_STAT_DISCHARG Pq 0x0001
|
|
Battery is discharging,
|
|
.It Dv ACPI_BATT_STAT_CHARGING Pq 0x0002
|
|
Battery is being charged, or
|
|
.It Dv ACPI_BATT_STAT_CRITICAL Pq 0x0004
|
|
Remaining battery life is critically low.
|
|
.El
|
|
.Pp
|
|
Note that the status bits of each battery will be
|
|
consolidated when
|
|
.Dv ACPI_BATTERY_ALL_UNITS
|
|
is specified.
|
|
.It Va rate
|
|
Current battery discharging rate in mW.
|
|
.Li -1
|
|
means not discharging right now.
|
|
.El
|
|
.It Dv ACPIIO_BATT_GET_BIX Vt struct acpi_bix
|
|
Returns battery information given by the ACPI
|
|
.Li _BIX Pq 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
|
|
.Li _BIF
|
|
object,
|
|
this ioctl will build a
|
|
.Vt struct acpi_bix
|
|
structure based on the obtained information
|
|
and return it.
|
|
.Bl -tag -width indent
|
|
.It Va rev
|
|
Revision number of the object.
|
|
There are the following well-known values:
|
|
.Bl -tag -width indent
|
|
.It Dv ACPI_BIX_REV_0 Pq 0x0000
|
|
A
|
|
.Li _BIX
|
|
object in ACPI 4.0.
|
|
.It Dv ACPI_BIX_REV_1 Pq 0x0001
|
|
A
|
|
.Li _BIX
|
|
object in ACPI 6.0.
|
|
.It Dv ACPI_BIX_REV_BIF Pq 0xffff
|
|
A
|
|
.Li _BIX
|
|
object built from the
|
|
.Li _BIF
|
|
object found on the system.
|
|
.El
|
|
.Pp
|
|
Note that this field should be checked by using
|
|
.Fn ACPI_BIX_REV_MIN_CHECK var rev
|
|
macro when checking the minimum revision number.
|
|
.It Va units
|
|
Indicates the units used by the battery to report its
|
|
capacity and charge rate encoded in the following:
|
|
.Bl -tag -width indent
|
|
.It ACPI_BIX_UNITS_MW Pq 0x00000000
|
|
in mW
|
|
.Pq power
|
|
.It ACPI_BIX_UNITS_MA Pq 0x00000001
|
|
in mA
|
|
.Pq current
|
|
.El
|
|
.Pp
|
|
Note that capacity is expressed in mWh or mAh,
|
|
and rate is expressed in mW or mA,
|
|
respectively.
|
|
.It Va 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
|
|
.Va units .
|
|
.It Va lfcap
|
|
Predicted battery capacity when fully charged.
|
|
Typically this will decrease every charging cycle.
|
|
.It btech
|
|
Battery technology:
|
|
.Bl -tag -width indent
|
|
.It 0x00000000 Primary cell Pq non-rechargable
|
|
.It 0x00000001 Secondary cell Pq rechargable
|
|
.El
|
|
.It Va dvol
|
|
Design voltage in mV,
|
|
which is the nominal voltage of a new battery.
|
|
.It Va wcap
|
|
Design capacity of warning.
|
|
When a discharging battery device reaches this capacity,
|
|
notification is sent to the system.
|
|
.It Va lcap
|
|
Design capacity of low.
|
|
.It Va cycles
|
|
.Pq 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.
|
|
.It Va accuracy
|
|
.Pq rev 0 or newer
|
|
The accuracy of the battery capacity measurement,
|
|
in thousandth of a percent.
|
|
.It Va stmax
|
|
.Pq 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
|
|
.Li _BST .
|
|
If two succeeding readings of
|
|
.Li _BST
|
|
beyond this duration occur,
|
|
two different results can be returned.
|
|
.It Va stmin
|
|
.Pq rev 0 or newer
|
|
The Minimum Sampling Time of the battery in
|
|
milliseconds.
|
|
.It Va aimax
|
|
.Pq 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
|
|
.Li _BST .
|
|
The Sampling Time specifies the frequency of measurements,
|
|
and the Average Interval specifies the width of the time
|
|
window of every measurement.
|
|
.It Va aimin
|
|
.Pq rev 0 or newer
|
|
The Minimum Average Interval of the battery in
|
|
milliseconds.
|
|
.It Va gra1
|
|
Battery capacity granularity between
|
|
.Va low
|
|
and
|
|
.Va warning .
|
|
This is expressed as power or current depending on
|
|
the value of
|
|
.Va units .
|
|
.It Va gra2
|
|
Battery capacity granularity between
|
|
.Va warning
|
|
and
|
|
.Va full .
|
|
This is expressed as power or current depending on
|
|
the value of
|
|
.Va units .
|
|
.It Va model
|
|
Model number of the battery as a string.
|
|
.It Va serial
|
|
Serial number of the battery as a string.
|
|
.It Va type
|
|
Type identifier of the battery as a string.
|
|
.It Va oeminfo
|
|
OEM-specific information of the battery as a string.
|
|
.It Va scap
|
|
.Pq rev 1 or newer
|
|
Battery swapping capability encoded in the following:
|
|
.Bl -tag -width indent
|
|
.It ACPI_BIX_SCAP_NO Pq 0x00000000
|
|
Non-swappable
|
|
.It ACPI_BIX_SCAP_COLD Pq 0x00000001
|
|
Cold-swappable
|
|
.It ACPI_BIX_SCAP_HOT Pq 0x00000010
|
|
Hot-swappable
|
|
.El
|
|
.El
|
|
.It Dv ACPIIO_BATT_GET_BIF Vt struct acpi_bif
|
|
.Pq deprecated
|
|
Returns battery information given by the ACPI
|
|
.Li _BIF Pq Battery Information
|
|
object,
|
|
which was deprecated in ACPI 4.0 specification.
|
|
The data structure is a subset of
|
|
.Vt struct acpi_bix .
|
|
.Pp
|
|
Note that this ioctl will built a
|
|
.Vt struct acpi_bif
|
|
structure based on the obtained information
|
|
even if this object is not available and a
|
|
.Li _BIX
|
|
object is found.
|
|
.It ACPIIO_BATT_GET_BST Vt struct acpi_bst
|
|
Returns battery information given by the ACPI
|
|
.Li _BST Pq Battery Status
|
|
object,
|
|
which is the present battery status.
|
|
In the case of a Smart Battery attached to SMBus,
|
|
this ioctl will build a
|
|
.Vt struct acpi_bst
|
|
structure based on the obtained information
|
|
and return it.
|
|
.Bl -tag -width indent
|
|
.It Va state
|
|
Battery state.
|
|
The value is encoded in the same way as
|
|
.Va state
|
|
of
|
|
.Vt struct acpi_battinfo .
|
|
.It Va rate
|
|
Battery present rate of charging or discharging.
|
|
The unit of the value depends on
|
|
.Va unit
|
|
of
|
|
.Vt struct acpi_bif .
|
|
.It Va cap
|
|
Battery remaining capacity.
|
|
The unit of this value depends on
|
|
.Va unit
|
|
of
|
|
.Vt struct acpi_bif .
|
|
.It Va volt
|
|
Battery present voltage.
|
|
.El
|
|
.El
|
|
.Sh SYSCTL VARIABLES
|
|
The following
|
|
.Xr sysctl 8
|
|
variables export battery status.
|
|
Note that they are accumulated status of all of the
|
|
connected batteries:
|
|
.Bl -tag -width indent
|
|
.It Va hw.acpi.battery.info_expire
|
|
Information cache expiration time in seconds.
|
|
The battery information obtained by
|
|
.Li _BIX
|
|
or
|
|
.Li _BIF
|
|
object will be stored and reused for successive
|
|
read access to this MIB within the specified period.
|
|
.It Va hw.acpi.battery.units
|
|
Number of battery units in the system.
|
|
.It Va hw.acpi.battery.state
|
|
Current battery charging status.
|
|
This is same as
|
|
.Va state
|
|
of
|
|
.Vt struct acpi_battinfo .
|
|
.It Va hw.acpi.battery.rate
|
|
Current battery discharging rate in mW.
|
|
.It Va hw.acpi.battery.time
|
|
Remaining battery life in minutes.
|
|
If the battery is not discharging,
|
|
the value shows
|
|
.Li -1 .
|
|
.It Va hw.acpi.battery.life
|
|
Battery capacity in percent.
|
|
.El
|
|
.Sh EVENT NOTIFICATIONS
|
|
Battery-related event notifications are sent
|
|
to the userland via the
|
|
.Xr devd 8
|
|
interface.
|
|
See
|
|
.Pa /etc/devd.conf
|
|
and
|
|
.Xr devd.conf 5
|
|
for more details.
|
|
Note that notifications are supported only by
|
|
the Control Method Battery.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
driver sends events with the following attributes:
|
|
.Pp
|
|
.Bl -tag -width "subsystem" -compact
|
|
.It system
|
|
.Li ACPI
|
|
.It subsystem
|
|
.Li CMBAT
|
|
.It type
|
|
The fully qualified battery object path as in the ASL.
|
|
.It notify
|
|
An integer designating the event:
|
|
.Pp
|
|
.Bl -tag -width indent -compact
|
|
.It Li 0x80
|
|
Battery status was changed.
|
|
.It Li 0x81
|
|
Battery information was changed.
|
|
.El
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr acpi 4 ,
|
|
.Xr acpiconf 8
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
.An Nate Lawson Aq Mt njl@FreeBSD.org ,
|
|
.An Munehiro Matsuda ,
|
|
.An Takanori Watanabe Aq Mt takawata@FreeBSD.org ,
|
|
.An Mitsuru IWASAKI Aq Mt iwasaki@FreeBSD.org ,
|
|
.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org ,
|
|
and
|
|
.An Hiroki Sato Aq Mt hrs@FreeBSD.org .
|
|
.Pp
|
|
This manual page was written by
|
|
.An Takanori Watanabe Aq Mt takawata@FreeBSD.org
|
|
and
|
|
.An Hiroki Sato Aq Mt hrs@FreeBSD.org .
|