636421f54b
PR:242100 Differential Revision: https://reviews.freebsd.org/D22556
284 lines
7.5 KiB
Groff
284 lines
7.5 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 November 26, 2019
|
|
.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.
|
|
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.
|
|
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
|
|
.Li ACPI_BATTERY_ALL_UNITS
|
|
specifies all of the attached units
|
|
and reports accumulated information.
|
|
.Bl -tag -width indent
|
|
.It ACPIIO_BATT_GET_UNITS Vt int
|
|
Returns the number of battery units in the system.
|
|
The unit number argument will be ignored.
|
|
.It ACPIIO_BATT_GET_BATTINFO Vt struct acpi_battinfo
|
|
Returns the following:
|
|
.Bl -tag -width indent
|
|
.It cap
|
|
Battery capacity in percent,
|
|
.It min
|
|
Remaining battery life in minutes,
|
|
.It state
|
|
Current status of the battery encoded in the following:
|
|
.Bl -tag -width indent
|
|
.It ACPI_BATT_STAT_DISCHARG Pq 0x0001
|
|
Battery is discharging,
|
|
.It ACPI_BATT_STAT_CHARGING Pq 0x0002
|
|
Battery is being charged, or
|
|
.It 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
|
|
.Li ACPI_BATTERY_ALL_UNITS
|
|
is specified.
|
|
.It rate
|
|
Current battery discharging rate in mW.
|
|
.Li -1
|
|
means not discharging right now.
|
|
.El
|
|
.It ACPIIO_BATT_GET_BIF Vt struct acpi_bif
|
|
Returns battery information given by the ACPI
|
|
.Li _BIF 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,
|
|
this ioctl will build a
|
|
.Vt struct acpi_bif
|
|
structure based on the obtained information
|
|
and return it.
|
|
.Bl -tag -width indent
|
|
.It 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_BIF_UNITS_MW Pq 0x00000000
|
|
in mW
|
|
.Pq power
|
|
.It ACPI_BIF_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 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 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 Secondery cell Pq rechargable
|
|
.El
|
|
.It dvol
|
|
Design voltage in mV,
|
|
which is the nominal voltage of a new battery.
|
|
.It wcap
|
|
Design capacity of warning.
|
|
When a discharging battery device reaches this capacity,
|
|
notification is sent to the system.
|
|
.It lcap
|
|
Design capacity of low.
|
|
.It 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 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 model
|
|
Model number of the battery as a string.
|
|
.It serial
|
|
Serial number of the battery as a string.
|
|
.It type
|
|
Type identifier of the battery as a string.
|
|
.It oeminfo
|
|
OEM-specific information of the battery as a string.
|
|
.El
|
|
.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 state
|
|
Battery state.
|
|
The value is encoded in the same way as
|
|
.Va state
|
|
of
|
|
.Vt struct acpi_battinfo .
|
|
.It rate
|
|
Battery present rate of charging or discharging.
|
|
The unit of the value depends on
|
|
.Va unit
|
|
of
|
|
.Vt struct acpi_bif .
|
|
.It cap
|
|
Battery remaining capacity.
|
|
The unit of this value depends on
|
|
.Va unit
|
|
of
|
|
.Vt struct acpi_bif .
|
|
.It 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 _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 ,
|
|
and
|
|
.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org .
|
|
.Pp
|
|
This manual page was written by
|
|
.An Takanori Watanabe Aq Mt takawata@FreeBSD.org .
|