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
56 	- Auxmac
59 site, http://ibm-acpi.sf.net/. I appreciate any success or failure
63 	- ThinkPad model name
64 	- a copy of your ACPI tables, using the "acpidump" utility
65 	- a copy of the output of dmidecode, with serial numbers
67 	- which driver features work and which don't
68 	- the observed behavior of non-working features
74 ------------
78 It is located on the menu path: "Device Drivers" -> "X86 Platform
79 Specific Device Drivers" -> "ThinkPad ACPI Laptop Extras".
83 --------
86 used to access the features it provides.  One is a legacy procfs-based
88 is a new sysfs-based interface which is not complete yet.
107 thinkpad-acpi's implementation of sysfs interfaces.
109 Also, any bugs in the thinkpad-acpi sysfs driver code or in the
110 thinkpad-acpi's implementation of the sysfs interfaces will be fixed for
112 non-compatible ways.  As these interfaces mature both in the kernel and
113 in thinkpad-acpi, such changes should become quite rare.
115 Applications interfacing to the thinkpad-acpi sysfs interfaces must
120 The version of thinkpad-acpi's sysfs interface is exported by the driver
138 --------------
148 -----------------------
152 Version of the thinkpad-acpi sysfs interface, as an unsigned long
156 	  - major revision
158 	  - minor revision
160 	  - bugfix revision
167 Changes to the thinkpad-acpi sysfs interface are only considered
168 non-experimental when they are submitted to Linux mainline, at which
170 may be updated.  If you are using any thinkpad-acpi features not yet
175 Changes that are backwards-compatible by nature (e.g. the addition of
184 --------
192 system.  Enabling the hotkey functionality of thinkpad-acpi signals the
213 thinkpad-acpi would prefer to handle it, if the firmware would be so
240 	echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
241 	echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
242 	... any other 8-hex-digit mask ...
243 	echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
248 	echo enable > /proc/acpi/ibm/hotkey -- does nothing
249 	echo disable > /proc/acpi/ibm/hotkey -- returns an error
252 maintain maximum bug-to-bug compatibility, it does not report any masks,
267 		Returns the hot keys mask when thinkpad-acpi was loaded.
276 		0: returns -EPERM
302 		poll the NVRAM for.  This is auto-detected by the driver
318 		version -- not just with firmware models -- as well as
354 		undock.  Set to zero for normal wake-ups or wake-ups
392 backwards-compatible way.  The MSB shall always be 0x41 for this input
396 been changed in a non-backwards compatible way.
399 backwards-compatible change for this input device.
401 Thinkpad-acpi Hot Key event map (version 0x4101):
407 0x1001	0x00	FN+F1		-
417 				off the ThinkLight as side-effect
421 				semantics, i.e. sleep-to-RAM).
433 				and W-WAN card if left in control
437 				radios (Bluetooth+W-WAN+WLAN),
440 0x1006	0x05	FN+F6		-
449 0x1009	0x08	FN+F9		-
453 0x100B	0x0A	FN+F11		-
465 0x100D	0x0C	FN+BACKSPACE	-
466 0x100E	0x0D	FN+INSERT	-
467 0x100F	0x0E	FN+DELETE	-
469 0x1010	0x0F	FN+HOME		Brightness up.  This key is
478 0x1011	0x10	FN+END		Brightness down.  See brightness
485 0x1013	0x12	FN+PGDOWN	-
525 In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW
534 ------------------------------
547 0x5010		Brightness level changed/control event
565 0x4010		Docked into hotplug port replicator (non-ACPI dock)
566 0x4011		Undocked from hotplug port replicator (non-ACPI dock)
597 Brightness hotkey notes
600 Don't mess with the brightness hotkeys in a Thinkpad.  If you want
605 implement brightness changes.  When you override these events, you will
607 action to change backlight brightness, or the ThinkPads that require
612 ---------
624 so it is kept across reboots and power-off.
638 	disabled through the "bluetooth_enable" thinkpad-acpi device
643 		- 0: disables Bluetooth / Bluetooth is disabled
644 		- 1: enables Bluetooth / Bluetooth is enabled.
651 	Documentation/driver-api/rfkill.rst for details.
654 Video output control -- /proc/acpi/ibm/video
655 --------------------------------------------
657 This feature allows control over the devices used for video output -
687 (it simulates the behavior of Fn-F7).
696 Fn-F7 from working. This also disables the video output switching
698 Fn-F7. Video switching on the console should still work.
704 ------------------
724 documentation, in Documentation/leds/leds-class.rst.  The ThinkLight LED name
728 cannot be read or if it is unknown, thinkpad-acpi will report it as "off".
733 -----------------
753 	- 0 - Related to "Volume down" key press
754 	- 1 - Related to "Volume up" key press
755 	- 2 - Related to "Mute on" key press
756 	- 3 - Related to "Access IBM" key press
757 	- 4 - Related to "LCD brightness up" key press
758 	- 5 - Related to "LCD brightness down" key press
759 	- 11 - Related to "toggle screen expansion" key press/function
760 	- 12 - Related to "ThinkLight on"
761 	- 13 - Related to "ThinkLight off"
762 	- 14 - Related to "ThinkLight" key press (toggle ThinkLight)
764 The cmos command interface is prone to firmware split-brain problems, as
770 -----------
786 Unrestricted access to all LEDs requires that thinkpad-acpi be
792 visible to userspace. They are used by the snd-hda-intel audio driver.
807 	- 0 - power
808 	- 1 - battery (orange)
809 	- 2 - battery (green)
810 	- 3 - UltraBase/dock
811 	- 4 - UltraBay
812 	- 5 - UltraBase battery slot
813 	- 6 - (unknown)
814 	- 7 - standby
815 	- 8 - dock status 1
816 	- 9 - dock status 2
817 	- 10, 11 - (unknown)
818 	- 12 - thinkvantage
819 	- 13, 14, 15 - (unknown)
827 documentation, in Documentation/leds/leds-class.rst.
837 indicators cannot be read due to an error, thinkpad-acpi will report it as
838 a brightness of zero (same as LED off).
841 trying to read the current LED brightness will just return whatever
842 brightness was last written to that attribute.
853 a report to ibm-acpi-devel@lists.sourceforge.net is appreciated.
856 ACPI sounds -- /proc/acpi/ibm/beep
857 ----------------------------------
863 The commands are non-negative integer numbers::
871 	- 0 - stop a sound in progress (but use 17 to stop 16)
872 	- 2 - two beeps, pause, third beep ("low battery")
873 	- 3 - single beep
874 	- 4 - high, followed by low-pitched beep ("unable")
875 	- 5 - single beep
876 	- 6 - very high, followed by high-pitched beep ("AC/DC")
877 	- 7 - high-pitched beep
878 	- 9 - three short beeps
879 	- 10 - very long beep
880 	- 12 - low-pitched beep
881 	- 15 - three high-pitched beeps repeating constantly, stop with 0
882 	- 16 - one medium-pitched beep repeating constantly, stop with 17
883 	- 17 - stop 16
887 -------------------
901 	42 42 45 41 36 -128 33 -128
906 	48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
909 system-board model (and thus, on ThinkPad model).
916 - 1:  CPU
917 - 2:  (depends on model)
918 - 3:  (depends on model)
919 - 4:  GPU
920 - 5:  Main battery: main sensor
921 - 6:  Bay battery: main sensor
922 - 7:  Main battery: secondary sensor
923 - 8:  Bay battery: secondary sensor
924 - 9-15: (depends on model)
928 - 2:  Mini-PCI
929 - 3:  Internal HDD
934 - 2:  System board, left side (near PCMCIA slot), reported as HDAPS temp
935 - 3:  PCMCIA slot
936 - 9:  MCH (northbridge) to DRAM Bus
937 - 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
939 - 11: Power regulator, underside of system board, below F2 key
944 - 1:  CPU
945 - 2:  Main Battery: main sensor
946 - 3:  Power Converter
947 - 4:  Bay Battery: main sensor
948 - 5:  MCH (northbridge)
949 - 6:  PCMCIA/ambient
950 - 7:  Main Battery: secondary sensor
951 - 8:  Bay Battery: secondary sensor
957 	Readings from sensors that are not available return -128.
967 	thinkpad-acpi thermal sensors are reported through the hwmon
972 -----------------------------------------------
982 	- make sure the battery is fully charged
983 	- make sure the fan is running
984 	- use above mentioned tool to read out the EC
991 embedded controller registers - e.g. make sure nothing else changes
998 LCD brightness control
999 ----------------------
1001 procfs: /proc/acpi/ibm/brightness
1005 This feature allows software control of the LCD brightness on ThinkPad
1006 models which don't have a hardware brightness slider.
1009 on or off by this interface, it just controls the backlight brightness
1010 level.
1013 has eight brightness levels, ranging from 0 to 7.  Some of the levels
1015 display backlight brightness control methods have 16 levels, ranging
1019 brightness control, EC and UCMS (or CMOS).  To select which one should be
1022 mode with NVRAM backing (so that brightness changes are remembered across
1031 When display backlight brightness controls are available through the
1033 ThinkPad-specific interface.  The driver will disable its native
1034 backlight brightness control interface if it detects that the standard
1037 If you want to use the thinkpad-acpi backlight brightness control
1038 instead of the generic ACPI video backlight brightness control for some
1042 the LCD brightness control feature will be enabled when available.
1052 	echo up   >/proc/acpi/ibm/brightness
1053 	echo down >/proc/acpi/ibm/brightness
1054 	echo 'level <level>' >/proc/acpi/ibm/brightness
1066 		Reads the maximum brightness the hardware can be set to.
1070 		Reads what brightness the screen is set to at this instant.
1072 	brightness:
1073 		Writes request the driver to change brightness to the
1074 		given value.  Reads will tell you what brightness the
1081 		will dim the display backlight to brightness level 0
1082 		because thinkpad-acpi cannot really turn the backlight
1084 		increase the current power management level, i.e. they can
1090     Whatever you do, do NOT ever call thinkpad-acpi backlight-level change
1091     interface and the ACPI-based backlight level change interface
1095     its level up and down at every change.
1099 --------------------------------------
1105 NOTE: by default, the volume control interface operates in read-only
1106 mode, as it is supposed to be used for on-screen-display purposes.
1113 the desktop environment to just provide on-screen-display feedback.
1121 ThinkPads have a built-in amplifier and muting circuit that drives the
1138 This is a very superior design when compared to the cheap software-only
1139 mute-toggle solution found on normal consumer laptops:  you can be
1143 The IBM ThinkPads, and the earlier Lenovo ThinkPads have variable-gain
1154 normal key presses to the operating system (thinkpad-acpi is not
1158 The ThinkPad-ACPI volume control
1171 	echo 'level <level>' >/proc/acpi/ibm/volume
1173 The <level> number range is 0 to 14 although not all of them may be
1175 up or down command (the level command will not unmute the volume), or
1179 whether your thinkpad has volume control or mute-only control:
1184 please report this to ibm-acpi-devel@lists.sourceforge.net, so that we
1194 ibm-acpi-devel@lists.sourceforge.net.
1201 ---------------------------------------------------------
1212    must be given to thinkpad-acpi.
1226 Most ThinkPad fans work in "levels" at the firmware interface.  Level 0
1227 stops the fan.  The higher the level, the higher the fan speed, although
1229 level, where the fan reaches the maximum recommended speed.
1231 Level "auto" means the EC changes the fan level according to some
1234 There is also a "full-speed" level, also known as "disengaged" level.
1235 In this level, the EC disables the speed-locked closed-loop fan control,
1237 limits, so use this level with caution.
1241 commands.  The full-speed level may take up to two minutes to ramp up to
1243 while the EC is transitioning to the full-speed level.
1249 An enabled fan in level "auto" may stop spinning if the EC decides the
1263 through thinkpad-acpi.
1265 The thinkpad-acpi kernel driver can be programmed to revert the fan
1266 level to a safe setting if userspace does not issue one of the procfs
1267 fan commands: "enable", "disable", "level" or "watchdog", or if there
1276 means other than the "enable", "disable", and "level" procfs fan
1287 Placing a fan on level 0 is the same as disabling it.  Enabling a fan
1288 will try to place it in a safe level if it is too slow or disabled.
1290 The fan level can be controlled with the command::
1292 	echo 'level <level>' > /proc/acpi/ibm/fan
1294 Where <level> is an integer from 0 to 7, or one of the words "auto" or
1295 "full-speed" (without the quotes).  Not all ThinkPads support the "auto"
1296 and "full-speed" levels.  The driver accepts "disengaged" as an alias for
1297 "full-speed", and reports it as "disengaged" for backwards
1326 is out-of-bounds, and EPERM if it is forbidden.  They may also return
1333 	- 0: PWM offline (fan is set to full-speed mode)
1334 	- 1: Manual PWM control (use pwm1 to set fan level)
1335 	- 2: Hardware PWM control (EC "auto" mode)
1336 	- 3: reserved (Software PWM control, not implemented yet)
1340 	mode is unsupported, it will return -EINVAL.
1343 	Fan level, scaled from the firmware values of 0-7 to the hwmon
1344 	scale of 0-255.  0 means fan stopped, 255 means highest normal
1345 	speed (level 7).
1373 ---
1381 This feature shows the presence and current state of the built-in
1385 so it is kept across reboots and power-off.
1393 If the W-WAN card is installed, the following commands can be used::
1401 	If the W-WAN card is installed, it can be enabled /
1402 	disabled through the "wwan_enable" thinkpad-acpi device
1406 		- 0: disables WWAN card / WWAN card is disabled
1407 		- 1: enables WWAN card / WWAN card is enabled.
1414 	Documentation/driver-api/rfkill.rst for details.
1418 ------------------
1440 -------------------
1450 The property is read-only. If the platform doesn't have support the sysfs
1454 -----------------
1470 	Documentation/driver-api/rfkill.rst for details.
1474 -------------------------
1491 fr(French), fr-ch(French(Switzerland)), hu(Hungarian), it(Italy), jp (Japan),
1496 -----------------
1509 - type a
1510 - type b
1512 The property is read-only. If the platform doesn't have support the sysfs
1516 ------
1520 Some newer Thinkpads have a feature called MAC Address Pass-through. This
1523 network. This property enables user-space to easily determine the MAC address
1532 This property is read-only.
1535 -----------------
1543 - 0 = Home mode
1544 - 1 = Web-browser mode
1545 - 2 = Web-conference mode
1546 - 3 = Function mode
1547 - 4 = Layflat mode
1554 ----------------------
1563 percentage level, below which charging will begin. `charge_control_end_threshold`
1565 percentage level, above which charging will stop.
1568 Documentation/ABI/testing/sysfs-class-power.
1571 ------------------------------------
1579 Commands can also be specified when loading the thinkpad-acpi module,
1586 -------------------------
1607 	0x0020			Backlight brightness
1614 The level of debugging information output by the driver can be changed
1620 -----------------------
1622 If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify
1624 not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
1642 		and the hwmon class for libsensors4 (lm-sensors 3)
1646 0x020100:	Marker for thinkpad-acpi with hot key NVRAM polling
1651 0x020101:	Marker for thinkpad-acpi with hot key NVRAM polling
1675 0x020700:	Support for mute-only mixers.
1676 		Volume control in read-only mode by default.