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 19, 2015
  29 .Dt ACPI_IBM 4
  30 .Os
  31 .Sh NAME
  32 .Nm acpi_ibm
  33 .Nd "ACPI extras driver for IBM laptops"
  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 IBM 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 Values are ranging from 0 (off) to 7 (max).
 296 The resulting speed differs from model to model.
 297 On a T41p this is as follows:
 298 .Pp
 299 .Bl -tag -width indent-two -compact
 300 .It Li 0
 301 off
 302 .It Li 1, 2
 303 ~3000 RPM
 304 .It Li 3, 4, 5
 305 ~3600 RPM
 306 .It Li 6, 7
 307 ~4300 RPM
 308 .El
 309 .It Va dev.acpi_ibm.0.fan_speed
 310 (read-only)
 311 Fan speed in rounds per minute.
 312 A few older ThinkPads report the fan speed in levels ranging from 0 (off)
 313 to 7 (max).
 314 .It Va dev.acpi_ibm.0.thermal
 315 (read-only)
 316 Shows the readings of up to eight different temperature sensors.
 317 Most ThinkPads include six or more temperature sensors but
 318 only expose the CPU temperature through
 319 .Xr acpi_thermal 4 .
 320 Some ThinkPads have the below sensor layout which might vary depending on the
 321 specific model:
 322 .Pp
 323 .Bl -enum -compact
 324 .It
 325 CPU
 326 .It
 327 Mini PCI Module
 328 .It
 329 HDD
 330 .It
 331 GPU
 332 .It
 333 Built-in battery
 334 .It
 335 UltraBay battery
 336 .It
 337 Built-in battery
 338 .It
 339 UltraBay battery
 340 .El
 341 .It Va dev.acpi_ibm.0.handlerevents
 342 .Xr devd 8
 343 events handled by
 344 .Nm
 345 when
 346 .Va events
 347 is set to 1.
 348 Events are specified as a whitespace-separated list of event code in
 349 hexadecimal or decimal form.
 350 Note that the event maybe handled twice (e.g., Brightness up/down) if ACPI BIOS
 351 already handled the event.
 352 .El
 353 .Pp
 354 Defaults for these sysctls can be set in
 355 .Xr sysctl.conf 5 .
 356 .Sh FILES
 357 .Bl -tag -width ".Pa /dev/led/thinklight"
 358 .It Pa /dev/led/thinklight
 359 ThinkLight
 360 .Xr led 4
 361 device node
 362 .El
 363 .Sh EXAMPLES
 364 The following can be added to
 365 .Xr devd.conf 5
 366 in order to pass button events to a
 367 .Pa /usr/local/sbin/acpi_oem_exec.sh
 368 script:
 369 .Bd -literal -offset indent
 370 notify 10 {
 371         match "system"          "ACPI";
 372         match "subsystem"       "IBM";
 373         action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
 374 };
 375 .Ed
 376 .Pp
 377 A possible
 378 .Pa /usr/local/sbin/acpi_oem_exec.sh
 379 script might look like:
 380 .Bd -literal -offset indent
 381 #!/bin/sh
 382 #
 383 if [ "$1" = "" -o "$2" = "" ]
 384 then
 385         echo "usage: $0 notify oem_name"
 386         exit 1
 387 fi
 388 NOTIFY=`echo $1`
 389 LOGGER="logger"
 390 CALC="bc"
 391 BC_PRECOMMANDS="scale=2"
 392 ECHO="echo"
 393 CUT="cut"
 394 MAX_LCD_BRIGHTNESS=7
 395 MAX_VOLUME=14
 396 OEM=$2
 397 DISPLAY_PIPE=/tmp/acpi_${OEM}_display
 398
 399 case ${NOTIFY} in
 400         0x05)
 401                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
 402                 if [ "$LEVEL" = "1" ]
 403                 then
 404                         sysctl dev.acpi_${OEM}.0.bluetooth=0
 405                         MESSAGE="bluetooth disabled"
 406                 else
 407                         sysctl dev.acpi_${OEM}.0.bluetooth=1
 408                         MESSAGE="bluetooth enabled"
 409                 fi
 410                 ;;
 411         0x10|0x11)
 412                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
 413                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
 414                          ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
 415                          ${CALC} | ${CUT} -d . -f 1`
 416                 MESSAGE="brightness level ${PERCENT}%"
 417                 ;;
 418         0x12)
 419                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
 420                 if [ "$LEVEL" = "1" ]
 421                 then
 422                         MESSAGE="thinklight enabled"
 423                 else
 424                         MESSAGE="thinklight disabled"
 425                 fi
 426                 ;;
 427         0x15|0x16)
 428                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
 429                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
 430                         ${LEVEL} / ${MAX_VOLUME} * 100" | \\
 431                          ${CALC} | ${CUT} -d . -f 1`
 432                 MESSAGE="volume level ${PERCENT}%"
 433                 ;;
 434         0x17)
 435                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
 436                 if [ "$LEVEL" = "1" ]
 437                 then
 438                         MESSAGE="volume muted"
 439                 else
 440                         MESSAGE="volume unmuted"
 441                 fi
 442                 ;;
 443         0x1b)
 444                 LEVEL=`sysctl -n dev.acpi_ibm.0.mic_led`
 445                 if [ $LEVEL -eq 0 ]; then
 446                         sysctl dev.acpi_ibm.0.mic_led=1
 447                         mixer rec 0
 448                 fi
 449                 if [ $LEVEL -eq 1 ]; then
 450                         sysctl dev.acpi_ibm.0.mic_led=0
 451                         mixer rec 30
 452                 fi
 453                 ;;
 454         *)
 455                 ;;
 456 esac
 457 ${LOGGER} ${MESSAGE}
 458 if [ -p ${DISPLAY_PIPE} ]
 459 then
 460         ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
 461 fi
 462 exit 0
 463 .Ed
 464 .Pp
 465 The following example specify that event code 0x04 (Suspend to RAM),
 466 0x10 (Brightness up) and 0x11 (Brightness down) are handled by
 467 .Nm .
 468 .Bd -literal -offset indent
 469 sysctl dev.acpi_ibm.0.handlerevents='0x04 0x10 0x11'
 470 .Ed
 471 .Pp
 472 in
 473 .Xr sysctl.conf 5 :
 474 .Bd -literal -offset indent
 475 dev.acpi_ibm.0.handlerevents=0x04\\ 0x10\\ 0x11
 476 .Ed
 477 .Sh SEE ALSO
 478 .Xr acpi 4 ,
 479 .Xr led 4 ,
 480 .Xr sysctl.conf 5 ,
 481 .Xr devd 8 ,
 482 .Xr sysctl 8
 483 .Sh HISTORY
 484 The
 485 .Nm
 486 device driver first appeared in
 487 .Fx 6.0 .
 488 .Sh AUTHORS
 489 .An -nosplit
 490 The
 491 .Nm
 492 driver was written by
 493 .An Takanori Watanabe Aq Mt takawata@FreeBSD.org
 494 and later mostly rewritten by
 495 .An Markus Brueffer Aq Mt markus@FreeBSD.org .
 496 This manual page was written by
 497 .An Christian Brueffer Aq Mt brueffer@FreeBSD.org
 498 and
 499 .An Markus Brueffer Aq Mt markus@FreeBSD.org .