share/man/man4/acpi_battery.4

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