← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-lowlatency/precise

« back to all changes in this revision

Viewing changes to Documentation/laptops/thinkpad-acpi.txt

  • Committer: Package Import Robot
  • Author(s): Alessio Igor Bogani
  • Date: 2011-10-26 11:13:05 UTC
  • Revision ID: package-import@ubuntu.com-20111026111305-tz023xykf0i6eosh
Tags: upstream-3.2.0
Import upstream version 3.2.0

Show diffs side-by-side

added added

removed removed

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