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