share/man/man4/acpi_ibm.4

   1 .\" Copyright (c) 2005 Christian Brueffer
   2 .\" Copyright (c) 2005 Markus Brueffer
   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 June 24, 2020
  29 .Dt ACPI_IBM 4
  30 .Os
  31 .Sh NAME
  32 .Nm acpi_ibm
  33 .Nd "ThinkPad ACPI extras driver"
  34 .Sh SYNOPSIS
  35 To compile this driver into the kernel,
  36 place the following line in your
  37 kernel configuration file:
  38 .Bd -ragged -offset indent
  39 .Cd "device acpi_ibm"
  40 .Ed
  41 .Pp
  42 Alternatively, to load the driver as a
  43 module at boot time, place the following line in
  44 .Xr loader.conf 5 :
  45 .Bd -literal -offset indent
  46 acpi_ibm_load="YES"
  47 .Ed
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 driver provides support for hotkeys and other components of ThinkPad laptops.
  52 The main purpose of this driver is to provide an interface,
  53 accessible via
  54 .Xr sysctl 8
  55 and
  56 .Xr devd 8 ,
  57 through which applications can determine the status of
  58 various laptop components.
  59 .Pp
  60 While the
  61 .Xr sysctl 8
  62 interface is enabled automatically after loading the driver, the
  63 .Xr devd 8
  64 interface has to be enabled explicitly, as it may alter the default action of
  65 certain keys.
  66 This is done by setting the
  67 .Va events
  68 sysctl as described below.
  69 Specifying which keys should generate events is done by setting a bitmask,
  70 whereas each bit represents one key or key combination.
  71 This bitmask, accessible via the
  72 .Va eventmask
  73 sysctl, is set to
  74 .Va availmask
  75 by default, a value representing all possible keypress events on the specific
  76 ThinkPad model.
  77 .Ss Xr devd 8 Events
  78 Hotkey events received by
  79 .Xr devd 8
  80 provide the following information:
  81 .Pp
  82 .Bl -tag -width "subsystem" -offset indent -compact
  83 .It system
  84 .Qq Li ACPI
  85 .It subsystem
  86 .Qq Li IBM
  87 .It type
  88 The source of the event in the ACPI namespace.
  89 The value depends on the model.
  90 .It notify
  91 Event code (see below).
  92 .El
  93 .Pp
  94 Depending on the ThinkPad model, event codes may vary.
  95 On a ThinkPad T41p these are as follows:
  96 .Pp
  97 .Bl -tag -width "subsystem" -offset indent -compact
  98 .It Li 0x01
  99 Fn + F1
 100 .It Li 0x02
 101 Fn + F2
 102 .It Li 0x03
 103 Fn + F3 (LCD backlight)
 104 .It Li 0x04
 105 Fn + F4 (Suspend to RAM)
 106 .It Li 0x05
 107 Fn + F5 (Bluetooth)
 108 .It Li 0x06
 109 Fn + F6
 110 .It Li 0x07
 111 Fn + F7 (Screen expand)
 112 .It Li 0x08
 113 Fn + F8
 114 .It Li 0x09
 115 Fn + F9
 116 .It Li 0x0a
 117 Fn + F10
 118 .It Li 0x0b
 119 Fn + F11
 120 .It Li 0x0c
 121 Fn + F12 (Suspend to disk)
 122 .It Li 0x0d
 123 Fn + Backspace
 124 .It Li 0x0e
 125 Fn + Insert
 126 .It Li 0x0f
 127 Fn + Delete
 128 .It Li 0x10
 129 Fn + Home (Brightness up)
 130 .It Li 0x11
 131 Fn + End (Brightness down)
 132 .It Li 0x12
 133 Fn + PageUp (ThinkLight)
 134 .It Li 0x13
 135 Fn + PageDown
 136 .It Li 0x14
 137 Fn + Space (Zoom)
 138 .It Li 0x15
 139 Volume Up
 140 .It Li 0x16
 141 Volume Down
 142 .It Li 0x17
 143 Mute
 144 .It Li 0x18
 145 Access IBM Button
 146 .El
 147 .Ss Xr led 4 Interface
 148 The
 149 .Nm
 150 driver provides a
 151 .Xr led 4
 152 interface for the ThinkLight.
 153 The ThinkLight can be made to blink by writing
 154 .Tn ASCII
 155 strings to the
 156 .Pa /dev/led/thinklight
 157 device.
 158 .Sh SYSCTL VARIABLES
 159 The following sysctls are currently implemented:
 160 .Bl -tag -width indent
 161 .It Va dev.acpi_ibm.0.initialmask
 162 (read-only)
 163 Bitmask of ACPI events before the
 164 .Nm
 165 driver was loaded.
 166 .It Va dev.acpi_ibm.0.availmask
 167 (read-only)
 168 Bitmask of all supported ACPI events.
 169 .It Va dev.acpi_ibm.0.events
 170 Enable ACPI events and set the
 171 .Va eventmask
 172 to
 173 .Va availmask .
 174 Without the
 175 .Nm
 176 driver being loaded, only the Fn+F4 button generates an ACPI event.
 177 .It Va dev.acpi_ibm.0.eventmask
 178 Sets the ACPI events which are reported to
 179 .Xr devd 8 .
 180 Fn+F3, Fn+F4 and Fn+F12 always generate ACPI events, regardless which value
 181 .Va eventmask
 182 has.
 183 Depending on the ThinkPad model, the meaning of different bits in the
 184 .Va eventmask
 185 may vary.
 186 On a ThinkPad T41p this is a bitwise OR of the following:
 187 .Pp
 188 .Bl -tag -width indent-two -compact
 189 .It Li 1
 190 Fn + F1
 191 .It Li 2
 192 Fn + F2
 193 .It Li 4
 194 Fn + F3 (LCD backlight)
 195 .It Li 8
 196 Fn + F4 (Suspend to RAM)
 197 .It Li 16
 198 Fn + F5 (Bluetooth)
 199 .It Li 32
 200 Fn + F6
 201 .It Li 64
 202 Fn + F7 (Screen expand)
 203 .It Li 128
 204 Fn + F8
 205 .It Li 256
 206 Fn + F9
 207 .It Li 512
 208 Fn + F10
 209 .It Li 1024
 210 Fn + F11
 211 .It Li 2048
 212 Fn + F12 (Suspend to disk)
 213 .It Li 4096
 214 Fn + Backspace
 215 .It Li 8192
 216 Fn + Insert
 217 .It Li 16384
 218 Fn + Delete
 219 .It Li 32768
 220 Fn + Home (Brightness up)
 221 .It Li 65536
 222 Fn + End (Brightness down)
 223 .It Li 131072
 224 Fn + PageUp (ThinkLight)
 225 .It Li 262144
 226 Fn + PageDown
 227 .It Li 524288
 228 Fn + Space (Zoom)
 229 .It Li 1048576
 230 Volume Up
 231 .It Li 2097152
 232 Volume Down
 233 .It Li 4194304
 234 Mute
 235 .It Li 8388608
 236 Access IBM Button
 237 .El
 238 .It Va dev.acpi_ibm.0.hotkey
 239 (read-only)
 240 Status of several buttons.
 241 Every time a button is pressed, the respecting bit is toggled.
 242 It is a bitwise OR of the following:
 243 .Pp
 244 .Bl -tag -width indent-two -compact
 245 .It Li 1
 246 Home Button
 247 .It Li 2
 248 Search Button
 249 .It Li 4
 250 Mail Button
 251 .It Li 8
 252 Access IBM Button
 253 .It Li 16
 254 Zoom
 255 .It Li 32
 256 Wireless LAN Button
 257 .It Li 64
 258 Video Button
 259 .It Li 128
 260 Hibernate Button
 261 .It Li 256
 262 ThinkLight Button
 263 .It Li 512
 264 Screen Expand
 265 .It Li 1024
 266 Brightness Up/Down Button
 267 .It Li 2048
 268 Volume Up/Down/Mute Button
 269 .El
 270 .It Va dev.acpi_ibm.0.lcd_brightness
 271 Current brightness level of the display.
 272 .It Va dev.acpi_ibm.0.volume
 273 Speaker volume.
 274 .It Va dev.acpi_ibm.0.mute
 275 Indicates, whether the speakers are muted or not.
 276 .It Va dev.acpi_ibm.0.mic_mute
 277 Indicates, whether the microphone led (present on some model) is on or not.
 278 Note that this does not mean that the microphone input is muted.
 279 .It Va dev.acpi_ibm.0.thinklight
 280 Indicates, whether the ThinkLight keyboard light is activated or not.
 281 .It Va dev.acpi_ibm.0.bluetooth
 282 Toggle Bluetooth chip activity.
 283 .It Va dev.acpi_ibm.0.wlan
 284 (read-only)
 285 Indicates whether the WLAN chip is active or not.
 286 .It Va dev.acpi_ibm.0.fan
 287 Indicates whether the fan is in automatic (1) or manual (0) mode.
 288 Default is automatic mode.
 289 This sysctl should be used with extreme precaution, since disabling automatic
 290 fan control might overheat the ThinkPad and lead to permanent damage if the
 291 .Va fan_level
 292 is not set accordingly.
 293 .It Va dev.acpi_ibm.0.fan_level
 294 Indicates at what speed the fan should run when being in manual mode.
 295 Valid values range from 0 (off) to 7 (max) and 8.
 296 Level 8 is used by the driver to set the fan in unthrottled mode.
 297 In this mode, the fan is set to spin freely and will quickly reach a very
 298 high speed.
 299 Use this mode only if absolutely necessary, e.g., if the system has reached its
 300 critical temperature and it is about to shut down.
 301 The resulting speed differs from model to model.
 302 On a T41p this is as follows:
 303 .Pp
 304 .Bl -tag -width indent-two -compact
 305 .It Li 0
 306 off
 307 .It Li 1, 2
 308 ~3000 RPM
 309 .It Li 3, 4, 5
 310 ~3600 RPM
 311 .It Li 6, 7
 312 ~4300 RPM
 313 .It Li 8
 314 ~6400 RPM (Full-speed, unthrottled)
 315 .El
 316 .It Va dev.acpi_ibm.0.fan_speed
 317 (read-only)
 318 Fan speed in rounds per minute.
 319 A few older ThinkPads report the fan speed in levels ranging from 0 (off)
 320 to 7 (max).
 321 .It Va dev.acpi_ibm.0.thermal
 322 (read-only)
 323 Shows the readings of up to eight different temperature sensors.
 324 Most ThinkPads include six or more temperature sensors but
 325 only expose the CPU temperature through
 326 .Xr acpi_thermal 4 .
 327 Some ThinkPads have the below sensor layout which might vary depending on the
 328 specific model:
 329 .Pp
 330 .Bl -enum -compact
 331 .It
 332 CPU
 333 .It
 334 Mini PCI Module
 335 .It
 336 HDD
 337 .It
 338 GPU
 339 .It
 340 Built-in battery
 341 .It
 342 UltraBay battery
 343 .It
 344 Built-in battery
 345 .It
 346 UltraBay battery
 347 .El
 348 .It Va dev.acpi_ibm.0.handlerevents
 349 .Xr devd 8
 350 events handled by
 351 .Nm
 352 when
 353 .Va events
 354 is set to 1.
 355 Events are specified as a whitespace-separated list of event code in
 356 hexadecimal or decimal form.
 357 Note that the event maybe handled twice (e.g., Brightness up/down) if ACPI BIOS
 358 already handled the event.
 359 .El
 360 .Pp
 361 Defaults for these sysctls can be set in
 362 .Xr sysctl.conf 5 .
 363 .Sh FILES
 364 .Bl -tag -width ".Pa /dev/led/thinklight"
 365 .It Pa /dev/led/thinklight
 366 ThinkLight
 367 .Xr led 4
 368 device node
 369 .El
 370 .Sh EXAMPLES
 371 The following can be added to
 372 .Xr devd.conf 5
 373 in order to pass button events to a
 374 .Pa /usr/local/sbin/acpi_oem_exec.sh
 375 script:
 376 .Bd -literal -offset indent
 377 notify 10 {
 378         match "system"          "ACPI";
 379         match "subsystem"       "IBM";
 380         action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
 381 };
 382 .Ed
 383 .Pp
 384 A possible
 385 .Pa /usr/local/sbin/acpi_oem_exec.sh
 386 script might look like:
 387 .Bd -literal -offset indent
 388 #!/bin/sh
 389 #
 390 if [ "$1" = "" -o "$2" = "" ]
 391 then
 392         echo "usage: $0 notify oem_name"
 393         exit 1
 394 fi
 395 NOTIFY=`echo $1`
 396 LOGGER="logger"
 397 CALC="bc"
 398 BC_PRECOMMANDS="scale=2"
 399 ECHO="echo"
 400 CUT="cut"
 401 MAX_LCD_BRIGHTNESS=7
 402 MAX_VOLUME=14
 403 OEM=$2
 404 DISPLAY_PIPE=/tmp/acpi_${OEM}_display
 405
 406 case ${NOTIFY} in
 407         0x05)
 408                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
 409                 if [ "$LEVEL" = "1" ]
 410                 then
 411                         sysctl dev.acpi_${OEM}.0.bluetooth=0
 412                         MESSAGE="bluetooth disabled"
 413                 else
 414                         sysctl dev.acpi_${OEM}.0.bluetooth=1
 415                         MESSAGE="bluetooth enabled"
 416                 fi
 417                 ;;
 418         0x10|0x11)
 419                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
 420                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
 421                          ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
 422                          ${CALC} | ${CUT} -d . -f 1`
 423                 MESSAGE="brightness level ${PERCENT}%"
 424                 ;;
 425         0x12)
 426                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
 427                 if [ "$LEVEL" = "1" ]
 428                 then
 429                         MESSAGE="thinklight enabled"
 430                 else
 431                         MESSAGE="thinklight disabled"
 432                 fi
 433                 ;;
 434         0x15|0x16)
 435                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
 436                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
 437                         ${LEVEL} / ${MAX_VOLUME} * 100" | \\
 438                          ${CALC} | ${CUT} -d . -f 1`
 439                 MESSAGE="volume level ${PERCENT}%"
 440                 ;;
 441         0x17)
 442                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
 443                 if [ "$LEVEL" = "1" ]
 444                 then
 445                         MESSAGE="volume muted"
 446                 else
 447                         MESSAGE="volume unmuted"
 448                 fi
 449                 ;;
 450         0x1b)
 451                 LEVEL=`sysctl -n dev.acpi_ibm.0.mic_led`
 452                 if [ $LEVEL -eq 0 ]; then
 453                         sysctl dev.acpi_ibm.0.mic_led=1
 454                         mixer rec 0
 455                 fi
 456                 if [ $LEVEL -eq 1 ]; then
 457                         sysctl dev.acpi_ibm.0.mic_led=0
 458                         mixer rec 30
 459                 fi
 460                 ;;
 461         *)
 462                 ;;
 463 esac
 464 ${LOGGER} ${MESSAGE}
 465 if [ -p ${DISPLAY_PIPE} ]
 466 then
 467         ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
 468 fi
 469 exit 0
 470 .Ed
 471 .Pp
 472 The following example specify that event code 0x04 (Suspend to RAM),
 473 0x10 (Brightness up) and 0x11 (Brightness down) are handled by
 474 .Nm .
 475 .Bd -literal -offset indent
 476 sysctl dev.acpi_ibm.0.handlerevents='0x04 0x10 0x11'
 477 .Ed
 478 .Pp
 479 in
 480 .Xr sysctl.conf 5 :
 481 .Bd -literal -offset indent
 482 dev.acpi_ibm.0.handlerevents=0x04\\ 0x10\\ 0x11
 483 .Ed
 484 .Sh SEE ALSO
 485 .Xr acpi 4 ,
 486 .Xr led 4 ,
 487 .Xr sysctl.conf 5 ,
 488 .Xr devd 8 ,
 489 .Xr sysctl 8
 490 .Sh HISTORY
 491 The
 492 .Nm
 493 device driver first appeared in
 494 .Fx 6.0 .
 495 .Sh AUTHORS
 496 .An -nosplit
 497 The
 498 .Nm
 499 driver was written by
 500 .An Takanori Watanabe Aq Mt takawata@FreeBSD.org
 501 and later mostly rewritten by
 502 .An Markus Brueffer Aq Mt markus@FreeBSD.org .
 503 This manual page was written by
 504 .An Christian Brueffer Aq Mt brueffer@FreeBSD.org
 505 and
 506 .An Markus Brueffer Aq Mt markus@FreeBSD.org .