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 February 16, 2020 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. 40.Pp 41An ACPI-compatible battery device supports either a Control 42Method Battery interface or a Smart Battery subsystem interface. 43The former is accessed by the AML 44.Pq ACPI Machine Language 45code control methods, 46and the latter is controlled directly through the ACPI EC 47.Pq Embedded Controller 48typically via an SMBus interface. 49.Pp 50This driver supports the 51.Xr sysctl 8 52and 53.Xr ioctl 2 54interfaces as well as the 55.Xr devd 8 56event notification interface. 57.Sh IOCTLS 58Every ioctl for the 59.Nm 60driver takes a single integer value for the battery unit 61number as an argument, 62and returns a specific structure for each request. 63A special unit number 64.Dv ACPI_BATTERY_ALL_UNITS 65specifies all of the attached units 66and reports accumulated information. 67.Bl -tag -width indent 68.It Dv ACPIIO_BATT_GET_UNITS Vt int 69Returns the number of battery units in the system. 70The unit number argument will be ignored. 71.It Dv ACPIIO_BATT_GET_BATTINFO Vt struct acpi_battinfo 72Returns the following: 73.Bl -tag -width indent 74.It Va cap 75Battery capacity in percent, 76.It Va min 77Remaining battery life in minutes, 78.It Va state 79Current status of the battery encoded in the following: 80.Bl -tag -width indent 81.It Dv ACPI_BATT_STAT_DISCHARG Pq 0x0001 82Battery is discharging, 83.It Dv ACPI_BATT_STAT_CHARGING Pq 0x0002 84Battery is being charged, or 85.It Dv ACPI_BATT_STAT_CRITICAL Pq 0x0004 86Remaining battery life is critically low. 87.El 88.Pp 89Note that the status bits of each battery will be 90consolidated when 91.Dv ACPI_BATTERY_ALL_UNITS 92is specified. 93.It Va rate 94Current battery discharging rate in mW. 95.Li -1 96means not discharging right now. 97.El 98.It Dv ACPIIO_BATT_GET_BIX Vt struct acpi_bix 99Returns battery information given by the ACPI 100.Li _BIX Pq Battery Information 101object, 102which is the static portion of the Control Method 103Battery information. 104In the case of a Smart Battery attached to 105SMBus or a Control Method Battery with a 106.Li _BIF 107object, 108this ioctl will build a 109.Vt struct acpi_bix 110structure based on the obtained information 111and return it. 112.Bl -tag -width indent 113.It Va rev 114Revision number of the object. 115There are the following well-known values: 116.Bl -tag -width indent 117.It Dv ACPI_BIX_REV_0 Pq 0x0000 118A 119.Li _BIX 120object in ACPI 4.0. 121.It Dv ACPI_BIX_REV_1 Pq 0x0001 122A 123.Li _BIX 124object in ACPI 6.0. 125.It Dv ACPI_BIX_REV_BIF Pq 0xffff 126A 127.Li _BIX 128object built from the 129.Li _BIF 130object found on the system. 131.El 132.Pp 133Note that this field should be checked by using 134.Fn ACPI_BIX_REV_MIN_CHECK var rev 135macro when checking the minimum revision number. 136.It Va units 137Indicates the units used by the battery to report its 138capacity and charge rate encoded in the following: 139.Bl -tag -width indent 140.It ACPI_BIX_UNITS_MW Pq 0x00000000 141in mW 142.Pq power 143.It ACPI_BIX_UNITS_MA Pq 0x00000001 144in mA 145.Pq current 146.El 147.Pp 148Note that capacity is expressed in mWh or mAh, 149and rate is expressed in mW or mA, 150respectively. 151.It Va dcap 152The Battery's design capacity, 153which is the nominal capacity of a new battery. 154This is expressed as power or current depending on 155the value of 156.Va units . 157.It Va lfcap 158Predicted battery capacity when fully charged. 159Typically this will decrease every charging cycle. 160.It btech 161Battery technology: 162.Bl -tag -width indent 163.It 0x00000000 Primary cell Pq non-rechargable 164.It 0x00000001 Secondary cell Pq rechargable 165.El 166.It Va dvol 167Design voltage in mV, 168which is the nominal voltage of a new battery. 169.It Va wcap 170Design capacity of warning. 171When a discharging battery device reaches this capacity, 172notification is sent to the system. 173.It Va lcap 174Design capacity of low. 175.It Va cycles 176.Pq rev 0 or newer 177The number of cycles the battery has experienced. 178A cycle means an amount of discharge occurred which was 179approximately equal to the value of Design Capacity. 180.It Va accuracy 181.Pq rev 0 or newer 182The accuracy of the battery capacity measurement, 183in thousandth of a percent. 184.It Va stmax 185.Pq rev 0 or newer 186The Maximum Sampling Time of the battery in 187milliseconds. 188This is the maximum duration between two consecutive 189measurements of the battery's capacities specified in 190.Li _BST . 191If two succeeding readings of 192.Li _BST 193beyond this duration occur, 194two different results can be returned. 195.It Va stmin 196.Pq rev 0 or newer 197The Minimum Sampling Time of the battery in 198milliseconds. 199.It Va aimax 200.Pq rev 0 or newer 201The Maximum Average Interval of the battery in 202milliseconds. 203This is the length of time within which the battery 204averages the capacity measurements specified in 205.Li _BST . 206The Sampling Time specifies the frequency of measurements, 207and the Average Interval specifies the width of the time 208window of every measurement. 209.It Va aimin 210.Pq rev 0 or newer 211The Minimum Average Interval of the battery in 212milliseconds. 213.It Va gra1 214Battery capacity granularity between 215.Va low 216and 217.Va warning . 218This is expressed as power or current depending on 219the value of 220.Va units . 221.It Va gra2 222Battery capacity granularity between 223.Va warning 224and 225.Va full . 226This is expressed as power or current depending on 227the value of 228.Va units . 229.It Va model 230Model number of the battery as a string. 231.It Va serial 232Serial number of the battery as a string. 233.It Va type 234Type identifier of the battery as a string. 235.It Va oeminfo 236OEM-specific information of the battery as a string. 237.It Va scap 238.Pq rev 1 or newer 239Battery swapping capability encoded in the following: 240.Bl -tag -width indent 241.It ACPI_BIX_SCAP_NO Pq 0x00000000 242Non-swappable 243.It ACPI_BIX_SCAP_COLD Pq 0x00000001 244Cold-swappable 245.It ACPI_BIX_SCAP_HOT Pq 0x00000010 246Hot-swappable 247.El 248.El 249.It Dv ACPIIO_BATT_GET_BIF Vt struct acpi_bif 250.Pq deprecated 251Returns battery information given by the ACPI 252.Li _BIF Pq Battery Information 253object, 254which was deprecated in ACPI 4.0 specification. 255The data structure is a subset of 256.Vt struct acpi_bix . 257.Pp 258Note that this ioctl will built a 259.Vt struct acpi_bif 260structure based on the obtained information 261even if this object is not available and a 262.Li _BIX 263object is found. 264.It ACPIIO_BATT_GET_BST Vt struct acpi_bst 265Returns battery information given by the ACPI 266.Li _BST Pq Battery Status 267object, 268which is the present battery status. 269In the case of a Smart Battery attached to SMBus, 270this ioctl will build a 271.Vt struct acpi_bst 272structure based on the obtained information 273and return it. 274.Bl -tag -width indent 275.It Va state 276Battery state. 277The value is encoded in the same way as 278.Va state 279of 280.Vt struct acpi_battinfo . 281.It Va rate 282Battery present rate of charging or discharging. 283The unit of the value depends on 284.Va unit 285of 286.Vt struct acpi_bif . 287.It Va cap 288Battery remaining capacity. 289The unit of this value depends on 290.Va unit 291of 292.Vt struct acpi_bif . 293.It Va volt 294Battery present voltage. 295.El 296.El 297.Sh SYSCTL VARIABLES 298The following 299.Xr sysctl 8 300variables export battery status. 301Note that they are accumulated status of all of the 302connected batteries: 303.Bl -tag -width indent 304.It Va hw.acpi.battery.info_expire 305Information cache expiration time in seconds. 306The battery information obtained by 307.Li _BIX 308or 309.Li _BIF 310object will be stored and reused for successive 311read access to this MIB within the specified period. 312.It Va hw.acpi.battery.units 313Number of battery units in the system. 314.It Va hw.acpi.battery.state 315Current battery charging status. 316This is same as 317.Va state 318of 319.Vt struct acpi_battinfo . 320.It Va hw.acpi.battery.rate 321Current battery discharging rate in mW. 322.It Va hw.acpi.battery.time 323Remaining battery life in minutes. 324If the battery is not discharging, 325the value shows 326.Li -1 . 327.It Va hw.acpi.battery.life 328Battery capacity in percent. 329.El 330.Sh EVENT NOTIFICATIONS 331Battery-related event notifications are sent 332to the userland via the 333.Xr devd 8 334interface. 335See 336.Pa /etc/devd.conf 337and 338.Xr devd.conf 5 339for more details. 340Note that notifications are supported only by 341the Control Method Battery. 342.Pp 343The 344.Nm 345driver sends events with the following attributes: 346.Pp 347.Bl -tag -width "subsystem" -compact 348.It system 349.Li ACPI 350.It subsystem 351.Li CMBAT 352.It type 353The fully qualified battery object path as in the ASL. 354.It notify 355An integer designating the event: 356.Pp 357.Bl -tag -width indent -compact 358.It Li 0x80 359Battery status was changed. 360.It Li 0x81 361Battery information was changed. 362.El 363.El 364.Sh SEE ALSO 365.Xr acpi 4 , 366.Xr acpiconf 8 367.Sh AUTHORS 368.An -nosplit 369.An Nate Lawson Aq Mt njl@FreeBSD.org , 370.An Munehiro Matsuda , 371.An Takanori Watanabe Aq Mt takawata@FreeBSD.org , 372.An Mitsuru IWASAKI Aq Mt iwasaki@FreeBSD.org , 373.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org , 374and 375.An Hiroki Sato Aq Mt hrs@FreeBSD.org . 376.Pp 377This manual page was written by 378.An Takanori Watanabe Aq Mt takawata@FreeBSD.org 379and 380.An Hiroki Sato Aq Mt hrs@FreeBSD.org . 381