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