1=========================== 2ThinkPad ACPI Extras Driver 3=========================== 4 5Version 0.25 6 7October 16th, 2013 8 9- Borislav Deianov <borislav@users.sf.net> 10- Henrique de Moraes Holschuh <hmh@hmh.eng.br> 11 12http://ibm-acpi.sf.net/ 13 14This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It 15supports various features of these laptops which are accessible 16through the ACPI and ACPI EC framework, but not otherwise fully 17supported by the generic Linux ACPI drivers. 18 19This driver used to be named ibm-acpi until kernel 2.6.21 and release 200.13-20070314. It used to be in the drivers/acpi tree, but it was 21moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel 222.6.22, and release 0.14. It was moved to drivers/platform/x86 for 23kernel 2.6.29 and release 0.22. 24 25The driver is named "thinkpad-acpi". In some places, like module 26names and log messages, "thinkpad_acpi" is used because of userspace 27issues. 28 29"tpacpi" is used as a shorthand where "thinkpad-acpi" would be too 30long due to length limitations on some Linux kernel versions. 31 32Status 33------ 34 35The features currently supported are the following (see below for 36detailed description): 37 38 - Fn key combinations 39 - Bluetooth enable and disable 40 - video output switching, expansion control 41 - ThinkLight on and off 42 - CMOS/UCMS control 43 - LED control 44 - ACPI sounds 45 - temperature sensors 46 - Experimental: embedded controller register dump 47 - LCD brightness control 48 - Volume control 49 - Fan control and monitoring: fan speed, fan enable/disable 50 - WAN enable and disable 51 - UWB enable and disable 52 53A compatibility table by model and feature is maintained on the web 54site, http://ibm-acpi.sf.net/. I appreciate any success or failure 55reports, especially if they add to or correct the compatibility table. 56Please include the following information in your report: 57 58 - ThinkPad model name 59 - a copy of your ACPI tables, using the "acpidump" utility 60 - a copy of the output of dmidecode, with serial numbers 61 and UUIDs masked off 62 - which driver features work and which don't 63 - the observed behavior of non-working features 64 65Any other comments or patches are also more than welcome. 66 67 68Installation 69------------ 70 71If you are compiling this driver as included in the Linux kernel 72sources, look for the CONFIG_THINKPAD_ACPI Kconfig option. 73It is located on the menu path: "Device Drivers" -> "X86 Platform 74Specific Device Drivers" -> "ThinkPad ACPI Laptop Extras". 75 76 77Features 78-------- 79 80The driver exports two different interfaces to userspace, which can be 81used to access the features it provides. One is a legacy procfs-based 82interface, which will be removed at some time in the future. The other 83is a new sysfs-based interface which is not complete yet. 84 85The procfs interface creates the /proc/acpi/ibm directory. There is a 86file under that directory for each feature it supports. The procfs 87interface is mostly frozen, and will change very little if at all: it 88will not be extended to add any new functionality in the driver, instead 89all new functionality will be implemented on the sysfs interface. 90 91The sysfs interface tries to blend in the generic Linux sysfs subsystems 92and classes as much as possible. Since some of these subsystems are not 93yet ready or stabilized, it is expected that this interface will change, 94and any and all userspace programs must deal with it. 95 96 97Notes about the sysfs interface 98^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 99 100Unlike what was done with the procfs interface, correctness when talking 101to the sysfs interfaces will be enforced, as will correctness in the 102thinkpad-acpi's implementation of sysfs interfaces. 103 104Also, any bugs in the thinkpad-acpi sysfs driver code or in the 105thinkpad-acpi's implementation of the sysfs interfaces will be fixed for 106maximum correctness, even if that means changing an interface in 107non-compatible ways. As these interfaces mature both in the kernel and 108in thinkpad-acpi, such changes should become quite rare. 109 110Applications interfacing to the thinkpad-acpi sysfs interfaces must 111follow all sysfs guidelines and correctly process all errors (the sysfs 112interface makes extensive use of errors). File descriptors and open / 113close operations to the sysfs inodes must also be properly implemented. 114 115The version of thinkpad-acpi's sysfs interface is exported by the driver 116as a driver attribute (see below). 117 118Sysfs driver attributes are on the driver's sysfs attribute space, 119for 2.6.23+ this is /sys/bus/platform/drivers/thinkpad_acpi/ and 120/sys/bus/platform/drivers/thinkpad_hwmon/ 121 122Sysfs device attributes are on the thinkpad_acpi device sysfs attribute 123space, for 2.6.23+ this is /sys/devices/platform/thinkpad_acpi/. 124 125Sysfs device attributes for the sensors and fan are on the 126thinkpad_hwmon device's sysfs attribute space, but you should locate it 127looking for a hwmon device with the name attribute of "thinkpad", or 128better yet, through libsensors. For 4.14+ sysfs attributes were moved to the 129hwmon device (/sys/bus/platform/devices/thinkpad_hwmon/hwmon/hwmon? or 130/sys/class/hwmon/hwmon?). 131 132Driver version 133-------------- 134 135procfs: /proc/acpi/ibm/driver 136 137sysfs driver attribute: version 138 139The driver name and version. No commands can be written to this file. 140 141 142Sysfs interface version 143----------------------- 144 145sysfs driver attribute: interface_version 146 147Version of the thinkpad-acpi sysfs interface, as an unsigned long 148(output in hex format: 0xAAAABBCC), where: 149 150 AAAA 151 - major revision 152 BB 153 - minor revision 154 CC 155 - bugfix revision 156 157The sysfs interface version changelog for the driver can be found at the 158end of this document. Changes to the sysfs interface done by the kernel 159subsystems are not documented here, nor are they tracked by this 160attribute. 161 162Changes to the thinkpad-acpi sysfs interface are only considered 163non-experimental when they are submitted to Linux mainline, at which 164point the changes in this interface are documented and interface_version 165may be updated. If you are using any thinkpad-acpi features not yet 166sent to mainline for merging, you do so on your own risk: these features 167may disappear, or be implemented in a different and incompatible way by 168the time they are merged in Linux mainline. 169 170Changes that are backwards-compatible by nature (e.g. the addition of 171attributes that do not change the way the other attributes work) do not 172always warrant an update of interface_version. Therefore, one must 173expect that an attribute might not be there, and deal with it properly 174(an attribute not being there *is* a valid way to make it clear that a 175feature is not available in sysfs). 176 177 178Hot keys 179-------- 180 181procfs: /proc/acpi/ibm/hotkey 182 183sysfs device attribute: hotkey_* 184 185In a ThinkPad, the ACPI HKEY handler is responsible for communicating 186some important events and also keyboard hot key presses to the operating 187system. Enabling the hotkey functionality of thinkpad-acpi signals the 188firmware that such a driver is present, and modifies how the ThinkPad 189firmware will behave in many situations. 190 191The driver enables the HKEY ("hot key") event reporting automatically 192when loaded, and disables it when it is removed. 193 194The driver will report HKEY events in the following format:: 195 196 ibm/hotkey HKEY 00000080 0000xxxx 197 198Some of these events refer to hot key presses, but not all of them. 199 200The driver will generate events over the input layer for hot keys and 201radio switches, and over the ACPI netlink layer for other events. The 202input layer support accepts the standard IOCTLs to remap the keycodes 203assigned to each hot key. 204 205The hot key bit mask allows some control over which hot keys generate 206events. If a key is "masked" (bit set to 0 in the mask), the firmware 207will handle it. If it is "unmasked", it signals the firmware that 208thinkpad-acpi would prefer to handle it, if the firmware would be so 209kind to allow it (and it often doesn't!). 210 211Not all bits in the mask can be modified. Not all bits that can be 212modified do anything. Not all hot keys can be individually controlled 213by the mask. Some models do not support the mask at all. The behaviour 214of the mask is, therefore, highly dependent on the ThinkPad model. 215 216The driver will filter out any unmasked hotkeys, so even if the firmware 217doesn't allow disabling an specific hotkey, the driver will not report 218events for unmasked hotkeys. 219 220Note that unmasking some keys prevents their default behavior. For 221example, if Fn+F5 is unmasked, that key will no longer enable/disable 222Bluetooth by itself in firmware. 223 224Note also that not all Fn key combinations are supported through ACPI 225depending on the ThinkPad model and firmware version. On those 226ThinkPads, it is still possible to support some extra hotkeys by 227polling the "CMOS NVRAM" at least 10 times per second. The driver 228attempts to enables this functionality automatically when required. 229 230procfs notes 231^^^^^^^^^^^^ 232 233The following commands can be written to the /proc/acpi/ibm/hotkey file:: 234 235 echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys 236 echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys 237 ... any other 8-hex-digit mask ... 238 echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask 239 240The following commands have been deprecated and will cause the kernel 241to log a warning:: 242 243 echo enable > /proc/acpi/ibm/hotkey -- does nothing 244 echo disable > /proc/acpi/ibm/hotkey -- returns an error 245 246The procfs interface does not support NVRAM polling control. So as to 247maintain maximum bug-to-bug compatibility, it does not report any masks, 248nor does it allow one to manipulate the hot key mask when the firmware 249does not support masks at all, even if NVRAM polling is in use. 250 251sysfs notes 252^^^^^^^^^^^ 253 254 hotkey_bios_enabled: 255 DEPRECATED, WILL BE REMOVED SOON. 256 257 Returns 0. 258 259 hotkey_bios_mask: 260 DEPRECATED, DON'T USE, WILL BE REMOVED IN THE FUTURE. 261 262 Returns the hot keys mask when thinkpad-acpi was loaded. 263 Upon module unload, the hot keys mask will be restored 264 to this value. This is always 0x80c, because those are 265 the hotkeys that were supported by ancient firmware 266 without mask support. 267 268 hotkey_enable: 269 DEPRECATED, WILL BE REMOVED SOON. 270 271 0: returns -EPERM 272 1: does nothing 273 274 hotkey_mask: 275 bit mask to enable reporting (and depending on 276 the firmware, ACPI event generation) for each hot key 277 (see above). Returns the current status of the hot keys 278 mask, and allows one to modify it. 279 280 hotkey_all_mask: 281 bit mask that should enable event reporting for all 282 supported hot keys, when echoed to hotkey_mask above. 283 Unless you know which events need to be handled 284 passively (because the firmware *will* handle them 285 anyway), do *not* use hotkey_all_mask. Use 286 hotkey_recommended_mask, instead. You have been warned. 287 288 hotkey_recommended_mask: 289 bit mask that should enable event reporting for all 290 supported hot keys, except those which are always 291 handled by the firmware anyway. Echo it to 292 hotkey_mask above, to use. This is the default mask 293 used by the driver. 294 295 hotkey_source_mask: 296 bit mask that selects which hot keys will the driver 297 poll the NVRAM for. This is auto-detected by the driver 298 based on the capabilities reported by the ACPI firmware, 299 but it can be overridden at runtime. 300 301 Hot keys whose bits are set in hotkey_source_mask are 302 polled for in NVRAM, and reported as hotkey events if 303 enabled in hotkey_mask. Only a few hot keys are 304 available through CMOS NVRAM polling. 305 306 Warning: when in NVRAM mode, the volume up/down/mute 307 keys are synthesized according to changes in the mixer, 308 which uses a single volume up or volume down hotkey 309 press to unmute, as per the ThinkPad volume mixer user 310 interface. When in ACPI event mode, volume up/down/mute 311 events are reported by the firmware and can behave 312 differently (and that behaviour changes with firmware 313 version -- not just with firmware models -- as well as 314 OSI(Linux) state). 315 316 hotkey_poll_freq: 317 frequency in Hz for hot key polling. It must be between 318 0 and 25 Hz. Polling is only carried out when strictly 319 needed. 320 321 Setting hotkey_poll_freq to zero disables polling, and 322 will cause hot key presses that require NVRAM polling 323 to never be reported. 324 325 Setting hotkey_poll_freq too low may cause repeated 326 pressings of the same hot key to be misreported as a 327 single key press, or to not even be detected at all. 328 The recommended polling frequency is 10Hz. 329 330 hotkey_radio_sw: 331 If the ThinkPad has a hardware radio switch, this 332 attribute will read 0 if the switch is in the "radios 333 disabled" position, and 1 if the switch is in the 334 "radios enabled" position. 335 336 This attribute has poll()/select() support. 337 338 hotkey_tablet_mode: 339 If the ThinkPad has tablet capabilities, this attribute 340 will read 0 if the ThinkPad is in normal mode, and 341 1 if the ThinkPad is in tablet mode. 342 343 This attribute has poll()/select() support. 344 345 wakeup_reason: 346 Set to 1 if the system is waking up because the user 347 requested a bay ejection. Set to 2 if the system is 348 waking up because the user requested the system to 349 undock. Set to zero for normal wake-ups or wake-ups 350 due to unknown reasons. 351 352 This attribute has poll()/select() support. 353 354 wakeup_hotunplug_complete: 355 Set to 1 if the system was waken up because of an 356 undock or bay ejection request, and that request 357 was successfully completed. At this point, it might 358 be useful to send the system back to sleep, at the 359 user's choice. Refer to HKEY events 0x4003 and 360 0x3003, below. 361 362 This attribute has poll()/select() support. 363 364input layer notes 365^^^^^^^^^^^^^^^^^ 366 367A Hot key is mapped to a single input layer EV_KEY event, possibly 368followed by an EV_MSC MSC_SCAN event that shall contain that key's scan 369code. An EV_SYN event will always be generated to mark the end of the 370event block. 371 372Do not use the EV_MSC MSC_SCAN events to process keys. They are to be 373used as a helper to remap keys, only. They are particularly useful when 374remapping KEY_UNKNOWN keys. 375 376The events are available in an input device, with the following id: 377 378 ============== ============================== 379 Bus BUS_HOST 380 vendor 0x1014 (PCI_VENDOR_ID_IBM) or 381 0x17aa (PCI_VENDOR_ID_LENOVO) 382 product 0x5054 ("TP") 383 version 0x4101 384 ============== ============================== 385 386The version will have its LSB incremented if the keymap changes in a 387backwards-compatible way. The MSB shall always be 0x41 for this input 388device. If the MSB is not 0x41, do not use the device as described in 389this section, as it is either something else (e.g. another input device 390exported by a thinkpad driver, such as HDAPS) or its functionality has 391been changed in a non-backwards compatible way. 392 393Adding other event types for other functionalities shall be considered a 394backwards-compatible change for this input device. 395 396Thinkpad-acpi Hot Key event map (version 0x4101): 397 398======= ======= ============== ============================================== 399ACPI Scan 400event code Key Notes 401======= ======= ============== ============================================== 4020x1001 0x00 FN+F1 - 403 4040x1002 0x01 FN+F2 IBM: battery (rare) 405 Lenovo: Screen lock 406 4070x1003 0x02 FN+F3 Many IBM models always report 408 this hot key, even with hot keys 409 disabled or with Fn+F3 masked 410 off 411 IBM: screen lock, often turns 412 off the ThinkLight as side-effect 413 Lenovo: battery 414 4150x1004 0x03 FN+F4 Sleep button (ACPI sleep button 416 semantics, i.e. sleep-to-RAM). 417 It always generates some kind 418 of event, either the hot key 419 event or an ACPI sleep button 420 event. The firmware may 421 refuse to generate further FN+F4 422 key presses until a S3 or S4 ACPI 423 sleep cycle is performed or some 424 time passes. 425 4260x1005 0x04 FN+F5 Radio. Enables/disables 427 the internal Bluetooth hardware 428 and W-WAN card if left in control 429 of the firmware. Does not affect 430 the WLAN card. 431 Should be used to turn on/off all 432 radios (Bluetooth+W-WAN+WLAN), 433 really. 434 4350x1006 0x05 FN+F6 - 436 4370x1007 0x06 FN+F7 Video output cycle. 438 Do you feel lucky today? 439 4400x1008 0x07 FN+F8 IBM: toggle screen expand 441 Lenovo: configure UltraNav, 442 or toggle screen expand 443 4440x1009 0x08 FN+F9 - 445 446... ... ... ... 447 4480x100B 0x0A FN+F11 - 449 4500x100C 0x0B FN+F12 Sleep to disk. You are always 451 supposed to handle it yourself, 452 either through the ACPI event, 453 or through a hotkey event. 454 The firmware may refuse to 455 generate further FN+F12 key 456 press events until a S3 or S4 457 ACPI sleep cycle is performed, 458 or some time passes. 459 4600x100D 0x0C FN+BACKSPACE - 4610x100E 0x0D FN+INSERT - 4620x100F 0x0E FN+DELETE - 463 4640x1010 0x0F FN+HOME Brightness up. This key is 465 always handled by the firmware 466 in IBM ThinkPads, even when 467 unmasked. Just leave it alone. 468 For Lenovo ThinkPads with a new 469 BIOS, it has to be handled either 470 by the ACPI OSI, or by userspace. 471 The driver does the right thing, 472 never mess with this. 4730x1011 0x10 FN+END Brightness down. See brightness 474 up for details. 475 4760x1012 0x11 FN+PGUP ThinkLight toggle. This key is 477 always handled by the firmware, 478 even when unmasked. 479 4800x1013 0x12 FN+PGDOWN - 481 4820x1014 0x13 FN+SPACE Zoom key 483 4840x1015 0x14 VOLUME UP Internal mixer volume up. This 485 key is always handled by the 486 firmware, even when unmasked. 487 NOTE: Lenovo seems to be changing 488 this. 4890x1016 0x15 VOLUME DOWN Internal mixer volume up. This 490 key is always handled by the 491 firmware, even when unmasked. 492 NOTE: Lenovo seems to be changing 493 this. 4940x1017 0x16 MUTE Mute internal mixer. This 495 key is always handled by the 496 firmware, even when unmasked. 497 4980x1018 0x17 THINKPAD ThinkPad/Access IBM/Lenovo key 499 5000x1019 0x18 unknown 501 502... ... ... 503 5040x1020 0x1F unknown 505======= ======= ============== ============================================== 506 507The ThinkPad firmware does not allow one to differentiate when most hot 508keys are pressed or released (either that, or we don't know how to, yet). 509For these keys, the driver generates a set of events for a key press and 510immediately issues the same set of events for a key release. It is 511unknown by the driver if the ThinkPad firmware triggered these events on 512hot key press or release, but the firmware will do it for either one, not 513both. 514 515If a key is mapped to KEY_RESERVED, it generates no input events at all. 516If a key is mapped to KEY_UNKNOWN, it generates an input event that 517includes an scan code. If a key is mapped to anything else, it will 518generate input device EV_KEY events. 519 520In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW 521events for switches: 522 523============== ============================================== 524SW_RFKILL_ALL T60 and later hardware rfkill rocker switch 525SW_TABLET_MODE Tablet ThinkPads HKEY events 0x5009 and 0x500A 526============== ============================================== 527 528Non hotkey ACPI HKEY event map 529------------------------------ 530 531Events that are never propagated by the driver: 532 533====== ================================================== 5340x2304 System is waking up from suspend to undock 5350x2305 System is waking up from suspend to eject bay 5360x2404 System is waking up from hibernation to undock 5370x2405 System is waking up from hibernation to eject bay 5380x5001 Lid closed 5390x5002 Lid opened 5400x5009 Tablet swivel: switched to tablet mode 5410x500A Tablet swivel: switched to normal mode 5420x5010 Brightness level changed/control event 5430x6000 KEYBOARD: Numlock key pressed 5440x6005 KEYBOARD: Fn key pressed (TO BE VERIFIED) 5450x7000 Radio Switch may have changed state 546====== ================================================== 547 548 549Events that are propagated by the driver to userspace: 550 551====== ===================================================== 5520x2313 ALARM: System is waking up from suspend because 553 the battery is nearly empty 5540x2413 ALARM: System is waking up from hibernation because 555 the battery is nearly empty 5560x3003 Bay ejection (see 0x2x05) complete, can sleep again 5570x3006 Bay hotplug request (hint to power up SATA link when 558 the optical drive tray is ejected) 5590x4003 Undocked (see 0x2x04), can sleep again 5600x4010 Docked into hotplug port replicator (non-ACPI dock) 5610x4011 Undocked from hotplug port replicator (non-ACPI dock) 5620x500B Tablet pen inserted into its storage bay 5630x500C Tablet pen removed from its storage bay 5640x6011 ALARM: battery is too hot 5650x6012 ALARM: battery is extremely hot 5660x6021 ALARM: a sensor is too hot 5670x6022 ALARM: a sensor is extremely hot 5680x6030 System thermal table changed 5690x6032 Thermal Control command set completion (DYTC, Windows) 5700x6040 Nvidia Optimus/AC adapter related (TO BE VERIFIED) 5710x60C0 X1 Yoga 2016, Tablet mode status changed 5720x60F0 Thermal Transformation changed (GMTS, Windows) 573====== ===================================================== 574 575Battery nearly empty alarms are a last resort attempt to get the 576operating system to hibernate or shutdown cleanly (0x2313), or shutdown 577cleanly (0x2413) before power is lost. They must be acted upon, as the 578wake up caused by the firmware will have negated most safety nets... 579 580When any of the "too hot" alarms happen, according to Lenovo the user 581should suspend or hibernate the laptop (and in the case of battery 582alarms, unplug the AC adapter) to let it cool down. These alarms do 583signal that something is wrong, they should never happen on normal 584operating conditions. 585 586The "extremely hot" alarms are emergencies. According to Lenovo, the 587operating system is to force either an immediate suspend or hibernate 588cycle, or a system shutdown. Obviously, something is very wrong if this 589happens. 590 591 592Brightness hotkey notes 593^^^^^^^^^^^^^^^^^^^^^^^ 594 595Don't mess with the brightness hotkeys in a Thinkpad. If you want 596notifications for OSD, use the sysfs backlight class event support. 597 598The driver will issue KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN events 599automatically for the cases were userspace has to do something to 600implement brightness changes. When you override these events, you will 601either fail to handle properly the ThinkPads that require explicit 602action to change backlight brightness, or the ThinkPads that require 603that no action be taken to work properly. 604 605 606Bluetooth 607--------- 608 609procfs: /proc/acpi/ibm/bluetooth 610 611sysfs device attribute: bluetooth_enable (deprecated) 612 613sysfs rfkill class: switch "tpacpi_bluetooth_sw" 614 615This feature shows the presence and current state of a ThinkPad 616Bluetooth device in the internal ThinkPad CDC slot. 617 618If the ThinkPad supports it, the Bluetooth state is stored in NVRAM, 619so it is kept across reboots and power-off. 620 621Procfs notes 622^^^^^^^^^^^^ 623 624If Bluetooth is installed, the following commands can be used:: 625 626 echo enable > /proc/acpi/ibm/bluetooth 627 echo disable > /proc/acpi/ibm/bluetooth 628 629Sysfs notes 630^^^^^^^^^^^ 631 632 If the Bluetooth CDC card is installed, it can be enabled / 633 disabled through the "bluetooth_enable" thinkpad-acpi device 634 attribute, and its current status can also be queried. 635 636 enable: 637 638 - 0: disables Bluetooth / Bluetooth is disabled 639 - 1: enables Bluetooth / Bluetooth is enabled. 640 641 Note: this interface has been superseded by the generic rfkill 642 class. It has been deprecated, and it will be removed in year 643 2010. 644 645 rfkill controller switch "tpacpi_bluetooth_sw": refer to 646 Documentation/driver-api/rfkill.rst for details. 647 648 649Video output control -- /proc/acpi/ibm/video 650-------------------------------------------- 651 652This feature allows control over the devices used for video output - 653LCD, CRT or DVI (if available). The following commands are available:: 654 655 echo lcd_enable > /proc/acpi/ibm/video 656 echo lcd_disable > /proc/acpi/ibm/video 657 echo crt_enable > /proc/acpi/ibm/video 658 echo crt_disable > /proc/acpi/ibm/video 659 echo dvi_enable > /proc/acpi/ibm/video 660 echo dvi_disable > /proc/acpi/ibm/video 661 echo auto_enable > /proc/acpi/ibm/video 662 echo auto_disable > /proc/acpi/ibm/video 663 echo expand_toggle > /proc/acpi/ibm/video 664 echo video_switch > /proc/acpi/ibm/video 665 666NOTE: 667 Access to this feature is restricted to processes owning the 668 CAP_SYS_ADMIN capability for safety reasons, as it can interact badly 669 enough with some versions of X.org to crash it. 670 671Each video output device can be enabled or disabled individually. 672Reading /proc/acpi/ibm/video shows the status of each device. 673 674Automatic video switching can be enabled or disabled. When automatic 675video switching is enabled, certain events (e.g. opening the lid, 676docking or undocking) cause the video output device to change 677automatically. While this can be useful, it also causes flickering 678and, on the X40, video corruption. By disabling automatic switching, 679the flickering or video corruption can be avoided. 680 681The video_switch command cycles through the available video outputs 682(it simulates the behavior of Fn-F7). 683 684Video expansion can be toggled through this feature. This controls 685whether the display is expanded to fill the entire LCD screen when a 686mode with less than full resolution is used. Note that the current 687video expansion status cannot be determined through this feature. 688 689Note that on many models (particularly those using Radeon graphics 690chips) the X driver configures the video card in a way which prevents 691Fn-F7 from working. This also disables the video output switching 692features of this driver, as it uses the same ACPI methods as 693Fn-F7. Video switching on the console should still work. 694 695UPDATE: refer to https://bugs.freedesktop.org/show_bug.cgi?id=2000 696 697 698ThinkLight control 699------------------ 700 701procfs: /proc/acpi/ibm/light 702 703sysfs attributes: as per LED class, for the "tpacpi::thinklight" LED 704 705procfs notes 706^^^^^^^^^^^^ 707 708The ThinkLight status can be read and set through the procfs interface. A 709few models which do not make the status available will show the ThinkLight 710status as "unknown". The available commands are:: 711 712 echo on > /proc/acpi/ibm/light 713 echo off > /proc/acpi/ibm/light 714 715sysfs notes 716^^^^^^^^^^^ 717 718The ThinkLight sysfs interface is documented by the LED class 719documentation, in Documentation/leds/leds-class.rst. The ThinkLight LED name 720is "tpacpi::thinklight". 721 722Due to limitations in the sysfs LED class, if the status of the ThinkLight 723cannot be read or if it is unknown, thinkpad-acpi will report it as "off". 724It is impossible to know if the status returned through sysfs is valid. 725 726 727CMOS/UCMS control 728----------------- 729 730procfs: /proc/acpi/ibm/cmos 731 732sysfs device attribute: cmos_command 733 734This feature is mostly used internally by the ACPI firmware to keep the legacy 735CMOS NVRAM bits in sync with the current machine state, and to record this 736state so that the ThinkPad will retain such settings across reboots. 737 738Some of these commands actually perform actions in some ThinkPad models, but 739this is expected to disappear more and more in newer models. As an example, in 740a T43 and in a X40, commands 12 and 13 still control the ThinkLight state for 741real, but commands 0 to 2 don't control the mixer anymore (they have been 742phased out) and just update the NVRAM. 743 744The range of valid cmos command numbers is 0 to 21, but not all have an 745effect and the behavior varies from model to model. Here is the behavior 746on the X40 (tpb is the ThinkPad Buttons utility): 747 748 - 0 - Related to "Volume down" key press 749 - 1 - Related to "Volume up" key press 750 - 2 - Related to "Mute on" key press 751 - 3 - Related to "Access IBM" key press 752 - 4 - Related to "LCD brightness up" key press 753 - 5 - Related to "LCD brightness down" key press 754 - 11 - Related to "toggle screen expansion" key press/function 755 - 12 - Related to "ThinkLight on" 756 - 13 - Related to "ThinkLight off" 757 - 14 - Related to "ThinkLight" key press (toggle ThinkLight) 758 759The cmos command interface is prone to firmware split-brain problems, as 760in newer ThinkPads it is just a compatibility layer. Do not use it, it is 761exported just as a debug tool. 762 763 764LED control 765----------- 766 767procfs: /proc/acpi/ibm/led 768sysfs attributes: as per LED class, see below for names 769 770Some of the LED indicators can be controlled through this feature. On 771some older ThinkPad models, it is possible to query the status of the 772LED indicators as well. Newer ThinkPads cannot query the real status 773of the LED indicators. 774 775Because misuse of the LEDs could induce an unaware user to perform 776dangerous actions (like undocking or ejecting a bay device while the 777buses are still active), or mask an important alarm (such as a nearly 778empty battery, or a broken battery), access to most LEDs is 779restricted. 780 781Unrestricted access to all LEDs requires that thinkpad-acpi be 782compiled with the CONFIG_THINKPAD_ACPI_UNSAFE_LEDS option enabled. 783Distributions must never enable this option. Individual users that 784are aware of the consequences are welcome to enabling it. 785 786Audio mute and microphone mute LEDs are supported, but currently not 787visible to userspace. They are used by the snd-hda-intel audio driver. 788 789procfs notes 790^^^^^^^^^^^^ 791 792The available commands are:: 793 794 echo '<LED number> on' >/proc/acpi/ibm/led 795 echo '<LED number> off' >/proc/acpi/ibm/led 796 echo '<LED number> blink' >/proc/acpi/ibm/led 797 798The <LED number> range is 0 to 15. The set of LEDs that can be 799controlled varies from model to model. Here is the common ThinkPad 800mapping: 801 802 - 0 - power 803 - 1 - battery (orange) 804 - 2 - battery (green) 805 - 3 - UltraBase/dock 806 - 4 - UltraBay 807 - 5 - UltraBase battery slot 808 - 6 - (unknown) 809 - 7 - standby 810 - 8 - dock status 1 811 - 9 - dock status 2 812 - 10, 11 - (unknown) 813 - 12 - thinkvantage 814 - 13, 14, 15 - (unknown) 815 816All of the above can be turned on and off and can be made to blink. 817 818sysfs notes 819^^^^^^^^^^^ 820 821The ThinkPad LED sysfs interface is described in detail by the LED class 822documentation, in Documentation/leds/leds-class.rst. 823 824The LEDs are named (in LED ID order, from 0 to 12): 825"tpacpi::power", "tpacpi:orange:batt", "tpacpi:green:batt", 826"tpacpi::dock_active", "tpacpi::bay_active", "tpacpi::dock_batt", 827"tpacpi::unknown_led", "tpacpi::standby", "tpacpi::dock_status1", 828"tpacpi::dock_status2", "tpacpi::unknown_led2", "tpacpi::unknown_led3", 829"tpacpi::thinkvantage". 830 831Due to limitations in the sysfs LED class, if the status of the LED 832indicators cannot be read due to an error, thinkpad-acpi will report it as 833a brightness of zero (same as LED off). 834 835If the thinkpad firmware doesn't support reading the current status, 836trying to read the current LED brightness will just return whatever 837brightness was last written to that attribute. 838 839These LEDs can blink using hardware acceleration. To request that a 840ThinkPad indicator LED should blink in hardware accelerated mode, use the 841"timer" trigger, and leave the delay_on and delay_off parameters set to 842zero (to request hardware acceleration autodetection). 843 844LEDs that are known not to exist in a given ThinkPad model are not 845made available through the sysfs interface. If you have a dock and you 846notice there are LEDs listed for your ThinkPad that do not exist (and 847are not in the dock), or if you notice that there are missing LEDs, 848a report to ibm-acpi-devel@lists.sourceforge.net is appreciated. 849 850 851ACPI sounds -- /proc/acpi/ibm/beep 852---------------------------------- 853 854The BEEP method is used internally by the ACPI firmware to provide 855audible alerts in various situations. This feature allows the same 856sounds to be triggered manually. 857 858The commands are non-negative integer numbers:: 859 860 echo <number> >/proc/acpi/ibm/beep 861 862The valid <number> range is 0 to 17. Not all numbers trigger sounds 863and the sounds vary from model to model. Here is the behavior on the 864X40: 865 866 - 0 - stop a sound in progress (but use 17 to stop 16) 867 - 2 - two beeps, pause, third beep ("low battery") 868 - 3 - single beep 869 - 4 - high, followed by low-pitched beep ("unable") 870 - 5 - single beep 871 - 6 - very high, followed by high-pitched beep ("AC/DC") 872 - 7 - high-pitched beep 873 - 9 - three short beeps 874 - 10 - very long beep 875 - 12 - low-pitched beep 876 - 15 - three high-pitched beeps repeating constantly, stop with 0 877 - 16 - one medium-pitched beep repeating constantly, stop with 17 878 - 17 - stop 16 879 880 881Temperature sensors 882------------------- 883 884procfs: /proc/acpi/ibm/thermal 885 886sysfs device attributes: (hwmon "thinkpad") temp*_input 887 888Most ThinkPads include six or more separate temperature sensors but only 889expose the CPU temperature through the standard ACPI methods. This 890feature shows readings from up to eight different sensors on older 891ThinkPads, and up to sixteen different sensors on newer ThinkPads. 892 893For example, on the X40, a typical output may be: 894 895temperatures: 896 42 42 45 41 36 -128 33 -128 897 898On the T43/p, a typical output may be: 899 900temperatures: 901 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128 902 903The mapping of thermal sensors to physical locations varies depending on 904system-board model (and thus, on ThinkPad model). 905 906http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that 907tries to track down these locations for various models. 908 909Most (newer?) models seem to follow this pattern: 910 911- 1: CPU 912- 2: (depends on model) 913- 3: (depends on model) 914- 4: GPU 915- 5: Main battery: main sensor 916- 6: Bay battery: main sensor 917- 7: Main battery: secondary sensor 918- 8: Bay battery: secondary sensor 919- 9-15: (depends on model) 920 921For the R51 (source: Thomas Gruber): 922 923- 2: Mini-PCI 924- 3: Internal HDD 925 926For the T43, T43/p (source: Shmidoax/Thinkwiki.org) 927http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p 928 929- 2: System board, left side (near PCMCIA slot), reported as HDAPS temp 930- 3: PCMCIA slot 931- 9: MCH (northbridge) to DRAM Bus 932- 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI 933 card, under touchpad 934- 11: Power regulator, underside of system board, below F2 key 935 936The A31 has a very atypical layout for the thermal sensors 937(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) 938 939- 1: CPU 940- 2: Main Battery: main sensor 941- 3: Power Converter 942- 4: Bay Battery: main sensor 943- 5: MCH (northbridge) 944- 6: PCMCIA/ambient 945- 7: Main Battery: secondary sensor 946- 8: Bay Battery: secondary sensor 947 948 949Procfs notes 950^^^^^^^^^^^^ 951 952 Readings from sensors that are not available return -128. 953 No commands can be written to this file. 954 955Sysfs notes 956^^^^^^^^^^^ 957 958 Sensors that are not available return the ENXIO error. This 959 status may change at runtime, as there are hotplug thermal 960 sensors, like those inside the batteries and docks. 961 962 thinkpad-acpi thermal sensors are reported through the hwmon 963 subsystem, and follow all of the hwmon guidelines at 964 Documentation/hwmon. 965 966EXPERIMENTAL: Embedded controller register dump 967----------------------------------------------- 968 969This feature is not included in the thinkpad driver anymore. 970Instead the EC can be accessed through /sys/kernel/debug/ec with 971a userspace tool which can be found here: 972ftp://ftp.suse.com/pub/people/trenn/sources/ec 973 974Use it to determine the register holding the fan 975speed on some models. To do that, do the following: 976 977 - make sure the battery is fully charged 978 - make sure the fan is running 979 - use above mentioned tool to read out the EC 980 981Often fan and temperature values vary between 982readings. Since temperatures don't change vary fast, you can take 983several quick dumps to eliminate them. 984 985You can use a similar method to figure out the meaning of other 986embedded controller registers - e.g. make sure nothing else changes 987except the charging or discharging battery to determine which 988registers contain the current battery capacity, etc. If you experiment 989with this, do send me your results (including some complete dumps with 990a description of the conditions when they were taken.) 991 992 993LCD brightness control 994---------------------- 995 996procfs: /proc/acpi/ibm/brightness 997 998sysfs backlight device "thinkpad_screen" 999 1000This feature allows software control of the LCD brightness on ThinkPad 1001models which don't have a hardware brightness slider. 1002 1003It has some limitations: the LCD backlight cannot be actually turned 1004on or off by this interface, it just controls the backlight brightness 1005level. 1006 1007On IBM (and some of the earlier Lenovo) ThinkPads, the backlight control 1008has eight brightness levels, ranging from 0 to 7. Some of the levels 1009may not be distinct. Later Lenovo models that implement the ACPI 1010display backlight brightness control methods have 16 levels, ranging 1011from 0 to 15. 1012 1013For IBM ThinkPads, there are two interfaces to the firmware for direct 1014brightness control, EC and UCMS (or CMOS). To select which one should be 1015used, use the brightness_mode module parameter: brightness_mode=1 selects 1016EC mode, brightness_mode=2 selects UCMS mode, brightness_mode=3 selects EC 1017mode with NVRAM backing (so that brightness changes are remembered across 1018shutdown/reboot). 1019 1020The driver tries to select which interface to use from a table of 1021defaults for each ThinkPad model. If it makes a wrong choice, please 1022report this as a bug, so that we can fix it. 1023 1024Lenovo ThinkPads only support brightness_mode=2 (UCMS). 1025 1026When display backlight brightness controls are available through the 1027standard ACPI interface, it is best to use it instead of this direct 1028ThinkPad-specific interface. The driver will disable its native 1029backlight brightness control interface if it detects that the standard 1030ACPI interface is available in the ThinkPad. 1031 1032If you want to use the thinkpad-acpi backlight brightness control 1033instead of the generic ACPI video backlight brightness control for some 1034reason, you should use the acpi_backlight=vendor kernel parameter. 1035 1036The brightness_enable module parameter can be used to control whether 1037the LCD brightness control feature will be enabled when available. 1038brightness_enable=0 forces it to be disabled. brightness_enable=1 1039forces it to be enabled when available, even if the standard ACPI 1040interface is also available. 1041 1042Procfs notes 1043^^^^^^^^^^^^ 1044 1045The available commands are:: 1046 1047 echo up >/proc/acpi/ibm/brightness 1048 echo down >/proc/acpi/ibm/brightness 1049 echo 'level <level>' >/proc/acpi/ibm/brightness 1050 1051Sysfs notes 1052^^^^^^^^^^^ 1053 1054The interface is implemented through the backlight sysfs class, which is 1055poorly documented at this time. 1056 1057Locate the thinkpad_screen device under /sys/class/backlight, and inside 1058it there will be the following attributes: 1059 1060 max_brightness: 1061 Reads the maximum brightness the hardware can be set to. 1062 The minimum is always zero. 1063 1064 actual_brightness: 1065 Reads what brightness the screen is set to at this instant. 1066 1067 brightness: 1068 Writes request the driver to change brightness to the 1069 given value. Reads will tell you what brightness the 1070 driver is trying to set the display to when "power" is set 1071 to zero and the display has not been dimmed by a kernel 1072 power management event. 1073 1074 power: 1075 power management mode, where 0 is "display on", and 1 to 3 1076 will dim the display backlight to brightness level 0 1077 because thinkpad-acpi cannot really turn the backlight 1078 off. Kernel power management events can temporarily 1079 increase the current power management level, i.e. they can 1080 dim the display. 1081 1082 1083WARNING: 1084 1085 Whatever you do, do NOT ever call thinkpad-acpi backlight-level change 1086 interface and the ACPI-based backlight level change interface 1087 (available on newer BIOSes, and driven by the Linux ACPI video driver) 1088 at the same time. The two will interact in bad ways, do funny things, 1089 and maybe reduce the life of the backlight lamps by needlessly kicking 1090 its level up and down at every change. 1091 1092 1093Volume control (Console Audio control) 1094-------------------------------------- 1095 1096procfs: /proc/acpi/ibm/volume 1097 1098ALSA: "ThinkPad Console Audio Control", default ID: "ThinkPadEC" 1099 1100NOTE: by default, the volume control interface operates in read-only 1101mode, as it is supposed to be used for on-screen-display purposes. 1102The read/write mode can be enabled through the use of the 1103"volume_control=1" module parameter. 1104 1105NOTE: distros are urged to not enable volume_control by default, this 1106should be done by the local admin only. The ThinkPad UI is for the 1107console audio control to be done through the volume keys only, and for 1108the desktop environment to just provide on-screen-display feedback. 1109Software volume control should be done only in the main AC97/HDA 1110mixer. 1111 1112 1113About the ThinkPad Console Audio control 1114^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1115 1116ThinkPads have a built-in amplifier and muting circuit that drives the 1117console headphone and speakers. This circuit is after the main AC97 1118or HDA mixer in the audio path, and under exclusive control of the 1119firmware. 1120 1121ThinkPads have three special hotkeys to interact with the console 1122audio control: volume up, volume down and mute. 1123 1124It is worth noting that the normal way the mute function works (on 1125ThinkPads that do not have a "mute LED") is: 1126 11271. Press mute to mute. It will *always* mute, you can press it as 1128 many times as you want, and the sound will remain mute. 1129 11302. Press either volume key to unmute the ThinkPad (it will _not_ 1131 change the volume, it will just unmute). 1132 1133This is a very superior design when compared to the cheap software-only 1134mute-toggle solution found on normal consumer laptops: you can be 1135absolutely sure the ThinkPad will not make noise if you press the mute 1136button, no matter the previous state. 1137 1138The IBM ThinkPads, and the earlier Lenovo ThinkPads have variable-gain 1139amplifiers driving the speakers and headphone output, and the firmware 1140also handles volume control for the headphone and speakers on these 1141ThinkPads without any help from the operating system (this volume 1142control stage exists after the main AC97 or HDA mixer in the audio 1143path). 1144 1145The newer Lenovo models only have firmware mute control, and depend on 1146the main HDA mixer to do volume control (which is done by the operating 1147system). In this case, the volume keys are filtered out for unmute 1148key press (there are some firmware bugs in this area) and delivered as 1149normal key presses to the operating system (thinkpad-acpi is not 1150involved). 1151 1152 1153The ThinkPad-ACPI volume control 1154^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1155 1156The preferred way to interact with the Console Audio control is the 1157ALSA interface. 1158 1159The legacy procfs interface allows one to read the current state, 1160and if volume control is enabled, accepts the following commands:: 1161 1162 echo up >/proc/acpi/ibm/volume 1163 echo down >/proc/acpi/ibm/volume 1164 echo mute >/proc/acpi/ibm/volume 1165 echo unmute >/proc/acpi/ibm/volume 1166 echo 'level <level>' >/proc/acpi/ibm/volume 1167 1168The <level> number range is 0 to 14 although not all of them may be 1169distinct. To unmute the volume after the mute command, use either the 1170up or down command (the level command will not unmute the volume), or 1171the unmute command. 1172 1173You can use the volume_capabilities parameter to tell the driver 1174whether your thinkpad has volume control or mute-only control: 1175volume_capabilities=1 for mixers with mute and volume control, 1176volume_capabilities=2 for mixers with only mute control. 1177 1178If the driver misdetects the capabilities for your ThinkPad model, 1179please report this to ibm-acpi-devel@lists.sourceforge.net, so that we 1180can update the driver. 1181 1182There are two strategies for volume control. To select which one 1183should be used, use the volume_mode module parameter: volume_mode=1 1184selects EC mode, and volume_mode=3 selects EC mode with NVRAM backing 1185(so that volume/mute changes are remembered across shutdown/reboot). 1186 1187The driver will operate in volume_mode=3 by default. If that does not 1188work well on your ThinkPad model, please report this to 1189ibm-acpi-devel@lists.sourceforge.net. 1190 1191The driver supports the standard ALSA module parameters. If the ALSA 1192mixer is disabled, the driver will disable all volume functionality. 1193 1194 1195Fan control and monitoring: fan speed, fan enable/disable 1196--------------------------------------------------------- 1197 1198procfs: /proc/acpi/ibm/fan 1199 1200sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1, pwm1_enable, fan2_input 1201 1202sysfs hwmon driver attributes: fan_watchdog 1203 1204NOTE NOTE NOTE: 1205 fan control operations are disabled by default for 1206 safety reasons. To enable them, the module parameter "fan_control=1" 1207 must be given to thinkpad-acpi. 1208 1209This feature attempts to show the current fan speed, control mode and 1210other fan data that might be available. The speed is read directly 1211from the hardware registers of the embedded controller. This is known 1212to work on later R, T, X and Z series ThinkPads but may show a bogus 1213value on other models. 1214 1215Some Lenovo ThinkPads support a secondary fan. This fan cannot be 1216controlled separately, it shares the main fan control. 1217 1218Fan levels 1219^^^^^^^^^^ 1220 1221Most ThinkPad fans work in "levels" at the firmware interface. Level 0 1222stops the fan. The higher the level, the higher the fan speed, although 1223adjacent levels often map to the same fan speed. 7 is the highest 1224level, where the fan reaches the maximum recommended speed. 1225 1226Level "auto" means the EC changes the fan level according to some 1227internal algorithm, usually based on readings from the thermal sensors. 1228 1229There is also a "full-speed" level, also known as "disengaged" level. 1230In this level, the EC disables the speed-locked closed-loop fan control, 1231and drives the fan as fast as it can go, which might exceed hardware 1232limits, so use this level with caution. 1233 1234The fan usually ramps up or down slowly from one speed to another, and 1235it is normal for the EC to take several seconds to react to fan 1236commands. The full-speed level may take up to two minutes to ramp up to 1237maximum speed, and in some ThinkPads, the tachometer readings go stale 1238while the EC is transitioning to the full-speed level. 1239 1240WARNING WARNING WARNING: do not leave the fan disabled unless you are 1241monitoring all of the temperature sensor readings and you are ready to 1242enable it if necessary to avoid overheating. 1243 1244An enabled fan in level "auto" may stop spinning if the EC decides the 1245ThinkPad is cool enough and doesn't need the extra airflow. This is 1246normal, and the EC will spin the fan up if the various thermal readings 1247rise too much. 1248 1249On the X40, this seems to depend on the CPU and HDD temperatures. 1250Specifically, the fan is turned on when either the CPU temperature 1251climbs to 56 degrees or the HDD temperature climbs to 46 degrees. The 1252fan is turned off when the CPU temperature drops to 49 degrees and the 1253HDD temperature drops to 41 degrees. These thresholds cannot 1254currently be controlled. 1255 1256The ThinkPad's ACPI DSDT code will reprogram the fan on its own when 1257certain conditions are met. It will override any fan programming done 1258through thinkpad-acpi. 1259 1260The thinkpad-acpi kernel driver can be programmed to revert the fan 1261level to a safe setting if userspace does not issue one of the procfs 1262fan commands: "enable", "disable", "level" or "watchdog", or if there 1263are no writes to pwm1_enable (or to pwm1 *if and only if* pwm1_enable is 1264set to 1, manual mode) within a configurable amount of time of up to 1265120 seconds. This functionality is called fan safety watchdog. 1266 1267Note that the watchdog timer stops after it enables the fan. It will be 1268rearmed again automatically (using the same interval) when one of the 1269above mentioned fan commands is received. The fan watchdog is, 1270therefore, not suitable to protect against fan mode changes made through 1271means other than the "enable", "disable", and "level" procfs fan 1272commands, or the hwmon fan control sysfs interface. 1273 1274Procfs notes 1275^^^^^^^^^^^^ 1276 1277The fan may be enabled or disabled with the following commands:: 1278 1279 echo enable >/proc/acpi/ibm/fan 1280 echo disable >/proc/acpi/ibm/fan 1281 1282Placing a fan on level 0 is the same as disabling it. Enabling a fan 1283will try to place it in a safe level if it is too slow or disabled. 1284 1285The fan level can be controlled with the command:: 1286 1287 echo 'level <level>' > /proc/acpi/ibm/fan 1288 1289Where <level> is an integer from 0 to 7, or one of the words "auto" or 1290"full-speed" (without the quotes). Not all ThinkPads support the "auto" 1291and "full-speed" levels. The driver accepts "disengaged" as an alias for 1292"full-speed", and reports it as "disengaged" for backwards 1293compatibility. 1294 1295On the X31 and X40 (and ONLY on those models), the fan speed can be 1296controlled to a certain degree. Once the fan is running, it can be 1297forced to run faster or slower with the following command:: 1298 1299 echo 'speed <speed>' > /proc/acpi/ibm/fan 1300 1301The sustainable range of fan speeds on the X40 appears to be from about 13023700 to about 7350. Values outside this range either do not have any 1303effect or the fan speed eventually settles somewhere in that range. The 1304fan cannot be stopped or started with this command. This functionality 1305is incomplete, and not available through the sysfs interface. 1306 1307To program the safety watchdog, use the "watchdog" command:: 1308 1309 echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan 1310 1311If you want to disable the watchdog, use 0 as the interval. 1312 1313Sysfs notes 1314^^^^^^^^^^^ 1315 1316The sysfs interface follows the hwmon subsystem guidelines for the most 1317part, and the exception is the fan safety watchdog. 1318 1319Writes to any of the sysfs attributes may return the EINVAL error if 1320that operation is not supported in a given ThinkPad or if the parameter 1321is out-of-bounds, and EPERM if it is forbidden. They may also return 1322EINTR (interrupted system call), and EIO (I/O error while trying to talk 1323to the firmware). 1324 1325Features not yet implemented by the driver return ENOSYS. 1326 1327hwmon device attribute pwm1_enable: 1328 - 0: PWM offline (fan is set to full-speed mode) 1329 - 1: Manual PWM control (use pwm1 to set fan level) 1330 - 2: Hardware PWM control (EC "auto" mode) 1331 - 3: reserved (Software PWM control, not implemented yet) 1332 1333 Modes 0 and 2 are not supported by all ThinkPads, and the 1334 driver is not always able to detect this. If it does know a 1335 mode is unsupported, it will return -EINVAL. 1336 1337hwmon device attribute pwm1: 1338 Fan level, scaled from the firmware values of 0-7 to the hwmon 1339 scale of 0-255. 0 means fan stopped, 255 means highest normal 1340 speed (level 7). 1341 1342 This attribute only commands the fan if pmw1_enable is set to 1 1343 (manual PWM control). 1344 1345hwmon device attribute fan1_input: 1346 Fan tachometer reading, in RPM. May go stale on certain 1347 ThinkPads while the EC transitions the PWM to offline mode, 1348 which can take up to two minutes. May return rubbish on older 1349 ThinkPads. 1350 1351hwmon device attribute fan2_input: 1352 Fan tachometer reading, in RPM, for the secondary fan. 1353 Available only on some ThinkPads. If the secondary fan is 1354 not installed, will always read 0. 1355 1356hwmon driver attribute fan_watchdog: 1357 Fan safety watchdog timer interval, in seconds. Minimum is 1358 1 second, maximum is 120 seconds. 0 disables the watchdog. 1359 1360To stop the fan: set pwm1 to zero, and pwm1_enable to 1. 1361 1362To start the fan in a safe mode: set pwm1_enable to 2. If that fails 1363with EINVAL, try to set pwm1_enable to 1 and pwm1 to at least 128 (255 1364would be the safest choice, though). 1365 1366 1367WAN 1368--- 1369 1370procfs: /proc/acpi/ibm/wan 1371 1372sysfs device attribute: wwan_enable (deprecated) 1373 1374sysfs rfkill class: switch "tpacpi_wwan_sw" 1375 1376This feature shows the presence and current state of the built-in 1377Wireless WAN device. 1378 1379If the ThinkPad supports it, the WWAN state is stored in NVRAM, 1380so it is kept across reboots and power-off. 1381 1382It was tested on a Lenovo ThinkPad X60. It should probably work on other 1383ThinkPad models which come with this module installed. 1384 1385Procfs notes 1386^^^^^^^^^^^^ 1387 1388If the W-WAN card is installed, the following commands can be used:: 1389 1390 echo enable > /proc/acpi/ibm/wan 1391 echo disable > /proc/acpi/ibm/wan 1392 1393Sysfs notes 1394^^^^^^^^^^^ 1395 1396 If the W-WAN card is installed, it can be enabled / 1397 disabled through the "wwan_enable" thinkpad-acpi device 1398 attribute, and its current status can also be queried. 1399 1400 enable: 1401 - 0: disables WWAN card / WWAN card is disabled 1402 - 1: enables WWAN card / WWAN card is enabled. 1403 1404 Note: this interface has been superseded by the generic rfkill 1405 class. It has been deprecated, and it will be removed in year 1406 2010. 1407 1408 rfkill controller switch "tpacpi_wwan_sw": refer to 1409 Documentation/driver-api/rfkill.rst for details. 1410 1411 1412EXPERIMENTAL: UWB 1413----------------- 1414 1415This feature is considered EXPERIMENTAL because it has not been extensively 1416tested and validated in various ThinkPad models yet. The feature may not 1417work as expected. USE WITH CAUTION! To use this feature, you need to supply 1418the experimental=1 parameter when loading the module. 1419 1420sysfs rfkill class: switch "tpacpi_uwb_sw" 1421 1422This feature exports an rfkill controller for the UWB device, if one is 1423present and enabled in the BIOS. 1424 1425Sysfs notes 1426^^^^^^^^^^^ 1427 1428 rfkill controller switch "tpacpi_uwb_sw": refer to 1429 Documentation/driver-api/rfkill.rst for details. 1430 1431Adaptive keyboard 1432----------------- 1433 1434sysfs device attribute: adaptive_kbd_mode 1435 1436This sysfs attribute controls the keyboard "face" that will be shown on the 1437Lenovo X1 Carbon 2nd gen (2014)'s adaptive keyboard. The value can be read 1438and set. 1439 1440- 1 = Home mode 1441- 2 = Web-browser mode 1442- 3 = Web-conference mode 1443- 4 = Function mode 1444- 5 = Layflat mode 1445 1446For more details about which buttons will appear depending on the mode, please 1447review the laptop's user guide: 1448http://www.lenovo.com/shop/americas/content/user_guides/x1carbon_2_ug_en.pdf 1449 1450Multiple Commands, Module Parameters 1451------------------------------------ 1452 1453Multiple commands can be written to the proc files in one shot by 1454separating them with commas, for example:: 1455 1456 echo enable,0xffff > /proc/acpi/ibm/hotkey 1457 echo lcd_disable,crt_enable > /proc/acpi/ibm/video 1458 1459Commands can also be specified when loading the thinkpad-acpi module, 1460for example:: 1461 1462 modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable 1463 1464 1465Enabling debugging output 1466------------------------- 1467 1468The module takes a debug parameter which can be used to selectively 1469enable various classes of debugging output, for example:: 1470 1471 modprobe thinkpad_acpi debug=0xffff 1472 1473will enable all debugging output classes. It takes a bitmask, so 1474to enable more than one output class, just add their values. 1475 1476 ============= ====================================== 1477 Debug bitmask Description 1478 ============= ====================================== 1479 0x8000 Disclose PID of userspace programs 1480 accessing some functions of the driver 1481 0x0001 Initialization and probing 1482 0x0002 Removal 1483 0x0004 RF Transmitter control (RFKILL) 1484 (bluetooth, WWAN, UWB...) 1485 0x0008 HKEY event interface, hotkeys 1486 0x0010 Fan control 1487 0x0020 Backlight brightness 1488 0x0040 Audio mixer/volume control 1489 ============= ====================================== 1490 1491There is also a kernel build option to enable more debugging 1492information, which may be necessary to debug driver problems. 1493 1494The level of debugging information output by the driver can be changed 1495at runtime through sysfs, using the driver attribute debug_level. The 1496attribute takes the same bitmask as the debug module parameter above. 1497 1498 1499Force loading of module 1500----------------------- 1501 1502If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify 1503the module parameter force_load=1. Regardless of whether this works or 1504not, please contact ibm-acpi-devel@lists.sourceforge.net with a report. 1505 1506 1507Sysfs interface changelog 1508^^^^^^^^^^^^^^^^^^^^^^^^^ 1509 1510========= =============================================================== 15110x000100: Initial sysfs support, as a single platform driver and 1512 device. 15130x000200: Hot key support for 32 hot keys, and radio slider switch 1514 support. 15150x010000: Hot keys are now handled by default over the input 1516 layer, the radio switch generates input event EV_RADIO, 1517 and the driver enables hot key handling by default in 1518 the firmware. 1519 15200x020000: ABI fix: added a separate hwmon platform device and 1521 driver, which must be located by name (thinkpad) 1522 and the hwmon class for libsensors4 (lm-sensors 3) 1523 compatibility. Moved all hwmon attributes to this 1524 new platform device. 1525 15260x020100: Marker for thinkpad-acpi with hot key NVRAM polling 1527 support. If you must, use it to know you should not 1528 start a userspace NVRAM poller (allows to detect when 1529 NVRAM is compiled out by the user because it is 1530 unneeded/undesired in the first place). 15310x020101: Marker for thinkpad-acpi with hot key NVRAM polling 1532 and proper hotkey_mask semantics (version 8 of the 1533 NVRAM polling patch). Some development snapshots of 1534 0.18 had an earlier version that did strange things 1535 to hotkey_mask. 1536 15370x020200: Add poll()/select() support to the following attributes: 1538 hotkey_radio_sw, wakeup_hotunplug_complete, wakeup_reason 1539 15400x020300: hotkey enable/disable support removed, attributes 1541 hotkey_bios_enabled and hotkey_enable deprecated and 1542 marked for removal. 1543 15440x020400: Marker for 16 LEDs support. Also, LEDs that are known 1545 to not exist in a given model are not registered with 1546 the LED sysfs class anymore. 1547 15480x020500: Updated hotkey driver, hotkey_mask is always available 1549 and it is always able to disable hot keys. Very old 1550 thinkpads are properly supported. hotkey_bios_mask 1551 is deprecated and marked for removal. 1552 15530x020600: Marker for backlight change event support. 1554 15550x020700: Support for mute-only mixers. 1556 Volume control in read-only mode by default. 1557 Marker for ALSA mixer support. 1558 15590x030000: Thermal and fan sysfs attributes were moved to the hwmon 1560 device instead of being attached to the backing platform 1561 device. 1562========= =============================================================== 1563