Date: Tue, 10 Dec 2019 02:19:07 +0000 (UTC) From: Takanori Watanabe <takawata@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r355574 - head/share/man/man4 Message-ID: <201912100219.xBA2J7rU068027@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: takawata Date: Tue Dec 10 02:19:07 2019 New Revision: 355574 URL: https://svnweb.freebsd.org/changeset/base/355574 Log: Add ACPI battery subsystem man page. PR:242100 Differential Revision: https://reviews.freebsd.org/D22556 Added: head/share/man/man4/acpi_battery.4 (contents, props changed) Modified: head/share/man/man4/Makefile Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Tue Dec 10 00:08:05 2019 (r355573) +++ head/share/man/man4/Makefile Tue Dec 10 02:19:07 2019 (r355574) @@ -16,6 +16,7 @@ MAN= aac.4 \ ${_acpi_rapidstart.4} \ ${_acpi_sony.4} \ acpi_thermal.4 \ + acpi_battery.4 \ ${_acpi_toshiba.4} \ acpi_video.4 \ ${_acpi_wmi.4} \ Added: head/share/man/man4/acpi_battery.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/acpi_battery.4 Tue Dec 10 02:19:07 2019 (r355574) @@ -0,0 +1,283 @@ +.\" +.\" 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 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201912100219.xBA2J7rU068027>