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