xref: /freebsd/share/man/man4/acpi_ibm.4 (revision b2d48be1bc7df45ddd13b143a160d0acb5a383c5) 
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 "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 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.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.It Va dev.acpi_ibm.0.handlerevents
339.Xr devd 8
340events handled by
341.Nm
342when
343.Va events
344is set to 1.
345Events are specified as a whitespace-separated list of event code in
346hexadecimal or decimal form.
347Note that the event maybe handled twice (e.g., Brightness up/down) if ACPI BIOS
348already handled the event.
349.El
350.Pp
351Defaults for these sysctls can be set in
352.Xr sysctl.conf 5 .
353.Sh FILES
354.Bl -tag -width ".Pa /dev/led/thinklight"
355.It Pa /dev/led/thinklight
356ThinkLight
357.Xr led 4
358device node
359.El
360.Sh EXAMPLES
361The following can be added to
362.Xr devd.conf 5
363in order to pass button events to a
364.Pa /usr/local/sbin/acpi_oem_exec.sh
365script:
366.Bd -literal -offset indent
367notify 10 {
368        match "system"          "ACPI";
369        match "subsystem"       "IBM";
370        action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
371};
372.Ed
373.Pp
374A possible
375.Pa /usr/local/sbin/acpi_oem_exec.sh
376script might look like:
377.Bd -literal -offset indent
378#!/bin/sh
379#
380if [ "$1" = "" -o "$2" = "" ]
381then
382        echo "usage: $0 notify oem_name"
383        exit 1
384fi
385NOTIFY=`echo $1`
386LOGGER="logger"
387CALC="bc"
388BC_PRECOMMANDS="scale=2"
389ECHO="echo"
390CUT="cut"
391MAX_LCD_BRIGHTNESS=7
392MAX_VOLUME=14
393OEM=$2
394DISPLAY_PIPE=/tmp/acpi_${OEM}_display
395
396case ${NOTIFY} in
397        0x05)
398                LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
399                if [ "$LEVEL" = "1" ]
400                then
401                        sysctl dev.acpi_${OEM}.0.bluetooth=0
402                        MESSAGE="bluetooth disabled"
403                else
404                        sysctl dev.acpi_${OEM}.0.bluetooth=1
405                        MESSAGE="bluetooth enabled"
406                fi
407                ;;
408        0x10|0x11)
409                LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
410                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
411                         ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
412                         ${CALC} | ${CUT} -d . -f 1`
413                MESSAGE="brightness level ${PERCENT}%"
414                ;;
415        0x12)
416                LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
417                if [ "$LEVEL" = "1" ]
418                then
419                        MESSAGE="thinklight enabled"
420                else
421                        MESSAGE="thinklight disabled"
422                fi
423                ;;
424        0x15|0x16)
425                LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
426                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
427                        ${LEVEL} / ${MAX_VOLUME} * 100" | \\
428                         ${CALC} | ${CUT} -d . -f 1`
429                MESSAGE="volume level ${PERCENT}%"
430                ;;
431        0x17)
432                LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
433                if [ "$LEVEL" = "1" ]
434                then
435                        MESSAGE="volume muted"
436                else
437                        MESSAGE="volume unmuted"
438                fi
439                ;;
440        *)
441                ;;
442esac
443${LOGGER} ${MESSAGE}
444if [ -p ${DISPLAY_PIPE} ]
445then
446        ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
447fi
448exit 0
449.Ed
450.Pp
451The following example specify that event code 0x04 (Suspend to RAM),
4520x10 (Brightness up) and 0x11 (Brightness down) are handled by
453.Nm .
454.Bd -literal -offset indent
455sysctl dev.acpi_ibm.0.handlerevents='0x04 0x10 0x11'
456.Ed
457.Pp
458in
459.Xr sysctl.conf 5 :
460.Bd -literal -offset indent
461dev.acpi_ibm.0.handlerevents=0x04\\ 0x10\\ 0x11
462.Ed
463.Sh SEE ALSO
464.Xr acpi 4 ,
465.Xr led 4 ,
466.Xr sysctl.conf 5 ,
467.Xr devd 8 ,
468.Xr sysctl 8
469.Sh HISTORY
470The
471.Nm
472device driver first appeared in
473.Fx 6.0 .
474.Sh AUTHORS
475.An -nosplit
476The
477.Nm
478driver was written by
479.An Takanori Watanabe Aq Mt takawata@FreeBSD.org
480and later mostly rewritten by
481.An Markus Brueffer Aq Mt markus@FreeBSD.org .
482This manual page was written by
483.An Christian Brueffer Aq Mt brueffer@FreeBSD.org
484and
485.An Markus Brueffer Aq Mt markus@FreeBSD.org .
486