--- name: "acpi_battery" section: "4" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/acpi_battery" --- # acpi\_battery(4) ACPI battery management subsystem ## NAME **acpi\_battery** – ACPI battery management subsystem ## SYNOPSIS **device acpi** ## DESCRIPTION The **acpi\_battery** 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 (ACPI Machine Language) code control methods, and the latter is controlled directly through the ACPI EC (Embedded Controller) typically via an SMBus interface. This driver supports the [sysctl(8)](/sysctl/8.md) and [ioctl(2)](/ioctl/2.md) interfaces as well as the [devd(8)](/devd/8.md) event notification interface. ## IOCTLS Every ioctl for the **acpi\_battery** 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 ACPI\_BATTERY\_ALL\_UNITS specifies all of the attached units and reports accumulated information. - ACPIIO\_BATT\_GET\_UNITS *int* Returns the number of battery units in the system. The unit number argument will be ignored. - ACPIIO\_BATT\_GET\_BATTINFO *struct* *acpi\_battinfo* Returns the following: - *cap* Battery capacity in percent, - *min* Remaining battery life in minutes, - *state* Current status of the battery encoded in the following: - ACPI\_BATT\_STAT\_DISCHARG (0x0001) Battery is discharging, - ACPI\_BATT\_STAT\_CHARGING (0x0002) Battery is being charged, or - ACPI\_BATT\_STAT\_CRITICAL (0x0004) Remaining battery life is critically low. Note that the status bits of each battery will be consolidated when ACPI\_BATTERY\_ALL\_UNITS is specified. - *rate* Current battery discharging rate in mW. -1 means not discharging right now. - ACPIIO\_BATT\_GET\_BIX *struct* *acpi\_bix* Returns battery information given by the ACPI \_BIX (Battery Information) object, which is the static portion of the Control Method Battery information. In the case of a Smart Battery attached to SMBus or a Control Method Battery with a \_BIF object, this ioctl will build a *struct* *acpi\_bix* structure based on the obtained information and return it. - *rev* Revision number of the object. There are the following well-known values: - ACPI\_BIX\_REV\_0 (0x0000) A \_BIX object in ACPI 4.0. - ACPI\_BIX\_REV\_1 (0x0001) A \_BIX object in ACPI 6.0. - ACPI\_BIX\_REV\_BIF (0xffff) A \_BIX object built from the \_BIF object found on the system. Note that this field should be checked by using **ACPI\_BIX\_REV\_MIN\_CHECK**(*var*, *rev*) macro when checking the minimum revision number. - *units* Indicates the units used by the battery to report its capacity and charge rate encoded in the following: - ACPI\_BIX\_UNITS\_MW (0x00000000) in mW (power) - ACPI\_BIX\_UNITS\_MA (0x00000001) in mA (current) Note that capacity is expressed in mWh or mAh, and rate is expressed in mW or mA, respectively. - *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 *units*. - *lfcap* Predicted battery capacity when fully charged. Typically this will decrease every charging cycle. - btech Battery technology: - 0x00000000 Primary cell (non-rechargeable) - 0x00000001 Secondary cell (rechargeable) - *dvol* Design voltage in mV, which is the nominal voltage of a new battery. - *wcap* Design capacity of warning. When a discharging battery device reaches this capacity, notification is sent to the system. - *lcap* Design capacity of low. - *cycles* (rev 0 or newer) The number of cycles the battery has experienced. A cycle means an amount of discharge occurred which was approximately equal to the value of Design Capacity. - *accuracy* (rev 0 or newer) The accuracy of the battery capacity measurement, in thousandth of a percent. - *stmax* (rev 0 or newer) The Maximum Sampling Time of the battery in milliseconds. This is the maximum duration between two consecutive measurements of the battery's capacities specified in \_BST. If two succeeding readings of \_BST beyond this duration occur, two different results can be returned. - *stmin* (rev 0 or newer) The Minimum Sampling Time of the battery in milliseconds. - *aimax* (rev 0 or newer) The Maximum Average Interval of the battery in milliseconds. This is the length of time within which the battery averages the capacity measurements specified in \_BST. The Sampling Time specifies the frequency of measurements, and the Average Interval specifies the width of the time window of every measurement. - *aimin* (rev 0 or newer) The Minimum Average Interval of the battery in milliseconds. - *gra1* Battery capacity granularity between *low* and *warning*. This is expressed as power or current depending on the value of *units*. - *gra2* Battery capacity granularity between *warning* and *full*. This is expressed as power or current depending on the value of *units*. - *model* Model number of the battery as a string. - *serial* Serial number of the battery as a string. - *type* Type identifier of the battery as a string. - *oeminfo* OEM-specific information of the battery as a string. - *scap* (rev 1 or newer) Battery swapping capability encoded in the following: - ACPI\_BIX\_SCAP\_NO (0x00000000) Non-swappable - ACPI\_BIX\_SCAP\_COLD (0x00000001) Cold-swappable - ACPI\_BIX\_SCAP\_HOT (0x00000010) Hot-swappable - ACPIIO\_BATT\_GET\_BIF *struct* *acpi\_bif* (deprecated) Returns battery information given by the ACPI \_BIF (Battery Information) object, which was deprecated in ACPI 4.0 specification. The data structure is a subset of *struct* *acpi\_bix*. Note that this ioctl will built a *struct* *acpi\_bif* structure based on the obtained information even if this object is not available and a \_BIX object is found. - ACPIIO\_BATT\_GET\_BST *struct* *acpi\_bst* Returns battery information given by the ACPI \_BST (Battery Status) object, which is the present battery status. In the case of a Smart Battery attached to SMBus, this ioctl will build a *struct* *acpi\_bst* structure based on the obtained information and return it. - *state* Battery state. The value is encoded in the same way as *state* of *struct* *acpi\_battinfo*. - *rate* Battery present rate of charging or discharging. The unit of the value depends on *unit* of *struct* *acpi\_bif*. - *cap* Battery remaining capacity. The unit of this value depends on *unit* of *struct* *acpi\_bif*. - *volt* Battery present voltage. ## SYSCTL VARIABLES The following [sysctl(8)](/sysctl/8.md) variables export battery status. Note that they are accumulated status of all of the connected batteries: - *hw.acpi.battery.info\_expire* Information cache expiration time in seconds. The battery information obtained by \_BIX or \_BIF object will be stored and reused for successive read access to this MIB within the specified period. - *hw.acpi.battery.units* Number of battery units in the system. - *hw.acpi.battery.state* Current battery charging status. This is same as *state* of *struct* *acpi\_battinfo*. - *hw.acpi.battery.rate* Current battery discharging rate in mW. - *hw.acpi.battery.time* Remaining battery life in minutes. If the battery is not discharging, the value shows -1. - *hw.acpi.battery.life* Battery capacity in percent. ## EVENT NOTIFICATIONS Battery-related event notifications are sent to the userland via the [devd(8)](/devd/8.md) interface. See */etc/devd.conf* and [devd.conf(5)](/devd.conf/5.md) for more details. Note that notifications are supported only by the Control Method Battery. The **acpi\_battery** driver sends events with the following attributes: - system ACPI - subsystem CMBAT - type The fully qualified battery object path as in the ASL. - notify An integer designating the event: - 0x80 Battery status was changed. - 0x81 Battery information was changed. ## SEE ALSO [acpi(4)](/acpi/4.md), [acpiconf(8)](/acpiconf/8.md) ## AUTHORS Nate Lawson ⟨*njl@FreeBSD.org*⟩, Munehiro Matsuda, Takanori Watanabe ⟨*takawata@FreeBSD.org*⟩, Mitsuru IWASAKI ⟨*iwasaki@FreeBSD.org*⟩, Hans Petter Selasky ⟨*hselasky@FreeBSD.org*⟩, and Hiroki Sato ⟨*hrs@FreeBSD.org*⟩. This manual page was written by Takanori Watanabe ⟨*takawata@FreeBSD.org*⟩ and Hiroki Sato ⟨*hrs@FreeBSD.org*⟩.