1.\" 2.\" Copyright (c) 2019 Takanori Watanabe 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd November 26, 2019 29.Dt ACPI_BATTERY 4 30.Os 31.Sh NAME 32.Nm acpi_battery 33.Nd ACPI battery management subsystem 34.Sh SYNOPSIS 35.Cd "device acpi" 36.Sh DESCRIPTION 37The 38.Nm 39is a driver for battery management features of the ACPI module. 40An ACPI-compatible battery device supports either a Control 41Method Battery interface or a Smart Battery subsystem interface. 42The former is accessed by the AML 43.Pq ACPI Machine Language 44code control methods, 45and the latter is controlled directly through the ACPI EC 46.Pq Embedded Controller 47typically via an SMBus interface. 48This driver supports the 49.Xr sysctl 8 50and 51.Xr ioctl 2 52interfaces as well as the 53.Xr devd 8 54event notification interface. 55.Sh IOCTLS 56Every ioctl for the 57.Nm 58driver takes a single integer value for the battery unit 59number as an argument, 60and returns a specific structure for each request. 61A special unit number 62.Li ACPI_BATTERY_ALL_UNITS 63specifies all of the attached units 64and reports accumulated information. 65.Bl -tag -width indent 66.It ACPIIO_BATT_GET_UNITS Vt int 67Returns the number of battery units in the system. 68The unit number argument will be ignored. 69.It ACPIIO_BATT_GET_BATTINFO Vt struct acpi_battinfo 70Returns the following: 71.Bl -tag -width indent 72.It cap 73Battery capacity in percent, 74.It min 75Remaining battery life in minutes, 76.It state 77Current status of the battery encoded in the following: 78.Bl -tag -width indent 79.It ACPI_BATT_STAT_DISCHARG Pq 0x0001 80Battery is discharging, 81.It ACPI_BATT_STAT_CHARGING Pq 0x0002 82Battery is being charged, or 83.It ACPI_BATT_STAT_CRITICAL Pq 0x0004 84Remaining battery life is critically low. 85.El 86.Pp 87Note that the status bits of each battery will be 88consolidated when 89.Li ACPI_BATTERY_ALL_UNITS 90is specified. 91.It rate 92Current battery discharging rate in mW. 93.Li -1 94means not discharging right now. 95.El 96.It ACPIIO_BATT_GET_BIF Vt struct acpi_bif 97Returns battery information given by the ACPI 98.Li _BIF Pq Battery Information 99object, 100which is the static portion of the Control Method 101Battery information. 102In the case of a Smart Battery attached to SMBus, 103this ioctl will build a 104.Vt struct acpi_bif 105structure based on the obtained information 106and return it. 107.Bl -tag -width indent 108.It units 109Indicates the units used by the battery to report its 110capacity and charge rate encoded in the following: 111.Bl -tag -width indent 112.It ACPI_BIF_UNITS_MW Pq 0x00000000 113in mW 114.Pq power 115.It ACPI_BIF_UNITS_MA Pq 0x00000001 116in mA 117.Pq current 118.El 119.Pp 120Note that capacity is expressed in mWh or mAh, 121and rate is expressed in mW or mA, 122respectively. 123.It dcap 124The Battery's design capacity, 125which is the nominal capacity of a new battery. 126This is expressed as power or current depending on 127the value of 128.Va units . 129.It lfcap 130Predicted battery capacity when fully charged. 131Typically this will decrease every charging cycle. 132.It btech 133Battery technology: 134.Bl -tag -width indent 135.It 0x00000000 Primary cell Pq non-rechargable 136.It 0x00000001 Secondery cell Pq rechargable 137.El 138.It dvol 139Design voltage in mV, 140which is the nominal voltage of a new battery. 141.It wcap 142Design capacity of warning. 143When a discharging battery device reaches this capacity, 144notification is sent to the system. 145.It lcap 146Design capacity of low. 147.It gra1 148Battery capacity granularity between 149.Va low 150and 151.Va warning . 152This is expressed as power or current depending on 153the value of 154.Va units . 155.It gra2 156Battery capacity granularity between 157.Va warning 158and 159.Va full . 160This is expressed as power or current depending on 161the value of 162.Va units . 163.It model 164Model number of the battery as a string. 165.It serial 166Serial number of the battery as a string. 167.It type 168Type identifier of the battery as a string. 169.It oeminfo 170OEM-specific information of the battery as a string. 171.El 172.It ACPIIO_BATT_GET_BST Vt struct acpi_bst 173Returns battery information given by the ACPI 174.Li _BST Pq Battery Status 175object, 176which is the present battery status. 177In the case of a Smart Battery attached to SMBus, 178this ioctl will build a 179.Vt struct acpi_bst 180structure based on the obtained information 181and return it. 182.Bl -tag -width indent 183.It state 184Battery state. 185The value is encoded in the same way as 186.Va state 187of 188.Vt struct acpi_battinfo . 189.It rate 190Battery present rate of charging or discharging. 191The unit of the value depends on 192.Va unit 193of 194.Vt struct acpi_bif . 195.It cap 196Battery remaining capacity. 197The unit of this value depends on 198.Va unit 199of 200.Vt struct acpi_bif . 201.It volt 202Battery present voltage. 203.El 204.El 205.Sh SYSCTL VARIABLES 206The following 207.Xr sysctl 8 208variables export battery status. 209Note that they are accumulated status of all of the 210connected batteries: 211.Bl -tag -width indent 212.It Va hw.acpi.battery.info_expire 213Information cache expiration time in seconds. 214The battery information obtained by 215.Li _BIF 216object will be stored and reused for successive 217read access to this MIB within the specified period. 218.It Va hw.acpi.battery.units 219Number of battery units in the system. 220.It Va hw.acpi.battery.state 221Current battery charging status. 222This is same as 223.Va state 224of 225.Vt struct acpi_battinfo . 226.It Va hw.acpi.battery.rate 227Current battery discharging rate in mW. 228.It Va hw.acpi.battery.time 229Remaining battery life in minutes. 230If the battery is not discharging, 231the value shows 232.Li -1 . 233.It Va hw.acpi.battery.life 234Battery capacity in percent. 235.El 236.Sh EVENT NOTIFICATIONS 237Battery-related event notifications are sent 238to the userland via the 239.Xr devd 8 240interface. 241See 242.Pa /etc/devd.conf 243and 244.Xr devd.conf 5 245for more details. 246Note that notifications are supported only by 247the Control Method Battery. 248.Pp 249The 250.Nm 251driver sends events with the following attributes: 252.Pp 253.Bl -tag -width "subsystem" -compact 254.It system 255.Li ACPI 256.It subsystem 257.Li CMBAT 258.It type 259The fully qualified battery object path as in the ASL. 260.It notify 261An integer designating the event: 262.Pp 263.Bl -tag -width indent -compact 264.It Li 0x80 265Battery status was changed. 266.It Li 0x81 267Battery information was changed. 268.El 269.El 270.Sh SEE ALSO 271.Xr acpi 4 , 272.Xr acpiconf 8 273.Sh AUTHORS 274.An -nosplit 275.An Nate Lawson Aq Mt njl@FreeBSD.org , 276.An Munehiro Matsuda , 277.An Takanori Watanabe Aq Mt takawata@FreeBSD.org , 278.An Mitsuru IWASAKI Aq Mt iwasaki@FreeBSD.org , 279and 280.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . 281.Pp 282This manual page was written by 283.An Takanori Watanabe Aq Mt takawata@FreeBSD.org . 284