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