ACPI_IBM(4)

💖 acpi_ibm — the ACPI extras driver for IBM laptops 💖

okay bestie, sit DOWN, because this is the acpi_ibm(4) page and it's genuinely iconic. it lives in the Kernel Interfaces Manual, and it's about to tell you everything about hotkeys on IBM ThinkPads. no cap. 🫶

---

✨ NAME ✨

acpi_ibm — ACPI extras driver for IBM laptops

---

✨ SYNOPSIS ✨

so there's two ways to get this driver living in your life. pick your fighter. 💅

Way 1: compile it straight into the kernel. drop this line in your kernel configuration file:

device acpi_ibm

Way 2: load it as a module at boot time. put this line in loader.conf(5):

acpi_ibm_load="YES"

---

✨ DESCRIPTION ✨

okay so acpi_ibm is the driver that handles hotkeys and other components of IBM laptops. its whole thing — its main character purpose, if you will — is giving you an interface you can reach through sysctl(8) and devd(8), so your applications can figure out the status of all the various laptop components. it's giving middleman, but make it useful. 🌸

here's the tea tho: the sysctl(8) interface just turns itself on automatically after you load the driver. easy. effortless. slay. 🎀 but the devd(8) interface? nope, you have to enable that one explicitly, because it might alter the default action of certain keys. so you turn it on by setting the events sysctl, which we get into below.

now, how do you tell it which keys should generate events? with a bitmask, bestie. every bit = one key or key combo. this bitmask lives at the eventmask sysctl, and by default it's set to availmask — which is the value representing literally all the possible keypress events on your specific ThinkPad model. it just knows. 💫

🌈 devd(8) Events 🌈

the hotkey events that devd(8) receives come with the following info:

system     "ACPI"
subsystem  "IBM"
type       The source of the event in the ACPI namespace.  The
           value depends on the model.
notify     Event code (see below).

depending on the ThinkPad model, event codes may vary. on a ThinkPad T41p, they're giving:

0x01       Fn + F1
0x02       Fn + F2
0x03       Fn + F3 (LCD backlight)
0x04       Fn + F4 (Suspend to RAM)
0x05       Fn + F5 (Bluetooth)
0x06       Fn + F6
0x07       Fn + F7 (Screen expand)
0x08       Fn + F8
0x09       Fn + F9
0x0a       Fn + F10
0x0b       Fn + F11
0x0c       Fn + F12 (Suspend to disk)
0x0d       Fn + Backspace
0x0e       Fn + Insert
0x0f       Fn + Delete
0x10       Fn + Home (Brightness up)
0x11       Fn + End (Brightness down)
0x12       Fn + PageUp (ThinkLight)
0x13       Fn + PageDown
0x14       Fn + Space (Zoom)
0x15       Volume Up
0x16       Volume Down
0x17       Mute
0x18       Access IBM Button

🦋 led(4) Interface 🦋

the acpi_ibm driver also hooks you up with a led(4) interface for the ThinkLight. wanna make the ThinkLight blink? just write ASCII strings to the /dev/led/thinklight device. that's it. that's the whole vibe. ✨

---

✨ SYSCTL VARIABLES ✨

here are all the sysctls currently implemented, no gatekeeping:

• dev.acpi_ibm.0.initialmask — (read-only) bitmask of ACPI events before the acpi_ibm driver was loaded.
• dev.acpi_ibm.0.availmask — (read-only) bitmask of all supported ACPI events.
• dev.acpi_ibm.0.events — enables ACPI events and sets the eventmask to availmask. heads up: without the acpi_ibm driver being loaded, only the Fn+F4 button generates an ACPI event.
• dev.acpi_ibm.0.eventmask — sets which ACPI events get reported to devd(8). important note bestie: Fn+F3, Fn+F4 and Fn+F12 always generate ACPI events, regardless of whatever value eventmask has. and depending on your ThinkPad model, the meaning of different bits in the eventmask may vary. on a ThinkPad T41p it's a bitwise OR of the following:
  • 1 — Fn + F1
  • 2 — Fn + F2
  • 4 — Fn + F3 (LCD backlight)
  • 8 — Fn + F4 (Suspend to RAM)
  • 16 — Fn + F5 (Bluetooth)
  • 32 — Fn + F6
  • 64 — Fn + F7 (Screen expand)
  • 128 — Fn + F8
  • 256 — Fn + F9
  • 512 — Fn + F10
  • 1024 — Fn + F11
  • 2048 — Fn + F12 (Suspend to disk)
  • 4096 — Fn + Backspace
  • 8192 — Fn + Insert
  • 16384 — Fn + Delete
  • 32768 — Fn + Home (Brightness up)
  • 65536 — Fn + End (Brightness down)
  • 131072 — Fn + PageUp (ThinkLight)
  • 262144 — Fn + PageDown
  • 524288 — Fn + Space (Zoom)
  • 1048576 — Volume Up
  • 2097152 — Volume Down
  • 4194304 — Mute
  • 8388608 — Access IBM Button
• dev.acpi_ibm.0.hotkey — (read-only) status of several buttons. every time a button is pressed, the respecting bit is toggled. it's a bitwise OR of the following:
  • 1 — Home Button
  • 2 — Search Button
  • 4 — Mail Button
  • 8 — Access IBM Button
  • 16 — Zoom
  • 32 — Wireless LAN Button
  • 64 — Video Button
  • 128 — Hibernate Button
  • 256 — ThinkLight Button
  • 512 — Screen Expand
  • 1024 — Brightness Up/Down Button
  • 2048 — Volume Up/Down/Mute Button
• dev.acpi_ibm.0.lcd_brightness — current brightness level of the display.
• dev.acpi_ibm.0.volume — speaker volume.
• dev.acpi_ibm.0.mute — indicates whether the speakers are muted or not.
• dev.acpi_ibm.0.thinklight — indicates whether the ThinkLight keyboard light is activated or not.
• dev.acpi_ibm.0.bluetooth — toggle Bluetooth chip activity.
• dev.acpi_ibm.0.wlan — (read-only) indicates whether the WLAN chip is active or not.
• dev.acpi_ibm.0.fan — indicates whether the fan is in automatic (1) or manual (0) mode. default is automatic mode. 🚨 bestie, be so careful with this one — this sysctl should be used with extreme precaution, because disabling automatic fan control might overheat the ThinkPad and lead to permanent damage if the fan_level is not set accordingly. i am not joking, this is real.
• dev.acpi_ibm.0.fan_level — indicates at what speed the fan should run when being in manual mode. valid values range from 0 (off) to 7 (max) and 8. level 8 is used by the driver to set the fan in unthrottled mode. in this mode, the fan is set to spin freely and will quickly reach a very high speed. use this mode only if absolutely necessary, e.g., if the system has reached its critical temperature and it is about to shut down. the resulting speed differs from model to model. on a T41p this is as follows:
  • 0 — off
  • 1, 2 — ~3000 RPM
  • 3, 4, 5 — ~3600 RPM
  • 6, 7 — ~4300 RPM
  • 8 — ~6400 RPM (Full-speed, unthrottled)
• dev.acpi_ibm.0.fan_speed — (read-only) fan speed in rounds per minute. a few older ThinkPads report the fan speed in levels ranging from 0 (off) to 7 (max).
• dev.acpi_ibm.0.thermal — (read-only) shows the readings of up to eight different temperature sensors. most ThinkPads include six or more temperature sensors but only expose the CPU temperature through acpi_thermal(4). some ThinkPads have the below sensor layout, which might vary depending on the specific model:
  1. CPU
  2. Mini PCI Module
  3. HDD
  4. GPU
  5. Built-in battery
  6. UltraBay battery
  7. Built-in battery
  8. UltraBay battery
• dev.acpi_ibm.0.handlerevents — devd(8) events handled by acpi_ibm when events is set to 1. events are specified as a whitespace-separated list of event code in hexadecimal or decimal form. note that the event maybe handled twice (e.g., Brightness up/down) if ACPI BIOS already handled the event. 💀

defaults for these sysctls can be set in sysctl.conf(5). 🫶

---

✨ FILES ✨

• /dev/led/thinklight — ThinkLight led(4) device node

✨ EXAMPLES ✨

okay bestie, this is the part where it gets fun 🌈 you can literally wire your ThinkPad's buttons up to your own script. here's how.

drop this into devd.conf(5) and every button event gets handed off to a /usr/local/sbin/acpi_oem_exec.sh script:

notify 10 {
        match "system"          "ACPI";
        match "subsystem"       "IBM";
        action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
};

and like… what would that script even look like? glad you asked 💅 here's a possible /usr/local/sbin/acpi_oem_exec.sh:

#!/bin/sh
#
if [ "$1" = "" -o "$2" = "" ]
then
        echo "usage: $0 notify oem_name"
        exit 1
fi
NOTIFY=`echo $1`
LOGGER="logger"
CALC="bc"
BC_PRECOMMANDS="scale=2"
ECHO="echo"
CUT="cut"
MAX_LCD_BRIGHTNESS=7
MAX_VOLUME=14
OEM=$2
DISPLAY_PIPE=/tmp/acpi_${OEM}_display

case ${NOTIFY} in
        0x05)
                LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
                if [ "$LEVEL" = "1" ]
                then
                        sysctl dev.acpi_${OEM}.0.bluetooth=0
                        MESSAGE="bluetooth disabled"
                else
                        sysctl dev.acpi_${OEM}.0.bluetooth=1
                        MESSAGE="bluetooth enabled"
                fi
                ;;
        0x10|0x11)
                LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \
                         ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\
                         ${CALC} | ${CUT} -d . -f 1`
                MESSAGE="brightness level ${PERCENT}%"
                ;;
        0x12)
                LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
                if [ "$LEVEL" = "1" ]
                then
                        MESSAGE="thinklight enabled"
                else
                        MESSAGE="thinklight disabled"
                fi
                ;;
        0x15|0x16)
                LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \
                        ${LEVEL} / ${MAX_VOLUME} * 100" | \
                         ${CALC} | ${CUT} -d . -f 1`
                MESSAGE="volume level ${PERCENT}%"
                ;;
        0x17)
                LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
                if [ "$LEVEL" = "1" ]
                then
                        MESSAGE="volume muted"
                else
                        MESSAGE="volume unmuted"
                fi
                ;;
        *)
                ;;
esac
${LOGGER} ${MESSAGE}
if [ -p ${DISPLAY_PIPE} ]
then
        ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
fi
exit 0

so cute, so useful 🎀 (the ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100 bit is just turning a raw 0–7 into a percent for you, iykyk)

and if you want to be specific about which buttons acpi_ibm should handle, here's an example saying event code 0x04 (Suspend to RAM), 0x10 (Brightness up) and 0x11 (Brightness down) are all on acpi_ibm's plate:

sysctl dev.acpi_ibm.0.handlerevents='0x04 0x10 0x11'

and the same energy, but inside sysctl.conf(5) (note the escaped spaces, she's picky 🙈):

dev.acpi_ibm.0.handlerevents=0x04\ 0x10\ 0x11

---

🌸 SEE ALSO 🌸

• acpi(4)
• led(4)
• sysctl.conf(5)
• devd(8)
• sysctl(8)

---

👑 HISTORY 👑

the acpi_ibm device driver first appeared in FreeBSD 6.0. an icon, a legend, a moment in time ⭐

---

💖 AUTHORS 💖

the acpi_ibm driver was written by Takanori Watanabe <takawata@FreeBSD.org> and later mostly rewritten by Markus Brueffer <markus@FreeBSD.org>. this manual page was written by Christian Brueffer <brueffer@FreeBSD.org> and Markus Brueffer <markus@FreeBSD.org>. absolute main characters, no cap 🫶

---

and that's the whole page bestie!! 💅 this was the Debian build, dated June 24, 2020, for ACPI_IBM(4) — go forth and press buttons, you got this 🦋✨