admin-guide/laptops/thinkpad-acpi.rst

9 - Borislav Deianov <borislav@users.sf.net>
10 - Henrique de Moraes Holschuh <hmh@hmh.eng.br>
12 http://ibm-acpi.sf.net/
19 This driver used to be named ibm-acpi until kernel 2.6.21 and release
20 0.13-20070314.  It used to be in the drivers/acpi tree, but it was
21 moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel
25 The driver is named "thinkpad-acpi".  In some places, like module
29 "tpacpi" is used as a shorthand where "thinkpad-acpi" would be too
33 ------
38 	- Fn key combinations
39 	- Bluetooth enable and disable
40 	- video output switching, expansion control
41 	- ThinkLight on and off
42 	- CMOS/UCMS control
43 	- LED control
44 	- ACPI sounds
45 	- temperature sensors
46 	- Experimental: embedded controller register dump
47 	- LCD brightness control
48 	- Volume control
49 	- Fan control and monitoring: fan speed, fan enable/disable
50 	- WAN enable and disable
51 	- UWB enable and disable
52 	- LCD Shadow (PrivacyGuard) enable and disable
53 	- Lap mode sensor
54 	- Setting keyboard language
55 	- WWAN Antenna type
58 site, http://ibm-acpi.sf.net/. I appreciate any success or failure
62 	- ThinkPad model name
63 	- a copy of your ACPI tables, using the "acpidump" utility
64 	- a copy of the output of dmidecode, with serial numbers
66 	- which driver features work and which don't
67 	- the observed behavior of non-working features
73 ------------
77 It is located on the menu path: "Device Drivers" -> "X86 Platform
78 Specific Device Drivers" -> "ThinkPad ACPI Laptop Extras".
82 --------
85 used to access the features it provides.  One is a legacy procfs-based
87 is a new sysfs-based interface which is not complete yet.
106 thinkpad-acpi's implementation of sysfs interfaces.
108 Also, any bugs in the thinkpad-acpi sysfs driver code or in the
109 thinkpad-acpi's implementation of the sysfs interfaces will be fixed for
111 non-compatible ways.  As these interfaces mature both in the kernel and
112 in thinkpad-acpi, such changes should become quite rare.
114 Applications interfacing to the thinkpad-acpi sysfs interfaces must
119 The version of thinkpad-acpi's sysfs interface is exported by the driver
137 --------------
147 -----------------------
151 Version of the thinkpad-acpi sysfs interface, as an unsigned long
155 	  - major revision
157 	  - minor revision
159 	  - bugfix revision
166 Changes to the thinkpad-acpi sysfs interface are only considered
167 non-experimental when they are submitted to Linux mainline, at which
169 may be updated.  If you are using any thinkpad-acpi features not yet
174 Changes that are backwards-compatible by nature (e.g. the addition of
183 --------
190 some important events and also keyboard hot key presses to the operating
191 system.  Enabling the hotkey functionality of thinkpad-acpi signals the
195 The driver enables the HKEY ("hot key") event reporting automatically
202 Some of these events refer to hot key presses, but not all of them.
207 assigned to each hot key.
209 The hot key bit mask allows some control over which hot keys generate
210 events.  If a key is "masked" (bit set to 0 in the mask), the firmware
212 thinkpad-acpi would prefer to handle it, if the firmware would be so
225 example, if Fn+F5 is unmasked, that key will no longer enable/disable
228 Note also that not all Fn key combinations are supported through ACPI
239 	echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
240 	echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
241 	... any other 8-hex-digit mask ...
242 	echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
247 	echo enable > /proc/acpi/ibm/hotkey -- does nothing
248 	echo disable > /proc/acpi/ibm/hotkey -- returns an error
251 maintain maximum bug-to-bug compatibility, it does not report any masks,
252 nor does it allow one to manipulate the hot key mask when the firmware
266 		Returns the hot keys mask when thinkpad-acpi was loaded.
275 		0: returns -EPERM
280 		the firmware, ACPI event generation) for each hot key
301 		poll the NVRAM for.  This is auto-detected by the driver
317 		version -- not just with firmware models -- as well as
321 		frequency in Hz for hot key polling. It must be between
326 		will cause hot key presses that require NVRAM polling
330 		pressings of the same hot key to be misreported as a
331 		single key press, or to not even be detected at all.
353 		undock.  Set to zero for normal wake-ups or wake-ups
371 A Hot key is mapped to a single input layer EV_KEY event, possibly
372 followed by an EV_MSC MSC_SCAN event that shall contain that key's scan
391 backwards-compatible way.  The MSB shall always be 0x41 for this input
395 been changed in a non-backwards compatible way.
398 backwards-compatible change for this input device.
400 Thinkpad-acpi Hot Key event map (version 0x4101):
404 event	code	Key		Notes
406 0x1001	0x00	FN+F1		-
412 				this hot key, even with hot keys
416 				off the ThinkLight as side-effect
420 				semantics, i.e. sleep-to-RAM).
422 				of event, either the hot key
426 				key presses until a S3 or S4 ACPI
432 				and W-WAN card if left in control
436 				radios (Bluetooth+W-WAN+WLAN),
439 0x1006	0x05	FN+F6		-
448 0x1009	0x08	FN+F9		-
452 0x100B	0x0A	FN+F11		-
459 				generate further FN+F12 key
464 0x100D	0x0C	FN+BACKSPACE	-
465 0x100E	0x0D	FN+INSERT	-
466 0x100F	0x0E	FN+DELETE	-
468 0x1010	0x0F	FN+HOME		Brightness up.  This key is
480 0x1012	0x11	FN+PGUP		ThinkLight toggle.  This key is
484 0x1013	0x12	FN+PGDOWN	-
486 0x1014	0x13	FN+SPACE	Zoom key
489 				key is always handled by the
494 				key is always handled by the
499 				key is always handled by the
502 0x1018	0x17	THINKPAD	ThinkPad/Access IBM/Lenovo key
513 For these keys, the driver generates a set of events for a key press and
514 immediately issues the same set of events for a key release.  It is
516 hot key press or release, but the firmware will do it for either one, not
519 If a key is mapped to KEY_RESERVED, it generates no input events at all.
520 If a key is mapped to KEY_UNKNOWN, it generates an input event that
521 includes an scan code.  If a key is mapped to anything else, it will
524 In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW
533 ------------------------------
547 0x6000		KEYBOARD: Numlock key pressed
548 0x6005		KEYBOARD: Fn key pressed (TO BE VERIFIED)
561 0x3006		Bay hotplug request (hint to power up SATA link when
564 0x4010		Docked into hotplug port replicator (non-ACPI dock)
565 0x4011		Undocked from hotplug port replicator (non-ACPI dock)
581 cleanly (0x2413) before power is lost.  They must be acted upon, as the
611 ---------
623 so it is kept across reboots and power-off.
631 	echo disable > /proc/acpi/ibm/bluetooth
637 	disabled through the "bluetooth_enable" thinkpad-acpi device
642 		- 0: disables Bluetooth / Bluetooth is disabled
643 		- 1: enables Bluetooth / Bluetooth is enabled.
650 	Documentation/driver-api/rfkill.rst for details.
653 Video output control -- /proc/acpi/ibm/video
654 --------------------------------------------
656 This feature allows control over the devices used for video output -
686 (it simulates the behavior of Fn-F7).
695 Fn-F7 from working. This also disables the video output switching
697 Fn-F7. Video switching on the console should still work.
703 ------------------
723 documentation, in Documentation/leds/leds-class.rst.  The ThinkLight LED name
727 cannot be read or if it is unknown, thinkpad-acpi will report it as "off".
732 -----------------
752 	- 0 - Related to "Volume down" key press
753 	- 1 - Related to "Volume up" key press
754 	- 2 - Related to "Mute on" key press
755 	- 3 - Related to "Access IBM" key press
756 	- 4 - Related to "LCD brightness up" key press
757 	- 5 - Related to "LCD brightness down" key press
758 	- 11 - Related to "toggle screen expansion" key press/function
759 	- 12 - Related to "ThinkLight on"
760 	- 13 - Related to "ThinkLight off"
761 	- 14 - Related to "ThinkLight" key press (toggle ThinkLight)
763 The cmos command interface is prone to firmware split-brain problems, as
769 -----------
785 Unrestricted access to all LEDs requires that thinkpad-acpi be
791 visible to userspace. They are used by the snd-hda-intel audio driver.
806 	- 0 - power
807 	- 1 - battery (orange)
808 	- 2 - battery (green)
809 	- 3 - UltraBase/dock
810 	- 4 - UltraBay
811 	- 5 - UltraBase battery slot
812 	- 6 - (unknown)
813 	- 7 - standby
814 	- 8 - dock status 1
815 	- 9 - dock status 2
816 	- 10, 11 - (unknown)
817 	- 12 - thinkvantage
818 	- 13, 14, 15 - (unknown)
826 documentation, in Documentation/leds/leds-class.rst.
829 "tpacpi::power", "tpacpi:orange:batt", "tpacpi:green:batt",
836 indicators cannot be read due to an error, thinkpad-acpi will report it as
852 a report to ibm-acpi-devel@lists.sourceforge.net is appreciated.
855 ACPI sounds -- /proc/acpi/ibm/beep
856 ----------------------------------
862 The commands are non-negative integer numbers::
870 	- 0 - stop a sound in progress (but use 17 to stop 16)
871 	- 2 - two beeps, pause, third beep ("low battery")
872 	- 3 - single beep
873 	- 4 - high, followed by low-pitched beep ("unable")
874 	- 5 - single beep
875 	- 6 - very high, followed by high-pitched beep ("AC/DC")
876 	- 7 - high-pitched beep
877 	- 9 - three short beeps
878 	- 10 - very long beep
879 	- 12 - low-pitched beep
880 	- 15 - three high-pitched beeps repeating constantly, stop with 0
881 	- 16 - one medium-pitched beep repeating constantly, stop with 17
882 	- 17 - stop 16
886 -------------------
900 	42 42 45 41 36 -128 33 -128
905 	48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
908 system-board model (and thus, on ThinkPad model).
915 - 1:  CPU
916 - 2:  (depends on model)
917 - 3:  (depends on model)
918 - 4:  GPU
919 - 5:  Main battery: main sensor
920 - 6:  Bay battery: main sensor
921 - 7:  Main battery: secondary sensor
922 - 8:  Bay battery: secondary sensor
923 - 9-15: (depends on model)
927 - 2:  Mini-PCI
928 - 3:  Internal HDD
933 - 2:  System board, left side (near PCMCIA slot), reported as HDAPS temp
934 - 3:  PCMCIA slot
935 - 9:  MCH (northbridge) to DRAM Bus
936 - 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
938 - 11: Power regulator, underside of system board, below F2 key
943 - 1:  CPU
944 - 2:  Main Battery: main sensor
945 - 3:  Power Converter
946 - 4:  Bay Battery: main sensor
947 - 5:  MCH (northbridge)
948 - 6:  PCMCIA/ambient
949 - 7:  Main Battery: secondary sensor
950 - 8:  Bay Battery: secondary sensor
956 	Readings from sensors that are not available return -128.
966 	thinkpad-acpi thermal sensors are reported through the hwmon
971 -----------------------------------------------
981 	- make sure the battery is fully charged
982 	- make sure the fan is running
983 	- use above mentioned tool to read out the EC
990 embedded controller registers - e.g. make sure nothing else changes
998 ----------------------
1032 ThinkPad-specific interface.  The driver will disable its native
1036 If you want to use the thinkpad-acpi backlight brightness control
1074 		driver is trying to set the display to when "power" is set
1076 		power management event.
1078 	power:
1079 		power management mode, where 0 is "display on", and 1 to 3
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
1089     Whatever you do, do NOT ever call thinkpad-acpi backlight-level change
1090     interface and the ACPI-based backlight level change interface
1098 --------------------------------------
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.
1112 the desktop environment to just provide on-screen-display feedback.
1120 ThinkPads have a built-in amplifier and muting circuit that drives the
1134 2. Press either volume key to unmute the ThinkPad (it will _not_
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
1142 The IBM ThinkPads, and the earlier Lenovo ThinkPads have variable-gain
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
1157 The ThinkPad-ACPI volume control
1178 whether your thinkpad has volume control or mute-only control:
1183 please report this to ibm-acpi-devel@lists.sourceforge.net, so that we
1193 ibm-acpi-devel@lists.sourceforge.net.
1196 mixer is disabled, the driver will disable all volume functionality.
1199 Fan control and monitoring: fan speed, fan enable/disable
1200 ---------------------------------------------------------
1211    must be given to thinkpad-acpi.
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,
1240 commands.  The full-speed level may take up to two minutes to ramp up to
1242 while the EC is transitioning to the full-speed level.
1262 through thinkpad-acpi.
1264 The thinkpad-acpi kernel driver can be programmed to revert the fan
1266 fan commands: "enable", "disable", "level" or "watchdog", or if there
1275 means other than the "enable", "disable", and "level" procfs fan
1284 	echo disable >/proc/acpi/ibm/fan
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
1315 If you want to disable the watchdog, use 0 as the interval.
1325 is out-of-bounds, and EPERM if it is forbidden.  They may also return
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)
1339 	mode is unsupported, it will return -EINVAL.
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
1372 ---
1380 This feature shows the presence and current state of the built-in
1384 so it is kept across reboots and power-off.
1392 If the W-WAN card is installed, the following commands can be used::
1395 	echo disable > /proc/acpi/ibm/wan
1400 	If the W-WAN card is installed, it can be enabled /
1401 	disabled through the "wwan_enable" thinkpad-acpi device
1405 		- 0: disables WWAN card / WWAN card is disabled
1406 		- 1: enables WWAN card / WWAN card is enabled.
1413 	Documentation/driver-api/rfkill.rst for details.
1417 ------------------
1439 -------------------
1445 to decide if WWAN transmission can be increased to maximum power and is
1449 The property is read-only. If the platform doesn't have support the sysfs
1453 -----------------
1469 	Documentation/driver-api/rfkill.rst for details.
1473 -------------------------
1482 language to ECFW and then these key's will work correctly.
1490 fr(French), fr-ch(French(Switzerland)), hu(Hungarian), it(Italy), jp (Japan),
1495 -----------------
1508 - type a
1509 - type b
1511 The property is read-only. If the platform doesn't have support the sysfs
1515 -----------------
1523 - 0 = Home mode
1524 - 1 = Web-browser mode
1525 - 2 = Web-conference mode
1526 - 3 = Function mode
1527 - 4 = Layflat mode
1534 ----------------------
1548 Documentation/ABI/testing/sysfs-class-power.
1551 ------------------------------------
1559 Commands can also be specified when loading the thinkpad-acpi module,
1566 -------------------------
1600 -----------------------
1602 If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify
1604 not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
1613 0x000200:	Hot key support for 32 hot keys, and radio slider switch
1617 		and the driver enables hot key handling by default in
1622 		and the hwmon class for libsensors4 (lm-sensors 3)
1626 0x020100:	Marker for thinkpad-acpi with hot key NVRAM polling
1631 0x020101:	Marker for thinkpad-acpi with hot key NVRAM polling
1640 0x020300:	hotkey enable/disable support removed, attributes
1649 		and it is always able to disable hot keys.  Very old
1655 0x020700:	Support for mute-only mixers.
1656 		Volume control in read-only mode by default.