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