1 ThinkPad ACPI Extras Driver
6 Borislav Deianov <borislav@users.sf.net>
7 Henrique de Moraes Holschuh <hmh@hmh.eng.br>
8 http://ibm-acpi.sf.net/
11 This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
12 supports various features of these laptops which are accessible
13 through the ACPI and ACPI EC framework, but not otherwise fully
14 supported by the generic Linux ACPI drivers.
16 This driver used to be named ibm-acpi until kernel 2.6.21 and release
17 0.13-20070314. It used to be in the drivers/acpi tree, but it was
18 moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel
19 2.6.22, and release 0.14.
25 The features currently supported are the following (see below for
26 detailed description):
29 - Bluetooth enable and disable
30 - video output switching, expansion control
31 - ThinkLight on and off
32 - limited docking and undocking
38 - Experimental: embedded controller register dump
39 - LCD brightness control
41 - Fan control and monitoring: fan speed, fan enable/disable
42 - Experimental: WAN enable and disable
44 A compatibility table by model and feature is maintained on the web
45 site, http://ibm-acpi.sf.net/. I appreciate any success or failure
46 reports, especially if they add to or correct the compatibility table.
47 Please include the following information in your report:
50 - a copy of your DSDT, from /proc/acpi/dsdt
51 - a copy of the output of dmidecode, with serial numbers
53 - which driver features work and which don't
54 - the observed behavior of non-working features
56 Any other comments or patches are also more than welcome.
62 If you are compiling this driver as included in the Linux kernel
63 sources, simply enable the CONFIG_THINKPAD_ACPI option, and optionally
64 enable the CONFIG_THINKPAD_ACPI_BAY option if you want the
65 thinkpad-specific bay functionality.
70 The driver exports two different interfaces to userspace, which can be
71 used to access the features it provides. One is a legacy procfs-based
72 interface, which will be removed at some time in the distant future.
73 The other is a new sysfs-based interface which is not complete yet.
75 The procfs interface creates the /proc/acpi/ibm directory. There is a
76 file under that directory for each feature it supports. The procfs
77 interface is mostly frozen, and will change very little if at all: it
78 will not be extended to add any new functionality in the driver, instead
79 all new functionality will be implemented on the sysfs interface.
81 The sysfs interface tries to blend in the generic Linux sysfs subsystems
82 and classes as much as possible. Since some of these subsystems are not
83 yet ready or stabilized, it is expected that this interface will change,
84 and any and all userspace programs must deal with it.
87 Notes about the sysfs interface:
89 Unlike what was done with the procfs interface, correctness when talking
90 to the sysfs interfaces will be enforced, as will correctness in the
91 thinkpad-acpi's implementation of sysfs interfaces.
93 Also, any bugs in the thinkpad-acpi sysfs driver code or in the
94 thinkpad-acpi's implementation of the sysfs interfaces will be fixed for
95 maximum correctness, even if that means changing an interface in
96 non-compatible ways. As these interfaces mature both in the kernel and
97 in thinkpad-acpi, such changes should become quite rare.
99 Applications interfacing to the thinkpad-acpi sysfs interfaces must
100 follow all sysfs guidelines and correctly process all errors (the sysfs
101 interface makes extensive use of errors). File descriptors and open /
102 close operations to the sysfs inodes must also be properly implemented.
104 The version of thinkpad-acpi's sysfs interface is exported by the driver
105 as a driver attribute (see below).
107 Sysfs driver attributes are on the driver's sysfs attribute space,
108 for 2.6.20 this is /sys/bus/platform/drivers/thinkpad-acpi/.
110 Sysfs device attributes are on the driver's sysfs attribute space,
111 for 2.6.20 this is /sys/devices/platform/thinkpad-acpi/.
116 procfs: /proc/acpi/ibm/driver
117 sysfs driver attribute: version
119 The driver name and version. No commands can be written to this file.
121 Sysfs interface version
122 -----------------------
124 sysfs driver attribute: interface_version
126 Version of the thinkpad-acpi sysfs interface, as an unsigned long
127 (output in hex format: 0xAAAABBCC), where:
128 AAAA - major revision
132 The sysfs interface version changelog for the driver can be found at the
133 end of this document. Changes to the sysfs interface done by the kernel
134 subsystems are not documented here, nor are they tracked by this
140 procfs: /proc/acpi/ibm/hotkey
141 sysfs device attribute: hotkey_*
143 Without this driver, only the Fn-F4 key (sleep button) generates an
144 ACPI event. With the driver loaded, the hotkey feature enabled and the
145 mask set (see below), the various hot keys generate ACPI events in the
148 ibm/hotkey HKEY 00000080 0000xxxx
150 The last four digits vary depending on the key combination pressed.
151 All labeled Fn-Fx key combinations generate distinct events. In
152 addition, the lid microswitch and some docking station buttons may
153 also generate such events.
155 The bit mask allows some control over which hot keys generate ACPI
156 events. Not all bits in the mask can be modified. Not all bits that can
157 be modified do anything. Not all hot keys can be individually controlled
158 by the mask. Some models do not support the mask at all. On those
159 models, hot keys cannot be controlled individually.
161 Note that enabling ACPI events for some keys prevents their default
162 behavior. For example, if events for Fn-F5 are enabled, that key will no
163 longer enable/disable Bluetooth by itself. This can still be done from
164 an acpid handler for the ibm/hotkey event.
166 On some models, even enabling/disabling the entire hot key feature may
167 change the way some keys behave (e.g. in a T43, Fn+F4 will generate an
168 button/sleep ACPI event if hot keys are disabled, and it will ignore its
169 mask when hot keys are enabled, so the key always does something. On a
170 X40, Fn+F4 respects its mask status, but generates the button/sleep ACPI
171 event if masked off).
173 Note also that not all Fn key combinations are supported through
174 ACPI. For example, on the X40, the brightness, volume and "Access IBM"
175 buttons do not generate ACPI events even with this driver. They *can*
176 be used through the "ThinkPad Buttons" utility, see
177 http://www.nongnu.org/tpb/
181 The following commands can be written to the /proc/acpi/ibm/hotkey file:
183 echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature
184 echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature
185 echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
186 echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
187 ... any other 8-hex-digit mask ...
188 echo reset > /proc/acpi/ibm/hotkey -- restore the original mask
193 Returns the status of the hot keys feature when
194 thinkpad-acpi was loaded. Upon module unload, the hot
195 key feature status will be restored to this value.
197 0: hot keys were disabled
198 1: hot keys were enabled
201 Returns the hot keys mask when thinkpad-acpi was loaded.
202 Upon module unload, the hot keys mask will be restored
206 Enables/disables the hot keys feature, and reports
207 current status of the hot keys feature.
209 0: disables the hot keys feature / feature disabled
210 1: enables the hot keys feature / feature enabled
213 bit mask to enable ACPI event generation for each hot
214 key (see above). Returns the current status of the hot
215 keys mask, and allows one to modify it.
221 procfs: /proc/acpi/ibm/bluetooth
222 sysfs device attribute: bluetooth_enable
224 This feature shows the presence and current state of a ThinkPad
225 Bluetooth device in the internal ThinkPad CDC slot.
229 If Bluetooth is installed, the following commands can be used:
231 echo enable > /proc/acpi/ibm/bluetooth
232 echo disable > /proc/acpi/ibm/bluetooth
236 If the Bluetooth CDC card is installed, it can be enabled /
237 disabled through the "bluetooth_enable" thinkpad-acpi device
238 attribute, and its current status can also be queried.
241 0: disables Bluetooth / Bluetooth is disabled
242 1: enables Bluetooth / Bluetooth is enabled.
244 Note: this interface will be probably be superseeded by the
245 generic rfkill class, so it is NOT to be considered stable yet.
247 Video output control -- /proc/acpi/ibm/video
248 --------------------------------------------
250 This feature allows control over the devices used for video output -
251 LCD, CRT or DVI (if available). The following commands are available:
253 echo lcd_enable > /proc/acpi/ibm/video
254 echo lcd_disable > /proc/acpi/ibm/video
255 echo crt_enable > /proc/acpi/ibm/video
256 echo crt_disable > /proc/acpi/ibm/video
257 echo dvi_enable > /proc/acpi/ibm/video
258 echo dvi_disable > /proc/acpi/ibm/video
259 echo auto_enable > /proc/acpi/ibm/video
260 echo auto_disable > /proc/acpi/ibm/video
261 echo expand_toggle > /proc/acpi/ibm/video
262 echo video_switch > /proc/acpi/ibm/video
264 Each video output device can be enabled or disabled individually.
265 Reading /proc/acpi/ibm/video shows the status of each device.
267 Automatic video switching can be enabled or disabled. When automatic
268 video switching is enabled, certain events (e.g. opening the lid,
269 docking or undocking) cause the video output device to change
270 automatically. While this can be useful, it also causes flickering
271 and, on the X40, video corruption. By disabling automatic switching,
272 the flickering or video corruption can be avoided.
274 The video_switch command cycles through the available video outputs
275 (it simulates the behavior of Fn-F7).
277 Video expansion can be toggled through this feature. This controls
278 whether the display is expanded to fill the entire LCD screen when a
279 mode with less than full resolution is used. Note that the current
280 video expansion status cannot be determined through this feature.
282 Note that on many models (particularly those using Radeon graphics
283 chips) the X driver configures the video card in a way which prevents
284 Fn-F7 from working. This also disables the video output switching
285 features of this driver, as it uses the same ACPI methods as
286 Fn-F7. Video switching on the console should still work.
288 UPDATE: There's now a patch for the X.org Radeon driver which
289 addresses this issue. Some people are reporting success with the patch
290 while others are still having problems. For more information:
292 https://bugs.freedesktop.org/show_bug.cgi?id=2000
294 ThinkLight control -- /proc/acpi/ibm/light
295 ------------------------------------------
297 The current status of the ThinkLight can be found in this file. A few
298 models which do not make the status available will show it as
299 "unknown". The available commands are:
301 echo on > /proc/acpi/ibm/light
302 echo off > /proc/acpi/ibm/light
304 Docking / undocking -- /proc/acpi/ibm/dock
305 ------------------------------------------
307 Docking and undocking (e.g. with the X4 UltraBase) requires some
308 actions to be taken by the operating system to safely make or break
309 the electrical connections with the dock.
311 The docking feature of this driver generates the following ACPI events:
313 ibm/dock GDCK 00000003 00000001 -- eject request
314 ibm/dock GDCK 00000003 00000002 -- undocked
315 ibm/dock GDCK 00000000 00000003 -- docked
317 NOTE: These events will only be generated if the laptop was docked
318 when originally booted. This is due to the current lack of support for
319 hot plugging of devices in the Linux ACPI framework. If the laptop was
320 booted while not in the dock, the following message is shown in the
323 Mar 17 01:42:34 aero kernel: thinkpad_acpi: dock device not present
325 In this case, no dock-related events are generated but the dock and
326 undock commands described below still work. They can be executed
327 manually or triggered by Fn key combinations (see the example acpid
328 configuration files included in the driver tarball package available
331 When the eject request button on the dock is pressed, the first event
332 above is generated. The handler for this event should issue the
335 echo undock > /proc/acpi/ibm/dock
337 After the LED on the dock goes off, it is safe to eject the laptop.
338 Note: if you pressed this key by mistake, go ahead and eject the
339 laptop, then dock it back in. Otherwise, the dock may not function as
342 When the laptop is docked, the third event above is generated. The
343 handler for this event should issue the following command to fully
346 echo dock > /proc/acpi/ibm/dock
348 The contents of the /proc/acpi/ibm/dock file shows the current status
349 of the dock, as provided by the ACPI framework.
351 The docking support in this driver does not take care of enabling or
352 disabling any other devices you may have attached to the dock. For
353 example, a CD drive plugged into the UltraBase needs to be disabled or
354 enabled separately. See the provided example acpid configuration files
355 for how this can be accomplished.
357 There is no support yet for PCI devices that may be attached to a
358 docking station, e.g. in the ThinkPad Dock II. The driver currently
359 does not recognize, enable or disable such devices. This means that
360 the only docking stations currently supported are the X-series
361 UltraBase docks and "dumb" port replicators like the Mini Dock (the
362 latter don't need any ACPI support, actually).
364 UltraBay eject -- /proc/acpi/ibm/bay
365 ------------------------------------
367 Inserting or ejecting an UltraBay device requires some actions to be
368 taken by the operating system to safely make or break the electrical
369 connections with the device.
371 This feature generates the following ACPI events:
373 ibm/bay MSTR 00000003 00000000 -- eject request
374 ibm/bay MSTR 00000001 00000000 -- eject lever inserted
376 NOTE: These events will only be generated if the UltraBay was present
377 when the laptop was originally booted (on the X series, the UltraBay
378 is in the dock, so it may not be present if the laptop was undocked).
379 This is due to the current lack of support for hot plugging of devices
380 in the Linux ACPI framework. If the laptop was booted without the
381 UltraBay, the following message is shown in the logs:
383 Mar 17 01:42:34 aero kernel: thinkpad_acpi: bay device not present
385 In this case, no bay-related events are generated but the eject
386 command described below still works. It can be executed manually or
387 triggered by a hot key combination.
389 Sliding the eject lever generates the first event shown above. The
390 handler for this event should take whatever actions are necessary to
391 shut down the device in the UltraBay (e.g. call idectl), then issue
392 the following command:
394 echo eject > /proc/acpi/ibm/bay
396 After the LED on the UltraBay goes off, it is safe to pull out the
399 When the eject lever is inserted, the second event above is
400 generated. The handler for this event should take whatever actions are
401 necessary to enable the UltraBay device (e.g. call idectl).
403 The contents of the /proc/acpi/ibm/bay file shows the current status
404 of the UltraBay, as provided by the ACPI framework.
406 EXPERIMENTAL warm eject support on the 600e/x, A22p and A3x (To use
407 this feature, you need to supply the experimental=1 parameter when
410 These models do not have a button near the UltraBay device to request
411 a hot eject but rather require the laptop to be put to sleep
412 (suspend-to-ram) before the bay device is ejected or inserted).
413 The sequence of steps to eject the device is as follows:
415 echo eject > /proc/acpi/ibm/bay
416 put the ThinkPad to sleep
419 cat /proc/acpi/ibm/bay should show that the drive was removed
421 On the A3x, both the UltraBay 2000 and UltraBay Plus devices are
422 supported. Use "eject2" instead of "eject" for the second bay.
424 Note: the UltraBay eject support on the 600e/x, A22p and A3x is
425 EXPERIMENTAL and may not work as expected. USE WITH CAUTION!
430 procfs: /proc/acpi/ibm/cmos
431 sysfs device attribute: cmos_command
433 This feature is used internally by the ACPI firmware to control the
434 ThinkLight on most newer ThinkPad models. It may also control LCD
435 brightness, sounds volume and more, but only on some models.
437 The range of valid cmos command numbers is 0 to 21, but not all have an
438 effect and the behavior varies from model to model. Here is the behavior
439 on the X40 (tpb is the ThinkPad Buttons utility):
441 0 - no effect but tpb reports "Volume down"
442 1 - no effect but tpb reports "Volume up"
443 2 - no effect but tpb reports "Mute on"
444 3 - simulate pressing the "Access IBM" button
445 4 - LCD brightness up
446 5 - LCD brightness down
447 11 - toggle screen expansion
450 14 - no effect but tpb reports ThinkLight status change
452 The cmos command interface is prone to firmware split-brain problems, as
453 in newer ThinkPads it is just a compatibility layer.
455 LED control -- /proc/acpi/ibm/led
456 ---------------------------------
458 Some of the LED indicators can be controlled through this feature. The
459 available commands are:
461 echo '<led number> on' >/proc/acpi/ibm/led
462 echo '<led number> off' >/proc/acpi/ibm/led
463 echo '<led number> blink' >/proc/acpi/ibm/led
465 The <led number> range is 0 to 7. The set of LEDs that can be
466 controlled varies from model to model. Here is the mapping on the X40:
475 All of the above can be turned on and off and can be made to blink.
477 ACPI sounds -- /proc/acpi/ibm/beep
478 ----------------------------------
480 The BEEP method is used internally by the ACPI firmware to provide
481 audible alerts in various situations. This feature allows the same
482 sounds to be triggered manually.
484 The commands are non-negative integer numbers:
486 echo <number> >/proc/acpi/ibm/beep
488 The valid <number> range is 0 to 17. Not all numbers trigger sounds
489 and the sounds vary from model to model. Here is the behavior on the
492 0 - stop a sound in progress (but use 17 to stop 16)
493 2 - two beeps, pause, third beep ("low battery")
495 4 - high, followed by low-pitched beep ("unable")
497 6 - very high, followed by high-pitched beep ("AC/DC")
498 7 - high-pitched beep
499 9 - three short beeps
501 12 - low-pitched beep
502 15 - three high-pitched beeps repeating constantly, stop with 0
503 16 - one medium-pitched beep repeating constantly, stop with 17
509 procfs: /proc/acpi/ibm/thermal
510 sysfs device attributes: (hwmon) temp*_input
512 Most ThinkPads include six or more separate temperature sensors but
513 only expose the CPU temperature through the standard ACPI methods.
514 This feature shows readings from up to eight different sensors on older
515 ThinkPads, and it has experimental support for up to sixteen different
516 sensors on newer ThinkPads.
518 EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the
519 implementation directly accesses hardware registers and may not work as
520 expected. USE WITH CAUTION! To use this feature, you need to supply the
521 experimental=1 parameter when loading the module. When EXPERIMENTAL
522 mode is enabled, reading the first 8 sensors on newer ThinkPads will
523 also use an new experimental thermal sensor access mode.
525 For example, on the X40, a typical output may be:
526 temperatures: 42 42 45 41 36 -128 33 -128
528 EXPERIMENTAL: On the T43/p, a typical output may be:
529 temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
531 The mapping of thermal sensors to physical locations varies depending on
532 system-board model (and thus, on ThinkPad model).
534 http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
535 tries to track down these locations for various models.
537 Most (newer?) models seem to follow this pattern:
540 2: (depends on model)
541 3: (depends on model)
543 5: Main battery: main sensor
544 6: Bay battery: main sensor
545 7: Main battery: secondary sensor
546 8: Bay battery: secondary sensor
547 9-15: (depends on model)
549 For the R51 (source: Thomas Gruber):
553 For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
554 http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
555 2: System board, left side (near PCMCIA slot), reported as HDAPS temp
557 9: MCH (northbridge) to DRAM Bus
558 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
560 11: Power regulator, underside of system board, below F2 key
562 The A31 has a very atypical layout for the thermal sensors
563 (source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
565 2: Main Battery: main sensor
567 4: Bay Battery: main sensor
570 7: Main Battery: secondary sensor
571 8: Bay Battery: secondary sensor
575 Readings from sensors that are not available return -128.
576 No commands can be written to this file.
579 Sensors that are not available return the ENXIO error. This
580 status may change at runtime, as there are hotplug thermal
581 sensors, like those inside the batteries and docks.
583 thinkpad-acpi thermal sensors are reported through the hwmon
584 subsystem, and follow all of the hwmon guidelines at
588 EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump
589 ------------------------------------------------------------------------
591 This feature is marked EXPERIMENTAL because the implementation
592 directly accesses hardware registers and may not work as expected. USE
593 WITH CAUTION! To use this feature, you need to supply the
594 experimental=1 parameter when loading the module.
596 This feature dumps the values of 256 embedded controller
597 registers. Values which have changed since the last time the registers
598 were dumped are marked with a star:
600 [root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
601 EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
602 EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00
603 EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00
604 EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80
605 EC 0x30: 01 07 1a 00 30 04 00 00 *85 00 00 10 00 50 00 00
606 EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00
607 EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 *bc *02 *bc
608 EC 0x60: *02 *bc *02 00 00 00 00 00 00 00 00 00 00 00 00 00
609 EC 0x70: 00 00 00 00 00 12 30 40 *24 *26 *2c *27 *20 80 *1f 80
610 EC 0x80: 00 00 00 06 *37 *0e 03 00 00 00 0e 07 00 00 00 00
611 EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
612 EC 0xa0: *ff 09 ff 09 ff ff *64 00 *00 *00 *a2 41 *ff *ff *e0 00
613 EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
614 EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
615 EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
616 EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03
617 EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a
619 This feature can be used to determine the register holding the fan
620 speed on some models. To do that, do the following:
622 - make sure the battery is fully charged
623 - make sure the fan is running
624 - run 'cat /proc/acpi/ibm/ecdump' several times, once per second or so
626 The first step makes sure various charging-related values don't
627 vary. The second ensures that the fan-related values do vary, since
628 the fan speed fluctuates a bit. The third will (hopefully) mark the
629 fan register with a star:
631 [root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
632 EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
633 EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00
634 EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00
635 EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80
636 EC 0x30: 01 07 1a 00 30 04 00 00 85 00 00 10 00 50 00 00
637 EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00
638 EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 bc 02 bc
639 EC 0x60: 02 bc 02 00 00 00 00 00 00 00 00 00 00 00 00 00
640 EC 0x70: 00 00 00 00 00 12 30 40 24 27 2c 27 21 80 1f 80
641 EC 0x80: 00 00 00 06 *be 0d 03 00 00 00 0e 07 00 00 00 00
642 EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
643 EC 0xa0: ff 09 ff 09 ff ff 64 00 00 00 a2 41 ff ff e0 00
644 EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
645 EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
646 EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
647 EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03
648 EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a
650 Another set of values that varies often is the temperature
651 readings. Since temperatures don't change vary fast, you can take
652 several quick dumps to eliminate them.
654 You can use a similar method to figure out the meaning of other
655 embedded controller registers - e.g. make sure nothing else changes
656 except the charging or discharging battery to determine which
657 registers contain the current battery capacity, etc. If you experiment
658 with this, do send me your results (including some complete dumps with
659 a description of the conditions when they were taken.)
661 LCD brightness control
662 ----------------------
664 procfs: /proc/acpi/ibm/brightness
665 sysfs backlight device "thinkpad_screen"
667 This feature allows software control of the LCD brightness on ThinkPad
668 models which don't have a hardware brightness slider.
670 It has some limitations: the LCD backlight cannot be actually turned on or off
671 by this interface, and in many ThinkPad models, the "dim while on battery"
672 functionality will be enabled by the BIOS when this interface is used, and
673 cannot be controlled.
675 The backlight control has eight levels, ranging from 0 to 7. Some of the
676 levels may not be distinct.
680 The available commands are:
682 echo up >/proc/acpi/ibm/brightness
683 echo down >/proc/acpi/ibm/brightness
684 echo 'level <level>' >/proc/acpi/ibm/brightness
688 The interface is implemented through the backlight sysfs class, which is poorly
689 documented at this time.
691 Locate the thinkpad_screen device under /sys/class/backlight, and inside it
692 there will be the following attributes:
695 Reads the maximum brightness the hardware can be set to.
696 The minimum is always zero.
699 Reads what brightness the screen is set to at this instant.
702 Writes request the driver to change brightness to the given
703 value. Reads will tell you what brightness the driver is trying
704 to set the display to when "power" is set to zero and the display
705 has not been dimmed by a kernel power management event.
708 power management mode, where 0 is "display on", and 1 to 3 will
709 dim the display backlight to brightness level 0 because
710 thinkpad-acpi cannot really turn the backlight off. Kernel
711 power management events can temporarily increase the current
712 power management level, i.e. they can dim the display.
715 Volume control -- /proc/acpi/ibm/volume
716 ---------------------------------------
718 This feature allows volume control on ThinkPad models which don't have
719 a hardware volume knob. The available commands are:
721 echo up >/proc/acpi/ibm/volume
722 echo down >/proc/acpi/ibm/volume
723 echo mute >/proc/acpi/ibm/volume
724 echo 'level <level>' >/proc/acpi/ibm/volume
726 The <level> number range is 0 to 15 although not all of them may be
727 distinct. The unmute the volume after the mute command, use either the
728 up or down command (the level command will not unmute the volume).
729 The current volume level and mute state is shown in the file.
731 Fan control and monitoring: fan speed, fan enable/disable
732 ---------------------------------------------------------
734 procfs: /proc/acpi/ibm/fan
735 sysfs device attributes: (hwmon) fan_input, pwm1, pwm1_enable
737 NOTE NOTE NOTE: fan control operations are disabled by default for
738 safety reasons. To enable them, the module parameter "fan_control=1"
739 must be given to thinkpad-acpi.
741 This feature attempts to show the current fan speed, control mode and
742 other fan data that might be available. The speed is read directly
743 from the hardware registers of the embedded controller. This is known
744 to work on later R, T, X and Z series ThinkPads but may show a bogus
745 value on other models.
749 Most ThinkPad fans work in "levels" at the firmware interface. Level 0
750 stops the fan. The higher the level, the higher the fan speed, although
751 adjacent levels often map to the same fan speed. 7 is the highest
752 level, where the fan reaches the maximum recommended speed.
754 Level "auto" means the EC changes the fan level according to some
755 internal algorithm, usually based on readings from the thermal sensors.
757 There is also a "full-speed" level, also known as "disengaged" level.
758 In this level, the EC disables the speed-locked closed-loop fan control,
759 and drives the fan as fast as it can go, which might exceed hardware
760 limits, so use this level with caution.
762 The fan usually ramps up or down slowly from one speed to another, and
763 it is normal for the EC to take several seconds to react to fan
764 commands. The full-speed level may take up to two minutes to ramp up to
765 maximum speed, and in some ThinkPads, the tachometer readings go stale
766 while the EC is transitioning to the full-speed level.
768 WARNING WARNING WARNING: do not leave the fan disabled unless you are
769 monitoring all of the temperature sensor readings and you are ready to
770 enable it if necessary to avoid overheating.
772 An enabled fan in level "auto" may stop spinning if the EC decides the
773 ThinkPad is cool enough and doesn't need the extra airflow. This is
774 normal, and the EC will spin the fan up if the varios thermal readings
777 On the X40, this seems to depend on the CPU and HDD temperatures.
778 Specifically, the fan is turned on when either the CPU temperature
779 climbs to 56 degrees or the HDD temperature climbs to 46 degrees. The
780 fan is turned off when the CPU temperature drops to 49 degrees and the
781 HDD temperature drops to 41 degrees. These thresholds cannot
782 currently be controlled.
784 The ThinkPad's ACPI DSDT code will reprogram the fan on its own when
785 certain conditions are met. It will override any fan programming done
786 through thinkpad-acpi.
788 The thinkpad-acpi kernel driver can be programmed to revert the fan
789 level to a safe setting if userspace does not issue one of the procfs
790 fan commands: "enable", "disable", "level" or "watchdog", or if there
791 are no writes to pwm1_enable (or to pwm1 *if and only if* pwm1_enable is
792 set to 1, manual mode) within a configurable amount of time of up to
793 120 seconds. This functionality is called fan safety watchdog.
795 Note that the watchdog timer stops after it enables the fan. It will be
796 rearmed again automatically (using the same interval) when one of the
797 above mentioned fan commands is received. The fan watchdog is,
798 therefore, not suitable to protect against fan mode changes made through
799 means other than the "enable", "disable", and "level" procfs fan
800 commands, or the hwmon fan control sysfs interface.
804 The fan may be enabled or disabled with the following commands:
806 echo enable >/proc/acpi/ibm/fan
807 echo disable >/proc/acpi/ibm/fan
809 Placing a fan on level 0 is the same as disabling it. Enabling a fan
810 will try to place it in a safe level if it is too slow or disabled.
812 The fan level can be controlled with the command:
814 echo 'level <level>' > /proc/acpi/ibm/fan
816 Where <level> is an integer from 0 to 7, or one of the words "auto" or
817 "full-speed" (without the quotes). Not all ThinkPads support the "auto"
818 and "full-speed" levels. The driver accepts "disengaged" as an alias for
819 "full-speed", and reports it as "disengaged" for backwards
822 On the X31 and X40 (and ONLY on those models), the fan speed can be
823 controlled to a certain degree. Once the fan is running, it can be
824 forced to run faster or slower with the following command:
826 echo 'speed <speed>' > /proc/acpi/ibm/fan
828 The sustainable range of fan speeds on the X40 appears to be from about
829 3700 to about 7350. Values outside this range either do not have any
830 effect or the fan speed eventually settles somewhere in that range. The
831 fan cannot be stopped or started with this command. This functionality
832 is incomplete, and not available through the sysfs interface.
834 To program the safety watchdog, use the "watchdog" command.
836 echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
838 If you want to disable the watchdog, use 0 as the interval.
842 The sysfs interface follows the hwmon subsystem guidelines for the most
843 part, and the exception is the fan safety watchdog.
845 Writes to any of the sysfs attributes may return the EINVAL error if
846 that operation is not supported in a given ThinkPad or if the parameter
847 is out-of-bounds, and EPERM if it is forbidden. They may also return
848 EINTR (interrupted system call), and EIO (I/O error while trying to talk
851 Features not yet implemented by the driver return ENOSYS.
853 hwmon device attribute pwm1_enable:
854 0: PWM offline (fan is set to full-speed mode)
855 1: Manual PWM control (use pwm1 to set fan level)
856 2: Hardware PWM control (EC "auto" mode)
857 3: reserved (Software PWM control, not implemented yet)
859 Modes 0 and 2 are not supported by all ThinkPads, and the
860 driver is not always able to detect this. If it does know a
861 mode is unsupported, it will return -EINVAL.
863 hwmon device attribute pwm1:
864 Fan level, scaled from the firmware values of 0-7 to the hwmon
865 scale of 0-255. 0 means fan stopped, 255 means highest normal
868 This attribute only commands the fan if pmw1_enable is set to 1
869 (manual PWM control).
871 hwmon device attribute fan1_input:
872 Fan tachometer reading, in RPM. May go stale on certain
873 ThinkPads while the EC transitions the PWM to offline mode,
874 which can take up to two minutes. May return rubbish on older
877 driver attribute fan_watchdog:
878 Fan safety watchdog timer interval, in seconds. Minimum is
879 1 second, maximum is 120 seconds. 0 disables the watchdog.
881 To stop the fan: set pwm1 to zero, and pwm1_enable to 1.
883 To start the fan in a safe mode: set pwm1_enable to 2. If that fails
884 with EINVAL, try to set pwm1_enable to 1 and pwm1 to at least 128 (255
885 would be the safest choice, though).
891 procfs: /proc/acpi/ibm/wan
892 sysfs device attribute: wwan_enable
894 This feature is marked EXPERIMENTAL because the implementation
895 directly accesses hardware registers and may not work as expected. USE
896 WITH CAUTION! To use this feature, you need to supply the
897 experimental=1 parameter when loading the module.
899 This feature shows the presence and current state of a W-WAN (Sierra
900 Wireless EV-DO) device.
902 It was tested on a Lenovo Thinkpad X60. It should probably work on other
903 Thinkpad models which come with this module installed.
907 If the W-WAN card is installed, the following commands can be used:
909 echo enable > /proc/acpi/ibm/wan
910 echo disable > /proc/acpi/ibm/wan
914 If the W-WAN card is installed, it can be enabled /
915 disabled through the "wwan_enable" thinkpad-acpi device
916 attribute, and its current status can also be queried.
919 0: disables WWAN card / WWAN card is disabled
920 1: enables WWAN card / WWAN card is enabled.
922 Note: this interface will be probably be superseeded by the
923 generic rfkill class, so it is NOT to be considered stable yet.
925 Multiple Commands, Module Parameters
926 ------------------------------------
928 Multiple commands can be written to the proc files in one shot by
929 separating them with commas, for example:
931 echo enable,0xffff > /proc/acpi/ibm/hotkey
932 echo lcd_disable,crt_enable > /proc/acpi/ibm/video
934 Commands can also be specified when loading the thinkpad-acpi module,
937 modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
939 Enabling debugging output
940 -------------------------
942 The module takes a debug paramater which can be used to selectively
943 enable various classes of debugging output, for example:
945 modprobe ibm_acpi debug=0xffff
947 will enable all debugging output classes. It takes a bitmask, so
948 to enable more than one output class, just add their values.
950 Debug bitmask Description
951 0x0001 Initialization and probing
954 There is also a kernel build option to enable more debugging
955 information, which may be necessary to debug driver problems.
957 The level of debugging information output by the driver can be changed
958 at runtime through sysfs, using the driver attribute debug_level. The
959 attribute takes the same bitmask as the debug module parameter above.
961 Force loading of module
962 -----------------------
964 If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify
965 the module parameter force_load=1. Regardless of whether this works or
966 not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
969 Sysfs interface changelog:
971 0x000100: Initial sysfs support, as a single platform driver and