xref: /freebsd/share/man/man4/acpi_ibm.4 (revision 2f513db7) 
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 June 19, 2015
29.Dt ACPI_IBM 4
30.Os
31.Sh NAME
32.Nm acpi_ibm
33.Nd "ThinkPad ACPI extras driver"
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 ThinkPad 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 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 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.mic_mute
277Indicates, whether the microphone led (present on some model) is on or not.
278Note that this does not mean that the microphone input is muted.
279.It Va dev.acpi_ibm.0.thinklight
280Indicates, whether the ThinkLight keyboard light is activated or not.
281.It Va dev.acpi_ibm.0.bluetooth
282Toggle Bluetooth chip activity.
283.It Va dev.acpi_ibm.0.wlan
284(read-only)
285Indicates whether the WLAN chip is active or not.
286.It Va dev.acpi_ibm.0.fan
287Indicates whether the fan is in automatic (1) or manual (0) mode.
288Default is automatic mode.
289This sysctl should be used with extreme precaution, since disabling automatic
290fan control might overheat the ThinkPad and lead to permanent damage if the
291.Va fan_level
292is not set accordingly.
293.It Va dev.acpi_ibm.0.fan_level
294Indicates at what speed the fan should run when being in manual mode.
295Values are ranging from 0 (off) to 7 (max).
296The resulting speed differs from model to model.
297On a T41p this is as follows:
298.Pp
299.Bl -tag -width indent-two -compact
300.It Li 0
301off
302.It Li 1, 2
303~3000 RPM
304.It Li 3, 4, 5
305~3600 RPM
306.It Li 6, 7
307~4300 RPM
308.El
309.It Va dev.acpi_ibm.0.fan_speed
310(read-only)
311Fan speed in rounds per minute.
312A few older ThinkPads report the fan speed in levels ranging from 0 (off)
313to 7 (max).
314.It Va dev.acpi_ibm.0.thermal
315(read-only)
316Shows the readings of up to eight different temperature sensors.
317Most ThinkPads include six or more temperature sensors but
318only expose the CPU temperature through
319.Xr acpi_thermal 4 .
320Some ThinkPads have the below sensor layout which might vary depending on the
321specific model:
322.Pp
323.Bl -enum -compact
324.It
325CPU
326.It
327Mini PCI Module
328.It
329HDD
330.It
331GPU
332.It
333Built-in battery
334.It
335UltraBay battery
336.It
337Built-in battery
338.It
339UltraBay battery
340.El
341.It Va dev.acpi_ibm.0.handlerevents
342.Xr devd 8
343events handled by
344.Nm
345when
346.Va events
347is set to 1.
348Events are specified as a whitespace-separated list of event code in
349hexadecimal or decimal form.
350Note that the event maybe handled twice (e.g., Brightness up/down) if ACPI BIOS
351already handled the event.
352.El
353.Pp
354Defaults for these sysctls can be set in
355.Xr sysctl.conf 5 .
356.Sh FILES
357.Bl -tag -width ".Pa /dev/led/thinklight"
358.It Pa /dev/led/thinklight
359ThinkLight
360.Xr led 4
361device node
362.El
363.Sh EXAMPLES
364The following can be added to
365.Xr devd.conf 5
366in order to pass button events to a
367.Pa /usr/local/sbin/acpi_oem_exec.sh
368script:
369.Bd -literal -offset indent
370notify 10 {
371        match "system"          "ACPI";
372        match "subsystem"       "IBM";
373        action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
374};
375.Ed
376.Pp
377A possible
378.Pa /usr/local/sbin/acpi_oem_exec.sh
379script might look like:
380.Bd -literal -offset indent
381#!/bin/sh
382#
383if [ "$1" = "" -o "$2" = "" ]
384then
385        echo "usage: $0 notify oem_name"
386        exit 1
387fi
388NOTIFY=`echo $1`
389LOGGER="logger"
390CALC="bc"
391BC_PRECOMMANDS="scale=2"
392ECHO="echo"
393CUT="cut"
394MAX_LCD_BRIGHTNESS=7
395MAX_VOLUME=14
396OEM=$2
397DISPLAY_PIPE=/tmp/acpi_${OEM}_display
398
399case ${NOTIFY} in
400        0x05)
401                LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
402                if [ "$LEVEL" = "1" ]
403                then
404                        sysctl dev.acpi_${OEM}.0.bluetooth=0
405                        MESSAGE="bluetooth disabled"
406                else
407                        sysctl dev.acpi_${OEM}.0.bluetooth=1
408                        MESSAGE="bluetooth enabled"
409                fi
410                ;;
411        0x10|0x11)
412                LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
413                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
414                         ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
415                         ${CALC} | ${CUT} -d . -f 1`
416                MESSAGE="brightness level ${PERCENT}%"
417                ;;
418        0x12)
419                LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
420                if [ "$LEVEL" = "1" ]
421                then
422                        MESSAGE="thinklight enabled"
423                else
424                        MESSAGE="thinklight disabled"
425                fi
426                ;;
427        0x15|0x16)
428                LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
429                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
430                        ${LEVEL} / ${MAX_VOLUME} * 100" | \\
431                         ${CALC} | ${CUT} -d . -f 1`
432                MESSAGE="volume level ${PERCENT}%"
433                ;;
434        0x17)
435                LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
436                if [ "$LEVEL" = "1" ]
437                then
438                        MESSAGE="volume muted"
439                else
440                        MESSAGE="volume unmuted"
441                fi
442                ;;
443	0x1b)
444		LEVEL=`sysctl -n dev.acpi_ibm.0.mic_led`
445		if [ $LEVEL -eq 0 ]; then
446			sysctl dev.acpi_ibm.0.mic_led=1
447			mixer rec 0
448		fi
449		if [ $LEVEL -eq 1 ]; then
450			sysctl dev.acpi_ibm.0.mic_led=0
451			mixer rec 30
452		fi
453		;;
454        *)
455                ;;
456esac
457${LOGGER} ${MESSAGE}
458if [ -p ${DISPLAY_PIPE} ]
459then
460        ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
461fi
462exit 0
463.Ed
464.Pp
465The following example specify that event code 0x04 (Suspend to RAM),
4660x10 (Brightness up) and 0x11 (Brightness down) are handled by
467.Nm .
468.Bd -literal -offset indent
469sysctl dev.acpi_ibm.0.handlerevents='0x04 0x10 0x11'
470.Ed
471.Pp
472in
473.Xr sysctl.conf 5 :
474.Bd -literal -offset indent
475dev.acpi_ibm.0.handlerevents=0x04\\ 0x10\\ 0x11
476.Ed
477.Sh SEE ALSO
478.Xr acpi 4 ,
479.Xr led 4 ,
480.Xr sysctl.conf 5 ,
481.Xr devd 8 ,
482.Xr sysctl 8
483.Sh HISTORY
484The
485.Nm
486device driver first appeared in
487.Fx 6.0 .
488.Sh AUTHORS
489.An -nosplit
490The
491.Nm
492driver was written by
493.An Takanori Watanabe Aq Mt takawata@FreeBSD.org
494and later mostly rewritten by
495.An Markus Brueffer Aq Mt markus@FreeBSD.org .
496This manual page was written by
497.An Christian Brueffer Aq Mt brueffer@FreeBSD.org
498and
499.An Markus Brueffer Aq Mt markus@FreeBSD.org .
500