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