xref: /dragonfly/share/man/man4/acpi_thinkpad.4 (revision 63ab6604) 
1.\" Copyright (c) 2005 Christian Brueffer
2.\" Copyright (c) 2005 Markus Brueffer
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\" $DragonFly: src/share/man/man4/acpi_thinkpad.4,v 1.6 2008/10/03 10:32:10 swildner Exp $
28.\"
29.Dd October 2, 2008
30.Dt ACPI_THINKPAD 4
31.Os
32.Sh NAME
33.Nm acpi_thinkpad
34.Nd "ACPI extras driver for IBM/Lenovo Thinkpad laptops"
35.Sh SYNOPSIS
36To compile this driver into the kernel,
37place the following line in your
38kernel configuration file:
39.Bd -ragged -offset indent
40.Cd "device acpi_thinkpad"
41.Ed
42.Pp
43Alternatively, to load the driver as a
44module at boot time, place the following line in
45.Xr loader.conf 5 :
46.Bd -literal -offset indent
47acpi_thinkpad_load="YES"
48.Ed
49.Sh DESCRIPTION
50The
51.Nm
52driver provides support for hotkeys and other components of IBM/Lenovo
53Thinkpad laptops.
54The main purpose of this driver is to provide an interface,
55accessible via
56.Xr sysctl 8
57and
58.Xr devd 8 ,
59through which applications can determine the status of
60various laptop components.
61.Pp
62While the
63.Xr sysctl 8
64interface is enabled automatically after loading the driver, the
65.Xr devd 8
66interface has to be enabled explicitly, as it may alter the default action of
67certain keys.
68This is done by setting the
69.Va events
70sysctl as described below.
71Specifying which keys should generate events is done by setting a bitmask,
72whereas each bit represents one key or key combination.
73This bitmask, accessible via the
74.Va eventmask
75sysctl, is set to
76.Va availmask
77by default, a value representing all possible keypress events on the specific
78ThinkPad model.
79.Ss Xr devd 8 Ss Events
80Hotkey events received by
81.Xr devd 8
82provide the following information:
83.Pp
84.Bl -tag -width "subsystem" -offset indent -compact
85.It system
86.Qq Li ACPI
87.It subsystem
88.Qq Li THINKPAD
89.It type
90The source of the event in the ACPI namespace.
91The value depends on the model.
92.It notify
93Event code (see below).
94.El
95.Pp
96Depending on the ThinkPad model, event codes may vary.
97On a ThinkPad T41p these are as follows:
98.Pp
99.Bl -tag -width "subsystem" -offset indent -compact
100.It Li 0x01
101Fn + F1
102.It Li 0x02
103Fn + F2
104.It Li 0x03
105Fn + F3 (LCD backlight)
106.It Li 0x04
107Fn + F4 (Suspend to RAM)
108.It Li 0x05
109Fn + F5 (Bluetooth)
110.It Li 0x06
111Fn + F6
112.It Li 0x07
113Fn + F7 (Screen expand)
114.It Li 0x08
115Fn + F8
116.It Li 0x09
117Fn + F9
118.It Li 0x0a
119Fn + F10
120.It Li 0x0b
121Fn + F11
122.It Li 0x0c
123Fn + F12 (Suspend to disk)
124.It Li 0x0d
125Fn + Backspace
126.It Li 0x0e
127Fn + Insert
128.It Li 0x0f
129Fn + Delete
130.It Li 0x10
131Fn + Home (Brightness up)
132.It Li 0x11
133Fn + End (Brightness down)
134.It Li 0x12
135Fn + PageUp (ThinkLight)
136.It Li 0x13
137Fn + PageDown
138.It Li 0x14
139Fn + Space (Zoom)
140.It Li 0x15
141Volume Up
142.It Li 0x16
143Volume Down
144.It Li 0x17
145Mute
146.It Li 0x18
147Access IBM Button
148.El
149.\" .Ss Xr led 4 Ss Interface
150.\" The
151.\" .Nm
152.\" driver provides a
153.\" .Xr led 4
154.\" interface for the ThinkLight.
155.\" The ThinkLight can be made to blink by writing
156.\" .Tn ASCII
157.\" strings to the
158.\" .Pa /dev/led/thinklight
159.\" device.
160.Sh SYSCTL VARIABLES
161The following sysctls are currently implemented:
162.Bl -tag -width indent
163.It Va dev.acpi_thinkpad.0.initialmask
164(read-only)
165Bitmask of ACPI events before the
166.Nm
167driver was loaded.
168.It Va dev.acpi_thinkpad.0.availmask
169(read-only)
170Bitmask of all supported ACPI events.
171.It Va dev.acpi_thinkpad.0.events
172Enable ACPI events and set the
173.Va eventmask
174to
175.Va availmask .
176Without the
177.Nm
178driver being loaded, only the Fn+F4 button generates an ACPI event.
179.It Va dev.acpi_thinkpad.0.eventmask
180Sets the ACPI events which are reported to
181.Xr devd 8
182(not yet available in
183.Dx ) .
184Fn+F3, Fn+F4 and Fn+F12 always generate ACPI events, regardless which value
185.Va eventmask
186has.
187Depending on the ThinkPad model, the meaning of different bits in the
188.Va eventmask
189may vary.
190On a ThinkPad T41p this is a bitwise OR of the following:
191.Pp
192.Bl -tag -width indent-two -compact
193.It Li 1
194Fn + F1
195.It Li 2
196Fn + F2
197.It Li 4
198Fn + F3 (LCD backlight)
199.It Li 8
200Fn + F4 (Suspend to RAM)
201.It Li 16
202Fn + F5 (Bluetooth)
203.It Li 32
204Fn + F6
205.It Li 64
206Fn + F7 (Screen expand)
207.It Li 128
208Fn + F8
209.It Li 256
210Fn + F9
211.It Li 512
212Fn + F10
213.It Li 1024
214Fn + F11
215.It Li 2048
216Fn + F12 (Suspend to disk)
217.It Li 4096
218Fn + Backspace
219.It Li 8192
220Fn + Insert
221.It Li 16384
222Fn + Delete
223.It Li 32768
224Fn + Home (Brightness up)
225.It Li 65536
226Fn + End (Brightness down)
227.It Li 131072
228Fn + PageUp (ThinkLight)
229.It Li 262144
230Fn + PageDown
231.It Li 524288
232Fn + Space (Zoom)
233.It Li 1048576
234Volume Up
235.It Li 2097152
236Volume Down
237.It Li 4194304
238Mute
239.It Li 8388608
240Access IBM Button
241.El
242.It Va dev.acpi_thinkpad.0.hotkey
243(read-only)
244Status of several buttons.
245Every time a button is pressed, the respecting bit is toggled.
246It is a bitwise OR of the following:
247.Pp
248.Bl -tag -width indent-two -compact
249.It Li 1
250Home Button
251.It Li 2
252Search Button
253.It Li 4
254Mail Button
255.It Li 8
256Access IBM Button
257.It Li 16
258Zoom
259.It Li 32
260Wireless LAN Button
261.It Li 64
262Video Button
263.It Li 128
264Hibernate Button
265.It Li 256
266ThinkLight Button
267.It Li 512
268Screen Expand
269.It Li 1024
270Brightness Up/Down Button
271.It Li 2048
272Volume Up/Down/Mute Button
273.El
274.It Va dev.acpi_thinkpad.0.lcd_brightness
275Current brightness level of the display.
276.It Va dev.acpi_thinkpad.0.volume
277Speaker volume.
278.It Va dev.acpi_thinkpad.0.mute
279Indicates, whether the speakers are muted or not.
280.It Va dev.acpi_thinkpad.0.thinklight
281Indicates, whether the ThinkLight keyboard light is activated or not.
282.It Va dev.acpi_thinkpad.0.bluetooth
283Toggle Bluetooth chip activity.
284.It Va dev.acpi_thinkpad.0.wlan
285(read-only)
286Indicates whether the WLAN chip is active or not.
287.It Va dev.acpi_thinkpad.0.fan
288Indicates whether the fan is in automatic (1) or manual (0) mode.
289Default is automatic mode.
290This sysctl should be used with extreme precaution, since disabling automatic
291fan control might overheat the ThinkPad and lead to permanent damage if the
292.Va fan_level
293is not set accordingly.
294.It Va dev.acpi_thinkpad.0.fan_level
295Indicates at what speed the fan should run when being in manual mode.
296Values are ranging from 0 (off) to 7 (max).
297The resulting speed differs from model to model.
298On a T41p this is as follows:
299.Pp
300.Bl -tag -width indent-two -compact
301.It Li 0
302off
303.It Li 1, 2
304~3000 RPM
305.It Li 3, 4, 5
306~3600 RPM
307.It Li 6, 7
308~4300 RPM
309.El
310.It Va hw.sensors.acpi_thinkpad0.tempX
311Show the readings of up to eight different temperature sensors.
312Most ThinkPads include six or more temperature sensors but
313only expose the CPU temperature through
314.Xr acpi_thermal 4 .
315Some ThinkPads have the below sensor layout which might vary depending on the
316specific model:
317.Pp
318.Bl -enum -compact
319.It
320CPU
321.It
322Mini PCI Module
323.It
324HDD
325.It
326GPU
327.It
328Built-in battery
329.It
330UltraBay battery
331.It
332Built-in battery
333.It
334UltraBay battery
335.El
336.It Va hw.sensors.acpi_thinkpad0.fan0
337Fan speed in rounds per minute.
338.\" A few older ThinkPads report the fan speed in levels ranging from 0 (off)
339.\" to 7 (max).
340.El
341.Pp
342Defaults for these sysctls can be set in
343.Xr sysctl.conf 5 .
344Sensors can be monitored by
345.Xr sensorsd 8 .
346.\" .Sh FILES
347.\" .Bl -tag -width ".Pa /dev/led/thinklight"
348.\" .It Pa /dev/led/thinklight
349.\" ThinkLight
350.\" .Xr led 4
351.\" device node
352.\" .El
353.Sh EXAMPLES
354The following can be added to
355.Xr devd.conf 5
356in order to pass button events to a
357.Pa /usr/local/sbin/acpi_oem_exec.sh
358script:
359.Bd -literal -offset indent
360notify 10 {
361        match "system"          "ACPI";
362        match "subsystem"       "IBM";
363        action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
364};
365.Ed
366.Pp
367A possible
368.Pa /usr/local/sbin/acpi_oem_exec.sh
369script might look like:
370.Bd -literal -offset indent
371#!/bin/sh
372#
373if [ "$1" = "" -o "$2" = "" ]
374then
375        echo "usage: $0 notify oem_name"
376        exit 1
377fi
378NOTIFY=`echo $1`
379LOGGER="logger"
380CALC="bc"
381BC_PRECOMMANDS="scale=2"
382ECHO="echo"
383CUT="cut"
384MAX_LCD_BRIGHTNESS=7
385MAX_VOLUME=14
386OEM=$2
387DISPLAY_PIPE=/tmp/acpi_${OEM}_display
388
389case ${NOTIFY} in
390        0x05)
391                LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
392                if [ "$LEVEL" = "1" ]
393                then
394                        sysctl dev.acpi_${OEM}.0.bluetooth=0
395                        MESSAGE="bluetooth disabled"
396                else
397                        sysctl dev.acpi_${OEM}.0.bluetooth=1
398                        MESSAGE="bluetooth enabled"
399                fi
400                ;;
401        0x10|0x11)
402                LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
403                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
404                         ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
405                         ${CALC} | ${CUT} -d . -f 1`
406                MESSAGE="brightness level ${PERCENT}%"
407                ;;
408        0x12)
409                LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
410                if [ "$LEVEL" = "1" ]
411                then
412                        MESSAGE="thinklight enabled"
413                else
414                        MESSAGE="thinklight disabled"
415                fi
416                ;;
417        0x15|0x16)
418                LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
419                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
420                        ${LEVEL} / ${MAX_VOLUME} * 100" | \\
421                         ${CALC} | ${CUT} -d . -f 1`
422                MESSAGE="volume level ${PERCENT}%"
423                ;;
424        0x17)
425                LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
426                if [ "$LEVEL" = "1" ]
427                then
428                        MESSAGE="volume muted"
429                else
430                        MESSAGE="volume unmuted"
431                fi
432                ;;
433        *)
434                ;;
435esac
436${LOGGER} ${MESSAGE}
437if [ -p ${DISPLAY_PIPE} ]
438then
439        ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
440fi
441exit 0
442.Ed
443.Sh SEE ALSO
444.Xr acpi 4 ,
445.\" .Xr led 4 ,
446.Xr sysctl.conf 5 ,
447.Xr devd 8 ,
448.Xr sensorsd 8 ,
449.Xr sysctl 8
450.Sh HISTORY
451The
452.Nm
453device driver first appeared in
454.Fx 6.0
455and was imported into
456.Dx 2.1 .
457.Sh AUTHORS
458.An -nosplit
459The
460.Nm
461driver was written by
462.An Takanori Watanabe Aq takawata@FreeBSD.org
463and later mostly rewritten by
464.An Markus Brueffer Aq markus@FreeBSD.org .
465This manual page was written by
466.An Christian Brueffer Aq brueffer@FreeBSD.org
467and
468.An Markus Brueffer Aq markus@FreeBSD.org .
469