0001 ===========================
0002 ThinkPad ACPI Extras Driver
0003 ===========================
0004
0005 Version 0.25
0006
0007 October 16th, 2013
0008
0009 - Borislav Deianov <borislav@users.sf.net>
0010 - Henrique de Moraes Holschuh <hmh@hmh.eng.br>
0011
0012 http://ibm-acpi.sf.net/
0013
0014 This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
0015 supports various features of these laptops which are accessible
0016 through the ACPI and ACPI EC framework, but not otherwise fully
0017 supported by the generic Linux ACPI drivers.
0018
0019 This driver used to be named ibm-acpi until kernel 2.6.21 and release
0020 0.13-20070314. It used to be in the drivers/acpi tree, but it was
0021 moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel
0022 2.6.22, and release 0.14. It was moved to drivers/platform/x86 for
0023 kernel 2.6.29 and release 0.22.
0024
0025 The driver is named "thinkpad-acpi". In some places, like module
0026 names and log messages, "thinkpad_acpi" is used because of userspace
0027 issues.
0028
0029 "tpacpi" is used as a shorthand where "thinkpad-acpi" would be too
0030 long due to length limitations on some Linux kernel versions.
0031
0032 Status
0033 ------
0034
0035 The features currently supported are the following (see below for
0036 detailed description):
0037
0038 - Fn key combinations
0039 - Bluetooth enable and disable
0040 - video output switching, expansion control
0041 - ThinkLight on and off
0042 - CMOS/UCMS control
0043 - LED control
0044 - ACPI sounds
0045 - temperature sensors
0046 - Experimental: embedded controller register dump
0047 - LCD brightness control
0048 - Volume control
0049 - Fan control and monitoring: fan speed, fan enable/disable
0050 - WAN enable and disable
0051 - UWB enable and disable
0052 - LCD Shadow (PrivacyGuard) enable and disable
0053 - Lap mode sensor
0054 - Setting keyboard language
0055 - WWAN Antenna type
0056
0057 A compatibility table by model and feature is maintained on the web
0058 site, http://ibm-acpi.sf.net/. I appreciate any success or failure
0059 reports, especially if they add to or correct the compatibility table.
0060 Please include the following information in your report:
0061
0062 - ThinkPad model name
0063 - a copy of your ACPI tables, using the "acpidump" utility
0064 - a copy of the output of dmidecode, with serial numbers
0065 and UUIDs masked off
0066 - which driver features work and which don't
0067 - the observed behavior of non-working features
0068
0069 Any other comments or patches are also more than welcome.
0070
0071
0072 Installation
0073 ------------
0074
0075 If you are compiling this driver as included in the Linux kernel
0076 sources, look for the CONFIG_THINKPAD_ACPI Kconfig option.
0077 It is located on the menu path: "Device Drivers" -> "X86 Platform
0078 Specific Device Drivers" -> "ThinkPad ACPI Laptop Extras".
0079
0080
0081 Features
0082 --------
0083
0084 The driver exports two different interfaces to userspace, which can be
0085 used to access the features it provides. One is a legacy procfs-based
0086 interface, which will be removed at some time in the future. The other
0087 is a new sysfs-based interface which is not complete yet.
0088
0089 The procfs interface creates the /proc/acpi/ibm directory. There is a
0090 file under that directory for each feature it supports. The procfs
0091 interface is mostly frozen, and will change very little if at all: it
0092 will not be extended to add any new functionality in the driver, instead
0093 all new functionality will be implemented on the sysfs interface.
0094
0095 The sysfs interface tries to blend in the generic Linux sysfs subsystems
0096 and classes as much as possible. Since some of these subsystems are not
0097 yet ready or stabilized, it is expected that this interface will change,
0098 and any and all userspace programs must deal with it.
0099
0100
0101 Notes about the sysfs interface
0102 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0103
0104 Unlike what was done with the procfs interface, correctness when talking
0105 to the sysfs interfaces will be enforced, as will correctness in the
0106 thinkpad-acpi's implementation of sysfs interfaces.
0107
0108 Also, any bugs in the thinkpad-acpi sysfs driver code or in the
0109 thinkpad-acpi's implementation of the sysfs interfaces will be fixed for
0110 maximum correctness, even if that means changing an interface in
0111 non-compatible ways. As these interfaces mature both in the kernel and
0112 in thinkpad-acpi, such changes should become quite rare.
0113
0114 Applications interfacing to the thinkpad-acpi sysfs interfaces must
0115 follow all sysfs guidelines and correctly process all errors (the sysfs
0116 interface makes extensive use of errors). File descriptors and open /
0117 close operations to the sysfs inodes must also be properly implemented.
0118
0119 The version of thinkpad-acpi's sysfs interface is exported by the driver
0120 as a driver attribute (see below).
0121
0122 Sysfs driver attributes are on the driver's sysfs attribute space,
0123 for 2.6.23+ this is /sys/bus/platform/drivers/thinkpad_acpi/ and
0124 /sys/bus/platform/drivers/thinkpad_hwmon/
0125
0126 Sysfs device attributes are on the thinkpad_acpi device sysfs attribute
0127 space, for 2.6.23+ this is /sys/devices/platform/thinkpad_acpi/.
0128
0129 Sysfs device attributes for the sensors and fan are on the
0130 thinkpad_hwmon device's sysfs attribute space, but you should locate it
0131 looking for a hwmon device with the name attribute of "thinkpad", or
0132 better yet, through libsensors. For 4.14+ sysfs attributes were moved to the
0133 hwmon device (/sys/bus/platform/devices/thinkpad_hwmon/hwmon/hwmon? or
0134 /sys/class/hwmon/hwmon?).
0135
0136 Driver version
0137 --------------
0138
0139 procfs: /proc/acpi/ibm/driver
0140
0141 sysfs driver attribute: version
0142
0143 The driver name and version. No commands can be written to this file.
0144
0145
0146 Sysfs interface version
0147 -----------------------
0148
0149 sysfs driver attribute: interface_version
0150
0151 Version of the thinkpad-acpi sysfs interface, as an unsigned long
0152 (output in hex format: 0xAAAABBCC), where:
0153
0154 AAAA
0155 - major revision
0156 BB
0157 - minor revision
0158 CC
0159 - bugfix revision
0160
0161 The sysfs interface version changelog for the driver can be found at the
0162 end of this document. Changes to the sysfs interface done by the kernel
0163 subsystems are not documented here, nor are they tracked by this
0164 attribute.
0165
0166 Changes to the thinkpad-acpi sysfs interface are only considered
0167 non-experimental when they are submitted to Linux mainline, at which
0168 point the changes in this interface are documented and interface_version
0169 may be updated. If you are using any thinkpad-acpi features not yet
0170 sent to mainline for merging, you do so on your own risk: these features
0171 may disappear, or be implemented in a different and incompatible way by
0172 the time they are merged in Linux mainline.
0173
0174 Changes that are backwards-compatible by nature (e.g. the addition of
0175 attributes that do not change the way the other attributes work) do not
0176 always warrant an update of interface_version. Therefore, one must
0177 expect that an attribute might not be there, and deal with it properly
0178 (an attribute not being there *is* a valid way to make it clear that a
0179 feature is not available in sysfs).
0180
0181
0182 Hot keys
0183 --------
0184
0185 procfs: /proc/acpi/ibm/hotkey
0186
0187 sysfs device attribute: hotkey_*
0188
0189 In a ThinkPad, the ACPI HKEY handler is responsible for communicating
0190 some important events and also keyboard hot key presses to the operating
0191 system. Enabling the hotkey functionality of thinkpad-acpi signals the
0192 firmware that such a driver is present, and modifies how the ThinkPad
0193 firmware will behave in many situations.
0194
0195 The driver enables the HKEY ("hot key") event reporting automatically
0196 when loaded, and disables it when it is removed.
0197
0198 The driver will report HKEY events in the following format::
0199
0200 ibm/hotkey HKEY 00000080 0000xxxx
0201
0202 Some of these events refer to hot key presses, but not all of them.
0203
0204 The driver will generate events over the input layer for hot keys and
0205 radio switches, and over the ACPI netlink layer for other events. The
0206 input layer support accepts the standard IOCTLs to remap the keycodes
0207 assigned to each hot key.
0208
0209 The hot key bit mask allows some control over which hot keys generate
0210 events. If a key is "masked" (bit set to 0 in the mask), the firmware
0211 will handle it. If it is "unmasked", it signals the firmware that
0212 thinkpad-acpi would prefer to handle it, if the firmware would be so
0213 kind to allow it (and it often doesn't!).
0214
0215 Not all bits in the mask can be modified. Not all bits that can be
0216 modified do anything. Not all hot keys can be individually controlled
0217 by the mask. Some models do not support the mask at all. The behaviour
0218 of the mask is, therefore, highly dependent on the ThinkPad model.
0219
0220 The driver will filter out any unmasked hotkeys, so even if the firmware
0221 doesn't allow disabling an specific hotkey, the driver will not report
0222 events for unmasked hotkeys.
0223
0224 Note that unmasking some keys prevents their default behavior. For
0225 example, if Fn+F5 is unmasked, that key will no longer enable/disable
0226 Bluetooth by itself in firmware.
0227
0228 Note also that not all Fn key combinations are supported through ACPI
0229 depending on the ThinkPad model and firmware version. On those
0230 ThinkPads, it is still possible to support some extra hotkeys by
0231 polling the "CMOS NVRAM" at least 10 times per second. The driver
0232 attempts to enables this functionality automatically when required.
0233
0234 procfs notes
0235 ^^^^^^^^^^^^
0236
0237 The following commands can be written to the /proc/acpi/ibm/hotkey file::
0238
0239 echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
0240 echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
0241 ... any other 8-hex-digit mask ...
0242 echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
0243
0244 The following commands have been deprecated and will cause the kernel
0245 to log a warning::
0246
0247 echo enable > /proc/acpi/ibm/hotkey -- does nothing
0248 echo disable > /proc/acpi/ibm/hotkey -- returns an error
0249
0250 The procfs interface does not support NVRAM polling control. So as to
0251 maintain maximum bug-to-bug compatibility, it does not report any masks,
0252 nor does it allow one to manipulate the hot key mask when the firmware
0253 does not support masks at all, even if NVRAM polling is in use.
0254
0255 sysfs notes
0256 ^^^^^^^^^^^
0257
0258 hotkey_bios_enabled:
0259 DEPRECATED, WILL BE REMOVED SOON.
0260
0261 Returns 0.
0262
0263 hotkey_bios_mask:
0264 DEPRECATED, DON'T USE, WILL BE REMOVED IN THE FUTURE.
0265
0266 Returns the hot keys mask when thinkpad-acpi was loaded.
0267 Upon module unload, the hot keys mask will be restored
0268 to this value. This is always 0x80c, because those are
0269 the hotkeys that were supported by ancient firmware
0270 without mask support.
0271
0272 hotkey_enable:
0273 DEPRECATED, WILL BE REMOVED SOON.
0274
0275 0: returns -EPERM
0276 1: does nothing
0277
0278 hotkey_mask:
0279 bit mask to enable reporting (and depending on
0280 the firmware, ACPI event generation) for each hot key
0281 (see above). Returns the current status of the hot keys
0282 mask, and allows one to modify it.
0283
0284 hotkey_all_mask:
0285 bit mask that should enable event reporting for all
0286 supported hot keys, when echoed to hotkey_mask above.
0287 Unless you know which events need to be handled
0288 passively (because the firmware *will* handle them
0289 anyway), do *not* use hotkey_all_mask. Use
0290 hotkey_recommended_mask, instead. You have been warned.
0291
0292 hotkey_recommended_mask:
0293 bit mask that should enable event reporting for all
0294 supported hot keys, except those which are always
0295 handled by the firmware anyway. Echo it to
0296 hotkey_mask above, to use. This is the default mask
0297 used by the driver.
0298
0299 hotkey_source_mask:
0300 bit mask that selects which hot keys will the driver
0301 poll the NVRAM for. This is auto-detected by the driver
0302 based on the capabilities reported by the ACPI firmware,
0303 but it can be overridden at runtime.
0304
0305 Hot keys whose bits are set in hotkey_source_mask are
0306 polled for in NVRAM, and reported as hotkey events if
0307 enabled in hotkey_mask. Only a few hot keys are
0308 available through CMOS NVRAM polling.
0309
0310 Warning: when in NVRAM mode, the volume up/down/mute
0311 keys are synthesized according to changes in the mixer,
0312 which uses a single volume up or volume down hotkey
0313 press to unmute, as per the ThinkPad volume mixer user
0314 interface. When in ACPI event mode, volume up/down/mute
0315 events are reported by the firmware and can behave
0316 differently (and that behaviour changes with firmware
0317 version -- not just with firmware models -- as well as
0318 OSI(Linux) state).
0319
0320 hotkey_poll_freq:
0321 frequency in Hz for hot key polling. It must be between
0322 0 and 25 Hz. Polling is only carried out when strictly
0323 needed.
0324
0325 Setting hotkey_poll_freq to zero disables polling, and
0326 will cause hot key presses that require NVRAM polling
0327 to never be reported.
0328
0329 Setting hotkey_poll_freq too low may cause repeated
0330 pressings of the same hot key to be misreported as a
0331 single key press, or to not even be detected at all.
0332 The recommended polling frequency is 10Hz.
0333
0334 hotkey_radio_sw:
0335 If the ThinkPad has a hardware radio switch, this
0336 attribute will read 0 if the switch is in the "radios
0337 disabled" position, and 1 if the switch is in the
0338 "radios enabled" position.
0339
0340 This attribute has poll()/select() support.
0341
0342 hotkey_tablet_mode:
0343 If the ThinkPad has tablet capabilities, this attribute
0344 will read 0 if the ThinkPad is in normal mode, and
0345 1 if the ThinkPad is in tablet mode.
0346
0347 This attribute has poll()/select() support.
0348
0349 wakeup_reason:
0350 Set to 1 if the system is waking up because the user
0351 requested a bay ejection. Set to 2 if the system is
0352 waking up because the user requested the system to
0353 undock. Set to zero for normal wake-ups or wake-ups
0354 due to unknown reasons.
0355
0356 This attribute has poll()/select() support.
0357
0358 wakeup_hotunplug_complete:
0359 Set to 1 if the system was waken up because of an
0360 undock or bay ejection request, and that request
0361 was successfully completed. At this point, it might
0362 be useful to send the system back to sleep, at the
0363 user's choice. Refer to HKEY events 0x4003 and
0364 0x3003, below.
0365
0366 This attribute has poll()/select() support.
0367
0368 input layer notes
0369 ^^^^^^^^^^^^^^^^^
0370
0371 A Hot key is mapped to a single input layer EV_KEY event, possibly
0372 followed by an EV_MSC MSC_SCAN event that shall contain that key's scan
0373 code. An EV_SYN event will always be generated to mark the end of the
0374 event block.
0375
0376 Do not use the EV_MSC MSC_SCAN events to process keys. They are to be
0377 used as a helper to remap keys, only. They are particularly useful when
0378 remapping KEY_UNKNOWN keys.
0379
0380 The events are available in an input device, with the following id:
0381
0382 ============== ==============================
0383 Bus BUS_HOST
0384 vendor 0x1014 (PCI_VENDOR_ID_IBM) or
0385 0x17aa (PCI_VENDOR_ID_LENOVO)
0386 product 0x5054 ("TP")
0387 version 0x4101
0388 ============== ==============================
0389
0390 The version will have its LSB incremented if the keymap changes in a
0391 backwards-compatible way. The MSB shall always be 0x41 for this input
0392 device. If the MSB is not 0x41, do not use the device as described in
0393 this section, as it is either something else (e.g. another input device
0394 exported by a thinkpad driver, such as HDAPS) or its functionality has
0395 been changed in a non-backwards compatible way.
0396
0397 Adding other event types for other functionalities shall be considered a
0398 backwards-compatible change for this input device.
0399
0400 Thinkpad-acpi Hot Key event map (version 0x4101):
0401
0402 ======= ======= ============== ==============================================
0403 ACPI Scan
0404 event code Key Notes
0405 ======= ======= ============== ==============================================
0406 0x1001 0x00 FN+F1 -
0407
0408 0x1002 0x01 FN+F2 IBM: battery (rare)
0409 Lenovo: Screen lock
0410
0411 0x1003 0x02 FN+F3 Many IBM models always report
0412 this hot key, even with hot keys
0413 disabled or with Fn+F3 masked
0414 off
0415 IBM: screen lock, often turns
0416 off the ThinkLight as side-effect
0417 Lenovo: battery
0418
0419 0x1004 0x03 FN+F4 Sleep button (ACPI sleep button
0420 semantics, i.e. sleep-to-RAM).
0421 It always generates some kind
0422 of event, either the hot key
0423 event or an ACPI sleep button
0424 event. The firmware may
0425 refuse to generate further FN+F4
0426 key presses until a S3 or S4 ACPI
0427 sleep cycle is performed or some
0428 time passes.
0429
0430 0x1005 0x04 FN+F5 Radio. Enables/disables
0431 the internal Bluetooth hardware
0432 and W-WAN card if left in control
0433 of the firmware. Does not affect
0434 the WLAN card.
0435 Should be used to turn on/off all
0436 radios (Bluetooth+W-WAN+WLAN),
0437 really.
0438
0439 0x1006 0x05 FN+F6 -
0440
0441 0x1007 0x06 FN+F7 Video output cycle.
0442 Do you feel lucky today?
0443
0444 0x1008 0x07 FN+F8 IBM: toggle screen expand
0445 Lenovo: configure UltraNav,
0446 or toggle screen expand
0447
0448 0x1009 0x08 FN+F9 -
0449
0450 ... ... ... ...
0451
0452 0x100B 0x0A FN+F11 -
0453
0454 0x100C 0x0B FN+F12 Sleep to disk. You are always
0455 supposed to handle it yourself,
0456 either through the ACPI event,
0457 or through a hotkey event.
0458 The firmware may refuse to
0459 generate further FN+F12 key
0460 press events until a S3 or S4
0461 ACPI sleep cycle is performed,
0462 or some time passes.
0463
0464 0x100D 0x0C FN+BACKSPACE -
0465 0x100E 0x0D FN+INSERT -
0466 0x100F 0x0E FN+DELETE -
0467
0468 0x1010 0x0F FN+HOME Brightness up. This key is
0469 always handled by the firmware
0470 in IBM ThinkPads, even when
0471 unmasked. Just leave it alone.
0472 For Lenovo ThinkPads with a new
0473 BIOS, it has to be handled either
0474 by the ACPI OSI, or by userspace.
0475 The driver does the right thing,
0476 never mess with this.
0477 0x1011 0x10 FN+END Brightness down. See brightness
0478 up for details.
0479
0480 0x1012 0x11 FN+PGUP ThinkLight toggle. This key is
0481 always handled by the firmware,
0482 even when unmasked.
0483
0484 0x1013 0x12 FN+PGDOWN -
0485
0486 0x1014 0x13 FN+SPACE Zoom key
0487
0488 0x1015 0x14 VOLUME UP Internal mixer volume up. This
0489 key is always handled by the
0490 firmware, even when unmasked.
0491 NOTE: Lenovo seems to be changing
0492 this.
0493 0x1016 0x15 VOLUME DOWN Internal mixer volume up. This
0494 key is always handled by the
0495 firmware, even when unmasked.
0496 NOTE: Lenovo seems to be changing
0497 this.
0498 0x1017 0x16 MUTE Mute internal mixer. This
0499 key is always handled by the
0500 firmware, even when unmasked.
0501
0502 0x1018 0x17 THINKPAD ThinkPad/Access IBM/Lenovo key
0503
0504 0x1019 0x18 unknown
0505
0506 ... ... ...
0507
0508 0x1020 0x1F unknown
0509 ======= ======= ============== ==============================================
0510
0511 The ThinkPad firmware does not allow one to differentiate when most hot
0512 keys are pressed or released (either that, or we don't know how to, yet).
0513 For these keys, the driver generates a set of events for a key press and
0514 immediately issues the same set of events for a key release. It is
0515 unknown by the driver if the ThinkPad firmware triggered these events on
0516 hot key press or release, but the firmware will do it for either one, not
0517 both.
0518
0519 If a key is mapped to KEY_RESERVED, it generates no input events at all.
0520 If a key is mapped to KEY_UNKNOWN, it generates an input event that
0521 includes an scan code. If a key is mapped to anything else, it will
0522 generate input device EV_KEY events.
0523
0524 In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW
0525 events for switches:
0526
0527 ============== ==============================================
0528 SW_RFKILL_ALL T60 and later hardware rfkill rocker switch
0529 SW_TABLET_MODE Tablet ThinkPads HKEY events 0x5009 and 0x500A
0530 ============== ==============================================
0531
0532 Non hotkey ACPI HKEY event map
0533 ------------------------------
0534
0535 Events that are never propagated by the driver:
0536
0537 ====== ==================================================
0538 0x2304 System is waking up from suspend to undock
0539 0x2305 System is waking up from suspend to eject bay
0540 0x2404 System is waking up from hibernation to undock
0541 0x2405 System is waking up from hibernation to eject bay
0542 0x5001 Lid closed
0543 0x5002 Lid opened
0544 0x5009 Tablet swivel: switched to tablet mode
0545 0x500A Tablet swivel: switched to normal mode
0546 0x5010 Brightness level changed/control event
0547 0x6000 KEYBOARD: Numlock key pressed
0548 0x6005 KEYBOARD: Fn key pressed (TO BE VERIFIED)
0549 0x7000 Radio Switch may have changed state
0550 ====== ==================================================
0551
0552
0553 Events that are propagated by the driver to userspace:
0554
0555 ====== =====================================================
0556 0x2313 ALARM: System is waking up from suspend because
0557 the battery is nearly empty
0558 0x2413 ALARM: System is waking up from hibernation because
0559 the battery is nearly empty
0560 0x3003 Bay ejection (see 0x2x05) complete, can sleep again
0561 0x3006 Bay hotplug request (hint to power up SATA link when
0562 the optical drive tray is ejected)
0563 0x4003 Undocked (see 0x2x04), can sleep again
0564 0x4010 Docked into hotplug port replicator (non-ACPI dock)
0565 0x4011 Undocked from hotplug port replicator (non-ACPI dock)
0566 0x500B Tablet pen inserted into its storage bay
0567 0x500C Tablet pen removed from its storage bay
0568 0x6011 ALARM: battery is too hot
0569 0x6012 ALARM: battery is extremely hot
0570 0x6021 ALARM: a sensor is too hot
0571 0x6022 ALARM: a sensor is extremely hot
0572 0x6030 System thermal table changed
0573 0x6032 Thermal Control command set completion (DYTC, Windows)
0574 0x6040 Nvidia Optimus/AC adapter related (TO BE VERIFIED)
0575 0x60C0 X1 Yoga 2016, Tablet mode status changed
0576 0x60F0 Thermal Transformation changed (GMTS, Windows)
0577 ====== =====================================================
0578
0579 Battery nearly empty alarms are a last resort attempt to get the
0580 operating system to hibernate or shutdown cleanly (0x2313), or shutdown
0581 cleanly (0x2413) before power is lost. They must be acted upon, as the
0582 wake up caused by the firmware will have negated most safety nets...
0583
0584 When any of the "too hot" alarms happen, according to Lenovo the user
0585 should suspend or hibernate the laptop (and in the case of battery
0586 alarms, unplug the AC adapter) to let it cool down. These alarms do
0587 signal that something is wrong, they should never happen on normal
0588 operating conditions.
0589
0590 The "extremely hot" alarms are emergencies. According to Lenovo, the
0591 operating system is to force either an immediate suspend or hibernate
0592 cycle, or a system shutdown. Obviously, something is very wrong if this
0593 happens.
0594
0595
0596 Brightness hotkey notes
0597 ^^^^^^^^^^^^^^^^^^^^^^^
0598
0599 Don't mess with the brightness hotkeys in a Thinkpad. If you want
0600 notifications for OSD, use the sysfs backlight class event support.
0601
0602 The driver will issue KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN events
0603 automatically for the cases were userspace has to do something to
0604 implement brightness changes. When you override these events, you will
0605 either fail to handle properly the ThinkPads that require explicit
0606 action to change backlight brightness, or the ThinkPads that require
0607 that no action be taken to work properly.
0608
0609
0610 Bluetooth
0611 ---------
0612
0613 procfs: /proc/acpi/ibm/bluetooth
0614
0615 sysfs device attribute: bluetooth_enable (deprecated)
0616
0617 sysfs rfkill class: switch "tpacpi_bluetooth_sw"
0618
0619 This feature shows the presence and current state of a ThinkPad
0620 Bluetooth device in the internal ThinkPad CDC slot.
0621
0622 If the ThinkPad supports it, the Bluetooth state is stored in NVRAM,
0623 so it is kept across reboots and power-off.
0624
0625 Procfs notes
0626 ^^^^^^^^^^^^
0627
0628 If Bluetooth is installed, the following commands can be used::
0629
0630 echo enable > /proc/acpi/ibm/bluetooth
0631 echo disable > /proc/acpi/ibm/bluetooth
0632
0633 Sysfs notes
0634 ^^^^^^^^^^^
0635
0636 If the Bluetooth CDC card is installed, it can be enabled /
0637 disabled through the "bluetooth_enable" thinkpad-acpi device
0638 attribute, and its current status can also be queried.
0639
0640 enable:
0641
0642 - 0: disables Bluetooth / Bluetooth is disabled
0643 - 1: enables Bluetooth / Bluetooth is enabled.
0644
0645 Note: this interface has been superseded by the generic rfkill
0646 class. It has been deprecated, and it will be removed in year
0647 2010.
0648
0649 rfkill controller switch "tpacpi_bluetooth_sw": refer to
0650 Documentation/driver-api/rfkill.rst for details.
0651
0652
0653 Video output control -- /proc/acpi/ibm/video
0654 --------------------------------------------
0655
0656 This feature allows control over the devices used for video output -
0657 LCD, CRT or DVI (if available). The following commands are available::
0658
0659 echo lcd_enable > /proc/acpi/ibm/video
0660 echo lcd_disable > /proc/acpi/ibm/video
0661 echo crt_enable > /proc/acpi/ibm/video
0662 echo crt_disable > /proc/acpi/ibm/video
0663 echo dvi_enable > /proc/acpi/ibm/video
0664 echo dvi_disable > /proc/acpi/ibm/video
0665 echo auto_enable > /proc/acpi/ibm/video
0666 echo auto_disable > /proc/acpi/ibm/video
0667 echo expand_toggle > /proc/acpi/ibm/video
0668 echo video_switch > /proc/acpi/ibm/video
0669
0670 NOTE:
0671 Access to this feature is restricted to processes owning the
0672 CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
0673 enough with some versions of X.org to crash it.
0674
0675 Each video output device can be enabled or disabled individually.
0676 Reading /proc/acpi/ibm/video shows the status of each device.
0677
0678 Automatic video switching can be enabled or disabled. When automatic
0679 video switching is enabled, certain events (e.g. opening the lid,
0680 docking or undocking) cause the video output device to change
0681 automatically. While this can be useful, it also causes flickering
0682 and, on the X40, video corruption. By disabling automatic switching,
0683 the flickering or video corruption can be avoided.
0684
0685 The video_switch command cycles through the available video outputs
0686 (it simulates the behavior of Fn-F7).
0687
0688 Video expansion can be toggled through this feature. This controls
0689 whether the display is expanded to fill the entire LCD screen when a
0690 mode with less than full resolution is used. Note that the current
0691 video expansion status cannot be determined through this feature.
0692
0693 Note that on many models (particularly those using Radeon graphics
0694 chips) the X driver configures the video card in a way which prevents
0695 Fn-F7 from working. This also disables the video output switching
0696 features of this driver, as it uses the same ACPI methods as
0697 Fn-F7. Video switching on the console should still work.
0698
0699 UPDATE: refer to https://bugs.freedesktop.org/show_bug.cgi?id=2000
0700
0701
0702 ThinkLight control
0703 ------------------
0704
0705 procfs: /proc/acpi/ibm/light
0706
0707 sysfs attributes: as per LED class, for the "tpacpi::thinklight" LED
0708
0709 procfs notes
0710 ^^^^^^^^^^^^
0711
0712 The ThinkLight status can be read and set through the procfs interface. A
0713 few models which do not make the status available will show the ThinkLight
0714 status as "unknown". The available commands are::
0715
0716 echo on > /proc/acpi/ibm/light
0717 echo off > /proc/acpi/ibm/light
0718
0719 sysfs notes
0720 ^^^^^^^^^^^
0721
0722 The ThinkLight sysfs interface is documented by the LED class
0723 documentation, in Documentation/leds/leds-class.rst. The ThinkLight LED name
0724 is "tpacpi::thinklight".
0725
0726 Due to limitations in the sysfs LED class, if the status of the ThinkLight
0727 cannot be read or if it is unknown, thinkpad-acpi will report it as "off".
0728 It is impossible to know if the status returned through sysfs is valid.
0729
0730
0731 CMOS/UCMS control
0732 -----------------
0733
0734 procfs: /proc/acpi/ibm/cmos
0735
0736 sysfs device attribute: cmos_command
0737
0738 This feature is mostly used internally by the ACPI firmware to keep the legacy
0739 CMOS NVRAM bits in sync with the current machine state, and to record this
0740 state so that the ThinkPad will retain such settings across reboots.
0741
0742 Some of these commands actually perform actions in some ThinkPad models, but
0743 this is expected to disappear more and more in newer models. As an example, in
0744 a T43 and in a X40, commands 12 and 13 still control the ThinkLight state for
0745 real, but commands 0 to 2 don't control the mixer anymore (they have been
0746 phased out) and just update the NVRAM.
0747
0748 The range of valid cmos command numbers is 0 to 21, but not all have an
0749 effect and the behavior varies from model to model. Here is the behavior
0750 on the X40 (tpb is the ThinkPad Buttons utility):
0751
0752 - 0 - Related to "Volume down" key press
0753 - 1 - Related to "Volume up" key press
0754 - 2 - Related to "Mute on" key press
0755 - 3 - Related to "Access IBM" key press
0756 - 4 - Related to "LCD brightness up" key press
0757 - 5 - Related to "LCD brightness down" key press
0758 - 11 - Related to "toggle screen expansion" key press/function
0759 - 12 - Related to "ThinkLight on"
0760 - 13 - Related to "ThinkLight off"
0761 - 14 - Related to "ThinkLight" key press (toggle ThinkLight)
0762
0763 The cmos command interface is prone to firmware split-brain problems, as
0764 in newer ThinkPads it is just a compatibility layer. Do not use it, it is
0765 exported just as a debug tool.
0766
0767
0768 LED control
0769 -----------
0770
0771 procfs: /proc/acpi/ibm/led
0772 sysfs attributes: as per LED class, see below for names
0773
0774 Some of the LED indicators can be controlled through this feature. On
0775 some older ThinkPad models, it is possible to query the status of the
0776 LED indicators as well. Newer ThinkPads cannot query the real status
0777 of the LED indicators.
0778
0779 Because misuse of the LEDs could induce an unaware user to perform
0780 dangerous actions (like undocking or ejecting a bay device while the
0781 buses are still active), or mask an important alarm (such as a nearly
0782 empty battery, or a broken battery), access to most LEDs is
0783 restricted.
0784
0785 Unrestricted access to all LEDs requires that thinkpad-acpi be
0786 compiled with the CONFIG_THINKPAD_ACPI_UNSAFE_LEDS option enabled.
0787 Distributions must never enable this option. Individual users that
0788 are aware of the consequences are welcome to enabling it.
0789
0790 Audio mute and microphone mute LEDs are supported, but currently not
0791 visible to userspace. They are used by the snd-hda-intel audio driver.
0792
0793 procfs notes
0794 ^^^^^^^^^^^^
0795
0796 The available commands are::
0797
0798 echo '<LED number> on' >/proc/acpi/ibm/led
0799 echo '<LED number> off' >/proc/acpi/ibm/led
0800 echo '<LED number> blink' >/proc/acpi/ibm/led
0801
0802 The <LED number> range is 0 to 15. The set of LEDs that can be
0803 controlled varies from model to model. Here is the common ThinkPad
0804 mapping:
0805
0806 - 0 - power
0807 - 1 - battery (orange)
0808 - 2 - battery (green)
0809 - 3 - UltraBase/dock
0810 - 4 - UltraBay
0811 - 5 - UltraBase battery slot
0812 - 6 - (unknown)
0813 - 7 - standby
0814 - 8 - dock status 1
0815 - 9 - dock status 2
0816 - 10, 11 - (unknown)
0817 - 12 - thinkvantage
0818 - 13, 14, 15 - (unknown)
0819
0820 All of the above can be turned on and off and can be made to blink.
0821
0822 sysfs notes
0823 ^^^^^^^^^^^
0824
0825 The ThinkPad LED sysfs interface is described in detail by the LED class
0826 documentation, in Documentation/leds/leds-class.rst.
0827
0828 The LEDs are named (in LED ID order, from 0 to 12):
0829 "tpacpi::power", "tpacpi:orange:batt", "tpacpi:green:batt",
0830 "tpacpi::dock_active", "tpacpi::bay_active", "tpacpi::dock_batt",
0831 "tpacpi::unknown_led", "tpacpi::standby", "tpacpi::dock_status1",
0832 "tpacpi::dock_status2", "tpacpi::unknown_led2", "tpacpi::unknown_led3",
0833 "tpacpi::thinkvantage".
0834
0835 Due to limitations in the sysfs LED class, if the status of the LED
0836 indicators cannot be read due to an error, thinkpad-acpi will report it as
0837 a brightness of zero (same as LED off).
0838
0839 If the thinkpad firmware doesn't support reading the current status,
0840 trying to read the current LED brightness will just return whatever
0841 brightness was last written to that attribute.
0842
0843 These LEDs can blink using hardware acceleration. To request that a
0844 ThinkPad indicator LED should blink in hardware accelerated mode, use the
0845 "timer" trigger, and leave the delay_on and delay_off parameters set to
0846 zero (to request hardware acceleration autodetection).
0847
0848 LEDs that are known not to exist in a given ThinkPad model are not
0849 made available through the sysfs interface. If you have a dock and you
0850 notice there are LEDs listed for your ThinkPad that do not exist (and
0851 are not in the dock), or if you notice that there are missing LEDs,
0852 a report to ibm-acpi-devel@lists.sourceforge.net is appreciated.
0853
0854
0855 ACPI sounds -- /proc/acpi/ibm/beep
0856 ----------------------------------
0857
0858 The BEEP method is used internally by the ACPI firmware to provide
0859 audible alerts in various situations. This feature allows the same
0860 sounds to be triggered manually.
0861
0862 The commands are non-negative integer numbers::
0863
0864 echo <number> >/proc/acpi/ibm/beep
0865
0866 The valid <number> range is 0 to 17. Not all numbers trigger sounds
0867 and the sounds vary from model to model. Here is the behavior on the
0868 X40:
0869
0870 - 0 - stop a sound in progress (but use 17 to stop 16)
0871 - 2 - two beeps, pause, third beep ("low battery")
0872 - 3 - single beep
0873 - 4 - high, followed by low-pitched beep ("unable")
0874 - 5 - single beep
0875 - 6 - very high, followed by high-pitched beep ("AC/DC")
0876 - 7 - high-pitched beep
0877 - 9 - three short beeps
0878 - 10 - very long beep
0879 - 12 - low-pitched beep
0880 - 15 - three high-pitched beeps repeating constantly, stop with 0
0881 - 16 - one medium-pitched beep repeating constantly, stop with 17
0882 - 17 - stop 16
0883
0884
0885 Temperature sensors
0886 -------------------
0887
0888 procfs: /proc/acpi/ibm/thermal
0889
0890 sysfs device attributes: (hwmon "thinkpad") temp*_input
0891
0892 Most ThinkPads include six or more separate temperature sensors but only
0893 expose the CPU temperature through the standard ACPI methods. This
0894 feature shows readings from up to eight different sensors on older
0895 ThinkPads, and up to sixteen different sensors on newer ThinkPads.
0896
0897 For example, on the X40, a typical output may be:
0898
0899 temperatures:
0900 42 42 45 41 36 -128 33 -128
0901
0902 On the T43/p, a typical output may be:
0903
0904 temperatures:
0905 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
0906
0907 The mapping of thermal sensors to physical locations varies depending on
0908 system-board model (and thus, on ThinkPad model).
0909
0910 https://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
0911 tries to track down these locations for various models.
0912
0913 Most (newer?) models seem to follow this pattern:
0914
0915 - 1: CPU
0916 - 2: (depends on model)
0917 - 3: (depends on model)
0918 - 4: GPU
0919 - 5: Main battery: main sensor
0920 - 6: Bay battery: main sensor
0921 - 7: Main battery: secondary sensor
0922 - 8: Bay battery: secondary sensor
0923 - 9-15: (depends on model)
0924
0925 For the R51 (source: Thomas Gruber):
0926
0927 - 2: Mini-PCI
0928 - 3: Internal HDD
0929
0930 For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
0931 https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
0932
0933 - 2: System board, left side (near PCMCIA slot), reported as HDAPS temp
0934 - 3: PCMCIA slot
0935 - 9: MCH (northbridge) to DRAM Bus
0936 - 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
0937 card, under touchpad
0938 - 11: Power regulator, underside of system board, below F2 key
0939
0940 The A31 has a very atypical layout for the thermal sensors
0941 (source: Milos Popovic, https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
0942
0943 - 1: CPU
0944 - 2: Main Battery: main sensor
0945 - 3: Power Converter
0946 - 4: Bay Battery: main sensor
0947 - 5: MCH (northbridge)
0948 - 6: PCMCIA/ambient
0949 - 7: Main Battery: secondary sensor
0950 - 8: Bay Battery: secondary sensor
0951
0952
0953 Procfs notes
0954 ^^^^^^^^^^^^
0955
0956 Readings from sensors that are not available return -128.
0957 No commands can be written to this file.
0958
0959 Sysfs notes
0960 ^^^^^^^^^^^
0961
0962 Sensors that are not available return the ENXIO error. This
0963 status may change at runtime, as there are hotplug thermal
0964 sensors, like those inside the batteries and docks.
0965
0966 thinkpad-acpi thermal sensors are reported through the hwmon
0967 subsystem, and follow all of the hwmon guidelines at
0968 Documentation/hwmon.
0969
0970 EXPERIMENTAL: Embedded controller register dump
0971 -----------------------------------------------
0972
0973 This feature is not included in the thinkpad driver anymore.
0974 Instead the EC can be accessed through /sys/kernel/debug/ec with
0975 a userspace tool which can be found here:
0976 ftp://ftp.suse.com/pub/people/trenn/sources/ec
0977
0978 Use it to determine the register holding the fan
0979 speed on some models. To do that, do the following:
0980
0981 - make sure the battery is fully charged
0982 - make sure the fan is running
0983 - use above mentioned tool to read out the EC
0984
0985 Often fan and temperature values vary between
0986 readings. Since temperatures don't change vary fast, you can take
0987 several quick dumps to eliminate them.
0988
0989 You can use a similar method to figure out the meaning of other
0990 embedded controller registers - e.g. make sure nothing else changes
0991 except the charging or discharging battery to determine which
0992 registers contain the current battery capacity, etc. If you experiment
0993 with this, do send me your results (including some complete dumps with
0994 a description of the conditions when they were taken.)
0995
0996
0997 LCD brightness control
0998 ----------------------
0999
1000 procfs: /proc/acpi/ibm/brightness
1001
1002 sysfs backlight device "thinkpad_screen"
1003
1004 This feature allows software control of the LCD brightness on ThinkPad
1005 models which don't have a hardware brightness slider.
1006
1007 It has some limitations: the LCD backlight cannot be actually turned
1008 on or off by this interface, it just controls the backlight brightness
1009 level.
1010
1011 On IBM (and some of the earlier Lenovo) ThinkPads, the backlight control
1012 has eight brightness levels, ranging from 0 to 7. Some of the levels
1013 may not be distinct. Later Lenovo models that implement the ACPI
1014 display backlight brightness control methods have 16 levels, ranging
1015 from 0 to 15.
1016
1017 For IBM ThinkPads, there are two interfaces to the firmware for direct
1018 brightness control, EC and UCMS (or CMOS). To select which one should be
1019 used, use the brightness_mode module parameter: brightness_mode=1 selects
1020 EC mode, brightness_mode=2 selects UCMS mode, brightness_mode=3 selects EC
1021 mode with NVRAM backing (so that brightness changes are remembered across
1022 shutdown/reboot).
1023
1024 The driver tries to select which interface to use from a table of
1025 defaults for each ThinkPad model. If it makes a wrong choice, please
1026 report this as a bug, so that we can fix it.
1027
1028 Lenovo ThinkPads only support brightness_mode=2 (UCMS).
1029
1030 When display backlight brightness controls are available through the
1031 standard ACPI interface, it is best to use it instead of this direct
1032 ThinkPad-specific interface. The driver will disable its native
1033 backlight brightness control interface if it detects that the standard
1034 ACPI interface is available in the ThinkPad.
1035
1036 If you want to use the thinkpad-acpi backlight brightness control
1037 instead of the generic ACPI video backlight brightness control for some
1038 reason, you should use the acpi_backlight=vendor kernel parameter.
1039
1040 The brightness_enable module parameter can be used to control whether
1041 the LCD brightness control feature will be enabled when available.
1042 brightness_enable=0 forces it to be disabled. brightness_enable=1
1043 forces it to be enabled when available, even if the standard ACPI
1044 interface is also available.
1045
1046 Procfs notes
1047 ^^^^^^^^^^^^
1048
1049 The available commands are::
1050
1051 echo up >/proc/acpi/ibm/brightness
1052 echo down >/proc/acpi/ibm/brightness
1053 echo 'level <level>' >/proc/acpi/ibm/brightness
1054
1055 Sysfs notes
1056 ^^^^^^^^^^^
1057
1058 The interface is implemented through the backlight sysfs class, which is
1059 poorly documented at this time.
1060
1061 Locate the thinkpad_screen device under /sys/class/backlight, and inside
1062 it there will be the following attributes:
1063
1064 max_brightness:
1065 Reads the maximum brightness the hardware can be set to.
1066 The minimum is always zero.
1067
1068 actual_brightness:
1069 Reads what brightness the screen is set to at this instant.
1070
1071 brightness:
1072 Writes request the driver to change brightness to the
1073 given value. Reads will tell you what brightness the
1074 driver is trying to set the display to when "power" is set
1075 to zero and the display has not been dimmed by a kernel
1076 power management event.
1077
1078 power:
1079 power management mode, where 0 is "display on", and 1 to 3
1080 will dim the display backlight to brightness level 0
1081 because thinkpad-acpi cannot really turn the backlight
1082 off. Kernel power management events can temporarily
1083 increase the current power management level, i.e. they can
1084 dim the display.
1085
1086
1087 WARNING:
1088
1089 Whatever you do, do NOT ever call thinkpad-acpi backlight-level change
1090 interface and the ACPI-based backlight level change interface
1091 (available on newer BIOSes, and driven by the Linux ACPI video driver)
1092 at the same time. The two will interact in bad ways, do funny things,
1093 and maybe reduce the life of the backlight lamps by needlessly kicking
1094 its level up and down at every change.
1095
1096
1097 Volume control (Console Audio control)
1098 --------------------------------------
1099
1100 procfs: /proc/acpi/ibm/volume
1101
1102 ALSA: "ThinkPad Console Audio Control", default ID: "ThinkPadEC"
1103
1104 NOTE: by default, the volume control interface operates in read-only
1105 mode, as it is supposed to be used for on-screen-display purposes.
1106 The read/write mode can be enabled through the use of the
1107 "volume_control=1" module parameter.
1108
1109 NOTE: distros are urged to not enable volume_control by default, this
1110 should be done by the local admin only. The ThinkPad UI is for the
1111 console audio control to be done through the volume keys only, and for
1112 the desktop environment to just provide on-screen-display feedback.
1113 Software volume control should be done only in the main AC97/HDA
1114 mixer.
1115
1116
1117 About the ThinkPad Console Audio control
1118 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1119
1120 ThinkPads have a built-in amplifier and muting circuit that drives the
1121 console headphone and speakers. This circuit is after the main AC97
1122 or HDA mixer in the audio path, and under exclusive control of the
1123 firmware.
1124
1125 ThinkPads have three special hotkeys to interact with the console
1126 audio control: volume up, volume down and mute.
1127
1128 It is worth noting that the normal way the mute function works (on
1129 ThinkPads that do not have a "mute LED") is:
1130
1131 1. Press mute to mute. It will *always* mute, you can press it as
1132 many times as you want, and the sound will remain mute.
1133
1134 2. Press either volume key to unmute the ThinkPad (it will _not_
1135 change the volume, it will just unmute).
1136
1137 This is a very superior design when compared to the cheap software-only
1138 mute-toggle solution found on normal consumer laptops: you can be
1139 absolutely sure the ThinkPad will not make noise if you press the mute
1140 button, no matter the previous state.
1141
1142 The IBM ThinkPads, and the earlier Lenovo ThinkPads have variable-gain
1143 amplifiers driving the speakers and headphone output, and the firmware
1144 also handles volume control for the headphone and speakers on these
1145 ThinkPads without any help from the operating system (this volume
1146 control stage exists after the main AC97 or HDA mixer in the audio
1147 path).
1148
1149 The newer Lenovo models only have firmware mute control, and depend on
1150 the main HDA mixer to do volume control (which is done by the operating
1151 system). In this case, the volume keys are filtered out for unmute
1152 key press (there are some firmware bugs in this area) and delivered as
1153 normal key presses to the operating system (thinkpad-acpi is not
1154 involved).
1155
1156
1157 The ThinkPad-ACPI volume control
1158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1159
1160 The preferred way to interact with the Console Audio control is the
1161 ALSA interface.
1162
1163 The legacy procfs interface allows one to read the current state,
1164 and if volume control is enabled, accepts the following commands::
1165
1166 echo up >/proc/acpi/ibm/volume
1167 echo down >/proc/acpi/ibm/volume
1168 echo mute >/proc/acpi/ibm/volume
1169 echo unmute >/proc/acpi/ibm/volume
1170 echo 'level <level>' >/proc/acpi/ibm/volume
1171
1172 The <level> number range is 0 to 14 although not all of them may be
1173 distinct. To unmute the volume after the mute command, use either the
1174 up or down command (the level command will not unmute the volume), or
1175 the unmute command.
1176
1177 You can use the volume_capabilities parameter to tell the driver
1178 whether your thinkpad has volume control or mute-only control:
1179 volume_capabilities=1 for mixers with mute and volume control,
1180 volume_capabilities=2 for mixers with only mute control.
1181
1182 If the driver misdetects the capabilities for your ThinkPad model,
1183 please report this to ibm-acpi-devel@lists.sourceforge.net, so that we
1184 can update the driver.
1185
1186 There are two strategies for volume control. To select which one
1187 should be used, use the volume_mode module parameter: volume_mode=1
1188 selects EC mode, and volume_mode=3 selects EC mode with NVRAM backing
1189 (so that volume/mute changes are remembered across shutdown/reboot).
1190
1191 The driver will operate in volume_mode=3 by default. If that does not
1192 work well on your ThinkPad model, please report this to
1193 ibm-acpi-devel@lists.sourceforge.net.
1194
1195 The driver supports the standard ALSA module parameters. If the ALSA
1196 mixer is disabled, the driver will disable all volume functionality.
1197
1198
1199 Fan control and monitoring: fan speed, fan enable/disable
1200 ---------------------------------------------------------
1201
1202 procfs: /proc/acpi/ibm/fan
1203
1204 sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1, pwm1_enable, fan2_input
1205
1206 sysfs hwmon driver attributes: fan_watchdog
1207
1208 NOTE NOTE NOTE:
1209 fan control operations are disabled by default for
1210 safety reasons. To enable them, the module parameter "fan_control=1"
1211 must be given to thinkpad-acpi.
1212
1213 This feature attempts to show the current fan speed, control mode and
1214 other fan data that might be available. The speed is read directly
1215 from the hardware registers of the embedded controller. This is known
1216 to work on later R, T, X and Z series ThinkPads but may show a bogus
1217 value on other models.
1218
1219 Some Lenovo ThinkPads support a secondary fan. This fan cannot be
1220 controlled separately, it shares the main fan control.
1221
1222 Fan levels
1223 ^^^^^^^^^^
1224
1225 Most ThinkPad fans work in "levels" at the firmware interface. Level 0
1226 stops the fan. The higher the level, the higher the fan speed, although
1227 adjacent levels often map to the same fan speed. 7 is the highest
1228 level, where the fan reaches the maximum recommended speed.
1229
1230 Level "auto" means the EC changes the fan level according to some
1231 internal algorithm, usually based on readings from the thermal sensors.
1232
1233 There is also a "full-speed" level, also known as "disengaged" level.
1234 In this level, the EC disables the speed-locked closed-loop fan control,
1235 and drives the fan as fast as it can go, which might exceed hardware
1236 limits, so use this level with caution.
1237
1238 The fan usually ramps up or down slowly from one speed to another, and
1239 it is normal for the EC to take several seconds to react to fan
1240 commands. The full-speed level may take up to two minutes to ramp up to
1241 maximum speed, and in some ThinkPads, the tachometer readings go stale
1242 while the EC is transitioning to the full-speed level.
1243
1244 WARNING WARNING WARNING: do not leave the fan disabled unless you are
1245 monitoring all of the temperature sensor readings and you are ready to
1246 enable it if necessary to avoid overheating.
1247
1248 An enabled fan in level "auto" may stop spinning if the EC decides the
1249 ThinkPad is cool enough and doesn't need the extra airflow. This is
1250 normal, and the EC will spin the fan up if the various thermal readings
1251 rise too much.
1252
1253 On the X40, this seems to depend on the CPU and HDD temperatures.
1254 Specifically, the fan is turned on when either the CPU temperature
1255 climbs to 56 degrees or the HDD temperature climbs to 46 degrees. The
1256 fan is turned off when the CPU temperature drops to 49 degrees and the
1257 HDD temperature drops to 41 degrees. These thresholds cannot
1258 currently be controlled.
1259
1260 The ThinkPad's ACPI DSDT code will reprogram the fan on its own when
1261 certain conditions are met. It will override any fan programming done
1262 through thinkpad-acpi.
1263
1264 The thinkpad-acpi kernel driver can be programmed to revert the fan
1265 level to a safe setting if userspace does not issue one of the procfs
1266 fan commands: "enable", "disable", "level" or "watchdog", or if there
1267 are no writes to pwm1_enable (or to pwm1 *if and only if* pwm1_enable is
1268 set to 1, manual mode) within a configurable amount of time of up to
1269 120 seconds. This functionality is called fan safety watchdog.
1270
1271 Note that the watchdog timer stops after it enables the fan. It will be
1272 rearmed again automatically (using the same interval) when one of the
1273 above mentioned fan commands is received. The fan watchdog is,
1274 therefore, not suitable to protect against fan mode changes made through
1275 means other than the "enable", "disable", and "level" procfs fan
1276 commands, or the hwmon fan control sysfs interface.
1277
1278 Procfs notes
1279 ^^^^^^^^^^^^
1280
1281 The fan may be enabled or disabled with the following commands::
1282
1283 echo enable >/proc/acpi/ibm/fan
1284 echo disable >/proc/acpi/ibm/fan
1285
1286 Placing a fan on level 0 is the same as disabling it. Enabling a fan
1287 will try to place it in a safe level if it is too slow or disabled.
1288
1289 The fan level can be controlled with the command::
1290
1291 echo 'level <level>' > /proc/acpi/ibm/fan
1292
1293 Where <level> is an integer from 0 to 7, or one of the words "auto" or
1294 "full-speed" (without the quotes). Not all ThinkPads support the "auto"
1295 and "full-speed" levels. The driver accepts "disengaged" as an alias for
1296 "full-speed", and reports it as "disengaged" for backwards
1297 compatibility.
1298
1299 On the X31 and X40 (and ONLY on those models), the fan speed can be
1300 controlled to a certain degree. Once the fan is running, it can be
1301 forced to run faster or slower with the following command::
1302
1303 echo 'speed <speed>' > /proc/acpi/ibm/fan
1304
1305 The sustainable range of fan speeds on the X40 appears to be from about
1306 3700 to about 7350. Values outside this range either do not have any
1307 effect or the fan speed eventually settles somewhere in that range. The
1308 fan cannot be stopped or started with this command. This functionality
1309 is incomplete, and not available through the sysfs interface.
1310
1311 To program the safety watchdog, use the "watchdog" command::
1312
1313 echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
1314
1315 If you want to disable the watchdog, use 0 as the interval.
1316
1317 Sysfs notes
1318 ^^^^^^^^^^^
1319
1320 The sysfs interface follows the hwmon subsystem guidelines for the most
1321 part, and the exception is the fan safety watchdog.
1322
1323 Writes to any of the sysfs attributes may return the EINVAL error if
1324 that operation is not supported in a given ThinkPad or if the parameter
1325 is out-of-bounds, and EPERM if it is forbidden. They may also return
1326 EINTR (interrupted system call), and EIO (I/O error while trying to talk
1327 to the firmware).
1328
1329 Features not yet implemented by the driver return ENOSYS.
1330
1331 hwmon device attribute pwm1_enable:
1332 - 0: PWM offline (fan is set to full-speed mode)
1333 - 1: Manual PWM control (use pwm1 to set fan level)
1334 - 2: Hardware PWM control (EC "auto" mode)
1335 - 3: reserved (Software PWM control, not implemented yet)
1336
1337 Modes 0 and 2 are not supported by all ThinkPads, and the
1338 driver is not always able to detect this. If it does know a
1339 mode is unsupported, it will return -EINVAL.
1340
1341 hwmon device attribute pwm1:
1342 Fan level, scaled from the firmware values of 0-7 to the hwmon
1343 scale of 0-255. 0 means fan stopped, 255 means highest normal
1344 speed (level 7).
1345
1346 This attribute only commands the fan if pmw1_enable is set to 1
1347 (manual PWM control).
1348
1349 hwmon device attribute fan1_input:
1350 Fan tachometer reading, in RPM. May go stale on certain
1351 ThinkPads while the EC transitions the PWM to offline mode,
1352 which can take up to two minutes. May return rubbish on older
1353 ThinkPads.
1354
1355 hwmon device attribute fan2_input:
1356 Fan tachometer reading, in RPM, for the secondary fan.
1357 Available only on some ThinkPads. If the secondary fan is
1358 not installed, will always read 0.
1359
1360 hwmon driver attribute fan_watchdog:
1361 Fan safety watchdog timer interval, in seconds. Minimum is
1362 1 second, maximum is 120 seconds. 0 disables the watchdog.
1363
1364 To stop the fan: set pwm1 to zero, and pwm1_enable to 1.
1365
1366 To start the fan in a safe mode: set pwm1_enable to 2. If that fails
1367 with EINVAL, try to set pwm1_enable to 1 and pwm1 to at least 128 (255
1368 would be the safest choice, though).
1369
1370
1371 WAN
1372 ---
1373
1374 procfs: /proc/acpi/ibm/wan
1375
1376 sysfs device attribute: wwan_enable (deprecated)
1377
1378 sysfs rfkill class: switch "tpacpi_wwan_sw"
1379
1380 This feature shows the presence and current state of the built-in
1381 Wireless WAN device.
1382
1383 If the ThinkPad supports it, the WWAN state is stored in NVRAM,
1384 so it is kept across reboots and power-off.
1385
1386 It was tested on a Lenovo ThinkPad X60. It should probably work on other
1387 ThinkPad models which come with this module installed.
1388
1389 Procfs notes
1390 ^^^^^^^^^^^^
1391
1392 If the W-WAN card is installed, the following commands can be used::
1393
1394 echo enable > /proc/acpi/ibm/wan
1395 echo disable > /proc/acpi/ibm/wan
1396
1397 Sysfs notes
1398 ^^^^^^^^^^^
1399
1400 If the W-WAN card is installed, it can be enabled /
1401 disabled through the "wwan_enable" thinkpad-acpi device
1402 attribute, and its current status can also be queried.
1403
1404 enable:
1405 - 0: disables WWAN card / WWAN card is disabled
1406 - 1: enables WWAN card / WWAN card is enabled.
1407
1408 Note: this interface has been superseded by the generic rfkill
1409 class. It has been deprecated, and it will be removed in year
1410 2010.
1411
1412 rfkill controller switch "tpacpi_wwan_sw": refer to
1413 Documentation/driver-api/rfkill.rst for details.
1414
1415
1416 LCD Shadow control
1417 ------------------
1418
1419 procfs: /proc/acpi/ibm/lcdshadow
1420
1421 Some newer T480s and T490s ThinkPads provide a feature called
1422 PrivacyGuard. By turning this feature on, the usable vertical and
1423 horizontal viewing angles of the LCD can be limited (as if some privacy
1424 screen was applied manually in front of the display).
1425
1426 procfs notes
1427 ^^^^^^^^^^^^
1428
1429 The available commands are::
1430
1431 echo '0' >/proc/acpi/ibm/lcdshadow
1432 echo '1' >/proc/acpi/ibm/lcdshadow
1433
1434 The first command ensures the best viewing angle and the latter one turns
1435 on the feature, restricting the viewing angles.
1436
1437
1438 DYTC Lapmode sensor
1439 -------------------
1440
1441 sysfs: dytc_lapmode
1442
1443 Newer thinkpads and mobile workstations have the ability to determine if
1444 the device is in deskmode or lapmode. This feature is used by user space
1445 to decide if WWAN transmission can be increased to maximum power and is
1446 also useful for understanding the different thermal modes available as
1447 they differ between desk and lap mode.
1448
1449 The property is read-only. If the platform doesn't have support the sysfs
1450 class is not created.
1451
1452 EXPERIMENTAL: UWB
1453 -----------------
1454
1455 This feature is considered EXPERIMENTAL because it has not been extensively
1456 tested and validated in various ThinkPad models yet. The feature may not
1457 work as expected. USE WITH CAUTION! To use this feature, you need to supply
1458 the experimental=1 parameter when loading the module.
1459
1460 sysfs rfkill class: switch "tpacpi_uwb_sw"
1461
1462 This feature exports an rfkill controller for the UWB device, if one is
1463 present and enabled in the BIOS.
1464
1465 Sysfs notes
1466 ^^^^^^^^^^^
1467
1468 rfkill controller switch "tpacpi_uwb_sw": refer to
1469 Documentation/driver-api/rfkill.rst for details.
1470
1471
1472 Setting keyboard language
1473 -------------------------
1474
1475 sysfs: keyboard_lang
1476
1477 This feature is used to set keyboard language to ECFW using ASL interface.
1478 Fewer thinkpads models like T580 , T590 , T15 Gen 1 etc.. has "=", "(',
1479 ")" numeric keys, which are not displaying correctly, when keyboard language
1480 is other than "english". This is because the default keyboard language in ECFW
1481 is set as "english". Hence using this sysfs, user can set the correct keyboard
1482 language to ECFW and then these key's will work correctly.
1483
1484 Example of command to set keyboard language is mentioned below::
1485
1486 echo jp > /sys/devices/platform/thinkpad_acpi/keyboard_lang
1487
1488 Text corresponding to keyboard layout to be set in sysfs are: be(Belgian),
1489 cz(Czech), da(Danish), de(German), en(English), es(Spain), et(Estonian),
1490 fr(French), fr-ch(French(Switzerland)), hu(Hungarian), it(Italy), jp (Japan),
1491 nl(Dutch), nn(Norway), pl(Polish), pt(portugese), sl(Slovenian), sv(Sweden),
1492 tr(Turkey)
1493
1494 WWAN Antenna type
1495 -----------------
1496
1497 sysfs: wwan_antenna_type
1498
1499 On some newer Thinkpads we need to set SAR value based on the antenna
1500 type. This interface will be used by userspace to get the antenna type
1501 and set the corresponding SAR value, as is required for FCC certification.
1502
1503 The available commands are::
1504
1505 cat /sys/devices/platform/thinkpad_acpi/wwan_antenna_type
1506
1507 Currently 2 antenna types are supported as mentioned below:
1508 - type a
1509 - type b
1510
1511 The property is read-only. If the platform doesn't have support the sysfs
1512 class is not created.
1513
1514 Adaptive keyboard
1515 -----------------
1516
1517 sysfs device attribute: adaptive_kbd_mode
1518
1519 This sysfs attribute controls the keyboard "face" that will be shown on the
1520 Lenovo X1 Carbon 2nd gen (2014)'s adaptive keyboard. The value can be read
1521 and set.
1522
1523 - 0 = Home mode
1524 - 1 = Web-browser mode
1525 - 2 = Web-conference mode
1526 - 3 = Function mode
1527 - 4 = Layflat mode
1528
1529 For more details about which buttons will appear depending on the mode, please
1530 review the laptop's user guide:
1531 https://download.lenovo.com/ibmdl/pub/pc/pccbbs/mobiles_pdf/x1carbon_2_ug_en.pdf
1532
1533 Battery charge control
1534 ----------------------
1535
1536 sysfs attributes:
1537 /sys/class/power_supply/BAT*/charge_control_{start,end}_threshold
1538
1539 These two attributes are created for those batteries that are supported by the
1540 driver. They enable the user to control the battery charge thresholds of the
1541 given battery. Both values may be read and set. `charge_control_start_threshold`
1542 accepts an integer between 0 and 99 (inclusive); this value represents a battery
1543 percentage level, below which charging will begin. `charge_control_end_threshold`
1544 accepts an integer between 1 and 100 (inclusive); this value represents a battery
1545 percentage level, above which charging will stop.
1546
1547 The exact semantics of the attributes may be found in
1548 Documentation/ABI/testing/sysfs-class-power.
1549
1550 Multiple Commands, Module Parameters
1551 ------------------------------------
1552
1553 Multiple commands can be written to the proc files in one shot by
1554 separating them with commas, for example::
1555
1556 echo enable,0xffff > /proc/acpi/ibm/hotkey
1557 echo lcd_disable,crt_enable > /proc/acpi/ibm/video
1558
1559 Commands can also be specified when loading the thinkpad-acpi module,
1560 for example::
1561
1562 modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
1563
1564
1565 Enabling debugging output
1566 -------------------------
1567
1568 The module takes a debug parameter which can be used to selectively
1569 enable various classes of debugging output, for example::
1570
1571 modprobe thinkpad_acpi debug=0xffff
1572
1573 will enable all debugging output classes. It takes a bitmask, so
1574 to enable more than one output class, just add their values.
1575
1576 ============= ======================================
1577 Debug bitmask Description
1578 ============= ======================================
1579 0x8000 Disclose PID of userspace programs
1580 accessing some functions of the driver
1581 0x0001 Initialization and probing
1582 0x0002 Removal
1583 0x0004 RF Transmitter control (RFKILL)
1584 (bluetooth, WWAN, UWB...)
1585 0x0008 HKEY event interface, hotkeys
1586 0x0010 Fan control
1587 0x0020 Backlight brightness
1588 0x0040 Audio mixer/volume control
1589 ============= ======================================
1590
1591 There is also a kernel build option to enable more debugging
1592 information, which may be necessary to debug driver problems.
1593
1594 The level of debugging information output by the driver can be changed
1595 at runtime through sysfs, using the driver attribute debug_level. The
1596 attribute takes the same bitmask as the debug module parameter above.
1597
1598
1599 Force loading of module
1600 -----------------------
1601
1602 If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify
1603 the module parameter force_load=1. Regardless of whether this works or
1604 not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
1605
1606
1607 Sysfs interface changelog
1608 ^^^^^^^^^^^^^^^^^^^^^^^^^
1609
1610 ========= ===============================================================
1611 0x000100: Initial sysfs support, as a single platform driver and
1612 device.
1613 0x000200: Hot key support for 32 hot keys, and radio slider switch
1614 support.
1615 0x010000: Hot keys are now handled by default over the input
1616 layer, the radio switch generates input event EV_RADIO,
1617 and the driver enables hot key handling by default in
1618 the firmware.
1619
1620 0x020000: ABI fix: added a separate hwmon platform device and
1621 driver, which must be located by name (thinkpad)
1622 and the hwmon class for libsensors4 (lm-sensors 3)
1623 compatibility. Moved all hwmon attributes to this
1624 new platform device.
1625
1626 0x020100: Marker for thinkpad-acpi with hot key NVRAM polling
1627 support. If you must, use it to know you should not
1628 start a userspace NVRAM poller (allows to detect when
1629 NVRAM is compiled out by the user because it is
1630 unneeded/undesired in the first place).
1631 0x020101: Marker for thinkpad-acpi with hot key NVRAM polling
1632 and proper hotkey_mask semantics (version 8 of the
1633 NVRAM polling patch). Some development snapshots of
1634 0.18 had an earlier version that did strange things
1635 to hotkey_mask.
1636
1637 0x020200: Add poll()/select() support to the following attributes:
1638 hotkey_radio_sw, wakeup_hotunplug_complete, wakeup_reason
1639
1640 0x020300: hotkey enable/disable support removed, attributes
1641 hotkey_bios_enabled and hotkey_enable deprecated and
1642 marked for removal.
1643
1644 0x020400: Marker for 16 LEDs support. Also, LEDs that are known
1645 to not exist in a given model are not registered with
1646 the LED sysfs class anymore.
1647
1648 0x020500: Updated hotkey driver, hotkey_mask is always available
1649 and it is always able to disable hot keys. Very old
1650 thinkpads are properly supported. hotkey_bios_mask
1651 is deprecated and marked for removal.
1652
1653 0x020600: Marker for backlight change event support.
1654
1655 0x020700: Support for mute-only mixers.
1656 Volume control in read-only mode by default.
1657 Marker for ALSA mixer support.
1658
1659 0x030000: Thermal and fan sysfs attributes were moved to the hwmon
1660 device instead of being attached to the backing platform
1661 device.
1662 ========= ===============================================================
