ACPI_BATTERY(4)

📦
version 15.1 · 2 versions
, in freebsd 14.5, freebsd 15.1

💖 ACPI_BATTERY(4) 💖

Okay so picture this: you're on your laptop, vibing, and you need to know what's up with your battery. That's literally where acpi_battery comes in — it's the ACPI battery management subsystem, and it's here to serve cunt and keep you informed. Periodt. 🔋✨

✨ SYNOPSIS ✨

device acpi

🌸 DESCRIPTION 🌸

So acpi_battery is literally the driver for battery management features of the ACPI module, bestie. It's giving main character energy in your kernel. 💅

An ACPI-compatible battery device supports either a Control Method Battery interface or a Smart Battery subsystem interface — like, it's one or the other, no cap. The Control Method Battery one is accessed by the AML (ACPI Machine Language) code control methods. The Smart Battery one? That's controlled directly through the ACPI EC (Embedded Controller), typically via an SMBus interface. Iykyk. 🎀

This driver is literally so versatile — it supports the sysctl(8) and ioctl(2) interfaces as well as the devd(8) event notification interface. Obsessed. 🌈

👑 IOCTLS 👑

Okay so every single 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. That's just how it is. 💁‍♀️

And here's the tea: there's a special unit number ACPI_BATTERY_ALL_UNITS that literally specifies ALL of the attached units and reports accumulated information. It's giving "we're all in this together" energy. 🫶

  • ACPIIO_BATT_GET_UNITS int — Returns the number of battery units in the system. The unit number argument will be ignored. Like, it literally doesn't care what you pass. 💀
  • ACPIIO_BATT_GET_BATTINFO struct acpi_battinfo — Returns the following, bestie:
    • cap — Battery capacity in percent. Giving you the numbers. 📊
    • min — Remaining battery life in minutes. Like, how long until you need to find a charger. 😭
    • state — Current status of the battery encoded in the following:
      • ACPI_BATT_STAT_DISCHARG (0x0001) — Battery is discharging. You're on your own, bestie. 💀
      • ACPI_BATT_STAT_CHARGING (0x0002) — Battery is being charged. Slay, plug that in. 🔌
      • ACPI_BATT_STAT_CRITICAL (0x0004) — Remaining battery life is critically low. Like, panic mode. 🚨

Note that the status bits of each battery will be consolidated when ACPI_BATTERY_ALL_UNITS is specified. So it's like a group chat for all your batteries. 💬

  • rate — Current battery discharging rate in mW. -1 means not discharging right now. So if it's -1, you're chillin'. 😌
  • 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. It's giving "here's the permanent record" vibes. 📋

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. It's adaptable, it's iconic. ✨

  • 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. Vintage, but make it fashion. 🕰️
    • ACPI_BIX_REV_1 (0x0001) — A _BIX object in ACPI 6.0. The newer model. 💅
    • ACPI_BIX_REV_BIF (0xffff) — A _BIX object built from the _BIF object found on the system. Like, we made it work. 💪

Note that this field should be checked by using ACPI_BIX_REV_MIN_CHECK(var, rev) macro when checking the minimum revision number. That's the move, bestie. 🎯

  • 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). It's giving watts but milli. ⚡
    • ACPI_BIX_UNITS_MA (0x00000001) — in mA (current). Current affairs, literally. 🌊

Note that capacity is expressed in mWh or mAh, and rate is expressed in mW or mA, respectively. Just so you know. 🧚

  • 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. Like, what it was born with. 👶
  • lfcap — Predicted battery capacity when fully charged. Typically this will decrease every charging cycle. Aging like fine wine, but in reverse. 🍷
  • btech — Battery technology:
    • 0x00000000 — Primary cell (non-rechargeable). One and done. 💀
    • 0x00000001 — Secondary cell (rechargeable). The sustainable queen. 🌱
  • dvol — Design voltage in mV, which is the nominal voltage of a new battery. Voltage, but make it design. ⚡
  • wcap — Design capacity of warning. When a discharging battery device reaches this capacity, notification is sent to the system. It's giving "hey bestie, heads up." 📢
  • lcap — Design capacity of low. Like, lower than warning. The stakes are higher. 📉
  • 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. It's like a battery's step count. 👟
  • accuracy — (rev 0 or newer) The accuracy of the battery capacity measurement, in thousandth of a percent. Precision, honey. 🎯
  • 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. Like, it's giving inconsistent. 🙈
  • stmin — (rev 0 or newer) The Minimum Sampling Time of the battery in milliseconds. The floor, the minimum, the "at least this often." ⏱️
  • 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. It's giving data science, honestly. 📊
  • aimin — (rev 0 or newer) The Minimum Average Interval of the battery in milliseconds. The lower bound, bestie. 📏
  • gra1 — Battery capacity granularity between low and warning. This is expressed as power or current depending on the value of units. Granular, like your fave eyeshadow palette. 💄
  • gra2 — Battery capacity granularity between warning and full. This is expressed as power or current depending on the value of units. More granularity, more power. 💅
  • model — Model number of the battery as a string. It's giving identity. 🏷️
  • serial — Serial number of the battery as a string. Unique, like you. 🌟
  • type — Type identifier of the battery as a string. Categorization, honey. 📁
  • oeminfo — OEM-specific information of the battery as a string. The manufacturer's little secret. 🤫
  • scap — (rev 1 or newer) Battery swapping capability encoded in the following:
    • ACPI_BIX_SCAP_NO (0x00000000) — Non-swappable. You're stuck with it. 💀
    • ACPI_BIX_SCAP_COLD (0x00000001) — Cold-swappable. Swap it while it's off. 🧊
    • ACPI_BIX_SCAP_HOT (0x00000010) — Hot-swappable. Swap it while it's running, living dangerously. 🔥
  • 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. It's giving vintage, but not in a cute way. The data structure is a subset of struct acpi_bix. So it's like the little sibling. 👶

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. It's resourceful, okay? 💁‍♀️

  • ACPIIO_BATT_GET_BST struct acpi_bst — Returns battery information given by the ACPI _BST (Battery Status) object, which is the present battery status. Like, what's happening right now. 📍

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. It's adaptable. ✨

  • state — Battery state. The value is encoded in the same way as state of struct acpi_battinfo. Same vibes, different struct. 💫
  • rate — Battery present rate of charging or discharging. The unit of the value depends on unit of struct acpi_bif. So like, check the units, bestie. 📏
  • cap — Battery remaining capacity. The unit of this value depends on unit of struct acpi_bif. Again, units matter. 🧮
  • volt — Battery present voltage. The juice, the power, the voltage. ⚡

🦋 SYSCTL VARIABLES 🦋

Okay so the following sysctl(8) variables export battery status. Note that they are accumulated status of all of the connected batteries — it's giving collective energy. 🌍

  • 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. It's giving "remember this for later." 🧠
  • hw.acpi.battery.units — Number of battery units in the system. Count 'em. 🔢
  • hw.acpi.battery.state — Current battery charging status. This is same as state of struct acpi_battinfo. Same energy, different variable. 💅
  • hw.acpi.battery.rate — Current battery discharging rate in mW. The speed at which you're losing power. 📉
  • hw.acpi.battery.time — Remaining battery life in minutes. If the battery is not discharging, the value shows -1. So -1 means you're chillin'. 😎
  • hw.acpi.battery.life — Battery capacity in percent. The big number, the one you check when you're anxious. 🔋

🌈 EVENT NOTIFICATIONS 🌈

Battery-related event notifications are sent to the userland via the devd(8) interface. See /etc/devd.conf and devd.conf(5) for more details. It's giving communication, it's giving connection. 📡

Note that notifications are supported only by the Control Method Battery. Like, only that one. Don't @ me. 🙅‍♀️

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. Something's different. 👀
    • 0x81 — Battery information was changed. New info dropped. 📬

💜 SEE ALSO 💜

acpi(4), acpiconf(8)

🎀 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>. Legends, all of them. 👑

This manual page was written by Takanori Watanabe <takawata@FreeBSD.org> and Hiroki Sato <hrs@FreeBSD.org>. Icons. ✨

This slay page is brought to you by Debian, from the Kernel Interfaces Manual, dated February 16, 2020. Periodt. 💅💖

📦 where this page comes from