SAFE public projects git trees. - safe/jmp/linux-2.6/blob - Documentation/thinkpad-acpi.txt

   1                      ThinkPad ACPI Extras Driver
   2
   3                             Version 0.14
   4                           March 26th, 2007
   5
   6                Borislav Deianov <borislav@users.sf.net>
   7              Henrique de Moraes Holschuh <hmh@hmh.eng.br>
   8                       http://ibm-acpi.sf.net/
   9
  10
  11 This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
  12 supports various features of these laptops which are accessible
  13 through the ACPI and ACPI EC framework, but not otherwise fully
  14 supported by the generic Linux ACPI drivers.
  15
  16 This driver used to be named ibm-acpi until kernel 2.6.21 and release
  17 0.13-20070314.  It used to be in the drivers/acpi tree, but it was
  18 moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel
  19 2.6.22, and release 0.14.
  20
  21
  22 Status
  23 ------
  24
  25 The features currently supported are the following (see below for
  26 detailed description):
  27
  28         - Fn key combinations
  29         - Bluetooth enable and disable
  30         - video output switching, expansion control
  31         - ThinkLight on and off
  32         - limited docking and undocking
  33         - UltraBay eject
  34         - CMOS control
  35         - LED control
  36         - ACPI sounds
  37         - temperature sensors
  38         - Experimental: embedded controller register dump
  39         - LCD brightness control
  40         - Volume control
  41         - Experimental: fan speed, fan enable/disable
  42         - Experimental: WAN enable and disable
  43
  44 A compatibility table by model and feature is maintained on the web
  45 site, http://ibm-acpi.sf.net/. I appreciate any success or failure
  46 reports, especially if they add to or correct the compatibility table.
  47 Please include the following information in your report:
  48
  49         - ThinkPad model name
  50         - a copy of your DSDT, from /proc/acpi/dsdt
  51         - a copy of the output of dmidecode, with serial numbers
  52           and UUIDs masked off
  53         - which driver features work and which don't
  54         - the observed behavior of non-working features
  55
  56 Any other comments or patches are also more than welcome.
  57
  58
  59 Installation
  60 ------------
  61
  62 If you are compiling this driver as included in the Linux kernel
  63 sources, simply enable the CONFIG_THINKPAD_ACPI option, and optionally
  64 enable the CONFIG_THINKPAD_ACPI_BAY option if you want the
  65 thinkpad-specific bay functionality.
  66
  67 Features
  68 --------
  69
  70 The driver creates the /proc/acpi/ibm directory. There is a file under
  71 that directory for each feature described below. Note that while the
  72 driver is still in the alpha stage, the exact proc file format and
  73 commands supported by the various features is guaranteed to change
  74 frequently.
  75
  76 Driver version -- /proc/acpi/ibm/driver
  77 ---------------------------------------
  78
  79 The driver name and version. No commands can be written to this file.
  80
  81 Hot keys -- /proc/acpi/ibm/hotkey
  82 ---------------------------------
  83
  84 Without this driver, only the Fn-F4 key (sleep button) generates an
  85 ACPI event. With the driver loaded, the hotkey feature enabled and the
  86 mask set (see below), the various hot keys generate ACPI events in the
  87 following format:
  88
  89         ibm/hotkey HKEY 00000080 0000xxxx
  90
  91 The last four digits vary depending on the key combination pressed.
  92 All labeled Fn-Fx key combinations generate distinct events. In
  93 addition, the lid microswitch and some docking station buttons may
  94 also generate such events.
  95
  96 The following commands can be written to this file:
  97
  98         echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature
  99         echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature
 100         echo 0xffff > /proc/acpi/ibm/hotkey -- enable all possible hot keys
 101         echo 0x0000 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
 102         ... any other 4-hex-digit mask ...
 103         echo reset > /proc/acpi/ibm/hotkey -- restore the original mask
 104
 105 The bit mask allows some control over which hot keys generate ACPI
 106 events. Not all bits in the mask can be modified. Not all bits that
 107 can be modified do anything. Not all hot keys can be individually
 108 controlled by the mask. Most recent ThinkPad models honor the
 109 following bits (assuming the hot keys feature has been enabled):
 110
 111         key     bit     behavior when set       behavior when unset
 112
 113         Fn-F3                   always generates ACPI event
 114         Fn-F4                   always generates ACPI event
 115         Fn-F5   0010    generate ACPI event     enable/disable Bluetooth
 116         Fn-F7   0040    generate ACPI event     switch LCD and external display
 117         Fn-F8   0080    generate ACPI event     expand screen or none
 118         Fn-F9   0100    generate ACPI event     none
 119         Fn-F12                  always generates ACPI event
 120
 121 Some models do not support all of the above. For example, the T30 does
 122 not support Fn-F5 and Fn-F9. Other models do not support the mask at
 123 all. On those models, hot keys cannot be controlled individually.
 124
 125 Note that enabling ACPI events for some keys prevents their default
 126 behavior. For example, if events for Fn-F5 are enabled, that key will
 127 no longer enable/disable Bluetooth by itself. This can still be done
 128 from an acpid handler for the ibm/hotkey event.
 129
 130 Note also that not all Fn key combinations are supported through
 131 ACPI. For example, on the X40, the brightness, volume and "Access IBM"
 132 buttons do not generate ACPI events even with this driver. They *can*
 133 be used through the "ThinkPad Buttons" utility, see
 134 http://www.nongnu.org/tpb/
 135
 136 Bluetooth -- /proc/acpi/ibm/bluetooth
 137 -------------------------------------
 138
 139 This feature shows the presence and current state of a Bluetooth
 140 device. If Bluetooth is installed, the following commands can be used:
 141
 142         echo enable > /proc/acpi/ibm/bluetooth
 143         echo disable > /proc/acpi/ibm/bluetooth
 144
 145 Video output control -- /proc/acpi/ibm/video
 146 --------------------------------------------
 147
 148 This feature allows control over the devices used for video output -
 149 LCD, CRT or DVI (if available). The following commands are available:
 150
 151         echo lcd_enable > /proc/acpi/ibm/video
 152         echo lcd_disable > /proc/acpi/ibm/video
 153         echo crt_enable > /proc/acpi/ibm/video
 154         echo crt_disable > /proc/acpi/ibm/video
 155         echo dvi_enable > /proc/acpi/ibm/video
 156         echo dvi_disable > /proc/acpi/ibm/video
 157         echo auto_enable > /proc/acpi/ibm/video
 158         echo auto_disable > /proc/acpi/ibm/video
 159         echo expand_toggle > /proc/acpi/ibm/video
 160         echo video_switch > /proc/acpi/ibm/video
 161
 162 Each video output device can be enabled or disabled individually.
 163 Reading /proc/acpi/ibm/video shows the status of each device.
 164
 165 Automatic video switching can be enabled or disabled.  When automatic
 166 video switching is enabled, certain events (e.g. opening the lid,
 167 docking or undocking) cause the video output device to change
 168 automatically. While this can be useful, it also causes flickering
 169 and, on the X40, video corruption. By disabling automatic switching,
 170 the flickering or video corruption can be avoided.
 171
 172 The video_switch command cycles through the available video outputs
 173 (it simulates the behavior of Fn-F7).
 174
 175 Video expansion can be toggled through this feature. This controls
 176 whether the display is expanded to fill the entire LCD screen when a
 177 mode with less than full resolution is used. Note that the current
 178 video expansion status cannot be determined through this feature.
 179
 180 Note that on many models (particularly those using Radeon graphics
 181 chips) the X driver configures the video card in a way which prevents
 182 Fn-F7 from working. This also disables the video output switching
 183 features of this driver, as it uses the same ACPI methods as
 184 Fn-F7. Video switching on the console should still work.
 185
 186 UPDATE: There's now a patch for the X.org Radeon driver which
 187 addresses this issue. Some people are reporting success with the patch
 188 while others are still having problems. For more information:
 189
 190 https://bugs.freedesktop.org/show_bug.cgi?id=2000
 191
 192 ThinkLight control -- /proc/acpi/ibm/light
 193 ------------------------------------------
 194
 195 The current status of the ThinkLight can be found in this file. A few
 196 models which do not make the status available will show it as
 197 "unknown". The available commands are:
 198
 199         echo on  > /proc/acpi/ibm/light
 200         echo off > /proc/acpi/ibm/light
 201
 202 Docking / undocking -- /proc/acpi/ibm/dock
 203 ------------------------------------------
 204
 205 Docking and undocking (e.g. with the X4 UltraBase) requires some
 206 actions to be taken by the operating system to safely make or break
 207 the electrical connections with the dock.
 208
 209 The docking feature of this driver generates the following ACPI events:
 210
 211         ibm/dock GDCK 00000003 00000001 -- eject request
 212         ibm/dock GDCK 00000003 00000002 -- undocked
 213         ibm/dock GDCK 00000000 00000003 -- docked
 214
 215 NOTE: These events will only be generated if the laptop was docked
 216 when originally booted. This is due to the current lack of support for
 217 hot plugging of devices in the Linux ACPI framework. If the laptop was
 218 booted while not in the dock, the following message is shown in the
 219 logs:
 220
 221         Mar 17 01:42:34 aero kernel: thinkpad_acpi: dock device not present
 222
 223 In this case, no dock-related events are generated but the dock and
 224 undock commands described below still work. They can be executed
 225 manually or triggered by Fn key combinations (see the example acpid
 226 configuration files included in the driver tarball package available
 227 on the web site).
 228
 229 When the eject request button on the dock is pressed, the first event
 230 above is generated. The handler for this event should issue the
 231 following command:
 232
 233         echo undock > /proc/acpi/ibm/dock
 234
 235 After the LED on the dock goes off, it is safe to eject the laptop.
 236 Note: if you pressed this key by mistake, go ahead and eject the
 237 laptop, then dock it back in. Otherwise, the dock may not function as
 238 expected.
 239
 240 When the laptop is docked, the third event above is generated. The
 241 handler for this event should issue the following command to fully
 242 enable the dock:
 243
 244         echo dock > /proc/acpi/ibm/dock
 245
 246 The contents of the /proc/acpi/ibm/dock file shows the current status
 247 of the dock, as provided by the ACPI framework.
 248
 249 The docking support in this driver does not take care of enabling or
 250 disabling any other devices you may have attached to the dock. For
 251 example, a CD drive plugged into the UltraBase needs to be disabled or
 252 enabled separately. See the provided example acpid configuration files
 253 for how this can be accomplished.
 254
 255 There is no support yet for PCI devices that may be attached to a
 256 docking station, e.g. in the ThinkPad Dock II. The driver currently
 257 does not recognize, enable or disable such devices. This means that
 258 the only docking stations currently supported are the X-series
 259 UltraBase docks and "dumb" port replicators like the Mini Dock (the
 260 latter don't need any ACPI support, actually).
 261
 262 UltraBay eject -- /proc/acpi/ibm/bay
 263 ------------------------------------
 264
 265 Inserting or ejecting an UltraBay device requires some actions to be
 266 taken by the operating system to safely make or break the electrical
 267 connections with the device.
 268
 269 This feature generates the following ACPI events:
 270
 271         ibm/bay MSTR 00000003 00000000 -- eject request
 272         ibm/bay MSTR 00000001 00000000 -- eject lever inserted
 273
 274 NOTE: These events will only be generated if the UltraBay was present
 275 when the laptop was originally booted (on the X series, the UltraBay
 276 is in the dock, so it may not be present if the laptop was undocked).
 277 This is due to the current lack of support for hot plugging of devices
 278 in the Linux ACPI framework. If the laptop was booted without the
 279 UltraBay, the following message is shown in the logs:
 280
 281         Mar 17 01:42:34 aero kernel: thinkpad_acpi: bay device not present
 282
 283 In this case, no bay-related events are generated but the eject
 284 command described below still works. It can be executed manually or
 285 triggered by a hot key combination.
 286
 287 Sliding the eject lever generates the first event shown above. The
 288 handler for this event should take whatever actions are necessary to
 289 shut down the device in the UltraBay (e.g. call idectl), then issue
 290 the following command:
 291
 292         echo eject > /proc/acpi/ibm/bay
 293
 294 After the LED on the UltraBay goes off, it is safe to pull out the
 295 device.
 296
 297 When the eject lever is inserted, the second event above is
 298 generated. The handler for this event should take whatever actions are
 299 necessary to enable the UltraBay device (e.g. call idectl).
 300
 301 The contents of the /proc/acpi/ibm/bay file shows the current status
 302 of the UltraBay, as provided by the ACPI framework.
 303
 304 EXPERIMENTAL warm eject support on the 600e/x, A22p and A3x (To use
 305 this feature, you need to supply the experimental=1 parameter when
 306 loading the module):
 307
 308 These models do not have a button near the UltraBay device to request
 309 a hot eject but rather require the laptop to be put to sleep
 310 (suspend-to-ram) before the bay device is ejected or inserted).
 311 The sequence of steps to eject the device is as follows:
 312
 313         echo eject > /proc/acpi/ibm/bay
 314         put the ThinkPad to sleep
 315         remove the drive
 316         resume from sleep
 317         cat /proc/acpi/ibm/bay should show that the drive was removed
 318
 319 On the A3x, both the UltraBay 2000 and UltraBay Plus devices are
 320 supported. Use "eject2" instead of "eject" for the second bay.
 321
 322 Note: the UltraBay eject support on the 600e/x, A22p and A3x is
 323 EXPERIMENTAL and may not work as expected. USE WITH CAUTION!
 324
 325 CMOS control -- /proc/acpi/ibm/cmos
 326 -----------------------------------
 327
 328 This feature is used internally by the ACPI firmware to control the
 329 ThinkLight on most newer ThinkPad models. It may also control LCD
 330 brightness, sounds volume and more, but only on some models.
 331
 332 The commands are non-negative integer numbers:
 333
 334         echo 0 >/proc/acpi/ibm/cmos
 335         echo 1 >/proc/acpi/ibm/cmos
 336         echo 2 >/proc/acpi/ibm/cmos
 337         ...
 338
 339 The range of valid numbers is 0 to 21, but not all have an effect and
 340 the behavior varies from model to model. Here is the behavior on the
 341 X40 (tpb is the ThinkPad Buttons utility):
 342
 343         0 - no effect but tpb reports "Volume down"
 344         1 - no effect but tpb reports "Volume up"
 345         2 - no effect but tpb reports "Mute on"
 346         3 - simulate pressing the "Access IBM" button
 347         4 - LCD brightness up
 348         5 - LCD brightness down
 349         11 - toggle screen expansion
 350         12 - ThinkLight on
 351         13 - ThinkLight off
 352         14 - no effect but tpb reports ThinkLight status change
 353
 354 LED control -- /proc/acpi/ibm/led
 355 ---------------------------------
 356
 357 Some of the LED indicators can be controlled through this feature. The
 358 available commands are:
 359
 360         echo '<led number> on' >/proc/acpi/ibm/led
 361         echo '<led number> off' >/proc/acpi/ibm/led
 362         echo '<led number> blink' >/proc/acpi/ibm/led
 363
 364 The <led number> range is 0 to 7. The set of LEDs that can be
 365 controlled varies from model to model. Here is the mapping on the X40:
 366
 367         0 - power
 368         1 - battery (orange)
 369         2 - battery (green)
 370         3 - UltraBase
 371         4 - UltraBay
 372         7 - standby
 373
 374 All of the above can be turned on and off and can be made to blink.
 375
 376 ACPI sounds -- /proc/acpi/ibm/beep
 377 ----------------------------------
 378
 379 The BEEP method is used internally by the ACPI firmware to provide
 380 audible alerts in various situations. This feature allows the same
 381 sounds to be triggered manually.
 382
 383 The commands are non-negative integer numbers:
 384
 385         echo <number> >/proc/acpi/ibm/beep
 386
 387 The valid <number> range is 0 to 17. Not all numbers trigger sounds
 388 and the sounds vary from model to model. Here is the behavior on the
 389 X40:
 390
 391         0 - stop a sound in progress (but use 17 to stop 16)
 392         2 - two beeps, pause, third beep ("low battery")
 393         3 - single beep
 394         4 - high, followed by low-pitched beep ("unable")
 395         5 - single beep
 396         6 - very high, followed by high-pitched beep ("AC/DC")
 397         7 - high-pitched beep
 398         9 - three short beeps
 399         10 - very long beep
 400         12 - low-pitched beep
 401         15 - three high-pitched beeps repeating constantly, stop with 0
 402         16 - one medium-pitched beep repeating constantly, stop with 17
 403         17 - stop 16
 404
 405 Temperature sensors -- /proc/acpi/ibm/thermal
 406 ---------------------------------------------
 407
 408 Most ThinkPads include six or more separate temperature sensors but
 409 only expose the CPU temperature through the standard ACPI methods.
 410 This feature shows readings from up to eight different sensors on older
 411 ThinkPads, and it has experimental support for up to sixteen different
 412 sensors on newer ThinkPads.  Readings from sensors that are not available
 413 return -128.
 414
 415 No commands can be written to this file.
 416
 417 EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the
 418 implementation directly accesses hardware registers and may not work as
 419 expected. USE WITH CAUTION! To use this feature, you need to supply the
 420 experimental=1 parameter when loading the module.  When EXPERIMENTAL
 421 mode is enabled, reading the first 8 sensors on newer ThinkPads will
 422 also use an new experimental thermal sensor access mode.
 423
 424 For example, on the X40, a typical output may be:
 425 temperatures:   42 42 45 41 36 -128 33 -128
 426
 427 EXPERIMENTAL: On the T43/p, a typical output may be:
 428 temperatures:   48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
 429
 430 The mapping of thermal sensors to physical locations varies depending on
 431 system-board model (and thus, on ThinkPad model).
 432
 433 http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
 434 tries to track down these locations for various models.
 435
 436 Most (newer?) models seem to follow this pattern:
 437
 438 1:  CPU
 439 2:  (depends on model)
 440 3:  (depends on model)
 441 4:  GPU
 442 5:  Main battery: main sensor
 443 6:  Bay battery: main sensor
 444 7:  Main battery: secondary sensor
 445 8:  Bay battery: secondary sensor
 446 9-15: (depends on model)
 447
 448 For the R51 (source: Thomas Gruber):
 449 2:  Mini-PCI
 450 3:  Internal HDD
 451
 452 For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
 453 http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
 454 2:  System board, left side (near PCMCIA slot), reported as HDAPS temp
 455 3:  PCMCIA slot
 456 9:  MCH (northbridge) to DRAM Bus
 457 10: ICH (southbridge), under Mini-PCI card, under touchpad
 458 11: Power regulator, underside of system board, below F2 key
 459
 460 The A31 has a very atypical layout for the thermal sensors
 461 (source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
 462 1:  CPU
 463 2:  Main Battery: main sensor
 464 3:  Power Converter
 465 4:  Bay Battery: main sensor
 466 5:  MCH (northbridge)
 467 6:  PCMCIA/ambient
 468 7:  Main Battery: secondary sensor
 469 8:  Bay Battery: secondary sensor
 470
 471
 472 EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump
 473 ------------------------------------------------------------------------
 474
 475 This feature is marked EXPERIMENTAL because the implementation
 476 directly accesses hardware registers and may not work as expected. USE
 477 WITH CAUTION! To use this feature, you need to supply the
 478 experimental=1 parameter when loading the module.
 479
 480 This feature dumps the values of 256 embedded controller
 481 registers. Values which have changed since the last time the registers
 482 were dumped are marked with a star:
 483
 484 [root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
 485 EC       +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
 486 EC 0x00:  a7  47  87  01  fe  96  00  08  01  00  cb  00  00  00  40  00
 487 EC 0x10:  00  00  ff  ff  f4  3c  87  09  01  ff  42  01  ff  ff  0d  00
 488 EC 0x20:  00  00  00  00  00  00  00  00  00  00  00  03  43  00  00  80
 489 EC 0x30:  01  07  1a  00  30  04  00  00 *85  00  00  10  00  50  00  00
 490 EC 0x40:  00  00  00  00  00  00  14  01  00  04  00  00  00  00  00  00
 491 EC 0x50:  00  c0  02  0d  00  01  01  02  02  03  03  03  03 *bc *02 *bc
 492 EC 0x60: *02 *bc *02  00  00  00  00  00  00  00  00  00  00  00  00  00
 493 EC 0x70:  00  00  00  00  00  12  30  40 *24 *26 *2c *27 *20  80 *1f  80
 494 EC 0x80:  00  00  00  06 *37 *0e  03  00  00  00  0e  07  00  00  00  00
 495 EC 0x90:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00
 496 EC 0xa0: *ff  09  ff  09  ff  ff *64  00 *00 *00 *a2  41 *ff *ff *e0  00
 497 EC 0xb0:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00
 498 EC 0xc0:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00
 499 EC 0xd0:  03  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00
 500 EC 0xe0:  00  00  00  00  00  00  00  00  11  20  49  04  24  06  55  03
 501 EC 0xf0:  31  55  48  54  35  38  57  57  08  2f  45  73  07  65  6c  1a
 502
 503 This feature can be used to determine the register holding the fan
 504 speed on some models. To do that, do the following:
 505
 506         - make sure the battery is fully charged
 507         - make sure the fan is running
 508         - run 'cat /proc/acpi/ibm/ecdump' several times, once per second or so
 509
 510 The first step makes sure various charging-related values don't
 511 vary. The second ensures that the fan-related values do vary, since
 512 the fan speed fluctuates a bit. The third will (hopefully) mark the
 513 fan register with a star:
 514
 515 [root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
 516 EC       +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
 517 EC 0x00:  a7  47  87  01  fe  96  00  08  01  00  cb  00  00  00  40  00
 518 EC 0x10:  00  00  ff  ff  f4  3c  87  09  01  ff  42  01  ff  ff  0d  00
 519 EC 0x20:  00  00  00  00  00  00  00  00  00  00  00  03  43  00  00  80
 520 EC 0x30:  01  07  1a  00  30  04  00  00  85  00  00  10  00  50  00  00
 521 EC 0x40:  00  00  00  00  00  00  14  01  00  04  00  00  00  00  00  00
 522 EC 0x50:  00  c0  02  0d  00  01  01  02  02  03  03  03  03  bc  02  bc
 523 EC 0x60:  02  bc  02  00  00  00  00  00  00  00  00  00  00  00  00  00
 524 EC 0x70:  00  00  00  00  00  12  30  40  24  27  2c  27  21  80  1f  80
 525 EC 0x80:  00  00  00  06 *be  0d  03  00  00  00  0e  07  00  00  00  00
 526 EC 0x90:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00
 527 EC 0xa0:  ff  09  ff  09  ff  ff  64  00  00  00  a2  41  ff  ff  e0  00
 528 EC 0xb0:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00
 529 EC 0xc0:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00
 530 EC 0xd0:  03  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00
 531 EC 0xe0:  00  00  00  00  00  00  00  00  11  20  49  04  24  06  55  03
 532 EC 0xf0:  31  55  48  54  35  38  57  57  08  2f  45  73  07  65  6c  1a
 533
 534 Another set of values that varies often is the temperature
 535 readings. Since temperatures don't change vary fast, you can take
 536 several quick dumps to eliminate them.
 537
 538 You can use a similar method to figure out the meaning of other
 539 embedded controller registers - e.g. make sure nothing else changes
 540 except the charging or discharging battery to determine which
 541 registers contain the current battery capacity, etc. If you experiment
 542 with this, do send me your results (including some complete dumps with
 543 a description of the conditions when they were taken.)
 544
 545 LCD brightness control -- /proc/acpi/ibm/brightness
 546 ---------------------------------------------------
 547
 548 This feature allows software control of the LCD brightness on ThinkPad
 549 models which don't have a hardware brightness slider. The available
 550 commands are:
 551
 552         echo up   >/proc/acpi/ibm/brightness
 553         echo down >/proc/acpi/ibm/brightness
 554         echo 'level <level>' >/proc/acpi/ibm/brightness
 555
 556 The <level> number range is 0 to 7, although not all of them may be
 557 distinct. The current brightness level is shown in the file.
 558
 559 Volume control -- /proc/acpi/ibm/volume
 560 ---------------------------------------
 561
 562 This feature allows volume control on ThinkPad models which don't have
 563 a hardware volume knob. The available commands are:
 564
 565         echo up   >/proc/acpi/ibm/volume
 566         echo down >/proc/acpi/ibm/volume
 567         echo mute >/proc/acpi/ibm/volume
 568         echo 'level <level>' >/proc/acpi/ibm/volume
 569
 570 The <level> number range is 0 to 15 although not all of them may be
 571 distinct. The unmute the volume after the mute command, use either the
 572 up or down command (the level command will not unmute the volume).
 573 The current volume level and mute state is shown in the file.
 574
 575 EXPERIMENTAL: fan speed, fan enable/disable -- /proc/acpi/ibm/fan
 576 -----------------------------------------------------------------
 577
 578 This feature is marked EXPERIMENTAL because the implementation
 579 directly accesses hardware registers and may not work as expected. USE
 580 WITH CAUTION! To use this feature, you need to supply the
 581 experimental=1 parameter when loading the module.
 582
 583 This feature attempts to show the current fan speed, control mode and
 584 other fan data that might be available.  The speed is read directly
 585 from the hardware registers of the embedded controller.  This is known
 586 to work on later R, T and X series ThinkPads but may show a bogus
 587 value on other models.
 588
 589 Most ThinkPad fans work in "levels".  Level 0 stops the fan.  The higher
 590 the level, the higher the fan speed, although adjacent levels often map
 591 to the same fan speed.  7 is the highest level, where the fan reaches
 592 the maximum recommended speed.  Level "auto" means the EC changes the
 593 fan level according to some internal algorithm, usually based on
 594 readings from the thermal sensors.  Level "disengaged" means the EC
 595 disables the speed-locked closed-loop fan control, and drives the fan as
 596 fast as it can go, which might exceed hardware limits, so use this level
 597 with caution.
 598
 599 The fan usually ramps up or down slowly from one speed to another,
 600 and it is normal for the EC to take several seconds to react to fan
 601 commands.
 602
 603 The fan may be enabled or disabled with the following commands:
 604
 605         echo enable  >/proc/acpi/ibm/fan
 606         echo disable >/proc/acpi/ibm/fan
 607
 608 Placing a fan on level 0 is the same as disabling it.  Enabling a fan
 609 will try to place it in a safe level if it is too slow or disabled.
 610
 611 WARNING WARNING WARNING: do not leave the fan disabled unless you are
 612 monitoring all of the temperature sensor readings and you are ready to
 613 enable it if necessary to avoid overheating.
 614
 615 An enabled fan in level "auto" may stop spinning if the EC decides the
 616 ThinkPad is cool enough and doesn't need the extra airflow.  This is
 617 normal, and the EC will spin the fan up if the varios thermal readings
 618 rise too much.
 619
 620 On the X40, this seems to depend on the CPU and HDD temperatures.
 621 Specifically, the fan is turned on when either the CPU temperature
 622 climbs to 56 degrees or the HDD temperature climbs to 46 degrees.  The
 623 fan is turned off when the CPU temperature drops to 49 degrees and the
 624 HDD temperature drops to 41 degrees.  These thresholds cannot
 625 currently be controlled.
 626
 627 The fan level can be controlled with the command:
 628
 629         echo 'level <level>' > /proc/acpi/ibm/thermal
 630
 631 Where <level> is an integer from 0 to 7, or one of the words "auto"
 632 or "disengaged" (without the quotes).  Not all ThinkPads support the
 633 "auto" and "disengaged" levels.
 634
 635 On the X31 and X40 (and ONLY on those models), the fan speed can be
 636 controlled to a certain degree. Once the fan is running, it can be
 637 forced to run faster or slower with the following command:
 638
 639         echo 'speed <speed>' > /proc/acpi/ibm/thermal
 640
 641 The sustainable range of fan speeds on the X40 appears to be from
 642 about 3700 to about 7350. Values outside this range either do not have
 643 any effect or the fan speed eventually settles somewhere in that
 644 range. The fan cannot be stopped or started with this command.
 645
 646 The ThinkPad's ACPI DSDT code will reprogram the fan on its own when
 647 certain conditions are met.  It will override any fan programming done
 648 through thinkpad-acpi.
 649
 650 The thinkpad-acpi kernel driver can be programmed to revert the fan
 651 level to a safe setting if userspace does not issue one of the fan
 652 commands: "enable", "disable", "level" or "watchdog" within a
 653 configurable ammount of time.  To do this, use the "watchdog" command.
 654
 655         echo 'watchdog <interval>' > /proc/acpi/ibm/fan
 656
 657 Interval is the ammount of time in seconds to wait for one of the
 658 above mentioned fan commands before reseting the fan level to a safe
 659 one.  If set to zero, the watchdog is disabled (default).  When the
 660 watchdog timer runs out, it does the exact equivalent of the "enable"
 661 fan command.
 662
 663 Note that the watchdog timer stops after it enables the fan.  It will
 664 be rearmed again automatically (using the same interval) when one of
 665 the above mentioned fan commands is received.  The fan watchdog is,
 666 therefore, not suitable to protect against fan mode changes made
 667 through means other than the "enable", "disable", and "level" fan
 668 commands.
 669
 670 EXPERIMENTAL: WAN -- /proc/acpi/ibm/wan
 671 ---------------------------------------
 672
 673 This feature is marked EXPERIMENTAL because the implementation
 674 directly accesses hardware registers and may not work as expected. USE
 675 WITH CAUTION! To use this feature, you need to supply the
 676 experimental=1 parameter when loading the module.
 677
 678 This feature shows the presence and current state of a WAN (Sierra
 679 Wireless EV-DO) device. If WAN is installed, the following commands can
 680 be used:
 681
 682         echo enable > /proc/acpi/ibm/wan
 683         echo disable > /proc/acpi/ibm/wan
 684
 685 It was tested on a Lenovo Thinkpad X60. It should probably work on other
 686 Thinkpad models which come with this module installed.
 687
 688 Multiple Commands, Module Parameters
 689 ------------------------------------
 690
 691 Multiple commands can be written to the proc files in one shot by
 692 separating them with commas, for example:
 693
 694         echo enable,0xffff > /proc/acpi/ibm/hotkey
 695         echo lcd_disable,crt_enable > /proc/acpi/ibm/video
 696
 697 Commands can also be specified when loading the thinkpad-acpi module,
 698 for example:
 699
 700         modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
 701
 702 Enabling debugging output
 703 -------------------------
 704
 705 The module takes a debug paramater which can be used to selectively
 706 enable various classes of debugging output, for example:
 707
 708          modprobe ibm_acpi debug=0xffff
 709
 710 will enable all debugging output classes.  It takes a bitmask, so
 711 to enable more than one output class, just add their values.
 712
 713         Debug bitmask           Description
 714         0x0001                  Initialization and probing
 715         0x0002                  Removal
 716
 717 There is also a kernel build option to enable more debugging
 718 information, which may be necessary to debug driver problems.