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 358333 2020-02-26 14:26:36Z kaktus $
  27 .\"
  28 .Dd June 1, 2020
  29 .Dt ACPI_THINKPAD 4
  30 .Os
  31 .Sh NAME
  32 .Nm acpi_thinkpad
  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_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 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 THINKPAD
  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 THINKPAD 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_thinkpad.<node>.initialmask
 162 (read-only)
 163 Bitmask of ACPI events before the
 164 .Nm
 165 driver was loaded.
 166 .It Va dev.acpi_thinkpad.<node>.availmask
 167 (read-only)
 168 Bitmask of all supported ACPI events.
 169 .It Va dev.acpi_thinkpad.<node>.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_thinkpad.<node>.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 THINKPAD Button
 237 .El
 238 .It Va dev.acpi_thinkpad.<node>.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 THINKPAD 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_thinkpad.<node>.lcd_brightness
 271 Current brightness level of the display.
 272 .It Va dev.acpi_thinkpad.<node>.volume
 273 Speaker volume.
 274 .It Va dev.acpi_thinkpad.<node>.mute
 275 Indicates, whether the speakers are muted or not.
 276 .It Va dev.acpi_thinkpad.<node>.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_thinkpad.<node>.thinklight
 280 Indicates, whether the ThinkLight keyboard light is activated or not.
 281 .It Va dev.acpi_thinkpad.<node>.bluetooth
 282 Toggle Bluetooth chip activity.
 283 .It Va dev.acpi_thinkpad.<node>.wlan
 284 (read-only)
 285 Indicates whether the WLAN chip is active or not.
 286 .It Va dev.acpi_thinkpad.<node>.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_thinkpad.<node>.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_thinkpad.<node>.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 hw.acpi.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_thinkpad.<node>.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 may be handled twice (eg. Brightness up/down) if ACPI BIOS
 351 already handled the event.
 352 .It Va hw.sensors.acpi_thinkpad0.tempX
 353 Show the readings of up to eight different temperature sensors.
 354 .It Va hw.sensors.acpi_thinkpad0.fan0
 355 Fan speed in rounds per minute.
 356 .\" A few older ThinkPads report the fan speed in levels ranging from 0 (off)
 357 .\" to 7 (max).
 358 .El
 359 .Pp
 360 Defaults for these sysctls can be set in
 361 .Xr sysctl.conf 5 .
 362 Sensors can be monitored by
 363 .Xr sensorsd 8 .
 364 .Sh FILES
 365 .Bl -tag -width ".Pa /dev/led/thinklight"
 366 .It Pa /dev/led/thinklight
 367 ThinkLight
 368 .Xr led 4
 369 device node
 370 .El
 371 .Sh EXAMPLES
 372 The following can be added to
 373 .Xr devd.conf 5
 374 in order to pass button events to a
 375 .Pa /usr/local/sbin/acpi_oem_exec.sh
 376 script:
 377 .Bd -literal -offset indent
 378 notify 10 {
 379         match "system"          "ACPI";
 380         match "subsystem"       "THINKPAD";
 381         action "/usr/local/sbin/acpi_oem_exec.sh $notify thinkpad";
 382 };
 383 .Ed
 384 .Pp
 385 A possible
 386 .Pa /usr/local/sbin/acpi_oem_exec.sh
 387 script might look like:
 388 .Bd -literal -offset indent
 389 #!/bin/sh
 390 #
 391 if [ "$1" = "" -o "$2" = "" ]
 392 then
 393         echo "usage: $0 notify oem_name"
 394         exit 1
 395 fi
 396 NOTIFY=`echo $1`
 397 LOGGER="logger"
 398 CALC="bc"
 399 BC_PRECOMMANDS="scale=2"
 400 ECHO="echo"
 401 CUT="cut"
 402 MAX_LCD_BRIGHTNESS=7
 403 MAX_VOLUME=14
 404 OEM=$2
 405 DISPLAY_PIPE=/tmp/acpi_${OEM}_display
 406
 407 case ${NOTIFY} in
 408         0x05)
 409                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
 410                 if [ "$LEVEL" = "1" ]
 411                 then
 412                         sysctl dev.acpi_${OEM}.0.bluetooth=0
 413                         MESSAGE="bluetooth disabled"
 414                 else
 415                         sysctl dev.acpi_${OEM}.0.bluetooth=1
 416                         MESSAGE="bluetooth enabled"
 417                 fi
 418                 ;;
 419         0x10|0x11)
 420                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
 421                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
 422                          ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
 423                          ${CALC} | ${CUT} -d . -f 1`
 424                 MESSAGE="brightness level ${PERCENT}%"
 425                 ;;
 426         0x12)
 427                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
 428                 if [ "$LEVEL" = "1" ]
 429                 then
 430                         MESSAGE="thinklight enabled"
 431                 else
 432                         MESSAGE="thinklight disabled"
 433                 fi
 434                 ;;
 435         0x15|0x16)
 436                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
 437                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
 438                         ${LEVEL} / ${MAX_VOLUME} * 100" | \\
 439                          ${CALC} | ${CUT} -d . -f 1`
 440                 MESSAGE="volume level ${PERCENT}%"
 441                 ;;
 442         0x17)
 443                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
 444                 if [ "$LEVEL" = "1" ]
 445                 then
 446                         MESSAGE="volume muted"
 447                 else
 448                         MESSAGE="volume unmuted"
 449                 fi
 450                 ;;
 451         0x1b)
 452                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.mic_led`
 453                 if [ $LEVEL -eq 0 ]; then
 454                         sysctl dev.acpi_${OEM}.0.mic_led=1
 455                         mixer rec 0
 456                 fi
 457                 if [ $LEVEL -eq 1 ]; then
 458                         sysctl dev.acpi_${OEM}.0.mic_led=0
 459                         mixer rec 30
 460                 fi
 461                 ;;
 462         *)
 463                 ;;
 464 esac
 465 ${LOGGER} ${MESSAGE}
 466 if [ -p ${DISPLAY_PIPE} ]
 467 then
 468         ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
 469 fi
 470 exit 0
 471 .Ed
 472 .Pp
 473 The following example specify that event code 0x04 (Suspend to RAM),
 474 0x10 (Brightness up) and 0x11 (Brightness down) are handled by
 475 .Nm .
 476 .Bd -literal -offset indent
 477 sysctl dev.acpi_thinkpad.0.handlerevents='0x04 0x10 0x11'
 478 .Ed
 479 .Pp
 480 in
 481 .Xr sysctl.conf 5 :
 482 .Bd -literal -offset indent
 483 hw.acpi.thinkpad.handlerevents=0x04\\ 0x10\\ 0x11
 484 .Ed
 485 .Sh SEE ALSO
 486 .Xr acpi 4 ,
 487 .Xr led 4 ,
 488 .Xr sysctl.conf 5 ,
 489 .Xr devd 8 ,
 490 .Xr sensorsd 8 ,
 491 .Xr sysctl 8
 492 .Sh HISTORY
 493 The
 494 .Nm
 495 device driver first appeared in
 496 .Fx 6.0
 497 and was imported into
 498 .Dx 2.1 .
 499 .Sh AUTHORS
 500 .An -nosplit
 501 The
 502 .Nm
 503 driver was written by
 504 .An Takanori Watanabe Aq Mt takawata@FreeBSD.org
 505 and later mostly rewritten by
 506 .An Markus Brueffer Aq Mt markus@FreeBSD.org .
 507 This manual page was written by
 508 .An Christian Brueffer Aq Mt brueffer@FreeBSD.org
 509 and
 510 .An Markus Brueffer Aq Mt markus@FreeBSD.org .