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 January 14, 2006
  29 .Dt ACPI_IBM 4 i386
  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 .El
 339 .Pp
 340 Defaults for these sysctls can be set in
 341 .Xr sysctl.conf 5 .
 342 .Sh FILES
 343 .Bl -tag -width ".Pa /dev/led/thinklight"
 344 .It Pa /dev/led/thinklight
 345 ThinkLight
 346 .Xr led 4
 347 device node
 348 .El
 349 .Sh EXAMPLES
 350 The following can be added to
 351 .Xr devd.conf 5
 352 in order to pass button events to a
 353 .Pa /usr/local/sbin/acpi_oem_exec.sh
 354 script:
 355 .Bd -literal -offset indent
 356 notify 10 {
 357         match "system"          "ACPI";
 358         match "subsystem"       "IBM";
 359         action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
 360 };
 361 .Ed
 362 .Pp
 363 A possible
 364 .Pa /usr/local/sbin/acpi_oem_exec.sh
 365 script might look like:
 366 .Bd -literal -offset indent
 367 #!/bin/sh
 368 #
 369 if [ "$1" = "" -o "$2" = "" ]
 370 then
 371         echo "usage: $0 notify oem_name"
 372         exit 1
 373 fi
 374 NOTIFY=`echo $1`
 375 LOGGER="logger"
 376 CALC="bc"
 377 BC_PRECOMMANDS="scale=2"
 378 ECHO="echo"
 379 CUT="cut"
 380 MAX_LCD_BRIGHTNESS=7
 381 MAX_VOLUME=14
 382 OEM=$2
 383 DISPLAY_PIPE=/tmp/acpi_${OEM}_display
 384
 385 case ${NOTIFY} in
 386         0x05)
 387                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
 388                 if [ "$LEVEL" = "1" ]
 389                 then
 390                         sysctl dev.acpi_${OEM}.0.bluetooth=0
 391                         MESSAGE="bluetooth disabled"
 392                 else
 393                         sysctl dev.acpi_${OEM}.0.bluetooth=1
 394                         MESSAGE="bluetooth enabled"
 395                 fi
 396                 ;;
 397         0x10|0x11)
 398                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
 399                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
 400                          ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
 401                          ${CALC} | ${CUT} -d . -f 1`
 402                 MESSAGE="brightness level ${PERCENT}%"
 403                 ;;
 404         0x12)
 405                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
 406                 if [ "$LEVEL" = "1" ]
 407                 then
 408                         MESSAGE="thinklight enabled"
 409                 else
 410                         MESSAGE="thinklight disabled"
 411                 fi
 412                 ;;
 413         0x15|0x16)
 414                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
 415                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
 416                         ${LEVEL} / ${MAX_VOLUME} * 100" | \\
 417                          ${CALC} | ${CUT} -d . -f 1`
 418                 MESSAGE="volume level ${PERCENT}%"
 419                 ;;
 420         0x17)
 421                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
 422                 if [ "$LEVEL" = "1" ]
 423                 then
 424                         MESSAGE="volume muted"
 425                 else
 426                         MESSAGE="volume unmuted"
 427                 fi
 428                 ;;
 429         *)
 430                 ;;
 431 esac
 432 ${LOGGER} ${MESSAGE}
 433 if [ -p ${DISPLAY_PIPE} ]
 434 then
 435         ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
 436 fi
 437 exit 0
 438 .Ed
 439 .Sh SEE ALSO
 440 .Xr acpi 4 ,
 441 .Xr led 4 ,
 442 .Xr sysctl.conf 5 ,
 443 .Xr devd 8 ,
 444 .Xr sysctl 8
 445 .Sh HISTORY
 446 The
 447 .Nm
 448 device driver first appeared in
 449 .Fx 6.0 .
 450 .Sh AUTHORS
 451 .An -nosplit
 452 The
 453 .Nm
 454 driver was written by
 455 .An Takanori Watanabe Aq takawata@FreeBSD.org
 456 and later mostly rewritten by
 457 .An Markus Brueffer Aq markus@FreeBSD.org .
 458 This manual page was written by
 459 .An Christian Brueffer Aq brueffer@FreeBSD.org
 460 and
 461 .An Markus Brueffer Aq markus@FreeBSD.org .