1 ThinkPad ACPI Extras Driver 2 3 Version 0.14 4 April 21st, 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 11This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It 12supports various features of these laptops which are accessible 13through the ACPI and ACPI EC framework, but not otherwise fully 14supported by the generic Linux ACPI drivers. 15 16This driver used to be named ibm-acpi until kernel 2.6.21 and release 170.13-20070314. It used to be in the drivers/acpi tree, but it was 18moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel 192.6.22, and release 0.14. 20 21 22Status 23------ 24 25The features currently supported are the following (see below for 26detailed 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 - Fan control and monitoring: fan speed, fan enable/disable 42 - Experimental: WAN enable and disable 43 44A compatibility table by model and feature is maintained on the web 45site, http://ibm-acpi.sf.net/. I appreciate any success or failure 46reports, especially if they add to or correct the compatibility table. 47Please 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 56Any other comments or patches are also more than welcome. 57 58 59Installation 60------------ 61 62If you are compiling this driver as included in the Linux kernel 63sources, simply enable the CONFIG_THINKPAD_ACPI option, and optionally 64enable the CONFIG_THINKPAD_ACPI_BAY option if you want the 65thinkpad-specific bay functionality. 66 67Features 68-------- 69 70The driver exports two different interfaces to userspace, which can be 71used to access the features it provides. One is a legacy procfs-based 72interface, which will be removed at some time in the distant future. 73The other is a new sysfs-based interface which is not complete yet. 74 75The procfs interface creates the /proc/acpi/ibm directory. There is a 76file under that directory for each feature it supports. The procfs 77interface is mostly frozen, and will change very little if at all: it 78will not be extended to add any new functionality in the driver, instead 79all new functionality will be implemented on the sysfs interface. 80 81The sysfs interface tries to blend in the generic Linux sysfs subsystems 82and classes as much as possible. Since some of these subsystems are not 83yet ready or stabilized, it is expected that this interface will change, 84and any and all userspace programs must deal with it. 85 86 87Notes about the sysfs interface: 88 89Unlike what was done with the procfs interface, correctness when talking 90to the sysfs interfaces will be enforced, as will correctness in the 91thinkpad-acpi's implementation of sysfs interfaces. 92 93Also, any bugs in the thinkpad-acpi sysfs driver code or in the 94thinkpad-acpi's implementation of the sysfs interfaces will be fixed for 95maximum correctness, even if that means changing an interface in 96non-compatible ways. As these interfaces mature both in the kernel and 97in thinkpad-acpi, such changes should become quite rare. 98 99Applications interfacing to the thinkpad-acpi sysfs interfaces must 100follow all sysfs guidelines and correctly process all errors (the sysfs 101interface makes extensive use of errors). File descriptors and open / 102close operations to the sysfs inodes must also be properly implemented. 103 104The version of thinkpad-acpi's sysfs interface is exported by the driver 105as a driver attribute (see below). 106 107Sysfs driver attributes are on the driver's sysfs attribute space, 108for 2.6.20 this is /sys/bus/platform/drivers/thinkpad-acpi/. 109 110Sysfs device attributes are on the driver's sysfs attribute space, 111for 2.6.20 this is /sys/devices/platform/thinkpad-acpi/. 112 113Driver version 114-------------- 115 116procfs: /proc/acpi/ibm/driver 117sysfs driver attribute: version 118 119The driver name and version. No commands can be written to this file. 120 121Sysfs interface version 122----------------------- 123 124sysfs driver attribute: interface_version 125 126Version of the thinkpad-acpi sysfs interface, as an unsigned long 127(output in hex format: 0xAAAABBCC), where: 128 AAAA - major revision 129 BB - minor revision 130 CC - bugfix revision 131 132The sysfs interface version changelog for the driver can be found at the 133end of this document. Changes to the sysfs interface done by the kernel 134subsystems are not documented here, nor are they tracked by this 135attribute. 136 137Hot keys 138-------- 139 140procfs: /proc/acpi/ibm/hotkey 141sysfs device attribute: hotkey_* 142 143Without this driver, only the Fn-F4 key (sleep button) generates an 144ACPI event. With the driver loaded, the hotkey feature enabled and the 145mask set (see below), the various hot keys generate ACPI events in the 146following format: 147 148 ibm/hotkey HKEY 00000080 0000xxxx 149 150The last four digits vary depending on the key combination pressed. 151All labeled Fn-Fx key combinations generate distinct events. In 152addition, the lid microswitch and some docking station buttons may 153also generate such events. 154 155The bit mask allows some control over which hot keys generate ACPI 156events. Not all bits in the mask can be modified. Not all bits that 157can be modified do anything. Not all hot keys can be individually 158controlled by the mask. Most recent ThinkPad models honor the 159following bits (assuming the hot keys feature has been enabled): 160 161 key bit behavior when set behavior when unset 162 163 Fn-F3 always generates ACPI event 164 Fn-F4 always generates ACPI event 165 Fn-F5 0010 generate ACPI event enable/disable Bluetooth 166 Fn-F7 0040 generate ACPI event switch LCD and external display 167 Fn-F8 0080 generate ACPI event expand screen or none 168 Fn-F9 0100 generate ACPI event none 169 Fn-F12 always generates ACPI event 170 171Some models do not support all of the above. For example, the T30 does 172not support Fn-F5 and Fn-F9. Other models do not support the mask at 173all. On those models, hot keys cannot be controlled individually. 174 175Note that enabling ACPI events for some keys prevents their default 176behavior. For example, if events for Fn-F5 are enabled, that key will 177no longer enable/disable Bluetooth by itself. This can still be done 178from an acpid handler for the ibm/hotkey event. 179 180Note also that not all Fn key combinations are supported through 181ACPI. For example, on the X40, the brightness, volume and "Access IBM" 182buttons do not generate ACPI events even with this driver. They *can* 183be used through the "ThinkPad Buttons" utility, see 184http://www.nongnu.org/tpb/ 185 186procfs notes: 187 188The following commands can be written to the /proc/acpi/ibm/hotkey file: 189 190 echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature 191 echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature 192 echo 0xffff > /proc/acpi/ibm/hotkey -- enable all possible hot keys 193 echo 0x0000 > /proc/acpi/ibm/hotkey -- disable all possible hot keys 194 ... any other 4-hex-digit mask ... 195 echo reset > /proc/acpi/ibm/hotkey -- restore the original mask 196 197sysfs notes: 198 199 hotkey_bios_enabled: 200 Returns the status of the hot keys feature when 201 thinkpad-acpi was loaded. Upon module unload, the hot 202 key feature status will be restored to this value. 203 204 0: hot keys were disabled 205 1: hot keys were enabled 206 207 hotkey_bios_mask: 208 Returns the hot keys mask when thinkpad-acpi was loaded. 209 Upon module unload, the hot keys mask will be restored 210 to this value. 211 212 hotkey_enable: 213 Enables/disables the hot keys feature, and reports 214 current status of the hot keys feature. 215 216 0: disables the hot keys feature / feature disabled 217 1: enables the hot keys feature / feature enabled 218 219 hotkey_mask: 220 bit mask to enable ACPI event generation for each hot 221 key (see above). Returns the current status of the hot 222 keys mask, and allows one to modify it. 223 224 225Bluetooth 226--------- 227 228procfs: /proc/acpi/ibm/bluetooth 229sysfs device attribute: bluetooth_enable 230 231This feature shows the presence and current state of a ThinkPad 232Bluetooth device in the internal ThinkPad CDC slot. 233 234Procfs notes: 235 236If Bluetooth is installed, the following commands can be used: 237 238 echo enable > /proc/acpi/ibm/bluetooth 239 echo disable > /proc/acpi/ibm/bluetooth 240 241Sysfs notes: 242 243 If the Bluetooth CDC card is installed, it can be enabled / 244 disabled through the "bluetooth_enable" thinkpad-acpi device 245 attribute, and its current status can also be queried. 246 247 enable: 248 0: disables Bluetooth / Bluetooth is disabled 249 1: enables Bluetooth / Bluetooth is enabled. 250 251 Note: this interface will be probably be superseeded by the 252 generic rfkill class, so it is NOT to be considered stable yet. 253 254Video output control -- /proc/acpi/ibm/video 255-------------------------------------------- 256 257This feature allows control over the devices used for video output - 258LCD, CRT or DVI (if available). The following commands are available: 259 260 echo lcd_enable > /proc/acpi/ibm/video 261 echo lcd_disable > /proc/acpi/ibm/video 262 echo crt_enable > /proc/acpi/ibm/video 263 echo crt_disable > /proc/acpi/ibm/video 264 echo dvi_enable > /proc/acpi/ibm/video 265 echo dvi_disable > /proc/acpi/ibm/video 266 echo auto_enable > /proc/acpi/ibm/video 267 echo auto_disable > /proc/acpi/ibm/video 268 echo expand_toggle > /proc/acpi/ibm/video 269 echo video_switch > /proc/acpi/ibm/video 270 271Each video output device can be enabled or disabled individually. 272Reading /proc/acpi/ibm/video shows the status of each device. 273 274Automatic video switching can be enabled or disabled. When automatic 275video switching is enabled, certain events (e.g. opening the lid, 276docking or undocking) cause the video output device to change 277automatically. While this can be useful, it also causes flickering 278and, on the X40, video corruption. By disabling automatic switching, 279the flickering or video corruption can be avoided. 280 281The video_switch command cycles through the available video outputs 282(it simulates the behavior of Fn-F7). 283 284Video expansion can be toggled through this feature. This controls 285whether the display is expanded to fill the entire LCD screen when a 286mode with less than full resolution is used. Note that the current 287video expansion status cannot be determined through this feature. 288 289Note that on many models (particularly those using Radeon graphics 290chips) the X driver configures the video card in a way which prevents 291Fn-F7 from working. This also disables the video output switching 292features of this driver, as it uses the same ACPI methods as 293Fn-F7. Video switching on the console should still work. 294 295UPDATE: There's now a patch for the X.org Radeon driver which 296addresses this issue. Some people are reporting success with the patch 297while others are still having problems. For more information: 298 299https://bugs.freedesktop.org/show_bug.cgi?id=2000 300 301ThinkLight control -- /proc/acpi/ibm/light 302------------------------------------------ 303 304The current status of the ThinkLight can be found in this file. A few 305models which do not make the status available will show it as 306"unknown". The available commands are: 307 308 echo on > /proc/acpi/ibm/light 309 echo off > /proc/acpi/ibm/light 310 311Docking / undocking -- /proc/acpi/ibm/dock 312------------------------------------------ 313 314Docking and undocking (e.g. with the X4 UltraBase) requires some 315actions to be taken by the operating system to safely make or break 316the electrical connections with the dock. 317 318The docking feature of this driver generates the following ACPI events: 319 320 ibm/dock GDCK 00000003 00000001 -- eject request 321 ibm/dock GDCK 00000003 00000002 -- undocked 322 ibm/dock GDCK 00000000 00000003 -- docked 323 324NOTE: These events will only be generated if the laptop was docked 325when originally booted. This is due to the current lack of support for 326hot plugging of devices in the Linux ACPI framework. If the laptop was 327booted while not in the dock, the following message is shown in the 328logs: 329 330 Mar 17 01:42:34 aero kernel: thinkpad_acpi: dock device not present 331 332In this case, no dock-related events are generated but the dock and 333undock commands described below still work. They can be executed 334manually or triggered by Fn key combinations (see the example acpid 335configuration files included in the driver tarball package available 336on the web site). 337 338When the eject request button on the dock is pressed, the first event 339above is generated. The handler for this event should issue the 340following command: 341 342 echo undock > /proc/acpi/ibm/dock 343 344After the LED on the dock goes off, it is safe to eject the laptop. 345Note: if you pressed this key by mistake, go ahead and eject the 346laptop, then dock it back in. Otherwise, the dock may not function as 347expected. 348 349When the laptop is docked, the third event above is generated. The 350handler for this event should issue the following command to fully 351enable the dock: 352 353 echo dock > /proc/acpi/ibm/dock 354 355The contents of the /proc/acpi/ibm/dock file shows the current status 356of the dock, as provided by the ACPI framework. 357 358The docking support in this driver does not take care of enabling or 359disabling any other devices you may have attached to the dock. For 360example, a CD drive plugged into the UltraBase needs to be disabled or 361enabled separately. See the provided example acpid configuration files 362for how this can be accomplished. 363 364There is no support yet for PCI devices that may be attached to a 365docking station, e.g. in the ThinkPad Dock II. The driver currently 366does not recognize, enable or disable such devices. This means that 367the only docking stations currently supported are the X-series 368UltraBase docks and "dumb" port replicators like the Mini Dock (the 369latter don't need any ACPI support, actually). 370 371UltraBay eject -- /proc/acpi/ibm/bay 372------------------------------------ 373 374Inserting or ejecting an UltraBay device requires some actions to be 375taken by the operating system to safely make or break the electrical 376connections with the device. 377 378This feature generates the following ACPI events: 379 380 ibm/bay MSTR 00000003 00000000 -- eject request 381 ibm/bay MSTR 00000001 00000000 -- eject lever inserted 382 383NOTE: These events will only be generated if the UltraBay was present 384when the laptop was originally booted (on the X series, the UltraBay 385is in the dock, so it may not be present if the laptop was undocked). 386This is due to the current lack of support for hot plugging of devices 387in the Linux ACPI framework. If the laptop was booted without the 388UltraBay, the following message is shown in the logs: 389 390 Mar 17 01:42:34 aero kernel: thinkpad_acpi: bay device not present 391 392In this case, no bay-related events are generated but the eject 393command described below still works. It can be executed manually or 394triggered by a hot key combination. 395 396Sliding the eject lever generates the first event shown above. The 397handler for this event should take whatever actions are necessary to 398shut down the device in the UltraBay (e.g. call idectl), then issue 399the following command: 400 401 echo eject > /proc/acpi/ibm/bay 402 403After the LED on the UltraBay goes off, it is safe to pull out the 404device. 405 406When the eject lever is inserted, the second event above is 407generated. The handler for this event should take whatever actions are 408necessary to enable the UltraBay device (e.g. call idectl). 409 410The contents of the /proc/acpi/ibm/bay file shows the current status 411of the UltraBay, as provided by the ACPI framework. 412 413EXPERIMENTAL warm eject support on the 600e/x, A22p and A3x (To use 414this feature, you need to supply the experimental=1 parameter when 415loading the module): 416 417These models do not have a button near the UltraBay device to request 418a hot eject but rather require the laptop to be put to sleep 419(suspend-to-ram) before the bay device is ejected or inserted). 420The sequence of steps to eject the device is as follows: 421 422 echo eject > /proc/acpi/ibm/bay 423 put the ThinkPad to sleep 424 remove the drive 425 resume from sleep 426 cat /proc/acpi/ibm/bay should show that the drive was removed 427 428On the A3x, both the UltraBay 2000 and UltraBay Plus devices are 429supported. Use "eject2" instead of "eject" for the second bay. 430 431Note: the UltraBay eject support on the 600e/x, A22p and A3x is 432EXPERIMENTAL and may not work as expected. USE WITH CAUTION! 433 434CMOS control 435------------ 436 437procfs: /proc/acpi/ibm/cmos 438sysfs device attribute: cmos_command 439 440This feature is used internally by the ACPI firmware to control the 441ThinkLight on most newer ThinkPad models. It may also control LCD 442brightness, sounds volume and more, but only on some models. 443 444The range of valid cmos command numbers is 0 to 21, but not all have an 445effect and the behavior varies from model to model. Here is the behavior 446on the X40 (tpb is the ThinkPad Buttons utility): 447 448 0 - no effect but tpb reports "Volume down" 449 1 - no effect but tpb reports "Volume up" 450 2 - no effect but tpb reports "Mute on" 451 3 - simulate pressing the "Access IBM" button 452 4 - LCD brightness up 453 5 - LCD brightness down 454 11 - toggle screen expansion 455 12 - ThinkLight on 456 13 - ThinkLight off 457 14 - no effect but tpb reports ThinkLight status change 458 459The cmos command interface is prone to firmware split-brain problems, as 460in newer ThinkPads it is just a compatibility layer. 461 462LED control -- /proc/acpi/ibm/led 463--------------------------------- 464 465Some of the LED indicators can be controlled through this feature. The 466available commands are: 467 468 echo '<led number> on' >/proc/acpi/ibm/led 469 echo '<led number> off' >/proc/acpi/ibm/led 470 echo '<led number> blink' >/proc/acpi/ibm/led 471 472The <led number> range is 0 to 7. The set of LEDs that can be 473controlled varies from model to model. Here is the mapping on the X40: 474 475 0 - power 476 1 - battery (orange) 477 2 - battery (green) 478 3 - UltraBase 479 4 - UltraBay 480 7 - standby 481 482All of the above can be turned on and off and can be made to blink. 483 484ACPI sounds -- /proc/acpi/ibm/beep 485---------------------------------- 486 487The BEEP method is used internally by the ACPI firmware to provide 488audible alerts in various situations. This feature allows the same 489sounds to be triggered manually. 490 491The commands are non-negative integer numbers: 492 493 echo <number> >/proc/acpi/ibm/beep 494 495The valid <number> range is 0 to 17. Not all numbers trigger sounds 496and the sounds vary from model to model. Here is the behavior on the 497X40: 498 499 0 - stop a sound in progress (but use 17 to stop 16) 500 2 - two beeps, pause, third beep ("low battery") 501 3 - single beep 502 4 - high, followed by low-pitched beep ("unable") 503 5 - single beep 504 6 - very high, followed by high-pitched beep ("AC/DC") 505 7 - high-pitched beep 506 9 - three short beeps 507 10 - very long beep 508 12 - low-pitched beep 509 15 - three high-pitched beeps repeating constantly, stop with 0 510 16 - one medium-pitched beep repeating constantly, stop with 17 511 17 - stop 16 512 513Temperature sensors 514------------------- 515 516procfs: /proc/acpi/ibm/thermal 517sysfs device attributes: (hwmon) temp*_input 518 519Most ThinkPads include six or more separate temperature sensors but 520only expose the CPU temperature through the standard ACPI methods. 521This feature shows readings from up to eight different sensors on older 522ThinkPads, and it has experimental support for up to sixteen different 523sensors on newer ThinkPads. 524 525EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the 526implementation directly accesses hardware registers and may not work as 527expected. USE WITH CAUTION! To use this feature, you need to supply the 528experimental=1 parameter when loading the module. When EXPERIMENTAL 529mode is enabled, reading the first 8 sensors on newer ThinkPads will 530also use an new experimental thermal sensor access mode. 531 532For example, on the X40, a typical output may be: 533temperatures: 42 42 45 41 36 -128 33 -128 534 535EXPERIMENTAL: On the T43/p, a typical output may be: 536temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128 537 538The mapping of thermal sensors to physical locations varies depending on 539system-board model (and thus, on ThinkPad model). 540 541http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that 542tries to track down these locations for various models. 543 544Most (newer?) models seem to follow this pattern: 545 5461: CPU 5472: (depends on model) 5483: (depends on model) 5494: GPU 5505: Main battery: main sensor 5516: Bay battery: main sensor 5527: Main battery: secondary sensor 5538: Bay battery: secondary sensor 5549-15: (depends on model) 555 556For the R51 (source: Thomas Gruber): 5572: Mini-PCI 5583: Internal HDD 559 560For the T43, T43/p (source: Shmidoax/Thinkwiki.org) 561http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p 5622: System board, left side (near PCMCIA slot), reported as HDAPS temp 5633: PCMCIA slot 5649: MCH (northbridge) to DRAM Bus 56510: ICH (southbridge), under Mini-PCI card, under touchpad 56611: Power regulator, underside of system board, below F2 key 567 568The A31 has a very atypical layout for the thermal sensors 569(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) 5701: CPU 5712: Main Battery: main sensor 5723: Power Converter 5734: Bay Battery: main sensor 5745: MCH (northbridge) 5756: PCMCIA/ambient 5767: Main Battery: secondary sensor 5778: Bay Battery: secondary sensor 578 579 580Procfs notes: 581 Readings from sensors that are not available return -128. 582 No commands can be written to this file. 583 584Sysfs notes: 585 Sensors that are not available return the ENXIO error. This 586 status may change at runtime, as there are hotplug thermal 587 sensors, like those inside the batteries and docks. 588 589 thinkpad-acpi thermal sensors are reported through the hwmon 590 subsystem, and follow all of the hwmon guidelines at 591 Documentation/hwmon. 592 593 594EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump 595------------------------------------------------------------------------ 596 597This feature is marked EXPERIMENTAL because the implementation 598directly accesses hardware registers and may not work as expected. USE 599WITH CAUTION! To use this feature, you need to supply the 600experimental=1 parameter when loading the module. 601 602This feature dumps the values of 256 embedded controller 603registers. Values which have changed since the last time the registers 604were dumped are marked with a star: 605 606[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump 607EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f 608EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00 609EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00 610EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80 611EC 0x30: 01 07 1a 00 30 04 00 00 *85 00 00 10 00 50 00 00 612EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00 613EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 *bc *02 *bc 614EC 0x60: *02 *bc *02 00 00 00 00 00 00 00 00 00 00 00 00 00 615EC 0x70: 00 00 00 00 00 12 30 40 *24 *26 *2c *27 *20 80 *1f 80 616EC 0x80: 00 00 00 06 *37 *0e 03 00 00 00 0e 07 00 00 00 00 617EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 618EC 0xa0: *ff 09 ff 09 ff ff *64 00 *00 *00 *a2 41 *ff *ff *e0 00 619EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 620EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 621EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 622EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03 623EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a 624 625This feature can be used to determine the register holding the fan 626speed on some models. To do that, do the following: 627 628 - make sure the battery is fully charged 629 - make sure the fan is running 630 - run 'cat /proc/acpi/ibm/ecdump' several times, once per second or so 631 632The first step makes sure various charging-related values don't 633vary. The second ensures that the fan-related values do vary, since 634the fan speed fluctuates a bit. The third will (hopefully) mark the 635fan register with a star: 636 637[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump 638EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f 639EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00 640EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00 641EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80 642EC 0x30: 01 07 1a 00 30 04 00 00 85 00 00 10 00 50 00 00 643EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00 644EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 bc 02 bc 645EC 0x60: 02 bc 02 00 00 00 00 00 00 00 00 00 00 00 00 00 646EC 0x70: 00 00 00 00 00 12 30 40 24 27 2c 27 21 80 1f 80 647EC 0x80: 00 00 00 06 *be 0d 03 00 00 00 0e 07 00 00 00 00 648EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 649EC 0xa0: ff 09 ff 09 ff ff 64 00 00 00 a2 41 ff ff e0 00 650EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 651EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 652EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 653EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03 654EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a 655 656Another set of values that varies often is the temperature 657readings. Since temperatures don't change vary fast, you can take 658several quick dumps to eliminate them. 659 660You can use a similar method to figure out the meaning of other 661embedded controller registers - e.g. make sure nothing else changes 662except the charging or discharging battery to determine which 663registers contain the current battery capacity, etc. If you experiment 664with this, do send me your results (including some complete dumps with 665a description of the conditions when they were taken.) 666 667LCD brightness control 668---------------------- 669 670procfs: /proc/acpi/ibm/brightness 671sysfs backlight device "thinkpad_screen" 672 673This feature allows software control of the LCD brightness on ThinkPad 674models which don't have a hardware brightness slider. 675 676It has some limitations: the LCD backlight cannot be actually turned on or off 677by this interface, and in many ThinkPad models, the "dim while on battery" 678functionality will be enabled by the BIOS when this interface is used, and 679cannot be controlled. 680 681The backlight control has eight levels, ranging from 0 to 7. Some of the 682levels may not be distinct. 683 684Procfs notes: 685 686 The available commands are: 687 688 echo up >/proc/acpi/ibm/brightness 689 echo down >/proc/acpi/ibm/brightness 690 echo 'level <level>' >/proc/acpi/ibm/brightness 691 692Sysfs notes: 693 694The interface is implemented through the backlight sysfs class, which is poorly 695documented at this time. 696 697Locate the thinkpad_screen device under /sys/class/backlight, and inside it 698there will be the following attributes: 699 700 max_brightness: 701 Reads the maximum brightness the hardware can be set to. 702 The minimum is always zero. 703 704 actual_brightness: 705 Reads what brightness the screen is set to at this instant. 706 707 brightness: 708 Writes request the driver to change brightness to the given 709 value. Reads will tell you what brightness the driver is trying 710 to set the display to when "power" is set to zero and the display 711 has not been dimmed by a kernel power management event. 712 713 power: 714 power management mode, where 0 is "display on", and 1 to 3 will 715 dim the display backlight to brightness level 0 because 716 thinkpad-acpi cannot really turn the backlight off. Kernel 717 power management events can temporarily increase the current 718 power management level, i.e. they can dim the display. 719 720 721Volume control -- /proc/acpi/ibm/volume 722--------------------------------------- 723 724This feature allows volume control on ThinkPad models which don't have 725a hardware volume knob. The available commands are: 726 727 echo up >/proc/acpi/ibm/volume 728 echo down >/proc/acpi/ibm/volume 729 echo mute >/proc/acpi/ibm/volume 730 echo 'level <level>' >/proc/acpi/ibm/volume 731 732The <level> number range is 0 to 15 although not all of them may be 733distinct. The unmute the volume after the mute command, use either the 734up or down command (the level command will not unmute the volume). 735The current volume level and mute state is shown in the file. 736 737Fan control and monitoring: fan speed, fan enable/disable 738--------------------------------------------------------- 739 740procfs: /proc/acpi/ibm/fan 741sysfs device attributes: (hwmon) fan_input, pwm1, pwm1_enable 742 743NOTE NOTE NOTE: fan control operations are disabled by default for 744safety reasons. To enable them, the module parameter "fan_control=1" 745must be given to thinkpad-acpi. 746 747This feature attempts to show the current fan speed, control mode and 748other fan data that might be available. The speed is read directly 749from the hardware registers of the embedded controller. This is known 750to work on later R, T, X and Z series ThinkPads but may show a bogus 751value on other models. 752 753Fan levels: 754 755Most ThinkPad fans work in "levels" at the firmware interface. Level 0 756stops the fan. The higher the level, the higher the fan speed, although 757adjacent levels often map to the same fan speed. 7 is the highest 758level, where the fan reaches the maximum recommended speed. 759 760Level "auto" means the EC changes the fan level according to some 761internal algorithm, usually based on readings from the thermal sensors. 762 763There is also a "full-speed" level, also known as "disengaged" level. 764In this level, the EC disables the speed-locked closed-loop fan control, 765and drives the fan as fast as it can go, which might exceed hardware 766limits, so use this level with caution. 767 768The fan usually ramps up or down slowly from one speed to another, and 769it is normal for the EC to take several seconds to react to fan 770commands. The full-speed level may take up to two minutes to ramp up to 771maximum speed, and in some ThinkPads, the tachometer readings go stale 772while the EC is transitioning to the full-speed level. 773 774WARNING WARNING WARNING: do not leave the fan disabled unless you are 775monitoring all of the temperature sensor readings and you are ready to 776enable it if necessary to avoid overheating. 777 778An enabled fan in level "auto" may stop spinning if the EC decides the 779ThinkPad is cool enough and doesn't need the extra airflow. This is 780normal, and the EC will spin the fan up if the varios thermal readings 781rise too much. 782 783On the X40, this seems to depend on the CPU and HDD temperatures. 784Specifically, the fan is turned on when either the CPU temperature 785climbs to 56 degrees or the HDD temperature climbs to 46 degrees. The 786fan is turned off when the CPU temperature drops to 49 degrees and the 787HDD temperature drops to 41 degrees. These thresholds cannot 788currently be controlled. 789 790The ThinkPad's ACPI DSDT code will reprogram the fan on its own when 791certain conditions are met. It will override any fan programming done 792through thinkpad-acpi. 793 794The thinkpad-acpi kernel driver can be programmed to revert the fan 795level to a safe setting if userspace does not issue one of the procfs 796fan commands: "enable", "disable", "level" or "watchdog", or if there 797are no writes to pwm1_enable (or to pwm1 *if and only if* pwm1_enable is 798set to 1, manual mode) within a configurable amount of time of up to 799120 seconds. This functionality is called fan safety watchdog. 800 801Note that the watchdog timer stops after it enables the fan. It will be 802rearmed again automatically (using the same interval) when one of the 803above mentioned fan commands is received. The fan watchdog is, 804therefore, not suitable to protect against fan mode changes made through 805means other than the "enable", "disable", and "level" procfs fan 806commands, or the hwmon fan control sysfs interface. 807 808Procfs notes: 809 810The fan may be enabled or disabled with the following commands: 811 812 echo enable >/proc/acpi/ibm/fan 813 echo disable >/proc/acpi/ibm/fan 814 815Placing a fan on level 0 is the same as disabling it. Enabling a fan 816will try to place it in a safe level if it is too slow or disabled. 817 818The fan level can be controlled with the command: 819 820 echo 'level <level>' > /proc/acpi/ibm/fan 821 822Where <level> is an integer from 0 to 7, or one of the words "auto" or 823"full-speed" (without the quotes). Not all ThinkPads support the "auto" 824and "full-speed" levels. The driver accepts "disengaged" as an alias for 825"full-speed", and reports it as "disengaged" for backwards 826compatibility. 827 828On the X31 and X40 (and ONLY on those models), the fan speed can be 829controlled to a certain degree. Once the fan is running, it can be 830forced to run faster or slower with the following command: 831 832 echo 'speed <speed>' > /proc/acpi/ibm/fan 833 834The sustainable range of fan speeds on the X40 appears to be from about 8353700 to about 7350. Values outside this range either do not have any 836effect or the fan speed eventually settles somewhere in that range. The 837fan cannot be stopped or started with this command. This functionality 838is incomplete, and not available through the sysfs interface. 839 840To program the safety watchdog, use the "watchdog" command. 841 842 echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan 843 844If you want to disable the watchdog, use 0 as the interval. 845 846Sysfs notes: 847 848The sysfs interface follows the hwmon subsystem guidelines for the most 849part, and the exception is the fan safety watchdog. 850 851Writes to any of the sysfs attributes may return the EINVAL error if 852that operation is not supported in a given ThinkPad or if the parameter 853is out-of-bounds, and EPERM if it is forbidden. They may also return 854EINTR (interrupted system call), and EIO (I/O error while trying to talk 855to the firmware). 856 857Features not yet implemented by the driver return ENOSYS. 858 859hwmon device attribute pwm1_enable: 860 0: PWM offline (fan is set to full-speed mode) 861 1: Manual PWM control (use pwm1 to set fan level) 862 2: Hardware PWM control (EC "auto" mode) 863 3: reserved (Software PWM control, not implemented yet) 864 865 Modes 0 and 2 are not supported by all ThinkPads, and the 866 driver is not always able to detect this. If it does know a 867 mode is unsupported, it will return -EINVAL. 868 869hwmon device attribute pwm1: 870 Fan level, scaled from the firmware values of 0-7 to the hwmon 871 scale of 0-255. 0 means fan stopped, 255 means highest normal 872 speed (level 7). 873 874 This attribute only commands the fan if pmw1_enable is set to 1 875 (manual PWM control). 876 877hwmon device attribute fan1_input: 878 Fan tachometer reading, in RPM. May go stale on certain 879 ThinkPads while the EC transitions the PWM to offline mode, 880 which can take up to two minutes. May return rubbish on older 881 ThinkPads. 882 883driver attribute fan_watchdog: 884 Fan safety watchdog timer interval, in seconds. Minimum is 885 1 second, maximum is 120 seconds. 0 disables the watchdog. 886 887To stop the fan: set pwm1 to zero, and pwm1_enable to 1. 888 889To start the fan in a safe mode: set pwm1_enable to 2. If that fails 890with EINVAL, try to set pwm1_enable to 1 and pwm1 to at least 128 (255 891would be the safest choice, though). 892 893 894EXPERIMENTAL: WAN 895----------------- 896 897procfs: /proc/acpi/ibm/wan 898sysfs device attribute: wwan_enable 899 900This feature is marked EXPERIMENTAL because the implementation 901directly accesses hardware registers and may not work as expected. USE 902WITH CAUTION! To use this feature, you need to supply the 903experimental=1 parameter when loading the module. 904 905This feature shows the presence and current state of a W-WAN (Sierra 906Wireless EV-DO) device. 907 908It was tested on a Lenovo Thinkpad X60. It should probably work on other 909Thinkpad models which come with this module installed. 910 911Procfs notes: 912 913If the W-WAN card is installed, the following commands can be used: 914 915 echo enable > /proc/acpi/ibm/wan 916 echo disable > /proc/acpi/ibm/wan 917 918Sysfs notes: 919 920 If the W-WAN card is installed, it can be enabled / 921 disabled through the "wwan_enable" thinkpad-acpi device 922 attribute, and its current status can also be queried. 923 924 enable: 925 0: disables WWAN card / WWAN card is disabled 926 1: enables WWAN card / WWAN card is enabled. 927 928 Note: this interface will be probably be superseeded by the 929 generic rfkill class, so it is NOT to be considered stable yet. 930 931Multiple Commands, Module Parameters 932------------------------------------ 933 934Multiple commands can be written to the proc files in one shot by 935separating them with commas, for example: 936 937 echo enable,0xffff > /proc/acpi/ibm/hotkey 938 echo lcd_disable,crt_enable > /proc/acpi/ibm/video 939 940Commands can also be specified when loading the thinkpad-acpi module, 941for example: 942 943 modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable 944 945Enabling debugging output 946------------------------- 947 948The module takes a debug paramater which can be used to selectively 949enable various classes of debugging output, for example: 950 951 modprobe ibm_acpi debug=0xffff 952 953will enable all debugging output classes. It takes a bitmask, so 954to enable more than one output class, just add their values. 955 956 Debug bitmask Description 957 0x0001 Initialization and probing 958 0x0002 Removal 959 960There is also a kernel build option to enable more debugging 961information, which may be necessary to debug driver problems. 962 963The level of debugging information output by the driver can be changed 964at runtime through sysfs, using the driver attribute debug_level. The 965attribute takes the same bitmask as the debug module parameter above. 966 967Force loading of module 968----------------------- 969 970If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify 971the module parameter force_load=1. Regardless of whether this works or 972not, please contact ibm-acpi-devel@lists.sourceforge.net with a report. 973 974 975Sysfs interface changelog: 976 9770x000100: Initial sysfs support, as a single platform driver and 978 device. 979